eggpool 0.1.0__tar.gz → 0.1.2__tar.gz

{eggpool-0.1.0 → eggpool-0.1.2}/.github/workflows/ci.yml

@@ -36,12 +36,15 @@ jobs:
 
   test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
       - run: uv sync --frozen --extra dev
       - name: Verify coverage plugin is present
         run: uv run pytest --help | grep -- --cov
@@ -55,5 +58,5 @@ jobs:
         if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: coverage-report
+          name: coverage-report-py${{ matrix.python-version }}
           path: coverage.xml

{eggpool-0.1.0 → eggpool-0.1.2}/AGENTS.md

@@ -27,7 +27,7 @@ All four must pass with zero errors.
 
 ## Code Style
 
-- Python 3.12+ with `from __future__ import annotations` in ALL files
+- 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)
@@ -92,19 +92,23 @@ Use the hierarchy in `errors.py`. Chain exceptions with `raise ... from err` or
 
 | Command | Description |
 |---------|-------------|
+| `eggpool help` | Show help message and available commands |
+| `eggpool version` | Print the installed version |
 | `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 onboard` | Run the interactive onboarding setup (connect providers, start server) |
 | `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 croncheck` | Lightweight check: exit 0 if server is running, exit 1 if not |
 | `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`).
+Running `eggpool` with no arguments prints the help message.
 
 ## Git Workflow
 

{eggpool-0.1.0 → eggpool-0.1.2}/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.2] - 2026-06-23
+
+### Fixed
+
+- Create minimal config when `config.toml` is missing during `eggpool
+  onboard`, so fresh installs no longer fail with "Failed to update config".
+- Fix `update` command misidentifying source installs as pipx (causing
+  wrong upgrade method).
+
+### Changed
+
+- Add `--install` flag to `deploy` subcommands for automated setup.
+- Rewrite deployment docs with personal-use and production sections.
+
+## [0.1.1] - 2026-06-23
+
+### Added
+
+- `eggpool deploy` subcommands: `systemd`, `logrotate`, `cron`, `all`.
+- Dynamic deploy snippets based on detected install paths.
+
 ## [0.1.0] - 2026-06-23
 
 ### Added

