eggpool 0.4.2__tar.gz → 0.4.4__tar.gz

{eggpool-0.4.2 → eggpool-0.4.4}/AGENTS.md

@@ -69,7 +69,7 @@ CI sets `PYTHONHASHSEED=0` and `TZ=UTC`; reproduce locally for deterministic res
 - **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.
+- **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, Phase 5 operator controls and docs, and Phase 6.1 tool-use/tool_calls body and streaming translation (including `pause_turn` sentinel handling and `stream_options.include_usage` lifting) 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, same-tier fairness rotor. See `architecture/README.md` § Quota and Routing.
 - **Error hierarchy**: `AggregatorError` → `UpstreamError` → specific subclasses. See `architecture/README.md` § Error Hierarchy.
@@ -92,6 +92,7 @@ CI sets `PYTHONHASHSEED=0` and `TZ=UTC`; reproduce locally for deterministic res
 - **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).
+- **model_info FK seeding**: `model_info_canonical.model_id`, `model_info_observations.model_id`, `model_info_aliases.model_id`, and `model_info_overrides.model_id` all carry FKs to `models.model_id` (`src/eggpool/db/schema/0036_model_info.sql`, `0038_model_info_phase5.sql`). Catalog entries for unresolved static models can reach the model-info paths before `_persist_catalog` writes them to the `models` table (and pre-0036 installations may have FK-violating rows for any reason). The repository seeds a placeholder `models` row inside the same transaction as the sidecar write — see `upsert_canonical_with_model` and `upsert_observation` in `src/eggpool/model_info/repository.py`. `INSERT OR IGNORE` is mandatory: catalog-authored fields (display_name, protocol, capabilities) must never be clobbered by an observation-side seed.
 - **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.
 - **`db.transaction()` nesting semantics** (`src/eggpool/db/connection.py`): nesting is detected via SQLite's per-connection `conn.in_transaction`, NOT task identity. A shielded or `create_task` child entering `db.transaction()` while the parent's `BEGIN IMMEDIATE` is still open piggybacks on the outer's commit boundary; the child never re-issues `BEGIN` and never acquires `_connection_lock` (the outer holds it). This fixes the AB/BA deadlock where a shielded child would block waiting for `_connection_lock` while the parent awaited `asyncio.shield()`. Two ContextVars back the semantics: `_in_transaction_context: ContextVar[bool]` is set/reset by both nested and outermost paths and is inherited by shielded/child tasks so they can `execute_write`; `_transaction_owner: ContextVar[Task]` is set only by the outermost path and is used by `vacuum()` to refuse running when the *current* task holds the lock (deadlock guard). `vacuum()` and `_require_transaction_owner()` consult `_in_transaction_context`, not `_transaction_owner`, so shielded/child task writes piggyback cleanly. Regression coverage lives in `tests/unit/test_database.py::TestTransactionNestingAcrossTaskBoundaries`.

{eggpool-0.4.2 → eggpool-0.4.4}/CHANGELOG.md

@@ -7,8 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+Nothing yet.
+
+## [0.4.4] - 2026-06-30
+
+### Fixed
+
+- **Provider-scoped transcodable protocol lookup**. `get_transcodable_protocols` and `count_eligible_accounts_for_protocol` on `ModelCatalogCache` now accept an optional `provider_id` filter so protocol inference and eligibility counting only consider accounts that belong to a specific provider. `_infer_upstream_protocol` in `proxy_request.py` and `RequestCoordinator._resolve_upstream_protocol` pass the selected account's `provider_id`, preventing cross-provider protocol leakage when the same model is served by providers with different protocol surfaces.
+- **MiniMax token-plan contract warning**. `check-config` now emits a warning when a MiniMax provider entry targets `api.minimax.io` with `openai` protocol but does not use the `/anthropic` path — token-plan keys hitting the OpenAI `/v1/chat/completions` surface can return upstream `insufficient balance (1008)` errors.
+- **`build_upstream_headers` now receives the upstream protocol**. The coordinator passes `context.upstream_protocol` to `build_upstream_headers` so protocol-specific auth header construction (e.g. `x-api-key` for Anthropic vs `Authorization: Bearer` for OpenAI) uses the correct upstream protocol instead of the client's protocol.
+
+## [0.4.3] - 2026-06-30
+
 ### Added
 
