@kylebrodeur/pi-model-router 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# 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
+- Ollama auto-sync feature
+- Rate-limit fallback with transparent HTTP error handling (402, 429, 503, 529)
+- Feature toggles in config (`features` object)
+- Scope shim for syncing router profiles to Pi enabled models
+- Progressive enhancement (auto-detect qmd-ledger and agent-bus)
+- Progressive config files (`model-router.ledger.json`, `model-router.agent-bus.json`, `model-router.essential.json`)
+- GitHub issue templates and pull request template
+- Code of Conduct
+
+### Changed
+- Updated minimum Pi SDK version from 0.68.0 to 0.70.2
+- Merged `README_FORK.md` into canonical `README.md`
+- Replaced `@sinclair/typebox` peer dependency with `typebox`
+
+## [0.1.1] - 2025-04-22
+
+### Fixed
+- Config merge bug where `features`, `ollamaSync`, and `rateLimitFallback` were dropped during global/project merge
+
+## [0.1.0] - 2025-04-21
+
+### Added
+- Initial fork from `yeliu84/pi-model-router`
+- Feature toggles system
+- Ollama sync module
+- Rate-limit fallback module
+- Scope shim module
+- Progressive enhancement with plugin detection
+
+[Unreleased]: https://github.com/kylebrodeur/pi-model-router/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/kylebrodeur/pi-model-router/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/kylebrodeur/pi-model-router/releases/tag/v0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,310 @@
+# Contributing to Upstream (pi-model-router)
+
+This fork is designed for eventual upstream contribution. Here's how to structure and deliver your changes.
+
+## Fork Strategy
+
+```
+yeliu84/pi-model-router (upstream)
+    │
+    └── your-github/pi-model-router-fork (this repo)
+            │
+            ├── branch: main (tracks upstream)
+            ├── branch: feature/ollama-sync
+            ├── branch: feature/rate-limit-fallback
+            └── branch: feature/feature-toggles
+```
+
+## Recommended Commit Structure
+
+Separate your work into **independent PRs** for maximum merge probability:
+
+### PR 1: Feature Toggle Framework
+**Commit message:** `feat: add feature toggle system for modular extensions`
+
+**Files touched:**
+- `extensions/types.ts` — add `FeatureToggles`, `OllamaSyncConfig`, `RateLimitFallbackConfig`
+- `extensions/config.ts` — add feature fields to `mergeConfig()` and `normalizeConfig()`
+
+**Rationale:**
+- Minimal surface area
+- No behavior changes to existing code
+- Enables future features
+- Easy to review and merge
+
+### PR 2: Ollama Auto-Sync Feature
+**Commit message:** `feat: add ollama-sync for auto-registering local models`
+
+**Files touched:**
+- `extensions/ollama-sync.ts` — new file
+- `extensions/index.ts` — conditionally initialize from toggles
+
+**Rationale:**
+- Self-contained module
+- Uses existing patterns (pi.exec, config merge)
+- Useful to upstream community (many Pi users use Ollama)
+
+### PR 3: Rate Limit Fallback
+**Commit message:** `feat: add rate-limit fallback with manual restore`
+
+**Files touched:**
+- `extensions/rate-limit.ts` — new file
+- `extensions/index.ts` — conditionally initialize from toggles
+
+**Rationale:**
+- Solves real production pain (API rate limits)
+- Manual fallback is safe (no auto-magic)
+- Composable with any routing profile
+
+## Upstream Compatibility Rules
+
+### ✅ Do
+
+1. **Extend existing types** rather than replacing
+   ```typescript
+   // ✅ Good
+   export interface RouterConfig {
+     // ... existing fields ...
+     features?: FeatureToggles;
+   }
+   
+   // ❌ Bad
+   export interface RouterConfigWithToggles { } // Separate type
+   ```
+
+2. **Use existing patterns** from upstream code
+   - Session persistence via `pi.appendEntry('router-state', ...)`
+   - Config merge: global → project (already in `loadRouterConfig()`)
+   - Commands via `pi.registerCommand()`
+   - State restoration in `session_start`
+
+3. **Make features opt-out** (enabled by default)
+   ```typescript
+   const isEnabled =
+     !currentConfig.features ||
+     currentConfig.features.myFeature !== false;
+   ```
+
+4. **Co-locate feature commands** under `/router-*` namespace
+   - `/router-ollama-sync` not `/ollama-sync`
+   - `/router-fallback` not `/fallback`
+
+5. **Follow style guide**
+   - Single quotes for strings
+   - Trailing commas in objects/arrays
+   - Same naming conventions (kebab-case files, camelCase identifiers)
+
+### ❌ Don't
+
+1. **Don't modify upstream internals** without justification
+   - Don't change `provider.ts` routing logic
+   - Don't change `routing.ts` tier decisions
+   - Don't modify UI rendering unless adding new elements
+
+2. **Don't introduce breaking config changes**
+   - Keep `model-router.json` backward compatible
+   - New fields must be optional
+
+3. **Don't add new dependencies**
+   - Use built-in `node:*` modules
+   - If upstream uses a package, you can use it
+
+4. **Don't auto-switch models without explicit user action**
+   - Manual fallback only (user must type `/router-fallback`)
+   - Optional auto-fallback behind config flag (disabled by default)
+
+5. **Don't modify the `RouterPersistedState` structure**
+   - Use separate session entries for feature state
+   - Or nest inside state object without changing required fields
+
+## PR Preparation Checklist
+
+For each PR:
+
+- [ ] All TypeScript compiles with `npx tsc --noEmit`
+- [ ] No lint errors (`npm run lint` if available)
+- [ ] Upstream tests pass (`npm test` if available)
+- [ ] New code follows file header comment pattern
+- [ ] README.md updated with new feature docs
+- [ ] Example config in `model-router.example.json` updated
+- [ ] CHANGELOG.md entry (if upstream uses one)
+
+## Commit Message Format
+
+Follow upstream conventions:
+
+```
+feat: add ollama-sync for auto-registering local models
+
+- Detect new Ollama models on session start/reload
+- Infer capabilities (vision, reasoning, context window)
+- Update models.json with sensible defaults
+- Toggle via features.ollamaSync in config
+
+Refs: #upstream-issue-if-any
+```
+
+```
+feat: add rate-limit fallback to local Ollama models
+
+- Monitor after_provider_response for HTTP 429/503
+- Manual fallback command: /router-fallback
+- Restore command: /router-restore
+- Configurable via features.rateLimitFallback
+
+Refs: #upstream-issue-if-any
+```
+
+```
+feat: add feature toggle system for modular extension
+
+- features config key for enabling/disabling features
+- ollamaSync and rateLimitFallback as first features
+- Per-turn routing preserved as default behavior
+- Project-level override support
+```
+
+## Testing for Upstream PRs
+
+Before submitting each PR:
+
+1. **Clean checkout of upstream `main` branch**
+   ```bash
+   git remote add upstream https://github.com/yeliu84/pi-model-router.git
+   git fetch upstream
+   git checkout -b my-feature upstream/main
+   ```
+
+2. **Cherry-pick only your feature commits**
+   ```bash
+   git cherry-pick <commit-hash-from-fork>
+   ```
+
+3. **Ensure no other fork changes leak in**
+   ```bash
+   git diff upstream/main --name-only
+   # Should only show files relevant to this PR
+   ```
+
+4. **Test against upstream's vanilla config**
+   ```bash
+   mv ~/.pi/agent/model-router.json ~/.pi/agent/model-router.json.bak
+   
+   # Test with upstream defaults only
+   # Ensure no runtime errors when features are absent
+   
+   mv ~/.pi/agent/model-router.json.bak ~/.pi/agent/model-router.json
+   ```
+
+## Handling Merge Conflicts
+
+If upstream changes while your PR is open:
+
+```bash
+# Fetch latest
+git fetch upstream
+
+# Rebase your branch
+git rebase upstream/main
+
+# Resolve conflicts (usually in config.ts and index.ts)
+# - Always preserve upstream defaults
+# - Add your features as additions
+git add .
+git rebase --continue
+```
+
+Common conflict points:
+- **`config.ts` `normalizeConfig()`** — add your feature fields at the end
+- **`index.ts` imports** — add new feature imports in alphabetical order
+- **`index.ts` `actions` object** — add `syncFeatures` last
+- **`types.ts`** — add new interfaces at the bottom
+
+## Conversation with Upstream
+
+### What to say in your PR description
+
+```markdown
+## Summary
+Adds [feature name] to pi-model-router. This feature [1-sentence problem it solves].
+
+## Configuration
+Users can enable it in their `model-router.json`:
+```json
+{
+  "features": {
+    "[featureName]": true
+  }
+}
+```
+
+## How it works
+[2-3 sentence description]
+
+## Backward Compatibility
+- Disabled by default (opt-out after feature framework PR)
+- No changes to existing routing behavior
+- Existing configs work without modification
+
+## Testing
+- [ ] Tested with Pi 0.67+
+- [ ] Tested with Ollama [if applicable]
+- [ ] Regression tested upstream routing
+```
+
+### What NOT to say
+- Don't pitch it as "our fork adds X"
+- Don't mention other features in the same PR description
+- Don't change scope mid-PR (no "later I'll also add Y")
+
+## If Upstream Declines
+
+Your options:
+
+1. **Maintain fork** — Keep this repo, publish as separate npm package
+2. **Plugin architecture** — Request upstream add an extension hook API
+3. **Separate extension** — Extract to `.pi/extensions/some-name.ts` as standalone
+
+## Quick Reference: Files by PR
+
+### PR 1: Feature Toggles (minimal)
+| File | Change |
+|------|--------|
+| `extensions/types.ts` | +FeatureToggles, +OllamaSyncConfig, +RateLimitFallbackConfig, add fields to RouterConfig |
+| `extensions/config.ts` | preserve feature fields in mergeConfig/normalizeConfig |
+
+### PR 2: Ollama Sync
+| File | Change |
+|------|--------|
+| `extensions/ollama-sync.ts` | New file |
+| `extensions/index.ts` | Import + conditional init |
+
+### PR 3: Rate Limit Fallback
+| File | Change |
+|------|--------|
+| `extensions/rate-limit.ts` | New file |
+| `extensions/index.ts` | Import + conditional init |
+
+---
+
+## Release Plan (for your fork)
+
+Before upstream PRs merge, your fork can be used as:
+
+```bash
+# Install from local folder
+pi install ~/projects/pi-model-router-forked
+
+# Or register manually
+cp -r ~/projects/pi-model-router-forked/extensions ~/pi/extensions/model-router
+```
+
+Once upstream merges, switch back:
+
+```bash
+# Update upstream package
+npm install -g @yeliu84/pi-model-router
+
+# Remove local override
+rm -rf ~/.pi/agent/extensions/pi-model-router
+```

