eggpool 0.3.4__tar.gz → 0.3.5__tar.gz

eggpool-0.3.5/AGENTS.md

@@ -0,0 +1,103 @@
+# AGENTS.md
+
+## Skills
+
+Project-specific skills are in `.opencode/skills/`:
+
+- `architecture` — design principles, request lifecycle, invariants, error hierarchy
+- `deployment` — production deployment, systemd, operational scripts
+- `development` — linting, testing, pre-commit checks, code style
+
+## Quick Start
+
+- Package manager: **uv** (not pip). Install deps: `uv sync --extra dev`
+- Entry point: `src/eggpool/cli.py` → `eggpool` console script
+- Config: `config.toml` + `.env` for API keys
+
+## Pre-commit Checks (run before every commit)
+
+```bash
+uv run ruff format --check src/ tests/ scripts/
+uv run ruff check src/ tests/ scripts/
+uv run pyright src/ scripts/
+uv run pytest
+```
+
+All four must pass with zero errors.
+
+## Code Style
+
+- Python 3.11+ with `from __future__ import annotations` in ALL files
+- Type hints on all function signatures and return types
+- Ruff: E, F, W, I, N, UP, B, A, SIM, TCH rules
+- Pyright strict mode — covers `src/` AND `scripts/` (not tests)
+- Line length: 88 chars
+- Use `NoReturn` for functions that never return (e.g., `sys.exit`)
+
+## Testing
+
+- pytest with `asyncio_mode = "strict"` (from `pyproject.toml`)
+- respx for HTTPX upstream mocking
+- Tests in `tests/unit/`, `tests/integration/`, `tests/contract/`
+- Provider contract tests: `uv run pytest tests/unit/test_contract.py tests/unit/test_contract_urls.py -v`
+
+## File Organization
+
+- Source: `src/eggpool/`
+- Tests: `tests/` (mirrors src structure)
+- Config: `config.example.toml`, `.env.example`
+- DB schema: `src/eggpool/db/schema/`
+- Scripts: `scripts/` (operational, also type-checked by pyright)
+- Deployment: `deploy/`
+
+## Architecture Index
+
+> Full design details are in `architecture/README.md` and the `architecture` skill.
+
+- **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.
+- **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.
+- **Process model**: supervisor + Granian worker, PID file lifecycle, daemon mode. See `architecture/README.md` § Daemon Mode.
+- **Dashboard**: server-rendered HTML, 12 pages, Chart.js v4, grouped timeseries, CSS tooltips. See `architecture` skill § Dashboard.
+- **Observability**: attempt analytics, routing analytics, latency phases, pending health, runtime metrics. See `architecture` skill § Runtime Observability.
+
+## Gotchas
+
+- 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.
+
+## Error Handling
+
+Use the hierarchy in `errors.py`. Chain exceptions with `raise ... from err` or `raise ... from None`.
+
+- `AggregatorError` → `ConfigError`, `DatabaseError`, `ProxyError`
+- `UpstreamError` (has `status_code`) → `TemporaryUpstreamError`, `TransientUpstreamError`, `AuthenticationError`, `QuotaExhaustedError`, `RateLimitError` (has `retry_after`), `ModelUnavailableError`
+- `ModelNotFoundError` (has `model_id`), `NoEligibleAccountError`, `CatalogUnavailableError`, `AuthenticationUnavailableError`, `UpstreamExhaustedError`, `AccountSuspendedError`, `RequestTooLargeError`, `ContextLimitExceededError`
+
+## Fast-Path CLI
+
+- `src/eggpool/cli.py` is a tiny bootstrap (74 lines)
+- `main()` calls `eggpool.fastcli.maybe_run_fast_command()` first; recognized fast commands (`croncheck`, `ensure-running`) are dispatched without importing Click
+- **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`
+- Commit messages: concise, imperative mood
+- Never commit secrets, API keys, or `.env` files

{eggpool-0.3.4 → eggpool-0.3.5}/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.5] - 2026-06-27
+
+### Changed
+
+- **README rewrite**: condensed the README from 870 lines to a concise, user-focused overview with quick start, CLI reference, configuration summary, API endpoints, and a documentation table linking to dedicated docs. Detailed content (deployment, providers, proxy, backup, model limits, Raspberry Pi, firewall, filesystem layout, network diagnostics) now lives in `docs/` and is linked from the README where it makes sense.
+
 ## [0.3.4] - 2026-06-27
 
 ### Fixed

eggpool-0.3.5/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: eggpool
+Version: 0.3.5
+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
+Project-URL: Issues, https://github.com/eggstack/eggpool/issues
+Project-URL: Documentation, https://github.com/eggstack/eggpool/tree/main/docs
+Project-URL: Changelog, https://github.com/eggstack/eggpool/blob/main/CHANGELOG.md
+Author-email: David Bowman <dbowman91@proton.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aggregation,anthropic,llm,multi-account,openai,opencode,proxy,router
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite
+Requires-Dist: click
+Requires-Dist: fastapi
+Requires-Dist: granian[pname]
+Requires-Dist: httpx
+Requires-Dist: pproxy>=2.7.9
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: coverage[toml]; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![PyPI version](https://badge.fury.io/py/eggpool.svg)](https://pypi.org/project/eggpool/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/eggstack/eggpool/actions/workflows/ci.yml/badge.svg)](https://github.com/eggstack/eggpool/actions/workflows/ci.yml)
+
+# EggPool
+
+A lightweight, LAN-hosted proxy that aggregates multiple AI provider accounts behind one OpenAI/Anthropic-compatible endpoint.
+
+## Features
+
+- Proxies model requests across multiple providers and accounts behind a single endpoint
+- Supports OpenAI-compatible and Anthropic-compatible upstream request paths
+- Dynamically discovers available models; routes by quota utilization
+- Per-account outbound proxy support ([pproxy](https://pypi.org/project/pproxy/) — SOCKS5, HTTP, Shadowsocks)
+- 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)
+
+## Quick Start
+
+```bash
+# Install (one-shot)
+curl -fsSL https://raw.githubusercontent.com/eggstack/eggpool/main/scripts/install.sh | bash
+
+# Interactive onboarding — connect providers, validate, start
+eggpool onboard
+
+# Install as a systemd service
+sudo env "PATH=$PATH" "$(command -v eggpool)" deploy systemd --install
+```
+
+See [Deployment](docs/deployment.md) for alternative install methods (pipx, manual, production) and the full deployment guide.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `eggpool serve` | Start the proxy server (`--daemon` to detach) |
+| `eggpool onboard` | Interactive onboarding wizard |
+| `eggpool connect` | Add a provider account interactively |
+| `eggpool connect list` | List supported providers |
+| `eggpool check-config` | Validate configuration |
+| `eggpool migrate` | Run database migrations |
+| `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 runtime-status` | Print runtime health summary |
+| `eggpool backup` | Create a timestamped backup |
+| `eggpool recover` | Restore from a backup archive |
+| `eggpool deploy systemd` | Install/manage systemd service |
+| `eggpool deploy cron` | Install watchdog cron (non-systemd) |
+| `eggpool update` | Check for and install updates |
+
+All commands accept `--config /path/to/config.toml`. Config resolution: `--config` > `$EGGPOOL_CONFIG` > `~/.config/eggpool/config.toml` > `./config.toml`.
+
+Full command reference: [docs/deployment.md](docs/deployment.md#deploy-commands-reference)
+
+## Configuration
+
+Configuration lives in a single TOML file. API keys are loaded from environment variables or `.env`.
+
+```toml
+# Example provider configuration
+[providers.opencode-go]
+id = "opencode-go"
+base_url = "https://opencode.ai/zen/go/v1"
+protocols = ["openai", "anthropic"]
+
+[[providers.opencode-go.accounts]]
+name = "personal"
+api_key = "sk-your-opencode-go-key"
+```
+
+Use `eggpool connect` for interactive provider setup. See [docs/providers.md](docs/providers.md) for the full provider catalog, configuration details, and troubleshooting.
+
+### Key Config Sections
+
+| Section | Purpose |
+|---------|---------|
+| `[server]` | Bind address, port (default 11300), API key, logging, threads |
+| `[upstream]` | Upstream API base URL, timeouts, connection pool |
+| `[database]` | SQLite path, WAL mode |
+| `[models]` | Catalog refresh, exposure mode, model collapse |
+| `[routing]` | Routing strategy, retry limits, quota mode |
+| `[dashboard]` | Dashboard toggle, theme, refresh interval |
+| `[providers.*]` | Provider configs with accounts and routing priority |
+| `[network]` | Outbound transport, DNS cache |
+
+Full config reference: [`config.example.toml`](config.example.toml) | [docs/providers.md](docs/providers.md)
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/models` | List available models |
+| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completions |
+| `POST` | `/v1/messages` | Anthropic-compatible messages |
+| `GET` | `/v1/healthz` | Liveness check |
+| `GET` | `/v1/readyz` | Readiness check |
+
+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/*`.
+
+## Documentation
+
+| Topic | Link |
+|-------|------|
+| Deployment (install, systemd, production) | [docs/deployment.md](docs/deployment.md) |
+| Provider catalog & configuration | [docs/providers.md](docs/providers.md) |
+| Backup & restore | [docs/backup-restore.md](docs/backup-restore.md) |
+| Per-account outbound proxy | [docs/proxy.md](docs/proxy.md) |
+| Model context limits | [docs/model-limits.md](docs/model-limits.md) |
+| Raspberry Pi setup | [docs/raspberry-pi.md](docs/raspberry-pi.md) |
+| 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) |
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check src/ tests/ scripts/
+uv run ruff format src/ tests/ scripts/
+uv run pyright src/ scripts/
+uv run pytest
+```
+
+## License
+
+MIT

eggpool-0.3.5/README.md

@@ -0,0 +1,131 @@
+[![PyPI version](https://badge.fury.io/py/eggpool.svg)](https://pypi.org/project/eggpool/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/eggstack/eggpool/actions/workflows/ci.yml/badge.svg)](https://github.com/eggstack/eggpool/actions/workflows/ci.yml)
+
+# EggPool
+
+A lightweight, LAN-hosted proxy that aggregates multiple AI provider accounts behind one OpenAI/Anthropic-compatible endpoint.
+
+## Features
+
+- Proxies model requests across multiple providers and accounts behind a single endpoint
+- Supports OpenAI-compatible and Anthropic-compatible upstream request paths
+- Dynamically discovers available models; routes by quota utilization
+- Per-account outbound proxy support ([pproxy](https://pypi.org/project/pproxy/) — SOCKS5, HTTP, Shadowsocks)
+- 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)
+
+## Quick Start
+
+```bash
+# Install (one-shot)
+curl -fsSL https://raw.githubusercontent.com/eggstack/eggpool/main/scripts/install.sh | bash
+
+# Interactive onboarding — connect providers, validate, start
+eggpool onboard
+
+# Install as a systemd service
+sudo env "PATH=$PATH" "$(command -v eggpool)" deploy systemd --install
+```
+
+See [Deployment](docs/deployment.md) for alternative install methods (pipx, manual, production) and the full deployment guide.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `eggpool serve` | Start the proxy server (`--daemon` to detach) |
+| `eggpool onboard` | Interactive onboarding wizard |
+| `eggpool connect` | Add a provider account interactively |
+| `eggpool connect list` | List supported providers |
+| `eggpool check-config` | Validate configuration |
+| `eggpool migrate` | Run database migrations |
+| `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 runtime-status` | Print runtime health summary |
+| `eggpool backup` | Create a timestamped backup |
+| `eggpool recover` | Restore from a backup archive |
+| `eggpool deploy systemd` | Install/manage systemd service |
+| `eggpool deploy cron` | Install watchdog cron (non-systemd) |
+| `eggpool update` | Check for and install updates |
+
+All commands accept `--config /path/to/config.toml`. Config resolution: `--config` > `$EGGPOOL_CONFIG` > `~/.config/eggpool/config.toml` > `./config.toml`.
+
+Full command reference: [docs/deployment.md](docs/deployment.md#deploy-commands-reference)
+
+## Configuration
+
+Configuration lives in a single TOML file. API keys are loaded from environment variables or `.env`.
+
+```toml
+# Example provider configuration
+[providers.opencode-go]
+id = "opencode-go"
+base_url = "https://opencode.ai/zen/go/v1"
+protocols = ["openai", "anthropic"]
+
+[[providers.opencode-go.accounts]]
+name = "personal"
+api_key = "sk-your-opencode-go-key"
+```
+
+Use `eggpool connect` for interactive provider setup. See [docs/providers.md](docs/providers.md) for the full provider catalog, configuration details, and troubleshooting.
+
+### Key Config Sections
+
+| Section | Purpose |
+|---------|---------|
+| `[server]` | Bind address, port (default 11300), API key, logging, threads |
+| `[upstream]` | Upstream API base URL, timeouts, connection pool |
+| `[database]` | SQLite path, WAL mode |
+| `[models]` | Catalog refresh, exposure mode, model collapse |
+| `[routing]` | Routing strategy, retry limits, quota mode |
+| `[dashboard]` | Dashboard toggle, theme, refresh interval |
+| `[providers.*]` | Provider configs with accounts and routing priority |
+| `[network]` | Outbound transport, DNS cache |
+
+Full config reference: [`config.example.toml`](config.example.toml) | [docs/providers.md](docs/providers.md)
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/v1/models` | List available models |
+| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completions |
+| `POST` | `/v1/messages` | Anthropic-compatible messages |
+| `GET` | `/v1/healthz` | Liveness check |
+| `GET` | `/v1/readyz` | Readiness check |
+
+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/*`.
+
+## Documentation
+
+| Topic | Link |
+|-------|------|
+| Deployment (install, systemd, production) | [docs/deployment.md](docs/deployment.md) |
+| Provider catalog & configuration | [docs/providers.md](docs/providers.md) |
+| Backup & restore | [docs/backup-restore.md](docs/backup-restore.md) |
+| Per-account outbound proxy | [docs/proxy.md](docs/proxy.md) |
+| Model context limits | [docs/model-limits.md](docs/model-limits.md) |
+| Raspberry Pi setup | [docs/raspberry-pi.md](docs/raspberry-pi.md) |
+| 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) |
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check src/ tests/ scripts/
+uv run ruff format src/ tests/ scripts/
+uv run pyright src/ scripts/
+uv run pytest
+```
+
+## License
+
+MIT

{eggpool-0.3.4 → eggpool-0.3.5}/architecture/README.md

@@ -457,9 +457,15 @@ Production (`eggpool deploy systemd --install --production`):
 
 ## Background Tasks
 
-`TaskSupervisor` (`background/__init__.py`) manages long-running loops with restart-on-failure and exponential backoff:
-- Catalog refresh (configurable interval, default 300s)
-- Retention cleanup (old requests, events, pings)
-- Periodic checkpoint
-- Usage window refresh
-- Reservation expiry reconciliation
+`TaskSupervisor` (`background/__init__.py`) manages long-running loops with restart-on-failure and exponential backoff. All tasks are registered in `app.py` during lifespan setup:
+
+| Task | Condition | Description |
+|------|-----------|-------------|
+| `catalog_refresh` | `refresh_interval_s > 0` | Periodic upstream model catalog refresh |
+| `retention_cleanup` | Always | Hourly cleanup of old requests, events, pings, rollups, and expired reservations |
+| `checkpoint` | Always | Periodic SQLite WAL checkpoint (every 4h) |
+| `usage_window_refresh` | Always | Refreshes persisted usage windows every 60s |
+| `stale_request_finalizer` | Always | Safety net for leaked streaming requests (every 60s) |
+| `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` |

{eggpool-0.3.4 → eggpool-0.3.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "eggpool"
-version = "0.3.4"
+version = "0.3.5"
 description = "A lightweight proxy that aggregates multiple LLM provider accounts behind one OpenAI-compatible endpoint"
 readme = "README.md"
 requires-python = ">=3.11"

{eggpool-0.3.4 → eggpool-0.3.5}/src/eggpool/accounts/state.py

@@ -31,7 +31,7 @@ def _failure_backoff(consecutive_failures: int) -> float:
     )
 
 
-@dataclass
+@dataclass(slots=True)
 class AccountRuntimeState:
     """Mutable runtime state for an account."""
 

{eggpool-0.3.4 → eggpool-0.3.5}/src/eggpool/app.py

@@ -1125,23 +1125,20 @@ def create_app(
             def __init__(self, max_size: int = 3, ttl_s: int = 300) -> None:
                 self._max_size = max_size
                 self._ttl_s = ttl_s
-                self._cache: dict[str, tuple[str, float]] = {}
-                self._last_used: str = ""
-
-            def get(self, theme_name: str) -> str | None:
-                if theme_name in self._cache:
-                    css, ts = self._cache[theme_name]
-                    if (
-                        time.monotonic() - ts < self._ttl_s
-                        or theme_name == self._last_used
-                    ):
-                        self._last_used = theme_name
+                self._cache: dict[tuple[str, str | None], tuple[str, float]] = {}
+                self._last_used: tuple[str, str | None] | None = None
+
+            def get(self, key: tuple[str, str | None]) -> str | None:
+                if key in self._cache:
+                    css, ts = self._cache[key]
+                    if time.monotonic() - ts < self._ttl_s or key == self._last_used:
+                        self._last_used = key
                         return css
-                    del self._cache[theme_name]
+                    del self._cache[key]
                 return None
 
-            def put(self, theme_name: str, css: str) -> None:
-                if len(self._cache) >= self._max_size and theme_name not in self._cache:
+            def put(self, key: tuple[str, str | None], css: str) -> None:
+                if len(self._cache) >= self._max_size and key not in self._cache:
                     now = time.monotonic()
                     to_evict = [
                         k
@@ -1157,15 +1154,17 @@ def create_app(
                         )
                         if oldest != self._last_used:
                             del self._cache[oldest]
-                self._cache[theme_name] = (css, time.monotonic())
-                self._last_used = theme_name
+                self._cache[key] = (css, time.monotonic())
+                self._last_used = key
 
         _theme_css_cache = _ThemeCssCache()
 
         @app.get("/static/theme.css")
         async def theme_css(request: Request) -> Response:  # pyright: ignore[reportUnusedFunction]
             theme_name = request.query_params.get("theme", "default")
-            cached = _theme_css_cache.get(theme_name)
+            themes_dir = config.dashboard.themes_dir
+            cache_key = (theme_name, themes_dir)
+            cached = _theme_css_cache.get(cache_key)
             if cached is not None:
                 return Response(
                     content=cached,
@@ -1174,8 +1173,8 @@ def create_app(
                 )
             from eggpool.dashboard.render import get_theme_css
 
-            css = get_theme_css(theme_name)
-            _theme_css_cache.put(theme_name, css)
+            css = get_theme_css(theme_name, themes_dir)
+            _theme_css_cache.put(cache_key, css)
             return Response(
                 content=css,
                 media_type="text/css",