Skip to content

Self-improving AI Employees for everyone

feat(gateway): add the hosted LiteLLM gateway, its local stack and CI

trohitgf5fe282939a4
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 5748fe9b..5616a044 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -56,6 +56,24 @@ updates:
ignore:
- dependency-name: "*"
+ # gateway/ holds the gateway's test dependencies (gateway/uv.lock); same
+ # pair of entries as server/, same manual policy.
+ - package-ecosystem: pip
+ directory: /gateway
+ schedule:
+ interval: monthly
+ open-pull-requests-limit: 0
+ ignore:
+ - dependency-name: "*"
+
+ - package-ecosystem: uv
+ directory: /gateway
+ schedule:
+ interval: monthly
+ open-pull-requests-limit: 0
+ ignore:
+ - dependency-name: "*"
+
- package-ecosystem: github-actions
directory: /
schedule:
diff --git a/.github/workflows/gateway-ci.yml b/.github/workflows/gateway-ci.yml
new file mode 100644
index 00000000..47a18b4b
--- /dev/null
+++ b/.github/workflows/gateway-ci.yml
@@ -0,0 +1,100 @@
+# OpenCompany Gateway (LiteLLM) checks: Terraform validity, image signatures,
+# the test dependencies, and the contract tests against a local LiteLLM stack
+# with mock models. Path-filtered, so it is not a required check.
+name: gateway-ci
+
+on:
+ pull_request:
+ paths:
+ - "gateway/**"
+ - "server/config/llm_defaults.json"
+ - ".github/workflows/gateway-ci.yml"
+ push:
+ branches: [main]
+ paths:
+ - "gateway/**"
+ - "server/config/llm_defaults.json"
+ - ".github/workflows/gateway-ci.yml"
+
+permissions:
+ contents: read
+
+concurrency:
+ group: gateway-ci-${{ github.ref }}
+ cancel-in-progress: true
+
+env:
+ # Keep in step with local.litellm_version in gateway/infra/terraform/main.tf
+ # and the image tag in gateway/local/docker-compose.yml (gateway/tests/test_pins.py checks).
+ LITELLM_VERSION: "1.103.4"
+ # Commit that introduced LiteLLM's image-signing key (docs: Docker image security).
+ LITELLM_COSIGN_KEY: https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub
+
+jobs:
+ terraform:
+ name: Terraform fmt and validate
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ - uses: hashicorp/setup-terraform@dfe3c3f87815947d99a8997f908cb6525fc44e9e # v4.0.1
+ with:
+ terraform_version: 1.14.8
+ terraform_wrapper: false
+ - run: terraform -chdir=gateway/infra/terraform fmt -check -recursive
+ - run: terraform -chdir=gateway/infra/terraform init -backend=false -input=false
+ - run: terraform -chdir=gateway/infra/terraform validate
+
+ image-signatures:
+ name: Verify LiteLLM image signatures
+ runs-on: ubuntu-latest
+ steps:
+ - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+ - name: cosign verify
+ run: |
+ for image in litellm litellm-gateway litellm-backend litellm-ui litellm-migrations; do
+ cosign verify --key "$LITELLM_COSIGN_KEY" "ghcr.io/berriai/${image}:v${LITELLM_VERSION}" > /dev/null
+ echo "verified ghcr.io/berriai/${image}:v${LITELLM_VERSION}"
+ done
+
+ dependencies:
+ name: Test dependencies locked and audited
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+ with:
+ enable-cache: false
+ - name: Lockfile is current
+ working-directory: gateway
+ run: uv lock --check
+ - name: Audit Python dependencies
+ working-directory: gateway
+ run: |
+ uv export --locked --no-hashes --no-emit-project --output-file "${RUNNER_TEMP}/gateway-audit.txt" > /dev/null
+ uvx --from pip-audit==2.10.1 pip-audit --strict --disable-pip --no-deps -r "${RUNNER_TEMP}/gateway-audit.txt"
+
+ contract:
+ name: Contract tests (local LiteLLM, mock models)
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+ with:
+ enable-cache: false
+ - name: Start the local gateway stack
+ run: docker compose -f gateway/local/docker-compose.yml up -d --wait --wait-timeout 300
+ - name: Run the contract and pin tests
+ run: uv run --locked --project gateway pytest gateway/tests -v
+ - name: Gateway logs
+ if: failure()
+ run: docker compose -f gateway/local/docker-compose.yml logs litellm
+ - name: Stop the stack
+ if: always()
+ run: docker compose -f gateway/local/docker-compose.yml down -v
diff --git a/.gitignore b/.gitignore
index 5e6c6784..5cba9f58 100644
--- a/.gitignore
+++ b/.gitignore
@@ -119,6 +119,7 @@ venv/
# app version gets the same dependency tree, and CI runs ``uv lock --check``.
uv.lock
!server/uv.lock
+!gateway/uv.lock
# server/requirements.txt is a pip export of server/uv.lock, made on demand
# (docs-internal/SETUP.md). A tracked copy drifts from the lock and gets its
# own Dependabot alerts, which never close.
@@ -195,6 +196,9 @@ cli/terraform/**/*.tfstate
cli/terraform/**/*.tfstate.*
cli/terraform/**/*.tfvars
cli/terraform/**/*.tfvars.json
+# Gateway state lives in S3; never commit a local copy
+gateway/infra/terraform/**/*.tfstate
+gateway/infra/terraform/**/*.tfstate.*
# =============================================================================
# Desktop shell (desktop/) — build outputs, staged bundle inputs, downloaded
diff --git a/CLAUDE.md b/CLAUDE.md
index 6568ef85..229ae60b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -51,6 +51,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Translate / Transliterate / Detect](./docs-internal/speech_provider_rfc.md#8-the-pattern-generalised-nodestranslate)** | The second application of the multi-vendor pattern, and the one that retired `nodes/sarvam/`. Three nodes (`translateText`, `transliterateText`, `detectLanguage`) in [`server/nodes/translate/`](./server/nodes/translate/), backed by **three registries — one per capability**, because the asymmetry is sharper than speech's: DeepL translates and does nothing else, while Sarvam and LLM-backed providers do all three. Membership makes an unsupported selection unrepresentable rather than a runtime failure inside a paid call. Providers: **deepl** (`Authorization: DeepL-Auth-Key`, `text` is an array, free keys ending `:fx` route to a different host, and it returns `billed_characters` so cost is the provider's own figure), **sarvam** (all three over dedicated REST), **openai** (all three via `ChatUnifier` — proves the Protocol does not care what a provider does internally; billing deliberately NOT recorded because that path bills tokens the LLM layer already costs). Capabilities in `server/config/translate_defaults.json`. |
| **[Desktop App](./docs-internal/desktop_app.md)** | Electron shell in [`desktop/`](./desktop/) — a standalone bun package (NOT a root workspace member; `cli/tests/test_release_pipeline_config.py` locks `workspaces`). Bundles pinned `uv`, python-build-standalone CPython 3.12 and bun 1.4.0 — the only JavaScript runtime shipped; no Node, no npm (`desktop/runtimes.json`, verified against upstream checksum manifests by `scripts/fetch-runtimes.ts`, which also fetches bun's `LICENSE.md` from the bun repo — the release zip carries none — and prunes stale runtime dirs such as a leftover `node/`), stages the backend sibling layout from `bun pm pack --dry-run` (`scripts/stage.ts`, which runs the sidecar package's own `bun run build` — `bun build --target=bun`, express inlined — and copies `dist/index.js`), sets `OPENCOMPANY_BUN_BIN` / `BUN_INSTALL=<userData>/bun` / `BUN_INSTALL_CACHE_DIR` and prepends the bundled bun dir (then uv) to PATH for the backend (`env.ts`; `OPENCOMPANY_NODE_BIN` no longer exists), provisions the venv into Electron `userData` on first launch with `uv sync --frozen --python <bundled>` (stamp = sha256 of uv.lock + pyproject + Python + uv versions; falls back to `uv python install 3.12`), pre-warms `PYTHONPYCACHEPREFIX` (with a prefix set Python ignores in-tree .pyc — 32 s vs 3 s first boot), spawns uvicorn on `127.0.0.1:5678` (persisted port; attaches to a running `company serve` instead of double-spawning), waits on `/health/ready`, loads the backend-served SPA (zero frontend changes), routes `window.open` / `_blank` to the OS browser. Quit = `POST /api/desktop/shutdown` + stdin EOF, 30 s, then tree-kill. electron-builder: NSIS x64, DMG+zip arm64/x64, AppImage+deb x64, unsigned first (`mac.identity: null`; macOS auto-update notify-only until signed — Squirrel.Mac refuses unsigned). CI: `desktop-release.yml` (tag-triggered: `prepare` drafts the GitHub Release from the annotated tag's message, three legs build and upload version-less OS-named installers such as `OpenCompany-windows-x64.exe` / `OpenCompany-macos-arm64.dmg` / `OpenCompany-linux-x86_64.AppImage` so the README can link `releases/latest/download/<file>`, each leg refuses a desktop version that differs from the tag, `finalize` undrafts) and `desktop-ci.yml` (typecheck/unit/invariants/Playwright smoke). **Gotcha: editor-hosted terminals export `ELECTRON_RUN_AS_NODE=1`, which makes Electron boot as plain Node (`electron.app` undefined) — strip it before launching; the e2e test does.** |
| **[Desktop Host Contract](./docs-internal/desktop_host_contract.md)** | The backend's side of being owned by a GUI shell. `core/approot.py` is the ONE module that locates the app tree (`OPENCOMPANY_APP_ROOT` / `OPENCOMPANY_CLIENT_DIST` / `OPENCOMPANY_ENV_FILE` / `OPENCOMPANY_ENV_TEMPLATE`); `tests/test_no_root_climb.py` forbids any other `Path(__file__).parents[N]` climb above `server/` and any `"client"/"dist"` / `.env.template` / `package.json` path join. `core/env_defaults.apply_file_defaults_to_environ()` does the CLI's `.env.template < .env < process env` layering at the top of `main.py`, and `Settings.env_file` is the absolute `(template, .env)` tuple — so a shell spawns `python -m uvicorn` from any cwd without the CLI package. Desktop mode (`OPENCOMPANY_DESKTOP=1`, `core/desktop.py`): parent-PID watchdog with create-time PID-reuse guard, stdin-EOF watchdog (polling via `PeekNamedPipe`/`select`, never a blocking read — a daemon thread parked in `ReadFile` at finalisation crashed exit with 0xC0000005), ctypes Job Object so children die with the backend (no pywin32 in the server venv), token-gated `POST /api/desktop/shutdown` (`routers/desktop.py`, public path; raises the signal uvicorn handles so the lifespan reaps Temporal/the bun sidecar/edgymeow), 45 s hard deadline. `GET /health/ready` (public) = DB up AND (Temporal disabled OR worker manager started), with `phase` written by `services/temporal/lifecycle.py` (`installing_temporal` / `starting_temporal` / `connecting` / `starting_workers` / `ready`). Plugin shutdown hooks now run under a 10 s per-hook timeout (`HOOK_TIMEOUT_SECONDS`), and the current browser hook uses `peek_browser_runtime()` so shutdown never constructs or installs the runtime. Historical incident: the retired `get_browser_service()` lazily installed agent-browser at shutdown and wedged graceful exit (masked under the CLI by its 5 s grace + tree-kill). `server/uv.lock` is committed; `predeploy.yml` runs `uv lock --check`. |
+| **[LLM Gateway](./docs-internal/llm_gateway.md)** | Hosted LiteLLM Proxy in `gateway/` (official AWS module, mock-model local stack, contract and pin tests, `gateway-ci.yml`): pinned LiteLLM 1.103.4 and price list, served providers, and the contract OpenCompany relies on (wire model names, `budget_exceeded` refusals, `/user/info` allowance with Default keys, attribution headers, cache replay). Operator runbook: `gateway/README.md`. OpenCompany-side routing not implemented yet. |
| **[CI/CD Pipeline](./docs-internal/ci_cd.md)** | GitHub Actions workflows, predeploy validation, release publishing, and the composite setup action (bun via SHA-pinned `oven-sh/setup-bun` reading the root `packageManager` pin + Node 22 as a CI-only convenience so bun runs vite / vitest / eslint on it via their node shebangs + Python 3.12 + uv; `bun install --frozen-lockfile` everywhere; publish is `bun publish --access public` after a `bun pm whoami` credential preflight with `~/.npmrc` written from `NPM_TOKEN` — no npm CLI, no `setup-node` step of their own in the publish jobs (they get Node through the composite action), and npm provenance attestation went away with npm). Also **Cutting a release**: the annotated tag is the version and its message is the release notes; `company version sync vX.Y.Z` bumps every version file for the `chore(release)` commit the tag sits on, and `desktop-release.yml` drafts the GitHub Release from the tag message and refuses a version that differs from the tag |
| **[Performance](./docs-internal/performance.md)** | Cold-start measurements (Application startup complete 2.90 s warm, 21.5 s cold post-`company clean` — was 71 s before the 2026-07-14 boot-delay fixes; first WS connect 8.29 s) + warm and cold per-phase timelines + optimisation history (lazy LangChain imports, lazy LLM-SDK exception refs, pre-bundled sidecar (esbuild at the time, `bun build --target=bun` today), bytecode-at-build, PartySocket reconnect, TanStack Query auth bootstrap, `manualChunks`, Vite dep-cache preservation, off-loop Temporal build-id hash) + bottleneck inventory + reproduction commands + anti-patterns to never reintroduce (incl. eager SDK import at LLM provider registration, unconditional `.vite` wipe, synchronous `Worker()` on the event loop). Pairs with the build-time pipeline doc below. |
| **[Release Build Pipeline](./docs-internal/release_build_pipeline.md)** | Build pipeline for the registry tarball (installed with `bun add -g`; bun is the only JavaScript runtime and package manager anything shipped needs): `typescript@7` (native Go compiler, exact-pinned in **root** devDependencies — client keeps `typescript@^5.x` because typescript-eslint's peer range excludes 6/7, and one manifest cannot declare `typescript` twice) for type-check, measured 5.9× faster than tsc 5.9.3 (820 ms vs 4830 ms); `bun run --filter react-flow-client typecheck` delegates up to the root gate, Vite `manualChunks` + `target: 'es2022'`, `bun build --target=bun` sidecar bundle (self-contained `dist/index.js` with express inlined, run as `bun dist/index.js`; drops the `tsx` interpreter cost and needs no `node_modules` at runtime), bytecode pre-compile in two halves — `[tool.uv] compile-bytecode = true` (uv sync compiles `.venv/` site-packages) + `python -m compileall` for project source (plain `.pyc`, **no `-O`** — per PEP 488 the non-`-O` runtimes never load `.opt-1.pyc`; excludes `.venv/`, `tests/`). Single source of truth for the bytecode-compile path list: `cli.commands.build.COMPILEALL_SOURCE_DIRS`. Dev PM is **[email protected]** (tracked text `bun.lock`, `bunfig.toml` pins the isolated linker, ranged security pins in top-level `overrides`); `company build` step [1/6] is `bun install`. |
diff --git a/docs-internal/ci_cd.md b/docs-internal/ci_cd.md
index ea7e94da..bb742f5e 100644
--- a/docs-internal/ci_cd.md
+++ b/docs-internal/ci_cd.md
@@ -2,7 +2,7 @@
Internal reference for OpenCompany's GitHub Actions setup. Workflow inventory, release flow, and the composite setup action.
-The repo currently ships **five workflows** plus one composite action. Code scanning is live but has no workflow file: it runs through GitHub's **default CodeQL setup**, which is why alerts land in the Security tab with nothing in `.github/workflows/` to point at (see [Code scanning](#code-scanning)). The other hardening workflows described in earlier revisions of this doc (zizmor, rollback, reusable PyPI publish, cross-platform test-install) are **not yet implemented** — see [Planned (not yet implemented)](#planned-not-yet-implemented) at the end.
+The repo currently ships **six workflows** plus one composite action. Code scanning is live but has no workflow file: it runs through GitHub's **default CodeQL setup**, which is why alerts land in the Security tab with nothing in `.github/workflows/` to point at (see [Code scanning](#code-scanning)). The other hardening workflows described in earlier revisions of this doc (zizmor, rollback, reusable PyPI publish, cross-platform test-install) are **not yet implemented** — see [Planned (not yet implemented)](#planned-not-yet-implemented) at the end.
---
@@ -25,6 +25,10 @@ The repo currently ships **five workflows** plus one composite action. Code scan
| +---------------------+
+-- publish-npm
+-- publish-github-packages
+
+ PR / push to main touching ------> +------------------+ terraform, image-signatures,
+ gateway/** or llm_defaults.json | gateway-ci.yml | dependencies, contract
+ +------------------+
```
> Documentation is NOT deployed from this repo: the Mintlify docs live in
@@ -41,6 +45,7 @@ The repo currently ships **five workflows** plus one composite action. Code scan
| Release | `.github/workflows/release.yml` | `v*.*.*` tag, `workflow_dispatch` | predeploy gate → publish (npm + GitHub Packages) |
| Desktop CI | `.github/workflows/desktop-ci.yml` | PR touching `desktop/**` or the backend host-contract files; push to main touching `desktop/**` | typecheck + unit + staged-tree invariants + `electron-vite build` + Playwright Electron smoke on ubuntu-22.04 (xvfb) and windows-latest |
| Desktop release | `.github/workflows/desktop-release.yml` | `v*.*.*` tag, `workflow_dispatch` | `prepare` drafts the GitHub Release from the annotated tag's message (first line = title, rest = notes); a 3-runner matrix (windows-latest x64, macos-14 arm64+x64, ubuntu-22.04 x64) checks the synced version against the tag, builds installers with electron-builder and uploads into that one **draft**; `finalize` undrafts once every leg is green. Artifacts-only on dispatch unless `publish` is ticked |
+| Gateway CI | `.github/workflows/gateway-ci.yml` | PR / push to main touching `gateway/**`, `server/config/llm_defaults.json` or the workflow | The LiteLLM gateway ([LLM Gateway](./llm_gateway.md)): `terraform fmt`/`validate` with Terraform 1.14.8, cosign verification of the pinned LiteLLM images, `uv lock --check` and pip-audit for `gateway/uv.lock`, then the contract and pin tests against the local mock stack. Path-filtered, so it is not a required check |
| Setup | `.github/actions/setup/action.yml` | (composite) | bun 1.4 + Node 22 (CI-only: bun runs vite / vitest / eslint on it) + Python 3.12 + uv v8 + editable CLI install |
### Toolchain pin
@@ -202,6 +207,7 @@ folder — both the folder and the workflow are gone.
| `.github/workflows/release.yml` | Tag / manual release: predeploy gate → publish npm + GitHub Packages |
| `.github/workflows/desktop-ci.yml` | Desktop shell checks on PRs: typecheck, unit, invariants, build, Playwright smoke |
| `.github/workflows/desktop-release.yml` | Tag-triggered desktop installers (NSIS / DMG+zip / AppImage+deb) into a draft release, then undraft. Separate from `release.yml` so npm publish is never blocked |
+| `.github/workflows/gateway-ci.yml` | LiteLLM gateway checks: Terraform, image signatures, locked and audited test dependencies, contract and pin tests |
| `.github/actions/setup/action.yml` | Composite: bun + Node + Python + uv + editable CLI install |
| `.github/dependabot.yml` | **Manual dependency updates** — scheduled PRs suppressed; automatic security-update attempts also require the repository setting to be disabled; see below |
| `.python-version` | Toolchain pin (`3.12`) — single source of truth |
@@ -270,7 +276,9 @@ repository setting described below. Dependencies move by hand with tests:
`overrides` block in the root manifest for transitive pins), `bun install`,
`bun run audit:deps` (at the root and in `desktop/`), run the suites.
- pip: `uv lock --upgrade-package <name>` in `server/`, `uv sync`, run the
- suites (`predeploy.yml` runs `uv lock --check` and the audit below).
+ suites (`predeploy.yml` runs `uv lock --check` and the audit below). The
+ gateway's test dependencies (`gateway/uv.lock`) move the same way, in
+ `gateway/`; `gateway-ci.yml` runs the same lock check and audit.
The Python gate exports exact pins from `uv.lock` without installing optional
extras. `pip-audit==2.10.1` queries advisories with `--strict --disable-pip
@@ -287,8 +295,8 @@ On Windows, use a file under `$env:TEMP` in both commands. Advisory lookup
requires network access; Python markers select the current platform, so the
Ubuntu CI audit also covers Linux-only dependencies.
-The five entries (`bun /`, `bun /desktop`, `pip /server`, `uv /server`,
-`github-actions /`) declare the intended updaters; they do not guarantee
+The seven entries (`bun /`, `bun /desktop`, `pip /server`, `uv /server`,
+`pip /gateway`, `uv /gateway`, `github-actions /`) declare the intended updaters; they do not guarantee
the ecosystem chosen for alert-triggered jobs. The
[2026-10-06 Sharp update attempt](https://github.com/zeenie-ai/OpenCompany/actions/runs/37474349729)
selected `npm_and_yarn` for `/desktop`, with no ignore conditions, despite
diff --git a/docs-internal/llm_gateway.md b/docs-internal/llm_gateway.md
new file mode 100644
index 00000000..6015494f
--- /dev/null
+++ b/docs-internal/llm_gateway.md
@@ -0,0 +1,43 @@
+# LLM Gateway (LiteLLM)
+
+OpenCompany's hosted LLM gateway is the stock open-source LiteLLM Proxy, deployed from `gateway/` with BerriAI's official Terraform module. Invited people call LLMs on platform-owned vendor keys, each with a monthly allowance, and spend is recorded per person and per session. The repository holds only configuration and tests; there is no custom gateway code. The operator runbook (deployment, adding people, upgrades) is [gateway/README.md](../gateway/README.md).
+
+**Status:** the gateway (Phase 0) is in `gateway/`. The OpenCompany side (routing, the Connectors entry, attribution headers) is not implemented yet; the contract below is what it will rely on, and `gateway/tests/test_gateway_contract.py` pins each part of it against the local stack.
+
+## Layout
+
+| Path | Contents |
+|---|---|
+| `gateway/litellm/config.yaml` | Production proxy config: provider wildcards, budget defaults, unpriced-model refusal, opt-in Redis cache, spend-log retention |
+| `gateway/local/` | Local stack: Postgres 16, Redis 7, LiteLLM with mock models, and `fake_anthropic.py`, a real upstream event stream for streamed-pricing tests |
+| `gateway/tests/test_gateway_contract.py` | Contract tests against the local stack (skipped when it isn't running) |
+| `gateway/tests/test_pins.py` | Offline checks: version and price-list pins agree; every served default model is priced |
+| `gateway/infra/terraform/` | Wrapper around `BerriAI/litellm/aws`: ECS Fargate, Aurora Postgres (IAM auth), ElastiCache, ALB, ACM, Route 53 records in the delegated `gw.opencompany.sh` zone |
+| `.github/workflows/gateway-ci.yml` | Terraform checks, cosign verification of the pinned images, locked and audited test dependencies, contract and pin tests |
+
+## Pins
+
+- **LiteLLM 1.103.4**, in four places that `test_pins.py` keeps in agreement: `local.litellm_version` and the module `version` in `main.tf`, the compose image tag, and `LITELLM_VERSION` in CI. 1.103.x is the only stable line with the streamed-alias billing fix (LiteLLM PR #44341).
+- **The price list**: `LITELLM_MODEL_COST_MAP_URL` points at one reviewed commit of LiteLLM's `model_prices_and_context_window.json`, in `main.tf` and the compose file. Unpinned, the gateway downloads upstream `main` at every start, so prices would change unannounced; the list bundled with 1.103.4 predates `gpt-6-sol` and the Claude 5.5 models. `GET /model/cost_map/source` shows the list a process loaded (on the deployed stack it is routed to the backend service, not the gateway tasks).
+
+## Served providers
+
+OpenAI, Anthropic, Gemini, Groq, Cerebras, xAI, Moonshot (OpenCompany's `kimi`) and Mistral for chat; OpenAI and Groq speech; OpenAI embeddings. `test_pins.py` lists them as `SERVED_PROVIDERS` and checks each default model in `server/config/llm_defaults.json` against the pinned list.
+
+Not served: OpenRouter, DeepSeek and Sarvam (no price for their default models), ElevenLabs and Deepgram (OpenCompany speaks their native formats), and every tool API.
+
+## Contract OpenCompany relies on
+
+| Behaviour | Detail | Test |
+|---|---|---|
+| Wire model names | OpenAI-format calls use `<litellm prefix>/<model>` on `/v1` (`openai/`, `groq/`, `cerebras/`, `xai/`, `moonshot/`, `mistral/`). Anthropic SDK calls send bare `claude-*` ids to `/v1/messages`; Gemini SDK calls use the native `/v1beta/models/<id>:generateContent` route with the key in `x-goog-api-key` | `test_anthropic_messages_route_accepts_bare_model_ids`, `test_gemini_native_route_accepts_virtual_key` |
+| Spent allowance | Refused with error type `budget_exceeded` on all three routes; HTTP 429 on 1.103.x, 402 from 1.104. Recognise it by type | `test_budget_refusal_is_typed_on_every_route` |
+| Unpriced model | HTTP 403, error type `model_cost_map_missing` | `test_unpriced_model_is_refused` |
+| Allowance | `GET /user/info` with the person's key returns `user_info.spend`, `max_budget` and `budget_reset_at`. Needs a Default-type key; LLM-API keys are refused; another user's id is refused | `test_user_info_needs_a_default_key_and_stays_scoped` |
+| Attribution | `x-litellm-session-id`, `x-litellm-tags` (comma-separated, low cardinality: `workflow:`, `source:`, `user:`) and `x-litellm-spend-logs-metadata` (JSON) land on the spend row, queryable with `/spend/logs/v2?session_id=` | `test_attribution_headers_reach_spend_logs` |
+| Retry replay | Request body `cache: {"use-cache": true, "namespace": <stable per activity>, "ttl": 172800}` (OpenAI format through `extra_body`). A repeated call with the same namespace is a cache hit billed at $0, streamed or not, on `/v1/chat/completions` and `/v1/messages` | `test_cache_namespace_replays_retry_for_free`, `test_streamed_retry_replays_for_free`, `test_anthropic_messages_cache_namespace` |
+| Streamed pricing | A real upstream stream through a dotted alias is billed at the deployment's price | `test_streamed_alias_is_priced_at_the_deployment` |
+
+## Keys
+
+People create one Default-type key per install in the console. A key draws on its person's monthly allowance, and LiteLLM reserves the worst-case cost of each call in Redis before admitting it, so a request with a large `max_tokens` can be refused near the cap. A Default key can also create and delete that person's own keys (not raise the allowance); a leaked key is revoked in the console.
diff --git a/gateway/README.md b/gateway/README.md
new file mode 100644
index 00000000..c7aa435c
--- /dev/null
+++ b/gateway/README.md
@@ -0,0 +1,112 @@
+# OpenCompany Gateway
+
+The hosted LLM gateway for OpenCompany: invited people use LLMs on platform-owned vendor keys, each with a monthly allowance, and spend is tracked per person and per session. It is the stock [LiteLLM Proxy](https://docs.litellm.ai/docs/) deployed with BerriAI's official Terraform module. Everything in this folder is configuration and tests; there is no custom gateway code.
+
+| What | Where |
+|---|---|
+| Proxy config (models, budgets, cache) | [litellm/config.yaml](litellm/config.yaml) |
+| AWS deployment (ECS Fargate, Aurora Postgres, ElastiCache, ALB) | [infra/terraform/](infra/terraform/) |
+| Local stack with mock models | [local/](local/) |
+| Contract and pin tests | [tests/](tests/) |
+| CI | [.github/workflows/gateway-ci.yml](../.github/workflows/gateway-ci.yml) |
+| How OpenCompany uses it | [docs-internal/llm_gateway.md](../docs-internal/llm_gateway.md) |
+
+## How it works
+
+- **People** are LiteLLM internal users. Each has a monthly USD allowance (`max_budget` with `budget_duration: 1mo`, reset on the 1st, UTC).
+- **Keys**: each person creates one **Default**-type key per OpenCompany install in the console and pastes it into Connectors. Every key of a person draws on the same allowance. OpenCompany needs a Default key to show the allowance: LLM-API keys can't read `/user/info`.
+- **Budgets** are checked before every call: LiteLLM reserves the worst-case cost in Redis, then settles the real cost. A spent allowance is refused with error type `budget_exceeded` (HTTP 429 on 1.103.x; 402 from 1.104, set by `budget_exceeded_status_code`). OpenCompany reads the type, not the status.
+- **Prices** come from a pinned copy of LiteLLM's price list (`LITELLM_MODEL_COST_MAP_URL`). A model without a price is refused (HTTP 403, `model_cost_map_missing`) rather than billed at $0.
+- **Attribution**: OpenCompany sends `x-litellm-session-id`, `x-litellm-tags` and `x-litellm-spend-logs-metadata`, so spend shows per person, per run and per workflow.
+- **Retries**: OpenCompany sends an opt-in cache namespace on Temporal LLM steps (`cache: {"use-cache": true, "namespace": ...}`), so a retried call replays from Redis at $0.
+
+## Served providers
+
+| Kind | Providers |
+|---|---|
+| Chat | OpenAI, Anthropic, Gemini, Groq, Cerebras, xAI, Moonshot (Kimi), Mistral |
+| Speech | OpenAI (speech and transcription), Groq (transcription) |
+| Embeddings | OpenAI |
+
+Not served: OpenRouter, DeepSeek and Sarvam (their default models have no price in the list), ElevenLabs and Deepgram (OpenCompany uses their native formats), and every tool API (Brave, Serper, TikHub, Google Maps, Perplexity, DeepL, Apify and the rest). Those stay on each install's own keys.
+
+To serve another provider: add its secret name to `secret_env_names`, its wildcard to `litellm/config.yaml`, and its OpenCompany provider id to `SERVED_PROVIDERS` in `tests/test_pins.py` (which checks its default model is priced), then apply.
+
+## Local stack and tests
+
+Needs Docker. Mock models plus a fake Anthropic upstream ([local/fake_anthropic.py](local/fake_anthropic.py)) for streamed calls: nothing is billed and no vendor key is needed.
+
+```bash
+docker compose -f gateway/local/docker-compose.yml up -d --wait
+uv run --project gateway pytest gateway/tests -v
+docker compose -f gateway/local/docker-compose.yml down -v
+```
+
+`tests/test_pins.py` needs no stack: it checks that the version and price-list pins agree across files, and that every served provider's default model is priced. The console runs at http://127.0.0.1:4000/ui (user `admin`, password `sk-local-master-key`).
+
+## First deployment
+
+Prerequisites: AWS credentials for the target account, an S3 bucket for Terraform state (fill `REPLACE_WITH_STATE_BUCKET` in `infra/terraform/envs/<env>.backend.hcl`), Terraform 1.14, and the `aws` CLI (the module runs the database bootstrap and migrations through it).
+
+1. **DNS, once for both environments.** `opencompany.sh` is on Cloudflare, so delegate a subzone to Route 53:
+
+ ```bash
+ aws route53 create-hosted-zone --name gw.opencompany.sh --caller-reference "gw-$(date +%s)"
+ ```
+
+ Add the four NS records it returns in Cloudflare as `gw` NS records (DNS only). Wait until `dig NS gw.opencompany.sh +short` returns them, then put the zone id in `infra/terraform/envs/<env>.tfvars` (`REPLACE_WITH_GW_ZONE_ID`). Hostnames: `api.gw.opencompany.sh` (prod) and `staging.gw.opencompany.sh`.
+
+2. **Secrets.** Create the empty secrets, then fill every one, including `SLACK_WEBHOOK_URL`: ECS tasks only start once each secret has a value.
+
+ ```bash
+ cd gateway/infra/terraform
+ terraform init -backend-config=envs/staging.backend.hcl
+ terraform apply -var-file=envs/staging.tfvars -target=aws_secretsmanager_secret.vendor
+ aws secretsmanager put-secret-value --secret-id opencompany-gateway-staging/env/openai-api-key --secret-string 'sk-...'
+ ```
+
+3. **Full apply.** `terraform apply -var-file=envs/staging.tfvars`. The module bootstraps the database and runs the migrations before the services start.
+
+4. **SpendLogs indexes, once.** LiteLLM no longer creates them in migrations (1.103.3+). Run the command from `terraform output -raw spendlogs_index_command`; it reuses the module's bootstrap task with the index SQL.
+
+5. **Price list check.** Call a current model through the gateway, for example `gpt-6-sol`. A 403 `model_cost_map_missing` means the task couldn't fetch the pinned price list at start and fell back to LiteLLM's bundled one: check the task logs, then restart the service.
+
+6. **Admin access.**
+ 1. Read the master key from the `master_key_secret_arn` output and sign in to `<gateway_url>/ui` as `admin` with it.
+ 2. Create named admin accounts (Internal Users, role Admin) and sign in with one.
+ 3. Set `disable_env_credential_login: true` in `general_settings` and apply, so the master key no longer opens the console.
+
+## Adding a person
+
+1. In the console, create an internal user (or `POST /user/new`) with their monthly `max_budget`. New people default to `max_internal_user_budget` ($50).
+2. Create an invitation (`POST /invitation/new`). Send them the link yourself: email delivery is an Enterprise feature. Links expire after 7 days.
+3. They set a password, open **Virtual Keys**, and create one key per install with the **Default** key type (the console's default). They paste it into OpenCompany's Connectors panel.
+
+Avoid team keys: they skip the person's allowance unless `apply_user_budget_to_team_keys` is set.
+
+## Upgrades
+
+LiteLLM ships a minor release every week and supports only the latest four minor lines, so upgrade every 2-4 weeks. Apply security releases within 72 hours ([advisories](https://github.com/BerriAI/litellm/security/advisories)).
+
+1. Bump the version together in `local.litellm_version` and the module `version` (`infra/terraform/main.tf`), the image tag in `local/docker-compose.yml`, and `LITELLM_VERSION` in the CI workflow. `tests/test_pins.py` fails if they disagree.
+2. To move the price list, pick a reviewed commit of `model_prices_and_context_window.json` and change `LITELLM_MODEL_COST_MAP_URL` in both `main.tf` and `local/docker-compose.yml`.
+3. Open a PR: CI verifies the image signatures and runs the contract and pin tests on the new version.
+4. Take an Aurora snapshot, then apply to staging. The module runs the database migration before the services roll.
+5. Smoke-test staging with a real cheap model per served provider, then apply to prod.
+
+Why 1.103.x: it is the only stable line with the streamed-alias billing fix (LiteLLM PR #44341, also in 1.106.0-dev). `test_streamed_alias_is_priced_at_the_deployment` guards streamed pricing through an alias on every upgrade. Moving to 1.104 or later also turns budget refusals into 402 (`budget_exceeded_status_code`).
+
+## Operating notes
+
+- **Alerts** go to Slack (`SLACK_WEBHOOK_URL`): budget thresholds, outages, database errors.
+- **Spend logs** are kept for 90 days (`maximum_spend_logs_retention_period`); the daily rollups that drive the usage views are kept.
+- **Redis** must never evict keys: evictions silently drop budget and rate-limit state. The module's ElastiCache cluster has a replica with automatic failover.
+- **The salt key** (`LITELLM_SALT_KEY`) encrypts credentials stored in the database and can never change. Terraform generates it once and ignores later changes.
+- **The price list** is fetched when a task starts. If GitHub is unreachable then, LiteLLM serves its bundled list (which refuses newer models) and retries in the background.
+- **Rust**: LiteLLM's Rust path is beta and opt-in per model. To trial it, set `rust: true` on the Anthropic models in staging, confirm responses carry `x-litellm-rust: true` and spend logs are unchanged, then promote. The standalone Rust gateway is not production-ready yet.
+
+## Known limits
+
+- Replay covers completed LLM calls only; an abandoned stream is billed for what it produced.
+- A Default key can create and delete that person's own keys, but not raise their allowance. Revoke a leaked key in the console.
+- The open-source tier has no SSO beyond 5 users, no audit log, no automatic key rotation, and no route permissions for tool pass-through. Those need a LiteLLM Enterprise license.
diff --git a/gateway/infra/terraform/.terraform.lock.hcl b/gateway/infra/terraform/.terraform.lock.hcl
new file mode 100644
index 00000000..e0d367c8
--- /dev/null
+++ b/gateway/infra/terraform/.terraform.lock.hcl
@@ -0,0 +1,54 @@
+# This file is maintained automatically by "terraform init".
+# Manual edits may be lost in future updates.
+
+provider "registry.terraform.io/hashicorp/aws" {
+ version = "5.100.0"
+ constraints = "~> 5.60, ~> 5.92"
+ hashes = [
+ "h1:H3mU/7URhP0uCRGK8jeQRKxx2XFzEqLiOq/L2Bbiaxs=",
+ "h1:Ijt7pOlB7Tr7maGQIqtsLFbl7pSMIj06TVdkoSBcYOw=",
+ "h1:edXOJWE4ORX8Fm+dpVpICzMZJat4AX0VRCAy/xkcOc0=",
+ "h1:hd45qFU5cFuJMpFGdUniU9mVIr5LYVWP1uMeunBpYYs=",
+ "h1:wOhTPz6apLBuF7/FYZuCoXRK/MLgrNprZ3vXmq83g5k=",
+ "zh:054b8dd49f0549c9a7cc27d159e45327b7b65cf404da5e5a20da154b90b8a644",
+ "zh:0b97bf8d5e03d15d83cc40b0530a1f84b459354939ba6f135a0086c20ebbe6b2",
+ "zh:1589a2266af699cbd5d80737a0fe02e54ec9cf2ca54e7e00ac51c7359056f274",
+ "zh:6330766f1d85f01ae6ea90d1b214b8b74cc8c1badc4696b165b36ddd4cc15f7b",
+ "zh:7c8c2e30d8e55291b86fcb64bdf6c25489d538688545eb48fd74ad622e5d3862",
+ "zh:99b1003bd9bd32ee323544da897148f46a527f622dc3971af63ea3e251596342",
+ "zh:9b12af85486a96aedd8d7984b0ff811a4b42e3d88dad1a3fb4c0b580d04fa425",
+ "zh:9f8b909d3ec50ade83c8062290378b1ec553edef6a447c56dadc01a99f4eaa93",
+ "zh:aaef921ff9aabaf8b1869a86d692ebd24fbd4e12c21205034bb679b9caf883a2",
+ "zh:ac882313207aba00dd5a76dbd572a0ddc818bb9cbf5c9d61b28fe30efaec951e",
+ "zh:bb64e8aff37becab373a1a0cc1080990785304141af42ed6aa3dd4913b000421",
+ "zh:dfe495f6621df5540d9c92ad40b8067376350b005c637ea6efac5dc15028add4",
+ "zh:f0ddf0eaf052766cfe09dea8200a946519f653c384ab4336e2a4a64fdd6310e9",
+ "zh:f1b7e684f4c7ae1eed272b6de7d2049bb87a0275cb04dbb7cda6636f600699c9",
+ "zh:ff461571e3f233699bf690db319dfe46aec75e58726636a0d97dd9ac6e32fb70",
+ ]
+}
+
+provider "registry.terraform.io/hashicorp/random" {
+ version = "3.9.1"
+ constraints = "~> 3.6"
+ hashes = [
+ "h1:7uiStw0Rl9KOdX5UNMG/sp9nyadoD4LZekQTiYlYPhE=",
+ "h1:PYbnOqRuGn4c0/Ae1f7yOS/0zvmXNHFJRZjuF4KECnM=",
+ "h1:PlW+UZ4EElQF3NQwf41KQwavFujab3Czc51zu9dyVM8=",
+ "h1:g40qr7yDmIpaur4SsK5BcOda3HSo1RJ6zHVMqN4EJ+0=",
+ "h1:nozfr4CZq73d4HjubKJundX/8A+Mj282oS/hyNfjUPU=",
+ "zh:05f4734c1f0be840b711b3eff259ebc5fca436784c728955b1678078466f48d7",
+ "zh:0b91bf19371d012434eba1deeb6aab77158def9b39601dcbd94450b3974a2a26",
+ "zh:0ee6eacd47ec00183d55d726a4b6c4ce951a199f944bf22f1aa58392ebdfa7a2",
+ "zh:19388a4074b76a89a43a6c8328d7ae8ee2e7de3d346af51e80d3e6d3d12925f1",
+ "zh:23e74d48c5e2ac2e823fd527f49fee9db37d32a1990c9e3bf126ead697b843eb",
+ "zh:3cabf7fbd096c520064aae3aba61aba670af83ab91291a71fa1b1332929c2b7f",
+ "zh:5c0a3b8af0be60be4eca12ddee385cfa8babc1ec8e98cdf9de2f2274c73eabfa",
+ "zh:60b4f8a8ef18f52bf8e19215229dae408bee732825964092db7c989fd2de4097",
+ "zh:7359015acfedcbd6366f2329c854cf8d3c8ca5cd0faa89d2d37db358d6eba6c5",
+ "zh:78d5eefdd9e494defcb3c68d282b8f96630502cac21d1ea161f53cfe9bb483b3",
+ "zh:7b38758402f0e13a1071162da28994023cd2ac676e54af350c9ffd8dfa73fa7b",
+ "zh:7c7fbb8895eb75bb4de1f933e98553bd99c8d048c89a925ddba490aa5a67f7dc",
+ "zh:8c2b8c6a7ccdec16b73e2fb9f3700ea097f58c592571e4c5de60c93d2301732c",
+ ]
+}
diff --git a/gateway/infra/terraform/envs/prod.backend.hcl b/gateway/infra/terraform/envs/prod.backend.hcl
new file mode 100644
index 00000000..40229c3e
--- /dev/null
+++ b/gateway/infra/terraform/envs/prod.backend.hcl
@@ -0,0 +1,5 @@
+bucket = "REPLACE_WITH_STATE_BUCKET"
+key = "opencompany-gateway/prod/terraform.tfstate"
+region = "us-east-1"
+encrypt = true
+use_lockfile = true
diff --git a/gateway/infra/terraform/envs/prod.tfvars b/gateway/infra/terraform/envs/prod.tfvars
new file mode 100644
index 00000000..01e165a1
--- /dev/null
+++ b/gateway/infra/terraform/envs/prod.tfvars
@@ -0,0 +1,5 @@
+env = "prod"
+gateway_hostname = "api.gw.opencompany.sh"
+route53_zone_id = "REPLACE_WITH_GW_ZONE_ID" # gw.opencompany.sh
+gateway_min_tasks = 2
+gateway_max_tasks = 10
diff --git a/gateway/infra/terraform/envs/staging.backend.hcl b/gateway/infra/terraform/envs/staging.backend.hcl
new file mode 100644
index 00000000..964a31cf
--- /dev/null
+++ b/gateway/infra/terraform/envs/staging.backend.hcl
@@ -0,0 +1,5 @@
+bucket = "REPLACE_WITH_STATE_BUCKET"
+key = "opencompany-gateway/staging/terraform.tfstate"
+region = "us-east-1"
+encrypt = true
+use_lockfile = true
diff --git a/gateway/infra/terraform/envs/staging.tfvars b/gateway/infra/terraform/envs/staging.tfvars
new file mode 100644
index 00000000..f90f5185
--- /dev/null
+++ b/gateway/infra/terraform/envs/staging.tfvars
@@ -0,0 +1,5 @@
+env = "staging"
+gateway_hostname = "staging.gw.opencompany.sh"
+route53_zone_id = "REPLACE_WITH_GW_ZONE_ID" # gw.opencompany.sh
+gateway_min_tasks = 1
+gateway_max_tasks = 3
diff --git a/gateway/infra/terraform/main.tf b/gateway/infra/terraform/main.tf
new file mode 100644
index 00000000..384425d5
--- /dev/null
+++ b/gateway/infra/terraform/main.tf
@@ -0,0 +1,142 @@
+# OpenCompany Gateway: BerriAI's official LiteLLM module on ECS Fargate, plus
+# the few things the module leaves to the caller (TLS certificate, DNS record,
+# the salt key, and the vendor-key secrets).
+
+locals {
+ # Keep in step with the module version below, the image tag in
+ # gateway/local/docker-compose.yml and LITELLM_VERSION in the CI workflow
+ # (gateway/tests/test_pins.py checks). 1.103.x is the only stable line with
+ # the streamed-alias billing fix (LiteLLM PR #44341).
+ litellm_version = "1.103.4"
+ name = "opencompany-gateway-${var.env}"
+
+ common_env = {
+ LITELLM_MODE = "PRODUCTION"
+ LITELLM_LOG = "ERROR"
+ PROXY_BASE_URL = "https://${var.gateway_hostname}"
+ NO_DOCS = "True"
+ NO_REDOC = "True"
+ NO_OPENAPI = "True"
+ # Prices come from this reviewed copy of LiteLLM's price list. Without it
+ # the gateway downloads upstream main on every start (prices change
+ # unannounced), and its bundled list predates the current models.
+ LITELLM_MODEL_COST_MAP_URL = "https://raw.githubusercontent.com/BerriAI/litellm/729b02d05719715f4faeb1f81ef2728ef06c3273/model_prices_and_context_window.json"
+ }
+
+ # Creates the two SpendLogs indexes that LiteLLM stopped creating in
+ # migrations (1.103.3+). Runs as the app user, which owns the tables.
+ spendlogs_index_sql = <<-SQL
+ GRANT litellm_app TO postgres;
+ SET ROLE litellm_app;
+ CREATE INDEX CONCURRENTLY IF NOT EXISTS "LiteLLM_SpendLogs_api_key_startTime_idx" ON "LiteLLM_SpendLogs" ("api_key", "startTime");
+ CREATE INDEX CONCURRENTLY IF NOT EXISTS "LiteLLM_SpendLogs_litellm_call_id_idx" ON "LiteLLM_SpendLogs" ("litellm_call_id");
+ SQL
+}
+
+# LITELLM_SALT_KEY encrypts provider credentials stored in the database. It can
+# never change once a credential is stored, so it is generated once and kept.
+resource "random_password" "salt_key" {
+ length = 48
+ special = false
+}
+
+resource "aws_secretsmanager_secret" "salt_key" {
+ name = "${local.name}/litellm-salt-key"
+ description = "LITELLM_SALT_KEY for the gateway and backend. Never change it."
+ recovery_window_in_days = 30
+}
+
+resource "aws_secretsmanager_secret_version" "salt_key" {
+ secret_id = aws_secretsmanager_secret.salt_key.id
+ secret_string = random_password.salt_key.result
+
+ lifecycle {
+ ignore_changes = [secret_string]
+ }
+}
+
+# One empty secret per vendor key. Values are set out of band (see README),
+# so no vendor key ever passes through Terraform state.
+resource "aws_secretsmanager_secret" "vendor" {
+ for_each = toset(var.secret_env_names)
+
+ name = "${local.name}/env/${lower(replace(each.value, "_", "-"))}"
+ description = "${each.value} for the gateway service."
+ recovery_window_in_days = 7
+}
+
+module "litellm" {
+ source = "BerriAI/litellm/aws"
+ version = "1.103.4"
+
+ region = var.region
+ tenant = "opencompany"
+ env = var.env
+ azs = var.azs
+
+ gateway_image = "ghcr.io/berriai/litellm-gateway:v${local.litellm_version}"
+ backend_image = "ghcr.io/berriai/litellm-backend:v${local.litellm_version}"
+ ui_image = "ghcr.io/berriai/litellm-ui:v${local.litellm_version}"
+ migrations_image = "ghcr.io/berriai/litellm-migrations:v${local.litellm_version}"
+
+ acm_certificate_arn = aws_acm_certificate_validation.gateway.certificate_arn
+
+ gateway_desired_count = var.gateway_min_tasks
+ gateway_min_capacity = var.gateway_min_tasks
+ gateway_max_capacity = var.gateway_max_tasks
+ gateway_cpu_target = 60
+ # Never scale on memory: Prisma's query engine holds on to its peak.
+ gateway_memory_target = 0
+ # In-task PgBouncer caps each task's database connections.
+ gateway_connection_pool_enabled = true
+
+ proxy_config = yamldecode(file("${path.module}/../../litellm/config.yaml"))
+
+ gateway_extra_secrets = merge(
+ { for env_name, secret in aws_secretsmanager_secret.vendor : env_name => secret.arn },
+ { LITELLM_SALT_KEY = aws_secretsmanager_secret.salt_key.arn },
+ )
+ backend_extra_secrets = {
+ LITELLM_SALT_KEY = aws_secretsmanager_secret.salt_key.arn
+ }
+ gateway_extra_env = local.common_env
+ backend_extra_env = local.common_env
+
+ depends_on = [aws_secretsmanager_secret_version.salt_key]
+}
+
+# TLS certificate for the gateway hostname, validated through DNS.
+resource "aws_acm_certificate" "gateway" {
+ domain_name = var.gateway_hostname
+ validation_method = "DNS"
+
+ lifecycle {
+ create_before_destroy = true
+ }
+}
+
+resource "aws_route53_record" "gateway_cert_validation" {
+ for_each = {
+ for option in aws_acm_certificate.gateway.domain_validation_options : option.domain_name => option
+ }
+
+ zone_id = var.route53_zone_id
+ name = each.value.resource_record_name
+ type = each.value.resource_record_type
+ records = [each.value.resource_record_value]
+ ttl = 60
+ allow_overwrite = true
+}
+
+resource "aws_acm_certificate_validation" "gateway" {
+ certificate_arn = aws_acm_certificate.gateway.arn
+ validation_record_fqdns = [for record in aws_route53_record.gateway_cert_validation : record.fqdn]
+}
+
+resource "aws_route53_record" "gateway" {
+ zone_id = var.route53_zone_id
+ name = var.gateway_hostname
+ type = "CNAME"
+ ttl = 60
+ records = [module.litellm.alb_dns_name]
+}
diff --git a/gateway/infra/terraform/outputs.tf b/gateway/infra/terraform/outputs.tf
new file mode 100644
index 00000000..96d5cbb2
--- /dev/null
+++ b/gateway/infra/terraform/outputs.tf
@@ -0,0 +1,44 @@
+output "gateway_url" {
+ value = "https://${var.gateway_hostname}"
+ description = "Base URL OpenCompany installs use. The admin and key console is <gateway_url>/ui."
+}
+
+output "alb_dns_name" {
+ value = module.litellm.alb_dns_name
+ description = "Load balancer DNS name behind gateway_hostname."
+}
+
+output "master_key_secret_arn" {
+ value = module.litellm.master_key_secret_arn
+ description = "Secret holding the master key. Used once for the first admin login; see README."
+}
+
+output "vendor_secret_arns" {
+ value = { for env_name, secret in aws_secretsmanager_secret.vendor : env_name => secret.arn }
+ description = "Secrets to fill with vendor keys before the first full apply."
+}
+
+output "migration_run_command" {
+ value = module.litellm.migration_run_command
+ description = "Re-runs the Prisma migration task by hand, if ever needed."
+}
+
+output "spendlogs_index_command" {
+ # The module's bootstrap task runs psql as the master user with BOOTSTRAP_SQL
+ # from its environment; this reuses it with the index SQL instead.
+ value = format(
+ "%s --overrides '%s'",
+ replace(
+ module.litellm.migration_run_command,
+ "/--task-definition \\S+/",
+ "--task-definition opencompany-litellm-${var.env}-bootstrap-db",
+ ),
+ jsonencode({
+ containerOverrides = [{
+ name = "psql"
+ environment = [{ name = "BOOTSTRAP_SQL", value = local.spendlogs_index_sql }]
+ }]
+ }),
+ )
+ description = "Run once after the first apply: builds the two SpendLogs indexes LiteLLM no longer creates (see README)."
+}
diff --git a/gateway/infra/terraform/terraform.tf b/gateway/infra/terraform/terraform.tf
new file mode 100644
index 00000000..b14d8f3e
--- /dev/null
+++ b/gateway/infra/terraform/terraform.tf
@@ -0,0 +1,29 @@
+terraform {
+ required_version = ">= 1.10.0"
+
+ required_providers {
+ aws = {
+ source = "hashicorp/aws"
+ version = "~> 5.92"
+ }
+ random = {
+ source = "hashicorp/random"
+ version = "~> 3.6"
+ }
+ }
+
+ # Remote state, one key per environment:
+ # terraform init -backend-config=envs/<env>.backend.hcl
+ backend "s3" {}
+}
+
+provider "aws" {
+ region = var.region
+
+ default_tags {
+ tags = {
+ project = "opencompany-gateway"
+ environment = var.env
+ }
+ }
+}
diff --git a/gateway/infra/terraform/variables.tf b/gateway/infra/terraform/variables.tf
new file mode 100644
index 00000000..b91ed1bb
--- /dev/null
+++ b/gateway/infra/terraform/variables.tf
@@ -0,0 +1,64 @@
+variable "region" {
+ type = string
+ default = "us-east-1"
+ description = "AWS region for the gateway."
+}
+
+variable "azs" {
+ type = list(string)
+ default = ["us-east-1a", "us-east-1b"]
+ description = "Availability zones for the module's subnets, Aurora and the ALB. At least two, in var.region."
+
+ validation {
+ condition = length(var.azs) >= 2
+ error_message = "The module needs at least two availability zones."
+ }
+}
+
+variable "env" {
+ type = string
+ description = "Environment name; also the suffix on every resource the module creates."
+
+ validation {
+ condition = contains(["staging", "prod"], var.env)
+ error_message = "env must be staging or prod."
+ }
+}
+
+variable "gateway_hostname" {
+ type = string
+ description = "Public hostname for the gateway, for example api.gw.opencompany.sh. It must sit inside the route53_zone_id zone."
+}
+
+variable "route53_zone_id" {
+ type = string
+ description = "Route 53 hosted zone that holds gateway_hostname: gw.opencompany.sh, delegated from Cloudflare (see README)."
+}
+
+variable "gateway_min_tasks" {
+ type = number
+ default = 2
+ description = "Minimum gateway tasks. Two keeps a task in each availability zone."
+}
+
+variable "gateway_max_tasks" {
+ type = number
+ default = 10
+ description = "Maximum gateway tasks under CPU autoscaling. Bound it by the database connection budget."
+}
+
+variable "secret_env_names" {
+ type = list(string)
+ description = "Environment variables the gateway reads from Secrets Manager. Terraform creates an empty secret for each; set the values before the first full apply."
+ default = [
+ "OPENAI_API_KEY",
+ "ANTHROPIC_API_KEY",
+ "GEMINI_API_KEY",
+ "GROQ_API_KEY",
+ "CEREBRAS_API_KEY",
+ "XAI_API_KEY",
+ "MOONSHOT_API_KEY",
+ "MISTRAL_API_KEY",
+ "SLACK_WEBHOOK_URL",
+ ]
+}
diff --git a/gateway/litellm/config.yaml b/gateway/litellm/config.yaml
new file mode 100644
index 00000000..079d862c
--- /dev/null
+++ b/gateway/litellm/config.yaml
@@ -0,0 +1,107 @@
+# OpenCompany Gateway: LiteLLM Proxy configuration for staging and prod.
+#
+# Every key below is a stock LiteLLM setting; there is no custom gateway code.
+# Vendor keys never appear here: ECS injects them from AWS Secrets Manager as
+# environment variables, and the proxy resolves `os.environ/<NAME>` at start.
+# Prices come from the pinned price list (LITELLM_MODEL_COST_MAP_URL, set in
+# infra/terraform/main.tf).
+#
+# gateway/local/config.local.yaml mirrors the policy blocks (litellm_settings,
+# general_settings) with mock models. Change both together, and run the
+# contract tests in gateway/tests after any policy change.
+
+model_list:
+ # Provider-prefixed wildcards: any model the price list prices works with
+ # no config change. Models without a price are refused, see
+ # block_requests_for_models_without_pricing below.
+ - model_name: openai/*
+ litellm_params:
+ model: openai/*
+ api_key: os.environ/OPENAI_API_KEY
+ - model_name: anthropic/*
+ litellm_params:
+ model: anthropic/*
+ api_key: os.environ/ANTHROPIC_API_KEY
+ # The Anthropic SDK and Claude Code send bare model ids to /v1/messages.
+ - model_name: claude-*
+ litellm_params:
+ model: anthropic/claude-*
+ api_key: os.environ/ANTHROPIC_API_KEY
+ - model_name: gemini/*
+ litellm_params:
+ model: gemini/*
+ api_key: os.environ/GEMINI_API_KEY
+ # The Gemini SDK puts a bare model id in the /v1beta/models/<id> path.
+ - model_name: gemini-*
+ litellm_params:
+ model: gemini/gemini-*
+ api_key: os.environ/GEMINI_API_KEY
+ - model_name: groq/*
+ litellm_params:
+ model: groq/*
+ api_key: os.environ/GROQ_API_KEY
+ - model_name: cerebras/*
+ litellm_params:
+ model: cerebras/*
+ api_key: os.environ/CEREBRAS_API_KEY
+ - model_name: xai/*
+ litellm_params:
+ model: xai/*
+ api_key: os.environ/XAI_API_KEY
+ # OpenCompany's "kimi" provider.
+ - model_name: moonshot/*
+ litellm_params:
+ model: moonshot/*
+ api_key: os.environ/MOONSHOT_API_KEY
+ - model_name: mistral/*
+ litellm_params:
+ model: mistral/*
+ api_key: os.environ/MISTRAL_API_KEY
+ # Speech (OpenAI and Groq) and embeddings (OpenAI) use the wildcards above:
+ # /v1/audio/speech, /v1/audio/transcriptions and /v1/embeddings.
+
+router_settings:
+ # Shared state across gateway tasks: rate-limit and budget counters,
+ # cooldowns. The Terraform module sets REDIS_HOST, REDIS_PORT and REDIS_SSL.
+ redis_host: os.environ/REDIS_HOST
+ redis_port: os.environ/REDIS_PORT
+
+litellm_settings:
+ json_logs: true
+ timezone: UTC
+ # Each person's allowance (USD) resets on the 1st of the month, UTC.
+ # Admins override it per person; this is the default for new people.
+ max_internal_user_budget: 50
+ internal_user_budget_duration: 1mo
+ # Takes effect from LiteLLM 1.104; 1.103.x always answers 429. OpenCompany
+ # reads the error type (budget_exceeded), so either status pauses the run.
+ # Without it, 1.104+ would answer 422.
+ budget_exceeded_status_code: 402
+ # A model without a price would be billed at $0; refuse it instead (403).
+ block_requests_for_models_without_pricing: true
+ # Ceilings for keys that people create for their installs.
+ upperbound_key_generate_params:
+ rpm_limit: 120
+ tpm_limit: 2000000
+ max_parallel_requests: 32
+ # Opt-in response cache. OpenCompany sends a retry-stable namespace on
+ # Temporal LLM steps, so a retried call replays from cache at $0.
+ cache: true
+ cache_params:
+ type: redis
+ mode: default_off
+ ttl: 172800
+
+general_settings:
+ master_key: os.environ/LITELLM_MASTER_KEY
+ proxy_batch_write_at: 60
+ disable_error_logs: true
+ maximum_spend_logs_retention_period: 90d
+ maximum_spend_logs_retention_interval: 1d
+ # Platform keys are our money: reject a call when the budget can't be
+ # confirmed, rather than letting it through.
+ fail_closed_budget_enforcement: true
+ # The module's VPC; client IPs are read from the ALB's forwarding header.
+ trusted_proxy_ranges: ["10.40.0.0/16"]
+ alerting: ["slack"]
+ alert_types: ["budget_alerts", "outage_alerts", "db_exceptions"]
diff --git a/gateway/local/config.local.yaml b/gateway/local/config.local.yaml
new file mode 100644
index 00000000..7411fdaf
--- /dev/null
+++ b/gateway/local/config.local.yaml
@@ -0,0 +1,61 @@
+# Local OpenCompany Gateway config: mock models instead of real vendors, so
+# nothing is billed and no vendor keys are needed.
+#
+# The policy blocks mirror gateway/litellm/config.yaml. Differences, all
+# deliberate: mock_response on every model, spend logs flush every second so
+# the tests can read them, and there is no Slack alerting or proxy-range trust.
+
+model_list:
+ - model_name: openai/*
+ litellm_params:
+ model: openai/*
+ api_key: sk-local-unused
+ mock_response: pong
+ - model_name: claude-*
+ litellm_params:
+ model: anthropic/claude-*
+ api_key: sk-local-unused
+ mock_response: pong
+ - model_name: gemini-*
+ litellm_params:
+ model: gemini/gemini-*
+ api_key: local-unused
+ mock_response: pong
+ # A dotted alias that is not a price-list key, the shape LiteLLM's own test
+ # for PR #44341 uses: a stream through it must still be priced at the
+ # deployment's model. It streams from fake_anthropic.py, because mock
+ # responses skip LiteLLM's upstream streaming path.
+ - model_name: claude-opus-4.8-20261010
+ litellm_params:
+ model: anthropic/claude-opus-4-8
+ api_key: sk-local-unused
+ api_base: http://fake-anthropic:8080
+
+router_settings:
+ redis_host: os.environ/REDIS_HOST
+ redis_port: os.environ/REDIS_PORT
+
+litellm_settings:
+ json_logs: true
+ timezone: UTC
+ max_internal_user_budget: 50
+ internal_user_budget_duration: 1mo
+ budget_exceeded_status_code: 402
+ block_requests_for_models_without_pricing: true
+ upperbound_key_generate_params:
+ rpm_limit: 120
+ tpm_limit: 2000000
+ max_parallel_requests: 32
+ cache: true
+ cache_params:
+ type: redis
+ mode: default_off
+ ttl: 172800
+
+general_settings:
+ master_key: os.environ/LITELLM_MASTER_KEY
+ proxy_batch_write_at: 1
+ disable_error_logs: true
+ maximum_spend_logs_retention_period: 90d
+ maximum_spend_logs_retention_interval: 1d
+ fail_closed_budget_enforcement: true
diff --git a/gateway/local/docker-compose.yml b/gateway/local/docker-compose.yml
new file mode 100644
index 00000000..aa7cec3f
--- /dev/null
+++ b/gateway/local/docker-compose.yml
@@ -0,0 +1,75 @@
+# Local OpenCompany Gateway stack, for development and the contract tests in
+# gateway/tests. Mock models only: no vendor keys, no spend. Not for
+# production; staging and prod run from gateway/infra.
+#
+# docker compose -f gateway/local/docker-compose.yml up -d --wait
+# docker compose -f gateway/local/docker-compose.yml down -v
+name: opencompany-gateway-local
+
+services:
+ postgres:
+ image: postgres:16-alpine
+ environment:
+ POSTGRES_DB: litellm
+ POSTGRES_USER: litellm
+ POSTGRES_PASSWORD: litellm-local
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U litellm -d litellm"]
+ interval: 2s
+ timeout: 3s
+ retries: 30
+
+ redis:
+ image: redis:7-alpine
+ # Same eviction policy as ElastiCache in gateway/infra: evicting keys
+ # would silently drop budget and rate-limit counters.
+ command: ["redis-server", "--maxmemory-policy", "noeviction", "--save", ""]
+ healthcheck:
+ test: ["CMD", "redis-cli", "ping"]
+ interval: 2s
+ timeout: 3s
+ retries: 30
+
+ fake-anthropic:
+ # A real upstream stream for the streamed-pricing test (see the file).
+ image: python:3.12-alpine
+ command: ["python", "/app/fake_anthropic.py"]
+ volumes:
+ - ./fake_anthropic.py:/app/fake_anthropic.py:ro
+ healthcheck:
+ test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')"]
+ interval: 2s
+ timeout: 3s
+ retries: 30
+
+ litellm:
+ # Keep the tag and LITELLM_MODEL_COST_MAP_URL in step with
+ # gateway/infra/terraform/main.tf (gateway/tests/test_pins.py checks).
+ image: ghcr.io/berriai/litellm:v1.103.4
+ command: ["--config", "/app/config.yaml", "--port", "4000"]
+ environment:
+ DATABASE_URL: postgresql://litellm:litellm-local@postgres:5432/litellm
+ REDIS_HOST: redis
+ REDIS_PORT: "6379"
+ LITELLM_MASTER_KEY: sk-local-master-key
+ LITELLM_SALT_KEY: sk-local-salt-key
+ LITELLM_MODE: PRODUCTION
+ STORE_MODEL_IN_DB: "False"
+ LITELLM_MODEL_COST_MAP_URL: https://raw.githubusercontent.com/BerriAI/litellm/729b02d05719715f4faeb1f81ef2728ef06c3273/model_prices_and_context_window.json
+ volumes:
+ - ./config.local.yaml:/app/config.yaml:ro
+ ports:
+ - "127.0.0.1:4000:4000"
+ depends_on:
+ postgres:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ fake-anthropic:
+ condition: service_healthy
+ healthcheck:
+ test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:4000/health/liveliness')\""]
+ interval: 5s
+ timeout: 5s
+ retries: 60
+ start_period: 30s
diff --git a/gateway/local/fake_anthropic.py b/gateway/local/fake_anthropic.py
new file mode 100644
index 00000000..564235ee
--- /dev/null
+++ b/gateway/local/fake_anthropic.py
@@ -0,0 +1,75 @@
+"""Fake Anthropic upstream for the gateway contract tests.
+
+Answers POST /v1/messages the way Anthropic does: a JSON message, or a
+server-sent event stream when the request sets "stream": true, always with
+the same usage. Mock responses inside LiteLLM skip its streaming path, so the
+streamed-pricing test needs a real upstream stream; this is the smallest one.
+Standard library only.
+"""
+
+from __future__ import annotations
+
+import json
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+INPUT_TOKENS = 30
+OUTPUT_TOKENS = 40
+
+
+def _message(model: str) -> dict:
+ return {
+ "id": "msg_contract",
+ "type": "message",
+ "role": "assistant",
+ "model": model,
+ "content": [{"type": "text", "text": "pong"}],
+ "stop_reason": "end_turn",
+ "stop_sequence": None,
+ "usage": {"input_tokens": INPUT_TOKENS, "output_tokens": OUTPUT_TOKENS},
+ }
+
+
+def _events(model: str) -> list[tuple[str, dict]]:
+ start = {**_message(model), "content": [], "stop_reason": None, "usage": {"input_tokens": INPUT_TOKENS, "output_tokens": 1}}
+ return [
+ ("message_start", {"type": "message_start", "message": start}),
+ ("content_block_start", {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}),
+ ("content_block_delta", {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "pong"}}),
+ ("content_block_stop", {"type": "content_block_stop", "index": 0}),
+ ("message_delta", {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": None}, "usage": {"output_tokens": OUTPUT_TOKENS}}),
+ ("message_stop", {"type": "message_stop"}),
+ ]
+
+
+class Handler(BaseHTTPRequestHandler):
+ def do_GET(self) -> None: # health check
+ self.send_response(200 if self.path == "/health" else 404)
+ self.end_headers()
+
+ def do_POST(self) -> None:
+ if not self.path.endswith("/v1/messages"):
+ self.send_error(404)
+ return
+ body = json.loads(self.rfile.read(int(self.headers.get("content-length") or 0)) or b"{}")
+ model = body.get("model", "claude-opus-4-8")
+ if body.get("stream"):
+ self.send_response(200)
+ self.send_header("content-type", "text/event-stream")
+ self.end_headers()
+ for name, payload in _events(model):
+ self.wfile.write(f"event: {name}\ndata: {json.dumps(payload)}\n\n".encode())
+ self.wfile.flush()
+ return
+ data = json.dumps(_message(model)).encode()
+ self.send_response(200)
+ self.send_header("content-type", "application/json")
+ self.send_header("content-length", str(len(data)))
+ self.end_headers()
+ self.wfile.write(data)
+
+ def log_message(self, format: str, *args: object) -> None:
+ pass
+
+
+if __name__ == "__main__":
+ ThreadingHTTPServer(("0.0.0.0", 8080), Handler).serve_forever()
diff --git a/gateway/pyproject.toml b/gateway/pyproject.toml
new file mode 100644
index 00000000..04fbeff0
--- /dev/null
+++ b/gateway/pyproject.toml
@@ -0,0 +1,17 @@
+# Test dependencies for gateway/tests (contract and pin checks). Not a
+# package; uv.lock pins the exact versions CI installs.
+[project]
+name = "opencompany-gateway-checks"
+version = "0"
+requires-python = ">=3.12"
+dependencies = [
+ "httpx>=0.28",
+ "pytest>=8.3",
+ "pyyaml>=6.0",
+]
+
+[tool.uv]
+package = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
diff --git a/gateway/tests/test_gateway_contract.py b/gateway/tests/test_gateway_contract.py
new file mode 100644
index 00000000..a24f8616
--- /dev/null
+++ b/gateway/tests/test_gateway_contract.py
@@ -0,0 +1,290 @@
+"""Contract tests for the OpenCompany Gateway (LiteLLM Proxy).
+
+They run against the local stack in gateway/local (mock models, no real keys)
+and pin the LiteLLM behaviours the OpenCompany integration relies on: budget
+refusals, key scope, attribution, streamed pricing, retry replay, and the
+native Anthropic and Gemini routes.
+
+ docker compose -f gateway/local/docker-compose.yml up -d --wait
+ uv run --project gateway pytest gateway/tests -v
+
+Set GATEWAY_URL and GATEWAY_MASTER_KEY to point the suite at another stack.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from datetime import date, timedelta
+
+import httpx
+import pytest
+
+GATEWAY_URL = os.environ.get("GATEWAY_URL", "http://127.0.0.1:4000")
+MASTER_KEY = os.environ.get("GATEWAY_MASTER_KEY", "sk-local-master-key")
+CHAT_MODEL = "openai/gpt-4o-mini"
+# A dotted alias that is not a price-list key, streaming from a fake Anthropic
+# upstream (gateway/local/config.local.yaml, gateway/local/fake_anthropic.py).
+ALIAS_MODEL = "claude-opus-4.8-20261010"
+# 1.103.x always answers a spent allowance with 429; budget_exceeded_status_code
+# makes it 402 from 1.104. OpenCompany reads the error type either way.
+BUDGET_STATUSES = {402, 429}
+PING = [{"role": "user", "content": "ping"}]
+
+
+def _gateway_up() -> bool:
+ try:
+ return httpx.get(f"{GATEWAY_URL}/health/liveliness", timeout=3).status_code == 200
+ except httpx.HTTPError:
+ return False
+
+
+pytestmark = pytest.mark.skipif(not _gateway_up(), reason=f"gateway not reachable at {GATEWAY_URL}")
+
+
+@dataclass(frozen=True)
+class Person:
+ user_id: str
+ key: str
+
+
+def _auth(key: str) -> dict[str, str]:
+ return {"Authorization": f"Bearer {key}"}
+
+
+def _chat(key: str, *, headers: dict[str, str] | None = None, body: dict | None = None) -> httpx.Response:
+ payload = {"model": CHAT_MODEL, "max_tokens": 16, "messages": PING}
+ payload.update(body or {})
+ return httpx.post(
+ f"{GATEWAY_URL}/v1/chat/completions",
+ headers={**_auth(key), **(headers or {})},
+ json=payload,
+ timeout=30,
+ )
+
+
+def _messages(key: str, *, headers: dict[str, str] | None = None, body: dict | None = None) -> httpx.Response:
+ payload = {"model": "claude-haiku-4-5", "max_tokens": 16, "messages": PING}
+ payload.update(body or {})
+ return httpx.post(
+ f"{GATEWAY_URL}/v1/messages",
+ headers={"x-api-key": key, "anthropic-version": "2023-06-01", **(headers or {})},
+ json=payload,
+ timeout=30,
+ )
+
+
+def _generate_content(key: str, *, body: dict | None = None) -> httpx.Response:
+ payload = {"contents": [{"role": "user", "parts": [{"text": "ping"}]}]}
+ payload.update(body or {})
+ return httpx.post(
+ f"{GATEWAY_URL}/v1beta/models/gemini-2.5-flash:generateContent",
+ headers={"x-goog-api-key": key},
+ json=payload,
+ timeout=30,
+ )
+
+
+def _error_type(resp: httpx.Response) -> str | None:
+ """The error type in OpenAI-shaped ({"error": {...}}) and Anthropic-shaped bodies."""
+ try:
+ body = resp.json()
+ except ValueError:
+ return None
+ error = body.get("error", body) if isinstance(body, dict) else None
+ return error.get("type") if isinstance(error, dict) else None
+
+
+def _spend_rows(admin: httpx.Client, **filters: str) -> list[dict]:
+ """Poll /spend/logs/v2 until rows matching the filters appear (spend is batch-written)."""
+ today = date.today()
+ params = {
+ "start_date": (today - timedelta(days=1)).isoformat(),
+ "end_date": (today + timedelta(days=1)).isoformat(),
+ **filters,
+ }
+ for _ in range(20):
+ resp = admin.get("/spend/logs/v2", params=params)
+ resp.raise_for_status()
+ body = resp.json()
+ rows = body.get("data", []) if isinstance(body, dict) else body
+ if rows:
+ return rows
+ time.sleep(1)
+ return []
+
+
[email protected](scope="module")
+def admin() -> Iterator[httpx.Client]:
+ with httpx.Client(base_url=GATEWAY_URL, headers=_auth(MASTER_KEY), timeout=30) as client:
+ yield client
+
+
+def person(admin: httpx.Client) -> Iterator[Callable[..., Person]]:
+ """Create a fresh person (internal user) with a personal key; delete them afterwards.
+
+ Keys are Default-type unless key_type says otherwise: that is what the
+ console creates, and OpenCompany needs it to read the allowance.
+ """
+ created: list[str] = []
+
+ def make(max_budget: float = 10.0, key_type: str | None = None) -> Person:
+ user_id = f"contract-{uuid.uuid4().hex[:12]}"
+ admin.post(
+ "/user/new",
+ json={"user_id": user_id, "user_role": "internal_user", "max_budget": max_budget, "budget_duration": "1mo"},
+ ).raise_for_status()
+ created.append(user_id)
+ request = {"user_id": user_id, **({"key_type": key_type} if key_type else {})}
+ resp = admin.post("/key/generate", json=request)
+ resp.raise_for_status()
+ return Person(user_id=user_id, key=resp.json()["key"])
+
+ yield make
+ if created:
+ admin.post("/user/delete", json={"user_ids": created})
+
+
+def test_unpriced_model_is_refused(person: Callable[..., Person]) -> None:
+ """block_requests_for_models_without_pricing: an unpriced model never bills $0."""
+ resp = _chat(person().key, body={"model": "openai/oc-contract-unpriced-model"})
+ assert resp.status_code == 403, resp.text
+ assert _error_type(resp) == "model_cost_map_missing", resp.text
+
+
+def test_budget_refusal_is_typed_on_every_route(person: Callable[..., Person]) -> None:
+ """OpenCompany recognises a spent allowance by its error type, on each route it uses."""
+ key = person(max_budget=0.0000001).key
+ calls: dict[str, Callable[[], httpx.Response]] = {
+ "chat/completions": lambda: _chat(key, body={"max_tokens": 1000}),
+ "messages": lambda: _messages(key, body={"max_tokens": 1000}),
+ "generateContent": lambda: _generate_content(key, body={"generationConfig": {"maxOutputTokens": 1000}}),
+ }
+ for route, call in calls.items():
+ resp = call()
+ for _ in range(3):
+ if resp.status_code != 200:
+ break
+ time.sleep(2)
+ resp = call()
+ assert resp.status_code in BUDGET_STATUSES, (route, resp.status_code, resp.text)
+ assert _error_type(resp) == "budget_exceeded", (route, resp.text)
+
+
+def test_user_info_needs_a_default_key_and_stays_scoped(person: Callable[..., Person]) -> None:
+ """OpenCompany shows the allowance from /user/info: a Default key reads only its own."""
+ me, other = person(), person()
+ own = httpx.get(f"{GATEWAY_URL}/user/info", headers=_auth(me.key), timeout=30)
+ assert own.status_code == 200, own.text
+ assert own.json().get("user_id") == me.user_id, own.text
+ info = own.json().get("user_info") or {}
+ assert {"spend", "max_budget", "budget_reset_at"} <= set(info), own.text
+
+ theirs = httpx.get(f"{GATEWAY_URL}/user/info", params={"user_id": other.user_id}, headers=_auth(me.key), timeout=30)
+ assert theirs.status_code in (401, 403), theirs.text
+
+ llm_only = person(key_type="llm_api")
+ refused = httpx.get(f"{GATEWAY_URL}/user/info", headers=_auth(llm_only.key), timeout=30)
+ assert refused.status_code in (401, 403), refused.text
+
+
+def test_attribution_headers_reach_spend_logs(person: Callable[..., Person], admin: httpx.Client) -> None:
+ """x-litellm-session-id / -tags / -spend-logs-metadata land on the spend row."""
+ session = f"r_{uuid.uuid4().hex}"
+ resp = _chat(
+ person().key,
+ headers={
+ "x-litellm-session-id": session,
+ "x-litellm-tags": "workflow:wf-contract,source:chat,user:owner",
+ "x-litellm-spend-logs-metadata": json.dumps({"root_execution_id": "exec-1", "node_id": "agent-1"}),
+ },
+ )
+ assert resp.status_code == 200, resp.text
+ rows = _spend_rows(admin, session_id=session)
+ assert rows, "no spend row for the session id"
+ row = rows[0]
+ assert {"workflow:wf-contract", "source:chat", "user:owner"} <= set(row.get("request_tags") or []), row
+ stored = (row.get("metadata") or {}).get("spend_logs_metadata") or {}
+ assert stored.get("root_execution_id") == "exec-1", row
+
+
+def test_streamed_alias_is_priced_at_the_deployment(person: Callable[..., Person], admin: httpx.Client) -> None:
+ """A real upstream stream through a dotted alias is billed at the deployment's price.
+
+ The shape of LiteLLM PR #44341 ($0 for streamed aliases). With this config
+ and the pinned price list, 1.103.2 (without the fix) already passes, so this
+ guards streamed pricing on upgrades rather than proving the fix is present.
+ """
+ session = f"alias-{uuid.uuid4().hex}"
+ resp = _chat(
+ person().key,
+ headers={"x-litellm-session-id": session},
+ body={"model": ALIAS_MODEL, "stream": True, "stream_options": {"include_usage": True}},
+ )
+ assert resp.status_code == 200, resp.text
+ rows = _spend_rows(admin, session_id=session)
+ assert rows, "no spend row for the streamed call"
+ assert float(rows[0].get("spend") or 0) > 0, rows[0]
+
+
+def test_cache_namespace_replays_retry_for_free(person: Callable[..., Person], admin: httpx.Client) -> None:
+ """Opt-in cache with a per-request namespace: the replayed retry costs $0."""
+ key = person().key
+ namespace = f"oc1-{uuid.uuid4().hex}"
+ cache = {"cache": {"use-cache": True, "namespace": namespace, "ttl": 600}}
+ first = _chat(key, headers={"x-litellm-session-id": f"{namespace}-first"}, body=cache)
+ second = _chat(key, headers={"x-litellm-session-id": f"{namespace}-retry"}, body=cache)
+ assert first.status_code == second.status_code == 200, (first.text, second.text)
+ rows = _spend_rows(admin, session_id=f"{namespace}-retry")
+ assert rows, "no spend row for the retry"
+ assert str(rows[0].get("cache_hit")).lower() == "true", rows[0]
+ assert float(rows[0].get("spend") or 0) == 0.0, rows[0]
+
+
+def test_streamed_retry_replays_for_free(person: Callable[..., Person], admin: httpx.Client) -> None:
+ """The same replay for streamed calls, which chat runs use."""
+ key = person().key
+ namespace = f"oc1-{uuid.uuid4().hex}"
+ body = {
+ "stream": True,
+ "stream_options": {"include_usage": True},
+ "cache": {"use-cache": True, "namespace": namespace, "ttl": 600},
+ }
+ first = _chat(key, headers={"x-litellm-session-id": f"{namespace}-first"}, body=body)
+ second = _chat(key, headers={"x-litellm-session-id": f"{namespace}-retry"}, body=body)
+ assert first.status_code == second.status_code == 200, (first.text, second.text)
+ rows = _spend_rows(admin, session_id=f"{namespace}-retry")
+ assert rows, "no spend row for the streamed retry"
+ assert str(rows[0].get("cache_hit")).lower() == "true", rows[0]
+ assert float(rows[0].get("spend") or 0) == 0.0, rows[0]
+
+
+def test_anthropic_messages_route_accepts_bare_model_ids(person: Callable[..., Person]) -> None:
+ """The claude-* wildcard serves the Anthropic SDK and Claude Code on /v1/messages."""
+ resp = _messages(person().key)
+ assert resp.status_code == 200, resp.text
+ assert resp.json().get("type") == "message", resp.text
+
+
+def test_anthropic_messages_cache_namespace(person: Callable[..., Person], admin: httpx.Client) -> None:
+ """The same opt-in cache controls work on /v1/messages."""
+ key = person().key
+ namespace = f"oc1-{uuid.uuid4().hex}"
+ body = {"cache": {"use-cache": True, "namespace": namespace, "ttl": 600}}
+ for suffix in ("first", "retry"):
+ resp = _messages(key, headers={"x-litellm-session-id": f"{namespace}-{suffix}"}, body=body)
+ assert resp.status_code == 200, resp.text
+ rows = _spend_rows(admin, session_id=f"{namespace}-retry")
+ assert rows, "no spend row for the retry"
+ assert str(rows[0].get("cache_hit")).lower() == "true", rows[0]
+
+
+def test_gemini_native_route_accepts_virtual_key(person: Callable[..., Person]) -> None:
+ """The gemini-* wildcard serves the Gemini SDK, which sends its key as x-goog-api-key."""
+ resp = _generate_content(person().key)
+ assert resp.status_code == 200, resp.text
diff --git a/gateway/tests/test_pins.py b/gateway/tests/test_pins.py
new file mode 100644
index 00000000..f5ed90bf
--- /dev/null
+++ b/gateway/tests/test_pins.py
@@ -0,0 +1,71 @@
+"""Offline checks on the gateway's pins; no gateway needed.
+
+- LiteLLM's version and the price-list commit agree across Terraform, the
+ local stack and CI.
+- The pinned price list prices the default model of every provider the
+ gateway serves, so OpenCompany's defaults are never refused as unpriced.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+import httpx
+import pytest
+import yaml
+
+REPO = Path(__file__).resolve().parents[2]
+TERRAFORM = (REPO / "gateway/infra/terraform/main.tf").read_text(encoding="utf-8")
+COMPOSE = yaml.safe_load((REPO / "gateway/local/docker-compose.yml").read_text(encoding="utf-8"))
+CI = yaml.safe_load((REPO / ".github/workflows/gateway-ci.yml").read_text(encoding="utf-8"))
+LITELLM = COMPOSE["services"]["litellm"]
+
+# Providers the gateway serves: OpenCompany provider id (server/config/
+# llm_defaults.json) -> the prefix of its keys in LiteLLM's price list.
+SERVED_PROVIDERS = {
+ "openai": "",
+ "anthropic": "",
+ "gemini": "gemini/",
+ "groq": "groq/",
+ "cerebras": "cerebras/",
+ "xai": "xai/",
+ "kimi": "moonshot/",
+ "mistral": "mistral/",
+}
+
+
+def _terraform_string(name: str) -> str:
+ match = re.search(rf'^\s*{name}\s*=\s*"([^"]+)"', TERRAFORM, re.MULTILINE)
+ assert match, f"{name} not found in gateway/infra/terraform/main.tf"
+ return match.group(1)
+
+
+def test_pins_agree() -> None:
+ version = _terraform_string("litellm_version")
+ module = re.search(r'source\s*=\s*"BerriAI/litellm/aws"\s*\n\s*version\s*=\s*"([^"]+)"', TERRAFORM)
+ assert module and module.group(1) == version, "module version and local.litellm_version differ in main.tf"
+ assert LITELLM["image"].endswith(f":v{version}"), LITELLM["image"]
+ assert CI["env"]["LITELLM_VERSION"] == version, CI["env"]
+ assert LITELLM["environment"]["LITELLM_MODEL_COST_MAP_URL"] == _terraform_string("LITELLM_MODEL_COST_MAP_URL")
+
+
+def test_served_default_models_are_priced() -> None:
+ url = LITELLM["environment"]["LITELLM_MODEL_COST_MAP_URL"]
+ assert re.search(r"/[0-9a-f]{40}/", url), "the price list must be pinned to a commit"
+ try:
+ prices = httpx.get(url, timeout=60).raise_for_status().json()
+ except httpx.HTTPError as exc:
+ if os.environ.get("CI"):
+ raise
+ pytest.skip(f"price list unreachable: {exc}")
+ providers = json.loads((REPO / "server/config/llm_defaults.json").read_text(encoding="utf-8"))["providers"]
+ unpriced = []
+ for provider, prefix in SERVED_PROVIDERS.items():
+ key = prefix + providers[provider]["default_model"]
+ entry = prices.get(key) or {}
+ if "input_cost_per_token" not in entry and "output_cost_per_token" not in entry:
+ unpriced.append(key)
+ assert not unpriced, f"served default models with no price in the pinned list: {unpriced}"
diff --git a/gateway/uv.lock b/gateway/uv.lock
new file mode 100644
index 00000000..0b34a655
--- /dev/null
+++ b/gateway/uv.lock
@@ -0,0 +1,204 @@
+version = 1
+revision = 3
+requires-python = ">=3.12"
+
+[[package]]
+name = "anyio"
+version = "4.15.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "idna" },
+ { name = "typing-extensions", marker = "python_full_version < '3.15'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a9/d2/f4d173e22df740bc37b1db102b386ba719b66e95b0f0d751f556b387e6d2/anyio-4.15.1.tar.gz", hash = "sha256:9f28306018cbd6d329e64a36d58256edff76dd996fe423bc957326e578b82a94", size = 276966, upload-time = "2026-09-05T10:42:39.44Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/12/b8/4bd346e22b28902df4d651910f5242c28d84e4a5c2435ca5c3f797ed7e2e/anyio-4.15.1-py3-none-any.whl", hash = "sha256:6152fdbbf9a77fdec97731721bebf7c4c44f7c29b424b0065826173efc7ed101", size = 132079, upload-time = "2026-09-05T10:42:37.923Z" },
+]
+
+[[package]]
+name = "certifi"
+version = "2026.7.22"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a3/c2/24167ea9858356b47a87a50d39908bfdb72ceeefe0041586e704e5376b3a/certifi-2026.7.22.tar.gz", hash = "sha256:741e2c3b351ddf169a738da9f2c048608ff7f2c5cc02f1ebc6b118bb090d5d55", size = 138112, upload-time = "2026-07-22T03:35:12.644Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/0b/a7/71ac2cff56fec219ed242bb11b8efb69fcc4bec75db06fb7bfe35de520e6/certifi-2026.7.22-py3-none-any.whl", hash = "sha256:62f22742b58a1a33014a2b6b706588a8d7e2a88ae7bd1a6ebe8c992928483775", size = 136983, upload-time = "2026-07-22T03:35:11.276Z" },
+]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "h11"
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
+]
+
+[[package]]
+name = "httpcore"
+version = "1.0.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "certifi" },
+ { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/94/82699a10bca87a5556c9c59b5963f2d039dbd239f25bc2a63907a05a14cb/httpcore-1.0.9.tar.gz", hash = "sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8", size = 85484, upload-time = "2025-04-24T22:06:22.219Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" },
+]
+
+[[package]]
+name = "httpx"
+version = "0.28.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "anyio" },
+ { name = "certifi" },
+ { name = "httpcore" },
+ { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/df/48c586a5fe32a0f01324ee087459e112ebb7224f646c0b5023f5e79e9956/httpx-0.28.1.tar.gz", hash = "sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc", size = 141406, upload-time = "2024-12-06T15:37:23.222Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" },
+]
+
+[[package]]
+name = "idna"
+version = "3.20"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f5/08/8eea9d4b8302028f3abb2c0813953f7aec26d33b7a8960ed760e65ff29fa/idna-3.20.tar.gz", hash = "sha256:a7db850025b95ded1eae8a46181a1a6c56c92c96f0e2b005d9ff8dc0210cab44", size = 216463, upload-time = "2026-09-17T14:11:04.752Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/58/a2/bb081bab032533a855d44de1d56f8e8426114ff1ba5d1f07a438a0a654f8/idna-3.20-py3-none-any.whl", hash = "sha256:ab7ae7122974553370f0bdb919e1a960b2cd1bc1ef0276416d896db81c14582c", size = 69583, upload-time = "2026-09-17T14:11:03.168Z" },
+]
+
+[[package]]
+name = "iniconfig"
+version = "2.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/e1/2069291243c926a2ff1cd706c7f3eeb9b62144bf60f77c9fb9ff2fb26bd3/iniconfig-2.3.1.tar.gz", hash = "sha256:67f4b9c50da0dedf52af349e7749a80a9057a5031199791b906c3bb3ae878960", size = 21209, upload-time = "2026-10-06T22:48:38.076Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/56/43/4ca9e49d27a1fcf6bece6f6aec0ea46bb9112489b93d4b688fb415457bdb/iniconfig-2.3.1-py3-none-any.whl", hash = "sha256:9121e2c1fdb355232495be3194c8dfe87ccc2d5dee45947b78e68f499790d7a7", size = 7552, upload-time = "2026-10-06T22:48:36.959Z" },
+]
+
+[[package]]
+name = "opencompany-gateway-checks"
+version = "0"
+source = { virtual = "." }
+dependencies = [
+ { name = "httpx" },
+ { name = "pytest" },
+ { name = "pyyaml" },
+]
+
+[package.metadata]
+requires-dist = [
+ { name = "httpx", specifier = ">=0.28" },
+ { name = "pytest", specifier = ">=8.3" },
+ { name = "pyyaml", specifier = ">=6.0" },
+]
+
+[[package]]
+name = "packaging"
+version = "26.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/fa/3944b40b07da9ce895c0e6303a5ab7d53da063554f534556b134a54d6093/packaging-26.3.tar.gz", hash = "sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79", size = 313412, upload-time = "2026-08-04T18:15:28.737Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/63/34/ba1c580383c9eada3711951fef0795c80b829a078d72188184bcab9dd527/packaging-26.3-py3-none-any.whl", hash = "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c", size = 129956, upload-time = "2026-08-04T18:15:27.159Z" },
+]
+
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.21.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/49/2e/ced460408999b33da6b31b0021b0f37d329e202d4169aeb164493778f25b/pygments-2.21.0.tar.gz", hash = "sha256:610ca751c9bc2492b38eb9a38a7fbc93edbbb2d7182edaf34e66ae493dee5c8c", size = 5005329, upload-time = "2026-08-17T08:02:48.824Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/71/46/17f022dd3e953bf20a04a028a21ec746d942f8d2af30fa0f124fa0e6a684/pygments-2.21.0-py3-none-any.whl", hash = "sha256:2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9", size = 1250147, upload-time = "2026-08-17T08:02:44.912Z" },
+]
+
+[[package]]
+name = "pytest"
+version = "9.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "colorama", marker = "sys_platform == 'win32'" },
+ { name = "iniconfig" },
+ { name = "packaging" },
+ { name = "pluggy" },
+ { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e4/47/b9efed96c114afcfa3c9d3fe98a76a1d14c74a9e266d397cf6eb64be5e01/pytest-9.1.1.tar.gz", hash = "sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313", size = 1636369, upload-time = "2026-06-19T10:58:32.857Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" },
+]
+
+[[package]]
+name = "pyyaml"
+version = "6.0.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/05/8e/961c0007c59b8dd7729d542c61a4d537767a59645b82a0b521206e1e25c2/pyyaml-6.0.3.tar.gz", hash = "sha256:d76623373421df22fb4cf8817020cbb7ef15c725b9d5e45f17e189bfc384190f", size = 130960, upload-time = "2025-09-25T21:33:16.546Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d1/33/422b98d2195232ca1826284a76852ad5a86fe23e31b009c9886b2d0fb8b2/pyyaml-6.0.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:7f047e29dcae44602496db43be01ad42fc6f1cc0d8cd6c83d342306c32270196", size = 182063, upload-time = "2025-09-25T21:32:11.445Z" },
+ { url = "https://files.pythonhosted.org/packages/89/a0/6cf41a19a1f2f3feab0e9c0b74134aa2ce6849093d5517a0c550fe37a648/pyyaml-6.0.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:fc09d0aa354569bc501d4e787133afc08552722d3ab34836a80547331bb5d4a0", size = 173973, upload-time = "2025-09-25T21:32:12.492Z" },
+ { url = "https://files.pythonhosted.org/packages/ed/23/7a778b6bd0b9a8039df8b1b1d80e2e2ad78aa04171592c8a5c43a56a6af4/pyyaml-6.0.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9149cad251584d5fb4981be1ecde53a1ca46c891a79788c0df828d2f166bda28", size = 775116, upload-time = "2025-09-25T21:32:13.652Z" },
+ { url = "https://files.pythonhosted.org/packages/65/30/d7353c338e12baef4ecc1b09e877c1970bd3382789c159b4f89d6a70dc09/pyyaml-6.0.3-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5fdec68f91a0c6739b380c83b951e2c72ac0197ace422360e6d5a959d8d97b2c", size = 844011, upload-time = "2025-09-25T21:32:15.21Z" },
+ { url = "https://files.pythonhosted.org/packages/8b/9d/b3589d3877982d4f2329302ef98a8026e7f4443c765c46cfecc8858c6b4b/pyyaml-6.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ba1cc08a7ccde2d2ec775841541641e4548226580ab850948cbfda66a1befcdc", size = 807870, upload-time = "2025-09-25T21:32:16.431Z" },
+ { url = "https://files.pythonhosted.org/packages/05/c0/b3be26a015601b822b97d9149ff8cb5ead58c66f981e04fedf4e762f4bd4/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:8dc52c23056b9ddd46818a57b78404882310fb473d63f17b07d5c40421e47f8e", size = 761089, upload-time = "2025-09-25T21:32:17.56Z" },
+ { url = "https://files.pythonhosted.org/packages/be/8e/98435a21d1d4b46590d5459a22d88128103f8da4c2d4cb8f14f2a96504e1/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:41715c910c881bc081f1e8872880d3c650acf13dfa8214bad49ed4cede7c34ea", size = 790181, upload-time = "2025-09-25T21:32:18.834Z" },
+ { url = "https://files.pythonhosted.org/packages/74/93/7baea19427dcfbe1e5a372d81473250b379f04b1bd3c4c5ff825e2327202/pyyaml-6.0.3-cp312-cp312-win32.whl", hash = "sha256:96b533f0e99f6579b3d4d4995707cf36df9100d67e0c8303a0c55b27b5f99bc5", size = 137658, upload-time = "2025-09-25T21:32:20.209Z" },
+ { url = "https://files.pythonhosted.org/packages/86/bf/899e81e4cce32febab4fb42bb97dcdf66bc135272882d1987881a4b519e9/pyyaml-6.0.3-cp312-cp312-win_amd64.whl", hash = "sha256:5fcd34e47f6e0b794d17de1b4ff496c00986e1c83f7ab2fb8fcfe9616ff7477b", size = 154003, upload-time = "2025-09-25T21:32:21.167Z" },
+ { url = "https://files.pythonhosted.org/packages/1a/08/67bd04656199bbb51dbed1439b7f27601dfb576fb864099c7ef0c3e55531/pyyaml-6.0.3-cp312-cp312-win_arm64.whl", hash = "sha256:64386e5e707d03a7e172c0701abfb7e10f0fb753ee1d773128192742712a98fd", size = 140344, upload-time = "2025-09-25T21:32:22.617Z" },
+ { url = "https://files.pythonhosted.org/packages/d1/11/0fd08f8192109f7169db964b5707a2f1e8b745d4e239b784a5a1dd80d1db/pyyaml-6.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8da9669d359f02c0b91ccc01cac4a67f16afec0dac22c2ad09f46bee0697eba8", size = 181669, upload-time = "2025-09-25T21:32:23.673Z" },
+ { url = "https://files.pythonhosted.org/packages/b1/16/95309993f1d3748cd644e02e38b75d50cbc0d9561d21f390a76242ce073f/pyyaml-6.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2283a07e2c21a2aa78d9c4442724ec1eb15f5e42a723b99cb3d822d48f5f7ad1", size = 173252, upload-time = "2025-09-25T21:32:25.149Z" },
+ { url = "https://files.pythonhosted.org/packages/50/31/b20f376d3f810b9b2371e72ef5adb33879b25edb7a6d072cb7ca0c486398/pyyaml-6.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ee2922902c45ae8ccada2c5b501ab86c36525b883eff4255313a253a3160861c", size = 767081, upload-time = "2025-09-25T21:32:26.575Z" },
+ { url = "https://files.pythonhosted.org/packages/49/1e/a55ca81e949270d5d4432fbbd19dfea5321eda7c41a849d443dc92fd1ff7/pyyaml-6.0.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a33284e20b78bd4a18c8c2282d549d10bc8408a2a7ff57653c0cf0b9be0afce5", size = 841159, upload-time = "2025-09-25T21:32:27.727Z" },
+ { url = "https://files.pythonhosted.org/packages/74/27/e5b8f34d02d9995b80abcef563ea1f8b56d20134d8f4e5e81733b1feceb2/pyyaml-6.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0f29edc409a6392443abf94b9cf89ce99889a1dd5376d94316ae5145dfedd5d6", size = 801626, upload-time = "2025-09-25T21:32:28.878Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/11/ba845c23988798f40e52ba45f34849aa8a1f2d4af4b798588010792ebad6/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f7057c9a337546edc7973c0d3ba84ddcdf0daa14533c2065749c9075001090e6", size = 753613, upload-time = "2025-09-25T21:32:30.178Z" },
+ { url = "https://files.pythonhosted.org/packages/3d/e0/7966e1a7bfc0a45bf0a7fb6b98ea03fc9b8d84fa7f2229e9659680b69ee3/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:eda16858a3cab07b80edaf74336ece1f986ba330fdb8ee0d6c0d68fe82bc96be", size = 794115, upload-time = "2025-09-25T21:32:31.353Z" },
+ { url = "https://files.pythonhosted.org/packages/de/94/980b50a6531b3019e45ddeada0626d45fa85cbe22300844a7983285bed3b/pyyaml-6.0.3-cp313-cp313-win32.whl", hash = "sha256:d0eae10f8159e8fdad514efdc92d74fd8d682c933a6dd088030f3834bc8e6b26", size = 137427, upload-time = "2025-09-25T21:32:32.58Z" },
+ { url = "https://files.pythonhosted.org/packages/97/c9/39d5b874e8b28845e4ec2202b5da735d0199dbe5b8fb85f91398814a9a46/pyyaml-6.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:79005a0d97d5ddabfeeea4cf676af11e647e41d81c9a7722a193022accdb6b7c", size = 154090, upload-time = "2025-09-25T21:32:33.659Z" },
+ { url = "https://files.pythonhosted.org/packages/73/e8/2bdf3ca2090f68bb3d75b44da7bbc71843b19c9f2b9cb9b0f4ab7a5a4329/pyyaml-6.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:5498cd1645aa724a7c71c8f378eb29ebe23da2fc0d7a08071d89469bf1d2defb", size = 140246, upload-time = "2025-09-25T21:32:34.663Z" },
+ { url = "https://files.pythonhosted.org/packages/9d/8c/f4bd7f6465179953d3ac9bc44ac1a8a3e6122cf8ada906b4f96c60172d43/pyyaml-6.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:8d1fab6bb153a416f9aeb4b8763bc0f22a5586065f86f7664fc23339fc1c1fac", size = 181814, upload-time = "2025-09-25T21:32:35.712Z" },
+ { url = "https://files.pythonhosted.org/packages/bd/9c/4d95bb87eb2063d20db7b60faa3840c1b18025517ae857371c4dd55a6b3a/pyyaml-6.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:34d5fcd24b8445fadc33f9cf348c1047101756fd760b4dacb5c3e99755703310", size = 173809, upload-time = "2025-09-25T21:32:36.789Z" },
+ { url = "https://files.pythonhosted.org/packages/92/b5/47e807c2623074914e29dabd16cbbdd4bf5e9b2db9f8090fa64411fc5382/pyyaml-6.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:501a031947e3a9025ed4405a168e6ef5ae3126c59f90ce0cd6f2bfc477be31b7", size = 766454, upload-time = "2025-09-25T21:32:37.966Z" },
+ { url = "https://files.pythonhosted.org/packages/02/9e/e5e9b168be58564121efb3de6859c452fccde0ab093d8438905899a3a483/pyyaml-6.0.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b3bc83488de33889877a0f2543ade9f70c67d66d9ebb4ac959502e12de895788", size = 836355, upload-time = "2025-09-25T21:32:39.178Z" },
+ { url = "https://files.pythonhosted.org/packages/88/f9/16491d7ed2a919954993e48aa941b200f38040928474c9e85ea9e64222c3/pyyaml-6.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c458b6d084f9b935061bc36216e8a69a7e293a2f1e68bf956dcd9e6cbcd143f5", size = 794175, upload-time = "2025-09-25T21:32:40.865Z" },
+ { url = "https://files.pythonhosted.org/packages/dd/3f/5989debef34dc6397317802b527dbbafb2b4760878a53d4166579111411e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7c6610def4f163542a622a73fb39f534f8c101d690126992300bf3207eab9764", size = 755228, upload-time = "2025-09-25T21:32:42.084Z" },
+ { url = "https://files.pythonhosted.org/packages/d7/ce/af88a49043cd2e265be63d083fc75b27b6ed062f5f9fd6cdc223ad62f03e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5190d403f121660ce8d1d2c1bb2ef1bd05b5f68533fc5c2ea899bd15f4399b35", size = 789194, upload-time = "2025-09-25T21:32:43.362Z" },
+ { url = "https://files.pythonhosted.org/packages/23/20/bb6982b26a40bb43951265ba29d4c246ef0ff59c9fdcdf0ed04e0687de4d/pyyaml-6.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:4a2e8cebe2ff6ab7d1050ecd59c25d4c8bd7e6f400f5f82b96557ac0abafd0ac", size = 156429, upload-time = "2025-09-25T21:32:57.844Z" },
+ { url = "https://files.pythonhosted.org/packages/f4/f4/a4541072bb9422c8a883ab55255f918fa378ecf083f5b85e87fc2b4eda1b/pyyaml-6.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:93dda82c9c22deb0a405ea4dc5f2d0cda384168e466364dec6255b293923b2f3", size = 143912, upload-time = "2025-09-25T21:32:59.247Z" },
+ { url = "https://files.pythonhosted.org/packages/7c/f9/07dd09ae774e4616edf6cda684ee78f97777bdd15847253637a6f052a62f/pyyaml-6.0.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:02893d100e99e03eda1c8fd5c441d8c60103fd175728e23e431db1b589cf5ab3", size = 189108, upload-time = "2025-09-25T21:32:44.377Z" },
+ { url = "https://files.pythonhosted.org/packages/4e/78/8d08c9fb7ce09ad8c38ad533c1191cf27f7ae1effe5bb9400a46d9437fcf/pyyaml-6.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c1ff362665ae507275af2853520967820d9124984e0f7466736aea23d8611fba", size = 183641, upload-time = "2025-09-25T21:32:45.407Z" },
+ { url = "https://files.pythonhosted.org/packages/7b/5b/3babb19104a46945cf816d047db2788bcaf8c94527a805610b0289a01c6b/pyyaml-6.0.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6adc77889b628398debc7b65c073bcb99c4a0237b248cacaf3fe8a557563ef6c", size = 831901, upload-time = "2025-09-25T21:32:48.83Z" },
+ { url = "https://files.pythonhosted.org/packages/8b/cc/dff0684d8dc44da4d22a13f35f073d558c268780ce3c6ba1b87055bb0b87/pyyaml-6.0.3-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a80cb027f6b349846a3bf6d73b5e95e782175e52f22108cfa17876aaeff93702", size = 861132, upload-time = "2025-09-25T21:32:50.149Z" },
+ { url = "https://files.pythonhosted.org/packages/b1/5e/f77dc6b9036943e285ba76b49e118d9ea929885becb0a29ba8a7c75e29fe/pyyaml-6.0.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:00c4bdeba853cc34e7dd471f16b4114f4162dc03e6b7afcc2128711f0eca823c", size = 839261, upload-time = "2025-09-25T21:32:51.808Z" },
+ { url = "https://files.pythonhosted.org/packages/ce/88/a9db1376aa2a228197c58b37302f284b5617f56a5d959fd1763fb1675ce6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:66e1674c3ef6f541c35191caae2d429b967b99e02040f5ba928632d9a7f0f065", size = 805272, upload-time = "2025-09-25T21:32:52.941Z" },
+ { url = "https://files.pythonhosted.org/packages/da/92/1446574745d74df0c92e6aa4a7b0b3130706a4142b2d1a5869f2eaa423c6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:16249ee61e95f858e83976573de0f5b2893b3677ba71c9dd36b9cf8be9ac6d65", size = 829923, upload-time = "2025-09-25T21:32:54.537Z" },
+ { url = "https://files.pythonhosted.org/packages/f0/7a/1c7270340330e575b92f397352af856a8c06f230aa3e76f86b39d01b416a/pyyaml-6.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4ad1906908f2f5ae4e5a8ddfce73c320c2a1429ec52eafd27138b7f1cbe341c9", size = 174062, upload-time = "2025-09-25T21:32:55.767Z" },
+ { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f6/cc/6253133b5bb138fc3306cebfbda2c520f545d36b5be2c7255cc528bb45d6/typing_extensions-4.16.0.tar.gz", hash = "sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5", size = 113555, upload-time = "2026-07-02T08:40:05.92Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/49/d3/b8441a820a491ddfc024b0b0cf0393375b75ea13866d9c66727e54c2fc80/typing_extensions-4.16.0-py3-none-any.whl", hash = "sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8", size = 45571, upload-time = "2026-07-02T08:40:04.659Z" },
+]