p034-gateway-sdk 0.1.1__tar.gz

p034_gateway_sdk-0.1.1/.gitignore

@@ -0,0 +1,69 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# Environment variables
+.env
+.env.local
+.env.production
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Data (never commit large data)
+data/
+data/*.sqlite3-*
+*.db
+*.sqlite3
+
+# Logs
+logs/
+*.log
+
+# Test coverage
+htmlcov/
+.coverage
+coverage.xml
+
+# Docker
+docker-compose.override.yml
+
+# Node (frontend)
+node_modules/
+.next/
+out/
+.nuxt/
+
+# Build
+*.pyc
+*.pyo
+
+# AI logs — tracked structure, ignored content
+.ai-log/*.jsonl
+.ai-log/archive/
+
+
+P-034-streamlit demo full
+.env copy.example
+
+tmp
+
+P-034-dev

p034_gateway_sdk-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI20K Build Phase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

p034_gateway_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,156 @@
+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.

p034_gateway_sdk-0.1.1/README.md

@@ -0,0 +1,127 @@
+# 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.

p034_gateway_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "p034-gateway-sdk"
+version = "0.1.1"
+description = "Python SDK for the P-034 AI Gateway runtime API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["httpx>=0.28,<1", "pydantic>=2.10,<3"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/AI20K-Build-Phase-Cohort-4/P-034"
+Documentation = "https://github.com/AI20K-Build-Phase-Cohort-4/P-034/tree/main/sdk/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/p034_gateway"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src/p034_gateway", "/README.md", "/LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.9", "twine>=6"]

p034_gateway_sdk-0.1.1/src/p034_gateway/__init__.py

@@ -0,0 +1,66 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from p034_gateway.client import AsyncGatewayClient, GatewayClient
+from p034_gateway.exceptions import (
+    APIConnectionError,
+    APIError,
+    APIResponseValidationError,
+    APITimeoutError,
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    GatewayError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProviderExecutionError,
+    RateLimitError,
+    RequestInProgressError,
+    RequestOutcomeUnknownError,
+    RequestTooLargeError,
+    ServiceUnavailableError,
+    ValidationError,
+)
+from p034_gateway.models import (
+    RequestConstraints,
+    RuntimeCost,
+    RuntimeOperationError,
+    RuntimeRequest,
+    RuntimeUsage,
+    RuntimeUsageScope,
+    RuntimeWarning,
+)
+
+try:
+    __version__ = version("p034-gateway-sdk")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APIResponseValidationError",
+    "APITimeoutError",
+    "AsyncGatewayClient",
+    "AuthenticationError",
+    "ConfigurationError",
+    "ConflictError",
+    "GatewayClient",
+    "GatewayError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "ProviderExecutionError",
+    "RateLimitError",
+    "RequestConstraints",
+    "RequestInProgressError",
+    "RequestOutcomeUnknownError",
+    "RequestTooLargeError",
+    "RuntimeCost",
+    "RuntimeOperationError",
+    "RuntimeRequest",
+    "RuntimeUsage",
+    "RuntimeUsageScope",
+    "RuntimeWarning",
+    "ServiceUnavailableError",
+    "ValidationError",
+    "__version__",
+]

p034_gateway_sdk-0.1.1/src/p034_gateway/_transport.py

@@ -0,0 +1,383 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+from pydantic import ValidationError as PydanticValidationError
+
+from p034_gateway.exceptions import (
+    APIConnectionError,
+    APIError,
+    APIResponseValidationError,
+    APITimeoutError,
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    GatewayError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProviderExecutionError,
+    RateLimitError,
+    RequestInProgressError,
+    RequestOutcomeUnknownError,
+    RequestTooLargeError,
+    ServiceUnavailableError,
+    ValidationError,
+)
+from p034_gateway.models import RuntimeRequest
+
+_RETRYABLE_STATUSES = {429, 503}
+
+
+class BaseTransport:
+    def __init__(self, *, api_key: str, base_url: str, timeout: float | httpx.Timeout, max_retries: int):
+        self.api_key = api_key
+        self.base_url = _normalize_base_url(base_url)
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": _user_agent(),
+        }
+
+    def _url(self, request_id: str | None = None) -> str:
+        path = "runtime/requests" if request_id is None else f"runtime/requests/{quote(request_id, safe='')}"
+        return f"{self.base_url}/{path}"
+
+    def _decode_response(
+        self,
+        response: httpx.Response,
+        *,
+        idempotency_key: str | None = None,
+    ) -> RuntimeRequest:
+        _require_api_version(response)
+        try:
+            payload = response.json()
+        except (json.JSONDecodeError, ValueError):
+            raise APIResponseValidationError(
+                "Gateway returned an unreadable success response.",
+                status_code=response.status_code,
+                request_id=response.headers.get("X-Request-ID"),
+                idempotency_key=idempotency_key,
+            ) from None
+        try:
+            parsed = RuntimeRequest.model_validate(payload)
+        except (PydanticValidationError, TypeError, ValueError):
+            raise APIResponseValidationError(
+                "Gateway success response did not match API v1.",
+                status_code=response.status_code,
+                request_id=response.headers.get("X-Request-ID"),
+                idempotency_key=idempotency_key,
+            ) from None
+        replayed = response.headers.get("Idempotency-Replayed", "false").lower() == "true"
+        return parsed.model_copy(update={"idempotency_key": idempotency_key, "replayed": replayed})
+
+    def _api_error(self, response: httpx.Response, *, idempotency_key: str | None = None) -> GatewayError:
+        envelope: dict[str, Any] = {}
+        try:
+            data = response.json()
+            if isinstance(data, dict):
+                envelope = data
+        except (json.JSONDecodeError, ValueError):
+            pass
+        error = envelope.get("error") if isinstance(envelope.get("error"), dict) else {}
+        code = error.get("code") if isinstance(error.get("code"), str) else None
+        message = error.get("message") if isinstance(error.get("message"), str) else "Gateway request failed."
+        raw_details = error.get("details") if isinstance(error.get("details"), dict) else {}
+        details = _redact(raw_details, self.api_key)
+        request_id = envelope.get("request_id") or response.headers.get("X-Request-ID")
+        retryable = error.get("retryable") is True
+        exception_type: type[GatewayError]
+        if response.status_code == 401:
+            exception_type = AuthenticationError
+        elif response.status_code == 403:
+            exception_type = PermissionDeniedError
+        elif response.status_code == 404:
+            exception_type = NotFoundError
+        elif response.status_code == 409 and code == "REQUEST_IN_PROGRESS":
+            exception_type = RequestInProgressError
+        elif response.status_code == 409 and code == "REQUEST_OUTCOME_UNKNOWN":
+            exception_type = RequestOutcomeUnknownError
+        elif response.status_code == 409:
+            exception_type = ConflictError
+        elif response.status_code == 413:
+            exception_type = RequestTooLargeError
+        elif response.status_code in {400, 422}:
+            exception_type = ValidationError
+        elif response.status_code == 429:
+            exception_type = RateLimitError
+        elif response.status_code == 502:
+            exception_type = ProviderExecutionError
+        elif response.status_code == 503:
+            exception_type = ServiceUnavailableError
+        else:
+            exception_type = APIError
+        return exception_type(
+            _redact(message[:500], self.api_key),
+            code=code,
+            status_code=response.status_code,
+            request_id=request_id,
+            idempotency_key=idempotency_key,
+            retryable=retryable,
+            details=details,
+        )
+
+    def _post_retryable(self, response: httpx.Response) -> bool:
+        if response.status_code == 429:
+            return True
+        if response.status_code == 409:
+            error = _read_error(response)
+            return error.get("code") == "REQUEST_IN_PROGRESS"
+        if response.status_code == 503:
+            try:
+                data = response.json()
+            except (json.JSONDecodeError, ValueError):
+                return True
+            error = data.get("error") if isinstance(data, dict) else None
+            return isinstance(error, dict) and error.get("retryable") is True
+        return False
+
+    @staticmethod
+    def _delay(response: httpx.Response | None, retry_index: int) -> float:
+        retry_after = response.headers.get("Retry-After") if response is not None else None
+        if retry_after:
+            delay = _parse_retry_after(retry_after)
+            if delay is not None:
+                return min(10.0, max(0.0, delay))
+        return min(10.0, 0.5 * (2**retry_index))
+
+
+class SyncTransport(BaseTransport):
+    def __init__(self, *, http_client: httpx.Client | None = None, **kwargs):
+        super().__init__(**kwargs)
+        self._owns_client = http_client is None
+        self.client = http_client or httpx.Client(timeout=self.timeout, follow_redirects=False, verify=True)
+
+    def create(self, body: bytes, idempotency_key: str, timeout: float | httpx.Timeout | None) -> RuntimeRequest:
+        last_error: GatewayError | None = None
+        for retry_index in range(self.max_retries + 1):
+            try:
+                response = self.client.post(
+                    self._url(),
+                    content=body,
+                    headers={**self.headers, "Idempotency-Key": idempotency_key},
+                    timeout=timeout if timeout is not None else self.timeout,
+                    follow_redirects=False,
+                )
+            except httpx.TimeoutException as exc:
+                last_error = APITimeoutError(
+                    "Gateway request timed out.", idempotency_key=idempotency_key, retryable=True
+                )
+                if retry_index >= self.max_retries:
+                    raise last_error from exc
+                time.sleep(self._delay(None, retry_index))
+                continue
+            except httpx.RequestError as exc:
+                last_error = APIConnectionError(
+                    "Could not connect to the gateway.", idempotency_key=idempotency_key, retryable=True
+                )
+                if retry_index >= self.max_retries:
+                    raise last_error from exc
+                time.sleep(self._delay(None, retry_index))
+                continue
+            if 200 <= response.status_code < 300:
+                return self._decode_response(response, idempotency_key=idempotency_key)
+            last_error = self._api_error(response, idempotency_key=idempotency_key)
+            if retry_index >= self.max_retries or not self._post_retryable(response):
+                raise last_error
+            time.sleep(self._delay(response, retry_index))
+        assert last_error is not None
+        raise last_error
+
+    def get(self, request_id: str, timeout: float | httpx.Timeout | None) -> RuntimeRequest:
+        last_error: GatewayError | None = None
+        for retry_index in range(self.max_retries + 1):
+            try:
+                response = self.client.get(
+                    self._url(request_id),
+                    headers=self.headers,
+                    timeout=timeout if timeout is not None else self.timeout,
+                    follow_redirects=False,
+                )
+            except httpx.TimeoutException as exc:
+                last_error = APITimeoutError("Gateway request timed out.", retryable=True)
+                if retry_index >= self.max_retries:
+                    raise last_error from exc
+                time.sleep(self._delay(None, retry_index))
+                continue
+            except httpx.RequestError as exc:
+                last_error = APIConnectionError("Could not connect to the gateway.", retryable=True)
+                if retry_index >= self.max_retries:
+                    raise last_error from exc
+                time.sleep(self._delay(None, retry_index))
+                continue
+            if 200 <= response.status_code < 300:
+                return self._decode_response(response)
+            last_error = self._api_error(response)
+            if retry_index >= self.max_retries or response.status_code not in _RETRYABLE_STATUSES:
+                raise last_error
+            time.sleep(self._delay(response, retry_index))
+        assert last_error is not None
+        raise last_error
+
+    def close(self) -> None:
+        if self._owns_client:
+            self.client.close()
+
+
+class AsyncTransport(BaseTransport):
+    def __init__(self, *, http_client: httpx.AsyncClient | None = None, **kwargs):
+        super().__init__(**kwargs)
+        self._owns_client = http_client is None
+        self.client = http_client or httpx.AsyncClient(timeout=self.timeout, follow_redirects=False, verify=True)
+
+    async def create(self, body: bytes, idempotency_key: str, timeout: float | httpx.Timeout | None) -> RuntimeRequest:
+        last_error: GatewayError | None = None
+        for retry_index in range(self.max_retries + 1):
+            try:
+                response = await self.client.post(
+                    self._url(),
+                    content=body,
+                    headers={**self.headers, "Idempotency-Key": idempotency_key},
+                    timeout=timeout if timeout is not None else self.timeout,
+                    follow_redirects=False,
+                )
+            except httpx.TimeoutException as exc:
+                last_error = APITimeoutError(
+                    "Gateway request timed out.", idempotency_key=idempotency_key, retryable=True
+                )
+                if retry_index >= self.max_retries:
+                    raise last_error from exc
+                await asyncio.sleep(self._delay(None, retry_index))
+                continue
+            except httpx.RequestError as exc:
+                last_error = APIConnectionError(
+                    "Could not connect to the gateway.", idempotency_key=idempotency_key, retryable=True
+                )
+                if retry_index >= self.max_retries:
+                    raise last_error from exc
+                await asyncio.sleep(self._delay(None, retry_index))
+                continue
+            if 200 <= response.status_code < 300:
+                return self._decode_response(response, idempotency_key=idempotency_key)
+            last_error = self._api_error(response, idempotency_key=idempotency_key)
+            if retry_index >= self.max_retries or not self._post_retryable(response):
+                raise last_error
+            await asyncio.sleep(self._delay(response, retry_index))
+        assert last_error is not None
+        raise last_error
+
+    async def get(self, request_id: str, timeout: float | httpx.Timeout | None) -> RuntimeRequest:
+        last_error: GatewayError | None = None
+        for retry_index in range(self.max_retries + 1):
+            try:
+                response = await self.client.get(
+                    self._url(request_id),
+                    headers=self.headers,
+                    timeout=timeout if timeout is not None else self.timeout,
+                    follow_redirects=False,
+                )
+            except httpx.TimeoutException as exc:
+                last_error = APITimeoutError("Gateway request timed out.", retryable=True)
+                if retry_index >= self.max_retries:
+                    raise last_error from exc
+                await asyncio.sleep(self._delay(None, retry_index))
+                continue
+            except httpx.RequestError as exc:
+                last_error = APIConnectionError("Could not connect to the gateway.", retryable=True)
+                if retry_index >= self.max_retries:
+                    raise last_error from exc
+                await asyncio.sleep(self._delay(None, retry_index))
+                continue
+            if 200 <= response.status_code < 300:
+                return self._decode_response(response)
+            last_error = self._api_error(response)
+            if retry_index >= self.max_retries or response.status_code not in _RETRYABLE_STATUSES:
+                raise last_error
+            await asyncio.sleep(self._delay(response, retry_index))
+        assert last_error is not None
+        raise last_error
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self.client.aclose()
+
+
+def _normalize_base_url(base_url: str) -> str:
+    try:
+        parsed = httpx.URL(base_url.strip())
+    except (httpx.InvalidURL, TypeError, ValueError):
+        raise ConfigurationError("base_url must be a valid HTTP(S) API root") from None
+    if parsed.scheme not in {"http", "https"} or not parsed.host or parsed.username or parsed.password:
+        raise ConfigurationError("base_url must be a valid HTTP(S) API root")
+    if parsed.query or parsed.fragment:
+        raise ConfigurationError("base_url must not include a query string or fragment")
+    return str(parsed.copy_with(path=parsed.path.rstrip("/"), query=None, fragment=None)).rstrip("/")
+
+
+def _require_api_version(response: httpx.Response) -> None:
+    value = response.headers.get("X-Gateway-API-Version", "")
+    try:
+        major = int(value.split(".", 1)[0])
+    except ValueError as exc:
+        raise APIResponseValidationError(
+            "Gateway success response omitted a valid API version.",
+            status_code=response.status_code,
+            request_id=response.headers.get("X-Request-ID"),
+        ) from exc
+    if major != 1:
+        raise APIResponseValidationError(
+            "Gateway API major version is not supported.",
+            code=value or None,
+            status_code=response.status_code,
+            request_id=response.headers.get("X-Request-ID"),
+        )
+
+
+def _read_error(response: httpx.Response) -> dict[str, Any]:
+    try:
+        data = response.json()
+    except (json.JSONDecodeError, ValueError):
+        return {}
+    error = data.get("error") if isinstance(data, dict) else None
+    return error if isinstance(error, dict) else {}
+
+
+def _parse_retry_after(value: str) -> float | None:
+    try:
+        return max(0.0, float(int(value.strip())))
+    except ValueError:
+        try:
+            retry_time = parsedate_to_datetime(value)
+        except (TypeError, ValueError, OverflowError):
+            return None
+        if retry_time.tzinfo is None:
+            retry_time = retry_time.replace(tzinfo=UTC)
+        return max(0.0, (retry_time.astimezone(UTC) - datetime.now(UTC)).total_seconds())
+
+
+def _user_agent() -> str:
+    try:
+        package_version = version("p034-gateway-sdk")
+    except PackageNotFoundError:
+        package_version = "0.1.0"
+    return f"p034-gateway-sdk/{package_version}"
+
+
+def _redact(value: Any, secret: str) -> Any:
+    if isinstance(value, str):
+        return value.replace(secret, "[redacted]") if secret else value
+    if isinstance(value, list):
+        return [_redact(item, secret) for item in value]
+    if isinstance(value, dict):
+        return {_redact(key, secret): _redact(item, secret) for key, item in value.items()}
+    return value

p034_gateway_sdk-0.1.1/src/p034_gateway/client.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import os
+from typing import Self
+
+import httpx
+
+from p034_gateway._transport import AsyncTransport, SyncTransport
+from p034_gateway.exceptions import ConfigurationError
+from p034_gateway.resources.requests import AsyncRequests, Requests
+
+
+def _resolve_config(api_key: str | None, base_url: str | None) -> tuple[str, str]:
+    resolved_key = api_key if api_key is not None else os.getenv("GATEWAY_API_KEY")
+    resolved_url = base_url if base_url is not None else os.getenv("GATEWAY_BASE_URL")
+    if not isinstance(resolved_key, str) or not resolved_key.strip() or any(char.isspace() for char in resolved_key):
+        raise ConfigurationError("api_key is required; set api_key or GATEWAY_API_KEY.")
+    if not isinstance(resolved_url, str) or not resolved_url.strip():
+        raise ConfigurationError("base_url is required; set base_url or GATEWAY_BASE_URL.")
+    try:
+        parsed = httpx.URL(resolved_url.strip())
+    except (httpx.InvalidURL, TypeError, ValueError):
+        raise ConfigurationError("base_url must be a valid HTTP(S) API root.") from None
+    if (
+        parsed.scheme not in {"http", "https"}
+        or not parsed.host
+        or parsed.username
+        or parsed.password
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ConfigurationError("base_url must be a valid HTTP(S) API root.")
+    return resolved_key.strip(), resolved_url.strip()
+
+
+def _validate_retries(max_retries: int) -> None:
+    if isinstance(max_retries, bool) or not isinstance(max_retries, int) or not 0 <= max_retries <= 3:
+        raise ConfigurationError("max_retries must be an integer from 0 to 3.")
+
+
+class GatewayClient:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        max_retries: int = 0,
+        http_client: httpx.Client | None = None,
+    ):
+        self.api_key, self.base_url = _resolve_config(api_key, base_url)
+        _validate_retries(max_retries)
+        self.timeout = timeout if timeout is not None else httpx.Timeout(connect=5, pool=5, write=10, read=130)
+        self._transport = SyncTransport(
+            api_key=self.api_key,
+            base_url=self.base_url,
+            timeout=self.timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+        self.requests = Requests(self._transport)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> None:
+        self.close()
+
+
+class AsyncGatewayClient:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        max_retries: int = 0,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        self.api_key, self.base_url = _resolve_config(api_key, base_url)
+        _validate_retries(max_retries)
+        self.timeout = timeout if timeout is not None else httpx.Timeout(connect=5, pool=5, write=10, read=130)
+        self._transport = AsyncTransport(
+            api_key=self.api_key,
+            base_url=self.base_url,
+            timeout=self.timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+        self.requests = AsyncRequests(self._transport)
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, exc_type, exc, traceback) -> None:
+        await self.aclose()

p034_gateway_sdk-0.1.1/src/p034_gateway/exceptions.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class GatewayError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        idempotency_key: str | None = None,
+        retryable: bool = False,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.request_id = request_id
+        self.idempotency_key = idempotency_key
+        self.retryable = retryable
+        self.details = details or {}
+        super().__init__(message)
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(message={self.message!r}, code={self.code!r}, "
+            f"status_code={self.status_code!r}, request_id={self.request_id!r}, "
+            f"idempotency_key={self.idempotency_key!r})"
+        )
+
+
+class ConfigurationError(GatewayError):
+    pass
+
+
+class AuthenticationError(GatewayError):
+    pass
+
+
+class PermissionDeniedError(GatewayError):
+    pass
+
+
+class NotFoundError(GatewayError):
+    pass
+
+
+class ConflictError(GatewayError):
+    pass
+
+
+class RequestInProgressError(ConflictError):
+    pass
+
+
+class RequestOutcomeUnknownError(ConflictError):
+    pass
+
+
+class RequestTooLargeError(GatewayError):
+    pass
+
+
+class ValidationError(GatewayError):
+    pass
+
+
+class RateLimitError(GatewayError):
+    pass
+
+
+class ProviderExecutionError(GatewayError):
+    pass
+
+
+class ServiceUnavailableError(GatewayError):
+    pass
+
+
+class APIError(GatewayError):
+    pass
+
+
+class APIConnectionError(GatewayError):
+    pass
+
+
+class APITimeoutError(APIConnectionError):
+    pass
+
+
+class APIResponseValidationError(GatewayError):
+    pass

p034_gateway_sdk-0.1.1/src/p034_gateway/models.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictInt, StrictStr
+
+
+class RequestConstraints(BaseModel):
+    """Request-level routing and output constraints supported by API v1."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    quality_priority: Literal["cost_first", "balanced", "latency_first", "quality_first"] | None = None
+    max_output_tokens: StrictInt | None = Field(default=None, ge=1, le=32_768)
+    max_latency_ms: StrictInt | None = Field(default=None, gt=0)
+    allowed_models: list[StrictStr] | None = None
+    blocked_models: list[StrictStr] | None = None
+    allowed_providers: list[StrictStr] | None = None
+    blocked_providers: list[StrictStr] | None = None
+    external_provider_allowed: StrictBool | None = None
+    output_format: Literal["text", "markdown", "json"] | None = None
+    allow_partial_response: StrictBool | None = None
+
+    def to_api_dict(self) -> dict[str, Any]:
+        values = self.model_dump(mode="json", exclude_none=True, exclude_unset=True)
+        for name in ("allowed_models", "blocked_models", "allowed_providers", "blocked_providers"):
+            if name in values:
+                values[name] = sorted(set(values[name]))
+        return values
+
+
+class RuntimeUsageScope(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+
+
+class RuntimeUsage(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    execution: RuntimeUsageScope | None = None
+    pipeline: RuntimeUsageScope | None = None
+    complete: bool
+
+
+class RuntimeCost(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    currency: Literal["USD"] = "USD"
+    estimated_cost: float
+    estimated: bool = True
+
+
+class RuntimeWarning(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    code: str
+    message: str
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class RuntimeOperationError(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    code: str
+    message: str
+    retryable: bool = False
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class RuntimeRequest(BaseModel):
+    """Typed API receipt with SDK-only idempotency metadata."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    request_id: str
+    application_id: str
+    status: Literal["running", "completed", "partial", "failed", "indeterminate"]
+    execution_mode: Literal["offline", "live"]
+    output: str | None = None
+    models_used: list[str] = Field(default_factory=list)
+    providers_used: list[str] = Field(default_factory=list)
+    usage: RuntimeUsage | None = None
+    cost: RuntimeCost | None = None
+    latency_ms: float | None = None
+    fallback_used: bool = False
+    config_version: int
+    started_at: datetime
+    finished_at: datetime | None = None
+    warnings: list[RuntimeWarning] = Field(default_factory=list)
+    error: RuntimeOperationError | None = None
+    idempotency_key: str | None = None
+    replayed: bool = False

p034_gateway_sdk-0.1.1/src/p034_gateway/py.typed

@@ -0,0 +1 @@
+

p034_gateway_sdk-0.1.1/src/p034_gateway/resources/__init__.py

@@ -0,0 +1,3 @@
+from p034_gateway.resources.requests import AsyncRequests, Requests
+
+__all__ = ["AsyncRequests", "Requests"]

p034_gateway_sdk-0.1.1/src/p034_gateway/resources/requests.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+from uuid import uuid4
+
+import httpx
+from pydantic import BaseModel, ConfigDict, StrictStr, field_validator
+from pydantic import ValidationError as PydanticValidationError
+
+from p034_gateway._transport import AsyncTransport, SyncTransport
+from p034_gateway.exceptions import ConfigurationError, ValidationError
+from p034_gateway.models import RequestConstraints, RuntimeRequest
+
+
+class _CreateRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    prompt: StrictStr
+    context: dict[str, Any] | None = None
+    constraints: RequestConstraints | None = None
+    metadata: dict[str, Any] | None = None
+
+    @field_validator("prompt")
+    @classmethod
+    def require_prompt_text(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("prompt must contain non-whitespace characters")
+        if len(value) > 100_000:
+            raise ValueError("prompt must not exceed 100000 characters")
+        return value
+
+
+class Requests:
+    def __init__(self, transport: SyncTransport):
+        self._transport = transport
+
+    def create(
+        self,
+        *,
+        prompt: str,
+        context: dict[str, Any] | None = None,
+        constraints: RequestConstraints | dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> RuntimeRequest:
+        body, key = _serialize_create(prompt, context, constraints, metadata, idempotency_key)
+        return self._transport.create(body, key, timeout)
+
+    def get(self, request_id: str, *, timeout: float | httpx.Timeout | None = None) -> RuntimeRequest:
+        _validate_request_id(request_id)
+        return self._transport.get(request_id, timeout)
+
+
+class AsyncRequests:
+    def __init__(self, transport: AsyncTransport):
+        self._transport = transport
+
+    async def create(
+        self,
+        *,
+        prompt: str,
+        context: dict[str, Any] | None = None,
+        constraints: RequestConstraints | dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> RuntimeRequest:
+        body, key = _serialize_create(prompt, context, constraints, metadata, idempotency_key)
+        return await self._transport.create(body, key, timeout)
+
+    async def get(self, request_id: str, *, timeout: float | httpx.Timeout | None = None) -> RuntimeRequest:
+        _validate_request_id(request_id)
+        return await self._transport.get(request_id, timeout)
+
+
+def _serialize_create(
+    prompt: str,
+    context: dict[str, Any] | None,
+    constraints: RequestConstraints | dict[str, Any] | None,
+    metadata: dict[str, Any] | None,
+    idempotency_key: str | None,
+) -> tuple[bytes, str]:
+    if idempotency_key is None:
+        key = str(uuid4())
+    elif (
+        not isinstance(idempotency_key, str)
+        or not 1 <= len(idempotency_key) <= 128
+        or any(ord(char) < 0x21 or ord(char) > 0x7E for char in idempotency_key)
+    ):
+        raise ValidationError("idempotency_key must contain 1 to 128 visible ASCII characters.")
+    else:
+        key = idempotency_key
+    try:
+        constraint_model = (
+            None
+            if constraints is None
+            else constraints
+            if isinstance(constraints, RequestConstraints)
+            else RequestConstraints.model_validate(constraints)
+        )
+        request = _CreateRequest.model_validate(
+            {"prompt": prompt, "context": context, "constraints": constraint_model, "metadata": metadata}
+        )
+        body_data: dict[str, Any] = {"prompt": request.prompt}
+        if context is not None:
+            body_data["context"] = request.context
+        if constraint_model is not None:
+            body_data["constraints"] = constraint_model.to_api_dict()
+        if metadata is not None:
+            body_data["metadata"] = request.metadata
+        body = json.dumps(body_data, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False).encode(
+            "utf-8"
+        )
+    except PydanticValidationError as exc:
+        fields = [".".join(str(piece) for piece in error.get("loc", [])) for error in exc.errors(include_input=False)]
+        raise ValidationError("Request arguments failed local validation.", details={"fields": fields}) from None
+    except (TypeError, ValueError):
+        raise ValidationError("context and metadata must contain finite JSON values.") from None
+    return body, key
+
+
+def _validate_request_id(request_id: str) -> None:
+    if not isinstance(request_id, str) or not request_id or len(request_id) > 128:
+        raise ConfigurationError("request_id must be a non-empty string of at most 128 characters.")