package/LEARNINGS.md

@@ -0,0 +1,181 @@
+# Pi Model Router: Extension Development Learnings
+
+This document captures key insights from developing the `pi-model-router` extension, focusing on architectural patterns, type safety, and best practices for future Pi extensions and AI tool integrations.
+
+## 🎯 Extension Architecture
+
+### 1. Provider-First Design Pattern
+The extension registers itself as a **custom provider** rather than a simple script. The `router` provider exposes "virtual models" (e.g., `router/auto`, `router/cheap`) that remain stable while underlying concrete models change transparently.
+
+*   **When to use**: For any extension that needs to provide its own model selection logic, caching, or request routing.
+*   **Key benefit**: The UI and commands can target `router/auto` consistently, while the backend can swap underlying models based on configuration, load, or context.
+
+### 2. Modularity by Concern
+The extension strictly separates responsibilities into dedicated modules:
+
+*   `extensions/types.ts`: All interfaces (e.g., `RouterConfig`, `RoutingRule`)
+*   `extensions/config.ts`: Loading, normalization, merging, validation
+*   `extensions/routing.ts`: Core decision logic (heuristics, classifier, rules)
+*   `extensions/provider.ts`: Provider registration, stream delegation
+*   `extensions/state.ts`: Session-persisted state management
+*   `extensions/ui.ts`: Status line and widget rendering
+*   `extensions/commands.ts`: CLI command registrations and completions
+*   `extensions/feature-module.ts`: Feature-specific modules (e.g., `ollama-sync.ts`, `rate-limit.ts`)
+
+*   **When to use**: For any extension with complex logic that will benefit from maintainability and testing benefits.
+*   **Key benefit**: Each module can be unit tested in isolation. Changes to one concern (e.g., updating heuristics) don't risk breaking unrelated logic (e.g., command registration).
+
+### 3. State Management via Session Entries
+Router state is persisted using `pi.appendEntry('router-state', state)`, which creates custom session entries. This ensures state is **branch-safe**, meaning if a user creates a new conversation branch, the router can either share or isolate state as needed.
+
+*   **When to use**: For any extension that needs to maintain state across agent restarts or conversation branches.
+*   **Key benefit**: State survives session reloads and is automatically cleaned up when branches are deleted.
+
+## 🛡️ Type Safety & Code Quality
+
+### 1. Zero-`any` Policy
+The extension enforces a strict policy: **Never use the `any` type**. When `any` was encountered, it was replaced with `unknown` or more specific types (e.g., `RoutedTierConfig`, `RouterTier`).
+
+*   **When to use**: For any project where long-term maintainability and robustness are priorities.
+*   **Key benefit**: Prevents runtime errors from invalid data structures. The compiler catches mismatches before deployment.
+
+### 2. Arrow Functions Only
+All functions are defined as arrow functions (`const myFunc = () => ...`) instead of function statements. This ensures consistent lexical scoping.
+
+*   **When to use**: For consistency across modern TypeScript projects.
+*   **Key benefit**: Eliminates unexpected `this` binding issues.
+
+### 3. Prettier-First Development
+The extension was formatted with Prettier (`npx prettier --write extensions/*.ts`). This enforced consistency before any deeper logic work.
+
+*   **When to use**: For any multi-author project or open-source contribution.
+*   **Key benefit**: Saves time on code reviews and prevents "style wars" in PR discussions.
+
+## 🧭 Routing Decision Logic
+
+### 1. Tiered Decision System
+The router uses a tiered (`high`, `medium`, `low`) decision system, ordered by complexity and cost. A priority-based flow:
+1. **Budget Check** (downgrade if exceeded)
+2. **Context Trigger** (upgrade if large)
+3. **Manual Pin** (user override)
+4. **Custom Rules** (keyword matching)
+5. **LLM Classifier** (optional)
+6. **Heuristics** (fallback)
+7. **Phase Bias** (stickiness)
+
+*   **When to use**: For any AI agent that needs to balance cost vs. performance dynamically.
+*   **Key insight**: Tiering allows fine-grained control over cost vs. quality trade-offs.
+
+### 2. Fallback Sequence Design
+The fallback mechanism uses a user-configurable sequence of models: `fallbackSequence: ["anthropic/claude-3-haiku", "ollama/*"]`. This is more robust than hardcoding.
+
+*   **When to use**: For any extension with high-stakes reliability requirements.
+*   **Key benefit**: Prevents catastrophic failures when a primary model is unavailable.
+
+### 3. Graceful Error Handling
+The extension transparently handles errors. For "out of credits" (`402`) or "rate limit" (`429`), it automatically switches to a fallback model and emits a custom session entry (`router-fallback`) for headless tooling to detect.
+
+*   **When to use**: For any extension exposed to external API services.
+*   **Key insight**: Never mask API errors; provide enough detail (status codes) in UI notifications for users to diagnose.
+
+## 🔌 Pi Integration Patterns
+
+### 1. Feature Toggles via Config
+A `features` object in `model-router.json` allows enabling/disabling features at runtime:
+```json
+{
+  "features": {
+    "ollamaSync": true,
+    "respectPiScope": false,
+    "rateLimitFallback": true
+  }
+}
+```
+
+*   **When to use**: For any extension with optional functionality.
+*   **Key benefit**: Allows backward compatibility while testing new features.
+
+### 2. Config Merging Strategy
+The extension supports both global and project-level config:
+- Global: `~/.pi/agent/model-router.json`
+- Project: `.pi/model-router.json`
+
+The project config **overrides** the global config, enabling granular overrides per repository.
+
+*   **When to use**: For any extension where users want both global defaults and per-project overrides.
+*   **Key insight**: A clear merge hierarchy avoids confusion about where settings live.
+
+### 3. Command Registration
+Commands are registered under `/router` with subcommands (`/router status`, `/router profile`, etc.). This namespace keeps the command list clean and avoids conflicts.
+
+*   **When to use**: For any extension with multiple commands.
+*   **Key benefit**: Users can discover commands via autocompletion.
+
+## 📊 Pi Extension Best Practices (Learnings Summary)
+
+### For Future Pi Extensions
+
+1.  **Provider Registration**
+    -   Always register a custom provider if your extension needs to provide its own models or routing logic.
+    -   Keep the provider name stable while underlying models change.
+
+2.  **State Management**
+    -   Use `pi.appendEntry('router-state', state)` for session-persisted state.
+    -   Use a `type` field (e.g., `customType: 'router-state'`) to serialize/deserialize custom state.
+
+3.  **Type Safety**
+    -   Never use `any`. Replace with `unknown` or specific interfaces.
+    -   Enforce TypeScript strict mode.
+    -   Format code with Prettier.
+
+4.  **Configuration**
+    -   Support global (`~/.pi/agent/`) and project (`.pi/`) config.
+    -   Use feature flags (`features: {...}`) to enable/disable optional behavior.
+
+5.  **Command Design**
+    -   Prefix all commands with a single top-level namespace (e.g., `/router *`).
+    -   Use autocompletion (`getArgumentCompletions`) to guide users.
+
+6.  **Error Handling**
+    -   Never mask API errors. Provide details (status codes) in UI notifications.
+    -   For critical failures, emit custom session entries so headless tooling can react.
+
+### For AI Tools and LLM Systems
+
+1.  **Fallback Strategy**
+    -   Always implement a fallback sequence. Never leave the user hanging on a single point of failure.
+
+2.  **Cost vs. Quality Trade-off**
+    -   Tiering (`high`, `medium`, `low`) is a powerful abstraction for managing cost vs. quality.
+    -   Let users define their own tiers based on their wallet and performance needs.
+
+3.  **Context Awareness**
+    -   Be aware of context size limits. Many models have smaller context windows than their advertised maximum.
+    -   Implement context truncation and auto-oversight to prevent failures.
+
+4.  **User Transparency**
+    -   Inform users when switching models or tiers.
+    -   Provide history or logs so users can audit decisions.
+
+5.  **Testing and Documentation**
+    -   Create a `TESTING.md` for step-by-step user validation.
+    -   Create a `QUICKSTART.md` for users to get running in 5 minutes.
+    -   Document all feature flags and their trade-offs.
+
+## 🚀 Next Steps for pi-model-router
+
+1.  **NPM Publishing**
+    -   Bump version in `package.json` (e.g., `v0.1.2`).
+    -   Run `npm publish --access public`.
+    -   Tag release on GitHub (`git tag v0.1.2`).
+
+2.  **Documentation Enhancements**
+    -   Consider adding a "Thinking Guide" for users to choose thinking levels (`off`, `minimal`, `medium`, `high`, `xhigh`) based on task type.
+    -   Add a "Tier Selection" guide, explaining when to use `high` vs. `medium` vs. `low`.
+
+3.  **Future Feature Ideas**
+    -   Per-profile Ollama models (different models per router profile).
+    -   Rate limit dashboard (`/router rate-limit show` with history graph).
+    -   Config UI wizard (`/router config setup` interactive).
+
+This document serves as a knowledge base for the project, capturing lessons learned and recommendations for future development. It can be used to onboard new contributors or to inform the architecture of similar extensions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ye Liu
+
+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/QUICKSTART.md

