axonium 1.0.0rc1__tar.gz

axonium-1.0.0rc1/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Rust
+target/
+
+# Environment variables
+**/.env
+
+# macOS
+.DS_Store

axonium-1.0.0rc1/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Emeric Espiritu Santiago
+
+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.
+
+Additional Terms for Enterprise Use:
+
+For commercial or enterprise use, please contact the copyright holder at
+emericespiritusantiago@gmail.com to discuss licensing terms and potential
+remuneration.

axonium-1.0.0rc1/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.5
+Name: axonium
+Version: 1.0.0rc1
+Summary: Python SDK for the Prometheus Gateway inference API
+Project-URL: Homepage, https://github.com/Root1V/axonium-sdk
+Project-URL: Repository, https://github.com/Root1V/axonium-sdk
+Project-URL: Changelog, https://github.com/Root1V/axonium-sdk/blob/main/CHANGELOG.md
+Author: Emeric Espiritu Santiago
+License-Expression: MIT
+License-File: LICENSE
+Keywords: inference,llm,openai-compatible,prometheus-gateway,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.7
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# axonium (Python)
+
+Python SDK for the Prometheus Gateway inference API.
+
+> **Status: release candidate.** The client is feature-complete against the current gateway
+> contract. Not yet published to PyPI.
+
+## Installation
+
+```bash
+pip install axonium
+```
+
+With OpenTelemetry span support:
+
+```bash
+pip install "axonium[otel]"
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+from axonium import Axonium
+
+with Axonium() as client:
+    print(client.models.mine().ids)  # what this token can actually call
+
+    completion = client.chat.completions.create(
+        model="llama3-8b-q4",
+        messages=[{"role": "user", "content": "Hello"}],
+    )
+    print(completion.content)
+```
+
+Streaming is a separate method, because it needs a different scope and is never retried
+automatically:
+
+```python
+with client.chat.completions.stream(model="llama3-8b-q4", messages=messages) as stream:
+    for chunk in stream:
+        print(chunk.content or "", end="", flush=True)
+    print(stream.usage())
+```
+
+`AsyncAxonium` mirrors the whole surface — same names, same behavior, with `await`, `async with`
+and `async for`.
+
+### Reasoning models
+
+A reasoning model streams its chain of thought before any answer token, and keeps it in a field
+separate from the answer. `content` is therefore empty until it stops thinking — with a small
+`max_tokens` it can stay empty, and `finish_reason` will be `"length"`. Both are exposed, and
+neither is inferred from the other:
+
+```python
+if completion.content:
+    print(completion.content)
+elif completion.reasoning:
+    print(f"still thinking: {completion.reasoning}")  # raise max_tokens
+
+# Streaming: a chunk carries one or the other, so progress can show which phase it is in.
+for chunk in stream:
+    print(chunk.reasoning or chunk.content or "", end="")
+print(stream.reasoning, stream.content)
+```
+
+Runnable examples are in [`examples/`](examples/).
+
+## What the client does for you
+
+**Authentication.** Tokens are obtained with OAuth2 `client_credentials` and refreshed *ahead* of
+expiry, so a request never fails just to discover its token died. The lifetime comes from the
+server — its `Date` header and the token's `exp` claim are both server-side readings, so no clock
+skew between your machine and the platform can shorten or extend it. Concurrent callers share one
+refresh rather than each triggering their own.
+
+**Typed errors.** Every gateway error maps to its own exception class, so you branch on the type
+rather than string-matching a human-readable message. The token endpoint's errors are a separate
+branch of the hierarchy, since their shape and meaning differ — `except APIError` will not swallow
+an authentication failure.
+
+**Retries that will not double-bill you.** This API has no idempotency mechanism: a retried
+generation is a new billable one, not a replay. So retries happen only where the platform tells us
+no generation occurred — a rate limit, or a circuit breaker that fast-failed without reaching a
+model. A `502` may have reached one, so retrying it is opt-in. Client-side timeouts are never
+retried, because the backend is probably still working. A server-supplied `Retry-After` is honored,
+but capped: a wait longer than `max_backoff` is handed back to you rather than slept through.
+
+**Request validation before the wire.** The gateway silently drops fields it does not accept, so
+the SDK warns by name about every one it removes instead of letting you believe a parameter took
+effect. Remote image URLs are rejected client-side, with the SSRF reason spelled out.
+
+**Optional modality preflight.** The gateway's modality check is one-directional: calling
+`/v1/embeddings` with a text model is rejected, but calling `/v1/chat/completions` with an
+*embedding* model is not — it returns `200` with degenerate output that you pay for. Enable the
+check to catch that, and typos, before the request is sent:
+
+```python
+client = Axonium(verify_modality=True)  # or AXONIUM_VERIFY_MODALITY=true
+```
+
+Off by default because it costs one catalog request per client, and the SDK otherwise makes no
+request you did not ask for. If you already call `models.list()`, the result is reused and the
+check is free. If the catalog cannot be loaded the check is skipped rather than failing your
+request — a guard rail should not become a new way for inference to break.
+
+## Credential modes
+
+Two modes, permanent and mutually exclusive. Which one you use follows from how the SDK is
+embedded, not from preference.
+
+**Autonomous** — the SDK mints and refreshes its own tokens. For development, notebooks and tests,
+where there is no host to ask.
+
+```python
+client = Axonium(client_id=..., client_secret=...)  # or from the environment
+```
+
+**Governed** — a host that already owns the credential supplies tokens, and the SDK never holds a
+secret. The provider is the sole authority: it owns caching, refresh and rotation, and Axonium does
+no refresh-ahead of its own, because two caches for one token is how a client ends up sending a
+token its owner already retired.
+
+```python
+def tokens(
+    rejected: str | None,
+) -> str: ...  # `rejected` is the token the gateway just refused, or None
+
+
+client = Axonium(token_provider=tokens)
+```
+
+**The rejected token comes back, not a flag.** With a boolean a provider cannot tell whether two
+concurrent refreshes concern the same dead token or different ones, so it must mint twice or guess
+with a time window. Given the token, the answer is exact — if what it holds already differs, it
+refreshed already.
+
+`AsyncAxonium` requires an async provider: a blocking token fetch would stall the event loop, so
+the mismatch is reported rather than tolerated.
+
+Asking for both modes by name is refused. Credentials that merely happen to be in the environment
+are not — the explicit provider wins, and the credentials are **discarded** with a warning, so the
+secret really does leave the process rather than sitting unused.
+
+## Configuration
+
+The SDK never hardcodes a host, port, or certificate — every deployment supplies its own. Settings
+resolve in this order, first match wins:
+
+1. Per-call argument
+2. Constructor argument
+3. Environment variable
+4. `ConfigurationError` naming the missing setting and its environment variable
+
+| Environment variable | Purpose |
+|---|---|
+| `AXONIUM_AUTH_BASE_URL` | auth-service base URL (OAuth2 token endpoint) |
+| `AXONIUM_GATEWAY_BASE_URL` | gateway base URL (`/v1/` inference API) |
+| `AXONIUM_CLIENT_ID` | OAuth2 client ID issued by the platform operator |
+| `AXONIUM_CLIENT_SECRET` | OAuth2 client secret |
+| `AXONIUM_SCOPE` | Optional space-separated scope request |
+| `AXONIUM_CA_BUNDLE` | Path to a CA bundle, for deployments using a self-signed certificate |
+
+The SDK does not read `.env` files. Loading them is the application's responsibility (for example
+with `python-dotenv`), and because settings resolve when the client is constructed rather than at
+import time, load order does not silently change behavior.
+
+## Observability
+
+The platform owns tracing. This SDK provides only the complementary piece: enough for your traces
+and logs to line up with the platform's, and nothing that duplicates what it already records.
+
+**Correlation IDs on every response.** `X-Request-ID` and `X-Trace-ID` are parsed onto
+`response.meta` for successes as well as failures, and onto every raised error. Correlating a slow
+but successful call matters as much as correlating a failed one.
+
+**Rate-limit visibility.** `client.last_rate_limit` and `response.meta.rate_limit` expose the
+`X-RateLimit-*` budget from every response that carries one, so you can slow down before a `429`
+rather than only reacting to one. The token figures are the gateway's post-hoc accounting — a
+strong signal, not a guarantee.
+
+**Structured logging.** The SDK logs under the `axonium` logger with a `NullHandler` attached, so
+it stays silent until your application configures logging. Records carry `request_id`, `trace_id`,
+`model`, `status`, `duration_ms` and `attempt`.
+
+Prompts, completions and credentials are **never** logged, and there is no option to enable it.
+Anything you need to log about the content, you already have at the call site.
+
+**OpenTelemetry spans** are available behind an extra and off by default:
+
+```python
+client = Axonium(otel_enabled=True)  # or AXONIUM_OTEL_ENABLED=true
+```
+
+Spans only — exporters and providers are your application's to configure. Trace context is not
+propagated outbound, because the gateway never reads `traceparent` in any mode; correlation runs
+inbound instead, via the IDs above.
+
+**Scope diagnostics.** A `403` is matched against the scopes your token was actually granted, so
+the error says what is missing rather than just that access was refused:
+
+```
+Forbidden Scope check: the token holds inference:read but not inference:stream;
+streaming needs its own scope and holding one does not grant the other. request_id=...
+```
+
+## Development
+
+```bash
+cd python
+uv sync
+uv run pytest
+uv run ruff check
+uv run mypy src/
+```

