# zidane/providers/neuralwatt

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

Import: `import { … } from 'zidane/providers/neuralwatt'`. Source: [src/providers/neuralwatt.ts](https://github.com/Tahul/zidane/blob/main/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`.

```ts
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

### `neuralwatt`

Function.

Neuralwatt provider.

Thin wrapper around [`openaiCompat`](https://zidane.si/docs/reference/providers-openai-compat.md#openaiCompat): Bearer auth, usage requested on
the stream (`stream_options.include_usage`), reasoning round-tripped as
`reasoning_content`, the thinking level mapped by
[`planNeuralwattReasoning`](https://zidane.si/docs/reference/providers-neuralwatt.md#planNeuralwattReasoning), and the session id sent as
`X-NW-Conversation-ID` (see `NeuralwattParams.conversationId`).

```ts
function neuralwatt(params?: NeuralwattParams): Provider
```

**Parameters**

- `params?` (`NeuralwattParams`): API key, base URL, default model, capabilities, extra headers and conversation id settings.

**Returns** `Provider`

**Example**

```ts
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.' })
```

Source: [src/providers/neuralwatt.ts:115](https://github.com/Tahul/zidane/blob/main/src/providers/neuralwatt.ts#L115)

### `planNeuralwattReasoning`

Function.

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.

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

**Parameters**

- `ctx` (`{ model: string; thinking?: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'adaptive' }`): Request model id and thinking level.

**Returns** `Record<string, unknown> | undefined`

Source: [src/providers/neuralwatt.ts:85](https://github.com/Tahul/zidane/blob/main/src/providers/neuralwatt.ts#L85)

## Constants

### `NEURALWATT_DEFAULT_MODEL`

Constant.

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

```ts
const NEURALWATT_DEFAULT_MODEL = 'kimi-k3'
```

Source: [src/providers/neuralwatt.ts:15](https://github.com/Tahul/zidane/blob/main/src/providers/neuralwatt.ts#L15)

## Interfaces

### `NeuralwattParams`

Interface.

Options for [`neuralwatt`](https://zidane.si/docs/reference/providers-neuralwatt.md#neuralwatt).

```ts
interface NeuralwattParams
```

**Properties**

- `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`, default `'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`](https://zidane.si/docs/reference/providers-openai-compat.md#openaiCompat).

Source: [src/providers/neuralwatt.ts:24](https://github.com/Tahul/zidane/blob/main/src/providers/neuralwatt.ts#L24)