# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

"""Stubs for the compiled ``nemo_relay._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.
"""

from __future__ import annotations

from collections.abc import AsyncIterator, Awaitable, Callable, Generator, Mapping, Sequence
from datetime import datetime
from typing import ClassVar, Literal, Optional, TypeAlias, TypedDict

_JsonPrimitive: TypeAlias = str | int | float | bool | None
_JsonValue: TypeAlias = _JsonPrimitive | list["_JsonValue"] | dict[str, "_JsonValue"]
_JsonObject: TypeAlias = dict[str, _JsonValue]
_Json: TypeAlias = _JsonValue
_MessageContent: TypeAlias = str | Sequence[Mapping[str, _JsonValue]]

def _shutdown_default_logging() -> None: ...

class _EventSanitizeFields(TypedDict):
    data: _Json | None
    category_profile: _JsonObject | None
    metadata: _Json | None

_ToolSanitizeGuardrail: TypeAlias = Callable[[str, _Json], _Json | Awaitable[_Json]]
_ToolConditionalExecutionGuardrail: TypeAlias = Callable[[str, _Json], Optional[str] | Awaitable[Optional[str]]]
_LlmSanitizeRequestGuardrail: TypeAlias = Callable[
    ["LLMRequest", "LlmSanitizeRequestContext"],
    Optional["LLMRequest"] | Awaitable[Optional["LLMRequest"]],
]
_LlmSanitizeResponseGuardrail: TypeAlias = Callable[
    [_Json, "LlmSanitizeResponseContext"],
    Optional[_Json] | Awaitable[Optional[_Json]],
]
_EventSanitizeGuardrail: TypeAlias = Callable[
    [ScopeEvent | MarkEvent, _EventSanitizeFields],
    _EventSanitizeFields | Awaitable[_EventSanitizeFields],
]
_LlmConditionalExecutionGuardrail: TypeAlias = Callable[["LLMRequest"], Optional[str] | Awaitable[Optional[str]]]
_ToolRequestIntercept: TypeAlias = Callable[[str, _Json], _Json | Awaitable[_Json]]
_ToolExecutionIntercept: TypeAlias = Callable[
    [str, _Json, Callable[[_Json], Awaitable[_Json]]],
    "ToolExecutionInterceptOutcome | Awaitable[ToolExecutionInterceptOutcome]",
]
_LlmRequestIntercept: TypeAlias = Callable[
    [str, "LLMRequest", "AnnotatedLLMRequest | None"],
    "LLMRequestInterceptOutcome | Awaitable[LLMRequestInterceptOutcome]",
]
_LlmExecutionIntercept: TypeAlias = Callable[
    [str, "LLMRequest", Callable[["LLMRequest"], Awaitable[_Json]]],
    _Json | Awaitable[_Json],
]
_LlmStreamExecutionIntercept: TypeAlias = Callable[
    ["LLMRequest", Callable[["LLMRequest"], Awaitable[AsyncIterator[_Json]]]],
    AsyncIterator[_Json] | Awaitable[AsyncIterator[_Json]],
]

class LlmCodecIdentity:
    """Structured identity of the active managed LLM codec."""

    @property
    def kind(self) -> Literal["none", "builtin", "runtime", "opaque"]: ...
    @property
    def id(self) -> str | None: ...

class LlmSanitizeRequestContext:
    """Per-call context passed to an LLM request sanitizer callback."""

    @property
    def codec(self) -> LlmCodecIdentity: ...
    def resolve_codec(self) -> LlmSanitizeRequestCodec | None: ...

class LlmSanitizeResponseContext:
    """Per-call context passed to an LLM response sanitizer callback."""

    @property
    def codec(self) -> LlmCodecIdentity: ...
    def resolve_codec(self) -> LlmSanitizeResponseCodec | None: ...

class LlmSanitizeRequestCodec:
    def decode(self, request: LLMRequest) -> AnnotatedLLMRequest: ...
    def encode(self, annotated: AnnotatedLLMRequest, original: LLMRequest) -> LLMRequest: ...

class LlmSanitizeResponseCodec:
    def decode_response(self, response: _Json) -> AnnotatedLLMResponse: ...

class ScopeAttributes:
    """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

    def __init__(self, value: int = 0) -> None:
        """Create a scope-attribute bitmask.

        Args:
            value: Raw integer bitmask. Defaults to no flags.

        Returns:
            ``None``.
        """
        ...
    @property
    def is_parallel(self) -> bool:
        """Return whether the ``PARALLEL`` flag is set."""
        ...
    @property
    def is_relocatable(self) -> bool:
        """Return whether the ``RELOCATABLE`` flag is set."""
        ...
    @property
    def value(self) -> int:
        """Return the raw integer bitmask."""
        ...
    def __or__(self, other: ScopeAttributes) -> ScopeAttributes:
        """Return the union of two scope-attribute bitmasks."""
        ...
    def __and__(self, other: ScopeAttributes) -> ScopeAttributes:
        """Return the intersection of two scope-attribute bitmasks."""
        ...

class ToolAttributes:
    """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

    def __init__(self, value: int = 0) -> None:
        """Create a tool-attribute bitmask.

        Args:
            value: Raw integer bitmask. Defaults to no flags.

        Returns:
            ``None``.
        """
        ...
    @property
    def is_remote(self) -> bool:
        """Return whether the ``REMOTE`` flag is set."""
        ...
    @property
    def value(self) -> int:
        """Return the raw integer bitmask."""
        ...
    def __or__(self, other: ToolAttributes) -> ToolAttributes:
        """Return the union of two tool-attribute bitmasks."""
        ...
    def __and__(self, other: ToolAttributes) -> ToolAttributes:
        """Return the intersection of two tool-attribute bitmasks."""
        ...

