Aliou Diallo
projects releases npm github

pi-neuralwatt

Pi extension providing a Neuralwatt inference API provider with energy transparency

banner

A Pi extension that adds Neuralwatt as a model provider, giving you access to open-source models through an OpenAI-compatible API with energy transparency.

Installation

Get API Key

Sign up here to get an API key (referral link).

Configure Credentials

The extension uses Pi’s credential storage. Add your API key to ~/.pi/agent/auth.json (recommended):

{
  "neuralwatt": { "type": "api_key", "key": "your-api-key-here" }
}

Or set environment variable:

export NEURALWATT_API_KEY="your-api-key-here"

Install Extension

# From npm
pi install npm:@aliou/pi-neuralwatt

# From git
pi install git:github.com/aliou/pi-neuralwatt

# Local development
pi -e ./extensions/provider/index.ts

Usage

Once installed, select neuralwatt as your provider and choose from available models:

/model neuralwatt meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8

API surface

Neuralwatt serves every model on two APIs. Pick one via /neuralwatt:settings → API (or set provider.api in the extension config):

The setting swaps the whole provider (same model ids on both sides) and applies on /reload. Usage/cost accounting and quota tracking work on both surfaces: per-request quota headers only exist on chat-completions responses, while /v1/messages streams carry the same data as : energy / : cost SSE comments.

Quota Command

Check your API usage at a glance:

/neuralwatt:quota

The quota command shows three tabs:

https://github.com/user-attachments/assets/a8994940-c467-4744-a0f2-833cb63923ff

Quota Warnings

When enabled, the extension notifies you when credits or energy are running low. When you have an active subscription, only energy warnings fire (credits are on-demand top-up only). Warnings use escalation on severity transitions and have a cooldown for warning level.

Sub-bar Integration

When a Neuralwatt model is active, the footer status bar shows live quota usage (credits and energy). The status updates after each response and on session start.

Settings

Configure features with /neuralwatt:settings:

The provider itself cannot be disabled — it is always loaded.

Configuration uses nested per-feature sections. Existing flat config files are migrated automatically, with a backup written next to the migrated config.

Model Refresh

Neuralwatt registers its public models without network access. Opening /model refreshes the catalog from the API in the background (authenticated when an API key is configured). pi update --models forces an immediate refresh.

Pi stores the complete effective Neuralwatt catalog in ~/.pi/agent/models-store.json for offline startup. Current hardcoded public definitions remain authoritative when cached models are restored.

Adding or Updating Models

Public models are hardcoded in extensions/provider/models/public-models.ts and validated against the live API. To update:

  1. Run pnpm test — it fetches /v1/models and compares against hardcoded definitions
  2. Fix any discrepancies (missing models, changed context windows)
  3. Re-run pnpm test to confirm

Development

Setup

git clone https://github.com/aliou/pi-neuralwatt.git
cd pi-neuralwatt

# Install dependencies (sets up pre-commit hooks)
pnpm install && pnpm prepare

Pre-commit hooks run on every commit:

Commands

# Type check
pnpm run typecheck

# Lint
pnpm run lint

# Format
pnpm run format

# Test
pnpm run test

Release

This repository uses Changesets for versioning.

Requirements