gemini-router 0.1.1__tar.gz

gemini_router-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,11 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra dev
+      - run: uv run ruff check src tests
+      - run: uv run pytest -q

gemini_router-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+*.db
+*.db-wal
+*.db-shm
+logs/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.DS_Store

gemini_router-0.1.1/AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md — gemini-router
+
+Follow the owner's global AGENTS.md (English in files, Russian in chat, PM-style reports,
+Conventional Commits, SemVer tags `v*`, push after every successful step, docs updated
+with functional changes). Repo-specific rules:
+
+## Context
+- Contract: `docs/SPEC.md`; system-wide requirements/architecture/plan live in
+  `vernikr/gemini-mcp/docs/01..04`. Keep SPEC.md as-built after every milestone.
+- This library MUST stay dependency-light (`httpx`, `pydantic`, `rich`, stdlib) and
+  MCP-agnostic — it is consumed by gemini-mcp, tldr-digest (sync facade) and outsiders.
+- All quota truth = SQLite ledger (`GEMINI_ROUTER_STATE`); no in-memory-only counters.
+  Multi-process safety (WAL, busy_timeout) is a hard requirement.
+- Model IDs are volatile (docs/blockers b04 in gemini-mcp): resolve via `listModels`,
+  never hardcode availability; every list config-overridable.
+
+## Commands (as-built; update me)
+- `uv sync` · `uv run pytest` · `uv run ruff check src tests`
+- `uv run gemini-router quota|models|calls|prune|doctor`
+
+## Testing & secrets
+- respx-mocked HTTP only (no network, no real keys in CI/fixtures).
+- Never log or persist raw API keys — `key_id = sha256[:8]`.
+- Ported tldr-digest logic keeps its tested taxonomy (RETRYABLE_STATUS,
+  MODEL_SWITCH_STATUS, Retry-After, extract_json) — extend, don't reinvent.

