powergrid-ai 1.0.0__tar.gz

powergrid_ai-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: |
+          ruff check powergrid/ tests/
+          ruff format --check powergrid/ tests/
+
+      - name: Type check with mypy
+        run: mypy powergrid/ --ignore-missing-imports
+        continue-on-error: true
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short -x
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

powergrid_ai-1.0.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+*.whl
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual environments
+venv/
+.venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# PowerGrid runtime
+*.db
+*.db-journal
+powergrid.pid
+
+# Test / coverage
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Distribution
+*.tar.gz
+*.zip
+
+# Environment / secrets
+.env
+.env.*
+!.env.example

powergrid_ai-1.0.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to PowerGrid will be 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).
+
+## [1.0.0] - 2026-09-01
+
+### Added
+- **Routing Engine** — intelligent, round-robin, and priority routing strategies
+- **Provider Adapters** — OpenAI-compatible, Google Gemini, and Mock providers
+- **Health Tracking** — automatic provider health monitoring with cooldown and exponential backoff
+- **Quota Engine** — RPM/TPM/RPD/TPD tracking with predictive rate limit protection
+- **Retry & Failover** — automatic retries across providers with exponential backoff and jitter
+- **Response Cache** — TTL-based exact-match caching to avoid redundant API calls
+- **Request Analyzer** — task type classification (coding, reasoning, creative, etc.)
+- **CLI** — 15+ commands: init, start, stop, status, providers, models, logs, test, config, cache-clear
+- **Interactive Provider Wizard** — add providers with templates for 8+ services (Groq, Cerebras, Gemini, OpenRouter, Together, NVIDIA, Mistral, Azure OpenAI)
+- **Secure Credential Storage** — OS keyring integration (Windows Credential Manager, macOS Keychain, Linux Secret Service) with file fallback
+- **OpenAI-Compatible API** — drop-in replacement for any OpenAI SDK usage
+- **Streaming Support** — SSE streaming for chat completions
+- **Auth Protection** — optional API token for endpoint security
+- **Request Logging** — middleware with correlation IDs and timing headers
+- **Mock Provider** — simulate success, 429s, timeouts, and errors for testing
+- **GitHub Actions CI** — automated testing on Python 3.11/3.12/3.13, Ubuntu and Windows
+- **Graceful Shutdown** — clean provider connection cleanup on SIGTERM/SIGINT
+- **Startup Health Checks** — verify provider connectivity on boot
+- **Request Validation** — message count and size limits to prevent abuse
+- **Localhost-Only CORS** — secure default for local development
+
+### Security
+- API keys never appear in logs, API responses, or config dumps
+- Auth token protection on `/v1/` endpoints
+- Localhost-only binding by default with explicit warning for `0.0.0.0`
+- OS credential store for API keys (not plaintext config files)
+- Request body size limits (1MB)

powergrid_ai-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Moses
+
+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.

powergrid_ai-1.0.0/PKG-INFO

