eggpool 0.3.6__tar.gz → 0.3.7__tar.gz

{eggpool-0.3.6 → eggpool-0.3.7}/AGENTS.md

@@ -11,6 +11,7 @@ Project-specific skills are in `.opencode/skills/`:
 ## Quick Start
 
 - Package manager: **uv** (not pip). Install deps: `uv sync --extra dev`
+- CI installs with `uv sync --frozen --extra dev` (locks match `uv.lock` exactly)
 - Entry point: `src/eggpool/cli.py` → `eggpool` console script
 - Config: `config.toml` + `.env` for API keys
 
@@ -25,6 +26,17 @@ uv run pytest
 
 All four must pass with zero errors.
 
+## Focused Verification
+
+```bash
+uv run pytest tests/unit/test_contract.py -v            # single test file
+uv run pytest tests/unit/ -v                             # all unit tests
+uv run pytest -k "test_something" -v                     # single test by name
+uv run ruff check --fix src/                             # auto-fix lint in one dir
+```
+
+CI sets `PYTHONHASHSEED=0` and `TZ=UTC`; reproduce locally for deterministic results.
+
 ## Code Style
 
 - Python 3.11+ with `from __future__ import annotations` in ALL files
@@ -57,6 +69,7 @@ All four must pass with zero errors.
 - **Request lifecycle**: `RequestCoordinator` orchestrates endpoint → routing → persistence → dispatch → finalization. See `architecture/README.md` § Request Lifecycle.
 - **Multi-provider architecture**: provider-suffixed model IDs (`model-id/provider-id`), `ProviderClientPool`, `OutboundClientManager`. See `architecture/README.md` § Multi-Provider Architecture.
 - **Provider contracts**: `compose_provider_url()` is the single source of truth for upstream URLs. See `architecture/README.md` § Provider Contracts and § Provider Contract Rendering.
+- **Protocol transcoding**: transparent request/response format conversion between OpenAI and Anthropic protocols. Phase 2 body translation, Phase 3 streaming SSE translation, Phase 4 routing eligibility widening, and Phase 5 operator controls and docs are implemented in `src/eggpool/transcoder/` and `src/eggpool/request/coordinator.py`. See `architecture/README.md` § Protocol Transcoding.
 - **Database invariants**: SQLite WAL, single-connection serialization, `async with db.transaction():` for all DML. See `architecture/README.md` § Database.
 - **Quota and routing**: tier-based routing via `routing_priority`, `QuotaFairScorer`, upstream-authoritative suppression. See `architecture/README.md` § Quota and Routing.
 - **Error hierarchy**: `AggregatorError` → `UpstreamError` → specific subclasses. See `architecture/README.md` § Error Hierarchy.
@@ -68,16 +81,21 @@ All four must pass with zero errors.
 
 - Configuration changes require a service restart; live reload is intentionally not supported
 - No pre-commit hooks are configured in this repo; CI runs ruff, pyright, and pytest via GitHub Actions
