nemo_flow._native#

Stubs for the compiled nemo_flow._native extension module.

Summary:: Type and documentation surface for the compiled Rust extension.
Description:: The native module owns scope-stack state, lifecycle handles, event objects, observability exporters, codec bridges, middleware registries, plugin activation, and adaptive runtime hooks. Python wrapper modules generally provide user-facing names and examples, while this file records the native API shape that those wrappers import.
Exceptional flow:: Native functions may raise exceptions produced by the Rust runtime, by Python callbacks invoked from middleware, or by invalid JSON-like values. Individual declarations call out the main exceptional paths where the behavior is specific.

Classes#

`ScopeAttributes`	Bitflags describing scope properties.
`ToolAttributes`	Bitflags describing tool call properties.
`LLMAttributes`	Bitflags describing LLM call properties.
`ScopeType`	Enum identifying the kind of execution scope.
`ScopeHandle`	An active execution scope in the scope stack.
`ToolHandle`	An active tool call.
`LLMHandle`	An active LLM call.
`LLMRequest`	An LLM request carrying headers and a content payload.
`AnnotatedLLMRequest`	Structured view of an LLM request produced by a codec.
`AnnotatedLLMResponse`	Structured view of an LLM response produced by a response codec.
`ScopeEvent`	ATOF scope lifecycle event emitted to subscribers.
`MarkEvent`	ATOF point-in-time mark event emitted to subscribers.
`AtifExporter`	ATIF trajectory exporter that collects events and exports trajectories.
`ScopeStack`	An isolated scope stack for per-request or per-task isolation.
`LlmStream`	An async iterator of JSON chunks from a streaming LLM response.
`OpenTelemetryConfig`	Mutable configuration for `OpenTelemetrySubscriber`.
`OpenTelemetrySubscriber`	OpenTelemetry-backed NeMo Flow event subscriber.
`OpenInferenceConfig`	Mutable configuration for `OpenInferenceSubscriber`.
`OpenInferenceSubscriber`	OpenInference-backed NeMo Flow event subscriber.
`OpenAIChatCodec`	Built-in codec for OpenAI Chat Completions requests and responses.
`OpenAIResponsesCodec`	Built-in codec for OpenAI Responses requests and responses.
`AnthropicMessagesCodec`	Built-in codec for Anthropic Messages requests and responses.
`AdaptiveRuntime`	Hosted adaptive runtime bridge implemented by the native extension.
`PluginContext`	Native plugin registration context passed to plugin implementations.

Functions#

`create_scope_stack`()	Create a fresh native scope stack.
`set_thread_scope_stack`(stack)	Install a scope stack into native thread-local storage.
`sync_thread_scope_stack`(stack)	Synchronize thread-local storage without marking it explicitly active.
`scope_stack_active`()	Return whether native thread-local storage has an explicitly active stack.
`get_handle`()	Return the current top-of-stack scope handle.
`push_scope`(name, scope_type, *[, handle, attributes, ...])	Push a new scope onto the active native stack.
`pop_scope`(handle[, output, timestamp])	Pop a scope and emit its end event.
`event`(name, *[, handle, data, metadata, timestamp])	Emit a point-in-time mark event.
`tool_call`(name, args, *[, handle, attributes, data, ...])	Begin a manual tool lifecycle span.
`tool_call_end`(handle, result, *[, data, metadata, ...])	End a manual tool lifecycle span.
`tool_call_execute`(name, args, func, **kwargs)	Execute a tool through the managed native middleware pipeline.
`llm_call`(name, request, *[, handle, attributes, data, ...])	Begin a manual LLM lifecycle span.
`llm_call_end`(handle, response, *[, data, metadata, ...])	End a manual LLM lifecycle span.
`llm_call_execute`(name, request, func, **kwargs)	Execute a non-streaming LLM call through native middleware.
`llm_stream_call_execute`(name, request, func, ...)	Execute a streaming LLM call through native middleware.
`tool_request_intercepts`(name, args)	Run the registered tool request-intercept chain.
`tool_conditional_execution`(name, args)	Run tool conditional-execution guardrails.
`llm_request_intercepts`(name, request)	Run the registered LLM request-intercept chain.
`llm_conditional_execution`(request)	Run LLM conditional-execution guardrails.
`register_tool_sanitize_request_guardrail`(name, ...)	Register a global tool sanitize-request guardrail.
`deregister_tool_sanitize_request_guardrail`(name)	Remove a global tool sanitize-request guardrail by name.
`register_tool_sanitize_response_guardrail`(name, ...)	Register a global tool sanitize-response guardrail.
`deregister_tool_sanitize_response_guardrail`(name)	Remove a global tool sanitize-response guardrail by name.
`register_tool_conditional_execution_guardrail`(name, ...)	Register a global tool conditional-execution guardrail.
`deregister_tool_conditional_execution_guardrail`(name)	Remove a global tool conditional-execution guardrail by name.
`register_llm_sanitize_request_guardrail`(name, ...)	Register a global LLM sanitize-request guardrail.
`deregister_llm_sanitize_request_guardrail`(name)	Remove a global LLM sanitize-request guardrail by name.
`register_llm_sanitize_response_guardrail`(name, ...)	Register a global LLM sanitize-response guardrail.
`deregister_llm_sanitize_response_guardrail`(name)	Remove a global LLM sanitize-response guardrail by name.
`register_llm_conditional_execution_guardrail`(name, ...)	Register a global LLM conditional-execution guardrail.
`deregister_llm_conditional_execution_guardrail`(name)	Remove a global LLM conditional-execution guardrail by name.
`register_tool_request_intercept`(name, priority, ...)	Register a global tool request intercept.
`deregister_tool_request_intercept`(name)	Remove a global tool request intercept and return whether it existed.
`register_tool_execution_intercept`(name, priority, callable)	Register a global tool execution intercept.
`deregister_tool_execution_intercept`(name)	Remove a global tool execution intercept.
`register_llm_request_intercept`(name, priority, ...)	Register a global LLM request intercept.
`deregister_llm_request_intercept`(name)	Remove a global LLM request intercept.
`register_llm_execution_intercept`(name, priority, callable)	Register a global LLM execution intercept.
`deregister_llm_execution_intercept`(name)	Remove a global LLM execution intercept.
`register_llm_stream_execution_intercept`(name, ...)	Register a global LLM stream-execution intercept.
`deregister_llm_stream_execution_intercept`(name)	Remove a global LLM stream-execution intercept.
`register_subscriber`(name, callback)	Register a global event subscriber callback.
`deregister_subscriber`(name)	Remove a global event subscriber.
`scope_register_tool_sanitize_request_guardrail`(...)	Register a scope-local tool sanitize-request guardrail.
`scope_deregister_tool_sanitize_request_guardrail`(...)	Remove a scope-local tool sanitize-request guardrail.
`scope_register_tool_sanitize_response_guardrail`(...)	Register a scope-local tool sanitize-response guardrail.
`scope_deregister_tool_sanitize_response_guardrail`(...)	Remove a scope-local tool sanitize-response guardrail.
`scope_register_tool_conditional_execution_guardrail`(...)	Register a scope-local tool conditional-execution guardrail.
`scope_deregister_tool_conditional_execution_guardrail`(...)	Remove a scope-local tool conditional-execution guardrail.
`scope_register_tool_request_intercept`(scope_uuid, ...)	Register a scope-local tool request intercept.
`scope_deregister_tool_request_intercept`(scope_uuid, name)	Remove a scope-local tool request intercept.
`scope_register_tool_execution_intercept`(scope_uuid, ...)	Register a scope-local tool execution intercept.
`scope_deregister_tool_execution_intercept`(scope_uuid, name)	Remove a scope-local tool execution intercept.
`scope_register_llm_sanitize_request_guardrail`(...)	Register a scope-local LLM sanitize-request guardrail.
`scope_deregister_llm_sanitize_request_guardrail`(...)	Remove a scope-local LLM sanitize-request guardrail.
`scope_register_llm_sanitize_response_guardrail`(...)	Register a scope-local LLM sanitize-response guardrail.
`scope_deregister_llm_sanitize_response_guardrail`(...)	Remove a scope-local LLM sanitize-response guardrail.
`scope_register_llm_conditional_execution_guardrail`(...)	Register a scope-local LLM conditional-execution guardrail.
`scope_deregister_llm_conditional_execution_guardrail`(...)	Remove a scope-local LLM conditional-execution guardrail.
`scope_register_llm_request_intercept`(scope_uuid, name, ...)	Register a scope-local LLM request intercept.
`scope_deregister_llm_request_intercept`(scope_uuid, name)	Remove a scope-local LLM request intercept.
`scope_register_llm_execution_intercept`(scope_uuid, ...)	Register a scope-local LLM execution intercept.
`scope_deregister_llm_execution_intercept`(scope_uuid, name)	Remove a scope-local LLM execution intercept.
`scope_register_llm_stream_execution_intercept`(...)	Register a scope-local LLM stream-execution intercept.
`scope_deregister_llm_stream_execution_intercept`(...)	Remove a scope-local LLM stream-execution intercept.
`scope_register_subscriber`(scope_uuid, name, callback)	Register a scope-local event subscriber callback.
`scope_deregister_subscriber`(scope_uuid, name)	Remove a scope-local event subscriber.
`validate_plugin_config`(config)	Validate a plugin configuration without changing active runtime state.
`initialize_plugins`(config)	Validate and activate plugin configuration.
`clear_plugin_configuration`()	Clear active plugin configuration while preserving registered kinds.
`active_plugin_report`()	Return the active plugin report.
`list_plugin_kinds`()	Return registered custom plugin kind names.
`register_plugin`(plugin_kind, plugin)	Register a custom plugin implementation under a kind string.
`deregister_plugin`(plugin_kind)	Deregister a custom plugin kind.
`build_cache_telemetry_event`(args, *kwargs)	Build a normalized adaptive cache telemetry event.
`validate_adaptive_config`(config)	Validate adaptive configuration.
`set_latency_sensitivity`(level)	Set the process-local manual latency-sensitivity override.

