theagentrouter-core 0.1.0a1__tar.gz

theagentrouter_core-0.1.0a1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,38 @@
+name: Bug report
+description: Something does not work as described
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: The smallest code that shows the problem, and the full error.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: model
+    attributes:
+      label: Model name
+      placeholder: anthropic/claude-sonnet-4-5
+    validations:
+      required: true
+  - type: dropdown
+    id: route
+    attributes:
+      label: Where the call goes
+      options: [Direct to the provider, Through a gateway (AGENTROUTER_BASE_URL), api_base on the call]
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: theagentrouter version
+      placeholder: python -c "import theagentrouter; print(theagentrouter.__version__)"
+    validations:
+      required: true
+  - type: input
+    id: framework
+    attributes:
+      label: Agent framework, if any
+      placeholder: Google ADK 2.10.0

theagentrouter_core-0.1.0a1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security problem
+    url: https://github.com/theagentrouter/agent-router-python/security/advisories/new
+    about: Report security problems privately, not as an issue.

theagentrouter_core-0.1.0a1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,15 @@
+name: Feature request
+description: Suggest a change
+labels: [enhancement]
+body:
+  - type: textarea
+    id: need
+    attributes:
+      label: What you are trying to do
+      description: Describe the job, not the solution.
+    validations:
+      required: true
+  - type: textarea
+    id: idea
+    attributes:
+      label: What you would like the SDK to do

theagentrouter_core-0.1.0a1/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

theagentrouter_core-0.1.0a1/.github/pull_request_template.md

@@ -0,0 +1,8 @@
+## What this changes
+
+## Checklist
+
+- [ ] Tests added or updated (`pytest`)
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] If the public API changed on purpose: `python scripts/surface.py --write`, and the reason is above
+- [ ] `CHANGELOG.md` updated under "Unreleased", if users will notice

theagentrouter_core-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: pytest
+      - run: python scripts/check_release.py
+
+  adk:
+    # A real Google ADK agent on this SDK, in an environment without LiteLLM.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[test]" google-adk
+      - run: python -c "import importlib.util as u, sys; sys.exit(u.find_spec('litellm') is not None)"
+      - run: pytest tests/test_adk.py --junitxml=adk-tests.xml
+      - run: python scripts/check_test_report.py adk-tests.xml
+
+  openai-agents:
+    # A real OpenAI Agents SDK agent on this SDK, in an environment without LiteLLM.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[test]" openai-agents
+      - run: python -c "import importlib.util as u, sys; sys.exit(u.find_spec('litellm') is not None)"
+      - run: pytest tests/test_openai_agents.py --junitxml=agents-tests.xml
+      - run: python scripts/check_test_report.py agents-tests.xml
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build                                         # theagentrouter-core
+      - run: python -m build packages/theagentrouter --outdir dist   # theagentrouter, no code
+      - run: python -m twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  local-gateway:
+    uses: ./.github/workflows/local-gateway-build.yml

theagentrouter_core-0.1.0a1/.github/workflows/local-gateway-build.yml

