> This page is for NeMo Fabric, version v0.6.0.
> For other versions, use one of these documentation indexes:
> - Latest (v0.6.0) (default): https://docs.nvidia.com/nemo/fabric/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/fabric/dev/llms.txt
> - v0.6.0: https://docs.nvidia.com/nemo/fabric/v0.6.0/llms.txt
> - v0.5.0: https://docs.nvidia.com/nemo/fabric/v0.5.0/llms.txt
> - v0.4.0: https://docs.nvidia.com/nemo/fabric/v0.4.0/llms.txt
> - v0.3.0: https://docs.nvidia.com/nemo/fabric/v0.3.0/llms.txt
> - v0.2.0: https://docs.nvidia.com/nemo/fabric/v0.2.0/llms.txt
> - v0.1.1: https://docs.nvidia.com/nemo/fabric/v0.1.1/llms.txt
> - v0.1.0: https://docs.nvidia.com/nemo/fabric/v0.1.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/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.
- `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` |
| `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 `EnvironmentReference`
Provider-specific identity for an existing execution environment.
Pass this reference to ``Fabric.attach_environment()``. The provider verifies the resource before returning a durable ``EnvironmentHandle`` and never gains deletion authority over the caller-owned resource.
**Attributes:**
- `provider`: Stable environment-provider identifier.
- `resource`: Provider-specific resource identity.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `provider` | `str` |
| `resource` | `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 `EnvironmentHandle`
Durable identity and provider binding for a prepared or attached environment.
Environment handles are independent of runtime sessions. Runtime and reuse limits are provider-specific. Release the environment separately after stopping its runtime and collecting results.
**Attributes:**
- `environment_id`: Unique identifier for the prepared environment.
- `provider`: Stable environment-provider identifier.
- `control_location`: Whether Fabric control runs outside or inside the environment.
- `workspace`: Optional workspace visible to the harness runtime.
- `artifacts`: Optional artifact root visible to the harness runtime.
- `env`: Environment variables visible to the harness and its tools.
- `ownership`: Whether the caller or Fabric owns the environment resource.
- `connection`: Provider connection metadata.
- `metadata`: Provider-specific metadata.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `environment_id` | `str` |
| `provider` | `str` |
| `control_location` | `str` |
| `workspace` | `str \| Path \| None` |
| `artifacts` | `str \| Path \| None` |
| `env` | `Mapping[str, str]` |
| `ownership` | `str` |
| `connection` | `Mapping[str, Any]` |
| `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.
- `service_id`: Optional service used by this runtime.
- `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` |
| `service_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 `ServiceReference`
Reference to an already-running caller-owned service.
``adapter_id`` selects the adapter that understands the service type and connection fields.
``connection`` contains endpoints and credential references such as an environment-variable name. It must not contain credential values.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `adapter_id` | `str` |
| `service_type` | `str` |
| `connection` | `Mapping[str, Any]` |
| `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 `ServiceHandle`
Opaque identity and binding for one prepared or attached service.
``service_id`` identifies the process-local Fabric service lifecycle, not the underlying remote deployment. ``service_binding`` is opaque and must be returned unchanged when the handle is used. ``adapter_id`` identifies the adapter that created or attached to the service, and ``service_type`` is that adapter's stable service kind. ``ownership`` is ``fabric_owned`` or ``caller_owned``. ``connection`` is a sanitized summary that never contains credential values, while ``metadata`` contains adapter-reported version and readiness information.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `service_id` | `str` |
| `service_binding` | `str` |
| `adapter_id` | `str` |
| `service_type` | `str` |
| `ownership` | `str` |
| `connection` | `Mapping[str, Any]` |
| `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 `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 `RunUsage`
Normalized invocation-local usage reported by an adapter target.
Missing counters and cost are unknown, not zero. ``cached_input_tokens`` records cache usage; ``input_tokens_include_cache`` declares whether input already includes that count. An absent flag means the semantics are unknown. Descriptor-declared detailed usage is preserved in ``metadata``.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `input_tokens` | `int \| None` |
| `cached_input_tokens` | `int \| None` |
| `input_tokens_include_cache` | `bool \| None` |
| `output_tokens` | `int \| None` |
| `total_tokens` | `int \| None` |
| `cost_usd` | `float \| 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 `RuntimeResourceSnapshot`
Timestamped resource usage of one runtime's local adapter host process tree.
Memory, process count, and CPU time cover the adapter host process and its live descendants, not a shared service process. Values that cannot be read raise an error instead of reading as zero.
**Attributes:**
- `runtime_id`: Runtime this snapshot describes.
- `started_at`: When NeMo Fabric started the adapter host, as RFC 3339 UTC.
- `observed_at`: When NeMo Fabric read these values, as RFC 3339 UTC.
- `resident_memory_bytes`: Sum of the live processes' resident set sizes. Pages shared between processes count once per process.
- `process_count`: Live processes in the tree, including the adapter host.
- `cpu_time_seconds`: CPU time used since the adapter host started, including exited descendants. It can drop when a descendant leaves the tree.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `runtime_id` | `str` |
| `started_at` | `str` |
| `observed_at` | `str` |
| `resident_memory_bytes` | `int` |
| `process_count` | `int` |
| `cpu_time_seconds` | `float` |
### 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 `ResourceObservation`
Adapter host process-tree reading, or an explicit collection failure.
**Attributes:**
- `status`: ``available``, ``unavailable``, ``unsupported``, or ``not_collected``.
- `snapshot`: Present only when available; a ``RuntimeResourceSnapshot``.
- `reason`: Present only when unavailable or unsupported.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `status` | `str` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### property reason
Return the collection failure reason, otherwise None.
---
### property snapshot
Return the reading when available, otherwise None.
---
### 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 `Measurement`
Measured numeric value, an unlimited limit, or explicit missing evidence.
**Attributes:**
- `status`: available, unlimited, unavailable, unsupported, or not_collected.
- `value`: Numeric reading when available, otherwise None.
- `reason`: Collection failure/capability reason, otherwise None.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `status` | `str` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### property reason
Return the reason for missing evidence, otherwise None.
---
### property value
Return an available reading, otherwise None.
---
### 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 `CgroupSnapshot`
Native adapter-host cgroup measurements, separate from process RSS.
Counters cover this cgroup and its descendants, potentially including other workloads. Limits are visible ancestor bounds; hidden ancestors and actual exclusive capacity are unknown. memory_peak_bytes covers cgroup lifetime or its last external reset, never this invocation's peak.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `source` | `str` |
| `scope` | `str` |
| `target` | `str` |
| `observed_at` | `str` |
| `visible_cpu_limit_cores` | `Measurement` |
| `visible_memory_limit_bytes` | `Measurement` |
| `memory_current_bytes` | `Measurement` |
| `memory_peak_bytes` | `Measurement` |
| `swap_current_bytes` | `Measurement` |
| `cpu_usage_microseconds` | `Measurement` |
| `cpu_throttled_microseconds` | `Measurement` |
| `oom_kills` | `Measurement` |
| `pressure_stall_microseconds` | `Mapping[str, Measurement]` |
### 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 `CgroupObservation`
Native cgroup snapshot or explicit unavailable/unsupported reason.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `status` | `str` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property extra_fields
Return an immutable view of preserved extension fields.
---
### property reason
Return the missing-evidence reason, otherwise None.
---
### property snapshot
Return the cgroup reading, otherwise None.
---
### 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 `CgroupStats`
Cgroup endpoint observations and counter deltas over an invocation.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `before` | `CgroupObservation` |
| `after` | `CgroupObservation` |
| `cpu_usage_microseconds` | `Measurement` |
| `cpu_throttled_microseconds` | `Measurement` |
| `oom_kills` | `Measurement` |
### 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 `GaugeSummary`
Sampled gauge extrema, hold-last-value mean, and covered time.
Sampled peak is not true high-water. Means exclude missing readings and gaps longer than twice the requested cadence. covered_fraction discloses how much of the invocation contributes to the mean.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `unit` | `str` |
| `final_value` | `int \| None` |
| `min` | `int \| None` |
| `sampled_peak` | `int \| None` |
| `time_weighted_mean` | `float \| None` |
| `valid_samples` | `int` |
| `covered_seconds` | `float` |
| `covered_fraction` | `float` |
### 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 `SampleSummary`
Retained native series, reductions, and collection-quality diagnostics.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `target_interval_ms` | `int` |
| `max_samples` | `int` |
| `sample_count` | `int` |
| `dropped_samples` | `int` |
| `largest_gap_seconds` | `float` |
| `collection_seconds` | `float` |
| `truncated` | `bool` |
| `diagnostics` | `Sequence[str]` |
| `samples` | `ArtifactRef \| None` |
| `cgroup_target_continuous` | `bool` |
| `resident_memory_bytes` | `GaugeSummary \| None` |
| `process_count` | `GaugeSummary \| None` |
| `cpu_time_seconds_estimate` | `Measurement` |
| `cpu_percent_one_core` | `Measurement` |
### 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 `InvocationSystemStats`
System measurements for one invocation in its executing runner.
Observations cover the adapter host process tree, excluding the orchestrator and remote services. Endpoints are neither peaks nor time averages.
**Attributes:**
- `elapsed_seconds`: Monotonic adapter exchange duration, excluding startup, endpoint collection, artifact preparation, and teardown.
- `before`: Observation immediately before the adapter exchange.
- `after`: Observation immediately after the exchange, under the same lock.
- `cgroup`: Native adapter-host cgroup readings and counter deltas, or None.
- `sampled`: Optional retained series, gauge reductions, and collection quality.
- `cpu_time_seconds_estimate`: Nonnegative CPU counter difference, or None if an endpoint is missing, identities differ, or the counter fell. Process reaping and reparenting can make this underestimate work.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `cgroup` | `CgroupStats \| None` |
| `sampled` | `SampleSummary \| None` |
| `collected_groups` | `Sequence[str]` |
| `elapsed_seconds` | `float` |
| `before` | `ResourceObservation` |
| `after` | `ResourceObservation` |
### method `__init__`
```python
def __init__(mapping: Mapping[str, Any]) -> None
```
---
### property cpu_time_seconds_estimate
Return the CPU counter difference estimate, or None when unknown.
---
### 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 `VersionObservation`
Read-only version observation with source, origin and original capture time.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `status` | `str` |
| `value` | `str \| None` |
| `reason` | `str \| None` |
| `source` | `str` |
| `origin` | `str` |
| `observed_at` | `str` |
### 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]
```
---
## class `SoftwareEntry`
One selected software component.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `role` | `str` |
| `kind` | `str` |
| `name` | `str` |
| `version` | `VersionObservation` |
### 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 `SoftwareEnvironment`
Observed installation context and selected coverage.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `context_ref` | `str` |
| `participants` | `Sequence[str]` |
| `status` | `str` |
| `complete` | `bool` |
| `reason` | `str \| None` |
| `entries` | `Sequence[SoftwareEntry]` |
### 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]
```
---
## class `ExecutionEvidence`
Selected software evidence; malformed reports become explicit coverage gaps.
### Fields
The mapping exposes the following typed fields:
| Field | Type |
| --- | --- |
| `software_environments` | `Sequence[SoftwareEnvironment]` |
| `infrastructure` | `Mapping[str, Any] \| None` |
### 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
```
---
### 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]
```
---
## 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.
- `usage`: Normalized invocation usage, or ``None`` when unavailable.
- `execution`: Selected software inventories and conditional owner reports, or ``None`` in older results and when collection is disabled.
- `resource_snapshot`: Runtime resource snapshot read once after the adapter returned this result, or ``None`` when the runtime's resources could not be observed.
- `system_stats`: Invocation duration and endpoint observations, or None for older results or execution backends without collection.
- `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` |
| `usage` | `RunUsage \| None` |
| `system_stats` | `InvocationSystemStats \| None` |
| `execution` | `ExecutionEvidence \| None` |
| `resource_snapshot` | `RuntimeResourceSnapshot \| 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)._