+- **Phase 6.1: Tool-Use Transcoding**. Bidirectional OpenAI ↔ Anthropic tool calling translation for both streaming and non-streaming requests. The transcoder now lifts `tools`, `tool_choice`, assistant `tool_calls` history, `role: "tool"` history, and `tool_use` / `tool_result` content blocks across protocols instead of dropping them with a warning.
+  - **Body translation**: `OpenAIToAnthropic.encode_request` / `decode_response` and `AnthropicToOpenAI.encode_request` / `decode_response` translate `tools[]`, `tool_choice` (string ↔ object shapes), `parallel_tool_calls` (`true` omitted; `false` dropped with `parallel_tool_calls_collapsed` warning since Anthropic has no parallel-disable knob), assistant `tool_calls[]` ↔ `content[].tool_use`, and `role: "tool"` ↔ `content[].tool_result` blocks. `tools[].function.strict` is dropped (no Anthropic equivalent); `tools[].cache_control` is dropped on the Anthropic → OpenAI path.
+  - **Streaming tool_call delta translation**: `OpenAIToAnthropicStreaming` and `AnthropicToOpenAIStreaming` extend their state machines to track `content_block_start` / `input_json_delta` / `content_block_stop` triples and emit OpenAI `tool_calls` deltas in insertion order; the reverse direction buffers `tool_calls[*].function.arguments` chunks keyed on `tool_calls[*].index` and flushes Anthropic `tool_use` blocks on `finish_reason: "tool_calls"`. `flush()` emits a final delta for any slot whose `content_block_stop` never arrived so the client never hangs on a missing terminal.
+  - **Tool-call ID translation map**: a per-request `ToolCallIdMap` (on `TranscodeContext.id_map`) mints `call_<24 hex>` and `toolu_<24 hex>` ids so the two namespaces never collide. Both `generate_openai_id()` and `generate_anthropic_id()` produce 24 hex characters after the prefix. The map is per-`TranscodeContext`, so concurrent requests cannot collide.
+  - **`pause_turn` sentinel handling**: Anthropic's `pause_turn` `stop_reason` maps to `finish_reason: "tool_calls"` plus a synthetic tool_call entry `{"id": "call_pause_turn_<request_id>", "type": "function", "function": {"name": "__eggpool_pause_turn__", "arguments": "{}"}}`. OpenAI clients detect the sentinel by name and resume the turn with the same `tool_use_id`. A `pause_turn` loss warning is appended whenever the sentinel is synthesized.
+  - **`stream_options.include_usage` lifting**: `OpenAIToAnthropic.encode_request` lifts `stream_options.include_usage` onto `TranscodeContext.request_include_usage` before the streaming transcoder runs. The streaming transcoder reads the flag to decide whether to forward upstream usage chunks to the OpenAI client. The wrapper object itself is dropped with a `dropped_field` warning.
+  - **New loss-warning kinds**: `tool_call_id_translated`, `tool_call_id_changed`, `parallel_tool_calls_collapsed`, `malformed_tool_arguments`, `invalid_tool_choice`, `unsupported_tool_type`, `empty_tool_use_block`, `tool_result_image_dropped`, `tool_result_error_passthrough`, `cache_control_dropped`, `pause_turn`, `non_text_content_dropped`, `tool_result_inferred`. All are registered in `eggpool.transcoder.LOSS_WARNING_KINDS`. See `docs/transcoding.md` § Tool-Use Transcoding for the full catalogue.
 - **Catalog non-destructive refresh contract.** `ModelCatalogCache.update_from_account()` now accepts `authoritative: bool = False, allow_withdrawals: bool = False`; both flags default to `False` so a failed, empty, or partial refresh cannot silently de-pool a healthy account. Operators opt into the old "refresh is the source of truth" behavior with `ModelsConfig.catalog_withdrawal_policy` (`preserve_until_health` default, `confirmed_once`, `confirmed_twice`). Under the default policy, health is the only de-pooling mechanism. `CatalogService._fetch_and_process_account()` returns an `AccountCatalogOutcome` enum (`SUCCESS_AUTHORITATIVE`, `SUCCESS_PARTIAL`, `SUCCESS_EMPTY`, `FAILED`, `SKIPPED`) plus an `AccountCatalogUpdateResult` summary row so the cache layer can stay non-destructive while operators still get full audit trail. `_log_refresh_summary` emits a single INFO line enumerating per-outcome counts after every cycle so catalog uncertainty shows up without enabling debug logging.
 - **`eggpool accounts explain --gates`** (`src/eggpool/cli_full.py`) renders the per-account gate breakdown (config, credentials, health, circuit, provider id registry/catalog match, provider-supports-protocol, model support row/availability/freshness, provider-metadata-exists, protocol_match, local_quota_gate, final_eligible) as a compact text table. Backed by `Router.explain_account_eligibility(include_gates=True)` and `Router._collect_gate_status(...)`; the breakdown is informational — the canonical decision still comes from `_classify_eligibility`.
 - **Same-tier account fairness rotor**: deterministic round-robin rotation for effectively tied same-tier accounts prevents routing starvation. Configurable via `[routing] fairness_mode`, `fairness_epsilon`, and `fairness_scope`. Defaults to `round_robin` with `provider_model_protocol` scope. Fairness decisions are recorded in `routing_decisions.score_components_json` under the `fairness` key for operator diagnostics. The `fairness` payload now includes the `scope` field, and each `top_candidates` entry carries `rank_before_fairness`, `rank_after_fairness`, and `fairness_band_member` for full traceability. The `FairnessRotor` position map is capped at 4096 entries (`_ROTOR_HARD_CAP`); when reached the entire map is cleared and rotation restarts from 0.
