> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/relay/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/relay/_mcp/server.

# Adaptive Helpers

> Adaptive plugin configuration helpers.

Generated from `crates/node/adaptive.d.ts`.

Import from `nemo-relay-node/adaptive`.

Adaptive plugin configuration helpers.

## Interfaces

### `BackendSpec`

Adaptive state backend selection.

```ts
export interface BackendSpec {
  kind: string;
  config?: Record<string, Json>;
}
```

### `StateConfig`

Adaptive state configuration.

```ts
export interface StateConfig {
  backend: BackendSpec;
}
```

### `TelemetryConfig`

Built-in adaptive telemetry settings.

```ts
export interface TelemetryConfig {
  subscriber_name?: string;
  learners?: string[];
}
```

### `AdaptiveHintsConfig`

Built-in adaptive hints injection settings.

```ts
export interface AdaptiveHintsConfig {
  priority?: number;
  break_chain?: boolean;
  inject_header?: boolean;
  inject_body_path?: string;
}
```

### `ToolParallelismConfig`

Built-in adaptive tool scheduling settings.

```ts
export interface ToolParallelismConfig {
  priority?: number;
  mode?: 'observe_only' | 'inject_hints' | 'schedule' | string;
}
```

### `AcgStabilityThresholds`

ACG prompt-stability classification thresholds.

```ts
export interface AcgStabilityThresholds {
  stable_threshold?: number;
  semi_stable_threshold?: number;
  min_observations_for_full_confidence?: number;
}
```

### `AcgConfig`

Adaptive cache-governor settings.

```ts
export interface AcgConfig {
  provider?: 'anthropic' | 'openai' | 'passthrough' | string;
  observation_window?: number;
  priority?: number;
  stability_thresholds?: AcgStabilityThresholds;
}
```

### `Config`

Canonical config object for the top-level adaptive component.

```ts
export interface Config {
  version?: number;
  agent_id?: string;
  state?: StateConfig;
  telemetry?: TelemetryConfig;
  adaptive_hints?: AdaptiveHintsConfig;
  tool_parallelism?: ToolParallelismConfig;
  acg?: AcgConfig;
  policy?: ConfigPolicy;
}
```

### `ComponentSpec` interface

Top-level adaptive component wrapper with fixed kind `adaptive`.

```ts
export interface ComponentSpec {
  kind: 'adaptive';
  enabled?: boolean;
  config: Config;
}
```

### `CacheUsage`

Normalized LLM token usage for cache telemetry.

```ts
export interface CacheUsage {
  prompt_tokens?: number;
  completion_tokens?: number;
  total_tokens?: number;
  cache_read_tokens?: number;
  cache_write_tokens?: number;
  cost?: Json;
}
```

### `AgentIdentity`

Identity of the agent associated with cache telemetry.

```ts
export interface AgentIdentity {
  agent_id: string;
  template_version: string;
  toolset_hash: string;
  model_family: string;
  tenant_scope: string;
}
```

### `CacheRequestFactsOptions`

Input for building cache request facts.

```ts
export interface CacheRequestFactsOptions {
  provider: string;
  requestId: string;
  annotatedRequest: Json;
  agentId: string;
  timestamp?: string;
}
```

### `CacheRequestFacts`

Request-time facts used to classify cache misses.

```ts
export interface CacheRequestFacts {
  provider: string;
  stable_prefix_length: number;
  stable_prefix_tokens?: number;
  required_min_tokens?: number;
  first_mismatch_span_id?: string;
  first_mismatch_sequence_index?: number;
  expected_hash_prefix?: string;
  actual_hash_prefix?: string;
  retention_window_secs?: number;
  observed_gap_secs?: number;
  missing_facts?: string[];
}
```

### `CacheTelemetryEventOptions`

Input for building cache telemetry events.

```ts
export interface CacheTelemetryEventOptions {
  provider: 'anthropic' | 'openai' | string;
  requestId: string;
  usage?: CacheUsage | null;
  requestFacts?: CacheRequestFacts | null;
  agentId: string;
  templateVersion: string;
  toolsetHash: string;
  modelFamily: string;
  tenantScope: string;
  timestamp?: string;
}
```

### `CacheTelemetryEvent`

Normalized adaptive cache telemetry event.

```ts
export interface CacheTelemetryEvent {
  request_id: string;
  agent_identity: AgentIdentity;
  cache_read_tokens: number;
  cache_creation_tokens: number;
  total_prompt_tokens: number;
  hit_rate: number;
  miss_reason?: Record<string, Json>;
  miss_diagnosis?: Record<string, Json>;
  provider: string;
  timestamp: string;
}
```

## Classes

### `AdaptiveRuntime`

Owned adaptive runtime outside the generic plugin system.

```ts
export declare class AdaptiveRuntime {
  constructor(config: Config);
  /** Register all configured adaptive runtime features. */
  register(): Promise<void>;
  /** Deregister all previously registered adaptive runtime features. */
  deregister(): void;
  /** Shut down the adaptive runtime and consume its Rust runtime state. */
  shutdown(): Promise<void>;
  /** Block until adaptive telemetry has processed pending events. */
  waitForIdle(): void;
  /** Return the validation report captured during construction. */
  report(): ConfigReport;
  /** Bind the runtime's ACG request rewrite to a scope. */
  bindScope(scopeHandle: ScopeHandle): void;
  /** Build cache request facts for an annotated LLM request. */
  buildCacheRequestFacts(options: CacheRequestFactsOptions): CacheRequestFacts | null;
}
```

