eggpool 0.1.0__tar.gz

eggpool-0.1.0/.env.example

@@ -0,0 +1,9 @@
+# EggPool environment variables
+#
+# API keys are now stored inline in config.toml via the `connect` command.
+# This file is only needed if you use api_key_env (env var) instead of inline keys.
+#
+# Example:
+#   OPENCODE_GO_KEY=sk-your-opencode-go-key
+#
+# See config.example.toml for all available configuration options.

eggpool-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  PYTHONHASHSEED: "0"
+  TZ: UTC
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --frozen --extra dev
+      - run: uv run ruff format --check src/ tests/ scripts/
+      - run: uv run ruff check src/ tests/ scripts/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --frozen --extra dev
+      - run: uv run pyright src/ scripts/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --frozen --extra dev
+      - name: Verify coverage plugin is present
+        run: uv run pytest --help | grep -- --cov
+      - name: Run tests with coverage
+        run: >-
+          uv run pytest
+          --cov=eggpool
+          --cov-report=term-missing
+          --cov-report=xml
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml

eggpool-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

eggpool-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# uv
+.uv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+coverage.xml
+
+# Type checking
+.pyright/
+.pytype/
+
+# Ruff
+.ruff_cache/
+
+# Database
+*.sqlite3
+*.sqlite3-wal
+*.sqlite3-shm
+
+# Environment files
+.env
+.env.local
+.env.production
+.envrc
+.env.*
+!.env.example
+secrets.env
+*.env.local
+gorouter.env
+gorouter.env.local
+
+# Configuration with secrets
+config.toml
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+/var/
+*.log
+bugs.md

eggpool-0.1.0/AGENTS.md

@@ -0,0 +1,113 @@
+# 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.12+ 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/`
+
+## Multi-Provider Architecture
+
+- Provider-suffixed model IDs: `model-id/provider-id` (e.g., `claude-sonnet-4/opencode-go`)
+- `ProviderClientPool` manages per-provider `httpx.AsyncClient` with independent connection pools
+- Flat `[[accounts]]` configs auto-normalize to a default `opencode-go` provider
+- `parse_model_provider()` and `format_model_provider()` in `routing/provider.py`
+
+## Provider Contracts
+
+Key design rules that are easy to get wrong:
+
+- `compose_provider_url()` is the single source of truth for upstream URLs — catalog fetch, non-streaming chat, and streaming chat all call it
+- `build_auth_headers()` reads from `ProviderConfig.auth` — never hardcode Bearer
+- `base_url` ending `/v1` + path beginning `/v1/` is rejected (duplicate version prefix)
+- `auth.mode = "none"` sends no upstream auth (Ollama local)
+- All outbound dispatch paths use `compose_provider_url()` so providers cannot list at one host and dispatch to another
+
+## Bearer-prefix Guard
+
+`AppConfig.validate_account_credentials()` rejects API keys beginning with `Bearer` for `auth.mode = "bearer"` providers. EggPool prepends `Bearer ` automatically; storing `Bearer <token>` produces `Authorization: Bearer Bearer <token>` and causes 401s. Providers using `auth.mode = "raw_authorization"` are unaffected.
+
+## 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`
+
+## Gotchas
+
+- Configuration changes require a service restart; live reload is intentionally not supported
+- No CI workflows or pre-commit hooks are configured in this repo
+- `Database.vacuum()` is the only sanctioned path for `VACUUM` in production code
+- Every DML write must run inside `async with db.transaction():`
+- SQLite transactions are serialized across concurrent tasks via a single connection lock + ContextVar
+- Requests must be persisted before upstream dispatch; pre-body failures can retry, but no retry after first downstream byte
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `eggpool serve` | Start the aggregation proxy server (default command) |
+| `eggpool check-config` | Validate the configuration file |
+| `eggpool migrate` | Run database migrations |
+| `eggpool onboard` | Run the interactive onboarding setup |
+| `eggpool connect` | Connect to a new provider interactively |
+| `eggpool connect list` | List available providers |
+| `eggpool logout` | Remove a configured provider account |
+| `eggpool rehash` | Restart to apply config changes |
+| `eggpool models refresh` | Refresh model catalog from upstream |
+| `eggpool configsetup opencode` | Print OpenCode provider config JSON with model limits |
+| `eggpool db vacuum` | Reclaim SQLite space |
+
+All commands accept `--config /path/to/config.toml` (defaults to `config.toml`).
+
+## Git Workflow
+
+- Branch: `main`
+- Commit messages: concise, imperative mood
+- Never commit secrets, API keys, or `.env` files

eggpool-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to EggPool are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-23
+
+### Added
+
+- Multi-provider aggregation across OpenAI- and Anthropic-compatible
+  upstreams with quota-aware routing.
+- SQLite-backed request, token, latency, error, and cost statistics.
+- Multi-page HTML dashboard (overview, accounts, models, latency, pings,
+  events, timeseries, bandwidth) with 50+ Halloy themes.
+- CLI commands: `serve`, `check-config`, `migrate`, `onboard`,
+  `connect`, `connect list`, `logout`, `accounts list`,
+  `accounts status`, `models refresh`, `db vacuum`, `dashboard public`,
+  `rehash`, `restart`, `stop`, `update`, `getkey`, `newkey`, `edit`,
+  `configsetup opencode`, `configsetup claude-code`, `set`,
+  `init-config`, and the `deploy` group (`systemd`, `logrotate`,
+  `cron`, `all`).
+- Operational scripts: `install.sh`, `install_prompt.py`,
+  `check_database.py`, `smoke_test.py`, `verify_upstream_auth.py`.
+
+### Notes
+
+- See the README and `docs/deployment.md` for install, configuration,
+  and deployment.

eggpool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Bowman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.