Adaptive Helpers

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

Import from nemo-relay-node/adaptive.

Adaptive plugin configuration helpers.

Interfaces

BackendSpec

Adaptive state backend selection.

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

StateConfig

Adaptive state configuration.

export interface StateConfig {
  backend: BackendSpec;
}

TelemetryConfig

Built-in adaptive telemetry settings.

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

AdaptiveHintsConfig

Built-in adaptive hints injection settings.

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

ToolParallelismConfig

Built-in adaptive tool scheduling settings.

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

AcgStabilityThresholds

ACG prompt-stability classification thresholds.

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

AcgConfig

Adaptive cache-governor settings.

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

ResponseCacheConfig

Opt-in LLM response cache (exact-match) settings.

export interface ResponseCacheConfig {
  ttlSeconds?: number;
  /**
   * Required non-empty cache trust domain. One configured cache must not span
   * mutually untrusted tenants or upstreams.
   */
  namespace?: string;
  priority?: number;
  bypassRate?: number;
  cacheNondeterministic?: boolean;
  keyStrategy?: string;
  headerAllowlist?: string[];
  backend?: BackendSpec;
}

Config

Canonical config object for the top-level adaptive component.

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

ComponentSpec interface

Top-level adaptive component wrapper with fixed kind adaptive.

export interface ComponentSpec {
  kind: 'adaptive';
  enabled?: boolean;
  config: AdaptivePluginConfig;
}

CacheUsage

Normalized LLM token usage for cache telemetry.

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.

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.

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

CacheRequestFacts

Request-time facts used to classify cache misses.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

responseCacheConfig

Create response-cache settings with defaults applied.

Merges caller-supplied overrides onto the opt-in LLM response-cache config shape (exact-match) used by the adaptive plugin. This is a section of the adaptive component, not a standalone plugin kind.

Parameters

• config: Partial response-cache settings to override.

Returns

A normalized response-cache config object.

Remarks

The default backend is in-memory; pass a backend (e.g. redisBackend(url)) for a shared cache. bypassRate defaults to 0.0, while caching nondeterministic requests is opt-in.

export declare function responseCacheConfig(config?: ResponseCacheConfig): ResponseCacheConfig;

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.

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

validateConfig

Validate an adaptive config document without constructing a runtime.

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

buildCacheTelemetryEvent

Build one adaptive cache telemetry event from normalized usage.

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

setLatencySensitivity

Set manual latency sensitivity on the current scope.

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

Constants

ADAPTIVE_PLUGIN_KIND

export declare const ADAPTIVE_PLUGIN_KIND: 'adaptive';

Re-exports

• ConfigDiagnostic
• ConfigPolicy
• ConfigReport