trusted-router-py 0.2.0__tar.gz

trusted_router_py-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      - run: uv sync --group dev
+      - run: uv run ruff check .
+      - run: uv run pytest
+      - name: Upload coverage XML for downstream tools
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: ignore

trusted_router_py-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,48 @@
+name: Release to PyPI
+
+# Triggered when a `vX.Y.Z` tag is pushed. Uses PyPI Trusted Publishing
+# (OIDC) — no API token needed once the publisher is configured at
+# https://pypi.org/manage/account/publishing/. The publisher must match:
+#   PyPI project name : trusted-router-py
+#   Owner             : Lore-Hex
+#   Repository        : trusted-router-py
+#   Workflow filename : release.yml
+#   Environment       : pypi  (matches the env: line below)
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      - run: uv sync --group dev
+      - run: uv run ruff check .
+      - run: uv run pytest
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          # No `password:` — uses GitHub OIDC + PyPI's trusted publisher.

trusted_router_py-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.coverage
+coverage.xml
+htmlcov/

trusted_router_py-0.2.0/LICENSE

@@ -0,0 +1,174 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions to
+      that Work or Derivative Works thereof, that is intentionally submitted
+      to Licensor for inclusion in the Work by the copyright owner or by an
+      individual or Legal Entity authorized to submit on behalf of the
+      copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of, publicly
+      display, publicly perform, sublicense, and distribute the Work and such
+      Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of this
+      License, each Contributor hereby grants to You a perpetual, worldwide,
+      non-exclusive, no-charge, royalty-free, irrevocable (except as stated
+      in this section) patent license to make, have made, use, offer to sell,
+      sell, import, and otherwise transfer the Work, where such license
+      applies only to those patent claims licensable by such Contributor
+      that are necessarily infringed by their Contribution(s) alone or by
+      combination of their Contribution(s) with the Work to which such
+      Contribution(s) was submitted. If You institute patent litigation
+      against any entity (including a cross-claim or counterclaim in a
+      lawsuit) alleging that the Work or a Contribution incorporated within
+      the Work constitutes direct or contributory patent infringement, then
+      any patent licenses granted to You under this License for that Work
+      shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the Work or
+      Derivative Works thereof in any medium, with or without modifications,
+      and in Source or Object form, provided that You meet the following
+      conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works
+          a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works that
+          You distribute, all copyright, patent, trademark, and attribution
+          notices from the Source form of the Work, excluding those notices
+          that do not pertain to any part of the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one of
+          the following places: within a NOTICE text file distributed as
+          part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do not
+          modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions for
+      use, reproduction, or distribution of Your modifications, or for any
+      such Derivative Works as a whole, provided Your use, reproduction, and
+      distribution of the Work otherwise complies with the conditions stated
+      in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work by
+      You to the Licensor shall be under the terms and conditions of this
+      License, without any additional terms or conditions. Notwithstanding
+      the above, nothing herein shall supersede or modify the terms of any
+      separate license agreement you may have executed with Licensor
+      regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed to
+      in writing, Licensor provides the Work (and each Contributor provides
+      its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+      CONDITIONS OF ANY KIND, either express or implied, including, without
+      limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
+      MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely
+      responsible for determining the appropriateness of using or
+      redistributing the Work and assume any risks associated with Your
+      exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise, unless
+      required by applicable law (such as deliberate and grossly negligent
+      acts) or agreed to in writing, shall any Contributor be liable to You
+      for damages, including any direct, indirect, special, incidental, or
+      consequential damages of any character arising as a result of this
+      License or out of the use or inability to use the Work (including but
+      not limited to damages for loss of goodwill, work stoppage, computer
+      failure or malfunction, or any and all other commercial damages or
+      losses), even if such Contributor has been advised of the possibility
+      of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing the
+      Work or Derivative Works thereof, You may choose to offer, and charge
+      a fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your own
+      behalf and on Your sole responsibility, not on behalf of any other
+      Contributor, and only if You agree to indemnify, defend, and hold each
+      Contributor harmless for any liability incurred by, or claims asserted
+      against, such Contributor by reason of your accepting any such
+      warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

trusted_router_py-0.2.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: trusted-router-py
+Version: 0.2.0
+Summary: Python SDK for TrustedRouter.
+Project-URL: Homepage, https://trustedrouter.com
+Project-URL: Repository, https://github.com/Lore-Hex/trusted-router-py
+Project-URL: Trust, https://trust.trustedrouter.com
+Author: Lore Hex
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: attestation
+Requires-Dist: cryptography>=42; extra == 'attestation'
+Description-Content-Type: text/markdown
+
+# TrustedRouter Python SDK
+
+OpenAI-compatible Python client for [TrustedRouter](https://trustedrouter.com) —
+the hosted, attested LLM router that lets you point one OpenAI-shaped client
+at every provider (Anthropic, OpenAI, Google Vertex, Gemini, DeepSeek,
+Mistral, Cerebras) and *prove* the prompt path doesn't log.
+
+- Gateway: `https://api.quillrouter.com/v1`
+- Trust release: `https://trust.trustedrouter.com`
+- Source: `https://github.com/Lore-Hex/trusted-router-py`
+- License: Apache-2.0
+
+```bash
+pip install trusted-router-py                  # base client
+pip install trusted-router-py[attestation]     # + GCP attestation verification
+```
+
+## Quick start
+
+```python
+from trustedrouter import TrustedRouter, AUTO_MODEL
+
+with TrustedRouter(api_key="sk-tr-v1-...") as client:
+    resp = client.chat_completions(
+        model=AUTO_MODEL,                     # "trustedrouter/auto" — multi-provider failover
+        messages=[{"role": "user", "content": "hello"}],
+    )
+    print(resp["choices"][0]["message"]["content"])
+```
+
+`chat_completions(...)` defaults to `AUTO_MODEL` when `model=` is omitted, so
+the simplest possible call is `client.chat_completions(messages=[...])`.
+
+## Streaming
+
+```python
+for token in client.chat_completions_stream(
+    model=AUTO_MODEL,
+    messages=[{"role": "user", "content": "Write a haiku"}],
+):
+    print(token, end="", flush=True)
+```
+
+`chat_completions_chunk_stream(...)` yields the raw OpenAI
+`chat.completion.chunk` dicts (with `finish_reason`, `model`, `id`) when you
+need more than just the text delta.
+
+## Async
+
+Every method on `TrustedRouter` is mirrored on `AsyncTrustedRouter` as a
+coroutine; streaming methods return `AsyncIterator`s. Use it from FastAPI,
+asyncio, or any event-loop-driven app:
+
+```python
+import asyncio
+from trustedrouter import AsyncTrustedRouter
+
+async def main():
+    async with AsyncTrustedRouter(api_key="sk-tr-v1-...") as client:
+        async for token in client.chat_completions_stream(
+            model="trustedrouter/auto",
+            messages=[{"role": "user", "content": "hi"}],
+        ):
+            print(token, end="", flush=True)
+
+asyncio.run(main())
+```
+
+## Region pinning
+
+The gateway is deployed in `us-central1` (the apex) and `europe-west4`. Pin
+to a specific region with one kwarg — no need to construct the URL yourself:
+
+```python
+client = TrustedRouter(api_key="sk-tr-v1-...", region="europe-west4")
+```
+
+The full list lives in `trustedrouter.REGION_HOSTS`. Pass `region=` for known
+regions, or `base_url=` for a custom endpoint (e.g. a self-hosted gateway).
+Passing both is a configuration error.
+
+## Typed errors
+
+Every HTTP failure raises a typed subclass of `TrustedRouterError` so callers
+can discriminate without inspecting status codes:
+
+```python
+from trustedrouter import (
+    TrustedRouter, AuthenticationError, RateLimitError,
+    BadRequestError, NotFoundError, InternalError,
+)
+
+try:
+    client.chat_completions(messages=[...])
+except RateLimitError as e:
+    time.sleep(e.retry_after or 5)        # honors Retry-After header
+except AuthenticationError:
+    refresh_key()
+except BadRequestError as e:
+    log.warning("bad request: %s", e)
+except InternalError:
+    pass                                   # auto-retried; still failing
+```
+
+All subclasses inherit from `TrustedRouterError`, so existing
+`except TrustedRouterError` blocks keep working.
+
+## Automatic retries
+
+By default the client retries `429` and `5xx` responses up to **2 times**
+with exponential backoff + jitter (capped at 30s, honors `Retry-After`).
+Disable with `max_retries=0`:
+
+```python
+client = TrustedRouter(api_key="...", max_retries=0)   # raise immediately on transient
+```
+
+## Per-call extras
+
+Every chat method (and `request()` for ad-hoc paths) accepts:
+
+| kwarg | use |
+|---|---|
+| `api_key=` | override the instance bearer for this call only (threadsafe — used by validate_bearer) |
+| `extra_headers=` | dict of headers to merge in (trace IDs, custom routing) |
+| `idempotency_key=` | adds `Idempotency-Key:` so the gateway dedupes retries — **strongly recommended for billing** |
+| `timeout=` | override the client-level timeout for this call |
+
+```python
+client.billing_checkout(
+    amount=25,
+    payment_method="stablecoin",
+    idempotency_key=f"checkout-{user_id}-{order_id}",   # never double-charge
+)
+```
+
+## Attestation verification (the differentiator)
+
+Every TrustedRouter response is generated inside a Google Confidential Space
+workload. The gateway's `/attestation` endpoint mints a Google-signed JWT
+that commits to the workload image digest, image reference, your nonce, and
+the TLS leaf cert SHA-256. Verifying it proves the prompt path you're about
+to use is the exact build the trust page advertises:
+
+```python
+import secrets, ssl, socket
+from trustedrouter import TrustedRouter
+from trustedrouter.attestation import (
+    verify_gateway_attestation, policy_from_trust_release,
+)
+
+# Pull the published image digest/reference from the trust page
+policy = policy_from_trust_release()                 # or pin one explicitly
+
+with TrustedRouter(api_key="sk-tr-v1-...") as client:
+    nonce = secrets.token_hex(16)
+    jwt = client.attestation()                       # raw JWT bytes
+
+    # Bind the JWT to the live TLS connection's cert
+    with ssl.create_default_context().wrap_socket(
+        socket.create_connection(("api.quillrouter.com", 443)),
+        server_hostname="api.quillrouter.com",
+    ) as s:
+        cert_der = s.getpeercert(binary_form=True)
+
+    attestation = verify_gateway_attestation(
+        jwt, policy=policy, nonce_hex=nonce, tls_cert_der=cert_der
+    )
+    print("verified gateway:", attestation.image_digest)
+```
+
+`verify_gateway_attestation()` raises `AttestationVerificationError` on any
+of: bad signature, expired JWT, wrong issuer, audience mismatch,
+image_digest mismatch, image_reference mismatch, missing nonce echo, or
+TLS cert mismatch. Never returns falsey for a failed verification.
+
+This codepath needs `cryptography`; install with
+`pip install trusted-router-py[attestation]`.
+
+## Bring your own httpx client
+
+Pass `client=` if you need a custom transport (cert pinning, retries you
+manage, observability hooks). The SDK won't close it on `aclose()`:
+
+```python
+import httpx
+from trustedrouter import AsyncTrustedRouter
+
+my_client = httpx.AsyncClient(
+    timeout=30.0,
+    event_hooks={"response": [my_cert_pin_hook]},
+)
+sdk = AsyncTrustedRouter(api_key="...", client=my_client)
+# ...use sdk...
+await sdk.aclose()        # no-op for caller-owned clients
+await my_client.aclose()  # caller still owns lifecycle
+```
+
+This is exactly how the [Quill device](https://github.com/Lore-Hex/quill)
+wraps the SDK so it can pin Quill Cloud's self-signed leaf cert via an
+httpx event hook, while delegating chat streaming to the SDK.
+
+## CLI
+
+`pip install` exposes a `trustedrouter` console script for sniff tests:
+
+```bash
+export TRUSTEDROUTER_API_KEY=sk-tr-v1-...
+
+trustedrouter chat "hello"                 # one-shot completion
+trustedrouter chat --stream "long answer"  # token-by-token
+trustedrouter regions                      # list deployed regions
+trustedrouter providers                    # list provider catalog
+trustedrouter models                       # list model catalog
+trustedrouter trust                        # show trust release
+trustedrouter attest                       # raw JWT bytes (pipe to `jq`-able tools)
+trustedrouter --region europe-west4 chat "hi"
+```
+
+## Other endpoints
+
+```python
+client.models()             # OpenAI-shape catalog
+client.providers()          # provider list
+client.regions()            # deployed regions
+client.credits()            # current prepaid balance
+client.activity(since="2026-01-01", limit=50)
+client.embeddings(model="text-embed", input="hello")
+client.messages(            # Anthropic-shape, preserves system + content blocks
+    model="anthropic/claude-3-5-sonnet",
+    messages=[{"role": "user", "content": "hi"}],
+    max_tokens=512,
+)
+client.billing_checkout(amount=25, payment_method="stablecoin", idempotency_key=...)
+```
+
+For routes the SDK doesn't wrap, drop down to `client.request(...)`:
+
+```python
+client.request("GET", "/some/new/route", headers={"x-trace": "abc"})
+```
+
+## Roadmap
+
+- **v0.3 (planned):** typed pydantic response models. Today every method
+  returns `dict[str, Any]`; pydantic models will give you IDE autocomplete +
+  runtime validation. Currently held back to avoid adding a heavy dependency
+  to the base install.
+- **v0.x:** AWS Nitro Enclaves attestation path (currently only GCP).
+
+## Contributing
+
+```bash
+uv sync --group dev
+uv run ruff check .
+uv run pytest                              # ~110 tests, ≥85% coverage gate
+```
+
+CI runs lint + tests on every push to main and PR. Coverage gate is
+enforced — PRs that drop coverage below 85% fail. Add tests with new
+public surface.