Module Contents#

class nemo_flow._native.ScopeAttributes(value: int = 0)#

Bitflags describing scope properties.

Summary:: Compact flag container attached to scope handles and scope events.
Description:: ScopeAttributes values can be created from a raw integer bitmask and combined with | or intersected with &. The native runtime uses these flags to record semantic execution properties on scopes.
Flag constants:: PARALLEL indicates child work may execute in parallel. RELOCATABLE indicates work may move to another execution context.
Exceptional flow:: Construction or bit operations may raise native type errors when values cannot be converted to the expected bitmask representation.

PARALLEL: int#

RELOCATABLE: int#

property is_parallel: bool#: Return whether the PARALLEL flag is set.

property is_relocatable: bool#: Return whether the RELOCATABLE flag is set.

property value: int#: Return the raw integer bitmask.

class nemo_flow._native.ToolAttributes(value: int = 0)#

Bitflags describing tool call properties.

Summary:: Compact flag container attached to tool handles and tool events.
Description:: ToolAttributes records semantic properties of a tool call. Values can be created from raw integer bitmasks and combined with bit operators.
Flag constants:: REMOTE indicates that the tool call is remote.

REMOTE: int#

property is_remote: bool#: Return whether the REMOTE flag is set.

property value: int#: Return the raw integer bitmask.

class nemo_flow._native.LLMAttributes(value: int = 0)#

Bitflags describing LLM call properties.

Summary:: Compact flag container attached to LLM handles and LLM events.
Description:: LLMAttributes records semantic properties of an LLM call. Values can be created from raw integer bitmasks and combined with bit operators.
Flag constants:: STATEFUL indicates that the LLM call uses stateful context. STREAMING indicates that the LLM call returns a stream.

STATEFUL: int#

STREAMING: int#

property is_stateful: bool#: Return whether the STATEFUL flag is set.

property is_streaming: bool#: Return whether the STREAMING flag is set.

property value: int#: Return the raw integer bitmask.

class nemo_flow._native.ScopeType#

Enum identifying the kind of execution scope.

Summary:: Native scope category used when creating scopes.
Description:: The selected ScopeType is recorded on handles and emitted events so subscribers can distinguish agents, tools, LLM calls, guardrails, and other semantic units of work.

Agent: ScopeType#: Autonomous agent scope.

Function: ScopeType#: Generic function-call scope.

Tool: ScopeType#: Tool invocation scope.

Llm: ScopeType#: LLM call scope.

Retriever: ScopeType#: Retriever or RAG lookup scope.

Embedder: ScopeType#: Embedding model scope.

Reranker: ScopeType#: Reranking model scope.

Guardrail: ScopeType#: Guardrail evaluation scope.

Evaluator: ScopeType#: Evaluator or judge scope.

Custom: ScopeType#: User-defined scope type.

Unknown: ScopeType#: Unknown or unspecified scope type.

class nemo_flow._native.ScopeHandle#

An active execution scope in the scope stack.

Summary:: Immutable native handle returned by scope creation APIs.
Description:: A ScopeHandle identifies one pushed scope. Pass it back to pop_scope or wrapper APIs to close the scope, attach child work, or register scope-local middleware.
Exceptional flow:: Accessing properties may propagate native errors if the handle has been invalidated by the runtime.

property uuid: str#: Return the globally unique scope identifier.

property name: str#: Return the human-readable scope name.

property scope_type: ScopeType#: Return the semantic scope type.

property attributes: ScopeAttributes#: Return the scope attribute bitmask.

property parent_uuid: str | None#: Return the parent scope UUID, or None for a root scope.

property data: _Json | None#: Return application data captured on the scope, if any.

