Skip to navigation

nemoguardrails.server.experimental.provider.stream

View as MarkdownOpen in Claude

Define the stream boundary implemented by provider adapters.

Module Contents

Classes

NameDescription
ClassifiedStreamAdapterCompose a stateless classifier with handwritten protocol hooks.
GuardedStreamEventDescribe one provider event at the Guardrails boundary.
ProviderStreamAdapterExpose the complete stream behavior consumed by the shared runtime.
ProviderStreamClassifierClassify native events using declarative projection semantics.
ProviderStreamHooksImplement stateful protocol checks and provider-native error framing.
StreamBindingBind shared classification to a fresh set of protocol hooks per request.
StreamCapabilityProfileIdentify a closed streaming capability understood by the framework.
StreamEventRoleDescribe how one provider event relates to guarded content.
StreamProjectionContractDescribe the runtime semantics of one guarded stream projection.
StreamShapeCoverageClassify every reviewed native event shape in a provider stream.
UnsupportedProviderStreamReport a provider event that the guarded stream cannot interpret.

Functions

NameDescription
validate_stream_eventRequire a classified event to match its declared shape semantics.

API

class nemoguardrails.server.experimental.provider.stream.ClassifiedStreamAdapter(
)
Dataclass

Compose a stateless classifier with handwritten protocol hooks.

classifier
ProviderStreamClassifier
contract
StreamProjectionContract

Return the classifier’s stream projection contract.

hooks
ProviderStreamHooks
nemoguardrails.server.experimental.provider.stream.ClassifiedStreamAdapter.classify_event(

Classify an event and expose it to stateful protocol hooks.

nemoguardrails.server.experimental.provider.stream.ClassifiedStreamAdapter.encode_error(
rendered_body: bytes
) -> collections.abc.Sequence[bytes]

Delegate provider-native error framing to provider hooks.

nemoguardrails.server.experimental.provider.stream.ClassifiedStreamAdapter.validate_end_of_stream() -> None

Delegate end-of-stream validation to provider hooks.

class nemoguardrails.server.experimental.provider.stream.GuardedStreamEvent(
shape: str,
text: str | None = None
)
Dataclass

Describe one provider event at the Guardrails boundary.

role
StreamEventRole
shape
str
text
str | None = None
nemoguardrails.server.experimental.provider.stream.GuardedStreamEvent.__post_init__() -> None

Require text exactly for roles that carry generated content.

class nemoguardrails.server.experimental.provider.stream.ProviderStreamAdapter()
Protocol

Expose the complete stream behavior consumed by the shared runtime.

contract
StreamProjectionContract
nemoguardrails.server.experimental.provider.stream.ProviderStreamAdapter.classify_event(

Validate, classify, and observe one provider event.

nemoguardrails.server.experimental.provider.stream.ProviderStreamAdapter.encode_error(
rendered_body: bytes
) -> collections.abc.Sequence[bytes]

Frame a proxy error and its provider-native body as complete SSE blocks.

nemoguardrails.server.experimental.provider.stream.ProviderStreamAdapter.validate_end_of_stream() -> None

Validate provider protocol state when the byte stream ends.

class nemoguardrails.server.experimental.provider.stream.ProviderStreamClassifier()
Protocol

Classify native events using declarative projection semantics.

contract
StreamProjectionContract
nemoguardrails.server.experimental.provider.stream.ProviderStreamClassifier.classify_event(

Validate and classify one provider event.

class nemoguardrails.server.experimental.provider.stream.ProviderStreamHooks()
Protocol

Implement stateful protocol checks and provider-native error framing.

nemoguardrails.server.experimental.provider.stream.ProviderStreamHooks.encode_error(
rendered_body: bytes
) -> collections.abc.Sequence[bytes]

Frame a proxy error and its provider-native body as complete SSE blocks.

nemoguardrails.server.experimental.provider.stream.ProviderStreamHooks.observe_event(
) -> None

Observe one classified event and update protocol state.

nemoguardrails.server.experimental.provider.stream.ProviderStreamHooks.validate_end_of_stream() -> None

Validate provider protocol state when the byte stream ends.

class nemoguardrails.server.experimental.provider.stream.StreamBinding(
)
Dataclass

Bind shared classification to a fresh set of protocol hooks per request.

Construction checks declarations without running the hook factory. Runtime uses create_adapter; inspection can read the classifier directly. Factories must return independent hook instances so lifecycle state is never shared. Handwritten classifiers are supported at runtime, but are not automatically representable by a guard contract.

classifier
ProviderStreamClassifier
hooks_factory
Callable[[], ProviderStreamHooks]
nemoguardrails.server.experimental.provider.stream.StreamBinding.__post_init__() -> None

Reject malformed bindings without creating request state.

nemoguardrails.server.experimental.provider.stream.StreamBinding.create_adapter() -> nemoguardrails.server.experimental.provider.stream.ClassifiedStreamAdapter

Create request-local hooks and validate their protocol interface.

class nemoguardrails.server.experimental.provider.stream.StreamCapabilityProfile

Bases: enum.Enum

Identify a closed streaming capability understood by the framework.

SINGLE_TEXT_DELTA_V1
= 'single_text_delta.v1'
class nemoguardrails.server.experimental.provider.stream.StreamEventRole

Bases: enum.Enum

Describe how one provider event relates to guarded content.

GUARDED_TEXT
= 'guarded_text'
OPAQUE_METADATA
= 'opaque_metadata'
PROVIDER_ERROR
= 'provider_error'
TEXT_SNAPSHOT
= 'text_snapshot'
class nemoguardrails.server.experimental.provider.stream.StreamProjectionContract(
projection_id: str,
)
Dataclass

Describe the runtime semantics of one guarded stream projection.

fields
ProjectionFieldCoverage | None = None
profile
StreamCapabilityProfile
projection_id
str
shapes
StreamShapeCoverage
nemoguardrails.server.experimental.provider.stream.StreamProjectionContract.__post_init__() -> None
class nemoguardrails.server.experimental.provider.stream.StreamShapeCoverage(
guarded_shapes: frozenset[str] = frozenset(),
snapshot_shapes: frozenset[str] = frozenset(),
opaque_shapes: frozenset[str] = frozenset(),
provider_error_shapes: frozenset[str] = frozenset()
)
Dataclass

Classify every reviewed native event shape in a provider stream.

guarded_shapes
frozenset[str] = frozenset()
opaque_shapes
frozenset[str] = frozenset()
provider_error_shapes
frozenset[str] = frozenset()
reviewed_shapes
frozenset[str]

Return every shape deliberately covered by the stream contract.

snapshot_shapes
frozenset[str] = frozenset()
nemoguardrails.server.experimental.provider.stream.StreamShapeCoverage.__post_init__() -> None
class nemoguardrails.server.experimental.provider.stream.UnsupportedProviderStream()

Bases: ValueError

Report a provider event that the guarded stream cannot interpret.

nemoguardrails.server.experimental.provider.stream.validate_stream_event(
) -> None

Require a classified event to match its declared shape semantics.