tokenbiryani 0.2.0__tar.gz

tokenbiryani-0.2.0/.dockerignore

@@ -0,0 +1,59 @@
+# Keep the build context small and the image free of anything that is not the
+# application. Everything here is either regenerated, machine-local, or a secret.
+
+# --- VCS and CI ---
+.git
+.gitignore
+.github
+
+# --- local environments ---
+.venv
+venv
+env
+.env
+.env.*
+
+# --- Python build and cache artefacts ---
+__pycache__
+*.py[cod]
+*.egg-info
+dist
+build
+.eggs
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.coverage
+.coverage.*
+htmlcov
+.tox
+.nox
+
+# --- not part of the application ---
+benchmarks
+docs
+site
+mkdocs.yml
+scripts
+*.md
+!README.md
+
+# --- editor and OS noise ---
+.idea
+.vscode
+.DS_Store
+Thumbs.db
+
+# --- state, credentials and anything machine-local ---
+# The image must never carry a config or a key baked in: both are mounted or
+# passed as environment at run time.
+tokenbiryani.yaml
+*.db
+*.db-shm
+*.db-wal
+*.sqlite3
+*.key
+.manual-test-key
+docker-compose.yml
+Dockerfile
+.dockerignore

tokenbiryani-0.2.0/.env.example

@@ -0,0 +1,19 @@
+# Copy to .env and edit. docker compose reads .env automatically; it is gitignored.
+#
+#   cp .env.example .env
+#   docker compose run --rm --no-deps gateway keygen           # TOKENBIRYANI_KEY
+#   docker compose run --rm --no-deps gateway keygen --secret  # TOKENBIRYANI_SECRET_KEY
+
+# The virtual key your clients authenticate with. Anything starting bir_ works.
+TOKENBIRYANI_KEY=bir_dev_only_change_me_0123456789
+
+# Encrypts account credentials before they reach Redis. Redis outlives the
+# container, so this key must too — lose it and the accounts you added from the
+# console are unrecoverable. Leave blank only for a throwaway stack.
+TOKENBIRYANI_SECRET_KEY=
+
+# Optional. The stack boots against a bundled mock upstream without it; set it only
+# if you uncomment the real account in docker/tokenbiryani.yaml. Adding accounts
+# from the console is the better path — they are stored encrypted and can be
+# renamed, tested and rotated in place.
+ANTHROPIC_API_KEY=

tokenbiryani-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,55 @@
+name: Bug report
+description: Something behaved differently from what the docs say.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please do not paste API keys, virtual keys, or prompt contents. The request
+        id from `/admin/requests` and the account id are usually enough.
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      placeholder: "0.1.0, or a commit sha"
+    validations: { required: true }
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Where
+      options:
+        - Routing / failover
+        - Streaming
+        - Rate limits, leases or the queue
+        - Session affinity / prompt cache
+        - Keys and auth
+        - Console or admin API
+        - CLI
+        - A provider adapter (Bedrock / Vertex)
+        - Config or startup
+        - Something else
+    validations: { required: true }
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected, and what happened instead
+    validations: { required: true }
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction
+      description: >
+        The most useful form is a failing test against the mock upstream
+        (`tests/support/mock_upstream.py`) — see CONTRIBUTING.
+      render: python
+  - type: textarea
+    id: config
+    attributes:
+      label: Relevant config
+      description: Redact api_key and key values.
+      render: yaml
+  - type: textarea
+    id: logs
+    attributes:
+      label: Log lines or the request inspector output
+      render: shell

tokenbiryani-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,6 @@
+blank_issues_enabled: true
+# A contact_link needs an absolute URL, and this repository has no home yet, so
+# pointing at a private-advisory page would be a dead link on the one form people
+# use when something is wrong. GitHub surfaces SECURITY.md by itself, and that file
+# says how to report privately.
+contact_links: []

tokenbiryani-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: Feature request
+description: Propose something the gateway should do.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to do that you cannot do today?
+    validations: { required: true }
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+  - type: dropdown
+    id: shape
+    attributes:
+      label: Does this fit an existing extension point?
+      description: >
+        Routing strategies and provider adapters can ship as separate packages;
+        see CONTRIBUTING. If yours fits one, it may not need to live here.
+      options:
+        - A routing strategy
+        - A provider adapter
+        - A state store backend
+        - Neither — it needs to be in the core
+    validations: { required: true }