axonium-1.0.0rc1/README.md

@@ -0,0 +1,217 @@
+# axonium (Python)
+
+Python SDK for the Prometheus Gateway inference API.
+
+> **Status: release candidate.** The client is feature-complete against the current gateway
+> contract. Not yet published to PyPI.
+
+## Installation
+
+```bash
+pip install axonium
+```
+
+With OpenTelemetry span support:
+
+```bash
+pip install "axonium[otel]"
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+from axonium import Axonium
+
+with Axonium() as client:
+    print(client.models.mine().ids)  # what this token can actually call
+
+    completion = client.chat.completions.create(
+        model="llama3-8b-q4",
+        messages=[{"role": "user", "content": "Hello"}],
+    )
+    print(completion.content)
+```
+
+Streaming is a separate method, because it needs a different scope and is never retried
+automatically:
+
+```python
+with client.chat.completions.stream(model="llama3-8b-q4", messages=messages) as stream:
+    for chunk in stream:
+        print(chunk.content or "", end="", flush=True)
+    print(stream.usage())
+```
+
+`AsyncAxonium` mirrors the whole surface — same names, same behavior, with `await`, `async with`
+and `async for`.
+
+### Reasoning models
+
+A reasoning model streams its chain of thought before any answer token, and keeps it in a field
+separate from the answer. `content` is therefore empty until it stops thinking — with a small
+`max_tokens` it can stay empty, and `finish_reason` will be `"length"`. Both are exposed, and
+neither is inferred from the other:
+
+```python
+if completion.content:
+    print(completion.content)
+elif completion.reasoning:
+    print(f"still thinking: {completion.reasoning}")  # raise max_tokens
+
+# Streaming: a chunk carries one or the other, so progress can show which phase it is in.
+for chunk in stream:
+    print(chunk.reasoning or chunk.content or "", end="")
+print(stream.reasoning, stream.content)
+```
+
+Runnable examples are in [`examples/`](examples/).
+
+## What the client does for you
+
+**Authentication.** Tokens are obtained with OAuth2 `client_credentials` and refreshed *ahead* of
+expiry, so a request never fails just to discover its token died. The lifetime comes from the
+server — its `Date` header and the token's `exp` claim are both server-side readings, so no clock
+skew between your machine and the platform can shorten or extend it. Concurrent callers share one
+refresh rather than each triggering their own.
+
+**Typed errors.** Every gateway error maps to its own exception class, so you branch on the type
+rather than string-matching a human-readable message. The token endpoint's errors are a separate
+branch of the hierarchy, since their shape and meaning differ — `except APIError` will not swallow
+an authentication failure.
+
+**Retries that will not double-bill you.** This API has no idempotency mechanism: a retried
+generation is a new billable one, not a replay. So retries happen only where the platform tells us
+no generation occurred — a rate limit, or a circuit breaker that fast-failed without reaching a
+model. A `502` may have reached one, so retrying it is opt-in. Client-side timeouts are never
+retried, because the backend is probably still working. A server-supplied `Retry-After` is honored,
+but capped: a wait longer than `max_backoff` is handed back to you rather than slept through.
+
+**Request validation before the wire.** The gateway silently drops fields it does not accept, so
+the SDK warns by name about every one it removes instead of letting you believe a parameter took
+effect. Remote image URLs are rejected client-side, with the SSRF reason spelled out.
+
+**Optional modality preflight.** The gateway's modality check is one-directional: calling
+`/v1/embeddings` with a text model is rejected, but calling `/v1/chat/completions` with an
+*embedding* model is not — it returns `200` with degenerate output that you pay for. Enable the
+check to catch that, and typos, before the request is sent:
+
+```python
+client = Axonium(verify_modality=True)  # or AXONIUM_VERIFY_MODALITY=true
+```
+
+Off by default because it costs one catalog request per client, and the SDK otherwise makes no
+request you did not ask for. If you already call `models.list()`, the result is reused and the
+check is free. If the catalog cannot be loaded the check is skipped rather than failing your
+request — a guard rail should not become a new way for inference to break.
+
+## Credential modes
+
+Two modes, permanent and mutually exclusive. Which one you use follows from how the SDK is
+embedded, not from preference.
+
+**Autonomous** — the SDK mints and refreshes its own tokens. For development, notebooks and tests,
+where there is no host to ask.
+
+```python
+client = Axonium(client_id=..., client_secret=...)  # or from the environment
+```
+
+**Governed** — a host that already owns the credential supplies tokens, and the SDK never holds a
+secret. The provider is the sole authority: it owns caching, refresh and rotation, and Axonium does
+no refresh-ahead of its own, because two caches for one token is how a client ends up sending a
+token its owner already retired.
+
+```python
+def tokens(
+    rejected: str | None,
+) -> str: ...  # `rejected` is the token the gateway just refused, or None
+
+
+client = Axonium(token_provider=tokens)
+```
+
+**The rejected token comes back, not a flag.** With a boolean a provider cannot tell whether two
+concurrent refreshes concern the same dead token or different ones, so it must mint twice or guess
+with a time window. Given the token, the answer is exact — if what it holds already differs, it
+refreshed already.
+
+`AsyncAxonium` requires an async provider: a blocking token fetch would stall the event loop, so
+the mismatch is reported rather than tolerated.
+
+Asking for both modes by name is refused. Credentials that merely happen to be in the environment
+are not — the explicit provider wins, and the credentials are **discarded** with a warning, so the
+secret really does leave the process rather than sitting unused.
+
+## Configuration
+
+The SDK never hardcodes a host, port, or certificate — every deployment supplies its own. Settings
+resolve in this order, first match wins:
+
+1. Per-call argument
+2. Constructor argument
+3. Environment variable
+4. `ConfigurationError` naming the missing setting and its environment variable
+
+| Environment variable | Purpose |
+|---|---|
+| `AXONIUM_AUTH_BASE_URL` | auth-service base URL (OAuth2 token endpoint) |
+| `AXONIUM_GATEWAY_BASE_URL` | gateway base URL (`/v1/` inference API) |
+| `AXONIUM_CLIENT_ID` | OAuth2 client ID issued by the platform operator |
+| `AXONIUM_CLIENT_SECRET` | OAuth2 client secret |
+| `AXONIUM_SCOPE` | Optional space-separated scope request |
+| `AXONIUM_CA_BUNDLE` | Path to a CA bundle, for deployments using a self-signed certificate |
+
+The SDK does not read `.env` files. Loading them is the application's responsibility (for example
+with `python-dotenv`), and because settings resolve when the client is constructed rather than at
+import time, load order does not silently change behavior.
+
+## Observability
+
+The platform owns tracing. This SDK provides only the complementary piece: enough for your traces
+and logs to line up with the platform's, and nothing that duplicates what it already records.
+
+**Correlation IDs on every response.** `X-Request-ID` and `X-Trace-ID` are parsed onto
+`response.meta` for successes as well as failures, and onto every raised error. Correlating a slow
+but successful call matters as much as correlating a failed one.
+
+**Rate-limit visibility.** `client.last_rate_limit` and `response.meta.rate_limit` expose the
+`X-RateLimit-*` budget from every response that carries one, so you can slow down before a `429`
+rather than only reacting to one. The token figures are the gateway's post-hoc accounting — a
+strong signal, not a guarantee.
+
+**Structured logging.** The SDK logs under the `axonium` logger with a `NullHandler` attached, so
+it stays silent until your application configures logging. Records carry `request_id`, `trace_id`,
+`model`, `status`, `duration_ms` and `attempt`.
+
+Prompts, completions and credentials are **never** logged, and there is no option to enable it.
+Anything you need to log about the content, you already have at the call site.
+
+**OpenTelemetry spans** are available behind an extra and off by default:
+
+```python
+client = Axonium(otel_enabled=True)  # or AXONIUM_OTEL_ENABLED=true
+```
+
+Spans only — exporters and providers are your application's to configure. Trace context is not
+propagated outbound, because the gateway never reads `traceparent` in any mode; correlation runs
+inbound instead, via the IDs above.
+
+**Scope diagnostics.** A `403` is matched against the scopes your token was actually granted, so
+the error says what is missing rather than just that access was refused:
+
+```
+Forbidden Scope check: the token holds inference:read but not inference:stream;
+streaming needs its own scope and holding one does not grant the other. request_id=...
+```
+
+## Development
+
+```bash
+cd python
+uv sync
+uv run pytest
+uv run ruff check
+uv run mypy src/
+```