{eggpool-0.1.0 → eggpool-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eggpool
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -19,10 +19,11 @@ 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.12
+Requires-Python: >=3.11
 Requires-Dist: aiosqlite
 Requires-Dist: click
 Requires-Dist: fastapi
@@ -42,7 +43,7 @@ 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.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
+[![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)
 
@@ -65,7 +66,7 @@ behind one OpenAI/Anthropic-compatible endpoint.
 
 ## Requirements
 
-- Python 3.12+
+- Python 3.11+
 - [uv](https://docs.astral.sh/uv/) for dependency management
 
 ## Quick Start
@@ -74,25 +75,16 @@ behind one OpenAI/Anthropic-compatible endpoint.
 
 ```bash
 pipx install eggpool
-pipx run eggpool --help   # or just `eggpool --help` if PATH includes it
+eggpool help
+eggpool onboard
 ```
 
-`pipx` installs `eggpool` into its own venv and exposes the
-`eggpool` console script globally. The bundled themes and
-provider templates ship inside the package — no extra files
-required to start.
+`eggpool onboard` lets you add several providers at once, does a config check, then runs the server. You can also run `eggpool connect` for each provider you want to add and `eggpool serve` to start the server. 
+`eggpool configsetup` will help setup config for opencode. 
 
-Then copy and edit configuration:
+To get the server to run on startup, run `eggpool deploy` for options, see docs/deployment.md for more info and configs.
 
-```bash
-cp /path/to/your/eggpool-venv/lib/python*/site-packages/eggpool/_share/config.example.toml ~/.config/eggpool/config.toml
-```
-
-Or use the built-in helper:
-
-```bash
-eggpool init-config
-```
+`pipx` installs `eggpool` into its own venv and exposes the `eggpool` command on your PATH.
 
 ### Option 2: Automated install
 
@@ -104,13 +96,14 @@ The script:
 
 - Downloads the repository if not running from a clone
 - Installs `uv` if missing
-- Verifies Python 3.12+
+- Verifies Python 3.11+
 - Installs dependencies
 - Copies example configuration files
 - Attempts configuration validation
 
-Validation fails until `.env` contains real, non-placeholder keys. Edit
-`config.toml` and `.env`, then run the validation and migration commands below.
+The script will ask if you want to continue with onboarding. if you select no, make sure you `cd eggpool`, then you can run `uv run eggpool onboard` to get started. `uv run eggpool connect` for one off provider adds, `uv run eggpool serve` to start server. `uv run eggpool help` for other commands. 
+
+Run `uv run eggpool deploy` for options on running the server on startup. See docs/deployment.md for more info and configs.
 
 ### Option 3: Manual install
 
@@ -127,19 +120,20 @@ cp .env.example .env
 
 # Validate configuration
 set -a; source .env; set +a
-uv run eggpool --config config.toml check-config
+uv run eggpool check-config
 
 # Run database migrations
-uv run eggpool --config config.toml migrate
+uv run eggpool migrate
 
 # Start the server
-uv run eggpool --config config.toml serve
+uv run eggpool serve
 ```
 
 ### Option 4: Interactive setup
 
 ```bash
-# Run the interactive onboarding wizard
+# Run the interactive onboarding wizard — connects one or more
+# providers, validates configuration, and starts the server.
 uv run eggpool onboard
 
 # Or connect to a specific provider
@@ -151,10 +145,12 @@ uv run eggpool connect list
 
 | Command | Description |
 |---------|-------------|
+| `eggpool help` | Show help message and available commands |
+| `eggpool version` | Print the installed version |
 | `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 onboard` | Run the interactive onboarding setup (connect providers, start server) |
 | `eggpool connect` | Connect to a new provider interactively |
 | `eggpool connect list` | List available providers for connection |
 | `eggpool logout` | Remove a configured provider account |
@@ -169,6 +165,7 @@ uv run eggpool connect list
 | `eggpool configsetup opencode` | Print OpenCode provider config JSON with model limits |
 | `eggpool configsetup claude-code` | Print Claude Code config snippet |
 | `eggpool update` | Check for updates and reinstall if newer |
+| `eggpool croncheck` | Lightweight check: exit 0 if server is running, exit 1 if not |
 | `eggpool models refresh` | Refresh the model catalog from upstream |
 | `eggpool accounts status` | Show configured account status |
 | `eggpool accounts list` | List configured provider accounts |
@@ -181,6 +178,7 @@ uv run eggpool connect list
 | `eggpool deploy all` | Print every deployment snippet in sequence |
 
 All commands accept `--config /path/to/config.toml` (defaults to `config.toml`).
+Running `eggpool` with no arguments prints the help message.
 Configuration changes require a service restart; live reload is intentionally
 not supported.
 
@@ -492,14 +490,28 @@ MIT
 
 ## Deployment
 
-See `docs/deployment.md` for production deployment instructions.
+See `docs/deployment.md` for full deployment instructions.
 
-For production (systemd):
+### Quick start (personal use)
 
 ```bash
-sudo systemctl enable --now eggpool
+pipx install eggpool
+eggpool onboard
+sudo eggpool deploy systemd --install
 ```
 
+The `--install` flag writes the systemd unit, enables the service,
+and starts it — all in one command. It detects your install method
+and config paths automatically.
+
+### Production (separate user, hardened)
+
+For public-facing deployments, see the Production Deployment section
+in `docs/deployment.md`. This creates a dedicated `eggpool` system
+user with proper file permissions.
+
+### Configuration changes
+
 Configuration changes require a service restart; the unit
 intentionally does not advertise any reload action:
 

{eggpool-0.1.0 → eggpool-0.1.2}/README.md

@@ -1,5 +1,5 @@
 [![PyPI version](https://badge.fury.io/py/eggpool.svg)](https://pypi.org/project/eggpool/)
-[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
+[![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)
 
@@ -22,7 +22,7 @@ behind one OpenAI/Anthropic-compatible endpoint.
 
 ## Requirements
 
-- Python 3.12+
+- Python 3.11+
 - [uv](https://docs.astral.sh/uv/) for dependency management
 
 ## Quick Start
@@ -31,25 +31,16 @@ behind one OpenAI/Anthropic-compatible endpoint.
 
 ```bash
 pipx install eggpool
-pipx run eggpool --help   # or just `eggpool --help` if PATH includes it
+eggpool help
+eggpool onboard
 ```
 
-`pipx` installs `eggpool` into its own venv and exposes the
-`eggpool` console script globally. The bundled themes and
-provider templates ship inside the package — no extra files
-required to start.
+`eggpool onboard` lets you add several providers at once, does a config check, then runs the server. You can also run `eggpool connect` for each provider you want to add and `eggpool serve` to start the server. 
+`eggpool configsetup` will help setup config for opencode. 
 
-Then copy and edit configuration:
+To get the server to run on startup, run `eggpool deploy` for options, see docs/deployment.md for more info and configs.
 
-```bash
-cp /path/to/your/eggpool-venv/lib/python*/site-packages/eggpool/_share/config.example.toml ~/.config/eggpool/config.toml
-```
-
-Or use the built-in helper:
-
-```bash
-eggpool init-config
-```
+`pipx` installs `eggpool` into its own venv and exposes the `eggpool` command on your PATH.
 
 ### Option 2: Automated install
 
@@ -61,13 +52,14 @@ The script:
 
 - Downloads the repository if not running from a clone
 - Installs `uv` if missing
-- Verifies Python 3.12+
+- Verifies Python 3.11+
 - Installs dependencies
 - Copies example configuration files
 - Attempts configuration validation
 
-Validation fails until `.env` contains real, non-placeholder keys. Edit
-`config.toml` and `.env`, then run the validation and migration commands below.
+The script will ask if you want to continue with onboarding. if you select no, make sure you `cd eggpool`, then you can run `uv run eggpool onboard` to get started. `uv run eggpool connect` for one off provider adds, `uv run eggpool serve` to start server. `uv run eggpool help` for other commands. 
+
+Run `uv run eggpool deploy` for options on running the server on startup. See docs/deployment.md for more info and configs.
 
 ### Option 3: Manual install
 
@@ -84,19 +76,20 @@ cp .env.example .env
 
 # Validate configuration
 set -a; source .env; set +a
-uv run eggpool --config config.toml check-config
+uv run eggpool check-config
 
 # Run database migrations
-uv run eggpool --config config.toml migrate
+uv run eggpool migrate
 
 # Start the server
-uv run eggpool --config config.toml serve
+uv run eggpool serve
 ```
 
 ### Option 4: Interactive setup
 
 ```bash
-# Run the interactive onboarding wizard
+# Run the interactive onboarding wizard — connects one or more
+# providers, validates configuration, and starts the server.
 uv run eggpool onboard
 
 # Or connect to a specific provider
@@ -108,10 +101,12 @@ uv run eggpool connect list
 
 | Command | Description |
 |---------|-------------|
+| `eggpool help` | Show help message and available commands |
+| `eggpool version` | Print the installed version |
 | `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 onboard` | Run the interactive onboarding setup (connect providers, start server) |
 | `eggpool connect` | Connect to a new provider interactively |
 | `eggpool connect list` | List available providers for connection |
 | `eggpool logout` | Remove a configured provider account |
@@ -126,6 +121,7 @@ uv run eggpool connect list
 | `eggpool configsetup opencode` | Print OpenCode provider config JSON with model limits |
 | `eggpool configsetup claude-code` | Print Claude Code config snippet |
 | `eggpool update` | Check for updates and reinstall if newer |
+| `eggpool croncheck` | Lightweight check: exit 0 if server is running, exit 1 if not |
 | `eggpool models refresh` | Refresh the model catalog from upstream |
 | `eggpool accounts status` | Show configured account status |
 | `eggpool accounts list` | List configured provider accounts |
@@ -138,6 +134,7 @@ uv run eggpool connect list
 | `eggpool deploy all` | Print every deployment snippet in sequence |
 
 All commands accept `--config /path/to/config.toml` (defaults to `config.toml`).
+Running `eggpool` with no arguments prints the help message.
 Configuration changes require a service restart; live reload is intentionally
 not supported.
 
@@ -449,14 +446,28 @@ MIT
 
 ## Deployment
 
-See `docs/deployment.md` for production deployment instructions.
+See `docs/deployment.md` for full deployment instructions.
 
-For production (systemd):
+### Quick start (personal use)
 
 ```bash
-sudo systemctl enable --now eggpool
+pipx install eggpool
+eggpool onboard
+sudo eggpool deploy systemd --install
 ```
 
+The `--install` flag writes the systemd unit, enables the service,
+and starts it — all in one command. It detects your install method
+and config paths automatically.
+
+### Production (separate user, hardened)
+
+For public-facing deployments, see the Production Deployment section
+in `docs/deployment.md`. This creates a dedicated `eggpool` system
+user with proper file permissions.
+
+### Configuration changes
+
 Configuration changes require a service restart; the unit
 intentionally does not advertise any reload action:
 

{eggpool-0.1.0 → eggpool-0.1.2}/architecture/README.md

@@ -87,7 +87,7 @@ Legacy flat `[[accounts]]` configs auto-normalize to a default `opencode-go` pro
 
 ### Model ID Format
 
-Models are exposed with provider-suffixed IDs: `model-id/provider-id` (e.g., `claude-sonnet-4/opencode-go`). `parse_model_id()` in `catalog/cache.py` handles suffix parsing.
+Models are exposed with provider-suffixed IDs: `model-id/provider-id` (e.g., `claude-sonnet-4/opencode-go`). `parse_model_provider()` in `routing/provider.py` is the canonical suffix parser; `catalog/cache.py` retains a compatibility alias.
 
 ### Provider-Specific Paths
 

eggpool-0.1.2/docs/deployment.md

@@ -0,0 +1,235 @@
+# Deployment Guide
+
+Two deployment modes: **personal use** (quick, current user) and
+**production** (separate user, hardened). Pick the one that fits.
+
+## Personal Use (Recommended for LAN/Raspberry Pi)
+
+Runs under your current user with your existing config. Not intended
+for public-facing deployments.
+
+### 1. Install
+
+```bash
+pipx install eggpool
+eggpool onboard
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/eggstack/eggpool.git && cd eggpool
+uv sync --no-dev
+uv run eggpool onboard
+```
+
+### 2. Start on boot
+
+The `--install` flag writes the systemd unit, enables the service,
+and starts it — all in one command:
+
+```bash
+sudo eggpool deploy systemd --install
+```
+
+This generates a unit file tailored to your system (correct binary
+path, config path, data directory) and sets it up automatically.
+
+Without `--install`, the command prints copy-paste instructions
+instead.
+
+### 3. Verify
+
+```bash
+sudo systemctl status eggpool
+curl http://localhost:11300/v1/healthz
+```
+
+### Other deploy commands
+
+```bash
+# Set up logrotate
+sudo eggpool deploy logrotate --install
+
+# Set up daily backup cron (user cron, ~/backups/eggpool/)
+sudo eggpool deploy cron --install
+
+# Set up everything at once
+sudo eggpool deploy all --install
+```
+
+Without `--install`, each command prints the snippet and manual
+instructions for you to copy-paste.
+
+### Configuration changes
+
+Live reload is not supported. Restart after any config change:
+
+```bash
+sudo systemctl restart eggpool
+```
+
+### Logs
+
+```bash
+sudo journalctl -u eggpool -f
+```
+
+### Alternative: cron (no systemd)
+
+For systems without systemd, `deploy cron` sets up a user cron
+entry that checks if the server is running and restarts it:
+
+```bash
+# Check every 5 minutes, restart if stopped
+ eggpool croncheck || eggpool serve &
+```
+
+This is a personal-use fallback — prefer systemd when available.
+
+---
+
+## Production Deployment
+
+For public-facing or multi-user deployments. Uses a dedicated
+`eggpool` system user with proper file permissions and a hardened
+systemd unit.
+
+**Not recommended for personal LAN use** — the personal-use path
+above is simpler and sufficient for single-user setups.
+
+### 1. Create system user
+
+```bash
+sudo useradd -r -s /usr/sbin/nologin -d /var/lib/eggpool eggpool
+sudo mkdir -p /var/lib/eggpool /var/log/eggpool /etc/eggpool
+sudo chown eggpool:eggpool /var/lib/eggpool /var/log/eggpool
+sudo chown root:eggpool /etc/eggpool
+sudo chmod 750 /var/lib/eggpool /var/log/eggpool
+sudo chmod 755 /etc/eggpool
+```
+
+### 2. Install application
+
+```bash
+cd /opt
+sudo git clone https://github.com/eggstack/eggpool.git
+sudo chown -R root:eggpool /opt/eggpool
+cd /opt/eggpool
+sudo uv sync --no-dev
+sudo chown -R root:eggpool /opt/eggpool
+sudo chmod -R o+rX /opt/eggpool
+```
+
+### 3. Configure
+
+```bash
+sudo cp config.example.toml /etc/eggpool/config.toml
+sudo cp deploy/env.example /etc/eggpool/env
+sudo chown root:eggpool /etc/eggpool/config.toml /etc/eggpool/env
+sudo chmod 640 /etc/eggpool/config.toml /etc/eggpool/env
+
+sudo nano /etc/eggpool/config.toml
+sudo nano /etc/eggpool/env
+```
+
+Minimal config:
+
+```toml
+[server]
+host = "0.0.0.0"
+port = 11300
+
+[database]
+path = "/var/lib/eggpool/usage.sqlite3"
+```
+
+### 4. Validate and start
+
+```bash
+sudo -u eggpool bash -c 'set -a; source /etc/eggpool/env; set +a; /opt/eggpool/.venv/bin/eggpool check-config --config /etc/eggpool/config.toml'
+sudo -u eggpool /opt/eggpool/.venv/bin/eggpool migrate --config /etc/eggpool/config.toml
+
+# Install the hardened systemd unit
+sudo cp deploy/eggpool.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable eggpool
+sudo systemctl start eggpool
+sudo systemctl status eggpool
+```
+
+### 5. Logrotate
+
+```bash
+sudo cp deploy/eggpool-logrotate.conf /etc/logrotate.d/eggpool
+```
+
+### 6. Automated backup
+
+```bash
+sudo cp deploy/eggpool.service /etc/systemd/system/
+# Or use the deploy command:
+sudo eggpool deploy cron
+```
+
+### Filesystem layout
+
+```
+/etc/eggpool/
+├── config.toml          # Configuration
+└── env                  # API keys
+
+/var/lib/eggpool/
+├── usage.sqlite3        # Database
+├── usage.sqlite3-wal    # WAL journal
+└── usage.sqlite3-shm    # Shared memory
+
+/opt/eggpool/
+├── .venv/               # Python virtual environment
+└── src/                 # Application source
+```
+
+### Systemd unit features
+
+- `ProtectSystem=strict` — read-only system directories
+- `ReadWritePaths=/var/lib/eggpool` — data directory writable
+- `NoNewPrivileges`, `PrivateTmp`, `RestrictNamespaces` — hardened
+- No `ExecReload` — config changes require `systemctl restart`
+
+---
+
+## Troubleshooting
+
+### Service fails to start
+
+```bash
+sudo journalctl -u eggpool --since "5 minutes ago"
+# or for personal use:
+sudo journalctl -u eggpool -n 50 --no-pager
+```
+
+### Database locked errors
+
+1. Ensure only one instance: `pgrep -f eggpool`
+2. Confirm WAL mode in config
+3. Increase `busy_timeout_ms` (try `10000` on Pi)
+
+### Cannot connect from LAN
+
+1. Verify `server.host = "0.0.0.0"` in config
+2. Check firewall: `ss -tlnp | grep 11300`
+3. See `docs/firewall.md`
+
+### Deploy commands reference
+
+| Command | Description |
+|---------|-------------|
+| `eggpool deploy systemd` | Print systemd unit + instructions |
+| `eggpool deploy systemd --install` | Write unit, enable, start |
+| `eggpool deploy logrotate` | Print logrotate config |
+| `eggpool deploy logrotate --install` | Write logrotate config |
+| `eggpool deploy cron` | Print backup cron entry |
+| `eggpool deploy cron --install` | Write backup script + cron entry |
+| `eggpool deploy all` | Print all snippets |
+| `eggpool deploy all --install` | Install everything |
+| `eggpool croncheck` | Check if server is running (exit 0/1) |