property metadata: _Json | None#: Return metadata captured on the scope, if any.

class nemo_flow._native.ToolHandle#

An active tool call.

Summary:: Native handle returned by manual tool-call start APIs.
Description:: Pass this handle to tool_call_end or wrapper APIs to close the tool lifecycle span and emit the corresponding end event.

property uuid: str#: Return the globally unique tool-call identifier.

property name: str#: Return the tool name.

property attributes: ToolAttributes#: Return the tool attribute bitmask.

property parent_uuid: str | None#: Return the parent scope UUID, if any.

property data: _Json | None#: Return application data captured on the tool call, if any.

property metadata: _Json | None#: Return metadata captured on the tool call, if any.

class nemo_flow._native.LLMHandle#

An active LLM call.

Summary:: Native handle returned by manual LLM-call start APIs.
Description:: Pass this handle to llm_call_end or wrapper APIs to close the LLM lifecycle span and emit the corresponding end event.

property uuid: str#: Return the globally unique LLM-call identifier.

property name: str#: Return the LLM provider or logical call name.

property attributes: LLMAttributes#: Return the LLM attribute bitmask.

property parent_uuid: str | None#: Return the parent scope UUID, if any.

property data: _Json | None#: Return application data captured on the LLM call, if any.

property metadata: _Json | None#: Return metadata captured on the LLM call, if any.

class nemo_flow._native.LLMRequest( headers: collections.abc.Mapping[str, _JsonValue], content: _JsonObject, )#

An LLM request carrying headers and a content payload.

Summary:: Provider request object passed through LLM middleware.
Description:: headers stores provider or transport metadata. content stores the JSON request body. Request intercepts and codecs consume this object to normalize, rewrite, and execute LLM calls.

property headers: _JsonObject#: Return the request headers as a JSON object.

property content: _JsonObject#: Return the request content body as a JSON object.

class nemo_flow._native.AnnotatedLLMRequest( messages: collections.abc.Sequence[collections.abc.Mapping[str, _JsonValue]], *, model: str | None = None, params: collections.abc.Mapping[str, _JsonValue] | None = None, tools: collections.abc.Sequence[collections.abc.Mapping[str, _JsonValue]] | None = None, tool_choice: str | collections.abc.Mapping[str, _JsonValue] | None = None, extra: collections.abc.Mapping[str, _JsonValue] | None = None, )#

Structured view of an LLM request produced by a codec.

Summary:: Provider-neutral request view for annotated LLM middleware.
Description:: Codecs decode provider-specific request bodies into this normalized shape so request intercepts can operate on messages, model name, parameters, tools, and extra provider fields.

property messages: list[_JsonObject]#: Return normalized message objects.

property model: str | None#: Return the normalized model name, if present.

property params: _JsonObject | None#: Return provider parameters, if present.

property tools: list[_JsonObject] | None#: Return normalized tool declarations, if present.

property tool_choice: str | _JsonObject | None#: Return the normalized tool-choice directive, if present.

property extra: _JsonObject#: Return provider-specific request fields.

system_prompt() → str | None#: Return the first normalized system prompt, if one is present.

last_user_message() → str | None#: Return the last normalized user message text, if one is present.

has_tool_calls() → bool#: Return whether the normalized request includes tool declarations.

class nemo_flow._native.AnnotatedLLMResponse#

Structured view of an LLM response produced by a response codec.

Summary:: Provider-neutral response view for LLM end-event annotations.
Description:: Response codecs decode provider responses into this normalized shape so subscribers can inspect model, text, tool-call, usage, and provider-specific fields consistently.

property id: str | None#: Return the provider response identifier, if present.

property model: str | None#: Return the provider model name, if present.

property message: _Json | None#: Return the normalized primary message payload, if present.

property tool_calls: list[_JsonObject] | None#: Return normalized tool-call payloads, if present.

property finish_reason: str | None#: Return the provider finish reason, if present.

property usage: _JsonObject | None#: Return normalized usage accounting, if present.

property api_specific: _JsonObject | None#: Return provider-specific response fields, if present.

property extra: _JsonObject#: Return additional normalized response fields.

response_text() → str | None#: Return extracted response text, if present.

has_tool_calls() → bool#: Return whether the response contains tool-call payloads.

class nemo_flow._native.ScopeEvent#

ATOF scope lifecycle event emitted to subscribers.

Summary:: Event emitted when a scope, tool call, or LLM call starts or ends.
Description:: Scope events contain hierarchy identifiers, semantic category data, user payloads, metadata, and optional normalized LLM request/response annotations.

property kind: Literal['scope']#: Return the discriminant value "scope".

property scope_category: Literal['start', 'end']#: Return whether this is a start or end lifecycle event.

property atof_version: str#: Return the ATOF schema version used for this event.

property parent_uuid: str | None#: Return the parent event UUID, if present.

property uuid: str#: Return the event UUID.

property timestamp: str#: Return the event timestamp as an RFC 3339 string.

property name: str#: Return the event or scope name.

property data: _Json | None#: Return application data attached to the event, if any.

property metadata: _Json | None#: Return metadata attached to the event, if any.

property attributes: list[str]#: Return stringified semantic attributes attached to the event.

property category: str#: Return the semantic event category.

property category_profile: _JsonObject | None#: Return category-specific profile data, if any.

property data_schema: _JsonObject | None#: Return a schema descriptor for data, if one is present.

property annotated_request: AnnotatedLLMRequest | None#: Return the normalized LLM request annotation, if present.

property annotated_response: AnnotatedLLMResponse | None#: Return the normalized LLM response annotation, if present.

class nemo_flow._native.MarkEvent#

ATOF point-in-time mark event emitted to subscribers.

Summary:: Event emitted for standalone marks and guardrail rejections.
Description:: Mark events record a named point in time under the current scope hierarchy. They do not have a start/end lifecycle pair.

property kind: Literal['mark']#: Return the discriminant value "mark".

property atof_version: str#: Return the ATOF schema version used for this event.

property parent_uuid: str | None#: Return the parent event UUID, if present.

property uuid: str#: Return the event UUID.

property timestamp: str#: Return the event timestamp as an RFC 3339 string.

property name: str#: Return the mark event name.

property data: _Json | None#: Return application data attached to the event, if any.

property metadata: _Json | None#: Return metadata attached to the event, if any.

property category: str | None#: Return the semantic mark category, if present.

property category_profile: _JsonObject | None#: Return category-specific profile data, if any.

property data_schema: _JsonObject | None#: Return a schema descriptor for data, if one is present.

class nemo_flow._native.AtifExporter( session_id: str, agent_name: str, agent_version: str, *, model_name: str | None = None, tool_definitions: list[_JsonObject] | None = None, extra: _Json | None = None, )#

ATIF trajectory exporter that collects events and exports trajectories.

