ReferenceAPIsNode.js Library Reference

Adaptive Helpers

View as Markdown

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

Import from nemo-relay-node/adaptive.

Adaptive plugin configuration helpers.

Interfaces

BackendSpec

Adaptive state backend selection.

1export interface BackendSpec {
2  kind: string;
3  config?: Record<string, Json>;
4}

StateConfig

Adaptive state configuration.

1export interface StateConfig {
2  backend: BackendSpec;
3}

TelemetryConfig

Built-in adaptive telemetry settings.

1export interface TelemetryConfig {
2  subscriber_name?: string;
3  learners?: string[];
4}

AdaptiveHintsConfig

Built-in adaptive hints injection settings.

1export interface AdaptiveHintsConfig {
2  priority?: number;
3  break_chain?: boolean;
4  inject_header?: boolean;
5  inject_body_path?: string;
6}

ToolParallelismConfig

Built-in adaptive tool scheduling settings.

1export interface ToolParallelismConfig {
2  priority?: number;
3  mode?: 'observe_only' | 'inject_hints' | 'schedule' | string;
4}

AcgStabilityThresholds

ACG prompt-stability classification thresholds.

1export interface AcgStabilityThresholds {
2  stable_threshold?: number;
3  semi_stable_threshold?: number;
4  min_observations_for_full_confidence?: number;
5}

AcgConfig

Adaptive cache-governor settings.

1export interface AcgConfig {
2  provider?: 'anthropic' | 'openai' | 'passthrough' | string;
3  observation_window?: number;
4  priority?: number;
5  stability_thresholds?: AcgStabilityThresholds;
6}

Config

Canonical config object for the top-level adaptive component.

1export interface Config {
2  version?: number;
3  agent_id?: string;
4  state?: StateConfig;
5  telemetry?: TelemetryConfig;
6  adaptive_hints?: AdaptiveHintsConfig;
7  tool_parallelism?: ToolParallelismConfig;
8  acg?: AcgConfig;
9  policy?: ConfigPolicy;
10}

ComponentSpec interface

Top-level adaptive component wrapper with fixed kind adaptive.

1export interface ComponentSpec {
2  kind: 'adaptive';
3  enabled?: boolean;
4  config: Config;
5}

CacheUsage

Normalized LLM token usage for cache telemetry.

1export interface CacheUsage {
2  prompt_tokens?: number;
3  completion_tokens?: number;
4  total_tokens?: number;
5  cache_read_tokens?: number;
6  cache_write_tokens?: number;
7  cost?: Json;
8}

AgentIdentity

Identity of the agent associated with cache telemetry.

1export interface AgentIdentity {
2  agent_id: string;
3  template_version: string;
4  toolset_hash: string;
5  model_family: string;
6  tenant_scope: string;
7}

CacheRequestFactsOptions

Input for building cache request facts.

1export interface CacheRequestFactsOptions {
2  provider: string;
3  requestId: string;
4  annotatedRequest: Json;
5  agentId: string;
6  timestamp?: string;
7}

CacheRequestFacts

Request-time facts used to classify cache misses.

1export interface CacheRequestFacts {
2  provider: string;
3  stable_prefix_length: number;
4  stable_prefix_tokens?: number;
5  required_min_tokens?: number;
6  first_mismatch_span_id?: string;
7  first_mismatch_sequence_index?: number;
8  expected_hash_prefix?: string;
9  actual_hash_prefix?: string;
10  retention_window_secs?: number;
11  observed_gap_secs?: number;
12  missing_facts?: string[];
13}

CacheTelemetryEventOptions

Input for building cache telemetry events.

1export interface CacheTelemetryEventOptions {
2  provider: 'anthropic' | 'openai' | string;
3  requestId: string;
4  usage?: CacheUsage | null;
5  requestFacts?: CacheRequestFacts | null;
6  agentId: string;
7  templateVersion: string;
8  toolsetHash: string;
9  modelFamily: string;
10  tenantScope: string;
11  timestamp?: string;
12}

CacheTelemetryEvent

Normalized adaptive cache telemetry event.

1export interface CacheTelemetryEvent {
2  request_id: string;
3  agent_identity: AgentIdentity;
4  cache_read_tokens: number;
5  cache_creation_tokens: number;
6  total_prompt_tokens: number;
7  hit_rate: number;
8  miss_reason?: Record<string, Json>;
9  miss_diagnosis?: Record<string, Json>;
10  provider: string;
11  timestamp: string;
12}

Classes

AdaptiveRuntime

Owned adaptive runtime outside the generic plugin system.

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

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.

1export 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.

1export 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.

1export 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.

1export 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.

1export 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.

1export 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.

1export 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.

1export declare function ComponentSpec(
2  config: Config,
3  options?: {
4    enabled?: boolean;

validateConfig

Validate an adaptive config document without constructing a runtime.

1export declare function validateConfig(config: Config): ConfigReport;

buildCacheTelemetryEvent

Build one adaptive cache telemetry event from normalized usage.

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

setLatencySensitivity

Set manual latency sensitivity on the current scope.

1export declare function setLatencySensitivity(value: number): void;

Constants

ADAPTIVE_PLUGIN_KIND

1export declare const ADAPTIVE_PLUGIN_KIND: 'adaptive';

Re-exports

  • ConfigDiagnostic
  • ConfigPolicy
  • ConfigReport