-- **`static_models` is the source of truth for provider-specific protocol** — `FAMILY_PROTOCOLS` (`src/eggpool/catalog/protocols.py`) is a global fallback that applies when no explicit override exists. Providers like `minimax-cn` that serve MiniMax models on the OpenAI-compatible surface **must** ship `[[providers.<id>.static_models]]` rows with `protocol = "openai"`, otherwise the live `/v1/models` fetch resolves `MiniMax-M*` via the `minimax-` family prefix to `anthropic` and the provider protocol constraint check (`src/eggpool/catalog/service.py:533-545`) clears the protocol to `None`, producing `ModelUnavailableError("Model 'MiniMax-M3' has unresolved protocol")` instead of the more obvious 400 `ProtocolMismatchError`. Static seeds with `protocol_source = "static_config"` survive the live merge via `ModelCatalogCache._preserve_static_fields` (`src/eggpool/catalog/cache.py:146-187`). The same model ID may also be flipped on a per-provider basis via `[providers.<id>.model_overrides."<model-id>"].protocol = "openai"` for operator overrides that go beyond the bundled template.
-- **Upstream-authoritative suppression**: local quota estimates are advisory by default (`local_quota_mode = "score_only"`). Above-capacity accounts stay eligible; only upstream-observed failures (429/402/5xx/auth) and explicit operator disablement suppress routing. Switch to `hard_cap` only as an opt-in escape hatch.
-- **Backoff persistence**: upstream-derived backoffs survive restarts via the `account_backoffs` table (`src/eggpool/db/schema/0024_account_backoffs.sql`). Hydration runs at startup after account sync, best-effort (never blocks boot). Local cost overruns must never be persisted as backoff rows.
-- **Synthetic 503 vs 502**: `ModelUnavailableError` (503) is reserved for genuine pre-dispatch unavailability. `UpstreamExhaustedError` (502) is raised when every candidate account was attempted and exhausted mid-request. Single-account upstream errors pass through to the client rather than becoming synthetic 503s.
-- **Streaming finalizer shielding**: streaming `_build_stream_generator` finalization runs under `asyncio.shield(asyncio.wait_for(..., timeout=10))` so ASGI task cancellation cannot kill the finalizer while it holds the DB lock. Leaks that escape this path are caught by the periodic `stale_request_finalizer` background task (`app._finalize_stale_requests`, runs every 60s) which force-finalizes any request that has been `pending` longer than `upstream.read_timeout_s`.
-- **Startup crash recovery**: `_crash_recovery` runs at every startup and recovers ALL pending requests and ALL active reservations with no time threshold. A process restart is a definitive boundary, so leaked state from the previous process is unconditionally cleaned up. If `Crash recovery: marked N stale requests` appears in logs, the safety net caught leaks from the previous run.
-- **Pricing pipeline**: prices flow TOML override → upstream metadata → external catalog (OpenRouter / OpenCode Zen via the alias registry). Cost precedence: `provider_reported > derived/partial/exact > estimated (reservation fallback) > unknown (zero)`. See the `architecture` skill for the full pricing resolution details.
-- **`eggpool stats recompute-costs [--dry-run|--apply] [--limit N]`**: walks the requests table in started_at DESC order, recomputes cost from the current price snapshots, and reports / applies the change. Default is `--dry-run`. Use after upgrading the resolver to fix inflated totals on cached-token-heavy models (e.g. MiMo 2.5). Implemented in `src/eggpool/cost_recompute.py` and reuses the live `CostCalculator` so the new values match what the finalizer would write today.
-- **Automatic backups**: in-process daily backups run by default under the `automatic_backup` supervised task (`src/eggpool/background/backup.py`). Uses stdlib `sqlite3.Connection.backup()` for consistent snapshots, atomic archive publication (write-to-temp + rename), and count-based retention (default 14). Controlled by `[backup]` config section. The `eggpool deploy backup-cron` path remains available for operators who prefer external scheduling.
-- **DNS cache**: `OutboundClientManager` and `ProviderClientPool` both integrate a `DnsNetworkBackend` that caches resolved DNS entries in memory. The cache reduces connection latency for repeated requests to the same upstream hosts. Controlled by `[network.dns_cache]` config. When a proxy is configured for an account, that account's client uses the proxy transport instead of the cached backend.
+- **`static_models` is the source of truth for provider-specific protocol** — `FAMILY_PROTOCOLS` (`src/eggpool/catalog/protocols.py`) is a global fallback. Providers like `minimax-cn` that serve MiniMax models on the OpenAI-compatible surface **must** ship `[[providers.<id>.static_models]]` rows with `protocol = "openai"`, otherwise the live `/v1/models` fetch resolves `MiniMax-M*` via the `minimax-` family prefix to `anthropic` and the protocol check clears it to `None`, producing `ModelUnavailableError` instead of `ProtocolMismatchError`. Static seeds survive via `ModelCatalogCache._preserve_static_fields` (`src/eggpool/catalog/cache.py:146-187`).
+- **Upstream-authoritative suppression**: local quota estimates are advisory by default (`local_quota_mode = "score_only"`). Only upstream-observed failures (429/402/5xx/auth) and explicit operator disablement suppress routing. Switch to `hard_cap` only as an opt-in escape hatch.
+- **Backoff persistence**: upstream-derived backoffs survive restarts via the `account_backoffs` table (`src/eggpool/db/schema/0024_account_backoffs.sql`). Local cost overruns must never be persisted as backoff rows.
+- **Synthetic 503 vs 502**: `ModelUnavailableError` (503) is reserved for genuine pre-dispatch unavailability. `UpstreamExhaustedError` (502) is raised when every candidate account was attempted and exhausted mid-request.
+- **Streaming finalizer shielding**: streaming `_build_stream_generator` finalization runs under `asyncio.shield(asyncio.wait_for(..., timeout=10))` so ASGI task cancellation cannot kill the finalizer while it holds the DB lock. Leaks that escape this path are caught by the periodic `stale_request_finalizer` background task (`app._finalize_stale_requests`, runs every 60s).
+- **Routing-decision score components** (`RoutingDecisionTrace.score_components`) carry the per-account score breakdown on every persisted `routing_decisions` row (`score_components_json`, migration `0035`). The dashboard and `eggpool accounts explain` consume this directly; do not re-score from quota tables when only the diagnostic breakdown is needed.
+- **`_select_lock` publish ordering**: in `RequestCoordinator._select_and_persist_attempt()`, runtime publication (`Router.increment_active_request_count` + `QuotaEstimator.add_reservation`) must run INSIDE `_select_lock` AFTER the durable transaction commits but BEFORE the lock releases. The two contexts are explicit nested `async with` blocks (outer `_select_lock`, inner `_db.transaction()`). Key invariant: block placement (publication outside DB transaction body, inside `_select_lock`), not context-exit order.
+- **`eggpool accounts explain` reads from SQLite, not an empty cache**: the command hydrates the catalog via `ModelCatalogCache.hydrate_from_db(db)` from `models`/`provider_model_metadata`/`account_models` rows. A thin `_CatalogShim` exposes the loaded cache as a `CatalogService`-compatible object. Output uses `click.echo` (no `rich` dependency).
+- **Startup crash recovery**: `_crash_recovery` runs at every startup and recovers ALL pending requests and active reservations with no time threshold. A process restart is a definitive boundary.
+- **Pricing pipeline**: prices flow TOML override → upstream metadata → external catalog (OpenRouter / OpenCode Zen via the alias registry). Cost precedence: `provider_reported > derived/partial/exact > estimated > unknown`.
+- **`eggpool stats recompute-costs [--dry-run|--apply] [--limit N]`**: recomputes cost from current price snapshots. Default `--dry-run`. Implemented in `src/eggpool/cost_recompute.py`.
+- **Automatic backups**: in-process daily backups run by default under the `automatic_backup` supervised task (`src/eggpool/background/backup.py`). Controlled by `[backup]` config section.
+- **DNS cache**: `OutboundClientManager` and `ProviderClientPool` both integrate a `DnsNetworkBackend` that caches resolved DNS entries. Controlled by `[network.dns_cache]` (enabled by default, TTL 1800s, max 50 entries). Exposes precise counters and derived rates for operator diagnostics.
+- **Memory footprint caps**: every growth axis is bounded by hardcoded caps (`EWMA_HARD_CAP = 4096`, `GLOBAL_EWMA_HARD_CAP = 1024`, `MAX_TRACKED_HOSTS = 256`). Regression gate: `tests/integration/test_memory.py` (`pytest.mark.slow`). See `plans/memory.md` for the full design.
+- **Transcoder body translation**: `select_transcoder()` in `src/eggpool/transcoder/protocol.py` is the single source of truth for translator dispatch. Loss-of-information warnings are accumulated on `TranscodeContext.loss_warnings` and logged at request completion.
 
 ## Error Handling
 
@@ -94,8 +112,6 @@ Use the hierarchy in `errors.py`. Chain exceptions with `raise ... from err` or
 - **Do not add transitive imports to `runtime_paths` or `fastcli`** — they are stdlib-only and must stay lightweight for the Raspberry Pi watchdog contract
 - Unrecognized commands fall through to `eggpool.cli_full`, which holds the heavy Click CLI
 - Public symbols (`cli`, helpers used by tests) are lazily forwarded from `cli_full` via PEP 562 `__getattr__` — so `from eggpool.cli import cli` and existing test imports still work without loading the full graph
-- See `plans/lightweight-cli-watchdog.md` for the full design
-
 ## Git Workflow
 
 - Branch: `main`