class LLMAttributes:
    """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

    def __init__(self, value: int = 0) -> None:
        """Create an LLM-attribute bitmask.

        Args:
            value: Raw integer bitmask. Defaults to no flags.

        Returns:
            ``None``.
        """
        ...
    @property
    def is_stateful(self) -> bool:
        """Return whether the ``STATEFUL`` flag is set."""
        ...
    @property
    def is_streaming(self) -> bool:
        """Return whether the ``STREAMING`` flag is set."""
        ...
    @property
    def value(self) -> int:
        """Return the raw integer bitmask."""
        ...
    def __or__(self, other: LLMAttributes) -> LLMAttributes:
        """Return the union of two LLM-attribute bitmasks."""
        ...
    def __and__(self, other: LLMAttributes) -> LLMAttributes:
        """Return the intersection of two LLM-attribute bitmasks."""
        ...

class 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 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
    def uuid(self) -> str:
        """Return the globally unique scope identifier."""
        ...
    @property
    def name(self) -> str:
        """Return the human-readable scope name."""
        ...
    @property
    def scope_type(self) -> ScopeType:
        """Return the semantic scope type."""
        ...
    @property
    def attributes(self) -> ScopeAttributes:
        """Return the scope attribute bitmask."""
        ...
    @property
    def parent_uuid(self) -> Optional[str]:
        """Return the parent scope UUID, or ``None`` for a root scope."""
        ...
    @property
    def data(self) -> Optional[_Json]:
        """Return application data captured on the scope, if any."""
        ...
    @property
    def metadata(self) -> Optional[_Json]:
        """Return metadata captured on the scope, if any."""
        ...

class 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
    def uuid(self) -> str:
        """Return the globally unique tool-call identifier."""
        ...
    @property
    def name(self) -> str:
        """Return the tool name."""
        ...
    @property
    def attributes(self) -> ToolAttributes:
        """Return the tool attribute bitmask."""
        ...
    @property
    def parent_uuid(self) -> Optional[str]:
        """Return the parent scope UUID, if any."""
        ...
    @property
    def data(self) -> Optional[_Json]:
        """Return application data captured on the tool call, if any."""
        ...
    @property
    def metadata(self) -> Optional[_Json]:
        """Return metadata captured on the tool call, if any."""
        ...

class 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
    def uuid(self) -> str:
        """Return the globally unique LLM-call identifier."""
        ...
    @property
    def name(self) -> str:
        """Return the LLM provider or logical call name."""
        ...
    @property
    def attributes(self) -> LLMAttributes:
        """Return the LLM attribute bitmask."""
        ...
    @property
    def parent_uuid(self) -> Optional[str]:
        """Return the parent scope UUID, if any."""
        ...
    @property
    def data(self) -> Optional[_Json]:
        """Return application data captured on the LLM call, if any."""
        ...
    @property
    def metadata(self) -> Optional[_Json]:
        """Return metadata captured on the LLM call, if any."""
        ...

class LLMRequest:
    """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.
    """

    def __init__(self, headers: Mapping[str, _JsonValue], content: _JsonObject) -> None:
        """Create an LLM request.

        Args:
            headers: Header-like metadata mapping.
            content: JSON object payload sent to the provider.

        Returns:
            ``None``.

        Exceptional flow:
            Raises native conversion errors if ``headers`` or ``content`` are
            not JSON-compatible mappings.
        """
        ...
    @property
    def headers(self) -> _JsonObject:
        """Return the request headers as a JSON object."""
        ...
    @property
    def content(self) -> _JsonObject:
        """Return the request content body as a JSON object."""
        ...

class PendingMarkSpec:
    """A runtime-owned mark specification returned by lifecycle middleware."""
    def __init__(
        self,
        name: str,
        category: Optional[str] = ...,
        category_profile: Optional[_Json] = ...,
        data: Optional[_Json] = ...,
        metadata: Optional[_Json] = ...,
    ) -> None: ...
    @property
    def name(self) -> str: ...
    @property
    def category(self) -> Optional[str]: ...
    @property
    def category_profile(self) -> Optional[_Json]: ...
    @property
    def data(self) -> Optional[_Json]: ...
    @property
    def metadata(self) -> Optional[_Json]: ...

class LLMRequestInterceptOutcome:
    """Canonical result returned by an LLM request intercept."""
    def __init__(
        self,
        request: LLMRequest,
        annotated_request: Optional[AnnotatedLLMRequest] = ...,
        pending_marks: list[PendingMarkSpec] = ...,
        optimization_contributions: Optional[Sequence[Mapping[str, _JsonValue]]] = ...,
    ) -> None: ...
    @property
    def request(self) -> LLMRequest: ...
    @property
    def annotated_request(self) -> Optional[AnnotatedLLMRequest]: ...
    @property
    def pending_marks(self) -> list[PendingMarkSpec]: ...
    @property
    def optimization_contributions(self) -> list[_JsonObject]:
        """Return ordered plugin-neutral optimization contribution objects."""
        ...

class ToolExecutionInterceptOutcome:
    """Canonical result returned by a tool execution intercept.

    ``result`` is passed to the remaining middleware and application.
    ``pending_marks`` are Relay-owned lifecycle metadata emitted after the
    tool-end event and are not included in the application-visible result.
    """
    def __init__(
        self,
        result: _Json,
        pending_marks: list[PendingMarkSpec] = ...,
    ) -> None: ...
    @property
    def result(self) -> _Json: ...
    @property
    def pending_marks(self) -> list[PendingMarkSpec]: ...

class AnnotatedLLMRequest:
    """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.
    """

    def __init__(
        self,
        messages: Sequence[Mapping[str, _JsonValue]],
        *,
        instructions: Optional[_MessageContent] = None,
        model: Optional[str] = None,
        params: Optional[Mapping[str, _JsonValue]] = None,
        tools: Optional[Sequence[Mapping[str, _JsonValue]]] = None,
        tool_choice: Optional[str | Mapping[str, _JsonValue]] = None,
        api_specific: Optional[Mapping[str, _JsonValue]] = None,
        extra: Optional[Mapping[str, _JsonValue]] = None,
    ) -> None:
        """Create a normalized LLM request view.

        Args:
            messages: Provider-normalized message objects.
            instructions: Optional provider-level instructions.
            model: Optional model name.
            params: Optional provider parameters.
            tools: Optional tool declarations.
            tool_choice: Optional tool-selection directive.
            api_specific: Optional tagged provider-specific request fields.
            extra: Optional unknown future top-level fields.

        Returns:
            ``None``.

        Exceptional flow:
            Raises conversion errors when JSON-like inputs cannot be converted
            to the native normalized representation.
        """
        ...
    @property
    def messages(self) -> list[_JsonObject]:
        """Return normalized message objects."""
        ...
    @messages.setter
    def messages(self, value: Sequence[Mapping[str, _JsonValue]]) -> None:
        """Replace normalized message objects."""
        ...
    @property
    def instructions(self) -> Optional[_MessageContent]:
        """Return provider-level instructions, if present."""
        ...
    @instructions.setter
    def instructions(self, value: Optional[_MessageContent]) -> None:
        """Set or clear provider-level instructions."""
        ...
    @property
    def model(self) -> Optional[str]:
        """Return the normalized model name, if present."""
        ...
    @model.setter
    def model(self, value: Optional[str]) -> None:
        """Set or clear the normalized model name."""
        ...
    @property
    def params(self) -> Optional[_JsonObject]:
        """Return provider parameters, if present."""
        ...
    @params.setter
    def params(self, value: Optional[Mapping[str, _JsonValue]]) -> None:
        """Set or clear provider parameters."""
        ...
    @property
    def tools(self) -> Optional[list[_JsonObject]]:
        """Return normalized tool declarations, if present."""
        ...
    @tools.setter
    def tools(self, value: Optional[Sequence[Mapping[str, _JsonValue]]]) -> None:
        """Set or clear normalized tool declarations."""
        ...
    @property
    def tool_choice(self) -> Optional[str | _JsonObject]:
        """Return the normalized tool-choice directive, if present."""
        ...
    @tool_choice.setter
    def tool_choice(self, value: Optional[str | Mapping[str, _JsonValue]]) -> None:
        """Set or clear the normalized tool-choice directive."""
        ...
    @property
    def api_specific(self) -> Optional[_JsonObject]:
        """Return tagged provider-specific request fields, if present."""
        ...
    @api_specific.setter
    def api_specific(self, value: Optional[Mapping[str, _JsonValue]]) -> None:
        """Set or clear tagged provider-specific request fields."""
        ...
    @property
    def extra(self) -> _JsonObject:
        """Return unknown future top-level request fields."""
        ...
    @extra.setter
    def extra(self, value: Mapping[str, _JsonValue]) -> None:
        """Replace unknown future top-level request fields."""
        ...
    def system_prompt(self) -> Optional[str]:
        """Return the first normalized system prompt, if one is present."""
        ...
    def last_user_message(self) -> Optional[str]:
        """Return the last normalized user message text, if one is present."""
        ...
    def has_tool_calls(self) -> bool:
        """Return whether the normalized request includes tool declarations."""
        ...

class 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.
    """

    def __init__(
        self,
        id: Optional[str] = None,
        model: Optional[str] = None,
        message: Optional[_JsonValue] = None,
        tool_calls: Optional[Sequence[Mapping[str, _JsonValue]]] = None,
        finish_reason: Optional[str | Mapping[str, _JsonValue]] = None,
        usage: Optional[Mapping[str, _JsonValue]] = None,
        api_specific: Optional[Mapping[str, _JsonValue]] = None,
        extra: Optional[Mapping[str, _JsonValue]] = None,
    ) -> None:
        """Create a normalized LLM response view.

        Args:
            id: Optional provider response identifier.
            model: Optional model that served the response.
            message: Optional normalized assistant response content.
            tool_calls: Optional normalized response tool-call payloads.
            finish_reason: Optional normalized finish reason.
            usage: Optional normalized usage accounting.
            api_specific: Optional API-specific response fields.
            extra: Optional additional response fields.

        Returns:
            ``None``.

        Exceptional flow:
            Raises conversion errors when JSON-like inputs cannot be converted
            to the native normalized representation.
        """
        ...
    @property
    def id(self) -> Optional[str]:
        """Return the provider response identifier, if present."""
        ...
    @property
    def model(self) -> Optional[str]:
        """Return the provider model name, if present."""
        ...
    @property
    def message(self) -> Optional[_Json]:
        """Return the normalized primary message payload, if present."""
        ...
    @property
    def tool_calls(self) -> Optional[list[_JsonObject]]:
        """Return normalized tool-call payloads, if present."""
        ...
    @property
    def finish_reason(self) -> Optional[str]:
        """Return the provider finish reason, if present."""
        ...
    @property
    def usage(self) -> Optional[_JsonObject]:
        """Return normalized usage accounting, if present."""
        ...
    @property
    def optimization_summary(self) -> Optional[_JsonObject]:
        """Return Relay's close-time optimization accounting, if present."""
        ...
    @property
    def api_specific(self) -> Optional[_JsonObject]:
        """Return provider-specific response fields, if present."""
        ...
    @property
    def extra(self) -> _JsonObject:
        """Return additional normalized response fields."""
        ...
    def response_text(self) -> Optional[str]:
        """Return extracted response text, if present."""
        ...
    def has_tool_calls(self) -> bool:
        """Return whether the response contains tool-call payloads."""
        ...

