pi-neuralwatt-provider 1.0.0

package/.github/FUNDING.yml

@@ -0,0 +1,4 @@
+github: monotykamary
+ko_fi: monotykamary
+buy_me_a_coffee: monotykamary
+polar: monotykamary

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

@@ -0,0 +1,51 @@
+name: Update Neuralwatt Models
+
+on:
+  schedule:
+    # Run daily at 00:00 UTC
+    - cron: '0 0 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-models:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Fetch and update models
+        run: node scripts/update-models.js
+
+      - 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.GITHUB_TOKEN }}
+          commit-message: 'feat: update neuralwatt models from API'
+          title: 'feat: update neuralwatt models from API'
+          body: |
+            Automated update of Neuralwatt models from https://api.neuralwatt.com/v1/models
+
+            Changes include:
+            - Updated models in `models.json`
+            - Updated model table in `README.md`
+          branch: update-neuralwatt-models
+          delete-branch: true

package/.pi/autoresearch/session-id

@@ -0,0 +1 @@
+019e2ca5-c86b-7705-aa78-225c135a3144

package/.pi/messenger/channels/memory.jsonl

@@ -0,0 +1 @@
+{"_meta":true,"v":1,"id":"memory","type":"named","createdAt":"2026-05-23T01:54:08.851Z","description":"Cross-session knowledge and insights"}

package/.pi/messenger/session-id