@@ -0,0 +1,111 @@
+# Quick Start — Use the Fork TODAY
+
+## 1. Install Extension
+
+```bash
+pi install npm:@kylebrodeur/pi-model-router
+```
+
+## 2. Initialize Config
+
+```
+/router init
+```
+
+This scaffolds a default configuration at `~/.pi/agent/model-router.json`.
+
+## 3. Use in Pi
+
+In Pi, run:
+
+```
+/reload
+```
+
+You should see in console:
+
+```
+[router] Feature sync complete - ollama: true rate-limit: true
+[router] ollama-sync: enabled
+[router] rate-limit-fallback: enabled
+```
+
+## 4. Verify Features
+
+### Auto-Sync Test
+
+```bash
+# In another terminal
+ollama pull llama3.2:3b
+```
+
+```
+# In Pi
+/router ollama-sync
+```
+
+Expected: `Added: llama3.2:3b`
+
+### Fallback Test
+
+```
+# In Pi — switch to a cloud model first
+/model anthropic/claude-sonnet-4
+
+# Then trigger fallback
+/router fallback
+```
+
+Expected: switches to best available model matching your `fallbackSequence` (e.g., an Ollama model)
+
+```
+# Restore
+/router restore
+```
+
+## 5. New Commands
+
+| Command               | What it does                               |
+| --------------------- | ------------------------------------------ |
+| `/router ollama-sync` | Manually sync Ollama models                |
+| `/router fallback`    | Switch to fallback model sequence (manual) |
+| `/router restore`     | Restore original cloud model               |
+| `/router init`        | Scaffold default config file               |
+| `/router scope apply` | Sync router profiles to Pi enabled models  |
+| `/router scope reset` | Clear router profiles from Pi enabled list |
+| `/router scope show`  | Show current Pi scoped models settings     |
+
+All existing `/router *` commands still work unchanged.
+
+## 6. Daily Workflow
+
+```bash
+# Pull new Ollama model
+ollama pull qwen3.5:7b
+```
+
+```
+# In Pi — auto-sync triggers on session start
+/new
+# → [Router] Added 1 model(s): qwen3.5:7b
+# → Run /reload to see: qwen3.5:7b
+
+/reload
+# → Model now available in /model
+```
+
+## Troubleshooting
+
+**"Ollama not available"**
+→ Check `ollama list` works in terminal
+
+**Models not in registry**
+→ `/reload` — extension reload refreshes model registry
+
+**TypeScript errors**
+→ Requires Pi 0.67+ for rate-limit fallback (uses `after_provider_response` event)
+→ Ollama sync works with current Pi version
+
+**Config not applying**
+→ Verify `~/.pi/agent/model-router.json` exists
+→ Check with `cat ~/.pi/agent/model-router.json`