axonium-1.0.0rc1/examples/concurrent_and_errors.py

@@ -0,0 +1,83 @@
+"""Concurrent requests, and what the typed errors let you do about failures.
+
+    python examples/concurrent_and_errors.py MODEL_ID
+
+One client is shared across all the tasks: the token is fetched once and refreshed once no matter
+how many requests are in flight, and connections are pooled.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from axonium import (
+    AsyncAxonium,
+    BackendUnavailableError,
+    ConfigurationError,
+    ContextExceededError,
+    RateLimitError,
+    RetryPolicy,
+    SpendCapExceededError,
+    TimeoutError,
+)
+
+QUESTIONS = [
+    "What is the capital of France?",
+    "What is the capital of Japan?",
+    "What is the capital of Peru?",
+]
+
+
+async def ask(client: AsyncAxonium, model: str, question: str) -> str:
+    try:
+        completion = await client.chat.completions.create(
+            model=model,
+            messages=[{"role": "user", "content": question}],
+            # Generous on purpose: a reasoning model spends its budget thinking before it emits
+            # any content, so a tight limit yields an empty string rather than a short answer.
+            max_tokens=512,
+        )
+    except RateLimitError as exc:
+        # Already retried according to the policy; reaching here means the budget is still spent.
+        return f"rate limited, retry in {exc.retry_after}s"
+    except BackendUnavailableError as exc:
+        # With retry_after set the gateway's circuit breaker is open and that value is its real
+        # expected recovery time. Without it, the backend was simply unreachable.
+        return f"backend unavailable{f', retry in {exc.retry_after}s' if exc.retry_after else ''}"
+    except SpendCapExceededError:
+        # Distinct from a rate limit on purpose: waiting will not fix this one.
+        return "spend cap reached; the cap has to be raised"
+    except ContextExceededError:
+        return "prompt is too long for this model's context window"
+    except TimeoutError:
+        # Deliberately not retried: the backend may still be generating, and a retry would start
+        # a second billable generation rather than resuming the first.
+        return "timed out; the backend may still be working"
+
+    return completion.content or "(no content)"
+
+
+async def main(model: str) -> None:
+    try:
+        # Retrying a generation is never free, so the policy is explicit rather than implied.
+        client = AsyncAxonium(retry=RetryPolicy(max_attempts=3))
+    except ConfigurationError as exc:
+        print(f"Not configured: {exc}")
+        return
+
+    async with client:
+        answers = await asyncio.gather(*(ask(client, model, q) for q in QUESTIONS))
+
+        for question, answer in zip(QUESTIONS, answers, strict=True):
+            print(f"{question}\n  -> {answer}\n")
+
+        if client.last_rate_limit:
+            print(f"Requests left this window: {client.last_rate_limit.remaining_requests}")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print(__doc__)
+        sys.exit(1)
+    asyncio.run(main(sys.argv[1]))

axonium-1.0.0rc1/examples/quickstart.py

@@ -0,0 +1,80 @@
+"""Basic usage: discover what a token can call, then call it.
+
+    python examples/quickstart.py
+
+Reads configuration from the environment. If your credentials live in a .env file, load it before
+constructing the client — the SDK does not read .env itself, and deliberately resolves settings
+when the client is built rather than at import time, so load order cannot silently change what you
+get.
+"""
+
+from __future__ import annotations
+
+from axonium import Axonium, ConfigurationError, ForbiddenError, UnknownModelError
+
+
+def main() -> None:
+    try:
+        client = Axonium()
+    except ConfigurationError as exc:
+        # Names the missing setting and the environment variable that supplies it.
+        print(f"Not configured: {exc}")
+        return
+
+    with client:
+        # Public: no token is fetched for this call.
+        catalog = client.models.list()
+        print(f"Deployed models: {', '.join(catalog.ids) or '(none)'}")
+
+        # Filtered to what this token actually holds a model:<id> grant for. Worth doing once at
+        # startup: it turns "why is everything 403" into a list you can read.
+        mine = client.models.mine()
+        print(f"Callable with this token: {', '.join(mine.ids) or '(none)'}")
+
+        if not mine.ids:
+            print("This token has no model grants; ask the operator to add model:<id> scopes.")
+            return
+
+        text_models = [m.id for m in mine if m.modality == "text"]
+        if not text_models:
+            print("This token has no text model to chat with.")
+            return
+
+        model = text_models[0]
+        try:
+            completion = client.chat.completions.create(
+                model=model,
+                messages=[{"role": "user", "content": "Reply with exactly: pong"}],
+                # Generous on purpose. A reasoning model spends its budget thinking before it
+                # emits any content, so a small limit returns an empty string and
+                # finish_reason="length" rather than a short answer.
+                max_tokens=512,
+            )
+        except UnknownModelError:
+            print(f"{model} is not registered on this gateway.")
+            return
+        except ForbiddenError as exc:
+            # The SDK checks the denial against the scopes the token was granted and says what
+            # is missing, rather than leaving you to guess.
+            print(f"Denied: {exc}")
+            return
+
+        if completion.content:
+            print(f"\n{model} says: {completion.content}")
+        else:
+            reason = completion.choices[0].finish_reason if completion.choices else None
+            print(f"\n{model} returned no content (finish_reason={reason!r}).")
+            if completion.reasoning:
+                print(f"It was still reasoning: {completion.reasoning[:120]}...")
+                print("Raise max_tokens to give it room to finish.")
+
+        if completion.usage:
+            print(f"Tokens: {completion.usage.total_tokens}")
+        if completion.meta:
+            print(f"Request ID: {completion.meta.request_id}")
+        if client.last_rate_limit:
+            print(f"Requests left this window: {client.last_rate_limit.remaining_requests}")
+
+
+if __name__ == "__main__":
+    main()