tokenbiryani-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,29 @@
+## What this changes
+
+<!-- One or two sentences. -->
+
+## Why
+
+<!-- The problem, not the patch. -->
+
+## Checks
+
+- [ ] `ruff check .`
+- [ ] `mypy`
+- [ ] `pytest`
+- [ ] Tests cover the behaviour, not the implementation detail
+- [ ] `CHANGELOG.md` has a line under `## [Unreleased]` — or the `no-changelog`
+      label, because this changes nothing a user would notice
+
+## House rules this touches
+
+<!-- Delete what does not apply, and say how you kept to the rest. -->
+
+- [ ] **Router, not a rewriter** — nothing modifies a request body outside
+      `providers/translate.py`
+- [ ] **Shared state goes through `StateStore`** — no reaching around it
+- [ ] **New failure modes go in the taxonomy** — account action and request action
+      stay separate decisions
+- [ ] **No prompt bodies logged** on any default path
+- [ ] Cache hit rate is not quietly traded away — `benchmarks/cache_affinity.py`
+      still shows sticky winning

tokenbiryani-0.2.0/.github/workflows/changelog.yml

@@ -0,0 +1,44 @@
+name: changelog
+
+# Its own file, and not a job in ci.yml, because of the label. `pull_request` without
+# a `types` list means [opened, synchronize, reopened] — so applying `no-changelog`
+# would never re-run the check that the label exists to switch off, and the required
+# check would stay red until the author pushed an unrelated commit. Listing the label
+# events here fixes that without re-running the whole test matrix every time someone
+# tidies up a label.
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+concurrency:
+  group: changelog-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  changelog:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - name: The change is described in CHANGELOG.md
+        if: ${{ !contains(github.event.pull_request.labels.*.name, 'no-changelog') }}
+        env:
+          BASE: ${{ github.base_ref }}
+        run: |
+          git fetch --no-tags origin "$BASE"
+          if git diff --name-only "origin/$BASE...HEAD" | grep -qx 'CHANGELOG.md'; then
+            echo "CHANGELOG.md updated."
+            exit 0
+          fi
+          echo "::error file=CHANGELOG.md::This pull request changes nothing in \
+          CHANGELOG.md. Add a line under '## [Unreleased]' describing what changed \
+          for someone upgrading — or apply the 'no-changelog' label if it genuinely \
+          changes nothing a user would notice (a test, a refactor, a typo)."
+          exit 1
+      - name: Labelled no-changelog
+        if: ${{ contains(github.event.pull_request.labels.*.name, 'no-changelog') }}
+        run: echo "Labelled no-changelog — nothing a user would notice. Not checking."

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