gemini_router-0.1.1/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: gemini-router
+Version: 0.1.1
+Summary: Quota-aware Gemini Flash router: cascading fallback, per-key/model RPD/RPM/TPM ledger (SQLite WAL), key pool, wait policy, CLI
+Author: vernikr
+License: MIT
+Keywords: gemini,llm,mcp,quota,rate-limit,router
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gemini-router
+
+Quota-aware **Gemini Flash router** as a standalone, reusable module — extracted and
+generalized from [`tldr-digest/src/llm.py`](https://github.com/vernikr/tldr-digest).
+
+One persistent ledger (SQLite WAL) = the single source of quota truth shared by every
+consumer on a machine: the [gemini-mcp](https://github.com/vernikr/gemini-mcp) gateway,
+`tldr-digest` cron runs, CLI calls, foreign scripts.
+
+- Cascading chain with runtime `listModels` validation (default
+  `gemini-3.8-flash → 3.7 → 3.6 → 3.5 → 3-flash-preview-slot`; config-overridable).
+- Per **key×model** budgets: RPD (Pacific-time day + rolling 24 h), RPM, TPM (sliding
+  60 s) — pre-flight enforced, accounted from `usageMetadata`; conservative 429 handling
+  with cooldowns and `Retry-After`.
+- Key pool (`GEMINI_API_KEYS` / `GEMINI_API_KEY_1..10`), budget-maximizing selection.
+- `thinking_level` per request (Gemini 3.x rules), request cache (0-RPD hits), opt-in
+  overflow tiers (`flash-lite → gemma-auto`), event stream for progress frontends.
+- Per-request wait policy for minute-scale gates (RPM/TPM/short cooldowns): default
+  **wait** with countdown events (`waiting`, remaining seconds); `wait=False` skips to
+  the next candidate or returns wait ETAs in the structured error. Daily resets are
+  never waited on.
+- CLI: `gemini-router quota | models | calls | prune | doctor` (rich tables).
+- Deps: `httpx`, `pydantic`, `rich`, stdlib `sqlite3` — **no MCP/web-framework coupling**.
+
+## Status
+
+**v0.1.1 implemented** (milestone M1 of the
+[gemini-mcp plan](https://github.com/vernikr/gemini-mcp/blob/main/docs/04-plan.md)):
+library + CLI, 45 tests green, CI on push. Contract: [`docs/SPEC.md`](docs/SPEC.md).
+
+## Planned usage
+
+```python
+from gemini_router import Router, RouterRequest
+router = Router.from_env()
+res = await router.complete(RouterRequest(prompt=..., thinking_level="high"),
+                            on_event=print)
+```
+
+```bash
+uv add "gemini-router @ git+https://github.com/vernikr/gemini-router.git@v1.0.0"
+gemini-router quota        # RPD left / RPM & TPM windows / cooldowns / next recommendation
+```
+
+Service-style (no Python): REST `/v1/complete` + `/v1/quota` on the gemini-mcp daemon.
+
+Conventions: English in files, Conventional Commits, SemVer tags `v*` (gemini-mcp pins
+a tag), CI = ruff + pytest with mocked HTTP (see `AGENTS.md`).

gemini_router-0.1.1/README.md

@@ -0,0 +1,48 @@
+# gemini-router
+
+Quota-aware **Gemini Flash router** as a standalone, reusable module — extracted and
+generalized from [`tldr-digest/src/llm.py`](https://github.com/vernikr/tldr-digest).
+
+One persistent ledger (SQLite WAL) = the single source of quota truth shared by every
+consumer on a machine: the [gemini-mcp](https://github.com/vernikr/gemini-mcp) gateway,
+`tldr-digest` cron runs, CLI calls, foreign scripts.
+
+- Cascading chain with runtime `listModels` validation (default
+  `gemini-3.8-flash → 3.7 → 3.6 → 3.5 → 3-flash-preview-slot`; config-overridable).
+- Per **key×model** budgets: RPD (Pacific-time day + rolling 24 h), RPM, TPM (sliding
+  60 s) — pre-flight enforced, accounted from `usageMetadata`; conservative 429 handling
+  with cooldowns and `Retry-After`.
+- Key pool (`GEMINI_API_KEYS` / `GEMINI_API_KEY_1..10`), budget-maximizing selection.
+- `thinking_level` per request (Gemini 3.x rules), request cache (0-RPD hits), opt-in
+  overflow tiers (`flash-lite → gemma-auto`), event stream for progress frontends.
+- Per-request wait policy for minute-scale gates (RPM/TPM/short cooldowns): default
+  **wait** with countdown events (`waiting`, remaining seconds); `wait=False` skips to
+  the next candidate or returns wait ETAs in the structured error. Daily resets are
+  never waited on.
+- CLI: `gemini-router quota | models | calls | prune | doctor` (rich tables).
+- Deps: `httpx`, `pydantic`, `rich`, stdlib `sqlite3` — **no MCP/web-framework coupling**.
+
+## Status
+
+**v0.1.1 implemented** (milestone M1 of the
+[gemini-mcp plan](https://github.com/vernikr/gemini-mcp/blob/main/docs/04-plan.md)):
+library + CLI, 45 tests green, CI on push. Contract: [`docs/SPEC.md`](docs/SPEC.md).
+
+## Planned usage
+
+```python
+from gemini_router import Router, RouterRequest
+router = Router.from_env()
+res = await router.complete(RouterRequest(prompt=..., thinking_level="high"),
+                            on_event=print)
+```
+
+```bash
+uv add "gemini-router @ git+https://github.com/vernikr/gemini-router.git@v1.0.0"
+gemini-router quota        # RPD left / RPM & TPM windows / cooldowns / next recommendation
+```
+
+Service-style (no Python): REST `/v1/complete` + `/v1/quota` on the gemini-mcp daemon.
+
+Conventions: English in files, Conventional Commits, SemVer tags `v*` (gemini-mcp pins
+a tag), CI = ruff + pytest with mocked HTTP (see `AGENTS.md`).

gemini_router-0.1.1/docs/SPEC.md

@@ -0,0 +1,126 @@
+# gemini-router · SPEC (stage 2/3 artifact slice)
+
+Date: 2026-10-08 · Companion docs live in `vernikr/gemini-mcp/docs/01..04` (system-wide
+requirements, architecture, plan). This file is the router's own contract; updated as-built
+each milestone.
+
+## 1. What it is
+
+Quota-aware Gemini Flash router extracted from `tldr-digest/src/llm.py`, generalized:
+
+- cascading model chain with runtime `listModels` validation (default
+  `gemini-3.8-flash → 3.7 → 3.6 → 3.5 → 3-flash-preview-slot`);
+- per **key×model** budgets: RPD (America/Los_Angeles day + rolling 24 h), RPM and TPM
+  (sliding 60 s) — enforced pre-flight, accounted post-fact from `usageMetadata`;
+- key pool (`GEMINI_API_KEYS` / `GEMINI_API_KEY_1..10`); selection prefers the pair with
+  the largest remaining budget;
+- persistent multi-process ledger (SQLite WAL) — the single source of quota truth shared
+  by every consumer on the machine (MCP daemon, stdio sessions, cron jobs, foreign scripts);
+- 429/5xx/4xx taxonomy inherited from tldr-digest (`RETRYABLE_STATUS`,
+  `MODEL_SWITCH_STATUS`, `Retry-After`, backoff+jitter, provider deadline);
+- opt-in overflow tiers (`gemini-3.5-flash-lite`, best `gemma-*`) — never automatic;
+- request cache (hash of model+params+prompt, TTL) — hits spend 0 RPD;
+- event stream (`on_event`) for progress reporting by frontends;
+- `thinking_level` (low|medium|high) per request; 3.x rules applied (no
+  temperature/top_p for Gemini 3.x; `thinking_level` not `thinking_budget`);
+- CLI: `quota`, `models`, `calls`, `prune`, `doctor`; sync facade for legacy callers.
+
+Zero MCP/web-framework deps: `httpx`, `pydantic`, `rich`, stdlib `sqlite3`. Python ≥3.12.
+
+## 2. Public API (v1 contract)
+
+```python
+from gemini_router import Router, RouterRequest, RouterResult, RouterEvent, QuotaExhaustedError
+
+router = Router.from_env()            # env + optional GEMINI_ROUTER_CONFIG yaml
+res: RouterResult = await router.complete(
+    RouterRequest(
+        prompt=str, system=str | None = None,
+        thinking_level="low|medium|high" = "high",
+        output_format="text|json" = "text",
+        max_output_tokens=8192,
+        kind="single|chunk|consolidate|count" = "single",
+        request_id=None, source="cli", overflow="off|lite|lite+gemma",
+        wait=True,                    # wait out minute-scale gates (RPM/TPM/short cooldown,
+                                      # ≤ wait.max_s), countdown via `waiting` events;
+                                      # daily RPD resets are NEVER waited on
+        model=None),                  # pin → skips chain fallback
+    on_event=callable | None)         # RouterEvent(stage, pct, model, key_id, wait_s, detail, ts)
+                                      # stages: routing|waiting|dispatch|retry|switch|overflow|ok|quota_exhausted
+
+res.text, res.model, res.key_id, res.tokens_in, res.tokens_out
+res.latency_s, res.cached, res.overflow_tier, res.events, res.quota_after
+await router.count_tokens(text, model=None) -> int
+await router.quota_table() -> list[QuotaRow]   # key_id, model, rpd_left, rpm_wait_s,
+                                               # tpm_wait_s, cooldown_until, recommended
+router.complete_sync(...)                      # blocking facade (tldr-digest migration)
+```
+
+Errors: `QuotaExhaustedError` carries the machine-readable payload
+(per-model rpd_left/rpm_wait_s/tpm_wait_s/cooldown_until, reset_eta_pt, hint) — frontends
+surface it as-is. `RouterError` base for everything else (network, http 4xx, parse).
+
+## 3. Ledger (SQLite, `GEMINI_ROUTER_STATE`, default `/opt/apps/shared/gemini-router/state.db`)
+
+Tables `calls`, `cooldowns`, `cache`, `meta` — full DDL and accounting rules:
+gemini-mcp `docs/03-architecture.md` §3 (single canonical definition).
+Rules summary: WAL + busy_timeout 5 s; TPM pre-flight writes a `status='planned'` row,
+upgraded after the call; RPD counts `ok|quota|http5xx` attempts (conservative),
+not client-validation 4xx/network; PT-midnight + rolling-24h dual gate; retention prune
+via `gemini-router prune` and by frontends' daily task.
+
+## 4. Config
+
+Env: `GEMINI_API_KEYS`/`GEMINI_API_KEY_1..10`, `GEMINI_ROUTER_STATE`,
+`GEMINI_ROUTER_CONFIG` (yaml). YAML keys: `chain`, `overflow_tiers`,
+`limits_per_key_model {rpd,rpm,tpm}`, `overflow_limits {rpd,rpm,tpm}`, `limits_overrides`,
+`quota_day_tz`, `retry {max,backoff_base_s,jitter_max_s,provider_timeout_s,request_delay_s}`,
+`wait {enabled_default,max_s,poll_s}` (FR-C13 semantics), `window_s`, `planned_ttl_s`,
+`models_refresh_h`, `cache_ttl_h`, `state_path`, `base_url`, `temperature` (pre-3.x models
+only), `max_output_tokens_default`, `chars_per_token`. Defaults per gemini-mcp `docs/03-architecture.md` §8. Secrets never logged
+(`key_id = sha256(key)[:8]`).
+
+## 5. Integration guide (external consumers)
+
+```bash
+uv add "gemini-router @ git+https://github.com/vernikr/gemini-router.git@v1.0.0"
+# private repo: export UV_INDEX / use gh auth or a deploy key; see README
+```
+
+Service-style consumption (no Python): REST `POST /v1/complete`, `GET /v1/quota` on the
+gemini-mcp daemon (localhost:8790, bearer) — same ledger, same rules.
+
+## 6. Extraction mapping from tldr-digest/src/llm.py
+
+| tldr-digest | router | Change |
+|---|---|---|
+| `DEFAULT_MODEL_PRIORITY`/`llm_model_priority` | `config.chain` | Gemini-only in v1; groq/openrouter stay in tldr until a provider abstraction is justified |
+| `_resolve_models`/`_list_models`/`_best_available` | `routing.resolve_chain` | + refresh interval, + preview-slot heuristics |
+| `RETRYABLE_STATUS`/`MODEL_SWITCH_STATUS`/`_parse_retry_after`/backoff | `routing` | ported as-is |
+| `Provider.can_call/register_call` (in-memory) | `ledger` queries | persistent, per key×model, + TPM |
+| `_call_gemini` | `gemini.generate` | async httpx, thinking_level, usageMetadata accounting |
+| `extract_json` | `gemini.extract_json` | ported as-is |
+| `complete_json` | `complete(output_format="json")` | superset |
+
+## 7. Versioning & CI
+
+SemVer; tags `v*`; gemini-mcp pins a tag. CI: ruff + pytest (respx mocks, no network) on
+push/PR (free runners). Conventional Commits.
+
+## 8. As-built notes
+
+- v0.1.1 (2026-10-08, live VPS smoke): **thinking-token starvation** discovered —
+  in 3.x models `maxOutputTokens` counts thinking tokens, so a tiny cap (16) yields
+  empty visible text and no `candidatesTokenCount`. Fixes: thought parts
+  (`thought=true`) never join visible text; `GenResult`/`RouterResult` carry
+  `finish_reason` + `tokens_thought`; `max_output_tokens_default` 8192→32768
+  (cap only, no spend implication). 45 tests green.
+- v0.1.0 (M1): full contract above implemented; 43 tests green (ledger dual-gate RPD,
+  planned-row TPM windows, wait policy incl. cap and countdown events, cache +
+  request_id idempotency, overflow lite→gemma, live 429-day cooldown, multi-key pool,
+  countTokens spends no RPD, pinned-model handling).
+- `extract_json` improvement over the tldr original: when several JSON candidates match,
+  the earliest starting in the text wins (fixes nested `{…[…]…}` extraction).
+- Ledger statuses: `planned|ok|quota|http4xx|http5xx|network|blocked|skipped`;
+  RPD-conservative set = `ok,quota,http5xx,blocked` (D3).
+- CLI exit codes: 0 ok, 1 doctor failed, 2 config/usage error.

gemini_router-0.1.1/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "gemini-router"
+version = "0.1.1"
+description = "Quota-aware Gemini Flash router: cascading fallback, per-key/model RPD/RPM/TPM ledger (SQLite WAL), key pool, wait policy, CLI"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "vernikr" }]
+keywords = ["gemini", "router", "quota", "rate-limit", "llm", "mcp"]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "pyyaml>=6.0",
+    "rich>=13.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+    "ruff>=0.6",
+]
+
+[project.scripts]
+gemini-router = "gemini_router.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gemini_router"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

gemini_router-0.1.1/src/gemini_router/__init__.py

@@ -0,0 +1,23 @@
+"""gemini-router — quota-aware Gemini Flash router with a persistent ledger.
+
+Public API (docs/SPEC.md §2):
+    Router, RouterRequest, RouterResult, RouterEvent,
+    RouterError, GeminiHTTPError, QuotaExhaustedError,
+    Config, Limits, Ledger, GeminiClient, extract_json, key_id, estimate_tokens
+"""
+from .config import Config, Limits, RetryCfg, WaitCfg, estimate_tokens, key_id
+from .errors import GeminiHTTPError, QuotaExhaustedError, RouterError
+from .events import RouterEvent
+from .gemini import GeminiClient, GenResult, extract_json, is_gemini3
+from .ledger import Ledger, iso, pt_midnight_ts
+from .routing import Router, RouterRequest, RouterResult, cache_hash, gates_for, pick_gemma
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "Router", "RouterRequest", "RouterResult", "RouterEvent",
+    "RouterError", "GeminiHTTPError", "QuotaExhaustedError",
+    "Config", "Limits", "RetryCfg", "WaitCfg", "Ledger", "GeminiClient", "GenResult",
+    "extract_json", "is_gemini3", "key_id", "estimate_tokens", "cache_hash",
+    "gates_for", "pick_gemma", "pt_midnight_ts", "iso", "__version__",
+]

gemini_router-0.1.1/src/gemini_router/cli.py

@@ -0,0 +1,188 @@
+"""Terminal UX (FR-C12): quota | models | calls | prune | doctor. Works over SSH
+against the shared state file without touching the daemon (FR-E7)."""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+from .config import Config
+from .errors import RouterError
+from .ledger import Ledger, iso, pt_midnight_ts
+from .routing import Router, pick_gemma
+
+console = Console()
+
+
+def _load_cfg(args) -> Config:
+    over = {"state_path": args.state} if getattr(args, "state", None) else {}
+    return Config.load(getattr(args, "config", None), **over)
+
+
+def _router(cfg: Config) -> Router:
+    return Router(cfg, ledger=Ledger(cfg.state_path))
+
+
+def cmd_quota(cfg: Config, args) -> int:
+    rows = _router(cfg).quota_table()
+    if args.json:
+        print(json.dumps(rows, indent=1, default=str))
+        return 0
+    t = Table(title="Gemini quota (per key×model)", title_style="bold cyan", expand=True)
+    for col in ("key", "model", "RPD left", "RPM win", "TPM win", "cooldown", "next"):
+        t.add_column(col)
+    for r in rows:
+        wait = f"{r['wait_s']:.0f}s ({r['reason']})" if r["wait_s"] > 0 else "—"
+        style = "green" if r["rpd_left"] > 0 and r["wait_s"] <= 0 else (
+            "yellow" if r["rpd_left"] > 0 else "red")
+        rpm_w = wait if r["reason"] == "rpm" else ""
+        tpm_w = wait if r["reason"] == "tpm" else ""
+        t.add_row(r["key_id"], f"[{style}]{r['model']}[/{style}]",
+                  f"{r['rpd_left']}/{r['rpd_limit']}",
+                  f"{r['rpm_used']}/{r['rpm_limit']} {rpm_w}".strip(),
+                  f"{r['tpm_used']}/{r['tpm_limit']} {tpm_w}".strip(),
+                  iso(r["cooldown_until"])[:19] if r["cooldown_until"] else "—",
+                  "★" if r["recommended"] else "")
+    console.print(t)
+    return 0
+
+
+def cmd_models(cfg: Config, args) -> int:
+    async def _run() -> dict:
+        r = _router(cfg)
+        try:
+            return await r.availability() if not args.offline else {}
+        finally:
+            await r.aclose()
+    avail = asyncio.run(_run())
+    union: set[str] = set()
+    for s in avail.values():
+        if s:
+            union |= s
+    out = {"chain": cfg.chain, "overflow_tiers": cfg.overflow_tiers,
+           "gemma_pick": pick_gemma(union) if union else None,
+           "per_key": {k: (sorted(v) if v else "listModels unavailable → trust config")
+                       for k, v in avail.items()},
+           "missing_from_live": sorted(m for m in cfg.chain if union and m not in union)}
+    if args.json:
+        print(json.dumps(out, indent=1))
+        return 0
+    console.print_json(json.dumps(out, indent=1))
+    return 0
+
+
+def cmd_calls(cfg: Config, args) -> int:
+    rows = Ledger(cfg.state_path).calls_tail(
+        args.n, model=args.model, status=args.status, source=args.source,
+        request_id=args.request_id)
+    if args.json:
+        print(json.dumps(rows, indent=1, default=str))
+        return 0
+    t = Table(title=f"Last {len(rows)} calls", expand=True)
+    for col in ("ts (UTC)", "src", "kind", "key", "model", "status", "http",
+                "in", "out", "ms", "tier"):
+        t.add_column(col, overflow="fold")
+    for r in reversed(rows):
+        style = {"ok": "green", "quota": "red", "http5xx": "yellow",
+                 "network": "yellow", "blocked": "magenta"}.get(r["status"], "dim")
+        t.add_row(r["ts_iso"][:19], r["source"], r["kind"], r["key_id"], r["model"],
+                  f"[{style}]{r['status']}[/{style}]", str(r["http_status"] or ""),
+                  str(r["tokens_in"] or ""), str(r["tokens_out"] or ""),
+                  str(r["latency_ms"] or ""), str(r["overflow_tier"]))
+    console.print(t)
+    return 0
+
+
+def cmd_prune(cfg: Config, args) -> int:
+    res = Ledger(cfg.state_path).prune(
+        audit_keep_days=args.audit_days, cache_ttl_s=cfg.cache_ttl_h * 3600, dry=args.dry)
+    console.print(("DRY " if args.dry else "") + json.dumps(res))
+    return 0
+
+
+def cmd_doctor(cfg: Config, args) -> int:
+    ok = True
+    console.print(f"[bold]gemini-router {__version__} doctor[/bold]")
+    console.print(f"  state: {cfg.state_path}")
+    try:
+        led = Ledger(cfg.state_path)
+        console.print(f"  state stats: {led.stats()}")
+    except Exception as e:  # noqa: BLE001
+        console.print(f"  [red]state unusable: {e}[/red]")
+        return 1
+    if cfg.api_keys:
+        from .config import key_id
+        console.print(f"  keys: {len(cfg.api_keys)} → "
+                      + ", ".join(key_id(k) for k in cfg.api_keys))
+    else:
+        console.print("  [red]no API keys configured "
+                      "(GEMINI_API_KEYS / GEMINI_API_KEY_1..10)[/red]")
+        ok = False
+    tz_now = pt_midnight_ts(cfg.quota_day_tz)
+    console.print(f"  quota day ({cfg.quota_day_tz}): resets in "
+                  f"{(pt_midnight_ts(cfg.quota_day_tz, days_ahead=1) - tz_now) / 3600:.1f} h "
+                  f"(midnight was {iso(tz_now)[:19]} UTC)")
+    console.print(f"  chain: {' → '.join(cfg.chain)}")
+    console.print(f"  limits/key×model: {cfg.limits_per_key_model.model_dump()} · "
+                  f"overflow: {cfg.overflow_limits.model_dump()} · "
+                  f"wait: {cfg.wait.model_dump()}")
+    if not args.offline and cfg.api_keys:
+        async def _probe() -> None:
+            r = _router(cfg)
+            try:
+                avail = await r.availability()
+                for kid, models in avail.items():
+                    if models is None:
+                        console.print(f"  [yellow]key {kid}: listModels failed (offline?)[/yellow]")
+                    else:
+                        have = [m for m in cfg.chain if m in models]
+                        console.print(f"  key {kid}: {len(models)} models live; chain available: "
+                                      + (", ".join(have) or "[red]NONE[/red]"))
+            finally:
+                await r.aclose()
+        asyncio.run(_probe())
+    console.print("[green]OK[/green]" if ok else "[red]FAILED[/red]")
+    return 0 if ok else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="gemini-router",
+                                 description="Quota-aware Gemini Flash router CLI")
+    ap.add_argument("--config", help="YAML config path (or GEMINI_ROUTER_CONFIG)")
+    ap.add_argument("--state", help="override state db path (or GEMINI_ROUTER_STATE)")
+    ap.add_argument("--version", action="version", version=f"gemini-router {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("quota", help="live budget table (which model can take a request)")
+    p.add_argument("--json", action="store_true")
+    p = sub.add_parser("models", help="resolved chain vs live listModels")
+    p.add_argument("--offline", action="store_true")
+    p.add_argument("--json", action="store_true")
+    p = sub.add_parser("calls", help="audit log tail")
+    p.add_argument("-n", type=int, default=50)
+    for flag in ("--model", "--status", "--source", "--request-id"):
+        p.add_argument(flag)
+    p.add_argument("--json", action="store_true")
+    p = sub.add_parser("prune", help="apply retention (audit days, cache TTL)")
+    p.add_argument("--audit-days", type=float, default=30)
+    p.add_argument("--dry", action="store_true")
+    p = sub.add_parser("doctor", help="config/state/connectivity check")
+    p.add_argument("--offline", action="store_true")
+
+    args = ap.parse_args(argv)
+    handlers = {"quota": cmd_quota, "models": cmd_models, "calls": cmd_calls,
+                "prune": cmd_prune, "doctor": cmd_doctor}
+    try:
+        cfg = _load_cfg(args)
+        return handlers[args.cmd](cfg, args)
+    except RouterError as e:
+        console.print(f"[red]error:[/red] {e}")
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gemini_router-0.1.1/src/gemini_router/config.py

@@ -0,0 +1,98 @@
+"""Config: pydantic model + YAML/env loading (SPEC §4). Defaults mirror
+gemini-mcp docs/03 §8. Secrets come only from env; never from YAML."""
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field
+
+DEFAULT_CHAIN = ["gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash",
+                 "gemini-3.5-flash", "gemini-3-flash-preview"]
+DEFAULT_OVERFLOW = ["gemini-3.5-flash-lite", "gemma-auto"]
+
+
+class Limits(BaseModel):
+    rpd: int = 20
+    rpm: int = 5
+    tpm: int = 250_000
+
+
+class RetryCfg(BaseModel):
+    max: int = 3
+    backoff_base_s: float = 5.0
+    jitter_max_s: float = 2.0
+    provider_timeout_s: float = 120.0
+    request_delay_s: float = 2.0
+
+
+class WaitCfg(BaseModel):
+    enabled_default: bool = True   # FR-C13: wait out minute-scale gates by default
+    max_s: float = 65.0
+    poll_s: float = 2.0
+
+
+class Config(BaseModel):
+    chain: list[str] = Field(default_factory=lambda: list(DEFAULT_CHAIN))
+    overflow_tiers: list[str] = Field(default_factory=lambda: list(DEFAULT_OVERFLOW))
+    limits_per_key_model: Limits = Field(default_factory=Limits)
+    overflow_limits: Limits = Field(default_factory=lambda: Limits(rpd=500, rpm=15, tpm=250_000))
+    limits_overrides: dict[str, dict[str, int]] = Field(default_factory=dict)
+    quota_day_tz: str = "America/Los_Angeles"
+    retry: RetryCfg = Field(default_factory=RetryCfg)
+    wait: WaitCfg = Field(default_factory=WaitCfg)
+    window_s: float = 60.0                     # sliding RPM/TPM window
+    planned_ttl_s: float = 300.0               # stale 'planned' rows stop counting after this
+    models_refresh_h: float = 12.0
+    cache_ttl_h: float = 24.0
+    state_path: str = "state.db"
+    base_url: str = "https://generativelanguage.googleapis.com/v1beta"
+    api_keys: list[str] = Field(default_factory=list)
+    temperature: float | None = None           # applied to pre-3.x models only
+    max_output_tokens_default: int = 32768   # cap only; 3.x thinking tokens count toward it
+    chars_per_token: int = 4                   # estimate when countTokens not provided
+
+    @classmethod
+    def load(cls, path: str | Path | None = None, **over) -> Config:
+        data: dict = {}
+        p = path or os.environ.get("GEMINI_ROUTER_CONFIG")
+        if p and Path(p).exists():
+            raw = yaml.safe_load(Path(p).read_text(encoding="utf-8")) or {}
+            data = raw.get("router", raw) if isinstance(raw.get("router"), dict) else raw
+        keys = _env_keys()
+        if keys:
+            data["api_keys"] = keys
+        if os.environ.get("GEMINI_ROUTER_STATE"):
+            data["state_path"] = os.environ["GEMINI_ROUTER_STATE"]
+        data.update({k: v for k, v in over.items() if v is not None})
+        return cls.model_validate(data)
+
+    def limits_for(self, model: str) -> Limits:
+        base = (self.limits_per_key_model if model in self.chain else self.overflow_limits)
+        merged = base.model_dump() | self.limits_overrides.get(model, {})
+        return Limits(**merged)
+
+
+def _env_keys() -> list[str]:
+    keys: list[str] = []
+    v = os.environ.get("GEMINI_API_KEYS", "")
+    keys += [k.strip() for k in v.split(",") if k.strip()]
+    for i in range(1, 11):
+        k = os.environ.get(f"GEMINI_API_KEY_{i}", "").strip()
+        if k:
+            keys.append(k)
+    k = os.environ.get("GEMINI_API_KEY", "").strip()
+    if k:
+        keys.append(k)
+    return list(dict.fromkeys(keys))
+
+
+def key_id(key: str) -> str:
+    """Masked key identity for logs/ledger (FR-E8): never store raw keys."""
+    return hashlib.sha256(key.encode()).hexdigest()[:8]
+
+
+def estimate_tokens(text: str, chars_per_token: int = 4) -> int:
+    return max(1, len(text) // max(1, chars_per_token))