{eggpool-0.3.6 → eggpool-0.3.7}/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Bidirectional OpenAI ↔ Anthropic protocol transcoding.** When `[transcoder] enabled = true`, requests from clients using one protocol can be forwarded to upstream accounts that speak only the other. Initial scope is text-only requests and responses, plus streaming SSE. Tool calls, vision, and extended thinking land in a follow-up release. See `docs/transcoding.md` for the full translation table.
+- New `eggpool stats transcoding [--period 1d|7d|30d]` subcommand for transcoding observability.
+- New "Transcoding" card on the `/runtime` dashboard page.
+- Structured INFO log per transcoded request with `request_id`, protocol direction, account, and loss-warning count.
+- Boot-time INFO line when `[transcoder] enabled = true` so operators see the configuration at startup.
+- **`routing_decisions.score_components_json` column (migration `0035`)** carries the per-account score breakdown captured by `QuotaFairScorer` at the moment the coordinator chose the selected account. The dashboard can now answer "why account A over account B?" without rescoring from quota tables. Includes `quota_score`, `inflight_penalty`, `health_penalty`, `final_score`, `weight`, `active_request_count`, `reserved_microdollars`, per-window `cost_*` and `capacity_*` microdollar values, `tier`, `requires_transcode`, and the top 5 near-tie candidates.
+- **`eggpool accounts explain --model <id> [--provider P] [--protocol P]`** subcommand (`src/eggpool/cli_full.py`) renders a Rich table listing every registered account with its live eligibility verdict and a stable `reason_code` (`disabled`, `auth_failed`, `quota_exhausted`, `cooldown`, `rate_limited`, `circuit_open`, `wrong_provider`, `no_protocol`, `protocol_mismatch`, `no_model`, `model_stale`, `ok`). Re-evaluated on every invocation against the live registry + catalog so operators can diagnose routing skew without restarting the service.
+- **`GET /api/stats/routing/eligibility`** JSON counterpart (auth-gated via the existing stats-route dependency list, `src/eggpool/api/stats.py`) returns the same per-account verdict list as a JSON document for programmatic dashboards and alerting.
+
+### Changed
+
+- `RequestCoordinator` now carries `upstream_protocol` alongside `protocol` on `ProxyRequestContext`. Behaviour is identical when `[transcoder] enabled = false`.
+- **`RequestCoordinator._select_and_persist_attempt()` lock scope.** The runtime publication step (`Router.increment_active_request_count` + `QuotaEstimator.add_reservation`) now runs INSIDE `_select_lock` AFTER the durable transaction commits but BEFORE the lock releases. The two contexts are written as explicit nested `async with` blocks (outer `_select_lock`, inner `_db.transaction()`). Note: collapsing them back into the previous compound `async with self._select_lock, self._db.transaction():` form would NOT by itself re-introduce the stale-score race on context-exit-order grounds — Python exits context managers right-to-left, so the transaction would still commit before the lock released. The actual bug was that the runtime publication block lived INSIDE the transaction body, so active-count and reserved-cost state were published before the durable transaction committed. The explicit nested form makes it hard to accidentally place publication inside the transaction while still keeping publication under `_select_lock`. The key invariant is block placement (publication must be outside the DB transaction body but still inside `_select_lock`), not context-exit order. The compensation chain (decrement → finalize-as-cancelled → release health slot → set `client_metadata["post_commit_interrupted"]` → re-raise) is preserved and still catches `BaseException` (including `CancelledError` / `SystemExit` / `KeyboardInterrupt`, all re-raised without being swallowed).
+- `RoutingScore` gains diagnostic fields (`reserved_microdollars`, `cost_5h_microdollars`, `cost_7d_microdollars`, `cost_30d_microdollars`, `capacity_5h_microdollars`, `capacity_7d_microdollars`, `capacity_30d_microdollars`, `active_request_count`) so the scorer can return enough state to populate `score_components_json` without a second pass over the quota tables.
+- `RoutingDecisionTrace` gains `score_components: Mapping[str, Any] | None` plus `to_score_components_json()`; `RoutingDecisionRepository.create()` accepts an optional `score_components_json` argument (defaults to `'{}'` for backward compatibility with rows inserted by code paths that have not yet been migrated).
+- **`score_components_json` payload adds per-window utilization ratios and a tie-break summary.** The diagnostic JSON now carries `util_5h`, `util_7d`, `util_30d` (None when capacity is unconfigured) plus a `tie_break` dict naming the decisive factor between the chosen account and the runner-up (`tier`, `quota`, `inflight`, `transcode`, `near_tie`, `exact_tie`, `no_runner_up`) so the dashboard can surface a concrete cause without re-scoring.
+- **`eggpool accounts explain` hydrates the catalog from SQLite.** The command now opens the database, runs migrations on a fresh install, and calls `ModelCatalogCache.hydrate_from_db(db)` (a new read-only helper on the cache module) to populate the in-memory model / provider / account-support tables from `models`, `provider_model_metadata`, and `account_models` rows before classification. The previous implementation constructed an empty cache and would have reported every account as ineligible even if the catalog-service shape had been right.
+- **`eggpool accounts explain` no longer imports `rich`.** The undeclared `rich` dependency was replaced with plain `click.echo` columnar output. `reason_detail` strings now embed the account name, provider id, configured protocols, requested model id, and stale-window seconds so operators can act directly on the diagnosis.
+- **`eggpool accounts status` now prints `routing_priority`.** The per-line output gained a `priority=N` field derived from the account's provider, alongside `provider`, `enabled`, `weight`, and the api-key-env set state.
+- **`eggpool accounts explain` runs migrations on fresh installs.** The inner `_run_explain` coroutine now calls `MigrationRunner(db).run()` before hydrating `ModelCatalogCache.hydrate_from_db(db)`, so a brand-new (unmigrated) database path no longer crashes with `sqlite3.OperationalError: no such table: models` / `provider_model_metadata` / `account_models`. With no catalog rows yet, accounts surface a `no_model` verdict instead of the SQL error. The command still performs no outbound provider refresh.
+
 ## [0.3.5] - 2026-06-27
 
 ### Changed

