Metadata-Version: 2.5
Name: p034-gateway-sdk
Version: 0.1.1
Summary: Python SDK for the P-034 AI Gateway runtime API
Project-URL: Repository, https://github.com/AI20K-Build-Phase-Cohort-4/P-034
Project-URL: Documentation, https://github.com/AI20K-Build-Phase-Cohort-4/P-034/tree/main/sdk/python
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic<3,>=2.10
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Description-Content-Type: text/markdown

# P-034 Gateway Python SDK

`p034-gateway-sdk` is a synchronous and asynchronous Python client for the
native P-034 AI Gateway runtime. A gateway API key identifies the application;
the Gateway backend handles model-pool routing, provider credentials,
execution, persistence, and billing. Provider API keys are configured on the
backend and are not passed to this SDK.

Tài liệu tiếng Việt: [README.vi.md](README.vi.md).

## Installation

Requires Python 3.11 or newer. Install the latest release from PyPI:

```bash
python -m pip install p034-gateway-sdk
```

To pin this release explicitly:

```bash
python -m pip install "p034-gateway-sdk==0.1.1"
```

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

```bash
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

```python
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`](examples/sync_request.py) for a complete
example.

## Asynchronous request

```python
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`](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

```bash
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.
