nemo_flow.adaptive#

Adaptive plugin configuration helpers.

Adaptive is configured as a single flat top-level plugin component. Hosted plugins remain separate top-level components managed through nemo_flow.plugin.

Attributes#

ADAPTIVE_PLUGIN_KIND

Classes#

`ConfigDiagnostic`	One adaptive validation diagnostic.
`ConfigReport`	Validation report for adaptive configuration.
`ConfigPolicy`	Policy for unsupported adaptive configuration.
`BackendSpec`	Adaptive state backend selection.
`StateConfig`	Adaptive state configuration.
`TelemetryConfig`	Built-in adaptive telemetry subscriber settings.
`AdaptiveHintsConfig`	Built-in adaptive hints injection settings.
`ToolParallelismConfig`	Built-in adaptive tool scheduling settings.
`AcgStabilityThresholds`	Prompt-stability classification thresholds for ACG.
`AcgConfig`	Adaptive Cache Governor settings.
`AdaptiveConfig`	Canonical config document for the top-level adaptive component.
`ComponentSpec`	Top-level adaptive component wrapper.

Functions#

set_latency_sensitivity(level)

Set a request-local latency-sensitivity hint.

Module Contents#

class nemo_flow.adaptive.ConfigDiagnostic#

Bases: _ConfigDiagnosticRequired

One adaptive validation diagnostic.

component: str#

field: str#

class nemo_flow.adaptive.ConfigReport#

Bases: TypedDict

Validation report for adaptive configuration.

diagnostics: list[ConfigDiagnostic]#

class nemo_flow.adaptive.ConfigPolicy#

Policy for unsupported adaptive configuration.

Parameters:

unknown_component – How to handle unknown component kinds.
unknown_field – How to handle unknown adaptive config fields.
unsupported_value – How to handle known fields with unsupported values.

unknown_component: nemo_flow.UnsupportedBehavior = 'warn'#

unknown_field: nemo_flow.UnsupportedBehavior = 'warn'#

unsupported_value: nemo_flow.UnsupportedBehavior = 'error'#

to_dict() → nemo_flow.JsonObject#: Serialize this policy to the canonical JSON object shape.

class nemo_flow.adaptive.BackendSpec#

Adaptive state backend selection.

Parameters:

kind – Backend kind string such as "in_memory" or "redis".
config – Backend-specific JSON object.

kind: str#

config: nemo_flow.JsonObject#

static in_memory() → BackendSpec#: Return an in-memory adaptive backend spec.

static redis(url: str, key_prefix: str = 'nemo_flow:') → BackendSpec#: Return a Redis adaptive backend spec.

to_dict() → nemo_flow.JsonObject#: Serialize this backend spec to the canonical JSON object shape.

class nemo_flow.adaptive.StateConfig#

Adaptive state configuration.

Parameters:: backend – State backend selection for adaptive features that persist or learn over time.

backend: BackendSpec#

to_dict() → nemo_flow.JsonObject#: Serialize this state config to the canonical JSON object shape.

class nemo_flow.adaptive.TelemetryConfig#

Built-in adaptive telemetry subscriber settings.

Parameters:

subscriber_name – Optional subscriber registration name override.
learners – Enabled learner identifiers.

subscriber_name: str | None = None#

learners: list[str] = []#

to_dict() → nemo_flow.JsonObject#: Serialize this telemetry config to the canonical JSON object shape.

class nemo_flow.adaptive.AdaptiveHintsConfig#

Built-in adaptive hints injection settings.

Parameters:

priority – Intercept priority. Lower values run first.
break_chain – Whether to stop later request intercepts after this one.
inject_header – Whether to inject the adaptive hints HTTP header.
inject_body_path – JSON body path used when injecting request-body hints.

priority: int = 100#

break_chain: bool = False#

inject_header: bool = True#

inject_body_path: str = 'nvext.agent_hints'#

to_dict() → nemo_flow.JsonObject#: Serialize this adaptive-hints config to the canonical JSON object shape.

class nemo_flow.adaptive.ToolParallelismConfig#

Built-in adaptive tool scheduling settings.

Parameters:

priority – Intercept priority. Lower values run first.
mode – Scheduling mode. "observe_only" records signals without changing behavior, while other modes enable stronger adaptive scheduling behavior.

priority: int = 100#

mode: Literal['observe_only', 'inject_hints', 'schedule'] = 'observe_only'#

to_dict() → nemo_flow.JsonObject#: Serialize this tool-parallelism config to the canonical JSON object shape.

class nemo_flow.adaptive.AcgStabilityThresholds#

Prompt-stability classification thresholds for ACG.

Parameters:

stable_threshold – Minimum effective score classified as stable.
semi_stable_threshold – Minimum effective score classified as semi-stable.
min_observations_for_full_confidence – Observation count required to reach full confidence.

stable_threshold: float = 0.95#

semi_stable_threshold: float = 0.5#

min_observations_for_full_confidence: int = 20#

to_dict() → nemo_flow.JsonObject#: Serialize these ACG stability thresholds to the canonical JSON object shape.

class nemo_flow.adaptive.AcgConfig#

Adaptive Cache Governor settings.

Parameters:

provider – Provider cache plugin name.
observation_window – Rolling PromptIR observation window size.
priority – LLM execution intercept priority.
stability_thresholds – Prompt-stability classification thresholds.

provider: Literal['anthropic', 'openai', 'passthrough'] = 'passthrough'#

observation_window: int = 100#

priority: int = 50#

stability_thresholds: AcgStabilityThresholds | None#

to_dict() → nemo_flow.JsonObject#: Serialize this ACG config to the canonical JSON object shape.

class nemo_flow.adaptive.AdaptiveConfig#

Canonical config document for the top-level adaptive component.

Parameters:

version – Adaptive config schema version.
agent_id – Optional explicit agent identifier for learned state.
state – Adaptive state backend configuration.
telemetry – Built-in adaptive telemetry settings.
adaptive_hints – Built-in LLM hint-injection settings.
tool_parallelism – Built-in tool scheduling settings.
acg – Adaptive Cache Governor settings.
policy – Unsupported-config policy applied within the adaptive config.

Behavior:: This document configures only the adaptive component. Plugins are configured separately through top-level plugin components.

version: int = 1#

agent_id: str | None = None#

state: StateConfig | None = None#

telemetry: TelemetryConfig | None = None#

adaptive_hints: AdaptiveHintsConfig | None = None#

tool_parallelism: ToolParallelismConfig | None = None#

acg: AcgConfig | None = None#

policy: ConfigPolicy#

to_dict() → nemo_flow.JsonObject#: Serialize this adaptive config to the canonical JSON object shape.

nemo_flow.adaptive.ADAPTIVE_PLUGIN_KIND = 'adaptive'#

class nemo_flow.adaptive.ComponentSpec#

Top-level adaptive component wrapper.

Parameters:

config – AdaptiveConfig or an equivalent JSON object.
enabled – Whether the adaptive component should be activated.

Behavior:: The component kind is always "adaptive".

config: AdaptiveConfig | nemo_flow.JsonObject#

enabled: bool = True#

to_dict() → nemo_flow.JsonObject#: Serialize this component to the canonical plugin shape.

nemo_flow.adaptive.set_latency_sensitivity(level: int) → None#

Set a request-local latency-sensitivity hint.

Parameters:: level – Positive integer sensitivity value for the current execution context.
Returns:: None.

Behavior:: This is an execution-time hint for the current request/scope context, not persistent adaptive configuration. The native adaptive layer stores this as a positive integer.