Summary:: Subscriber implementation that accumulates lifecycle events.
Description:: Register the exporter under a subscriber name, run application code, and export the collected event set as an ATIF trajectory dictionary or JSON string.

register(name: str) → None#: Register this exporter as a global event subscriber.

deregister(name: str) → bool#: Deregister this exporter and return whether a subscriber was removed.

export() → _JsonObject#: Return collected events as an ATIF trajectory object.

export_json() → str#: Return collected events as an ATIF trajectory JSON string.

clear() → None#: Clear collected events without changing subscriber registration.

class nemo_flow._native.ScopeStack#

An isolated scope stack for per-request or per-task isolation.

Summary:: Native stack object containing active scope hierarchy state.
Description:: Scope stacks are installed into Python context variables or native thread-local storage so nested scope, tool, and LLM events share the correct hierarchy.

class nemo_flow._native.LlmStream#

An async iterator of JSON chunks from a streaming LLM response.

Summary:: Native stream returned by managed streaming LLM execution.
Description:: The object can be awaited by compatibility wrappers and iterated with async for to receive post-intercept JSON chunks.

class nemo_flow._native.OpenTelemetryConfig#

Mutable configuration for OpenTelemetrySubscriber.

Summary:: Native OpenTelemetry exporter configuration object.
Description:: Configure transport, endpoint, service identity, exporter timeout, headers, and resource attributes before constructing a subscriber.

transport: str#

endpoint: str | None#

service_name: str#

service_namespace: str | None#

service_version: str | None#

instrumentation_scope: str#

timeout_millis: int#

property headers: dict[str, str]#: Return additional exporter headers.

property resource_attributes: dict[str, str]#: Return additional OpenTelemetry resource attributes.

set_header(key: str, value: str) → None#: Set one exporter header key/value pair.

set_resource_attribute(key: str, value: str) → None#: Set one OpenTelemetry resource attribute key/value pair.

class nemo_flow._native.OpenTelemetrySubscriber(config: OpenTelemetryConfig)#

OpenTelemetry-backed NeMo Flow event subscriber.

Summary:: Native subscriber that exports lifecycle events as OpenTelemetry spans.
Description:: Register the subscriber under a name to receive runtime events. Flush or shut it down before process exit when deterministic export is required.

register(name: str) → None#: Register the subscriber under name.

deregister(name: str) → bool#: Deregister name and return whether it existed.

force_flush() → None#: Flush pending telemetry through the configured exporter.

shutdown() → None#: Shut down native OpenTelemetry resources.

class nemo_flow._native.OpenInferenceConfig#

Mutable configuration for OpenInferenceSubscriber.

Summary:: Native OpenInference exporter configuration object.
Description:: Configure transport, endpoint, service identity, exporter timeout, headers, and resource attributes before constructing a subscriber.

transport: str#

endpoint: str | None#

service_name: str#

service_namespace: str | None#

service_version: str | None#

instrumentation_scope: str#

timeout_millis: int#

property headers: dict[str, str]#: Return additional exporter headers.

property resource_attributes: dict[str, str]#: Return additional OpenInference resource attributes.

set_header(key: str, value: str) → None#: Set one exporter header key/value pair.

set_resource_attribute(key: str, value: str) → None#: Set one OpenInference resource attribute key/value pair.

class nemo_flow._native.OpenInferenceSubscriber(config: OpenInferenceConfig)#

OpenInference-backed NeMo Flow event subscriber.

Summary:: Native subscriber that exports lifecycle events as OpenInference spans.
Description:: Register the subscriber under a name to receive runtime events. Flush or shut it down before process exit when deterministic export is required.

register(name: str) → None#: Register the subscriber under name.

deregister(name: str) → bool#: Deregister name and return whether it existed.

force_flush() → None#: Flush pending telemetry through the configured exporter.

shutdown() → None#: Shut down native OpenInference resources.

class nemo_flow._native.OpenAIChatCodec#

Built-in codec for OpenAI Chat Completions requests and responses.

Summary:: Native codec bridge for Chat Completions payloads.

decode(request: LLMRequest) → AnnotatedLLMRequest#: Decode a Chat Completions request into a normalized request view.

encode( annotated: AnnotatedLLMRequest, original: LLMRequest, ) → LLMRequest#: Encode a normalized request back into Chat Completions shape.

decode_response(response: _Json) → AnnotatedLLMResponse#: Decode a Chat Completions response into a normalized response view.

class nemo_flow._native.OpenAIResponsesCodec#

Built-in codec for OpenAI Responses requests and responses.

Summary:: Native codec bridge for OpenAI Responses payloads.

decode(request: LLMRequest) → AnnotatedLLMRequest#: Decode a Responses request into a normalized request view.

encode( annotated: AnnotatedLLMRequest, original: LLMRequest, ) → LLMRequest#: Encode a normalized request back into Responses shape.

decode_response(response: _Json) → AnnotatedLLMResponse#: Decode a Responses response into a normalized response view.

class nemo_flow._native.AnthropicMessagesCodec#

Built-in codec for Anthropic Messages requests and responses.

Summary:: Native codec bridge for Anthropic Messages payloads.

decode(request: LLMRequest) → AnnotatedLLMRequest#: Decode an Anthropic Messages request into a normalized request view.

encode( annotated: AnnotatedLLMRequest, original: LLMRequest, ) → LLMRequest#: Encode a normalized request back into Anthropic Messages shape.

decode_response(response: _Json) → AnnotatedLLMResponse#: Decode an Anthropic response into a normalized response view.

class nemo_flow._native.AdaptiveRuntime(config: object)#

Hosted adaptive runtime bridge implemented by the native extension.

Summary:: Native runtime for configured adaptive components.
Description:: AdaptiveRuntime validates and owns adaptive state for external integrations that need lifecycle-managed adaptive features.

async register() → None#: Validate and register configured adaptive components.

deregister() → None#: Deregister adaptive components owned by this runtime.

async shutdown() → None#: Deregister components and release owned native resources.

wait_for_idle() → None#: Block until the adaptive telemetry drain has processed pending work.

report() → _JsonObject#: Return the runtime validation report.

bind_scope(scope_handle: ScopeHandle) → None#: Bind runtime ACG behavior to an active scope handle.

build_cache_request_facts( *, provider: str, request_id: str, annotated_request: object, agent_id: str, timestamp: str | None = None, ) → _JsonObject | None#

Build cache-diagnostics facts for a provider request.

Parameters:

provider – Logical provider name.
request_id – Stable request identifier.
annotated_request – Normalized request or equivalent mapping.
agent_id – Agent identifier associated with the request.
timestamp – Optional RFC 3339 timestamp override.

Returns:

Derived cache facts, or None when there is not enough state to produce a valid event.

class nemo_flow._native.PluginContext#

Native plugin registration context passed to plugin implementations.

Summary:: Internal bridge used by the native plugin system.
Description:: Python plugin protocols expose the public shape. The native class exists for runtime registration callbacks.

