@aliou/pi-neuralwatt 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,150 @@
+![banner](assets/banner.png)
+
+# Pi Neuralwatt Extension
+
+A Pi extension that adds [Neuralwatt](https://portal.neuralwatt.com/auth/register?ref=NW-ALIOU-Q7MF) 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 at [neuralwatt.com](https://portal.neuralwatt.com/auth/register?ref=NW-ALIOU-Q7MF) to get an API key.
+
+### Configure Credentials
+
+The extension uses Pi's credential storage. Add your API key to `~/.pi/agent/auth.json` (recommended):
+
+```json
+{
+  "neuralwatt": { "type": "api_key", "key": "your-api-key-here" }
+}
+```
+
+Or set environment variable:
+
+```bash
+export NEURALWATT_API_KEY="your-api-key-here"
+```
+
+### Install Extension
+
+```bash
+# From npm
+pi install npm:@aliou/pi-neuralwatt
+
+# From git
+pi install git:github.com/aliou/pi-neuralwatt
+
+# Local development
+pi -e ./src/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
+```
+
+### Quota Command
+
+Check your API usage at a glance:
+
+```
+/neuralwatt:quota
+```
+
+The quota command shows three tabs:
+- **Subscription** (when subscribed) — plan details, energy quota with progress bar, billing period
+- **Credits** — credit balance with progress bar, accounting method
+- **Usage & Key** — monthly usage (cost, requests, tokens, energy), API key info, key allowance, rate limits
+
+### 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 via `/neuralwatt:settings` or `pi config`:
+
+```
+/neuralwatt:settings
+```
+
+Available settings:
+- **Quota command** (`quotaCommand`) — Show/hide `/neuralwatt:quota`
+- **Quota warnings** (`quotaWarnings`) — Enable/disable low quota notifications
+- **Sub-bar integration** (`subBarIntegration`) — Show/hide usage in status bar
+
+The provider itself cannot be disabled — it is always loaded.
+
+## Disabling Features
+
+Each feature is a separate Pi extension. You can disable individual features using `pi config`:
+
+```
+pi config extensions.disabled add @aliou/pi-neuralwatt/quota-warnings
+```
+
+This prevents the quota-warnings extension from loading while keeping the rest active. Replace `quota-warnings` with `command-quotas` or `sub-bar-integration` to disable other features.
+
+## Adding or Updating Models
+
+Models are hardcoded in `src/extensions/provider/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
+
+```bash
+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:
+- TypeScript type checking
+- Biome linting
+- Biome formatting with auto-fix
+
+### Commands
+
+```bash
+# Type check
+pnpm run typecheck
+
+# Lint
+pnpm run lint
+
+# Format
+pnpm run format
+
+# Test
+pnpm run test
+```
+
+## Release
+
+This repository uses [Changesets](https://github.com/changesets/changesets) for versioning.
+
+## Requirements
+
+- Pi coding agent v0.67.68+
+- Neuralwatt API key (configured in `~/.pi/agent/auth.json` or via `NEURALWATT_API_KEY`)
+
+## Links
+
+- [Neuralwatt](https://portal.neuralwatt.com/auth/register?ref=NW-ALIOU-Q7MF)
+- [Neuralwatt API Docs](https://neuralwatt.com/docs)
+- [Pi Documentation](https://buildwithpi.ai/)

package/package.json

@@ -1,15 +1,77 @@
 {
   "name": "@aliou/pi-neuralwatt",
-  "version": "0.0.1",
-  "description": "Pi extension providing a Neuralwatt inference API provider",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
   "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/aliou/pi-neuralwatt"
   },
-  "license": "MIT",
-  "main": "index.js",
+  "pi": {
+    "extensions": [
+      "./src/extensions/provider/index.ts",
+      "./src/extensions/command-quotas/index.ts",
+      "./src/extensions/quota-warnings/index.ts",
+      "./src/extensions/sub-bar-integration/index.ts"
+    ]
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "files": [
+    "src",
+    "schema.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aliou/pi-utils-settings": "^0.9.0",
+    "@aliou/pi-utils-ui": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": ">=0.67.68",
+    "@mariozechner/pi-tui": ">=0.67.68",
+    "@sinclair/typebox": ">=0.34.0"
+  },
+  "devDependencies": {
+    "@aliou/biome-plugins": "^0.8.1",
+    "@biomejs/biome": "^2.4.12",
+    "@changesets/cli": "^2.27.11",
+    "@mariozechner/pi-coding-agent": "0.67.68",
+    "@mariozechner/pi-tui": "0.67.68",
+    "@types/node": "^25.0.10",
+    "husky": "^9.1.7",
+    "ts-json-schema-generator": "^2.4.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-coding-agent": {
+      "optional": true
+    },
+    "@mariozechner/pi-tui": {
+      "optional": true
+    },
+    "@sinclair/typebox": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "format": "biome check --write",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "gen:schema": "ts-json-schema-generator --path src/config.ts --type NeuralwattConfig --no-type-check -o schema.json",
+    "check:schema": "ts-json-schema-generator --path src/config.ts --type NeuralwattConfig --no-type-check -o /tmp/schema-check.json && diff -q schema.json /tmp/schema-check.json",
+    "check:lockfile": "pnpm install --frozen-lockfile --ignore-scripts",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm changeset publish"
   }
-}
+}

package/schema.json

@@ -0,0 +1,24 @@
+{
+  "$ref": "#/definitions/NeuralwattConfig",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "NeuralwattConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "quotaCommand": {
+          "description": "Show the quota command (/neuralwatt:quota).",
+          "type": "boolean"
+        },
+        "quotaWarnings": {
+          "description": "Show quota warnings when credits or energy are low.",
+          "type": "boolean"
+        },
+        "subBarIntegration": {
+          "description": "Show usage in the sub-bar / status bar.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,154 @@
+import {
+  ConfigLoader,
+  registerSettingsCommand,
+  type SettingsSection,
+} from "@aliou/pi-utils-settings";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { SettingItem } from "@mariozechner/pi-tui";
+
+export type NeuralwattFeatureId =
+  | "quotaCommand"
+  | "quotaWarnings"
+  | "subBarIntegration";
+
+export const NEURALWATT_EXTENSIONS_REQUEST_EVENT =
+  "neuralwatt:extensions:request" as const;
+
+export const NEURALWATT_EXTENSIONS_REGISTER_EVENT =
+  "neuralwatt:extensions:register" as const;
+
+export interface NeuralwattExtensionsRegisterPayload {
+  feature: NeuralwattFeatureId;
+}
+
+export interface NeuralwattConfig {
+  /** Show the quota command (/neuralwatt:quota). */
+  quotaCommand?: boolean;
+  /** Show quota warnings when credits or energy are low. */
+  quotaWarnings?: boolean;
+  /** Show usage in the sub-bar / status bar. */
+  subBarIntegration?: boolean;
+}
+
+export interface ResolvedNeuralwattConfig {
+  quotaCommand: boolean;
+  quotaWarnings: boolean;
+  subBarIntegration: boolean;
+}
+
+const DEFAULTS: ResolvedNeuralwattConfig = {
+  quotaCommand: true,
+  quotaWarnings: true,
+  subBarIntegration: true,
+};
+
+export const configLoader = new ConfigLoader<
+  NeuralwattConfig,
+  ResolvedNeuralwattConfig
+>("neuralwatt", DEFAULTS);
+
+export const NEURALWATT_CONFIG_UPDATED_EVENT =
+  "neuralwatt:config:updated" as const;
+
+export interface NeuralwattConfigUpdatedPayload {
+  config: ResolvedNeuralwattConfig;
+}
+
+export function emitConfigUpdated(pi: ExtensionAPI): void {
+  pi.events.emit(NEURALWATT_CONFIG_UPDATED_EVENT, {
+    config: configLoader.getConfig(),
+  });
+}
+
+export interface RegisterNeuralwattSettingsOptions {
+  getLoadedFeatures: () => Set<NeuralwattFeatureId>;
+}
+
+function featureRow(
+  id: NeuralwattFeatureId,
+  label: string,
+  description: string,
+  configValue: boolean,
+  isLoaded: boolean,
+): SettingItem {
+  if (isLoaded) {
+    return {
+      id,
+      label,
+      description,
+      currentValue: configValue ? "enabled" : "disabled",
+      values: ["enabled", "disabled"],
+    };
+  }
+  return {
+    id,
+    label,
+    description: `${description} (Not loaded by Pi)`,
+    currentValue: "unavailable",
+    values: [],
+  };
+}
+
+export function registerNeuralwattSettings(
+  pi: ExtensionAPI,
+  options: RegisterNeuralwattSettingsOptions,
+): void {
+  const { getLoadedFeatures } = options;
+
+  registerSettingsCommand<NeuralwattConfig, ResolvedNeuralwattConfig>(pi, {
+    commandName: "neuralwatt:settings",
+    title: "Neuralwatt Settings",
+    configStore: configLoader,
+    buildSections: (tabConfig, resolved): SettingsSection[] => {
+      const loaded = getLoadedFeatures();
+      return [
+        {
+          label: "Features",
+          items: [
+            featureRow(
+              "quotaCommand",
+              "Quota command",
+              "Toggle the /neuralwatt:quota command, showing your API usage at a glance",
+              tabConfig?.quotaCommand ?? resolved.quotaCommand,
+              loaded.has("quotaCommand"),
+            ),
+            featureRow(
+              "quotaWarnings",
+              "Quota warnings",
+              "Toggle notifications when credits or energy are running low",
+              tabConfig?.quotaWarnings ?? resolved.quotaWarnings,
+              loaded.has("quotaWarnings"),
+            ),
+            featureRow(
+              "subBarIntegration",
+              "Sub-bar integration",
+              "Toggle integration with the status bar and sub-core",
+              tabConfig?.subBarIntegration ?? resolved.subBarIntegration,
+              loaded.has("subBarIntegration"),
+            ),
+          ],
+        },
+      ];
+    },
+    onSettingChange: (id, newValue, config) => {
+      if (!getLoadedFeatures().has(id as NeuralwattFeatureId)) {
+        return null;
+      }
+
+      const enabled = newValue === "enabled";
+      switch (id) {
+        case "quotaCommand":
+          return { ...config, quotaCommand: enabled };
+        case "quotaWarnings":
+          return { ...config, quotaWarnings: enabled };
+        case "subBarIntegration":
+          return { ...config, subBarIntegration: enabled };
+        default:
+          return null;
+      }
+    },
+    onSave: async () => {
+      emitConfigUpdated(pi);
+    },
+  });
+}

package/src/extensions/command-quotas/command.ts

@@ -0,0 +1,83 @@
+import { join } from "node:path";
+import { type ExtensionAPI, getAgentDir } from "@mariozechner/pi-coding-agent";
+import { getNeuralwattApiKey } from "../../lib/env";
+import { fetchQuotas } from "../../utils/quotas";
+import { QuotasComponent } from "./components/quotas-display";
+
+function missingAuthMessage(): string {
+  const authPath = join(getAgentDir(), "auth.json");
+  return `Neuralwatt quota requires an API key. Add credentials to ${authPath} or set the NEURALWATT_API_KEY environment variable.`;
+}
+
+export function registerQuotasCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("neuralwatt:quota", {
+    description: "Display Neuralwatt API usage and quota",
+    handler: async (_args, ctx) => {
+      const apiKey = await getNeuralwattApiKey(ctx.modelRegistry.authStorage);
+      if (!apiKey) {
+        ctx.ui.notify(missingAuthMessage(), "warning");
+        return;
+      }
+      const key: string = apiKey;
+
+      const result = await ctx.ui.custom<null>((tui, theme, _kb, done) => {
+        const controller = new AbortController();
+        const component = new QuotasComponent(
+          theme,
+          tui,
+          () => {
+            controller.abort();
+            done(null);
+          },
+          () => {
+            component.setState({ type: "loading" });
+            tui.requestRender();
+            void loadQuotas();
+          },
+        );
+
+        async function loadQuotas(): Promise<void> {
+          const fetchResult = await fetchQuotas(key, controller.signal);
+          if (controller.signal.aborted) return;
+          if (fetchResult.success) {
+            component.setState({
+              type: "loaded",
+              quotas: fetchResult.data.quotas,
+            });
+          } else {
+            component.setState({
+              type: "error",
+              message: fetchResult.error.message,
+            });
+          }
+          tui.requestRender();
+        }
+
+        void loadQuotas();
+
+        return {
+          render: (width: number) => component.render(width),
+          invalidate: () => component.invalidate(),
+          handleInput: (data: string) => component.handleInput(data),
+          dispose: () => {
+            controller.abort();
+            component.destroy();
+          },
+        };
+      });
+
+      // Non-interactive fallback (RPC, print, JSON modes)
+      if (result === undefined) {
+        const fetchResult = await fetchQuotas(key);
+        if (!fetchResult.success) {
+          ctx.ui.notify(
+            JSON.stringify({ error: fetchResult.error.message }),
+            "error",
+          );
+          return;
+        }
+        ctx.ui.notify(JSON.stringify(fetchResult.data.quotas), "info");
+      }
+    },
+  });
+}