class 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
    def kind(self) -> Literal["scope"]:
        """Return the discriminant value ``"scope"``."""
        ...
    @property
    def scope_category(self) -> Literal["start", "end"]:
        """Return whether this is a start or end lifecycle event."""
        ...
    @property
    def atof_version(self) -> str:
        """Return the ATOF schema version used for this event."""
        ...
    @property
    def parent_uuid(self) -> Optional[str]:
        """Return the parent event UUID, if present."""
        ...
    @property
    def uuid(self) -> str:
        """Return the event UUID."""
        ...
    @property
    def timestamp(self) -> str:
        """Return the event timestamp as an RFC 3339 string."""
        ...
    @property
    def name(self) -> str:
        """Return the event or scope name."""
        ...
    @property
    def data(self) -> Optional[_Json]:
        """Return application data attached to the event, if any."""
        ...
    @property
    def metadata(self) -> Optional[_Json]:
        """Return metadata attached to the event, if any."""
        ...
    @property
    def attributes(self) -> list[str]:
        """Return stringified semantic attributes attached to the event."""
        ...
    @property
    def category(self) -> str:
        """Return the semantic event category."""
        ...
    @property
    def category_profile(self) -> Optional[_JsonObject]:
        """Return category-specific profile data, if any."""
        ...
    @property
    def data_schema(self) -> Optional[_JsonObject]:
        """Return a schema descriptor for ``data``, if one is present."""
        ...
    @property
    def annotated_request(self) -> Optional[AnnotatedLLMRequest]:
        """Return the normalized LLM request annotation, if present."""
        ...
    @property
    def annotated_response(self) -> Optional[AnnotatedLLMResponse]:
        """Return the normalized LLM response annotation, if present."""
        ...
    def to_dict(self) -> _JsonObject:
        """Return this event as the canonical subscriber JSON dictionary."""
        ...
    def to_json(self) -> str:
        """Return this event as canonical subscriber JSON."""
        ...

