steipete--codexbar/docs/neuralwatt.md

summary, read_when

summary	read_when
Neuralwatt provider notes: API key setup and quota usage fields.	Adding or modifying the Neuralwatt provider Debugging Neuralwatt API keys or quota parsing Adjusting Neuralwatt credit labels

Neuralwatt Provider

The Neuralwatt provider reads account quota from the Neuralwatt Cloud API using an API key. Neuralwatt Cloud is an OpenAI-compatible inference API with energy-based pricing. Prepaid credits are a deplete-as-you-go USD balance: they do not reset on a billing cycle and are refilled by topping up. Active subscription usage is billed separately against a kWh allowance. The quota endpoint exposes both surfaces plus current-month spend and optional per-key spending allowances.

Features

• Active subscription kWh usage (kwh_used / kwh_included) as the primary quota window, with the subscription period end as its reset date.
• The separate prepaid USD credit balance as a pay-as-you-go balance. It does not reset and may be zero while subscription kWh remains available.
• Per-key spending allowance (spent_usd / limit_usd) as an extra rate window when configured.
• Subscription plan shown as the provider identity label, falling back to accounting method (Token vs Energy).
• Current calendar-month spend is parsed for future/reporting use, but is not shown as a resettable quota window.

Setup

CLI

Store the API key without opening Settings:

printf '%s' "$NEURALWATT_API_KEY" | codexbar config set-api-key --provider neuralwatt --stdin

This trims the piped key, writes it to CodexBar's config file (~/.config/codexbar/config.json by default, or the legacy ~/.codexbar/config.json when already present), and enables Neuralwatt by default. Use --no-enable to save the key without enabling the provider.

Settings

1. Open Settings → Providers
2. Enable Neuralwatt
3. Open https://portal.neuralwatt.com/dashboard
4. Create or copy an API key
5. Paste the key into CodexBar's Neuralwatt provider settings

Environment Variables

CodexBar also accepts these environment variables:

• NEURALWATT_API_KEY

For tests or self-hosted/proxy setups, override the API base URL with NEURALWATT_API_URL.

How It Works

• Endpoint: GET https://api.neuralwatt.com/v1/quota
• Auth header: Authorization: Bearer sk-...
• Fields used: balance.credits_remaining_usd, balance.total_credits_usd, balance.credits_used_usd, balance.accounting_method, usage.current_month.cost_usd, subscription.plan, subscription.current_period_end, subscription.kwh_included, subscription.kwh_used, subscription.kwh_remaining, key.allowance.limit_usd, key.allowance.spent_usd, key.allowance.period
• credits_used_usd is derived as total_credits_usd − credits_remaining_usd when the API omits it.
• subscription may be null; prepaid balance remains visible without a subscription window.
• Transient quota failures are retried once, including Retry-After handling for rate limits.

The native fetcher remains authoritative because that delayed retry behavior is not expressible through the current plugin HTTP API, which has no retry-policy or sleep capability.

Troubleshooting

"Missing Neuralwatt API key"

Set the key with codexbar config set-api-key --provider neuralwatt --stdin, add it in Settings → Providers → Neuralwatt, set NEURALWATT_API_KEY, or configure a Neuralwatt token account in CodexBar.

"Neuralwatt API error"

Confirm the API key is valid and that the current network can reach api.neuralwatt.com. The quota endpoint is rate-limited to 1 request per second per customer; CodexBar refreshes on its normal cycle so this should not be hit in practice.