> This page is for version v0.25.0.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.25.0: https://docs.nvidia.com/nemo/guardrails/v0.25.0/llms.txt
> - v0.24.1: https://docs.nvidia.com/nemo/guardrails/v0.24.1/llms.txt
> - v0.24.0: https://docs.nvidia.com/nemo/guardrails/v0.24.0/llms.txt
> - v0.23.0: https://docs.nvidia.com/nemo/guardrails/v0.23.0/llms.txt
> - v0.22.0: https://docs.nvidia.com/nemo/guardrails/v0.22.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.

# nemoguardrails.server.experimental.provider.stream

Define the stream boundary implemented by provider adapters.

## Module Contents

### Classes

| Name                                                                                                         | Description                                                              |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| [`ClassifiedStreamAdapter`](#nemoguardrails-server-experimental-provider-stream-ClassifiedStreamAdapter)     | Compose a stateless classifier with handwritten protocol hooks.          |
| [`GuardedStreamEvent`](#nemoguardrails-server-experimental-provider-stream-GuardedStreamEvent)               | Describe one provider event at the Guardrails boundary.                  |
| [`ProviderStreamAdapter`](#nemoguardrails-server-experimental-provider-stream-ProviderStreamAdapter)         | Expose the complete stream behavior consumed by the shared runtime.      |
| [`ProviderStreamClassifier`](#nemoguardrails-server-experimental-provider-stream-ProviderStreamClassifier)   | Classify native events using declarative projection semantics.           |
| [`ProviderStreamHooks`](#nemoguardrails-server-experimental-provider-stream-ProviderStreamHooks)             | Implement stateful protocol checks and provider-native error framing.    |
| [`StreamBinding`](#nemoguardrails-server-experimental-provider-stream-StreamBinding)                         | Bind shared classification to a fresh set of protocol hooks per request. |
| [`StreamCapabilityProfile`](#nemoguardrails-server-experimental-provider-stream-StreamCapabilityProfile)     | Identify a closed streaming capability understood by the framework.      |
| [`StreamEventRole`](#nemoguardrails-server-experimental-provider-stream-StreamEventRole)                     | Describe how one provider event relates to guarded content.              |
| [`StreamProjectionContract`](#nemoguardrails-server-experimental-provider-stream-StreamProjectionContract)   | Describe the runtime semantics of one guarded stream projection.         |
| [`StreamShapeCoverage`](#nemoguardrails-server-experimental-provider-stream-StreamShapeCoverage)             | Classify every reviewed native event shape in a provider stream.         |
| [`UnsupportedProviderStream`](#nemoguardrails-server-experimental-provider-stream-UnsupportedProviderStream) | Report a provider event that the guarded stream cannot interpret.        |

### Functions

| Name                                                                                                 | Description                                                       |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [`validate_stream_event`](#nemoguardrails-server-experimental-provider-stream-validate_stream_event) | Require a classified event to match its declared shape semantics. |

### API

```python
class nemoguardrails.server.experimental.provider.stream.ClassifiedStreamAdapter(
    classifier: nemoguardrails.server.experimental.provider.stream.ProviderStreamClassifier,
    hooks: nemoguardrails.server.experimental.provider.stream.ProviderStreamHooks
)
```

Dataclass

Compose a stateless classifier with handwritten protocol hooks.

**`classifier`** `ProviderStreamClassifier`

---

**`contract`** `StreamProjectionContract`

Return the classifier's stream projection contract.

---

**`hooks`** `ProviderStreamHooks`

---

```python
nemoguardrails.server.experimental.provider.stream.ClassifiedStreamAdapter.classify_event(
    event: nemoguardrails.server.experimental.provider.sse.ServerSentEvent
) -> nemoguardrails.server.experimental.provider.stream.GuardedStreamEvent
```

Classify an event and expose it to stateful protocol hooks.

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

Delegate provider-native error framing to provider hooks.

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

Delegate end-of-stream validation to provider hooks.

```python
class nemoguardrails.server.experimental.provider.stream.GuardedStreamEvent(
    shape: str,
    role: nemoguardrails.server.experimental.provider.stream.StreamEventRole,
    text: str | None = None
)
```

Dataclass

Describe one provider event at the Guardrails boundary.

**`role`** `StreamEventRole`

---

**`shape`** `str`

---

**`text`** `str | None = None`

---

```python
nemoguardrails.server.experimental.provider.stream.GuardedStreamEvent.__post_init__() -> None
```

Require text exactly for roles that carry generated content.

```python
class nemoguardrails.server.experimental.provider.stream.ProviderStreamAdapter()
```

Protocol

Expose the complete stream behavior consumed by the shared runtime.

**`contract`** `StreamProjectionContract`

---

```python
nemoguardrails.server.experimental.provider.stream.ProviderStreamAdapter.classify_event(
    event: nemoguardrails.server.experimental.provider.sse.ServerSentEvent
) -> nemoguardrails.server.experimental.provider.stream.GuardedStreamEvent
```

Validate, classify, and observe one provider event.

```python
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.

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

Validate provider protocol state when the byte stream ends.

```python
class nemoguardrails.server.experimental.provider.stream.ProviderStreamClassifier()
```

Protocol

Classify native events using declarative projection semantics.

**`contract`** `StreamProjectionContract`

---

```python
nemoguardrails.server.experimental.provider.stream.ProviderStreamClassifier.classify_event(
    event: nemoguardrails.server.experimental.provider.sse.ServerSentEvent
) -> nemoguardrails.server.experimental.provider.stream.GuardedStreamEvent
```

Validate and classify one provider event.

```python
class nemoguardrails.server.experimental.provider.stream.ProviderStreamHooks()
```

Protocol

Implement stateful protocol checks and provider-native error framing.

```python
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.

```python
nemoguardrails.server.experimental.provider.stream.ProviderStreamHooks.observe_event(
    event: nemoguardrails.server.experimental.provider.sse.ServerSentEvent,
    classified: nemoguardrails.server.experimental.provider.stream.GuardedStreamEvent
) -> None
```

Observe one classified event and update protocol state.

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

Validate provider protocol state when the byte stream ends.

```python
class nemoguardrails.server.experimental.provider.stream.StreamBinding(
    classifier: nemoguardrails.server.experimental.provider.stream.ProviderStreamClassifier,
    hooks_factory: typing.Callable[[], nemoguardrails.server.experimental.provider.stream.ProviderStreamHooks]
)
```

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]`

---

```python
nemoguardrails.server.experimental.provider.stream.StreamBinding.__post_init__() -> None
```

Reject malformed bindings without creating request state.

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

Create request-local hooks and validate their protocol interface.

```python
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'`

---

```python
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'`

---

```python
class nemoguardrails.server.experimental.provider.stream.StreamProjectionContract(
    projection_id: str,
    profile: nemoguardrails.server.experimental.provider.stream.StreamCapabilityProfile,
    shapes: nemoguardrails.server.experimental.provider.stream.StreamShapeCoverage,
    fields: nemoguardrails.server.experimental.provider.payload.ProjectionFieldCoverage | None = None
)
```

Dataclass

Describe the runtime semantics of one guarded stream projection.

**`fields`** `ProjectionFieldCoverage | None = None`

---

**`profile`** `StreamCapabilityProfile`

---

**`projection_id`** `str`

---

**`shapes`** `StreamShapeCoverage`

---

```python
nemoguardrails.server.experimental.provider.stream.StreamProjectionContract.__post_init__() -> None
```

```python
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()`

---

```python
nemoguardrails.server.experimental.provider.stream.StreamShapeCoverage.__post_init__() -> None
```

```python
class nemoguardrails.server.experimental.provider.stream.UnsupportedProviderStream()
```

**Bases:** `ValueError`

Report a provider event that the guarded stream cannot interpret.

```python
nemoguardrails.server.experimental.provider.stream.validate_stream_event(
    contract: nemoguardrails.server.experimental.provider.stream.StreamProjectionContract,
    event: nemoguardrails.server.experimental.provider.stream.GuardedStreamEvent
) -> None
```

Require a classified event to match its declared shape semantics.