@@ -0,0 +1,416 @@
+Metadata-Version: 2.5
+Name: powergrid-ai
+Version: 1.0.0
+Summary: Local-first AI routing runtime — one AI, many engines
+Project-URL: Homepage, https://github.com/micymike/powergrid
+Project-URL: Repository, https://github.com/micymike/powergrid
+Project-URL: Issues, https://github.com/micymike/powergrid/issues
+Project-URL: Changelog, https://github.com/micymike/powergrid/blob/main/CHANGELOG.md
+Author-email: Michael Moses <micymike@example.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,failover,llm,local-first,multi-provider,openai,routing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: pydantic-settings>=2.5.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: sse-starlette>=2.1.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PowerGrid
+
+**Local-first AI routing runtime — one AI, many engines.**
+
+PowerGrid runs on your machine and makes multiple AI providers appear as a single OpenAI-compatible endpoint. Your applications talk to `localhost:8787`, and PowerGrid intelligently routes requests across your available providers.
+
+[![CI](https://github.com/micymike/powergrid/actions/workflows/ci.yml/badge.svg)](https://github.com/micymike/powergrid/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/powergrid)](https://pypi.org/project/powergrid/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+## Why PowerGrid?
+
+Developers often have access to multiple AI providers (Groq, Gemini, Cerebras, OpenRouter, etc.). PowerGrid lets you:
+
+- **Use all your providers through one endpoint** — no app changes needed
+- **Get automatic failover** — if one provider is down or rate-limited, traffic shifts seamlessly
+- **Predict rate limits** — PowerGrid tracks usage and shifts traffic *before* you hit 429s
+- **Stay local** — your API keys never leave your machine
+- **Stay free** — PowerGrid itself costs $0/month
+
+## Quick Start
+
+```bash
+# Install
+pip install powergrid-ai
+
+# Initialize
+powergrid init
+
+# Add a provider
+powergrid provider
+
+# Start
+powergrid start
+```
+
+Then use it:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://localhost:8787/v1",
+    api_key="powergrid"
+)
+
+response = client.chat.completions.create(
+    model="powergrid-auto",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+```
+
+## Architecture
+
+```
+                    APPLICATION
+                         |
+                         v
+                +----------------+
+                |    POWERGRID   |
+                | Local Runtime  |
+                +-------+--------+
+                        |
+                 Request Analyzer
+                        |
+                 Routing Engine
+                        |
+        +---------------+---------------+
+        |               |               |
+        v               v               v
+     Gemini           Groq          Cerebras
+        |               |               |
+        +---------------+---------------+
+                        |
+                        v
+                 Unified Response
+```
+
+### Core Components
+
+| Component | Purpose |
+|-----------|---------|
+| **Provider Adapters** | Normalize provider APIs into a common format |
+| **Routing Engine** | Score and select the best provider per request |
+| **Health Tracker** | Monitor provider availability and apply cooldowns |
+| **Quota Engine** | Track usage and predict rate limit exhaustion |
+| **Retry Handler** | Manage retries, failover, and backoff |
+| **Cache** | Exact-match response caching with TTL |
+| **Request Analyzer** | Classify task types with heuristics |
+
+## Provider Configuration
+
+### Interactive Setup
+
+```bash
+powergrid provider
+```
+
+### YAML Configuration
+
+Copy `config.example.yaml` to `~/.config/powergrid/config.yaml`:
+
+```yaml
+providers:
+  - name: groq
+    type: openai_compatible
+    base_url: https://api.groq.com/openai/v1
+    api_key_env: GROQ_API_KEY
+    models:
+      - llama-3.3-70b-versatile
+    priority: 90
+    rpm_limit: 30
+
+  - name: gemini
+    type: gemini
+    api_key_env: GEMINI_API_KEY
+    models:
+      - gemini-2.0-flash
+    priority: 85
+```
+
+### Environment Variables
+
+Set your API keys:
+
+```bash
+export GROQ_API_KEY=gsk_...
+export GEMINI_API_KEY=AI...
+export CEREBRAS_API_KEY=...
+```
+
+## Running
+
+### Foreground
+
+```bash
+powergrid start
+```
+
+### Background
+
+```bash
+powergrid start --background
+powergrid status
+powergrid stop
+```
+
+### Custom Port/Host
+
+```bash
+powergrid start --port 9000 --host 127.0.0.1
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/models` | GET | List available models |
+| `/v1/chat/completions` | POST | Chat completions (OpenAI-compatible) |
+| `/health` | GET | Health check |
+| `/status` | GET | PowerGrid status and stats |
+| `/providers` | GET | Provider details |
+| `/routing/logs` | GET | Recent routing decisions |
+| `/routing/stats` | GET | Aggregate statistics |
+
+## Agent Configuration
+
+### OpenCode
+
+In `opencode.json`:
+
+```json
+{
+  "provider": {
+    "name": "powergrid",
+    "model": "powergrid-auto",
+    "api_key": "powergrid",
+    "base_url": "http://localhost:8787/v1"
+  }
+}
+```
+
+### Codex
+
+```bash
+export OPENAI_BASE_URL=http://localhost:8787/v1
+export OPENAI_API_KEY=powergrid
+```
+
+### Cline
+
+In VS Code settings:
+
+```json
+{
+  "cline.apiProvider": "openai-compatible",
+  "cline.openaiCompatibleBaseUrl": "http://localhost:8787/v1",
+  "cline.openaiCompatibleApiKey": "powergrid",
+  "cline.openaiCompatibleModelId": "powergrid-auto"
+}
+```
+
+### Python (OpenAI SDK)
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://localhost:8787/v1",
+    api_key="powergrid"
+)
+
+response = client.chat.completions.create(
+    model="powergrid-auto",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+```
+
+### Node.js
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  baseURL: "http://localhost:8787/v1",
+  apiKey: "powergrid",
+});
+
+const response = await client.chat.completions.create({
+  model: "powergrid-auto",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+```
+
+### curl
+
+```bash
+curl http://localhost:8787/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "powergrid-auto",
+    "messages": [{"role": "user", "content": "Hello!"}]
+  }'
+```
+
+## Routing
+
+PowerGrid supports three routing strategies:
+
+### Intelligent (default)
+
+Scores providers on health, quota, capability, priority, and latency. Best for most use cases.
+
+### Round Robin
+
+Cycles through providers evenly. Good for load distribution.
+
+### Priority
+
+Always selects the highest-priority provider. Good when you have a clear preference order.
+
+## How Failover Works
+
+1. Request arrives and is routed to the best provider
+2. If the provider returns **429** (rate limited), PowerGrid:
+   - Parses the `Retry-After` header
+   - Puts the provider in cooldown
+   - Selects the next-best provider
+3. If the provider returns **5xx** or **times out**:
+   - Applies exponential backoff with jitter
+   - Fails over to another provider
+4. A request retries up to `max_retries` times across different providers
+5. If all providers fail, a clean error is returned
+
+## Predictive Rate Limit Protection
+
+PowerGrid tracks request rates over time and estimates when a provider is approaching its limits:
+
+```
+Groq RPM = 30
+Recent: 18:01 → 21 requests, 18:02 → 26 requests, 18:03 → 29 requests
+→ PowerGrid shifts traffic BEFORE the 429 hits
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `powergrid init` | Initialize configuration |
+| `powergrid start` | Start the runtime |
+| `powergrid stop` | Stop background process |
+| `powergrid status` | Show runtime status |
+| `powergrid providers` | List configured providers |
+| `powergrid provider` | Add provider interactively |
+| `powergrid provider-remove NAME` | Remove a provider |
+| `powergrid models` | List virtual models |
+| `powergrid logs` | Show recent routing decisions |
+| `powergrid test` | Test provider connectivity |
+| `powergrid config` | Show config (redacted) |
+| `powergrid cache-clear` | Clear response cache |
+
+## Security
+
+- **Local-only by default** — binds to `127.0.0.1`
+- **API key protection** — optional `auth_token` for the endpoint
+- **No key leakage** — API keys never appear in logs or API responses
+- **Config redaction** — `powergrid config` masks secrets
+- **Explicit 0.0.0.0 warning** — warns if you bind publicly
+
+## Privacy
+
+- PowerGrid is fully local
+- No telemetry is sent anywhere
+- No API keys leave your machine
+- No prompts or responses are stored externally
+- All state lives in `~/.config/powergrid/`
+
+## Development
+
+```bash
+git clone https://github.com/micymike/powergrid.git
+cd powergrid
+pip install -e ".[dev]"
+pytest
+```
+
+### Mock Provider
+
+For testing without real API keys:
+
+```yaml
+providers:
+  - name: mock
+    type: mock
+    models:
+      - mock-model
+    priority: 50
+```
+
+The mock provider simulates success, 429s, timeouts, and errors.
+
+## Adding Providers
+
+Implement the `ProviderAdapter` interface:
+
+```python
+from powergrid.providers.base import ProviderAdapter, ProviderModel, ProviderStatus
+
+class MyProvider(ProviderAdapter):
+    name = "my_provider"
+    display_name = "My Provider"
+
+    async def chat_completion(self, request, model_id):
+        # Call provider API
+        ...
+
+    async def chat_completion_stream(self, request, model_id):
+        # Stream SSE chunks
+        ...
+
+    async def health_check(self):
+        return ProviderStatus.HEALTHY
+```
+
+Register it:
+
+```python
+from powergrid.providers.registry import registry
+
+registry.register(MyProvider(name="my_provider", api_key="..."))
+```
+
+## License
+
+MIT