nemo_flow._native.create_scope_stack() → ScopeStack#

Create a fresh native scope stack.

Returns:: A new ScopeStack that is not installed into any Python context or native thread-local slot.

Exceptional flow:: Native allocation errors propagate unchanged.

nemo_flow._native.set_thread_scope_stack(stack: ScopeStack) → None#

Install a scope stack into native thread-local storage.

Parameters:: stack – Scope stack to use for subsequent native calls on this thread.
Returns:: None.

nemo_flow._native.sync_thread_scope_stack(stack: ScopeStack) → None#

Synchronize thread-local storage without marking it explicitly active.

Parameters:: stack – Scope stack to synchronize into the native thread-local slot.
Returns:: None.

nemo_flow._native.scope_stack_active() → bool#: Return whether native thread-local storage has an explicitly active stack.

nemo_flow._native.get_handle() → ScopeHandle#

Return the current top-of-stack scope handle.

Returns:: The active ScopeHandle.

Exceptional flow:: Raises a native runtime error if the active stack has no current scope.

nemo_flow._native.push_scope( name: str, scope_type: ScopeType, *, handle: ScopeHandle | None = None, attributes: ScopeAttributes | None = None, data: _Json | None = None, metadata: _Json | None = None, input: _Json | None = None, timestamp: datetime.datetime | None = None, ) → ScopeHandle#

Push a new scope onto the active native stack.

Parameters:

name – Human-readable scope name.
scope_type – Semantic scope type.
handle – Optional parent scope handle. When omitted, the current top-of-stack scope becomes the parent.
attributes – Optional scope attribute bitflags.
data – Optional JSON application payload stored on the scope handle.
metadata – Optional JSON metadata recorded on the start event.
input – Optional JSON payload exported as semantic scope input on the start event.
timestamp – Optional timezone-aware datetime recorded as the handle start time and on the start event. When omitted, the current runtime time is used.

Returns:

Handle for the newly pushed scope.

Exceptional flow:: Raises native runtime errors for invalid parent handles, invalid JSON payloads, invalid timestamp types, naive datetimes, or inactive stack state.

nemo_flow._native.pop_scope( handle: ScopeHandle, output: _Json | None = None, timestamp: datetime.datetime | None = None, ) → None#

Pop a scope and emit its end event.

Parameters:

handle – Handle returned by push_scope.
output – Optional semantic output payload recorded on the end event.
timestamp – Optional timezone-aware datetime recorded on the end event. When omitted, the runtime default end timestamp is used.

Returns:

None.

Exceptional flow:: Raises native runtime errors if handle is not the current scope or if output cannot be converted to JSON-compatible data. Raises for invalid timestamp types or naive datetimes.

nemo_flow._native.event( name: str, *, handle: ScopeHandle | None = None, data: _Json | None = None, metadata: _Json | None = None, timestamp: datetime.datetime | None = None, ) → None#

Emit a point-in-time mark event.

Parameters:

name – Mark event name.
handle – Optional parent scope handle. When omitted, the current top-of-stack scope becomes the parent.
data – Optional JSON data payload recorded on the mark event.
metadata – Optional JSON metadata payload recorded on the mark event.
timestamp – Optional timezone-aware datetime recorded on the mark event. When omitted, the current runtime time is used.

Returns:

None.

Exceptional flow:: Raises for invalid JSON payloads, invalid timestamp types, or naive datetimes.

Begin a manual tool lifecycle span.

Parameters:

name – Tool name.
args – JSON-compatible tool arguments recorded on the start event after sanitize-request guardrails.
handle – Optional parent scope handle. When omitted, the current top-of-stack scope becomes the parent.
attributes – Optional tool attribute bitflags.
data – Optional JSON application payload stored on the tool handle.
metadata – Optional JSON metadata recorded on the start event.
tool_call_id – Optional provider-specific tool-call correlation ID.
timestamp – Optional timezone-aware datetime recorded on the start event. When omitted, the current runtime time is used.

Returns:

Tool handle that must be passed to tool_call_end.

Exceptional flow:: Raises for invalid JSON payloads, invalid timestamp types, or naive datetimes.

nemo_flow._native.tool_call_end( handle: ToolHandle, result: _Json, *, data: _Json | None = None, metadata: _Json | None = None, timestamp: datetime.datetime | None = None, ) → None#

End a manual tool lifecycle span.

Parameters:

handle – Tool handle returned by tool_call.
result – JSON-compatible tool result recorded on the end event after sanitize-response guardrails unless it sanitizes to JSON null.
data – Optional JSON payload used when the sanitized result is JSON null.
metadata – Optional JSON metadata recorded on the end event.
timestamp – Optional timezone-aware datetime recorded on the end event. When omitted, the runtime default end timestamp is used.

Returns:

None.

Exceptional flow:: Raises for invalid JSON payloads, invalid timestamp types, or naive datetimes.

nemo_flow._native.tool_call_execute(

name: str,

args: _Json,

func: collections.abc.Callable[[_Json], collections.abc.Awaitable[_Json]],

**kwargs: object,

) → collections.abc.Awaitable[_Json]#

Execute a tool through the managed native middleware pipeline.

Parameters:

name – Tool name.
args – Initial JSON-compatible tool arguments.
func – Awaitable tool implementation called with final arguments.
**kwargs – Optional parent handle, attributes, data, and metadata.

Returns:

Awaitable that resolves to the JSON-compatible tool result.

Exceptional flow:: Conditional guardrails may reject execution. Callback and native errors propagate through the returned awaitable.

nemo_flow._native.llm_call( name: str, request: LLMRequest, *, handle: ScopeHandle | None = None, attributes: LLMAttributes | None = None, data: _Json | None = None, metadata: _Json | None = None, model_name: str | None = None, timestamp: datetime.datetime | None = None, ) → LLMHandle#

Begin a manual LLM lifecycle span.

Parameters:

name – Provider or logical call name.
request – LLM request recorded on the start event after sanitize-request guardrails.
handle – Optional parent scope handle. When omitted, the current top-of-stack scope becomes the parent.
attributes – Optional LLM attribute bitflags.
data – Optional JSON application payload stored on the LLM handle.
metadata – Optional JSON metadata recorded on the start event.
model_name – Optional normalized model name recorded in the LLM event category profile.
timestamp – Optional timezone-aware datetime recorded on the start event. When omitted, the current runtime time is used.

Returns:

LLM handle that must be passed to llm_call_end.

Exceptional flow:: Raises for invalid timestamp types or naive datetimes.

nemo_flow._native.llm_call_end( handle: LLMHandle, response: _Json, *, data: _Json | None = None, metadata: _Json | None = None, timestamp: datetime.datetime | None = None, ) → None#

End a manual LLM lifecycle span.

Parameters:

