pi-tarmis-provider 1.0.7

package/AGENTS.md

@@ -0,0 +1,82 @@
+# AGENTS.md
+
+## DO NOT EDIT — Auto-generated Files
+
+The following files are **idempotent** and regenerated by `scripts/update-models.js`. Never edit them directly — your changes will be overwritten on the next model sync.
+
+| File | Why it's auto-generated |
+|------|------------------------|
+| `models.json` | Built from the provider API. `update-models.js` fetches models, derives pricing/context/maxTokens/vision/reasoning from the API metadata, and writes this file. |
+| `deprecated-models.json` | Graveyard for models the API delisted. update-models.js stamps them with deprecatedAt and pi keeps serving them for a 2-week grace period, then evicts them. Never edit by hand. |
+| `README.md` (model table) | The table under `## Available Models` is replaced in-place by `update-models.js` after merging base models → patch → custom models. |
+
+## Correct Files to Edit
+
+When a model needs overrides, new properties, or corrections, edit the appropriate source file below. These are the **source of truth** that the update script reads but never writes.
+
+| File | Purpose |
+|------|---------|
+| `patch.json` | Per-model overrides keyed by model ID. Add reasoning flags, compat settings, pricing corrections, thinking level maps, etc. Applied on top of `models.json` at runtime and for README generation. |
+| `custom-models.json` | Models that don't exist in the provider API (hidden models, router endpoints, cross-provider aliases). Merged after patch. Format: array of full model objects (same schema as `models.json` entries). |
+| `index.ts` | Provider extension code. |
+| `scripts/update-models.js` | The sync script itself (edit only if changing how models are fetched/transformed). |
+
+## How Tarmis differs from other providers
+
+Tarmis's `/v1/models` endpoint returns **rich metadata** (name, per-token pricing with an optional cached-input rate, `context_length`, `max_output_length`, `input_modalities`, and `supported_features`). `transformModel` derives most model fields directly from the API, so `models.json` self-heals on every sync:
+
+- `reasoning` ← `supported_features` includes `"reasoning"`
+- `input` / vision ← `input_modalities` includes `"image"`
+- `cost` ← `pricing[0].prompt` / `completion` / `input_cache_read` (per-token → per-million)
+- `contextWindow` ← `context_length`
+- `maxTokens` ← `max_output_length`
+
+The API reports *which* models support reasoning, but not the wire format each model expects. Reasoning models are given standard OpenAI-compatible defaults (`thinkingFormat: "openai"`, `supportsReasoningEffort: true`, `supportsDeveloperRole: false`). `patch.json` is where you override that for any model that needs a different format (e.g. a DeepSeek-native `thinking` field).
+
+Additionally, `/v1/models` is **public** (no auth), so the catalogue syncs even before a key is configured.
+
+## Data Flow
+
+```
+Provider API  ──fetch──►  models.json  ──apply──►  patch.json  ──merge──►  custom-models.json
+                                    │                            │                      │
+                                    └────────────────────────────┴──────────────────────┘
+                                                      │
+                                              README model table
+```
+
+1. `models.json` — base data from the provider API (auto-generated, DO NOT EDIT)
+2. `patch.json` — overrides applied on top (EDIT THIS for corrections/enrichments)
+3. `custom-models.json` — additional models not in the API (EDIT THIS for new models)
+4. README table — rendered from the merged result of all three (auto-generated, DO NOT EDIT)
+
+## Common Tasks
+
+### Change a reasoning model's thinking format
+→ Edit `patch.json`. Add an entry keyed by the model's `id` with a `compat` override, e.g.:
+```json
+{
+  "deepseek-ai/DeepSeek-V4-Flash": {
+    "compat": { "thinkingFormat": "deepseek", "requiresReasoningContentOnAssistantMessages": true }
+  }
+}
+```
+
+### Add a compat setting or override pricing for an existing model
+→ Edit `patch.json`. Add an entry keyed by the model's `id`.
+
+### Add a model not available in the provider API
+→ Edit `custom-models.json`. Add a full model object to the array.
+
+### Update models from the provider API
+→ Run `node scripts/update-models.js` (the `/v1/models` endpoint is public — no key needed).
+
+### Regenerate the README model table
+→ Run `node scripts/update-models.js` — it updates both `models.json` and the README table.
+
+## TL;DR
+
+- **Never edit `models.json`** — edit `patch.json` instead.
+- **Never edit the README model table** — run the update script instead.
+- `patch.json` and `custom-models.json` are the source files you should modify.
+- Most model fields are auto-derived from the API; `patch.json` only needs entries when a model deviates from the defaults.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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,184 @@
+<div align="center">
+
+# 🪐 pi-tarmis-provider
+
+**Open models on Tarmis's own GPUs for [pi](https://github.com/earendil-works/pi-coding-agent)**
+
+_One OpenAI-compatible API to open models on Tarmis's own GPUs — DeepSeek, GLM, Kimi, MiniMax, and more._
+
+[![npm](https://img.shields.io/npm/v/pi-tarmis-provider)](https://www.npmjs.com/package/pi-tarmis-provider)
+[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+</div>
+
+---
+
+## Features
+
+- **OpenAI-compatible API** — Uses Tarmis's `/v1/chat/completions` endpoint
+- **Rich auto-synced catalogue** — The Tarmis `/v1/models` endpoint returns per-model pricing, context windows, max output, modalities, and supported features; `models.json` is generated directly from it
+- **Public model list** — `/v1/models` is unauthenticated, so pi lists Tarmis models (and the background model sync runs) even before you set a key
+- **Reasoning models** — Thinking models are detected from the API's `supported_features` and configured for `reasoning_effort` control
+- **Vision models** — Image input is auto-detected from `input_modalities`
+- **Tool use** — Function calling for models that advertise `tools` support
+- **Streaming** — Real-time token streaming
+- **Prompt caching** — Cached input is billed at a cheaper rate when the API reports an `input_cache_read` price
+
+## Available Models
+
+| Model | Context | Vision | Reasoning | Input $/M | Output $/M |
+|-------|---------|--------|-----------|-----------|------------|
+| DeepSeek V4 Flash | 1.0M | ❌ | ✅ | $0.09 | $0.18 |
+| DeepSeek V4 Pro | 1.0M | ❌ | ✅ | $0.43 | $0.87 |
+| GLM-5.2 | 1.0M | ❌ | ✅ | $0.60 | $2.20 |
+| Kimi K3 | 1.0M | ✅ | ✅ | $2.50 | $10.00 |
+| MiniMax M3 | 524K | ❌ | ✅ | $0.30 | $1.20 |
+
+> The table above is regenerated by `node scripts/update-models.js` from the live Tarmis API. Costs are per million tokens (the API reports per-token prices). Prices subject to change — check [docs.tarmis.ai/docs/pricing](https://docs.tarmis.ai/docs/pricing) for current pricing.
+
+## Installation
+
+### Option 1: Using `pi install` (Recommended)
+
+Install from npm (published as [`pi-tarmis-provider`](https://www.npmjs.com/package/pi-tarmis-provider)) or directly from GitHub:
+
+```bash
+# From npm
+pi install npm:pi-tarmis-provider
+
+# Or directly from GitHub
+pi install https://github.com/monotykamary/pi-tarmis-provider
+```
+
+Then set your API key and run pi:
+```bash
+# Recommended: add to auth.json
+# See Authentication section below
+
+# Or set as environment variable
+export TARMIS_API_KEY=your-api-key-here
+
+pi
+```
+
+Get your API key from [tarmis.ai](https://tarmis.ai).
+
+### Option 2: Manual Clone
+
+1. Clone this repository:
+   ```bash
+   git clone https://github.com/monotykamary/pi-tarmis-provider.git
+   cd pi-tarmis-provider
+   ```
+
+2. Set your Tarmis API key:
+   ```bash
+   # Recommended: add to auth.json
+   # See Authentication section below
+
+   # Or set as environment variable
+   export TARMIS_API_KEY=your-api-key-here
+   ```
+
+3. Run pi with the extension:
+   ```bash
+   pi -e /path/to/pi-tarmis-provider
+   ```
+
+## Authentication
+
+The Tarmis API key can be configured in multiple ways (resolved in this order):
+
+1. **`auth.json`** (recommended) — Add to `~/.pi/agent/auth.json`:
+   ```json
+   { "tarmis": { "type": "api_key", "key": "your-api-key" } }
+   ```
+   The `key` field supports literal values, env var names, and shell commands (prefix with `!`). See [pi's auth file docs](https://github.com/badlogic/pi-mono) for details.
+2. **Runtime override** — Use the `--api-key` CLI flag
+3. **Environment variable** — Set `TARMIS_API_KEY`
+
+Get your API key from [tarmis.ai](https://tarmis.ai).
+
+> **Note:** A key is only required to actually call a model. The model catalogue (`/v1/models`) is public, so pi displays available Tarmis models and keeps them synced even before a key is configured.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `TARMIS_API_KEY` | No | Your Tarmis API key (fallback if not in auth.json; only needed to call a model) |
+
+## Configuration
+
+Add to your pi configuration for automatic loading:
+
+```json
+{
+  "extensions": [
+    "/path/to/pi-tarmis-provider"
+  ]
+}
+```
+
+## Usage
+
+Once loaded, select a model with:
+
+```
+/model tarmis minimax/minimax-m3
+```
+
+Or use `/models` to browse all available Tarmis models.
+
+### Reasoning Effort
+
+For reasoning models, control thinking depth:
+
+```
+/reasoning high
+```
+
+Values: `none`, `low`, `medium`, `high`, `max`
+
+## API Compatibility
+
+Tarmis provides an OpenAI-compatible API. Key notes:
+
+| Aspect | Behavior |
+|--------|----------|
+| Endpoint | `https://api.tarmis.ai/v1/chat/completions` |
+| Max tokens field | Both `max_tokens` and `max_completion_tokens` accepted |
+| Thinking format | `openai` (`reasoning_content` in response, `reasoning_effort` in request) |
+| Developer role | Not assumed (developer messages are converted to system) |
+| Reasoning effort | Accepted by reasoning models |
+| `/v1/models` | Public (no auth) — returns pricing, context, modalities, and features |
+| Prompt caching | Cached input billed at a cheaper `input_cache_read` rate when the API exposes one |
+
+> **Reasoning compat:** The Tarmis `/v1/models` endpoint reports *which* models support reasoning, but not the wire format each model expects. Reasoning models are given the standard OpenAI-compatible defaults (`thinkingFormat: "openai"`, `supportsReasoningEffort: true`, `supportsDeveloperRole: false`). If a model on Tarmis needs a different format (for example DeepSeek's native `thinking` field), override it in `patch.json` — see [AGENTS.md](./AGENTS.md).
+
+## API Documentation
+
+- Tarmis Docs: https://docs.tarmis.ai
+- OpenAI-compatible endpoint: `https://api.tarmis.ai/v1`
+- Models endpoint (public): `https://api.tarmis.ai/v1/models`
+- Pricing: https://docs.tarmis.ai/docs/pricing
+
+## Updating Models
+
+Run the update script to fetch the latest models from Tarmis's API:
+
+```bash
+node scripts/update-models.js
+```
+
+The `/v1/models` endpoint is public, so no API key is required. This will:
+
+1. Fetch models from `https://api.tarmis.ai/v1/models`
+2. Derive pricing, context windows, max output, vision, and reasoning support from the API metadata
+3. Apply overrides from `patch.json`
+4. Update `models.json` and the README model table
+5. Move delisted models into `deprecated-models.json` (14-day grace period)
+
+## License
+
+MIT

package/custom-models.json

@@ -0,0 +1 @@
+[]

package/deprecated-models.json

@@ -0,0 +1 @@
+{}