P-034 Gateway Python SDK

p034-gateway-sdk is a small sync/async HTTP client for the native AI Gateway runtime. The gateway key selects the application, and the server continues to own model-pool routing, provider credentials, execution, persistence, and billing.

The package is prepared as version 0.1.0. It is not published to PyPI yet. Install it from a checkout:

python -m pip install ./sdk/python

Set the API root and application key issued once by the dashboard's application API-key page:

export GATEWAY_API_KEY='ak_...'
export GATEWAY_BASE_URL='https://gateway.example.com/api/v1'

base_url is the API root. Keep /api/v1 in the value when the deployment uses that prefix. Explicit constructor arguments override those two environment variables. The SDK does not load .env files and has no implicit production URL.

Synchronous request

from p034_gateway import GatewayClient, RequestConstraints

with GatewayClient() as client:
    result = client.requests.create(
        prompt="Summarize this document and suggest three next steps.",
        context={"document": "Text to summarize"},
        constraints=RequestConstraints(
            quality_priority="cost_first",
            max_output_tokens=400,
        ),
        idempotency_key="ticket-123-summary-v1",
    )
    print(result.output)
    print(result.request_id, result.cost.estimated_cost if result.cost else None)

    receipt = client.requests.get(result.request_id)
    print(receipt.status)

See examples/sync_request.py for a complete example.

Asynchronous request

from p034_gateway import AsyncGatewayClient

async with AsyncGatewayClient() as client:
    result = await client.requests.create(prompt="Summarize this document.")
    receipt = await client.requests.get(result.request_id)

See examples/async_request.py. The async client uses HTTPX's async transport and does not start or manage an event loop for you.

Retries and recovery

Retries are off by default. Set max_retries to an integer from 0 to 3 to retry network errors, retryable admission responses, and requests that are still running. A create call generates one idempotency key when omitted and reuses the same key and request body for every attempt. Keep a caller-supplied key if you need to recover across separate method calls.

RequestInProgressError includes the request ID and idempotency key. Poll with client.requests.get(request_id) or retry create with the same key and body. RequestOutcomeUnknownError means the gateway cannot confirm the provider outcome; the SDK will not retry it. Do not submit a new key unless you intend to start another execution that could incur additional cost.

API errors are typed (AuthenticationError, ValidationError, RateLimitError, ProviderExecutionError, ServiceUnavailableError, and others). A GET of a failed request returns a RuntimeRequest whose status is failed; it does not raise a provider exception. A failed create call raises the mapped API exception.

Runtime limits

• The public runtime accepts prompt text, a JSON context, optional constraints, and optional metadata. It does not accept chat messages, streaming, tools, images, audio, or files.
• max_output_tokens caps each routed model generation, including retries and fallback attempts. It does not cap the combined output or structured pipeline stages.
• cost.estimated_cost is an estimate. Application budget ceilings are advisory in this API version and do not reserve or hard-block spend.
• Partial output is returned only when allow_partial_response=True and useful task output remains.
• The server deadline defaults to 120 seconds. The SDK's default HTTPX timeout uses 5 seconds connect/pool, 10 seconds write, and 130 seconds read. This is HTTPX phase timeout behavior, not a total wall-clock deadline.

Injected httpx.Client and httpx.AsyncClient instances remain owned by the caller. The SDK closes only clients it creates. Redirect following is disabled per request so the gateway key is not forwarded to a redirect target.

Development

cd sdk/python
python -m pip install -e '.[dev]'
pytest
ruff check src/ tests/
python -m build
python -m twine check dist/*

The SDK runtime depends only on HTTPX and Pydantic. Package publication and PyPI name ownership checks are separate release steps.