{eggpool-0.3.6 → eggpool-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eggpool
-Version: 0.3.6
+Version: 0.3.7
 Summary: A lightweight proxy that aggregates multiple LLM provider accounts behind one OpenAI-compatible endpoint
 Project-URL: Homepage, https://github.com/eggstack/eggpool
 Project-URL: Repository, https://github.com/eggstack/eggpool
@@ -60,6 +60,7 @@ A lightweight, LAN-hosted proxy that aggregates multiple AI provider accounts be
 - Tracks requests, tokens, latency, errors, and estimated costs in SQLite
 - Multi-page dashboard with 50+ themes, reliability, routing, and runtime views
 - Designed for lightweight deployments (Raspberry Pi, SBCs)
+- Transparent protocol transcoding between OpenAI and Anthropic request formats
 
 ## Quick Start
 
@@ -89,7 +90,9 @@ See [Deployment](docs/deployment.md) for alternative install methods (pipx, manu
 | `eggpool rehash` | Restart to apply config changes |
 | `eggpool stop` | Stop the running server |
 | `eggpool models refresh` | Refresh the model catalog |
-| `eggpool accounts status` | Show configured account status |
+| `eggpool stats transcoding` | Show protocol transcoding statistics |
+| `eggpool accounts status` | Show configured account status (provider, priority, weight, enabled) |
+| `eggpool accounts explain` | Show per-account routing eligibility for a model |
 | `eggpool runtime-status` | Print runtime health summary |
 | `eggpool backup` | Create a timestamped backup |
 | `eggpool recover` | Restore from a backup archive |
@@ -131,9 +134,35 @@ Use `eggpool connect` for interactive provider setup. See [docs/providers.md](do
 | `[dashboard]` | Dashboard toggle, theme, refresh interval |
 | `[providers.*]` | Provider configs with accounts and routing priority |
 | `[network]` | Outbound transport, DNS cache |
+| `[transcoder]` | Protocol transcoding between OpenAI and Anthropic formats |
 
 Full config reference: [`config.example.toml`](config.example.toml) | [docs/providers.md](docs/providers.md)
 
+## Protocol transcoding
+
+When `[transcoder] enabled = true`, EggPool bridges OpenAI Chat Completions and Anthropic Messages bidirectionally so a single client ecosystem (e.g. OpenCode, which speaks only OpenAI) can reach Anthropic-only upstreams (e.g. MiniMax International at `api.minimax.io/anthropic`) and vice versa.
+
+What gets translated:
+
+- Request bodies (text-only in v1)
+- Streaming SSE events
+- Non-retryable error envelopes
+- Usage and cost fields (preserved exactly as the upstream reported them)
+
+What is dropped with a structured warning log:
+
+- OpenAI fields with no Anthropic equivalent (`logit_bias`, `presence_penalty`, `top_logprobs`, etc.)
+- Anthropic fields with no OpenAI equivalent (`top_k`, `cache_control`)
+
+What is **not** translated in v1 (lands in phase 6):
+
+- Tool calls / function calling
+- Vision / image content
+- Extended thinking / reasoning
+- Structured outputs (`response_format` / `json_schema`)
+
+See [docs/transcoding.md](docs/transcoding.md) for the full translation table and known limitations.
+
 ## API Endpoints
 
 | Method | Path | Description |
@@ -143,6 +172,7 @@ Full config reference: [`config.example.toml`](config.example.toml) | [docs/prov
 | `POST` | `/v1/messages` | Anthropic-compatible messages |
 | `GET` | `/v1/healthz` | Liveness check |
 | `GET` | `/v1/readyz` | Readiness check |
+| `GET` | `/api/backoffs` | Active upstream-derived account backoffs (`?now=<epoch>` for reproducible snapshots) |
 
 When `[dashboard].enabled = true`, a multi-page dashboard is served at `/` with request stats, latency metrics, provider health, and more. Stats API available under `/api/stats/*`.
 
@@ -159,6 +189,7 @@ When `[dashboard].enabled = true`, a multi-page dashboard is served at `/` with
 | Firewall configuration | [docs/firewall.md](docs/firewall.md) |
 | Filesystem layout | [docs/filesystem-layout.md](docs/filesystem-layout.md) |
 | Network & DNS diagnostics | [docs/network-diagnostics.md](docs/network-diagnostics.md) |
+| Protocol transcoding | [docs/transcoding.md](docs/transcoding.md) |
 
 ## Development
 

{eggpool-0.3.6 → eggpool-0.3.7}/README.md

@@ -16,6 +16,7 @@ A lightweight, LAN-hosted proxy that aggregates multiple AI provider accounts be
 - Tracks requests, tokens, latency, errors, and estimated costs in SQLite
 - Multi-page dashboard with 50+ themes, reliability, routing, and runtime views
 - Designed for lightweight deployments (Raspberry Pi, SBCs)
+- Transparent protocol transcoding between OpenAI and Anthropic request formats
 
 ## Quick Start
 
@@ -45,7 +46,9 @@ See [Deployment](docs/deployment.md) for alternative install methods (pipx, manu
 | `eggpool rehash` | Restart to apply config changes |
 | `eggpool stop` | Stop the running server |
 | `eggpool models refresh` | Refresh the model catalog |
-| `eggpool accounts status` | Show configured account status |
+| `eggpool stats transcoding` | Show protocol transcoding statistics |
+| `eggpool accounts status` | Show configured account status (provider, priority, weight, enabled) |
+| `eggpool accounts explain` | Show per-account routing eligibility for a model |
 | `eggpool runtime-status` | Print runtime health summary |
 | `eggpool backup` | Create a timestamped backup |
 | `eggpool recover` | Restore from a backup archive |
@@ -87,9 +90,35 @@ Use `eggpool connect` for interactive provider setup. See [docs/providers.md](do
 | `[dashboard]` | Dashboard toggle, theme, refresh interval |
 | `[providers.*]` | Provider configs with accounts and routing priority |
 | `[network]` | Outbound transport, DNS cache |
+| `[transcoder]` | Protocol transcoding between OpenAI and Anthropic formats |
 
 Full config reference: [`config.example.toml`](config.example.toml) | [docs/providers.md](docs/providers.md)
 
+## Protocol transcoding
+
+When `[transcoder] enabled = true`, EggPool bridges OpenAI Chat Completions and Anthropic Messages bidirectionally so a single client ecosystem (e.g. OpenCode, which speaks only OpenAI) can reach Anthropic-only upstreams (e.g. MiniMax International at `api.minimax.io/anthropic`) and vice versa.
+
+What gets translated:
+
+- Request bodies (text-only in v1)
+- Streaming SSE events
+- Non-retryable error envelopes
+- Usage and cost fields (preserved exactly as the upstream reported them)
+
+What is dropped with a structured warning log:
+
+- OpenAI fields with no Anthropic equivalent (`logit_bias`, `presence_penalty`, `top_logprobs`, etc.)
+- Anthropic fields with no OpenAI equivalent (`top_k`, `cache_control`)
+
+What is **not** translated in v1 (lands in phase 6):
+
+- Tool calls / function calling
+- Vision / image content
+- Extended thinking / reasoning
+- Structured outputs (`response_format` / `json_schema`)
+
+See [docs/transcoding.md](docs/transcoding.md) for the full translation table and known limitations.
+
 ## API Endpoints
 
 | Method | Path | Description |
@@ -99,6 +128,7 @@ Full config reference: [`config.example.toml`](config.example.toml) | [docs/prov
 | `POST` | `/v1/messages` | Anthropic-compatible messages |
 | `GET` | `/v1/healthz` | Liveness check |
 | `GET` | `/v1/readyz` | Readiness check |
+| `GET` | `/api/backoffs` | Active upstream-derived account backoffs (`?now=<epoch>` for reproducible snapshots) |
 
 When `[dashboard].enabled = true`, a multi-page dashboard is served at `/` with request stats, latency metrics, provider health, and more. Stats API available under `/api/stats/*`.
 
@@ -115,6 +145,7 @@ When `[dashboard].enabled = true`, a multi-page dashboard is served at `/` with
 | Firewall configuration | [docs/firewall.md](docs/firewall.md) |
 | Filesystem layout | [docs/filesystem-layout.md](docs/filesystem-layout.md) |
 | Network & DNS diagnostics | [docs/network-diagnostics.md](docs/network-diagnostics.md) |
+| Protocol transcoding | [docs/transcoding.md](docs/transcoding.md) |
 
 ## Development
 

{eggpool-0.3.6 → eggpool-0.3.7}/architecture/README.md

@@ -17,6 +17,7 @@ src/eggpool/
 ├── models/            # Pydantic config, domain, API, and database models
 ├── providers/         # ProviderClientPool, pproxy transport, connect CLI
 ├── proxy/             # Transparent proxy, SSE observer, usage extraction
+├── transcoder/        # Protocol transcoding (OpenAI ↔ Anthropic, body + streaming)
 ├── quota/             # Quota estimation, reservations, scoring
 ├── request/           # RequestCoordinator, finalizers, body reader, limit enforcement
 ├── retry/             # Error classification and failover
@@ -49,7 +50,8 @@ All data-plane requests flow through `RequestCoordinator`:
 2. **Routing** selects an eligible account via quota-aware scoring (`routing/router.py`)
 3. **Attempt** is persisted to SQLite before upstream dispatch
 4. **Provider Contract** renders absolute URL (`compose_provider_url()`) and auth headers (`build_upstream_headers()`) from `providers/contract.py`
-5. **Proxy** sends the request via the provider's `httpx.AsyncClient` from `ProviderClientPool`
+5. **Protocol Transcoding** (if enabled) translates the request body when the client protocol differs from the upstream protocol
+6. **Proxy** sends the request via the provider's `httpx.AsyncClient` from `ProviderClientPool`
 6. **Streaming** is handled by `proxy/sse_observer.py` with chunk-level usage extraction
 7. **Finalization** records usage, releases reservations, updates health state
 
@@ -62,7 +64,7 @@ Key invariants:
 - Each attempt reservation is released exactly once via `AttemptFinalizer`
 - The same URL composition rules apply to catalog fetch and chat dispatch
 - **Structured observability persistence (migrations 0026-0029)** every `request_attempts` row carries provider/model/protocol/retry_category/latency/bytes/streamed/is_retry_outcome; every routing decision is persisted to `routing_decisions` in the same transaction as the `request_attempts` INSERT; safety-net tasks (`_crash_recovery`, `_finalize_stale_requests_once`, `reconcile_expired_reservations`) record `operational_events` rows inside the same transaction as the durable state mutation; latency is decomposed into `upstream_connect_ms / upstream_read_ms / coordinator_overhead_ms` so the dashboard can distinguish network vs upstream vs eggpool-side bottlenecks
-- **Runtime metrics are best-effort and process-local** — the `/api/stats/runtime` endpoint and `eggpool runtime-status` CLI command gather process topology, memory, background task state, database health, OS load average (`os.getloadavg` + normalized per-core), and a bounded rolling-window dispatch-overhead distribution via `DispatchOverheadRecorder` (`src/eggpool/runtime_dispatch.py`); failed probes return `null` rather than raising, and the endpoint is always auth-gated even with a public dashboard
+- **Runtime metrics are best-effort and process-local** — the `/api/stats/runtime` endpoint and `eggpool runtime-status` CLI command gather process topology, memory, background task state, database health, OS load average (`os.getloadavg` + normalized per-core), and a bounded rolling-window dispatch-overhead distribution via `DispatchOverheadRecorder` (`src/eggpool/runtime_dispatch.py`); failed probes return `null` rather than raising, `probe_errors` is capped to 16 truncated entries, and the endpoint is always auth-gated even with a public dashboard
 
 ## Multi-Provider Architecture
 
@@ -124,6 +126,52 @@ The coordinator calls `_build_upstream_headers()` and `_get_upstream_url()` whic
 
 `AppConfig.validate_account_credentials()` rejects API keys that begin with the `Bearer` scheme for providers configured with `auth.mode = "bearer"`. EggPool adds the scheme automatically, so a stored `Bearer <token>` would produce `Authorization: Bearer Bearer <token>` upstream and cause 401s. The same guard runs in `scripts/verify_upstream_auth.py` so the operator gets an explicit error before any upstream call. Providers using `auth.mode = "raw_authorization"` are unaffected because they pass the value verbatim.
 
+## Protocol Transcoding
+
+When a client sends a request in one protocol (e.g., Anthropic Messages API)
+but the routed provider only supports another (e.g., OpenAI Chat Completions
+API), the `transcoder` module translates the request body before dispatch and
+the response body (including streaming chunks) after receipt.
+
+**Phase 1 (foundation)** lands the data model, configuration surface, and
+helper modules without changing runtime behaviour:
+- `TranscoderPolicy` config model (`[transcoder]` section)
+- `TranscodeContext` per-request state dataclass
+- `upstream_protocol` field on `ProxyRequestContext`
+- Mechanical refactor: upstream-side reads in the coordinator use
+  `context.upstream_protocol` instead of `context.protocol`
+- Routing eligibility accepts a `transcode_eligibility` parameter
+- Helper modules: `ids.py` (tool-call ID map), `usage.py` (usage
+  canonicalisation), `errors.py` (upstream error envelope parser)
+
+**Phase 2 — Body translation**: text-only, non-streaming request/response
+body translation is implemented in `src/eggpool/transcoder/`. The
+`BodyTranscoder` Protocol (`protocol.py`) defines the interface;
+`OpenAIToAnthropic` and `AnthropicToOpenAI` are the concrete translators.
+`select_transcoder()` is the single source of truth for dispatch. The
+coordinator pre-translates the request body before dispatch, decodes the
+response body on success, and re-renders non-retryable errors in the client
+protocol. Loss-of-information warnings are accumulated on
+`TranscodeContext.loss_warnings` and logged at request completion.
+
+**Phase 3 — Streaming translation**: SSE stream translation in both
+directions for text-only streams. `StreamingTranscoder` implementations
+(`OpenAIToAnthropicStreaming`, `AnthropicToOpenAIStreaming`) translate
+upstream SSE frames into client-format bytes chunk-by-chunk.
+`select_streaming_transcoder()` in `streaming.py` is the dispatch source
+of truth. The coordinator's `_build_stream_generator` applies the transcoder
+when the client and upstream protocols differ. Same-protocol requests pass
+through unchanged. Tool calls, thinking, and routing widening are out of
+scope (phases 4–6).
+
+**Phase 4 — Routing eligibility widening**: when `[transcoder] enabled = true`, the routing layer widens the candidate set to include accounts whose `provider.protocols` includes the model's native protocol even if it does not include the client protocol. `_validate_endpoint` checks for transcodable routes before raising `ProtocolMismatchError`. The `_resolve_upstream_protocol` method determines which protocol to use upstream based on the largest eligible-account set. `prefer_native = true` (default) keeps native-protocol accounts ranked above transcodable ones via a secondary sort key in `QuotaFairScorer`. The two-pass context-limit check in `api/proxy_request.py` validates both client-side and upstream limits when transcoding is active.
+
+**Phase 5 — Operator controls and docs**: the default `[transcoder]` config block is documented and uncommented in `config.example.toml`. `eggpool stats transcoding` reports transcoded request counts and loss-warning summaries. The dashboard `/runtime` page includes a "Transcoding" card showing real-time counters. Structured INFO logs are emitted for every transcoded request and at boot time when enabled. See `docs/transcoding.md` for the full operator guide.
+
+Token counts are mapped between protocol-specific fields (e.g.,
+`input_tokens` → `prompt_tokens`, `cache_creation_input_tokens` →
+separate cache counters). Controlled by `[transcoder]` config.
+
 ## Database
 
 SQLite via aiosqlite with WAL mode. Single-connection serialization via a lock + ContextVar.
@@ -137,7 +185,7 @@ SQLite via aiosqlite with WAL mode. Single-connection serialization via a lock +
 
 ### Schema Migrations
 
-Ordered SQL migrations in `db/schema/` (0001 through 0032). Checksums tracked in `checksums.json`.
+Ordered SQL migrations in `db/schema/` (0001 through 0035). Checksums tracked in `checksums.json`.
 
 ### Repositories
 
@@ -183,8 +231,7 @@ Accounts are excluded from routing when:
 In the default `score_only` mode, local cost and quota estimates influence
 routing **priority** only — above-capacity accounts stay eligible. Only
 upstream-observed failures, explicit operator disablement, and catalog/
-protocol incompatibility can suppress routing. See
-`plans/upstream-authoritative-suppression.md` for the full design.
+protocol incompatibility can suppress routing.
 
 Upstream-derived backoffs (429, 402, model-unavailable) persist across
 restarts in the `account_backoffs` table (`src/eggpool/db/schema/0024_account_backoffs.sql`)
@@ -198,6 +245,76 @@ the coordinator raises `UpstreamExhaustedError` (502) — synthetic 503 is
 reserved for genuine pre-dispatch unavailability (no enabled accounts,
 missing credentials, all explicitly disabled, model unknown).
 
+### Lock scope and publish ordering
+
+The `RequestCoordinator._select_and_persist_attempt()` method holds
+`_select_lock` across both the durable transaction (`request_attempts`
++ `routing_decisions` INSERT inside `async with self._db.transaction():`)
+AND the runtime publication step (`Router.increment_active_request_count`
++ `QuotaEstimator.add_reservation`). The publication runs AFTER the
+transaction commits but BEFORE the lock releases, so a concurrent
+selector that enters the lock next observes this attempt's runtime
+state. The publish is fast (in-process counter + cache mutation), so
+the lock-hold stays tight while still closing the burst-skew race
+previously caused by publishing inside the transaction body.
+
+Note: the two contexts are written as explicit nested `async with`
+blocks (outer `_select_lock`, inner `_db.transaction()`) — NOT as a
+compound `async with self._select_lock, self._db.transaction():`. A
+compound form would still exit right-to-left (transaction commits
+before the lock releases), so context-exit order alone is not the
+invariant. The actual bug was that the runtime publication block lived
+INSIDE the transaction body; active-count and reserved-cost state were
+therefore published before the transaction committed. The explicit
+nested form makes it hard to accidentally place publication inside the
+transaction while still keeping publication under `_select_lock`. The
+key invariant is block placement (publication must be outside the DB
+transaction body but still inside `_select_lock`), not context-exit
+order.
+
+The compensation chain (`decrement` → finalize-as-cancelled → release
+health slot → set `client_metadata["post_commit_interrupted"]` →
+re-raise) wraps the publish step and catches `BaseException` (including
+`CancelledError` / `SystemExit` / `KeyboardInterrupt`, re-raised
+without swallowing).
+
+### Score components and eligibility diagnostics
+
+Every persisted `routing_decisions` row carries the per-account score
+breakdown captured by `QuotaFairScorer` at the moment the coordinator
+chose the selected account. Migration `0035` adds the
+`score_components_json` column; `RoutingDecisionTrace.to_score_components_json()`
+serializes the diagnostic payload (TEXT JSON, defaults to `'{}'` on rows
+written by code paths that pre-date the migration). The payload now also
+includes per-window `util_5h` / `util_7d` / `util_30d` utilization ratios
+(None when the scorer's capacity is unconfigured) and a `tie_break`
+summary naming the decisive factor between the chosen account and its
+runner-up (`tier`, `quota`, `inflight`, `transcode`, `near_tie`,
+`exact_tie`, `no_runner_up`). The same data flows through
+`eggpool accounts explain --model <id> [--provider P] [--protocol P]`
+and `GET /api/stats/routing/eligibility` for live operator diagnostics.
+
+`Router.explain_account_eligibility(model_id, provider_id, protocol)`
+returns one row per registered account with `eligible: bool`, a stable
+`reason_code` (`ok`, `disabled`, `auth_failed`, `quota_exhausted`,
+`cooldown`, `rate_limited`, `circuit_open`, `wrong_provider`,
+`no_protocol`, `protocol_mismatch`, `no_model`, `model_stale`), and a
+short `reason_detail` that names the account, its provider, its
+configured protocols, the requested model id, and the stale-window
+seconds (so the operator can act directly on the diagnosis). The
+classification mirrors the live filter chain in
+`eggpool.routing.eligibility.get_eligible_accounts` so explanations
+match the routing path exactly.
+
+`eggpool accounts explain` opens the database, runs migrations on a
+fresh install, and calls `ModelCatalogCache.hydrate_from_db(db)` to
+populate the in-memory model / provider / account-support tables from
+the durable `models`, `provider_model_metadata`, and `account_models`
+rows. The cache is wrapped in a tiny `_CatalogShim` so `Router` can
+consume it without booting a full `CatalogService`; output is rendered
+with `click.echo` (the previous `rich` table was removed because the
+dependency was undeclared).
+
 ## Provider Routing Priority and Model Collapse
 
 Two related configuration knobs let operators control how requests for the
@@ -469,3 +586,21 @@ Production (`eggpool deploy systemd --install --production`):
 | `metrics_flush` | `write_mode != "immediate"` | Buffered analytics flush to `usage_rollups` |
 | `update_checker` | Always | Periodic PyPI update check (default 24h); see `update_checker.py` |
 | `automatic_backup` | `backup.enabled` | In-process SQLite backup with count-based retention; see `background/backup.py` |
+| `health_disabled_models_prune` | Always | Periodic sweep that drops stale `model_availability` and `disabled_models` entries (every 60s) |
+
+## In-Memory Bounds and Memory Footprint
+
+Long-running deployments — especially Raspberry Pi / SBC nodes — must keep steady-state RSS bounded by workload throughput, not workload cardinality. Every growth axis in the hot path is capped by a hardcoded module constant or a per-catalog config knob; see `plans/memory.md` for the full design and the per-request regression test (`tests/integration/test_memory.py`, marked `pytest.mark.slow`).
+
+| Structure | Location | Cap | Eviction |
+|-----------|----------|-----|----------|
+| `QuotaEstimator.account_model_ewma` | `src/eggpool/quota/estimation.py:285` | `EWMA_HARD_CAP = 4096` (hardcoded) | LRU; on miss recomputes from persisted `QuotaWindow` |
+| `QuotaEstimator.global_model_ewma` | `src/eggpool/quota/estimation.py:286` | `GLOBAL_EWMA_HARD_CAP = 1024` (hardcoded) | LRU |
+| `CatalogResolverPipeline.TTLCache._data` | `src/eggpool/catalog/catalog_resolvers.py:128` | `max_entries = 4096` per `[pricing.catalogs.<name>]` (configurable) | LRU on store; `entry.raw` stripped after parse |
+| `ModelCatalogCache._models` / `_provider_models` | `src/eggpool/catalog/cache.py:109-111` | De-duplicated (per-provider override only when it differs from global) | — |
+| `ModelCatalogCache._account_support` | `src/eggpool/catalog/cache.py:114` | `frozenset[str]` (no per-call `.copy()`); bounded by registered account × model cardinality | — |
+| `OutboundClientManager._per_host_*` | `src/eggpool/providers/outbound.py:85` | `MAX_TRACKED_HOSTS = 256` (hardcoded) | Coldest-total eviction; `evictions_total` surfaced in `snapshot()` and the `outbound_client` runtime metric |
+| `AccountRuntimeState.model_availability` | `src/eggpool/accounts/state.py` | Pruned at every `AccountRegistry.sync_accounts` against advertised model set | — |
+| `HealthManager.AccountHealth.disabled_models` | `src/eggpool/health/health_manager.py:111` | Pruned by `health_disabled_models_prune` supervisor task (60s cycle) | — |
+
+The `frozenset` switch on `_account_support` (`src/eggpool/catalog/cache.py:639`) eliminates one O(n) `set.copy()` per routing decision. Every caller of `get_supporting_accounts(...)` / `get_supporting_accounts_for_model(...)` is read-only (membership, intersection, iteration), so the immutability is a strict superset of caller needs.

{eggpool-0.3.6 → eggpool-0.3.7}/config.example.toml

@@ -39,6 +39,23 @@ ping_retain_days = 7
 #                          # ID and routed across all of them. Default false
 #                          # emits one provider-suffixed entry per provider.
 
+# ─── Protocol Transcoding ────────────────────────────────────────────
+# When enabled, requests from clients using one protocol (OpenAI or
+# Anthropic) can be forwarded to upstream accounts whose provider
+# declares only the other protocol. EggPool translates the request body,
+# the streaming SSE events, and the response body bidirectionally.
+#
+# Use this when you want to mix protocol-native and protocol-transcoded
+# accounts (e.g. opencode-go native plus MiniMax International
+# Anthropic-only, both reachable from OpenCode clients).
+#
+# Default: enabled = false. The behaviour before this flag existed is
+# preserved exactly.
+[transcoder]
+enabled = false
+loss_policy = "warn"      # "warn" or "reject" for loss-of-information
+prefer_native = true      # prefer native-protocol accounts in routing
+
 [routing]
 strategy = "quota_fair"
 near_tie_epsilon = 0.1
@@ -63,6 +80,29 @@ five_hour_microdollars = 12000000
 weekly_microdollars = 30000000
 monthly_microdollars = 60000000
 
+# --- Pricing resolution ----------------------------------------------
+# External pricing catalogs supplement upstream model metadata when
+# providers do not include pricing in /v1/models responses. The per-catalog
+# max_entries cap bounds steady-state RSS on SBC deployments.
+[pricing]
+fallback = "generic_estimate"
+
+[pricing.catalogs]
+
+[pricing.catalogs.openrouter]
+enabled = true
+priority = 100
+ttl_seconds = 86400
+# max_entries = 4096  # bound the in-memory catalog cache; oldest entries evict first
+# base_url = "https://openrouter.ai/api/v1"
+# api_key = "..."     # optional; only needed for higher rate limits
+
+[pricing.catalogs.opencode_zen]
+enabled = false
+priority = 200
+ttl_seconds = 86400
+# max_entries = 4096  # bound the in-memory catalog cache; oldest entries evict first
+
 # ─── Network ─────────────────────────────────────────────────────────
 # Outbound client transport tuning and DNS caching. The DNS cache wraps
 # the default httpcore transport to cache resolved DNS entries in memory,
@@ -77,7 +117,7 @@ monthly_microdollars = 60000000
 # [network.dns_cache]
 # enabled = true                   # enable in-memory DNS cache (default: true)
 # max_entries = 50                 # max cached host entries (default: 50)
-# positive_ttl_seconds = 300       # upper cap for positive DNS answers (default: 300)
+# positive_ttl_seconds = 1800      # upper cap for positive DNS answers (default: 1800)
 # negative_ttl_seconds = 30        # how long to cache lookup failures (default: 30)
 # stale_if_error_seconds = 3600    # max age for stale records usable on resolver failure (default: 3600)
 # prefer_ipv6 = false              # prefer IPv6 addresses in DNS resolution (default: false)

{eggpool-0.3.6 → eggpool-0.3.7}/docs/deployment.md

@@ -156,7 +156,6 @@ the operator's interactive shell environment. `ensure-running`
 atomically checks-and-starts without ever spawning a duplicate
 instance, and uses the stdlib-only fast-path CLI so the cron tick is
 cheap enough to run every five minutes on Raspberry Pi-class hardware.
-See `plans/lightweight-cli-watchdog.md` for the design rationale.
 
 ### 5. Manual run (debug foreground)
 
@@ -533,8 +532,19 @@ The output covers:
 - **Routing** — active requests, pending count, active reservations,
   reserved microdollars, health states, active backoff rows.
 
+For a focused view of active upstream-derived suppression, call
+`GET /api/backoffs`. The endpoint returns persisted `account_backoffs`
+rows joined with account names and accepts `?now=<epoch seconds>` for
+reproducible snapshots during tests or incident review. Local quota
+estimates never appear in this response; only upstream-observed
+failures such as 429, 402, auth failures, model unavailability, and
+bounded transient errors create these rows.
+
 All probes are best-effort; failed probes return `null` rather than
-causing the command to fail.
+causing the command to fail. Probe diagnostics are exposed in the JSON
+payload as `probe_errors`, capped at 16 entries with each message
+truncated, so repeated host or permissions failures cannot produce an
+unbounded response.
 
 ### Checking from cron
 
@@ -635,7 +645,25 @@ section.  On Linux the snapshot reads current RSS from
 `/proc/self/stat`; on macOS it falls back to `ru_maxrss` (a
 high-water mark).
 
-If RSS grows continuously:
+The following in-memory growth axes are bounded by design; see
+`plans/memory.md` for the full design:
+
+- `QuotaEstimator.account_model_ewma` and `global_model_ewma` are
+  LRU-capped at `EWMA_HARD_CAP = 4096` and `GLOBAL_EWMA_HARD_CAP = 1024`
+  entries respectively (hardcoded, not configurable).
+- `ModelCatalogCache` deduplicates `_models` and `_provider_models`,
+  and `_account_support` is a `frozenset[str]` (no per-call `.copy()`).
+- `CatalogResolverPipeline.TTLCache` is bounded per catalog by
+  `max_entries` (default `4096`, configurable per `[pricing.catalogs.<name>]`).
+- `OutboundClientManager._per_host_requests` / `_per_host_errors`
+  are capped at `MAX_TRACKED_HOSTS = 256` (coldest-total eviction;
+  `evictions_total` is exposed in the manager snapshot).
+- `AccountRuntimeState.model_availability` and
+  `HealthManager.AccountHealth.disabled_models` are pruned at every
+  `AccountRegistry.sync_accounts` / `health_disabled_models_prune`
+  sweep against the currently-advertised model set.
+
+If RSS still grows continuously after the above:
 
 1. Check for leaked pending requests (see above).
 2. Verify WAL checkpointing is working: `PRAGMA wal_checkpoint(PASSIVE)`.
@@ -680,7 +708,7 @@ A process restart is a definitive boundary: any request that was still
 active reservations are released, regardless of how recently they were
 created.  Check the startup log for `Crash recovery: marked N stale
 requests` to confirm a clean recovery after a crash or forced
-restart.  See `plans/eggpoolfix.md` for the full safety-net design.
+restart.
 
 ---
 
@@ -708,4 +736,4 @@ restart.  See `plans/eggpoolfix.md` for the full safety-net design.
 | `eggpool uninstall` | Detect install method, preview PATH edits, remove binary + config + data + shell-rc entries |
 | `eggpool uninstall --deploy-artifacts` | Also remove systemd unit, logrotate config, watchdog + backup cron blocks, backup script |
 | `eggpool croncheck` | Check if server is running (exit 0/1) — fast-path, no heavy imports |
-| `eggpool ensure-running` | Atomically check-and-start the server; no-op when already alive — fast-path, no heavy imports |
+| `eggpool ensure-running` | Atomically check-and-start the server; no-op when already alive — fast-path, no heavy imports |