> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/fabric/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/fabric/_mcp/server.
# Types
> Typed config, request, plan, result, artifact, telemetry, and runtime contracts.
# module `nemo_fabric.types`
Public data contracts for the NeMo Fabric Python SDK.
---
## class `AdapterInfo`
Resolved adapter identity attached to a run plan.
**Attributes:**
- `adapter_id`: Stable identifier of the NeMo Fabric adapter implementation.
- `harness`: Stable machine-readable harness identifier.
- `adapter_kind`: Execution mechanism used by the adapter.
- `metadata`: Adapter-specific, JSON-compatible metadata.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `adapter_id` | `str` |
| `harness` | `str` |
| `adapter_kind` | `str` |
| `metadata` | `Mapping[str, Any]` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
## class `RuntimeCapabilities`
Operations declared by the resolved runtime and adapter.
Capabilities describe what the selected runtime can support; callers should still expect a capability-specific error when a transport is modeled but not implemented.
**Attributes:**
- `service`: Whether long-lived service handles are supported.
- `streaming`: Whether event streaming is supported.
- `updates`: Whether runtime configuration updates are supported.
- `cancellation`: Whether in-flight cancellation is supported.
- `metadata`: Additional capability details.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `service` | `bool` |
| `streaming` | `bool` |
| `updates` | `bool` |
| `cancellation` | `bool` |
| `metadata` | `Mapping[str, Any]` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
## class `RunPlan`
Immutable execution plan produced before a runtime is started.
**Attributes:**
- `agent_name`: Resolved agent name.
- `base_dir`: Base directory used to resolve relative paths.
- `config`: Typed configuration snapshot.
- `adapter`: Resolved adapter identity.
- `capabilities`: Operations declared by the resolved runtime.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `agent_name` | `str` |
| `base_dir` | `Path` |
| `config` | `_FabricConfigSnapshot` |
| `adapter` | `AdapterInfo` |
| `capabilities` | `RuntimeCapabilities` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
## class `DoctorCheck`
One diagnostic check in a ``DoctorReport``.
**Attributes:**
- `name`: Stable check identifier.
- `status`: Check outcome: ``pass``, ``warn``, or ``fail``.
- `message`: Human-readable result.
- `metadata`: Structured check details.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `name` | `str` |
| `status` | `str` |
| `message` | `str` |
| `metadata` | `Mapping[str, Any]` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
## class `DoctorReport`
Aggregate preflight diagnostics for a resolved run plan.
**Attributes:**
- `agent_name`: Resolved agent name.
- `status`: Aggregate outcome: ``pass``, ``warn``, or ``fail``.
- `checks`: Ordered ``DoctorCheck`` results.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `agent_name` | `str` |
| `status` | `str` |
| `checks` | `Sequence[DoctorCheck]` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
## class `ErrorInfo`
Structured failure returned inside a normalized ``RunResult``.
**Attributes:**
- `stage`: Lifecycle stage that failed.
- `code`: Stable machine-readable error code.
- `message`: Human-readable failure description.
- `retryable`: Whether retrying may succeed without changing the request.
- `metadata`: Adapter- or runtime-specific details.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `stage` | `str` |
| `code` | `str` |
| `message` | `str` |
| `retryable` | `bool` |
| `metadata` | `Mapping[str, Any]` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
## class `ArtifactRef`
Reference to one artifact produced by a run.
**Attributes:**
- `name`: Stable artifact name.
- `kind`: Artifact category.
- `path`: Artifact path under the manifest root or workspace.
- `media_type`: Optional MIME type.
- `metadata`: Artifact-specific details.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `name` | `str` |
| `kind` | `str` |
| `path` | `Path` |
| `media_type` | `str \| None` |
| `metadata` | `Mapping[str, Any]` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
## class `ArtifactManifest`
Normalized collection of artifacts produced by a run.
**Attributes:**
- `root`: Optional common artifact root.
- `artifacts`: Ordered ``ArtifactRef`` entries.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `root` | `Path \| None` |
| `artifacts` | `Sequence[ArtifactRef]` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
## class `TelemetryRef`
Reference to external or persisted telemetry for a run.
**Attributes:**
- `provider`: Telemetry provider, such as NVIDIA NeMo Relay.
- `kind`: Reference kind, such as ``trace``.
- `uri`: Optional location of persisted telemetry.
- `trace_id`: Optional provider trace identifier.
- `metadata`: Provider-specific details.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `provider` | `str` |
| `kind` | `str` |
| `uri` | `str \| None` |
| `trace_id` | `str \| None` |
| `metadata` | `Mapping[str, Any]` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
## class `FabricEvent`
One normalized lifecycle or invocation event.
**Attributes:**
- `event_id`: Stable event identifier.
- `timestamp_millis`: Event time as Unix epoch milliseconds.
- `kind`: Machine-readable event kind.
- `message`: Human-readable event description.
- `metadata`: Event-specific structured details.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `event_id` | `str` |
| `timestamp_millis` | `int` |
| `kind` | `str` |
| `message` | `str` |
| `metadata` | `Mapping[str, Any]` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
## class `RuntimeHandle`
Opaque identity and binding for one started runtime.
Applications should treat ``runtime_binding`` as opaque. NeMo Fabric validates the handle against the run plan before invocation or shutdown.
**Attributes:**
- `runtime_id`: Unique identifier for this runtime lifecycle.
- `runtime_binding`: Opaque integrity-bound runtime binding.
- `agent_name`: Resolved agent name.
- `harness`: Stable harness identifier.
- `adapter_kind`: Adapter execution mechanism.
- `adapter_id`: Optional NeMo Fabric adapter identifier.
- `environment`: Prepared environment snapshot.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `runtime_id` | `str` |
| `runtime_binding` | `str` |
| `agent_name` | `str` |
| `harness` | `str` |
| `adapter_kind` | `str` |
| `adapter_id` | `str \| None` |
| `environment` | `Mapping[str, Any]` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
## class `RunOutput`
Normalized adapter output.
``response`` is a known adapter response field whose value follows the core NeMo Fabric JSON contract. Other keys are adapter-specific extensions.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `response` | `JSONValue \| None` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### property response
Return the raw ``response`` JSON value, or ``None`` when absent.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
## class `RunResult`
Normalized terminal result from one NeMo Fabric invocation.
The model is both attribute-accessible and mapping-compatible. A harness failure can be represented by ``status`` and ``error`` without raising when the adapter successfully returns a normalized result.
**Attributes:**
- `agent_name`: Resolved agent name.
- `harness`: Stable harness identifier.
- `adapter_kind`: Adapter execution mechanism.
- `adapter_id`: NeMo Fabric adapter identifier.
- `runtime_id`: Runtime lifecycle identifier.
- `invocation_id`: Identifier for this invocation.
- `request_id`: Correlated request identifier.
- `status`: Terminal invocation status.
- `output`: Object-shaped adapter output as ``RunOutput``; non-object values are preserved as-is.
- `error`: Structured failure, or ``None`` on success.
- `artifacts`: Normalized artifact manifest.
- `telemetry`: Ordered telemetry references.
- `events`: Ordered lifecycle and invocation events.
- `metadata`: Result-specific structured details.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `agent_name` | `str` |
| `harness` | `str` |
| `adapter_kind` | `str` |
| `adapter_id` | `str` |
| `runtime_id` | `str` |
| `invocation_id` | `str` |
| `request_id` | `str` |
| `status` | `str` |
| `output` | `RunOutput \| JSONValue` |
| `error` | `ErrorInfo \| None` |
| `artifacts` | `ArtifactManifest` |
| `telemetry` | `Sequence[TelemetryRef]` |
| `events` | `Sequence[FabricEvent]` |
| `metadata` | `Mapping[str, Any]` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### classmethod `from_mapping`
```python
def from_mapping(mapping: Mapping[str, Any]) -> Self
```
Validate and copy a mapping into the requested typed model.
---
### method `to_dict`
```python
def to_dict() -> dict[str, Any]
```
Return the same detached representation as ``to_mapping()``.
---
### method `to_mapping`
```python
def to_mapping() -> dict[str, Any]
```
Return a detached, JSON-compatible mapping for serialization.
---
_This file was automatically generated via [lazydocs](https://github.com/ml-tooling/lazydocs)._