class 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
    def kind(self) -> Literal["mark"]:
        """Return the discriminant value ``"mark"``."""
        ...
    @property
    def atof_version(self) -> str:
        """Return the ATOF schema version used for this event."""
        ...
    @property
    def parent_uuid(self) -> Optional[str]:
        """Return the parent event UUID, if present."""
        ...
    @property
    def uuid(self) -> str:
        """Return the event UUID."""
        ...
    @property
    def timestamp(self) -> str:
        """Return the event timestamp as an RFC 3339 string."""
        ...
    @property
    def name(self) -> str:
        """Return the mark event name."""
        ...
    @property
    def data(self) -> Optional[_Json]:
        """Return application data attached to the event, if any."""
        ...
    @property
    def metadata(self) -> Optional[_Json]:
        """Return metadata attached to the event, if any."""
        ...
    @property
    def category(self) -> Optional[str]:
        """Return the semantic mark category, if present."""
        ...
    @property
    def category_profile(self) -> Optional[_JsonObject]:
        """Return category-specific profile data, if any."""
        ...
    @property
    def data_schema(self) -> Optional[_JsonObject]:
        """Return a schema descriptor for ``data``, if one is present."""
        ...
    def to_dict(self) -> _JsonObject:
        """Return this event as the canonical subscriber JSON dictionary."""
        ...
    def to_json(self) -> str:
        """Return this event as canonical subscriber JSON."""
        ...

class AtifExporter:
    """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.
    """

    def __init__(
        self,
        session_id: str,
        agent_name: str,
        agent_version: str,
        *,
        model_name: Optional[str] = None,
        tool_definitions: Optional[list[_JsonObject]] = None,
        extra: Optional[_Json] = None,
    ) -> None:
        """Create an ATIF exporter.

        Args:
            session_id: Stable session identifier for exported trajectories.
            agent_name: Human-readable agent name.
            agent_version: Agent version string.
            model_name: Optional primary model name.
            tool_definitions: Optional tool schema objects.
            extra: Optional additional JSON-compatible trajectory metadata.

        Returns:
            ``None``.
        """
        ...
    def register(self, name: str) -> None:
        """Register this exporter as a global event subscriber."""
        ...
    def deregister(self, name: str) -> bool:
        """Deregister this exporter and return whether a subscriber was removed."""
        ...
    def export(self) -> _JsonObject:
        """Return collected events as an ATIF trajectory object."""
        ...
    def export_json(self) -> str:
        """Return collected events as an ATIF trajectory JSON string."""
        ...
    def clear(self) -> None:
        """Clear collected events without changing subscriber registration."""
        ...

class AtofExporterMode:
    """File write mode for ``AtofExporter``."""

    Append: ClassVar[AtofExporterMode]
    Overwrite: ClassVar[AtofExporterMode]

class AtofStreamSinkConfig:
    """One stream sink for raw ATOF events."""

    url: str
    transport: str
    headers: dict[str, str]
    header_env: dict[str, str]
    timeout_millis: int
    field_name_policy: str

    def __init__(
        self,
        url: str,
        *,
        transport: str = "http_post",
        headers: dict[str, str] | None = None,
        header_env: dict[str, str] | None = None,
        timeout_millis: int = 3000,
        field_name_policy: str = "preserve",
    ) -> None:
        """Create an ATOF stream sink config.

        ``headers=None`` is converted to an empty dict; the instance field is
        always non-optional.
        """

class AtofExporterConfig:
    """One tagged sink configuration for the manual ATOF exporter."""

    sink_type: str
    output_directory: str
    mode: AtofExporterMode
    filename: str
    url: str
    transport: str
    headers: dict[str, str]
    header_env: dict[str, str]
    timeout_millis: int
    field_name_policy: str

    def __init__(self) -> None:
        """Create an ATOF exporter config with native defaults."""
        ...

class AtofExporter:
    """Single-sink exporter that writes or streams raw ATOF events."""

    def __init__(self, config: AtofExporterConfig) -> None:
        """Create an ATOF JSONL exporter from config."""
        ...
    @property
    def path(self) -> str | None:
        """Return the JSONL output path, or ``None`` for a stream sink."""
        ...
    def register(self, name: str) -> None:
        """Register the exporter under ``name``."""
        ...
    def deregister(self, name: str) -> bool:
        """Deregister ``name`` and return whether it existed."""
        ...
    def force_flush(self) -> None:
        """Flush the exporter.

        Outside subscriber and middleware callbacks, wait for queued
        subscriber delivery, then flush the file sink or ask the stream sink
        to drain up to its timeout. A stream timeout is logged and does not by
        itself return an error.
        """
        ...
    def shutdown(self) -> None:
        """Flush the exporter and shut it down.

        Outside subscriber and middleware callbacks, wait for queued
        subscriber delivery, then flush the file sink or ask the stream sink
        to drain and close up to its timeout. A stream timeout is logged and
        does not by itself return an error.
        """
        ...

class 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.
    """

    def __repr__(self) -> str:
        """Return a debug representation of the native scope stack."""
        ...

class 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.
    """

    def __await__(self) -> Generator[object, None, LlmStream]:
        """Return an awaitable that resolves to this stream."""
        ...
    def __aiter__(self) -> AsyncIterator[_Json]:
        """Return the async iterator for stream chunks."""
        ...
    async def __anext__(self) -> _Json:
        """Return the next JSON chunk or raise ``StopAsyncIteration``."""
        ...
    async def aclose(self) -> None:
        """Cancel the producer and release native stream resources."""
        ...