## Functions

### `defaultConfig`

Create a default adaptive component config.

Returns the minimal top-level adaptive config shape with `version = 1` so callers can add state, telemetry, and scheduler settings incrementally.

**Returns**

A new adaptive config object.

**Remarks**

The returned object is detached from runtime state until it is wrapped with `ComponentSpec` and activated through the plugin system.

```ts
export declare function defaultConfig(): Config;
```

### `inMemoryBackend`

Create an in-memory adaptive state backend spec.

Produces the backend descriptor for ephemeral adaptive state stored inside the current process rather than an external datastore.

**Returns**

An adaptive backend spec using in-memory storage.

**Remarks**

This backend does not persist state across process restarts.

```ts
export declare function inMemoryBackend(): BackendSpec;
```

### `redisBackend`

Create a Redis-backed adaptive state backend spec.

Produces the backend descriptor expected by the adaptive plugin when state should be shared or persisted through Redis.

**Parameters**

* `url`: Redis connection URL for the backend.
* `keyPrefix`: Prefix applied to Redis keys.

**Returns**

An adaptive backend spec using Redis storage.

**Remarks**

The default key prefix namespaces runtime records under `nemo_relay:` unless a different prefix is supplied.

```ts
export declare function redisBackend(url: string, keyPrefix?: string): BackendSpec;
```

### `telemetryConfig`

Create adaptive telemetry settings with runtime defaults applied.

Merges caller-supplied overrides onto the built-in telemetry config shape used by the adaptive plugin.

**Parameters**

* `config`: Partial telemetry settings to override.

**Returns**

A normalized adaptive telemetry config object.

**Remarks**

An empty `learners` array is supplied by default so callers can append learner names without checking for initialization first.

```ts
export declare function telemetryConfig(config?: TelemetryConfig): TelemetryConfig;
```

### `adaptiveHintsConfig`

Create adaptive hint-injection settings with defaults applied.

Merges caller-supplied overrides onto the default config used by the adaptive hints injector.

**Parameters**

* `config`: Partial adaptive hints settings to override.

**Returns**

A normalized adaptive hints config object.

**Remarks**

By default the injector runs at priority `100`, preserves the rest of the chain, and writes hints to `nvext.agent_hints`.

```ts
export declare function adaptiveHintsConfig(config?: AdaptiveHintsConfig): AdaptiveHintsConfig;
```

### `toolParallelismConfig`

Create adaptive tool-parallelism settings with defaults applied.

Merges caller-supplied overrides onto the scheduler config shape used by the adaptive plugin's tool parallelism component.

**Parameters**

* `config`: Partial tool scheduling settings to override.

**Returns**

A normalized tool-parallelism config object.

**Remarks**

The default mode is `observe_only`, so recommendations are produced without changing execution behavior unless the caller opts in.

```ts
export declare function toolParallelismConfig(config?: ToolParallelismConfig): ToolParallelismConfig;
```

### `acgConfig`

Create adaptive cache-governor settings with defaults applied.

Merges caller-supplied overrides onto the Adaptive Cache Governor (ACG) config shape used by the adaptive plugin's LLM execution intercept.

**Parameters**

* `config`: Partial Adaptive Cache Governor (ACG) settings to override.

**Returns**

A normalized adaptive cache-governor config object.

**Remarks**

Nested `stability_thresholds` values are defaulted individually so callers can override only the thresholds they need.

```ts
export declare function acgConfig(config?: AcgConfig): AcgConfig;
```

### `ComponentSpec` function

Wrap adaptive config as a top-level component.

Produces the plugin component entry that can be inserted directly into `plugin.defaultConfig().components`.

**Parameters**

* `config`: Adaptive component configuration document.
* `options`: Optional component-level flags.

**Returns**

A plugin component spec for the adaptive plugin.

**Remarks**

Setting `options.enabled = false` keeps the config in the plugin document for validation while skipping runtime activation.

```ts
export declare function ComponentSpec(
  config: Config,
  options?: {
    enabled?: boolean;
```

### `validateConfig`

Validate an adaptive config document without constructing a runtime.

```ts
export declare function validateConfig(config: Config): ConfigReport;
```

### `buildCacheTelemetryEvent`

Build one adaptive cache telemetry event from normalized usage.

```ts
export declare function buildCacheTelemetryEvent(options: CacheTelemetryEventOptions): CacheTelemetryEvent | null;
```

### `setLatencySensitivity`

Set manual latency sensitivity on the current scope.

```ts
export declare function setLatencySensitivity(value: number): void;
```

## Constants

### `ADAPTIVE_PLUGIN_KIND`

```ts
export declare const ADAPTIVE_PLUGIN_KIND: 'adaptive';
```

## Re-exports

* `ConfigDiagnostic`
* `ConfigPolicy`
* `ConfigReport`