@@ -36,6 +55,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Dashboard rollup filters now match request-table filters.** When buffered analytics are enabled, account-filtered summaries, unknown-account summaries, flat model-filtered timeseries, and grouped model-filtered timeseries now push filters into `usage_rollups` queries instead of accidentally returning global rollup data or falling back because the display series key did not contain the filtered model id.
 - **Cross-account protocol poisoning from a partial sibling refresh.** `_provider_models` is keyed by `(model_id, provider_id)` and shared by every account that lists that provider (e.g. all `opencode-go-0001`/`-0002`/`-0003` accounts share one row per model on the `opencode-go` provider). Prior to this fix a single sibling's partial refresh — transient upstream parse error, unresolved family prefix, or a model whose protocol cannot be re-derived this cycle — produced a model entry with `protocol=None` and clobbered the previously-resolved protocol on the shared row, silently dropping every sibling account from routing even though `_account_support` still listed them. `ModelCatalogCache._preserve_resolved_protocol()` now applies a sibling-wins guard: a non-destructive `update_from_account` will keep the existing resolved protocol when the new entry's `protocol` is `None` and the prior row carried a resolved value. The destructive path (`authoritative=True AND allow_withdrawals=True`) intentionally skips the guard so operator-initiated withdrawals remain effective. `tests/unit/test_catalog_withdrawal_policy.py::test_partial_refresh_does_not_clobber_shared_provider_protocol{,multiple}` and `test_explicit_destructive_update_can_still_clear_protocol` pin the new contract.
 
 ## [0.3.5] - 2026-06-27

{eggpool-0.4.2 → eggpool-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eggpool
-Version: 0.4.2
+Version: 0.4.4
 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
@@ -148,8 +148,8 @@ When `[transcoder] enabled = true`, EggPool bridges OpenAI Chat Completions and
 
 What gets translated:
 
-- Request bodies (text-only in v1)
-- Streaming SSE events
+- Request bodies (text + tool-use + vision + thinking + structured outputs)
+- Streaming SSE events (including tool-call deltas and thinking deltas)
 - Non-retryable error envelopes
 - Usage and cost fields (preserved exactly as the upstream reported them)
 
@@ -158,12 +158,13 @@ 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):
+Phase 6 feature flags (`[transcoder.features]`) — all **off** by default:
 