class 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
    type: Literal["full", "gen_ai", "openinference"]
    endpoint: str
    service_name: str
    service_namespace: Optional[str]
    service_version: Optional[str]
    instrumentation_scope: str
    timeout_millis: int
    mark_projection: Literal["inherit", "event", "tool"]
    mark_exclude_names: list[str]

    def __init__(
        self,
        otel_type: Literal["full", "gen_ai", "openinference"],
        endpoint: str,
    ) -> None:
        """Create a typed OpenTelemetry config for the required endpoint."""
        ...
    @property
    def headers(self) -> dict[str, str]:
        """Return additional exporter headers."""
        ...
    @headers.setter
    def headers(self, value: dict[str, str]) -> None:
        """Replace additional exporter headers."""
        ...
    @property
    def resource_attributes(self) -> dict[str, str]:
        """Return additional OpenTelemetry resource attributes."""
        ...
    @resource_attributes.setter
    def resource_attributes(self, value: dict[str, str]) -> None:
        """Replace additional OpenTelemetry resource attributes."""
        ...
    @property
    def attribute_mappings(self) -> list[dict[str, str]]:
        """Return configured full/OpenInference attribute aliases."""
        ...
    @attribute_mappings.setter
    def attribute_mappings(self, value: list[dict[str, str]]) -> None:
        """Replace configured full/OpenInference attribute aliases."""
        ...
    def set_header(self, key: str, value: str) -> None:
        """Set one exporter header key/value pair."""
        ...
    def set_resource_attribute(self, key: str, value: str) -> None:
        """Set one OpenTelemetry resource attribute key/value pair."""
        ...

class OpenTelemetrySubscriber:
    """OpenTelemetry-backed NeMo Relay 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.
    """

    def __init__(self, config: OpenTelemetryConfig) -> None:
        """Create a subscriber from an OpenTelemetry config."""
        ...
    def register(self, name: str) -> None:
        """Register the subscriber under ``name``."""
        ...
    def deregister(self, name: str) -> bool:
        """Deregister ``name`` and return whether it existed."""
        ...
    def force_flush(self) -> None:
        """Flush pending telemetry through the configured exporter."""
        ...
    def shutdown(self) -> None:
        """Shut down native OpenTelemetry resources."""
        ...

class OpenAIChatCodec:
    """Built-in codec for OpenAI Chat Completions requests and responses.

    Summary:
        Native codec bridge for Chat Completions payloads.
    """

    def __init__(self) -> None:
        """Create an OpenAI Chat codec."""
        ...
    def decode(self, request: LLMRequest) -> AnnotatedLLMRequest:
        """Decode a Chat Completions request into a normalized request view."""
        ...
    def encode(self, annotated: AnnotatedLLMRequest, original: LLMRequest) -> LLMRequest:
        """Encode a normalized request back into Chat Completions shape."""
        ...
    def decode_response(self, response: _Json) -> AnnotatedLLMResponse:
        """Decode a Chat Completions response into a normalized response view."""
        ...

class OpenAIResponsesCodec:
    """Built-in codec for OpenAI Responses requests and responses.

    Summary:
        Native codec bridge for OpenAI Responses payloads.
    """

    def __init__(self) -> None:
        """Create an OpenAI Responses codec."""
        ...
    def decode(self, request: LLMRequest) -> AnnotatedLLMRequest:
        """Decode a Responses request into a normalized request view."""
        ...
    def encode(self, annotated: AnnotatedLLMRequest, original: LLMRequest) -> LLMRequest:
        """Encode a normalized request back into Responses shape."""
        ...
    def decode_response(self, response: _Json) -> AnnotatedLLMResponse:
        """Decode a Responses response into a normalized response view."""
        ...

class AnthropicMessagesCodec:
    """Built-in codec for Anthropic Messages requests and responses.

    Summary:
        Native codec bridge for Anthropic Messages payloads.
    """

    def __init__(self) -> None:
        """Create an Anthropic Messages codec."""
        ...
    def decode(self, request: LLMRequest) -> AnnotatedLLMRequest:
        """Decode an Anthropic Messages request into a normalized request view."""
        ...
    def encode(self, annotated: AnnotatedLLMRequest, original: LLMRequest) -> LLMRequest:
        """Encode a normalized request back into Anthropic Messages shape."""
        ...
    def decode_response(self, response: _Json) -> AnnotatedLLMResponse:
        """Decode an Anthropic response into a normalized response view."""
        ...

class AdaptiveRuntime:
    """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.
    """

    def __init__(self, config: object) -> None:
        """Create a runtime from an adaptive config object or mapping."""
        ...
    async def register(self) -> None:
        """Validate and register configured adaptive components."""
        ...
    def deregister(self) -> None:
        """Deregister adaptive components owned by this runtime."""
        ...
    async def shutdown(self) -> None:
        """Deregister components and release owned native resources."""
        ...
    def wait_for_idle(self) -> None:
        """Block until the adaptive telemetry drain has processed pending work."""
        ...
    def report(self) -> _JsonObject:
        """Return the runtime validation report."""
        ...
    def bind_scope(self, scope_handle: ScopeHandle) -> None:
        """Bind runtime ACG behavior to an active scope handle."""
        ...
    def build_cache_request_facts(
        self,
        *,
        provider: str,
        request_id: str,
        annotated_request: object,
        agent_id: str,
        timestamp: Optional[str] = None,
    ) -> Optional[_JsonObject]:
        """Build cache-diagnostics facts for a provider request.

        Args:
            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 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.
    """
    def register_mark_sanitize_guardrail(self, name: str, priority: int, callback: _EventSanitizeGuardrail) -> None: ...
    def register_scope_sanitize_start_guardrail(
        self, name: str, priority: int, callback: _EventSanitizeGuardrail
    ) -> None: ...
    def register_scope_sanitize_end_guardrail(
        self, name: str, priority: int, callback: _EventSanitizeGuardrail
    ) -> None: ...

