powergrid-ai 1.2.0 → 1.3.1

package/README.md

@@ -0,0 +1,267 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/Local-First-blueviolet?style=for-the-badge" alt="Local-First">
+  <img src="https://img.shields.io/badge/OpenAI-Compatible-black?style=for-the-badge" alt="OpenAI-Compatible">
+  <img src="https://img.shields.io/badge/Routing-Intelligent-brightgreen?style=for-the-badge" alt="Routing">
+</p>
+
+<h1 align="center">PowerGrid</h1>
+
+<p align="center">
+  <strong>One AI. Many engines. Zero vendor lock-in.</strong><br>
+  Local-first AI routing runtime that turns multiple AI providers into a single OpenAI-compatible endpoint.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/powergrid-ai"><img src="https://img.shields.io/npm/v/powergrid-ai?style=flat-square" alt="npm"></a>
+  <a href="https://pypi.org/project/powergrid-ai"><img src="https://img.shields.io/pypi/v/powergrid?style=flat-square" alt="PyPI"></a>
+</p>
+
+---
+
+## What is PowerGrid?
+
+PowerGrid runs on your machine and makes multiple AI providers appear as **one endpoint**. Your apps talk to `localhost:8787`, and PowerGrid handles routing, failover, caching, and rate limit prediction — automatically.
+
+```
+Your App ──→ localhost:8787/v1 ──→ PowerGrid ──→ Gemini
+                                          ├─→ Groq
+                                          ├─→ Cerebras
+                                          ├─→ OpenRouter
+                                          └─→ Ollama (local)
+```
+
+**No vendor lock-in. No cloud dependency. Your keys never leave your machine.**
+
+---
+
+## Install
+
+```bash
+npm install -g powergrid-ai
+```
+
+The npm package detects Python 3.11+ and auto-installs the Python backend if needed.
+
+### Requirements
+
+- **Python 3.11+** must be on your PATH
+- The first run will auto-install `powergrid-ai` via pip
+
+---
+
+## Quick Start
+
+```bash
+# Setup — walks you through adding providers
+powergrid setup
+
+# Start the runtime
+powergrid start
+
+# Use it from any OpenAI-compatible client
+curl http://localhost:8787/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "powergrid-auto",
+    "messages": [{"role": "user", "content": "Hello!"}]
+  }'
+```
+
+---
+
+## Supported Providers
+
+### Core (free, no credit card required)
+
+| Provider | Free Tier | Speed | Best For |
+|----------|-----------|-------|----------|
+| Google Gemini | Generous | Fast | General, reasoning, large context |
+| Groq | 30 RPM | Blazing | Fast response, coding, tool calling |
+| Cerebras | Generous | Very Fast | Large context, reasoning |
+| OpenRouter | Rotating free models | Varies | Model variety, fallback |
+| NVIDIA NIM | Generous | Fast | Large model catalog |
+| Ollama | Unlimited (local) | Local | Privacy, offline, zero cost |
+
+### Extended
+
+| Provider | Notes |
+|----------|-------|
+| Mistral AI | Strong European models, Codestral |
+| Hugging Face | Open-source ecosystem |
+| SambaNova | High-performance inference |
+| Together AI | Open-source model hosting |
+| Cloudflare Workers AI | Edge inference |
+| Cohere | RAG + embeddings specialist |
+| GitHub Models | Great selection via GitHub |
+
+### Community / Experimental
+
+| Provider | Notes |
+|----------|-------|
+| SiliconFlow | Chinese/open-source models |
+| Chutes AI | Decentralized inference |
+| **Any OpenAI-compatible API** | Just provide a base URL |
+
+---
+
+## How It Works
+
+### Intelligent Routing (default)
+
+Every request is analyzed and routed to the best provider based on:
+
+```
+Request → Task Classification → Provider Scoring → Best Match
+                │                      │
+                ├─ coding               ├─ health (uptime %)
+                ├─ reasoning            ├─ quota (RPM remaining)
+                ├─ creative             ├─ capability match
+                ├─ fast_response        ├─ priority weight
+                └─ long_context         └─ latency score
+```
+
+### Automatic Failover
+
+```
+Request → Provider A
+            │
+            ├─ 200 OK → return response
+            ├─ 429 Rate Limited → cooldown → retry Provider B
+            ├─ 5xx Error → backoff → retry Provider C
+            └─ Timeout → retry Provider B
+```
+
+### Predictive Rate Limit Protection
+
+PowerGrid tracks usage patterns and shifts traffic **before** you hit rate limits.
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `powergrid setup` | Interactive setup wizard |
+| `powergrid init` | Initialize configuration |
+| `powergrid start` | Start the runtime |
+| `powergrid start --background` | Start as background process |
+| `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 available models |
+| `powergrid logs` | Show recent routing decisions |
+| `powergrid test` | Test provider connectivity |
+| `powergrid config` | Show config (redacted) |
+| `powergrid cache-clear` | Clear response cache |
+| `powergrid --version` | Show version |
+
+---
+
+## Agent Integrations
+
+PowerGrid works with any tool that speaks the OpenAI API format.
+
+### OpenCode
+
+```json
+{
+  "provider": {
+    "name": "powergrid",
+    "model": "powergrid-auto",
+    "api_key": "powergrid",
+    "base_url": "http://localhost:8787/v1"
+  }
+}
+```
+
+### Claude Code / Codex / Aider
+
+```bash
+export OPENAI_BASE_URL=http://localhost:8787/v1
+export OPENAI_API_KEY=powergrid
+```
+
+### Cline (VS Code)
+
+```json
+{
+  "cline.apiProvider": "openai-compatible",
+  "cline.openaiCompatibleBaseUrl": "http://localhost:8787/v1",
+  "cline.openaiCompatibleApiKey": "powergrid",
+  "cline.openaiCompatibleModelId": "powergrid-auto"
+}
+```
+
+### Python
+
+```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!" }],
+});
+```
+
+---
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/models` | GET | List available models |
+| `/v1/chat/completions` | POST | Chat completions (OpenAI-compatible) |
+| `/health` | GET | Health check with provider status |
+| `/status` | GET | PowerGrid status and stats |
+| `/providers` | GET | Provider details (keys redacted) |
+| `/routing/logs` | GET | Recent routing decisions |
+| `/routing/stats` | GET | Aggregate routing statistics |
+
+---
+
+## Security & Privacy
+
+- **Local-only by default** — binds to `127.0.0.1`
+- **Keys stored securely** — OS credential store, not config files
+- **No telemetry** — zero data sent anywhere
+- **No key leakage** — API keys never appear in logs or responses
+- **Config redaction** — `powergrid config` masks secrets
+
+---
+
+## Links
+
+- [PyPI Package](https://pypi.org/project/powergrid-ai)
+- [GitHub](https://github.com/micymike/powergrid)
+- [Issues](https://github.com/micymike/powergrid/issues)
+
+---
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  Built with ❤️ by <a href="https://github.com/micymike">Michael Moses</a>
+</p>

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "powergrid-ai",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Local-first AI routing runtime — one AI, many engines. Wraps the Python powergrid-ai package.",
+  "readmeFilename": "README.md",
   "keywords": [
     "ai",
     "routing",