-- Tool calls / function calling
-- Vision / image content
-- Extended thinking / reasoning
-- Structured outputs (`response_format` / `json_schema`)
+- `tools` — bidirectional tool calling translation
+- `vision` — image/document content parts
+- `thinking` — extended thinking ↔ reasoning_content
+- `structured_outputs` — `response_format` / `json_schema` coercion
+- `anthropic_primitives` — `top_k`, `cache_control`, `context_management`, `container`, `mcp_servers`
 
 See [docs/transcoding.md](docs/transcoding.md) for the full translation table and known limitations.
 

{eggpool-0.4.2 → eggpool-0.4.4}/README.md

@@ -104,8 +104,8 @@ When `[transcoder] enabled = true`, EggPool bridges OpenAI Chat Completions and
 
 What gets translated:
 
-- Request bodies (text-only in v1)
-- Streaming SSE events
+- Request bodies (text + tool-use + vision + thinking + structured outputs)
+- Streaming SSE events (including tool-call deltas and thinking deltas)
 - Non-retryable error envelopes
 - Usage and cost fields (preserved exactly as the upstream reported them)
 
@@ -114,12 +114,13 @@ 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):
+Phase 6 feature flags (`[transcoder.features]`) — all **off** by default:
 
-- Tool calls / function calling
-- Vision / image content
-- Extended thinking / reasoning
-- Structured outputs (`response_format` / `json_schema`)
+- `tools` — bidirectional tool calling translation
+- `vision` — image/document content parts
+- `thinking` — extended thinking ↔ reasoning_content
+- `structured_outputs` — `response_format` / `json_schema` coercion
+- `anthropic_primitives` — `top_k`, `cache_control`, `context_management`, `container`, `mcp_servers`
 
 See [docs/transcoding.md](docs/transcoding.md) for the full translation table and known limitations.
 

{eggpool-0.4.2 → eggpool-0.4.4}/architecture/README.md

@@ -174,6 +174,8 @@ scope (phases 4–6).
 
 **Phase 5 — Operator controls and docs**: the default `[transcoder]` config block is documented 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 a startup line announces transcoding state. See `docs/transcoding.md` for the full operator guide.
 
+**Phase 6.1 — Tool-use transcoding**: bidirectional tool calling translation in both directions for non-streaming and streaming requests. `OpenAIToAnthropic.encode_request` / `decode_response` and `AnthropicToOpenAI.encode_request` / `decode_response` translate `tools`, `tool_choice`, `parallel_tool_calls`, assistant `tool_calls` history, `role: "tool"` history, and `tool_use` / `tool_result` content blocks. A per-request `ToolCallIdMap` (on `TranscodeContext.id_map`) mints `call_<24 hex>` and `toolu_<24 hex>` ids so the two namespaces never collide. The streaming transcoders (`OpenAIToAnthropicStreaming`, `AnthropicToOpenAIStreaming`) extend their state machines to track `content_block_start` / `input_json_delta` / `content_block_stop` triples and emit OpenAI `tool_calls` deltas in insertion order; the reverse direction buffers OpenAI `tool_calls[*].function.arguments` chunks and flushes Anthropic `tool_use` blocks on `finish_reason: "tool_calls"`. Anthropic's `pause_turn` `stop_reason` maps to `finish_reason: "tool_calls"` plus a synthetic `__eggpool_pause_turn__` tool_call entry so OpenAI clients can detect pause-and-resume flows. `stream_options.include_usage` is lifted onto `TranscodeContext.request_include_usage` so the streaming transcoder can decide whether to forward upstream usage chunks. New loss-warning kinds (`tool_call_id_translated`, `tool_call_id_changed`, `parallel_tool_calls_collapsed`, `malformed_tool_arguments`, `invalid_tool_choice`, `unsupported_tool_type`, `empty_tool_use_block`, `tool_result_image_dropped`, `tool_result_error_passthrough`, `cache_control_dropped`, `pause_turn`, `non_text_content_dropped`, `tool_result_inferred`) are added to `LOSS_WARNING_KINDS`. See `docs/transcoding.md` § Tool-Use Transcoding and `plans/tooltranscoding.md` for the full design.
+
 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.