def register_mark_sanitize_guardrail(name: str, priority: int, guardrail: _EventSanitizeGuardrail) -> None: ...
def deregister_mark_sanitize_guardrail(name: str) -> bool: ...
def register_scope_sanitize_start_guardrail(name: str, priority: int, guardrail: _EventSanitizeGuardrail) -> None: ...
def deregister_scope_sanitize_start_guardrail(name: str) -> bool: ...
def register_scope_sanitize_end_guardrail(name: str, priority: int, guardrail: _EventSanitizeGuardrail) -> None: ...
def deregister_scope_sanitize_end_guardrail(name: str) -> bool: ...
def scope_register_mark_sanitize_guardrail(
    scope_uuid: str, name: str, priority: int, guardrail: _EventSanitizeGuardrail
) -> None: ...
def scope_deregister_mark_sanitize_guardrail(scope_uuid: str, name: str) -> bool: ...
def scope_register_scope_sanitize_start_guardrail(
    scope_uuid: str, name: str, priority: int, guardrail: _EventSanitizeGuardrail
) -> None: ...
def scope_deregister_scope_sanitize_start_guardrail(scope_uuid: str, name: str) -> bool: ...
def scope_register_scope_sanitize_end_guardrail(
    scope_uuid: str, name: str, priority: int, guardrail: _EventSanitizeGuardrail
) -> None: ...
def scope_deregister_scope_sanitize_end_guardrail(scope_uuid: str, name: str) -> bool: ...
def 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.
    """
    ...

class PropagationContext:
    """Transport-neutral Relay causal context."""
    def __init__(self, parent_uuid: str, root_uuid: str | None = None, version: int = 1) -> None: ...
    @property
    def version(self) -> int: ...
    @property
    def root_uuid(self) -> str | None: ...
    @property
    def parent_uuid(self) -> str: ...
    def to_json(self) -> str:
        """Serialize this context to the Relay JSON wire format."""
        ...
    @staticmethod
    def from_json(value: str) -> PropagationContext:
        """Deserialize and validate a Relay JSON wire context."""
        ...

def capture_propagation_context() -> PropagationContext: ...
def capture_propagation_context_with_root(root_uuid: str | None) -> PropagationContext: ...
def create_scope_stack_from_propagation(context: PropagationContext) -> ScopeStack: ...

class _ThreadScopeStackBinding: ...

def capture_thread_scope_stack() -> _ThreadScopeStackBinding: ...
def restore_thread_scope_stack(binding: _ThreadScopeStackBinding) -> None: ...
def set_thread_scope_stack(stack: ScopeStack) -> None:
    """Install a scope stack into native thread-local storage.

    Args:
        stack: Scope stack to use for subsequent native calls on this thread.

    Returns:
        ``None``.
    """
    ...

def sync_thread_scope_stack(stack: ScopeStack) -> None:
    """Synchronize thread-local storage without marking it explicitly active.

    Args:
        stack: Scope stack to synchronize into the native thread-local slot.

    Returns:
        ``None``.
    """
    ...

def scope_stack_active() -> bool:
    """Return whether native thread-local storage has an explicitly active stack."""
    ...

def 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.
    """
    ...

def 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 | None = None,
) -> ScopeHandle:
    """Push a new scope onto the active native stack.

    Args:
        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.
    """
    ...

def pop_scope(
    handle: ScopeHandle,
    output: Optional[_Json] = None,
    metadata: Optional[_Json] = None,
    timestamp: datetime | None = None,
) -> None:
    """Pop a scope and emit its end event.

    Args:
        handle: Handle returned by ``push_scope``.
        output: Optional semantic output payload recorded on the end event.
        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 native runtime errors if ``handle`` is not the current scope or
        if ``output`` or ``metadata`` cannot be converted to JSON-compatible data.
        Raises for invalid timestamp types or naive datetimes.
    """
    ...

def event(
    name: str,
    *,
    handle: ScopeHandle | None = None,
    data: _Json | None = None,
    metadata: _Json | None = None,
    timestamp: datetime | None = None,
) -> None:
    """Emit a point-in-time mark event.

    Args:
        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.
    """
    ...

def tool_call(
    name: str,
    args: _Json,
    *,
    handle: ScopeHandle | None = None,
    attributes: ToolAttributes | None = None,
    data: _Json | None = None,
    metadata: _Json | None = None,
    tool_call_id: str | None = None,
    timestamp: datetime | None = None,
) -> ToolHandle:
    """Begin a manual tool lifecycle span.

    Args:
        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.
    """
    ...

def tool_call_end(
    handle: ToolHandle,
    result: _Json,
    *,
    data: _Json | None = None,
    metadata: _Json | None = None,
    timestamp: datetime | None = None,
) -> None:
    """End a manual tool lifecycle span.

    Args:
        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.
    """
    ...

def tool_call_execute(
    name: str,
    args: _Json,
    func: Callable[[_Json], Awaitable[_Json]],
    **kwargs: object,
) -> Awaitable[_Json]:
    """Execute a tool through the managed native middleware pipeline.

    Args:
        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.
    """
    ...

def 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 | None = None,
) -> LLMHandle:
    """Begin a manual LLM lifecycle span.

    Args:
        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.
    """
    ...

def llm_call_end(
    handle: LLMHandle,
    response: _Json,
    *,
    data: _Json | None = None,
    metadata: _Json | None = None,
    annotated_response: AnnotatedLLMResponse | Mapping[str, _JsonValue] | None = None,
    response_codec: object | None = None,
    timestamp: datetime | None = None,
) -> None:
    """End a manual LLM lifecycle span.

    Args:
        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.
        annotated_response: Optional normalized response annotation attached to
            the end event. Accepts an ``AnnotatedLLMResponse`` instance or a
            JSON-compatible mapping matching that schema.
        response_codec: Optional object implementing ``decode_response`` used
            to derive ``annotated_response`` from ``response`` for observability
            when ``annotated_response`` is omitted.
        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.
    """
    ...

def llm_call_execute(
    name: str,
    request: LLMRequest,
    func: Callable[[LLMRequest], Awaitable[_Json]],
    **kwargs: object,
) -> Awaitable[_Json]:
    """Execute a non-streaming LLM call through native middleware.

    Args:
        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.
    """
    ...

def llm_stream_call_execute(
    name: str,
    request: LLMRequest,
    func: Callable[[LLMRequest], AsyncIterator[_Json]],
    collector: Callable[[_Json], None],
    finalizer: Callable[[], _Json],
    **kwargs: object,
) -> LlmStream:
    """Execute a streaming LLM call through native middleware.

    Args:
        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.
    """
    ...

def tool_request_intercepts(name: str, args: _Json) -> _Json | Awaitable[_Json]:
    """Run the registered tool request-intercept chain.

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

    Returns:
        Transformed tool arguments directly outside an event loop, or an
        awaitable resolving to them from an async caller.

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

def tool_conditional_execution(name: str, args: _Json) -> None | Awaitable[None]:
    """Run tool conditional-execution guardrails.

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

    Returns:
        ``None`` when all guardrails allow execution, directly outside an event
        loop or through an awaitable from an async caller.

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