@@ -0,0 +1 @@
+019e9272-aa36-7f8b-8373-5182876ff15d

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,238 @@
+<div align="center">
+
+# ⚡ pi-neuralwatt-provider
+
+**Models + energy tracking via [Neuralwatt](https://neuralwatt.com)**
+
+_Kimi, GLM, Qwen, DeepSeek — with real-time ⚡ energy/cost per session for [pi](https://github.com/earendil-works/pi-coding-agent)._
+
+[![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>
+
+---
+
+![Energy Reporting Status Widget](assets/screenshot.jpg)
+
+## Features
+
+- **OpenAI-compatible API** - Uses Neuralwatt's `/v1/chat/completions` endpoint
+- **Reasoning models** - Support for thinking models with `reasoning_effort` parameter
+- **Vision models** - Image input support on Kimi K2.5, K2.6, and Devstral
+- **Tool use** - Function calling support
+- **Streaming** - Real-time token streaming
+- **Fast variants** - Optimized "Fast" versions of popular models for quicker responses
+- **Energy reporting** - Displays energy consumption (⚡J/mWh/Wh/kWh) and actual billed cost ($) in a dedicated status widget below the editor, tracked per-session
+- **Quota display** - Shows subscription plan, kWh allocation, and credits remaining from your Neuralwatt account, right-aligned in the status widget
+- **Configurable display** - Energy and quota can each be shown in the below-editor widget, the built-in status bar, or turned off entirely via a config file
+
+## Available Models
+
+| Model | Context | Vision | Reasoning | Input $/M | Output $/M |
+|-------|---------|--------|-----------|-----------|------------|
+| Devstral-Small-2-24B-Instruct-2512 | 262K | ✅ | ❌ | $0.12 | $0.35 |
+| GLM-5 Fast | 203K | ❌ | ❌ | $1.10 | $3.60 |
+| GLM-5.1 | 203K | ❌ | ✅ | $1.10 | $3.60 |
+| GLM-5.1 Fast | 203K | ❌ | ❌ | $1.10 | $3.60 |
+| GPT-OSS 20B | 16K | ❌ | ✅ | $0.03 | $0.16 |
+| Kimi K2.5 | 262K | ✅ | ✅ | $0.52 | $2.59 |
+| Kimi K2.5 Fast | 262K | ✅ | ❌ | $0.52 | $2.59 |
+| Kimi K2.6 | 262K | ✅ | ✅ | $0.69 | $3.22 |
+| Kimi K2.6 Fast | 262K | ✅ | ❌ | $0.69 | $3.22 |
+| MiniMax M2.5 | 197K | ❌ | ✅ | $0.35 | $1.38 |
+| Qwen3.5 397B | 262K | ❌ | ✅ | $0.69 | $4.14 |
+| Qwen3.5 397B Fast | 262K | ❌ | ❌ | $0.69 | $4.14 |
+| Qwen3.6 35B | 131K | ✅ | ✅ | $0.29 | $1.15 |
+| Qwen3.6 35B Fast | 131K | ✅ | ❌ | $0.29 | $1.15 |
+| GLM-5.1 Canary | 203K | ❌ | ✅ | $1.10 | $3.60 |
+| GLM-5.1 NVFP4 Canary | 203K | ❌ | ✅ | $1.10 | $3.60 |
+| Kimi K2.6 Canary | 262K | ✅ | ✅ | $0.69 | $3.22 |
+| GLM-5.1 Flex | 203K | ❌ | ✅ | $1.10 | $3.60 |
+| Kimi K2.6 Flex | 262K | ✅ | ✅ | $0.69 | $3.22 |
+| GLM-5 Long (MCR 1M) | 1.0M | ❌ | ✅ | $1.10 | $3.60 |
+| GLM-5.1 Long (MCR 1M) | 1.0M | ❌ | ✅ | $1.10 | $3.60 |
+| GLM-5.1 Long Coherence (MCR 1M Canary) | 1.0M | ❌ | ✅ | $1.10 | $3.60 |
+| GLM-5.1 Fast Long (MCR 1M) | 1.0M | ❌ | ❌ | $1.10 | $3.60 |
+| Kimi K2.6 Long (MCR 1M) | 1.0M | ✅ | ✅ | $0.69 | $3.22 |
+| Kimi K2.5 Long (MCR 1M) | 1.0M | ✅ | ✅ | $0.52 | $2.59 |
+| Claude Opus (Cached) | 1.0M | ❌ | ✅ | $0.00 | $0.00 |
+
+## Authentication
+
+The Neuralwatt API key can be configured in multiple ways (resolved in this order):
+
+1. **`auth.json`** (recommended) — Add to `~/.pi/agent/auth.json`:
+   ```json
+   { "neuralwatt": { "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 `NEURALWATT_API_KEY`
+
+Get your API key from [neuralwatt.com](https://neuralwatt.com).
+
+## Installation
+
+### Option 1: Using `pi install` (Recommended)
+
+Install directly from GitHub:
+
+```bash
+pi install https://github.com/monotykamary/pi-neuralwatt-provider
+```
+
+Then authenticate and run pi:
+```bash
+# Recommended: add to auth.json
+# See Authentication section below
+
+# Or set as environment variable
+export NEURALWATT_API_KEY=your-api-key-here
+
+pi
+```
+
+### Option 2: Manual Clone
+
+1. Clone this repository:
+   ```bash
+   git clone git@github.com:monotykamary/pi-neuralwatt-provider.git
+   cd pi-neuralwatt-provider
+   ```
+
+2. Configure your Neuralwatt API key:
+   ```bash
+   # Recommended: add to auth.json
+   # See Authentication section below
+
+   # Or set as environment variable
+   export NEURALWATT_API_KEY=your-api-key-here
+   ```
+
+3. Run pi with the extension:
+   ```bash
+   pi -e /path/to/pi-neuralwatt-provider
+   ```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `NEURALWATT_API_KEY` | No | Your Neuralwatt API key (fallback if not in auth.json) |
+
+## Configuration
+
+### Compat Settings
+
+Neuralwatt's API now provides compatibility and capability metadata (pricing, reasoning, vision, developer_role, reasoning_effort, max_images) directly in the `/v1/models` response. The `update-models.js` script reads these and writes them into `models.json`. Only genuinely incorrect API data needs a manual override in `patch.json`.
+
+Currently configured compat settings (all sourced from the API):
+
+- **`supportsDeveloperRole: false`** — All models. vLLM doesn't support the `developer` role; pi sends system prompts as `system` messages instead.
+- **`supportsReasoningEffort: true`** — GPT-OSS. Sends `reasoning_effort` parameter (maps to pi's `/reasoning` command levels).
+
+### Custom Stream Handler
+
+This extension registers a custom `streamSimple` provider (`api: "neuralwatt"`) that wraps pi-ai's built-in `streamOpenAICompletions`. A temporary `globalThis.fetch` override tees the HTTP response body so the OpenAI SDK handles all standard chunk parsing (text, thinking, tool calls, usage) while the extension reads the tee for Neuralwatt's SSE comment lines (`: energy {...}`, `: cost {...}`) that the SDK discards.
+
+### Pi Configuration
+
+Add to your pi configuration for automatic loading:
+
+```json
+{
+  "extensions": [
+    "/path/to/pi-neuralwatt-provider"
+  ]
+}
+```
+
+## Usage
+
+Once loaded, select a model with:
+
+```
+/model neuralwatt kimi-k2.5
+```
+
+Or use `/models` to browse all available Neuralwatt models.
+
+### Reasoning Effort
+
+For reasoning models, control thinking depth:
+
+```
+/reasoning high
+```
+
+Values: `none`, `low`, `medium`, `high`
+
+## Display Configuration
+
+Energy and quota are independently configurable. Create `~/.pi/agent/extensions/neuralwatt.json`:
+
+```json
+{
+  "energy": "widget",
+  "quota": "widget"
+}
+```
+
+The file is auto-populated with defaults on first run.
+
+| Key | Values | Default | Description |
+|-----|--------|---------|-------------|
+| `energy` | `"widget"`, `"statusbar"`, `"off"` | `"widget"` | Energy/cost display mode |
+| `quota` | `"widget"`, `"statusbar"`, `"off"` | `"widget"` | Quota display mode |
+
+**Display modes:**
+
+- **`"widget"`** — Shown in the dedicated below-editor status line. Energy on the left, quota on the right, padded to terminal width.
+- **`"statusbar"`** — Shown in the built-in pi status bar. When both are set to `"statusbar"`, they're combined with a ` | ` separator: `⚡X J $Y | plan ● kWh ∙ $bal`.
+- **`"off"`** — Hidden entirely. For `"quota": "off"`, the `/v1/quota` API fetch is also skipped (saving a network round-trip). Energy data is still parsed from the SSE stream and persisted to the session even when `"off"`.
+
+**Example — custom quota footer:** If you use your own unified quota footer extension, disable the built-in quota display to avoid duplication:
+
+```json
+{
+  "energy": "widget",
+  "quota": "off"
+}
+```
+
+## Energy Reporting
+
+Neuralwatt provides real-time energy consumption data with every API response. This extension captures it and displays a running total in a dedicated status widget between the editor and the pi footer:
+
+| Segment | Meaning |
+|---------|----------|
+| `⚡0.8mWh` | Cumulative session energy consumption (auto-scaled: J → mWh → Wh → kWh) |
+| `$0.003952` | Cumulative session actual billed cost from Neuralwatt |
+| `pro` | Your Neuralwatt subscription plan |
+| `●` | Subscription status indicator (● = active, ⊘ = past due/paused) |
+| `31.7/33.0 kWh` | kWh remaining / kWh included in your plan |
+| `∙ $64.55` | Credits remaining on your account |
+| `🔑 .../.../mo` | Key allowance usage (if set on your API key) |
+
+The energy and cost data comes from Neuralwatt's SSE stream comments (`: energy` and `: cost`), which the standard OpenAI SDK discards. This extension uses a custom stream handler that parses raw SSE to capture them.
+
+Energy is measured directly from GPU hardware using NVIDIA's NVML. For concurrent requests, Neuralwatt uses token-weighted attribution to fairly calculate your share. See [Neuralwatt's energy methodology](https://portal.neuralwatt.com/docs/energy-methodology) for details.
+
+### Persistence
+
+Energy and cost data is persisted per-request as custom session entries. On session resume or tree navigation, the totals are rebuilt by replaying all events in the current branch. This means:
+
+- **Session resume** — Energy/cost totals are restored when you continue a session
+- **Branching** — Navigating to a different point in the session tree shows the correct totals for that branch
+- **Forking** — Forked sessions carry their energy history forward
+
+## API Documentation
+
+- Neuralwatt API: `https://api.neuralwatt.com/v1`
+- Models endpoint: `https://api.neuralwatt.com/v1/models`
+- Chat completions: `https://api.neuralwatt.com/v1/chat/completions`
+
+## License
+
+MIT