handle – LLM handle returned by llm_call.
response – JSON-compatible LLM response recorded on the end event after sanitize-response guardrails unless it sanitizes to JSON null.
data – Optional JSON payload used when the sanitized response is JSON null.
metadata – Optional JSON metadata recorded on the end event.
timestamp – Optional timezone-aware datetime recorded on the end event. When omitted, the runtime default end timestamp is used.

Returns:

None.

Exceptional flow:: Raises for invalid JSON payloads, invalid timestamp types, or naive datetimes.

nemo_flow._native.llm_call_execute(

name: str,

request: LLMRequest,

func: collections.abc.Callable[[LLMRequest], collections.abc.Awaitable[_Json]],

**kwargs: object,

) → collections.abc.Awaitable[_Json]#

Execute a non-streaming LLM call through native middleware.

Parameters:

name – Provider or logical call name.
request – Initial LLM request.
func – Awaitable provider implementation called with the final request.
**kwargs – Optional parent handle, attributes, data, metadata, model name, request codec, and response codec.

Returns:

Awaitable that resolves to a JSON-compatible LLM response.

Exceptional flow:: Conditional guardrails may reject execution. Request intercept, execution intercept, codec, callback, and native errors propagate through the returned awaitable.

nemo_flow._native.llm_stream_call_execute(

name: str,

request: LLMRequest,

func: collections.abc.Callable[[LLMRequest], collections.abc.AsyncIterator[_Json]],

collector: collections.abc.Callable[[_Json], None],

finalizer: collections.abc.Callable[[], _Json],

**kwargs: object,

) → LlmStream#

Execute a streaming LLM call through native middleware.

Parameters:

name – Provider or logical call name.
request – Initial LLM request.
func – Provider implementation returning an async iterator of chunks.
collector – Callback invoked for each post-intercept chunk.
finalizer – Callback that returns the aggregate final response.
**kwargs – Optional parent handle, attributes, data, metadata, model name, request codec, and response codec.

Returns:

LlmStream async iterator of JSON-compatible chunks.

Exceptional flow:: Conditional guardrails may reject execution. Streaming callback, collector, finalizer, codec, and native errors propagate while awaiting or iterating the stream.

nemo_flow._native.tool_request_intercepts(name: str, args: _Json) → _Json#

Run the registered tool request-intercept chain.

Parameters:

name – Tool name used to select and invoke intercept callbacks.
args – Current JSON-compatible tool arguments.

Returns:

Transformed tool arguments after all applicable request intercepts.

Exceptional flow:: Callback exceptions and native middleware errors propagate unchanged.

nemo_flow._native.tool_conditional_execution(name: str, args: _Json) → None#

Run tool conditional-execution guardrails.

Parameters:

name – Tool name used to select and invoke guardrail callbacks.
args – Current JSON-compatible tool arguments.

Returns:

None when all guardrails allow execution.

Exceptional flow:: Raises a native rejection error when a guardrail returns a rejection message. Callback exceptions also propagate.

nemo_flow._native.llm_request_intercepts(name: str, request: LLMRequest) → LLMRequest#

Run the registered LLM request-intercept chain.

Parameters:

name – Provider or logical LLM call name.
request – Current LLM request.

Returns:

Transformed request after all applicable request intercepts.

Exceptional flow:: Callback exceptions and native middleware errors propagate unchanged.

nemo_flow._native.llm_conditional_execution(request: LLMRequest) → None#

Run LLM conditional-execution guardrails.

Parameters:: request – LLM request to evaluate.
Returns:: None when all guardrails allow execution.

Exceptional flow:: Raises a native rejection error when a guardrail returns a rejection message. Callback exceptions also propagate.

nemo_flow._native.register_tool_sanitize_request_guardrail( name: str, priority: int, guardrail: _ToolSanitizeGuardrail, ) → None#

Register a global tool sanitize-request guardrail.

Parameters:

name – Unique guardrail name.
priority – Execution order; lower values run first.
guardrail – Callback that returns the request payload recorded on start events.

Returns:

None.

nemo_flow._native.deregister_tool_sanitize_request_guardrail(name: str) → bool#

Remove a global tool sanitize-request guardrail by name.

Parameters:: name – Guardrail name to remove.
Returns:: True if a guardrail was removed, otherwise False.

nemo_flow._native.register_tool_sanitize_response_guardrail( name: str, priority: int, guardrail: _ToolSanitizeGuardrail, ) → None#

Register a global tool sanitize-response guardrail.

Parameters:

name – Unique guardrail name.
priority – Execution order; lower values run first.
guardrail – Callback that returns the response payload recorded on end events.

Returns:

None.

nemo_flow._native.deregister_tool_sanitize_response_guardrail(name: str) → bool#

Remove a global tool sanitize-response guardrail by name.

Returns:: True if a guardrail was removed, otherwise False.

nemo_flow._native.register_tool_conditional_execution_guardrail( name: str, priority: int, guardrail: _ToolConditionalExecutionGuardrail, ) → None#

Register a global tool conditional-execution guardrail.

Parameters:

name – Unique guardrail name.
priority – Execution order; lower values run first.
guardrail – Callback that returns None to allow execution or a rejection message to block execution.

Returns:

None.

nemo_flow._native.deregister_tool_conditional_execution_guardrail(name: str) → bool#

Remove a global tool conditional-execution guardrail by name.

Returns:: True if a guardrail was removed, otherwise False.

nemo_flow._native.register_llm_sanitize_request_guardrail( name: str, priority: int, guardrail: _LlmSanitizeRequestGuardrail, ) → None#

Register a global LLM sanitize-request guardrail.

Parameters:

name – Unique guardrail name.
priority – Execution order; lower values run first.
guardrail – Callback that returns the request recorded on start events.

Returns:

None.

nemo_flow._native.deregister_llm_sanitize_request_guardrail(name: str) → bool#

Remove a global LLM sanitize-request guardrail by name.

Returns:: True if a guardrail was removed, otherwise False.

nemo_flow._native.register_llm_sanitize_response_guardrail( name: str, priority: int, guardrail: _LlmSanitizeResponseGuardrail, ) → None#

Register a global LLM sanitize-response guardrail.

Parameters:

name – Unique guardrail name.
priority – Execution order; lower values run first.
guardrail – Callback that returns the response object recorded on end events.

Returns:

None.

nemo_flow._native.deregister_llm_sanitize_response_guardrail(name: str) → bool#

Remove a global LLM sanitize-response guardrail by name.

Returns:: True if a guardrail was removed, otherwise False.

nemo_flow._native.register_llm_conditional_execution_guardrail( name: str, priority: int, guardrail: _LlmConditionalExecutionGuardrail, ) → None#

Register a global LLM conditional-execution guardrail.

Parameters:

name – Unique guardrail name.
priority – Execution order; lower values run first.
guardrail – Callback that returns None to allow execution or a rejection message to block execution.

Returns:

None.

nemo_flow._native.deregister_llm_conditional_execution_guardrail(name: str) → bool#

