Pārlūkot izejas kodu

add readme

Signed-off-by: greatbridf <[email protected]>
greatbridf 1 mēnesi atpakaļ
vecāks
revīzija
fa140c66d0
1 mainītis faili ar 104 papildinājumiem un 0 dzēšanām
  1. 104 0
      README.md

+ 104 - 0
README.md

@@ -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