def llm_request_intercepts(
    name: str, request: LLMRequest
) -> LLMRequestInterceptOutcome | Awaitable[LLMRequestInterceptOutcome]:
    """Run the registered LLM request-intercept chain.

    Args:
        name: Provider or logical LLM call name.
        request: Current LLM request.

    Returns:
        Transformed request directly outside an event loop, or an awaitable
        resolving to it from an async caller.

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

def llm_conditional_execution(request: LLMRequest) -> None | Awaitable[None]:
    """Run LLM conditional-execution guardrails.

    Args:
        request: LLM request to evaluate.

    Returns:
        ``None`` when all guardrails allow execution, directly outside an event
        loop or through an awaitable from an async caller.

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

def register_tool_sanitize_request_guardrail(name: str, priority: int, guardrail: _ToolSanitizeGuardrail) -> None:
    """Register a global tool sanitize-request guardrail.

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

    Returns:
        ``None``.
    """
    ...

def deregister_tool_sanitize_request_guardrail(name: str) -> bool:
    """Remove a global tool sanitize-request guardrail by name.

    Args:
        name: Guardrail name to remove.

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

def register_tool_sanitize_response_guardrail(name: str, priority: int, guardrail: _ToolSanitizeGuardrail) -> None:
    """Register a global tool sanitize-response guardrail.

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

    Returns:
        ``None``.
    """
    ...

def 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``.
    """
    ...

def register_tool_conditional_execution_guardrail(
    name: str, priority: int, guardrail: _ToolConditionalExecutionGuardrail
) -> None:
    """Register a global tool conditional-execution guardrail.

    Args:
        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``.
    """
    ...

def 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``.
    """
    ...

def register_llm_sanitize_request_guardrail(name: str, priority: int, guardrail: _LlmSanitizeRequestGuardrail) -> None:
    """Register a global LLM sanitize-request guardrail.

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

    Returns:
        ``None``.
    """
    ...

def 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``.
    """
    ...

def register_llm_sanitize_response_guardrail(
    name: str, priority: int, guardrail: _LlmSanitizeResponseGuardrail
) -> None:
    """Register a global LLM sanitize-response guardrail.

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

    Returns:
        ``None``.
    """
    ...

def 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``.
    """
    ...

def register_llm_conditional_execution_guardrail(
    name: str, priority: int, guardrail: _LlmConditionalExecutionGuardrail
) -> None:
    """Register a global LLM conditional-execution guardrail.

    Args:
        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``.
    """
    ...

def 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``.
    """
    ...

def register_tool_request_intercept(
    name: str,
    priority: int,
    break_chain: bool,
    callable: _ToolRequestIntercept,
) -> None:
    """Register a global tool request intercept.

    Args:
        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``.
    """
    ...

def deregister_tool_request_intercept(name: str) -> bool:
    """Remove a global tool request intercept and return whether it existed."""
    ...

def register_tool_execution_intercept(name: str, priority: int, callable: _ToolExecutionIntercept) -> None:
    """Register a global tool execution intercept.

    Args:
        name: Unique intercept name.
        priority: Execution order; lower values run first.
        callable: Middleware callback returning
            ``ToolExecutionInterceptOutcome``. It may call or short-circuit
            ``next``; ``next`` resolves to the raw downstream result while
            Relay retains downstream pending marks.

    Returns:
        ``None``.
    """
    ...

def deregister_tool_execution_intercept(name: str) -> bool:
    """Remove a global tool execution intercept.

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

def register_llm_request_intercept(
    name: str,
    priority: int,
    break_chain: bool,
    callable: _LlmRequestIntercept,
) -> None:
    """Register a global LLM request intercept.

    Args:
        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``.
    """
    ...

def deregister_llm_request_intercept(name: str) -> bool:
    """Remove a global LLM request intercept.

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

def register_llm_execution_intercept(name: str, priority: int, callable: _LlmExecutionIntercept) -> None:
    """Register a global LLM execution intercept.

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

    Returns:
        ``None``.
    """
    ...

def deregister_llm_execution_intercept(name: str) -> bool:
    """Remove a global LLM execution intercept.

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

def register_llm_stream_execution_intercept(
    name: str,
    priority: int,
    callable: _LlmStreamExecutionIntercept,
) -> None:
    """Register a global LLM stream-execution intercept.

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

    Returns:
        ``None``.
    """
    ...

def deregister_llm_stream_execution_intercept(name: str) -> bool:
    """Remove a global LLM stream-execution intercept.

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

def register_subscriber(name: str, callback: Callable[[ScopeEvent | MarkEvent], None]) -> None:
    """Register a global event subscriber callback.

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

    Returns:
        ``None``.

    Notes:
        Native event emission queues subscriber callbacks and does not wait for
        observer work before returning.
    """
    ...

def deregister_subscriber(name: str) -> bool:
    """Remove a global event subscriber.

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

def flush_subscribers() -> None:
    """Wait for queued callbacks and registered managed terminal publications.

    Call this function outside subscribers, event sanitizers, conditional
    guardrails, and request or execution intercepts. The public Python wrapper
    handles the limited queued tool/LLM observability-sanitizer exception.
    """
    ...

def subscriber_dispatcher_before_fork() -> None:
    """Lock subscriber dispatcher resources before a process forks."""
    ...

def subscriber_dispatcher_after_fork_parent() -> None:
    """Unlock subscriber dispatcher resources in the parent after a fork."""
    ...

def subscriber_dispatcher_after_fork_child() -> None:
    """Reset and unlock inherited subscriber dispatcher resources in a child."""
    ...

def scope_register_tool_sanitize_request_guardrail(
    scope_uuid: str, name: str, priority: int, guardrail: _ToolSanitizeGuardrail
) -> None:
    """Register a scope-local tool sanitize-request guardrail.

    Args:
        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``.
    """
    ...

def 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``.
    """
    ...

def scope_register_tool_sanitize_response_guardrail(
    scope_uuid: str, name: str, priority: int, guardrail: _ToolSanitizeGuardrail
) -> None:
    """Register a scope-local tool sanitize-response guardrail.

    Args:
        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``.
    """
    ...

def 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``.
    """
    ...

def scope_register_tool_conditional_execution_guardrail(
    scope_uuid: str, name: str, priority: int, guardrail: _ToolConditionalExecutionGuardrail
) -> None:
    """Register a scope-local tool conditional-execution guardrail.

    Args:
        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``.
    """
    ...

def 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``.
    """
    ...