Remove a global LLM conditional-execution guardrail by name.

Returns:: True if a guardrail was removed, otherwise False.

nemo_flow._native.register_tool_request_intercept( name: str, priority: int, break_chain: bool, callable: _ToolRequestIntercept, ) → None#

Register a global tool request intercept.

Parameters:

name – Unique intercept name.
priority – Execution order; lower values run first.
break_chain – Whether later request intercepts should be skipped after this one runs.
callable – Callback that rewrites tool arguments.

Returns:

None.

nemo_flow._native.deregister_tool_request_intercept(name: str) → bool#: Remove a global tool request intercept and return whether it existed.

nemo_flow._native.register_tool_execution_intercept( name: str, priority: int, callable: _ToolExecutionIntercept, ) → None#

Register a global tool execution intercept.

Parameters:

name – Unique intercept name.
priority – Execution order; lower values run first.
callable – Middleware callback that may call or short-circuit next.

Returns:

None.

nemo_flow._native.deregister_tool_execution_intercept(name: str) → bool#

Remove a global tool execution intercept.

Returns:: True if an intercept was removed, otherwise False.

nemo_flow._native.register_llm_request_intercept( name: str, priority: int, break_chain: bool, callable: _LlmRequestIntercept, ) → None#

Register a global LLM request intercept.

Parameters:

name – Unique intercept name.
priority – Execution order; lower values run first.
break_chain – Whether lower-priority request intercepts are skipped after this callback.
callable – Callback that rewrites the raw and optional annotated request.

Returns:

None.

nemo_flow._native.deregister_llm_request_intercept(name: str) → bool#

Remove a global LLM request intercept.

Returns:: True if an intercept was removed, otherwise False.

nemo_flow._native.register_llm_execution_intercept( name: str, priority: int, callable: _LlmExecutionIntercept, ) → None#

Register a global LLM execution intercept.

Parameters:

name – Unique intercept name.
priority – Execution order; lower values run first.
callable – Middleware callback that may call or short-circuit next.

Returns:

None.

nemo_flow._native.deregister_llm_execution_intercept(name: str) → bool#

Remove a global LLM execution intercept.

Returns:: True if an intercept was removed, otherwise False.

nemo_flow._native.register_llm_stream_execution_intercept( name: str, priority: int, callable: _LlmStreamExecutionIntercept, ) → None#

Register a global LLM stream-execution intercept.

Parameters:

name – Unique intercept name.
priority – Execution order; lower values run first.
callable – Streaming middleware callback.

Returns:

None.

nemo_flow._native.deregister_llm_stream_execution_intercept(name: str) → bool#

Remove a global LLM stream-execution intercept.

Returns:: True if an intercept was removed, otherwise False.

nemo_flow._native.register_subscriber( name: str, callback: collections.abc.Callable[[ScopeEvent | MarkEvent], None], ) → None#

Register a global event subscriber callback.

Parameters:

name – Unique subscriber name.
callback – Function invoked for each emitted scope or mark event.

Returns:

None.

Exceptional flow:: Subscriber callback exceptions propagate from the lifecycle operation that emitted the event.

nemo_flow._native.deregister_subscriber(name: str) → bool#

Remove a global event subscriber.

Returns:: True if a subscriber was removed, otherwise False.

nemo_flow._native.scope_register_tool_sanitize_request_guardrail( scope_uuid: str, name: str, priority: int, guardrail: _ToolSanitizeGuardrail, ) → None#

Register a scope-local tool sanitize-request guardrail.

Parameters:

scope_uuid – UUID of the owning scope.
name – Unique guardrail name within that scope.
priority – Execution order; lower values run first.
guardrail – Callback used while the owning scope is active.

Returns:

None.

nemo_flow._native.scope_deregister_tool_sanitize_request_guardrail( scope_uuid: str, name: str, ) → bool#

Remove a scope-local tool sanitize-request guardrail.

Returns:: True if a guardrail was removed, otherwise False.

nemo_flow._native.scope_register_tool_sanitize_response_guardrail( scope_uuid: str, name: str, priority: int, guardrail: _ToolSanitizeGuardrail, ) → None#

Register a scope-local tool sanitize-response guardrail.

Parameters:

scope_uuid – UUID of the owning scope.
name – Unique guardrail name within that scope.
priority – Execution order; lower values run first.
guardrail – Callback used while the owning scope is active.

Returns:

None.

nemo_flow._native.scope_deregister_tool_sanitize_response_guardrail( scope_uuid: str, name: str, ) → bool#

Remove a scope-local tool sanitize-response guardrail.

Returns:: True if a guardrail was removed, otherwise False.

nemo_flow._native.scope_register_tool_conditional_execution_guardrail( scope_uuid: str, name: str, priority: int, guardrail: _ToolConditionalExecutionGuardrail, ) → None#

Register a scope-local tool conditional-execution guardrail.

Parameters:

scope_uuid – UUID of the owning scope.
name – Unique guardrail name within that scope.
priority – Execution order; lower values run first.
guardrail – Callback used while the owning scope is active.

Returns:

None.

nemo_flow._native.scope_deregister_tool_conditional_execution_guardrail( scope_uuid: str, name: str, ) → bool#

Remove a scope-local tool conditional-execution guardrail.

Returns:: True if a guardrail was removed, otherwise False.

nemo_flow._native.scope_register_tool_request_intercept( scope_uuid: str, name: str, priority: int, break_chain: bool, callable: _ToolRequestIntercept, ) → None#

Register a scope-local tool request intercept.

Parameters:

scope_uuid – UUID of the owning scope.
name – Unique intercept name within that scope.
priority – Execution order; lower values run first.
break_chain – Whether lower-priority request intercepts are skipped.
callable – Callback used while the owning scope is active.

Returns:

None.

nemo_flow._native.scope_deregister_tool_request_intercept( scope_uuid: str, name: str, ) → bool#

Remove a scope-local tool request intercept.

Returns:: True if an intercept was removed, otherwise False.

nemo_flow._native.scope_register_tool_execution_intercept( scope_uuid: str, name: str, priority: int, callable: _ToolExecutionIntercept, ) → None#

Register a scope-local tool execution intercept.

Parameters:

scope_uuid – UUID of the owning scope.
name – Unique intercept name within that scope.
priority – Execution order; lower values run first.
callable – Middleware callback used while the owning scope is active.

Returns:

None.

nemo_flow._native.scope_deregister_tool_execution_intercept( scope_uuid: str, name: str, ) → bool#

Remove a scope-local tool execution intercept.

Returns:: True if an intercept was removed, otherwise False.

nemo_flow._native.scope_register_llm_sanitize_request_guardrail( scope_uuid: str, name: str, priority: int, guardrail: _LlmSanitizeRequestGuardrail, ) → None#

Register a scope-local LLM sanitize-request guardrail.

Parameters:

