Skip to content
zidane
SDK reference

zidane/providers/neuralwatt

The Neuralwatt provider, with the measured energy of every request.

import { … } from 'zidane/providers/neuralwatt'src/providers/neuralwatt.ts

Use neuralwatt() when your agent runs on Neuralwatt. It reads NEURALWATT_API_KEY when you pass no key, and its default model is kimi-k3. Each turn reports the measured energy in usage.energyJoules and the provider's own cost. The agent's session id goes in the X-NW-Conversation-ID header, so Neuralwatt groups a conversation's requests. planNeuralwattReasoning() maps a thinking level to reasoning_effort.

TypeScript
import { createAgent } from 'zidane'
import { neuralwatt } from 'zidane/providers/neuralwatt'

const agent = createAgent({ provider: neuralwatt({ defaultModel: 'kimi-k3' }) })
const stats = await agent.run({ prompt: 'Summarize README.md in three bullets.' })
console.log(stats.turns)

Functions#

neuralwattFunction#

Neuralwatt provider.

Thin wrapper around openaiCompat: Bearer auth, usage requested on the stream (stream_options.include_usage), reasoning round-tripped as reasoning_content, the thinking level mapped by planNeuralwattReasoning, and the session id sent as X-NW-Conversation-ID (see NeuralwattParams.conversationId).

TypeScript
function neuralwatt(params?: NeuralwattParams): Provider

Parameters

Parameters
NameTypeDescription
params?NeuralwattParams

API key, base URL, default model, capabilities, extra headers and conversation id settings.

Returns

Provider

Example

Example
import { createAgent } from 'zidane'
import { neuralwatt } from 'zidane/providers/neuralwatt'

const agent = createAgent({
  provider: neuralwatt({ apiKey: process.env.NEURALWATT_API_KEY }),
})
await agent.run({ prompt: 'Say hello.' })

src/providers/neuralwatt.ts:115

planNeuralwattReasoningFunction#

Map zidane's thinking level to Neuralwatt's reasoning_effort. Every model with effort control accepts the full seven-value scale (none … max) and folds it onto the levels it really has, so levels pass through unchanged:

  • unset or 'adaptive' → nothing (the model's own default, which for most models means reasoning on).
  • 'off' → 'none', since most models reason unless told not to. Models with mandatory reasoning (GLM-5.3) ignore it.
  • every other level → the same string.

Exported for tests.

TypeScript
function planNeuralwattReasoning(
  ctx: { model: string; thinking?: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'adaptive' },
): Record<string, unknown> | undefined

Parameters

Parameters
NameTypeDescription
ctx{ model: string; thinking?: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'adaptive' }

Request model id and thinking level.

Returns

Record<string, unknown> | undefined

src/providers/neuralwatt.ts:85

Constants#

NEURALWATT_DEFAULT_MODELConstant#

Model used when neither the request nor NeuralwattParams.defaultModel names one.

TypeScript
const NEURALWATT_DEFAULT_MODEL = 'kimi-k3'

src/providers/neuralwatt.ts:15

Interfaces#

NeuralwattParamsInterface#

Options for neuralwatt.

TypeScript
interface NeuralwattParams

Properties

NeuralwattParams properties
NameTypeDefaultDescription
apiKey?string

API key. Falls back to the NEURALWATT_API_KEY environment variable.

baseURL?string

Override the base URL, e.g. to route through a proxy or AI gateway.

capabilities?ProviderCapabilities

Provider capability flags. Default: { vision: true, imageInToolResult: false }, which fits the default model (Kimi K3 reads images). Set vision: false when pinning a text-only model (glm-5.3, deepseek-v4-flash): Neuralwatt silently drops images sent to those rather than rejecting them.

conversationId?PromptCacheKeyOption

Value sent as the X-NW-Conversation-ID header, which Neuralwatt uses to group a conversation's requests into one session (exact grouping in its Sessions dashboard and API, instead of a guess from the prompt prefix) and to route them to the server holding their prompt cache.

Default 'session': the agent's session id, and no header when the run has no session. Takes the same shapes as promptCacheKey on the other OpenAI-compatible providers (see ./prompt-cache-key.ts); false sends no header. A value that is empty, longer than 256 characters or not printable ASCII is dropped, since Neuralwatt rejects it with a 400.

defaultModel?string'kimi-k3'

Model used when a request does not set one.

extraHeaders?Record<string, string>

Extra HTTP headers sent on every request. Forwarded to openaiCompat.

src/providers/neuralwatt.ts:24