|
|
@@ -0,0 +1,104 @@
|
|
|
+# DuckCoding Provider for Pi
|
|
|
+
|
|
|
+A [pi](https://github.com/earendil-works/pi) extension that registers [DuckCoding AI](https://duckcoding.ai) as a custom AI provider using its OpenAI-compatible API (`openai-completions`).
|
|
|
+
|
|
|
+## Features
|
|
|
+
|
|
|
+- **Dynamic Catalog & Pricing**: Automatically fetches available models and pricing formulas directly from DuckCoding's pricing API (`https://www.duckcoding.ai/api/pricing`).
|
|
|
+- **Billing-Group Model Filtering**: Inspects the authenticated `/v1/models` endpoint using your API key to narrow down models specifically enabled for your billing tier/group, avoiding `model_not_found` errors.
|
|
|
+- **Pi Catalog Integration**: Fetches detailed metadata (context window sizes, max tokens, reasoning support, thinking level maps, multimodal input support) from the official Pi model catalog.
|
|
|
+- **Offline & Graceful Fallbacks**:
|
|
|
+ - Heuristic family defaults for popular model architectures (Claude, GPT, Gemini, Grok, DeepSeek, GLM, etc.).
|
|
|
+ - Session-start re-enrichment against Pi's local registry.
|
|
|
+ - Multi-tiered local file caching under `~/.cache/pi-agent-duckcoding/`.
|
|
|
+
|
|
|
+## Prerequisites
|
|
|
+
|
|
|
+- [pi](https://github.com/earendil-works/pi) installed.
|
|
|
+- A DuckCoding AI account and API key.
|
|
|
+
|
|
|
+## Installation
|
|
|
+
|
|
|
+You can install this plugin directly via `pi` package management or place it in your Pi configuration.
|
|
|
+
|
|
|
+### Option 1: Install using `pi install`
|
|
|
+
|
|
|
+```bash
|
|
|
+pi install npm:pi-extension-duckcoding
|
|
|
+# or from git repository:
|
|
|
+pi install git+https://github.com/<owner>/pi-agent-duckcoding-provider.git
|
|
|
+```
|
|
|
+
|
|
|
+### Option 2: Local extension
|
|
|
+
|
|
|
+Add the directory to your `~/.pi/agent/settings.json`:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "extensions": [
|
|
|
+ "/path/to/pi-agent-duckcoding-provider"
|
|
|
+ ]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+Or copy/link `index.ts` to `~/.pi/agent/extensions/duckcoding.ts`.
|
|
|
+
|
|
|
+## Configuration
|
|
|
+
|
|
|
+Set your DuckCoding API key in your environment:
|
|
|
+
|
|
|
+```bash
|
|
|
+export DUCKCODING_API_KEY="your-duckcoding-api-key"
|
|
|
+```
|
|
|
+
|
|
|
+You can also configure it in your shell startup file (`~/.bashrc`, `~/.zshrc`, etc.) or Pi's environment configuration.
|
|
|
+
|
|
|
+### Environment Variables
|
|
|
+
|
|
|
+| Variable | Description | Default |
|
|
|
+|---|---|---|
|
|
|
+| `DUCKCODING_API_KEY` | Your DuckCoding API key (required to query models and authenticate requests). | _None_ |
|
|
|
+| `DUCKCODING_MODEL_CACHE_TTL_MS` | Cache TTL in milliseconds for the public model & pricing list. | `604800000` (7 days) |
|
|
|
+| `PI_OFFLINE` | Disables network refresh when set. | _None_ |
|
|
|
+
|
|
|
+## Usage
|
|
|
+
|
|
|
+Once configured, launch Pi:
|
|
|
+
|
|
|
+```bash
|
|
|
+pi
|
|
|
+```
|
|
|
+
|
|
|
+Switch to any DuckCoding model using the `/model` command:
|
|
|
+
|
|
|
+```text
|
|
|
+/model duckcoding/<model-id>
|
|
|
+```
|
|
|
+
|
|
|
+Example:
|
|
|
+```text
|
|
|
+/model duckcoding/claude-3-7-sonnet-20250219
|
|
|
+```
|
|
|
+
|
|
|
+Or specify the model directly on launch:
|
|
|
+
|
|
|
+```bash
|
|
|
+pi --model duckcoding/claude-3-7-sonnet-20250219
|
|
|
+```
|
|
|
+
|
|
|
+## How It Works
|
|
|
+
|
|
|
+1. **Model Discovery**: The extension queries `https://www.duckcoding.ai/api/pricing` for chat-compatible models and their token costs.
|
|
|
+2. **Metadata Enrichment**: Fetches capabilities (tokens, context length, multimodal inputs, reasoning configs) from Pi's catalog (`https://pi.dev/api/models/providers/...`).
|
|
|
+3. **Availability Filtering**: Validates which models are enabled for your `DUCKCODING_API_KEY` using `https://api.duckcoding.ai/v1/models` and caches key availability for 1 hour.
|
|
|
+4. **Local Fallback**: Re-checks and enriches model definitions against Pi's local model registry at session start (`session_start` event).
|
|
|
+
|
|
|
+## Cache Locations
|
|
|
+
|
|
|
+Cache files are stored in:
|
|
|
+- `~/.cache/pi-agent-duckcoding/models.json` (Model definitions & pricing)
|
|
|
+- `~/.cache/pi-agent-duckcoding/availability.json` (Key-specific model availability)
|
|
|
+
|
|
|
+## License
|
|
|
+
|
|
|
+MIT
|