@@ -0,0 +1,235 @@
+name: ci
+
+# Every push to the trunk, every pull request, and — through `workflow_call` — every
+# tag, because release.yml runs this whole file before it publishes anything. There is
+# one definition of "green" and the release gate uses it rather than a second copy.
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+# A force-push or a quick second commit supersedes the run before it. Without this the
+# queue fills with runs nobody will read, which on a free plan is the whole budget.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# Least privilege by default. The jobs that need more ask for it themselves.
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      # The type check targets 3.8 regardless of the runner, so once is enough. It is
+      # deliberately not strict: it exists to catch Optional handling that would crash
+      # at runtime, not to make anyone annotate every local.
+      - run: mypy
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      # The browser suites are excluded here and run in `ui`, once, against a pinned
+      # Chromium. They used to run in every matrix entry against whatever Chrome the
+      # runner happened to ship, which made a real timeout look like a 3.8 problem.
+      - run: |
+          pytest -q \
+            --ignore=tests/test_console_ui.py \
+            --ignore=tests/test_onboarding_ui.py \
+            --cov=tokenbiryani --cov-report=term-missing --cov-fail-under=80
+
+  redis:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    services:
+      redis:
+        image: redis:7
+        ports: ["6379:6379"]
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s --health-timeout 3s --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      # The suite covers the Redis backend with fakeredis; this job runs the same
+      # store against a real server, where inclusive/exclusive range semantics bite.
+      - run: pytest -q tests/test_store.py
+        env:
+          TOKENBIRYANI_REDIS_URL: redis://127.0.0.1:6379/0
+
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: bash scripts/smoke.sh
+
+  ui:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: python -m playwright install --with-deps chromium
+      # Drives the real console in a real browser. The static assertions in
+      # tests/test_console.py cannot catch a panel that renders empty.
+      - run: pytest -q tests/test_console_ui.py tests/test_onboarding_ui.py
+        env:
+          TOKENBIRYANI_UI_BROWSER: chromium
+
+  docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[docs]"
+      # --strict turns a broken internal link into a failure, which is the only way
+      # docs links stay correct.
+      - run: mkdocs build --strict
+
+  package:
+    # A wheel that does not build, or that quietly starts shipping the test doubles
+    # again, is only discovered at release time otherwise — which is the worst moment.
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - name: The wheel carries the package and nothing else
+        run: |
+          wheel=$(ls dist/*.whl)
+          python - "$wheel" <<'PY'
+          import sys, zipfile
+          names = zipfile.ZipFile(sys.argv[1]).namelist()
+          assert any(n.endswith("prices.yaml") for n in names), "prices.yaml missing"
+          assert any(n.endswith("console.html") for n in names), "console.html missing"
+          leaked = [n for n in names if "/testing/" in n or n.startswith("tests/")]
+          assert not leaked, f"test scaffolding in the wheel: {leaked}"
+          print("wheel contents look right")
+          PY
+
+  docker:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: tokenbiryani:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      # Prove the image boots and serves, not just that it builds.
+      - name: Run the image
+        run: |
+          cat > ci.yaml <<'YAML'
+          server: {host: 0.0.0.0, port: 8787, allow_remote: true}
+          accounts:
+            - {id: acct-01, type: anthropic_api, api_key: unused, base_url: "http://127.0.0.1:1"}
+          keys:
+            - {key: bir_ci_key_0123456789abcdef, name: ci, admin: true}
+          YAML
+          cid=$(docker run -d -p 8787:8787 \
+            -v "$PWD/ci.yaml:/app/tokenbiryani.yaml:ro" tokenbiryani:ci)
+          for _ in $(seq 40); do
+            curl -sf -o /dev/null http://127.0.0.1:8787/healthz && break || sleep 0.5
+          done
+          curl -sf http://127.0.0.1:8787/healthz
+          curl -sf http://127.0.0.1:8787/console | grep -q "tokenbiryani console"
+          # The console is a page plus a stylesheet now. A missing stylesheet still
+          # serves a 200 page, so check the asset itself.
+          curl -sf http://127.0.0.1:8787/console.css | grep -q -- "--ready:"
+          # Adding an account needs cryptography and a writable key path, and the
+          # image had neither. Nothing above this line would have caught that.
+          curl -sf -X POST http://127.0.0.1:8787/admin/accounts \
+            -H "x-api-key: bir_ci_key_0123456789abcdef" \
+            -H "content-type: application/json" \
+            -d '{"id":"ci-added","name":"Added in CI","api_key":"sk-ant-unused"}' \
+            | grep -q '"name": *"Added in CI"'
+          curl -sf "http://127.0.0.1:8787/admin/usage?window=1h" \
+            -H "x-api-key: bir_ci_key_0123456789abcdef" | grep -q '"buckets"'
+          test "$(docker exec "$cid" id -un)" = tokenbiryani
+          docker rm -f "$cid"
+
+      # The dev target is what docker-compose.yml builds, so a break in it breaks
+      # every contributor's stack while the released image stays green.
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          target: dev
+          load: true
+          tags: tokenbiryani:dev
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      - name: The whole stack comes up, empty, and takes its first account
+        run: |
+          # No --wait on the gateway: the stack ships with an empty pool on purpose,
+          # /healthz answers 503 until an account exists, and the container is
+          # therefore "unhealthy" by design until someone adds one. That first-run
+          # state is exactly what this asserts, and then it adds the account.
+          KEY=bir_dev_only_change_me_0123456789
+          docker compose up -d
+          for _ in $(seq 60); do
+            curl -s -o /dev/null http://127.0.0.1:8787/console && break || sleep 1
+          done
+          curl -s http://127.0.0.1:8787/healthz | grep -q '"status": *"no_capacity"'
+          curl -sf http://127.0.0.1:8787/console.css > /dev/null
+          curl -sf -X POST http://127.0.0.1:8787/admin/accounts \
+            -H "x-api-key: $KEY" -H "content-type: application/json" \
+            -d '{"id":"compose-first","name":"First account","api_key":"sk-ant-unused"}' \
+            | grep -q '"name": *"First account"'
+          # The account is encrypted into Redis by the console's own path, so this
+          # also proves the compose stack can reach and write to its store.
+          curl -sf http://127.0.0.1:8787/healthz | grep -q '"ready": *1'
+          if docker compose logs gateway | grep -qi traceback; then
+            echo "::error::the gateway logged a traceback while coming up"
+            docker compose logs gateway
+            exit 1
+          fi
+          docker compose down -v

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

@@ -0,0 +1,186 @@
+name: release
+
+# A tag is the only thing that releases. Nothing here runs from a branch, a button or
+# a schedule, so "what is in 0.2.0" always has one answer: whatever v0.2.0 points at.
+on:
+  push:
+    tags: ["v*"]
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  # The tag has to agree with the tree it points at before anything is built. All
+  # three of these have been wrong in real projects: a tag one commit early, a
+  # version bump nobody made, and a release whose notes describe the version before.
+  guard:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      prerelease: ${{ steps.version.outputs.prerelease }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install packaging
+      # PEP 440 decides what a pre-release is, rather than a substring match that
+      # calls v1.0.0-alpha and v1.0.0 the same thing because both contain an "a".
+      - id: version
+        run: |
+          python - <<'PY' >> "$GITHUB_OUTPUT"
+          import os
+          from packaging.version import InvalidVersion, Version
+
+          tag = os.environ["GITHUB_REF_NAME"].lstrip("v")
+          try:
+              parsed = Version(tag)
+          except InvalidVersion:
+              raise SystemExit(f"::error::{tag!r} is not a PEP 440 version")
+          print(f"version={tag}")
+          print(f"prerelease={str(parsed.is_prerelease).lower()}")
+          PY
+      - name: The tag, pyproject.toml and __init__.py say the same version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pyproject=$(python -c "import re,pathlib;print(re.search(r'^version = \"([^\"]+)\"', pathlib.Path('pyproject.toml').read_text(), re.M).group(1))")
+          dunder=$(python -c "import re,pathlib;print(re.search(r'__version__ = \"([^\"]+)\"', pathlib.Path('src/tokenbiryani/__init__.py').read_text()).group(1))")
+          echo "tag=$tag pyproject=$pyproject __init__=$dunder"
+          if [ "$tag" != "$pyproject" ] || [ "$tag" != "$dunder" ]; then
+            echo "::error::the tag and the tree disagree about the version. Bump both files, commit, then move the tag."
+            exit 1
+          fi
+      - name: The changelog describes it
+        run: python scripts/changelog.py check "$GITHUB_REF_NAME"
+
+  # The full suite, from ci.yml rather than a second copy of it. A release that skips
+  # the tests is the only kind of release worth refusing outright.
+  verify:
+    needs: [guard]
+    uses: ./.github/workflows/ci.yml
+    permissions:
+      contents: read
+
+  github-release:
+    needs: [guard, verify]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write        # create the release and upload the artifacts
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      # The notes are quoted from CHANGELOG.md, never retyped — see scripts/changelog.py.
+      - name: Release notes, from the changelog
+        run: |
+          {
+            python scripts/changelog.py extract "$GITHUB_REF_NAME"
+            echo
+            echo "---"
+            echo
+            echo '```bash'
+            echo "pip install tokenbiryani==${{ needs.guard.outputs.version }}"
+            echo "docker pull ghcr.io/${{ github.repository }}:${{ needs.guard.outputs.version }}"
+            echo '```'
+          } > notes.md
+      # `gh` ships on the runner and authenticates with the job's own token, so the
+      # release is created without trusting a third-party action with contents:write.
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PRERELEASE: ${{ needs.guard.outputs.prerelease }}
+        run: |
+          flags=""
+          [ "$PRERELEASE" = "true" ] && flags="--prerelease"
+          gh release create "$GITHUB_REF_NAME" \
+            --title "tokenbiryani ${{ needs.guard.outputs.version }}" \
+            --notes-file notes.md \
+            $flags \
+            dist/*.whl dist/*.tar.gz
+
+  pypi:
+    needs: [guard, verify]
+    # Off until a PyPI trusted publisher exists for this repository. Set the
+    # repository variable PYPI_PUBLISH to "true" once it does:
+    #
+    #   gh variable set PYPI_PUBLISH --body true
+    #
+    # Gated rather than deleted because the alternative — an unconditional publish
+    # step — turns every tag into a failed release until the day PyPI is configured,
+    # and a red release is one nobody reads the notes of.
+    if: vars.PYPI_PUBLISH == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write        # trusted publishing; there is no API token to leak
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  ghcr:
+    needs: [guard, verify]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable=${{ needs.guard.outputs.prerelease == 'false' }}
+      # The default target: wheel only, no source, no test dependencies.
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  docs:
+    needs: [guard, verify]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write        # pushes the built site to gh-pages
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[docs]"
+      - run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          mkdocs gh-deploy --force