def 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.

    Args:
        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``.
    """
    ...

def 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``.
    """
    ...

def scope_register_tool_execution_intercept(
    scope_uuid: str,
    name: str,
    priority: int,
    callable: _ToolExecutionIntercept,
) -> None:
    """Register a scope-local tool execution intercept.

    Args:
        scope_uuid: UUID of the owning scope.
        name: Unique intercept name within that scope.
        priority: Execution order; lower values run first.
        callable: Middleware callback returning
            ``ToolExecutionInterceptOutcome`` while the owning scope is active.
            Its ``next`` continuation resolves to the raw downstream result
            while Relay retains downstream pending marks.

    Returns:
        ``None``.
    """
    ...

def 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``.
    """
    ...

def scope_register_llm_sanitize_request_guardrail(
    scope_uuid: str, name: str, priority: int, guardrail: _LlmSanitizeRequestGuardrail
) -> None:
    """Register a scope-local LLM sanitize-request guardrail.

    Args:
        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``.
    """
    ...

def 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``.
    """
    ...

def scope_register_llm_sanitize_response_guardrail(
    scope_uuid: str, name: str, priority: int, guardrail: _LlmSanitizeResponseGuardrail
) -> None:
    """Register a scope-local LLM sanitize-response guardrail.

    Args:
        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``.
    """
    ...

def 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``.
    """
    ...

def scope_register_llm_conditional_execution_guardrail(
    scope_uuid: str, name: str, priority: int, guardrail: _LlmConditionalExecutionGuardrail
) -> None:
    """Register a scope-local LLM conditional-execution guardrail.

    Args:
        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``.
    """
    ...

def 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``.
    """
    ...

def 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.

    Args:
        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``.
    """
    ...

def 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``.
    """
    ...

def scope_register_llm_execution_intercept(
    scope_uuid: str,
    name: str,
    priority: int,
    callable: _LlmExecutionIntercept,
) -> None:
    """Register a scope-local LLM execution intercept.

    Args:
        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``.
    """
    ...

def 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``.
    """
    ...

def scope_register_llm_stream_execution_intercept(
    scope_uuid: str,
    name: str,
    priority: int,
    callable: _LlmStreamExecutionIntercept,
) -> None:
    """Register a scope-local LLM stream-execution intercept.

    Args:
        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``.
    """
    ...

def 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``.
    """
    ...

def scope_register_subscriber(
    scope_uuid: str,
    name: str,
    callback: Callable[[ScopeEvent | MarkEvent], None],
) -> None:
    """Register a scope-local event subscriber callback.

    Args:
        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``.
    """
    ...

def scope_deregister_subscriber(scope_uuid: str, name: str) -> bool:
    """Remove a scope-local event subscriber.

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

def validate_plugin_config(config: object) -> _JsonObject:
    """Validate a plugin configuration without changing active runtime state.

    Args:
        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.
    """
    ...

class _PluginHostActivation:
    """Native owner for one process-wide dynamic plugin host."""

    @property
    def report(self) -> _JsonObject:
        """Return the validation report captured during activation."""
        ...

    @property
    def is_active(self) -> bool:
        """Return whether this activation handle has not begun teardown.

        ``False`` does not guarantee another process-wide activation can start;
        failed teardown may intentionally retain the activation owner.
        """
        ...

    def close(self) -> Awaitable[None]:
        """Clear and unload this activation; repeated calls are safe."""
        ...

def initialize_with_dynamic_plugins(config: object, dynamic_plugins: object) -> Awaitable[_PluginHostActivation]:
    """Initialize registered components with dynamic plugins as one owned host.

    Args:
        config: Base plugin configuration object.
        dynamic_plugins: Sequence of dynamic plugin activation specifications.

    Returns:
        Awaitable resolving to the native activation owner.

    Exceptional flow:
        Invalid configuration, load, ownership, and registration errors are
        raised through the awaitable.
    """
    ...

def initialize_plugins(config: object) -> Awaitable[_JsonObject]:
    """Validate and activate plugin configuration.

    Args:
        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.
    """
    ...

def clear_plugin_configuration() -> None:
    """Clear active plugin configuration while preserving registered kinds.

    Returns:
        ``None``.

    Exceptional flow:
        Native cleanup errors propagate unchanged.
    """
    ...

def clear_plugin_configuration_async() -> Awaitable[None]:
    """Clear active plugin configuration without blocking the Python event loop.

    Returns:
        Awaitable resolving when native teardown completes.

    Exceptional flow:
        Native cleanup and teardown worker errors propagate through the awaitable.
    """
    ...

def active_plugin_report() -> Optional[_JsonObject]:
    """Return the active plugin report or a failed-teardown diagnostic report.

    Returns:
        Report JSON object for the active configuration or a failed teardown
        with runtime diagnostics, or ``None`` if neither exists.
    """
    ...

def list_plugin_kinds() -> list[str]:
    """Return registered custom plugin kind names.

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

def register_plugin(plugin_kind: str, plugin: object) -> None:
    """Register a custom plugin implementation under a kind string.

    Args:
        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.
    """
    ...

def deregister_plugin(plugin_kind: str) -> bool:
    """Deregister a custom plugin kind.

    Args:
        plugin_kind: Kind string to remove.

    Returns:
        ``True`` if a plugin kind was removed, otherwise ``False``.
    """
    ...

def build_cache_telemetry_event(*args: object, **kwargs: object) -> _JsonObject:
    """Build a normalized adaptive cache telemetry event.

    Args:
        *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.
    """
    ...

def validate_adaptive_config(config: object) -> _JsonObject:
    """Validate adaptive configuration.

    Args:
        config: Adaptive configuration object or equivalent mapping.

    Returns:
        Validation report as a JSON object.

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

def set_latency_sensitivity(level: int) -> None:
    """Set the process-local manual latency-sensitivity override.

    Args:
        level: Positive integer sensitivity value for the current execution
            context.

    Returns:
        ``None``.

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

def __getattr__(name: str) -> object:
    """Resolve dynamic native attributes not represented by static stubs.

    Args:
        name: Attribute name to resolve.

    Returns:
        Native attribute object.

    Exceptional flow:
        Raises ``AttributeError`` when no native attribute exists.
    """
    ...