@@ -0,0 +1,77 @@
+name: Local gateway packages
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-14
+            target: darwin-arm64
+          - os: ubuntu-24.04
+            target: linux-amd64
+          - os: ubuntu-24.04-arm
+            target: linux-arm64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine pytest pytest-asyncio
+      - run: python scripts/check_release.py
+      - run: python scripts/fetch_aigw.py
+      - run: python -m build --wheel
+      - run: python -m build --wheel local-gateway --outdir local-dist
+      - run: python -m twine check --strict local-dist/*
+      - name: Install built packages
+        run: pip install dist/*.whl local-dist/*.whl
+      - name: PyPI companion wheel size limit
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+          for wheel in Path("local-dist").glob("*.whl"):
+              assert wheel.stat().st_size <= 100 * 1024 * 1024, f"{wheel} exceeds PyPI's default file limit"
+          PY
+      - run: python -m pip check
+      # Every test that starts the real aigw: the gateway itself, routes (fallbacks, retries,
+      # request limits) and embeddings. None may skip here.
+      - run: pytest tests/test_local_gateway.py tests/test_routes.py tests/test_embeddings.py --junitxml=local-gateway-tests.xml
+      - run: python scripts/check_test_report.py local-gateway-tests.xml
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-local-${{ matrix.target }}
+          path: local-dist/*.whl
+          compression-level: 0
+          if-no-files-found: error
+
+  # Where no platform wheel fits, pip installs this one, so `pip install theagentrouter` never fails.
+  fallback:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: AGENTROUTER_NO_BINARY_WHEEL=1 python -m build --wheel local-gateway --outdir local-dist
+      - run: python -m twine check --strict local-dist/*
+      - name: The fallback wheel has no program, and the SDK sees no local gateway
+        run: |
+          test "$(ls local-dist)" = "theagentrouter_local_gateway-$(python scripts/check_release.py --print-version)-py3-none-any.whl"
+          if unzip -l local-dist/*.whl | grep -q "/bin/"; then echo "the fallback wheel contains a program"; exit 1; fi
+          pip install . local-dist/*.whl
+          python -c "import theagentrouter.local_gateway as g; assert not g.installed()"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-local-any
+          path: local-dist/*.whl
+          if-no-files-found: error

theagentrouter_core-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,96 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    uses: ./.github/workflows/ci.yml
+
+  verify:
+    needs: checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python scripts/check_release.py --tag "$GITHUB_REF_NAME"
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: dist-local-*
+          path: companion-dist/
+          merge-multiple: true
+      - name: Verify SDK and all companion wheels are present
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+          files = list(Path("dist").glob("*")) + list(Path("companion-dist").glob("*"))
+          # darwin-arm64, linux-amd64, linux-arm64, and the py3-none-any fallback with no program
+          assert len(list(Path("companion-dist").glob("theagentrouter_local_gateway-*.whl"))) == 4
+          assert len(list(Path("companion-dist").glob("theagentrouter_local_gateway-*-py3-none-any.whl"))) == 1
+          for name in ("theagentrouter_core", "theagentrouter"):
+              assert len(list(Path("dist").glob(f"{name}-[0-9]*.whl"))) == 1, name
+              assert len(list(Path("dist").glob(f"{name}-[0-9]*.tar.gz"))) == 1, name
+          assert len(files) == 8
+          PY
+
+  # One job and one GitHub environment per package. PyPI accepts only one pending
+  # trusted publisher per owner, repository, workflow and environment, so each
+  # package needs its own environment until its project exists on PyPI.
+  # Each package goes up after the ones it depends on: the gateway, the SDK, then theagentrouter.
+  publish-local-gateway:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: pypi-local-gateway
+    permissions:
+      id-token: write   # PyPI trusted publishing; no token stored anywhere
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: dist-local-*
+          path: companion-dist/
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: companion-dist/
+
+  publish-core:
+    needs: publish-local-gateway
+    runs-on: ubuntu-latest
+    environment: pypi-core
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - run: rm dist/theagentrouter-[0-9]*
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  publish-theagentrouter:
+    needs: publish-core
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - run: rm dist/theagentrouter_core-*
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

theagentrouter_core-0.1.0a1/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+local-dist/
+build/
+.pytest_cache/
+.venv-adk/
+.venv-agents/
+
+# Local provider keys for scripts/smoke_*.py. Never committed.
+.env
+
+# The aigw program for the local-gateway package; put there by `make local-gateway`
+local-gateway/src/theagentrouter_local_gateway/bin/

theagentrouter_core-0.1.0a1/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

theagentrouter_core-0.1.0a1/AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md
+
+Instructions for coding agents (and people) working in this repository. `CLAUDE.md` points here.
+
+## What this is
+
+`theagentrouter` (imported as `theagentrouter`) is an open-source Python library. Agent frameworks use it to call AI models. It keeps LiteLLM's way of calling models (`completion`, `provider/model` names, response fields, error names) in a small install whose only dependency is `httpx`.
+
+It speaks two request formats: OpenAI Chat Completions and Anthropic Messages. With no gateway, it calls providers that already speak one of them. With a gateway set, it sends every call there in the OpenAI format, and the gateway translates.
+
+## Layout
+
+| Path | What it holds |
+|---|---|
+| `src/theagentrouter/__init__.py` | Public API: `completion`, `acompletion`, model lookups |
+| `src/theagentrouter/routing.py` | Where a call goes: `api_base`, a gateway you set, or the local gateway. Never a provider directly; settings from the environment and `AGENTROUTER_HOME/config.json` |
+| `src/theagentrouter/routes.py` | Routes: names of your own with fallbacks and retries (`route`, `Retry`), stored in `AGENTROUTER_HOME/routes.json` and served by the local gateway |
+| `src/theagentrouter/local_gateway.py` | The local gateway: which providers the environment has, the `aigw` config, starting, finding and stopping `aigw` |
+| `local-gateway/` | The `theagentrouter-local-gateway` package: the `aigw` program, one wheel per platform |
+| `packages/theagentrouter/` | The `theagentrouter` package: no code; installs `theagentrouter-core` (the root package) and the local gateway |
+| `src/theagentrouter/openai_format.py` | Build OpenAI requests; read responses and SSE streams |
+| `src/theagentrouter/anthropic_format.py` | Convert OpenAI-style messages and tools to Anthropic Messages; read responses and streams back |
+| `src/theagentrouter/transport.py` | HTTP with `httpx`, sync and async, streaming, error mapping |
+| `src/theagentrouter/exceptions.py` | LiteLLM's error names; `from_http` maps HTTP errors to them |
+| `src/theagentrouter/types.py` | LiteLLM-shaped response types; readable by attribute and as dicts |
+| `src/theagentrouter/models.py`, `model_catalog.json` | Model prices and limits from tetrateio/agent-router-models (bundled; never fetched at run time) |
+| `src/theagentrouter/compat/` | The LiteLLM-compatible module and `install_as_litellm()` |
+| `surface.txt` | The recorded public surface |
+| `tests/` | Tests against a local fake provider; `test_adk.py` and `test_openai_agents.py` run real Google ADK and OpenAI Agents SDK agents |
+| `scripts/` | `surface.py`, `sync_models.py`, `smoke_real.py`, `smoke_adk_real.py`, `smoke_local_gateway.py`, `smoke_routes.py` |
+
+## Rules
+
+1. **Keep LiteLLM's API.** Same function names, arguments, response fields and error names. A framework that works with LiteLLM must work after `install_as_litellm()`.
+2. **No provider code beyond the two formats.** The SDK never calls a provider; a new provider is one row in `local_gateway.PROVIDERS` (its `aigw` schema, address and key variables), which the local gateway's config is written from. Anything that needs translation belongs in the gateway, not here.
+3. **One dependency.** Do not add runtime dependencies without a strong reason; `httpx` is the only one.
+4. **The public surface is a contract.** `tests/test_surface.py` fails when the surface changes. After a deliberate change, run `python scripts/surface.py --write` and say why in the change description. The Enterprise SDK checks itself against `surface.txt`: it must contain all of it, unchanged.
+5. **Never refer to the Enterprise package.** The open-source SDK must not import, mention or look for the Enterprise package (`tetrate-agentrouter`, imported as `tetrate.agentrouter`). A test checks this.
+6. **Settings come from the environment, then `AGENTROUTER_HOME/config.json`.** Do not add a second place to read them.
+7. **No secrets in tests or examples.** Tests use the fake provider in `tests/fake_provider.py`. Real-provider checks live in `scripts/smoke_real.py` and read keys from the environment.
+
+## Commands
+
+```sh
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest                         # all tests, no keys needed
+.venv/bin/ruff check . && .venv/bin/ruff format --check .
+.venv/bin/python scripts/surface.py --write    # after a deliberate API change
+.venv/bin/python scripts/sync_models.py        # refresh the model table
+```
+
+`DEVELOPMENT.md` has the details, including the framework tests and the release steps. User docs are in `docs/`: keep `install.md`, `usage.md`, `coming-from-litellm.md` and `frameworks.md` in step with the code, especially the LiteLLM lists when `compat/litellm.py` or `transport.IGNORED` changes.
+
+## Before you finish a change
+
+- `pytest`, `ruff check` and `ruff format --check` pass.
+- New behavior has a test against the fake provider.
+- `CHANGELOG.md` has a line under "Unreleased" for anything a user would notice.

theagentrouter_core-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this project are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
+
+## Unreleased
+
+### Added (2026-10-12)
+
+- After an SDK upgrade, the next call restarts a local gateway that the old version started. `state.json` records the SDK's and the local gateway's versions.
+
+### Fixed (2026-10-12)
+
+- `pip install theagentrouter` no longer fails where the local gateway has no wheel (Intel macOS, macOS 12 and older, Alpine, Linux before glibc 2.36, Windows). A `py3-none-any` local gateway wheel with no program is published next to the platform wheels; pip picks it only where none fits, and the SDK then runs without a local gateway. The macOS wheel needs macOS 13 or newer; the docs said 12.
+- Two programs defining routes at the same time no longer lose one: the route file is locked while it is changed and written in one step.
+- Removing a route named like a model (`openai/gpt-4o-mini`) restarts the local gateway on the next call; the route's fallbacks, retries and limit stayed active before.
+- With `AGENTROUTER_AUTOSTART=0`, a route works when the running gateway already has it.
+- Claude: `cache_control` on content parts, on a whole message (LiteLLM's form) and on tools reaches Anthropic, so prompt caching works; the system prompt goes as text blocks when one is marked. Cache reads show in `usage.prompt_tokens_details.cached_tokens`.
+- Claude: streamed thinking arrives as `delta.reasoning_content`, and responses and rebuilt streams carry `thinking_blocks` with their signatures, as LiteLLM's do. Streamed, each fragment of thinking text comes in its own chunk and the signature alone in a last chunk, LiteLLM's shape, so Google ADK puts the block back together unchanged. Sent back with a tool result, the blocks go to Anthropic first in the turn, unchanged, which Anthropic requires when thinking is on.
+- `stream_chunk_builder` rebuilds each choice on its own; with `n=2` the two answers were joined into one.
+- `acompletion`, `aembedding` and `aresponses` no longer block the event loop while the local gateway starts.
+- `completion_cost` works on a `responses()` reply (it read only Chat Completions usage).
+- `validate_environment` for Bedrock asks for `AWS_SECRET_ACCESS_KEY` and `AWS_REGION` too, as the local gateway does.
+- The release workflow runs the route and embedding tests against the real `aigw`, not only the local gateway tests.
+
+### Changed (2026-10-12)
+
+- The bundled model list is read from `tetrateio/agent-router-models` (the SDK pointed at a `theagentrouter/` copy that does not exist) and refreshed: 228 models. DeepInfra models are keyed `deepinfra/<model>`; they were `deepinfra/deepinfra/<model>`, so lookups by their usual name found nothing.
+- **The local gateway chooses its port at each start** instead of always using 1975, so Tetrate Desktop or another `aigw run` on 1975 no longer blocks it. SDK programs find it through `state.json`. When `aigw`'s fixed internal ports (1061, 18000) are taken, the error names the program holding them.
+- **The SDK talks only to a gateway.** It no longer calls OpenAI, Anthropic, Gemini, Groq, Mistral, DeepSeek or Together directly: every call goes to the local gateway (Agent Router on this computer), to a gateway set with `AGENTROUTER_BASE_URL`, or to an endpoint named with `api_base=` (LiteLLM's argument). Claude goes to the gateway in Anthropic's Messages format, so prompt caching and thinking keep working.
+- **Three packages.** `theagentrouter` installs the SDK and, on macOS 13+ (Apple chips) and Linux (x86-64, Arm), the local gateway; it has no code of its own. `theagentrouter-core` is the SDK alone, for a remote gateway (servers, containers, serverless, CI). `theagentrouter-local-gateway` holds `aigw`. All import as `import theagentrouter`. `theagentrouter[local-gateway]` still works.
+- `api_key=` without `api_base=` warns and has no effect: the local gateway reads provider keys from the environment.
+- `_hidden_params["route"]` is `local gateway`, `gateway` or `api_base` (was `direct` for calls to providers).
+
+### Added
+
+- The rest of what agent frameworks call from LiteLLM (counted across 20 frameworks that import it): OpenAI and Anthropic model names work without a provider, as in LiteLLM (`gpt-4o-mini`, `claude-haiku-4-5`); a bare `gemini-…` is refused with the reason, since LiteLLM sends it to Vertex AI; `responses` and `aresponses` for OpenAI models, through the gateway's `/v1/responses`; `stream_chunk_builder`; `validate_environment`; `success_callback`, `failure_callback` and `callbacks` in `theagentrouter.compat.litellm`, calling your functions and loggers after each call and stream; `model_list`, `cost_calculator`, and `ChatCompletionDeltaToolCall`, `CostPerToken` and `ChatCompletionMessageToolCall` under `types.utils`.
+- A route defined in Python warns when `AGENTROUTER_BASE_URL` is set: routes program the local gateway only.
+- `token_counter`, with LiteLLM's arguments, also under `theagentrouter.compat.litellm`. OpenAI and Anthropic are counted by the gateway (`/responses/input_tokens`, `/messages/count_tokens`); everything else is estimated with LiteLLM's rules, using tiktoken from the new `tokens` extra or about four characters a token without it. `AGENTROUTER_TOKEN_COUNT=estimate` always estimates.
+- Embeddings: `theagentrouter.embedding` and `aembedding`, also under `theagentrouter.compat.litellm`, with LiteLLM's arguments and `EmbeddingResponse`, priced from the model list. Direct for OpenAI-format providers, through a gateway for the rest; Anthropic has none.
+- Request limits on routes: `route(..., limit=Limit(requests, per="minute"))`, enforced by the local gateway with Envoy's local rate limit. Requests, not tokens: counting tokens needs Redis, which `aigw run` does not have.
+- Routes: `theagentrouter.route(name, primary, fallbacks, retry)`, with `Retry`, `list_routes` and `remove_route`. A route is a model name of your own; the local gateway does its retries and fallbacks, with the models at priority 0, 1, …, as Agent Router Enterprise does. Models in one tier share the traffic.
+- LiteLLM's `Router` in `theagentrouter.compat.litellm`, for `model_list`, `fallbacks` and `num_retries`, served by routes.
+- Responses from a route carry `served_by` (read from the reply's model name) and `route_name` in `_hidden_params`, and are priced as the model that answered.
+- The local gateway writes a backend at `127.0.0.1` as `localhost`, and waits after starting until Envoy has looked up every route's backends.
+- Numbered examples, `examples/00_two_liner.py` to `examples/20_request_limit.py`, with an index.
+
+### Changed
+
+- The local gateway uses `aigw` v1.2.0 (was v1.1.0). Request limits need it: v1.1.0 is built on Envoy Gateway v1.8.1, whose rate-limit schema makes `aigw run` reject every `rateLimit` (`requests` declared int32 with a maximum of 4294967295); Envoy Gateway v1.9 fixed it.
+
+### Changed
+
+- The warning for `fallbacks` and `num_retries` now points to routes.
+
+## [0.1.0a1] - 2026-10-07
+
+### Added
+
+- `completion` and `acompletion` with LiteLLM's arguments, streaming and tool calls.
+- Direct calls with no gateway to OpenAI, Anthropic, Gemini, Groq, Mistral, DeepSeek and Together, using the key in the environment.
+- Anthropic Messages support: LiteLLM-style messages and tools are converted, and replies and streams are converted back.
+- Gateway mode: with `AGENTROUTER_BASE_URL` set, every call goes to that gateway in the OpenAI format.
+- Settings from `AGENTROUTER_HOME/config.json` when the environment does not set them.
+- LiteLLM's error names, mapped from provider HTTP errors.
+- `get_model_info`, `model_cost`, `completion_cost` and capability lookups, from a snapshot of tetrateio/agent-router-models.
+- `theagentrouter.compat.litellm` and `install_as_litellm()`, so Google ADK's `LiteLlm` class and the OpenAI Agents SDK's `LitellmModel` work without LiteLLM installed.
+- A warning, once per argument, when a LiteLLM-only argument such as `fallbacks` or `num_retries` is passed and ignored.
+- `usage.prompt_tokens_details`, `usage.completion_tokens_details`, `choice.logprobs`, `delta.refusal` and `model_copy()` on responses, as in LiteLLM.
+- Documentation: install, usage, coming from LiteLLM, and agent frameworks, under `docs/`.
+- The local gateway: `pip install "theagentrouter[local-gateway]"` installs Agent Router's `aigw` (package `theagentrouter-local-gateway`). The first call that needs it, such as a `bedrock/` model, starts it in the background with the providers whose keys are in the environment. While it runs, calls to its configured providers go through it, except direct-provider calls with an explicit `api_key`. `AGENTROUTER_AUTOSTART=0` turns starting off.
+
+### Fixed
+
+- An explicit provider `api_key` is honored even while the local gateway runs. Direct providers bypass it for that call.
+- Anthropic maps `parallel_tool_calls=False` to `disable_parallel_tool_use`. OpenAI-only parameters that cannot be translated raise `UnsupportedParamsError`; parameter discovery reports the supported set.
+- OpenAI responses retain refusal, reasoning, log probabilities and cached/reasoning token details, including streams.
+- Provider error events in streams raise the matching SDK exception with the requested model and provider.
+- Preparing a request leaves the caller's tool-call history unchanged.
+- Releases build, verify and publish the SDK and three companion wheels together. The companion uses checksum-pinned upstream binaries; required integration tests cannot silently skip.
+
+### Changed
+
+- A provider that needs a gateway now says how to install the local gateway, instead of only asking for `AGENTROUTER_BASE_URL`.
+- With a gateway set, a model name with no provider, such as `claude-sonnet-5`, goes to the gateway unchanged instead of being refused.
+- The local gateway receives the full `provider/model` name, as any gateway does, and routes it with one rule per model. No SDK-only header is sent.

theagentrouter_core-0.1.0a1/CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+Read [AGENTS.md](AGENTS.md): it holds the instructions for this repository, for every coding agent.
+
+Reminders that matter most:
+
+- `tests/test_surface.py` guards the public API. A failing surface test after an intended change means: run `python scripts/surface.py --write`, and explain the change.
+- Never add a reference to the Enterprise package (`tetrate-agentrouter` / `tetrate.agentrouter`) here; the open-source SDK must not know the Enterprise SDK exists.
+- The local gateway (`src/theagentrouter/local_gateway.py`, package in `local-gateway/`) has end-to-end tests that are skipped unless the package is installed. Before finishing a change to routing or the gateway, run `make local-gateway AIGW=/path/to/aigw`, then `pytest` — a skipped run proves nothing about the gateway. With keys in `.env`, also run `scripts/smoke_local_gateway.py`.
+- Never commit the `aigw` program (`local-gateway/src/theagentrouter_local_gateway/bin/`, git-ignored), and never write a key value into the gateway's config: it holds `${VAR}` references that `aigw` fills in from its environment.
+- Through the local gateway, the SDK sends the full `provider/model` name, as to any gateway; never add an SDK-only header. The gateway's config has one rule per model that passes the provider its own name, spread over routes of at most 15 rules (Gateway API's limit is 16 and `aigw` adds one). Anthropic goes in its own Messages format to `/anthropic/v1/messages`, because `aigw` does not translate OpenAI to Anthropic. Details in `docs/local-gateway.md`.

theagentrouter_core-0.1.0a1/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[TODO: add the Tetrate contact address before publishing].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.