pi-free 1.0.0

package/.github/workflows/update-benchmarks.yml

@@ -0,0 +1,67 @@
+name: Update Benchmark Data
+
+on:
+  schedule:
+    # Run monthly (1st of every month at 00:00 UTC)
+    - cron: '0 0 1 * *'
+  workflow_dispatch:
+    # Allow manual trigger
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-benchmarks:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          
+      - name: Install dependencies
+        run: npm ci
+        
+      - name: Update benchmark data
+        env:
+          ARTIFICIAL_ANALYSIS_API_KEY: ${{ secrets.ARTIFICIAL_ANALYSIS_API_KEY }}
+        run: npx tsx scripts/update-benchmarks.ts
+        
+      - name: Check for changes
+        id: check-changes
+        run: |
+          if git diff --quiet; then
+            echo "changed=false" >> $GITHUB_OUTPUT
+          else
+            echo "changed=true" >> $GITHUB_OUTPUT
+          fi
+          
+      - name: Create Pull Request
+        if: steps.check-changes.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.PAT_TOKEN }}
+          commit-message: 'chore: update benchmark data from Artificial Analysis'
+          title: 'chore: update benchmark data from Artificial Analysis'
+          body: |
+            ## Automated Benchmark Update
+            
+            This PR updates the hardcoded benchmark data with fresh scores from [Artificial Analysis](https://artificialanalysis.ai).
+            
+            ### Changes
+            - Updated `provider-failover/hardcoded-benchmarks.ts`
+            - New data as of ${{ github.event.repository.updated_at }}
+            
+            ### Verification
+            - [ ] Review score changes for major models
+            - [ ] Run tests: `npm run test:run`
+            - [ ] Check no unexpected tier downgrades
+            
+            Auto-generated by GitHub Actions.
+          branch: update-benchmarks-${{ github.run_number }}
+          delete-branch: true

package/.pi/skills/pi-extension-dev/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: pi-extension-dev
+description: Guide for developing Pi coding agent extensions. Use when creating or debugging extensions.
+---
+
+# Pi Extension Development
+
+## Documentation Locations
+
+| Resource | Path |
+|----------|------|
+| Extension API | `~/.pi/agent/docs/extensions.md` |
+| Examples | `~/.pi/agent/examples/extensions/*.ts` |
+| Type Definitions | `~/.pi/agent/node_modules/@mariozechner/pi-coding-agent/dist/core/extensions/types.d.ts` |
+| Logs | `~/.pi/agent/logs/` |
+| Global Extensions | `~/.pi/agent/extensions/*.ts` |
+| Project Extensions | `.pi/extensions/*.ts` |
+
+## Extension Structure
+
+```typescript
+// Single file: ~/.pi/agent/extensions/my-ext.ts
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    ctx.ui.notify("Loaded!", "info");
+  });
+}
+```
+
+## Key Events
+
+| Event | When | Use For |
+|-------|------|---------|
+| `session_start` | Session loads | Register providers, init state |
+| `turn_end` | Turn completes | **Error detection** (check `event.message.errorMessage`) |
+| `model_select` | Model changes | Clear provider status |
+| `before_agent_start` | Before LLM call | Inject messages |
+| `tool_call` | Tool invoked | Block/modify tools |
+
+## Context (ctx) Methods
+
+```typescript
+// UI
+ctx.ui.notify("msg", "info"|"warning"|"error"|"success")
+ctx.ui.setStatus("id", "text" | undefined)
+ctx.ui.confirm(title, message) → Promise<boolean>
+ctx.ui.input(title, placeholder?) → Promise<string>
+
+// Registry
+ctx.modelRegistry.registerProvider(id, config)
+ctx.modelRegistry.getAvailable()
+
+// Storage
+ctx.sessionStorage.setItem(key, value)
+ctx.sessionStorage.getItem(key)
+```
+
+## Register Provider
+
+```typescript
+pi.registerProvider("id", {
+  baseUrl: "https://api.example.com/v1",
+  apiKey: "ENV_VAR_NAME",
+  api: "openai-completions", // or "anthropic-messages"
+  headers: {},
+  models: [{
+    id: "model-id",
+    name: "Display Name",
+    reasoning: false,
+    input: ["text"], // or ["text", "image"]
+    cost: { input: 0.5, output: 1.5 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  }]
+});
+```
+
+## Error Detection (Important!)
+
+Pi has **no error event**. Detect errors in `turn_end`:
+
+```typescript
+pi.on("turn_end", async (event, ctx) => {
+  const msg = event.message as { role?: string; errorMessage?: string };
+  
+  if (msg?.role === "assistant" && msg.errorMessage) {
+    const error = msg.errorMessage;
+    
+    // Classify
+    if (error.includes("429") || /rate.?limit/i.test(error)) {
+      ctx.ui.notify("Rate limited! Try /model to switch.", "warning");
+    }
+  }
+});
+```
+
+## Error Patterns
+
+| Type | Patterns |
+|------|----------|
+| Rate Limit | `429`, `rate limit`, `quota exceeded`, `throttled` |
+| Capacity | `no capacity`, `overloaded`, `503`, `temporarily unavailable` |
+| Auth | `401`, `403`, `unauthorized`, `invalid key` |
+
+## Register Commands
+
+```typescript
+pi.registerCommand("my-cmd", {
+  description: "What it does",
+  handler: async (args, ctx) => {
+    ctx.ui.notify(`Args: ${args}`, "info");
+  }
+});
+```
+
+## Register Tools
+
+```typescript
+import { Type } from "@sinclair/typebox";
+
+pi.registerTool({
+  name: "my_tool",
+  label: "My Tool",
+  description: "What it does",
+  parameters: Type.Object({
+    param: Type.String({ description: "Param desc" })
+  }),
+  async execute(toolCallId, params, signal, onUpdate, ctx) {
+    return {
+      content: [{ type: "text", text: "Result" }],
+      details: {}
+    };
+  }
+});
+```
+
+## Best Practices
+
+- Import as type: `import type { ExtensionAPI }`
+- Export default function
+- Use `.ts` extensions for imports
+- Errors in `turn_end` (no error event exists)
+- Clear status in `model_select` when switching away
+- API keys in env vars, never hardcoded
+- Test with `pi -e ./ext.ts`, install to `~/.pi/agent/extensions/`
+- Hot reload with `/reload` after changes
+
+## Debugging
+
+```typescript
+console.log("[ext] Debug:", data); // Check ~/.pi/agent/logs/
+ctx.ui.notify("Extension loaded!", "info");
+```

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project 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).
+
+## [Unreleased]
+
+### Added
+- Structured logging with namespaced logger (lib/logger.ts)
+- LICENSE file (MIT)
+- CHANGELOG.md
+
+### Changed
+- **Major refactoring**: Split free-tier-limits.ts into usage/* modules
+  - usage/tracking.ts - runtime session tracking
+  - usage/cumulative.ts - persistent storage
+  - usage/formatters.ts - display formatting
+  - 77% line reduction (741 → 166 lines)
+- **Major refactoring**: Split usage-widget.ts into widget/* modules
+  - widget/data.ts - data collection
+  - widget/format.ts - formatting utilities
+  - widget/render.ts - HTML generation
+  - 74% line reduction (~350 → 90 lines)
+- **Refactoring**: Extracted functions from cline-auth.ts
+  - fetchAuthorizeUrl() - auth URL fetching
+  - waitForAuthCode() - callback handling
+  - exchangeCodeForTokens() - token exchange
+  - parseManualInput() - manual input parsing
+- **Refactoring**: Simplified model-hop.ts complexity
+  - Extracted handleDowngradeDecision()
+  - Extracted tryAlternativeModel()
+- **Deduplication**: Created shared modules
+  - lib/json-persistence.ts - file I/O with caching
+  - lib/logger.ts - structured logging
+  - providers/model-fetcher.ts - OpenRouter-compatible fetching
+- Replaced ~30 console.log statements with structured logging
+- Fixed all 9 pre-existing test failures
+  - fetchWithRetry now throws after last retry
+  - Fixed auth pattern matching (added key.*not.*valid)
+  - Updated capability ranking tests
+  - Added resetUsageStats() for test isolation
+
+### Fixed
+- fetchWithRetry() now properly throws after exhausting retries
+- Auth error pattern matching now handles more message variants
+- Test isolation for free-tier-limits tests
+
+## [1.0.0] - 2024-03-28
+
+### Added
+- Initial release with 6 providers: Kilo, Zen, OpenRouter, NVIDIA, Cline, Fireworks
+- Free tier usage tracking across all sessions
+- Provider failover with model hopping
+- Autocompact integration for rate limit recovery
+- Usage widget with glimpseui
+- Command toggles for free/all model filtering
+- Hardcoded benchmark data from Artificial Analysis

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 pi-free-providers contributors
+
+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.

package/README.md

@@ -0,0 +1,289 @@
+# pi-free-providers
+
+Free AI model providers for [Pi](https://pi.dev). Access **free models** from multiple providers in one install.
+
+---
+
+## What does pi-free do
+
+**pi-free is a Pi extension that unlocks free AI models from 8 different providers.**
+
+When you install pi-free, it:
+
+1. **Registers 7 AI providers** with Pi's model picker — OpenCode Zen, Kilo, OpenRouter, NVIDIA NIM, Cline, Mistral, and Ollama Cloud
+
+2. **Filters to show only free models by default** — You see only the models that cost $0 to use, no API key required for some providers
+
+3. **Provides a toggle command** — Run `/{provider}-toggle` (e.g., `/zen-toggle`, `/kilo-toggle`) to switch between free-only mode and showing all models including paid ones
+
+4. **Handles authentication for you** — OAuth flows (Kilo, Cline) open your browser automatically; API keys are read from `~/.pi/free.json` or environment variables
+
+5. **Adds Coding Index scores** — Model names include a coding benchmark score (CI: 45.2) to help you pick capable coding models at a glance
+
+6. **Persists your preferences** — Your toggle choices (free vs all models) are saved to `~/.pi/free.json` and remembered across Pi restarts
+
+---
+
+## How to use
+
+### 1. Install the extension
+
+```bash
+pi install git:github.com/apmantza/pi-free
+```
+
+### 2. Open the model picker
+
+Start Pi and press `Ctrl+L` to open the model picker.
+
+Free models are shown by default — look for the provider prefixes:
+- `zen/` — OpenCode Zen models (no setup required)
+- `kilo/` — Kilo models (free models available immediately, more after `/login kilo`)
+- `openrouter/` — OpenRouter models (free account required)
+- `nvidia/` — NVIDIA NIM models (free API key required)
+- `cline/` — Cline models (run `/login cline` to use)
+- `mistral/` — Mistral models (API key required)
+- `ollama/` — Ollama Cloud models (API key required)
+
+### 3. Toggle between free and paid models
+
+Want to see paid models too? Run the toggle command for your provider:
+
+```
+/zen-toggle      # Toggle Zen free/paid models
+/kilo-toggle     # Toggle Kilo free/paid models
+/openrouter-toggle  # Toggle OpenRouter free/paid models
+/nvidia-toggle   # Toggle NVIDIA zero-cost/credit-costing models
+/cline-toggle    # Toggle Cline free/paid models
+/mistral-toggle  # Toggle Mistral free/paid models
+/ollama-toggle   # Toggle Ollama models (requires SHOW_PAID=true)
+```
+
+You'll see a notification like: `zen: showing free models` or `zen: showing all models (including paid)`
+
+### 4. Add API keys for more providers (optional)
+
+Some providers require a free account or API key.
+
+**The first time you run Pi after installing this extension, a config file is automatically created:**
+- **Linux/Mac:** `~/.pi/free.json`
+- **Windows:** `%USERPROFILE%\.pi\free.json`
+
+Add your API keys to this file:
+
+```json
+{
+  "openrouter_api_key": "sk-or-v1-...",
+  "nvidia_api_key": "nvapi-...",
+  "ollama_api_key": "...",
+  "fireworks_api_key": "...",
+  "mistral_api_key": "..."
+}
+```
+
+Or set environment variables instead (same names, uppercase: `OPENROUTER_API_KEY`, `NVIDIA_API_KEY`, etc.)
+
+See the [Providers That Need Authentication](#providers-that-need-authentication) section below for detailed setup instructions per provider.
+
+### 5. Quick commands reference
+
+| Command | What it does |
+|---------|-------------|
+| `/{provider}-toggle` | Switch between free-only and all models for that provider |
+| `/login kilo` | Start OAuth flow for Kilo |
+| `/login cline` | Start OAuth flow for Cline |
+| `/logout kilo` | Clear Kilo OAuth credentials |
+| `/logout cline` | Clear Cline OAuth credentials |
+
+---
+
+## Using Free Models (No Setup Required)
+
+### OpenCode Zen — Easiest Start
+
+Works immediately with zero setup:
+
+1. Press `Ctrl+L`
+2. Search for `zen/`
+3. Pick any model (e.g., `zen/mimo-v2-omni-free`)
+4. Start chatting
+
+No account, no API key, no OAuth.
+
+### Ollama Cloud
+
+Get an API key from [ollama.com/settings/keys](https://ollama.com/settings/keys), then:
+
+**Option A: Environment variable**
+```bash
+export OLLAMA_API_KEY="..."
+export OLLAMA_SHOW_PAID=true
+```
+
+**Option B: Config file** (`~/.pi/free.json`)
+```json
+{
+  "ollama_api_key": "YOUR_KEY",
+  "ollama_show_paid": true
+}
+```
+
+**Note:** Ollama requires `OLLAMA_SHOW_PAID=true` because they have usage limits on their cloud API.
+
+Free tier resets every 5 hours + 7 days.
+
+---
+
+## Providers That Need Authentication
+
+Some providers require free accounts or OAuth to access their free tiers:
+
+### Kilo (free models, more after login)
+
+Kilo shows free models immediately. To unlock all models, authenticate with Kilo's free OAuth:
+
+```
+/login kilo
+```
+
+This command will:
+1. Open your browser to Kilo's authorization page
+2. Show a device code in Pi's UI
+3. Wait for you to authorize in the browser
+4. Automatically complete login once approved
+
+- No credit card required
+- Free tier: 200 requests/hour
+- After login, run `/kilo-toggle` to switch between free-only and all models
+
+### OpenRouter (free models available)
+
+Get a free API key at [openrouter.ai/keys](https://openrouter.ai/keys), then either:
+
+**Option A: Environment variable**
+```bash
+export OPENROUTER_API_KEY="sk-or-v1-..."
+```
+
+**Option B: Config file** (`~/.pi/free.json`)
+```json
+{
+  "openrouter_api_key": "sk-or-v1-..."
+}
+```
+
+Then in Pi:
+```
+/openrouter-all   # Show all models (free + paid)
+```
+
+### NVIDIA NIM (Free Credits System)
+
+NVIDIA provides **free monthly credits** (1000 requests/month) at [build.nvidia.com](https://build.nvidia.com).
+
+**Important:** Models have different "costs" per token:
+- **Zero-cost models**: Don't consume your credit balance (shown by default)
+- **Credit-costing models**: Consume credits faster (hidden by default)
+
+Get your API key and optionally enable all models:
+
+**Option A: Show only free models (default)**
+```bash
+export NVIDIA_API_KEY="nvapi-..."
+```
+Uses only zero-cost models → your 1000 credits last the full month
+
+**Option B: Show all models (uses credits faster)**
+```bash
+export NVIDIA_API_KEY="nvapi-..."
+export NVIDIA_SHOW_PAID=true
+```
+
+Or in `~/.pi/free.json`:
+```json
+{
+  "nvidia_api_key": "nvapi-...",
+  "nvidia_show_paid": true
+}
+```
+
+Toggle anytime with `/nvidia-toggle`
+
+### Cline
+
+Cline models appear immediately in the model picker. To use them, authenticate with Cline's free account:
+
+```
+/login cline
+```
+
+This command will:
+1. Open your browser to Cline's sign-in page
+2. Wait for you to complete sign-in
+3. Automatically complete login once approved
+
+- Free account required (no credit card)
+- Uses local ports 48801-48811 for OAuth callback
+
+### Mistral
+
+Add API key to `~/.pi/free.json` or environment variables:
+
+```bash
+export MISTRAL_API_KEY="..."
+```
+
+---
+
+## Slash Commands
+
+Each provider has toggle commands to switch between free and all models:
+
+| Command | Action |
+|---------|--------|
+| `/zen-toggle` | Toggle between free/all Zen models |
+| `/kilo-toggle` | Toggle between free/all Kilo models |
+| `/openrouter-toggle` | Toggle between free/all OpenRouter models |
+| `/nvidia-toggle` | Toggle between free/all NVIDIA models |
+| `/cline-toggle` | Toggle between free/all Cline models |
+| `/mistral-toggle` | Toggle between free/all Mistral models |
+| `/ollama-toggle` | Toggle between free/all Ollama models |
+
+**The toggle command:**
+- Switches between showing only free models vs. all available models
+- **Persists your preference** to `~/.pi/free.json` for next startup
+- Shows a notification: "zen: showing free models" or "zen: showing all models (including paid)"
+
+---
+
+## Configuration
+
+Create `~/.pi/free.json` in your home directory:
+
+```json
+{
+  "openrouter_api_key": "YOUR_OPENROUTER_KEY",
+  "nvidia_api_key": "YOUR_NVIDIA_KEY",
+  "fireworks_api_key": "YOUR_FIREWORKS_KEY",
+  "mistral_api_key": "YOUR_MISTRAL_KEY",
+  "opencode_api_key": "YOUR_ZEN_KEY",
+  "ollama_api_key": "YOUR_OLLAMA_KEY",
+  "ollama_show_paid": true,
+  "hidden_models": ["model-id-to-hide"]
+}
+```
+
+Or use environment variables (same names, uppercase):
+
+```bash
+export OPENROUTER_API_KEY="..."
+export NVIDIA_API_KEY="..."
+```
+
+---
+
+## License
+
+MIT — See [LICENSE](LICENSE)
+
+**Questions?** [Open an issue](https://github.com/apmantza/pi-free/issues)