scope_uuid – UUID of the owning scope.
name – Unique guardrail name within that scope.
priority – Execution order; lower values run first.
guardrail – Callback used while the owning scope is active.

Returns:

None.

nemo_flow._native.scope_deregister_llm_sanitize_request_guardrail( scope_uuid: str, name: str, ) → bool#

Remove a scope-local LLM sanitize-request guardrail.

Returns:: True if a guardrail was removed, otherwise False.

nemo_flow._native.scope_register_llm_sanitize_response_guardrail( scope_uuid: str, name: str, priority: int, guardrail: _LlmSanitizeResponseGuardrail, ) → None#

Register a scope-local LLM sanitize-response guardrail.

Parameters:

scope_uuid – UUID of the owning scope.
name – Unique guardrail name within that scope.
priority – Execution order; lower values run first.
guardrail – Callback used while the owning scope is active.

Returns:

None.

nemo_flow._native.scope_deregister_llm_sanitize_response_guardrail( scope_uuid: str, name: str, ) → bool#

Remove a scope-local LLM sanitize-response guardrail.

Returns:: True if a guardrail was removed, otherwise False.

nemo_flow._native.scope_register_llm_conditional_execution_guardrail( scope_uuid: str, name: str, priority: int, guardrail: _LlmConditionalExecutionGuardrail, ) → None#

Register a scope-local LLM conditional-execution guardrail.

Parameters:

scope_uuid – UUID of the owning scope.
name – Unique guardrail name within that scope.
priority – Execution order; lower values run first.
guardrail – Callback used while the owning scope is active.

Returns:

None.

nemo_flow._native.scope_deregister_llm_conditional_execution_guardrail( scope_uuid: str, name: str, ) → bool#

Remove a scope-local LLM conditional-execution guardrail.

Returns:: True if a guardrail was removed, otherwise False.

nemo_flow._native.scope_register_llm_request_intercept( scope_uuid: str, name: str, priority: int, break_chain: bool, callable: _LlmRequestIntercept, ) → None#

Register a scope-local LLM request intercept.

Parameters:

scope_uuid – UUID of the owning scope.
name – Unique intercept name within that scope.
priority – Execution order; lower values run first.
break_chain – Whether lower-priority request intercepts are skipped.
callable – Callback used while the owning scope is active.

Returns:

None.

nemo_flow._native.scope_deregister_llm_request_intercept( scope_uuid: str, name: str, ) → bool#

Remove a scope-local LLM request intercept.

Returns:: True if an intercept was removed, otherwise False.

nemo_flow._native.scope_register_llm_execution_intercept( scope_uuid: str, name: str, priority: int, callable: _LlmExecutionIntercept, ) → None#

Register a scope-local LLM execution intercept.

Parameters:

scope_uuid – UUID of the owning scope.
name – Unique intercept name within that scope.
priority – Execution order; lower values run first.
callable – Middleware callback used while the owning scope is active.

Returns:

None.

nemo_flow._native.scope_deregister_llm_execution_intercept( scope_uuid: str, name: str, ) → bool#

Remove a scope-local LLM execution intercept.

Returns:: True if an intercept was removed, otherwise False.

nemo_flow._native.scope_register_llm_stream_execution_intercept( scope_uuid: str, name: str, priority: int, callable: _LlmStreamExecutionIntercept, ) → None#

Register a scope-local LLM stream-execution intercept.

Parameters:

scope_uuid – UUID of the owning scope.
name – Unique intercept name within that scope.
priority – Execution order; lower values run first.
callable – Streaming middleware callback used while the owning scope is active.

Returns:

None.

nemo_flow._native.scope_deregister_llm_stream_execution_intercept( scope_uuid: str, name: str, ) → bool#

Remove a scope-local LLM stream-execution intercept.

Returns:: True if an intercept was removed, otherwise False.

nemo_flow._native.scope_register_subscriber( scope_uuid: str, name: str, callback: collections.abc.Callable[[ScopeEvent | MarkEvent], None], ) → None#

Register a scope-local event subscriber callback.

Parameters:

scope_uuid – UUID of the owning scope.
name – Unique subscriber name within that scope.
callback – Event callback used while the owning scope is active.

Returns:

None.

nemo_flow._native.scope_deregister_subscriber(scope_uuid: str, name: str) → bool#

Remove a scope-local event subscriber.

Returns:: True if a subscriber was removed, otherwise False.

nemo_flow._native.validate_plugin_config(config: object) → _JsonObject#

Validate a plugin configuration without changing active runtime state.

Parameters:: config – Plugin configuration object or equivalent mapping.
Returns:: Validation report as a JSON object.

Exceptional flow:: Raises native conversion or validation errors for malformed config.

nemo_flow._native.initialize_plugins( config: object, ) → collections.abc.Awaitable[_JsonObject]#

Validate and activate plugin configuration.

Parameters:: config – Plugin configuration object or equivalent mapping.
Returns:: Awaitable resolving to the activation report.

Exceptional flow:: Activation errors propagate through the awaitable. The native runtime rolls back partial registration when possible.

nemo_flow._native.clear_plugin_configuration() → None#

Clear active plugin configuration while preserving registered kinds.

Returns:: None.

Exceptional flow:: Native cleanup errors propagate unchanged.

nemo_flow._native.active_plugin_report() → _JsonObject | None#

Return the active plugin report.

Returns:: Report JSON object for the last active configuration, or None if no plugin configuration is active.

nemo_flow._native.list_plugin_kinds() → list[str]#

Return registered custom plugin kind names.

Returns:: Sorted plugin kind names known to the native registry.

nemo_flow._native.register_plugin(plugin_kind: str, plugin: object) → None#

Register a custom plugin implementation under a kind string.

Parameters:

plugin_kind – Unique top-level component kind string.
plugin – Plugin implementation object.

Returns:

None.

Exceptional flow:: Raises native registry errors for duplicate or invalid registrations.

nemo_flow._native.deregister_plugin(plugin_kind: str) → bool#

Deregister a custom plugin kind.

Parameters:: plugin_kind – Kind string to remove.
Returns:: True if a plugin kind was removed, otherwise False.

nemo_flow._native.build_cache_telemetry_event(

*args: object,

**kwargs: object,

) → _JsonObject#

Build a normalized adaptive cache telemetry event.

Parameters:

*args – Positional values accepted by the native adaptive helper.
**kwargs – Provider, request, usage, template, model, tenant, and timestamp values accepted by the native adaptive helper.

Returns:

Cache telemetry event as a JSON object.

nemo_flow._native.validate_adaptive_config(config: object) → _JsonObject#

Validate adaptive configuration.

Parameters:: config – Adaptive configuration object or equivalent mapping.
Returns:: Validation report as a JSON object.

Exceptional flow:: Native conversion and validation errors propagate unchanged.

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

Set the process-local manual latency-sensitivity override.

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

Exceptional flow:: Native validation errors propagate when level is unsupported.