[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75SR5PB70GHKA6WS8K22XMB":3,"skill-same:01M75SR5PB70GHKA6WS8K22XMB":81},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":31,"ownerHtmlUrl":32,"ownerBlogUrl":33,"ownerDescription":6,"updatedAt":34,"install":35,"resources":48},"01M75SR5PB70GHKA6WS8K22XMB","nemo-fabric-integrate",null,"Use this skill when integrating NVIDIA NeMo Fabric into a consumer application, service, evaluation harness, or platform through the typed Python SDK — translating the consumer's own application, job, or deployment config into an in-memory FabricConfig, choosing the single-invocation convenience API or an explicitly started runtime, validating with plan and doctor, and consuming normalized results, artifacts, and telemetry.","NVIDIA\u002FNeMo-Fabric","NVIDIA","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1728152?v=4","01M6BXXZYTRNBXSTRXNNBB356H","NVIDIA Corporation","01M75SNZXW1HWMCP6S3FTXPVA9",75,"Apache-2.0","https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fskills\u002Fnemo-fabric-integrate\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: nemo-fabric-integrate\ndescription: Use this skill when integrating NVIDIA NeMo Fabric into a consumer application, service, evaluation harness, or platform through the typed Python SDK — translating the consumer's own application, job, or deployment config into an in-memory FabricConfig, choosing the single-invocation convenience API or an explicitly started runtime, validating with plan and doctor, and consuming normalized results, artifacts, and telemetry.\nlicense: Apache-2.0\nmetadata:\n  author: NVIDIA Corporation and Affiliates\n---\n\n# Integrate NVIDIA NeMo Fabric Through The Python SDK\n\nUse this skill when a consumer codebase — an application, service, evaluation\nharness, or platform — needs to run agent harnesses through NeMo Fabric's typed\nPython SDK. The consumer owns its own configuration object and translates it\ninto an in-memory `FabricConfig`; NeMo Fabric owns adapter selection, the runtime\nlifecycle, and normalized results.\n\n## Integration Boundary\n\nUse the public, in-memory contract. These rules keep a consumer integration\nsupported and upgrade-safe:\n\n- Import only from the public `nemo_fabric` package. Never import `_native` or\n  any adapter-internal module.\n- Build configuration as a typed `FabricConfig` in memory and pass it directly to\n  NeMo Fabric. Create every deployment or evaluation variant with ordinary Python\n  functions and `model_copy(deep=True)`. A platform integration can serialize\n  the typed config inside a private transient run specification when it crosses\n  a process boundary; that transport is not a public authoring format.\n- Let NeMo Fabric own harness control. Do not reimplement start, invoke, or stop\n  logic, and do not manage adapter threads, sessions, or processes directly.\n- Treat `runtime_id`, `invocation_id`, and `request_id` as opaque correlation\n  strings, not parsable or reusable state.\n\nRefer to [config-mapping.md](references\u002Fconfig-mapping.md) for how to translate a\nconsumer config object into `FabricConfig`, and for the full list of mechanics\nthat stay hidden behind this boundary.\n\n## Install And Set Up The Environment\n\nThe consumer or its execution environment owns installation; NeMo Fabric validates\nruntime assumptions but never installs harnesses or credentials at run time.\n\n- Choose supported Python interpreters for the runtime, Harbor, and adapter\n  environments from the\n  [installation guide](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fgetting-started\u002Finstall.mdx).\n- Install the runtime with `uv pip install nemo-fabric` (add the `harbor` extra\n  for the Harbor integration).\n- Select the harness adapter through `HarnessConfig.adapter_id`. To install the\n  NeMo Fabric runtime, adapter, and supported harness in one environment, use\n  `nemo-fabric[claude]`, `nemo-fabric[codex]`,\n  or `nemo-fabric[deepagents]`.\n- Install Hermes Agent separately from the Fabric adapter. Follow the\n  [Hermes integration guide](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fintegrations\u002Fharness\u002Fhermes\u002Fhermes.mdx)\n  for the current compatible interpreter, source checkout, Relay dependencies,\n  and adapter installation. The `nemo-fabric[hermes-agent]` extra does not\n  install Hermes Agent.\n- In a separate adapter environment, install\n  `nemo-fabric-adapters-\u003Cadapter>[harness]`. This installs the adapter and\n  supported harness dependencies without the NeMo Fabric runtime. Use `full`\n  instead when that adapter package provides package-installable optional\n  integrations.\n- Point the runtime to a separate adapter environment with `ADAPTER_PYTHON`.\n  Use matching NeMo Fabric release versions for the runtime and adapter package\n  unless a different pairing has been explicitly validated.\n- If the adapter environment already manages a compatible harness, install the\n  bare `nemo-fabric-adapters-\u003Cadapter>` distribution. Bare adapter\n  distributions contain only adapter-owned runtime dependencies.\n- LangChain Deep Agents and Hermes adapter packages provide `relay` and include\n  the NeMo Relay Python package in `full`. Claude and Codex do not provide\n  `relay`; their `harness` and `full` extras install the supported `nemo-relay`\n  CLI alongside the harness SDK.\n- Provide model credentials through environment variables named by the config\n  (`ModelConfig.api_key_env`), never as literals in code.\n- Forward other existing variables with `EnvironmentConfig.env_names`; only names are stored in configuration and run plans. `EnvironmentConfig.env` supplies literal values and does not expand `$NAME` references. Neither field loads a `.env` file.\n- Keep named environment values unchanged while a runtime or service is active. NeMo Fabric rejects changed or unset values before invocation; restart the runtime and any associated service after changing them. With Harbor, deliver values into the task environment through Harbor's managed environment first.\n- Confirm the native extension is importable; SDK calls raise\n  `FabricNativeUnavailableError` when it is missing.\n- For descriptor inspection without harness SDKs, install the separate `nemo-fabric-adapter-catalog` package and call `nemo_fabric_adapter_catalog.get_adapter_descriptor(adapter_id)` or `get_target_descriptor(target_id)`. Refer to the [catalog guide](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fsdk\u002Fpython\u002Fnemo-fabric-adapter-catalog\u002FREADME.md). Catalog resources do not register execution runners; unknown IDs raise `KeyError`. Validate against the task environment's descriptor before relying on a snapshot claim. Catalog source versions and fingerprints are not runtime-observed provenance.\n\n## Build The Typed Config From Consumer Config\n\nMap the consumer's application, job, or deployment object into a `FabricConfig`\nwith the public models and helper methods:\n\n```python\nfrom nemo_fabric import (\n    FabricConfig,\n    HarnessConfig,\n    InstructionConfig,\n    InstructionsConfig,\n    MetadataConfig,\n    ModelConfig,\n    RuntimeConfig,\n    ToolsConfig,\n)\n\n\ndef to_tools_config(job) -> ToolsConfig | None:\n    enabled = job.enabled_tools\n    blocked = list(job.blocked_tools)\n    if enabled is None and not blocked:\n        return None\n    return ToolsConfig(\n        enabled=None if enabled is None else list(enabled),\n        blocked=blocked,\n    )\n\n\ndef to_fabric_config(job) -> FabricConfig:\n    config = FabricConfig(\n        metadata=MetadataConfig(name=job.name),\n        harness=HarnessConfig(adapter_id=job.adapter_id, resolution=\"preinstalled\"),\n        models={\n            \"default\": ModelConfig(\n                provider=job.provider,\n                model=job.model,\n                api_key_env=job.api_key_env,\n                base_url=job.base_url,\n            )\n        },\n        instructions=(\n            InstructionsConfig(\n                system=InstructionConfig(\n                    content=job.system_instruction,\n                    mode=job.system_instruction_mode,\n                ),\n            )\n            if job.system_instruction is not None\n            else None\n        ),\n        runtime=RuntimeConfig(\n            input_schema=\"chat\",\n            output_schema=\"message\",\n            timeout_seconds=job.timeout_seconds,\n            max_turns=job.max_turns,\n        ),\n        tools=to_tools_config(job),\n    )\n    config.add_skill_path(job.skill_dir)\n    config.add_mcp_server(\n        \"github\",\n        transport=\"streamable-http\",\n        url=\"${GITHUB_MCP_URL}\",\n        exposure=\"harness_native\",\n    )\n    return config\n```\n\n- Shape capabilities with `ToolsConfig`, `add_tool_definition`, `block_tools`, `add_skill_path`,\n  `remove_skill_path`,\n  `add_mcp_server`, `remove_mcp_server`, and `enable_relay`.\n- Use `add_tool_definition` only when the selected adapter accepts\n  `tools.definitions` and publishes a `tool_definition_schema`.\n- Use a restricted `allowed_tools` list or non-empty `blocked_tools` on\n  `add_mcp_server` only when the selected adapter declares both `mcp` and\n  `mcp.tool_filters`. An unfiltered server requires only `mcp`.\n  `allowed_tools=None` exposes every discovered tool, while an empty list\n  exposes none; blocked tools are removed after applying that allowlist. Tool\n  names must be non-blank, and planning rejects a tool that appears in both\n  lists.\n- Configure MCP authentication only when the selected adapter declares\n  `mcp.auth.oauth2` or `mcp.auth.service_account`, matching the authentication\n  type.\n- Create deployment or evaluation variants with `model_copy(deep=True)` and\n  ordinary Python functions; each copy plans and runs independently.\n- Pass `base_dir=...` to any `Fabric` call when the config uses relative paths,\n  so skills, workspaces, and artifacts anchor to the consumer's own layout.\n\nThe repository [`code_review_agent` example](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Ftree\u002Fmain\u002Fexamples\u002Fcode_review_agent)\nshows this pattern end to end with complete Hermes Agent, Codex, Deep Agents,\nenvironment, MCP, and telemetry variants. Reuse it rather than duplicating config\nconstruction.\n\n## Choose A Lifecycle\n\nFor Hermes, embedded SDK execution is enabled and eager by default. Set `harness.settings.sdk.enabled=False` only for native-only runtimes with an enabled API, dashboard, or terminal interface; management through the SDK remains available, but invocation fails explicitly. Browser and terminal clients share one managed TUI backend. Native responses remain native even when Relay emits standard ATOF\u002FATIF; do not treat them as SDK `RunResult` objects. Follow the [Hermes invocation guides](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fintegrations\u002Fharness\u002Fhermes\u002Fhermes.mdx) for interface-specific installation and attachment.\n\nFor Deep Agents, mini-SWE-agent, and the LangGraph custom-agent example, pass the same UUID string through `RunRequest.relay_session_root` on each conversation turn to group Relay trajectories under one session. Core forwards the typed field as `AgentRunRequest.relay_session_root`; context keys do not control Relay propagation. An unusable UUID preserves per-request behavior. The remaining adapters do not consume this field.\n\nFor Hermes cold resume, configure `runtime.keep_state` and retain the complete\nartifact state tree. Persist `Runtime.session_ref.to_mapping()` in caller-owned\nstorage and pass `session_ref=SessionRef.from_mapping(saved_reference)`\nto `Fabric.start_runtime()`, `start_runtime_in()`, or `run()`. A new runtime ID\ndoes not change the selected session. Retention alone starts a fresh\nconversation. Never select the latest conversation implicitly. Agent names are\nlabels, while the reference's adapter must match. Handle `state_in_use` and\nmissing or incompatible session errors explicitly. Inspect\n`Runtime.recovery_warnings` before continuing an uncertain session. Send a new\n`RunRequest(..., acknowledge_recovery=True)` only after inspecting native and\nexternal state. Do not replay an interrupted request automatically. Keep\nownership and retry cleanup when stop is unconfirmed. Native Hermes API and\ndashboard behavior remains owned by Hermes.\n\nHermes `SessionRef` resume requires the SDK backend to be enabled. Native-only Hermes runtimes can retain state and report `RunPlan.capabilities.session_resume: false`. Explicit SDK session selection then fails with `session_resume_unsupported` before native startup.\n\nPick the smallest lifecycle the consumer needs:\n\n- **Single invocation** — one input, no retained state after the call.\n  `await Fabric().run(config, input=...)` runs the full start, invoke, and stop\n  cycle and returns a `RunResult`. Pass\n  `request=RunRequest(...)` instead of `input=...` when the invocation needs a\n  caller-owned request ID or context (the two are mutually exclusive).\n- **Stateful runtime** — ordered turns over one logical harness lifecycle. Start it with\n  `start_runtime(...)` and use the returned `Runtime` as an async context\n  manager so cleanup runs on exit — shutdown is attempted, not guaranteed\n  (`stop()` can raise `FabricRuntimeError`; see Consume Results And Handle\n  Errors). A runtime accepts one active invocation at a time; overlapping calls\n  raise `FabricStateError`.\n- **Native OpenAI stream** — adapter-native OpenAI Chat Completions chunks plus\n  a separate terminal normalized result. Check\n  `runtime.supports_openai_streaming`, call\n  `runtime.invoke_openai_stream(...)`, iterate the returned\n  `OpenAIInvokeStream`, and then await `stream.result()`. The selected adapter\n  descriptor must declare `capabilities.streaming`. Each yielded mapping has\n  `object == \"chat.completion.chunk\"`; an empty stream is valid. If iteration\n  stops early, call `await stream.aclose()` to drain without cancelling the\n  target invocation. This path does not require NeMo Relay or\n  `streaming=True`.\n- **NVIDIA NeMo Relay stream** — live, raw ATOF records plus a terminal normalized\n  result. Install `nemo-fabric[streaming]` to include the matching collector for\n  the default embedded streaming path. Enable NeMo Relay, pass `streaming=True`\n  to `start_runtime(...)`, call\n  `runtime.invoke_stream(...)`, iterate the returned `InvokeStream`, and then\n  await `stream.result()`. Iteration ending does not indicate invocation\n  success; invocation exceptions raise from `result()`, while harness-reported\n  failures remain normalized `RunResult` values. If iteration stops early,\n  call `await stream.aclose()` before starting another turn. `aclose()` waits\n  for the turn to finish; it does not cancel the harness invocation. The SDK\n  intentionally exposes only ATOF records generated by NeMo Relay. This path is\n  independent of native OpenAI streaming. The collector registers the request\n  before the agent is invoked, then routes the matching ATOF root scope and its\n  descendants by request ID and UUID ancestry. By default, streaming starts an\n  embedded collector. Set `launch_collector=False` to use an externally managed\n  collector; configure its base URL as the `nemo-fabric-stream` sink with\n  `transport=\"ndjson\"`. The runtime directs Relay to `\u003Cbase-url>\u002Fv1\u002Fatof` and\n  uses the collector control and stream endpoints. The bundled Pi adapter requires\n  the embedded collector. Do not set `launch_collector=False` for Pi streaming.\n  The embedded collector waits up to `completion_wait_timeout` seconds (1.0 by\n  default) for a late `agent_settled` marker. The collector limits each record to\n  1 MiB and each request queue to 1,024 records or 16 MiB of encoded\n  data. The `streaming=True` flag does not enable NeMo Relay by itself. Without\n  `streaming=True`, startup leaves the NeMo Relay configuration unchanged.\n\nFor explicit environment management, call `prepare_environment(config)` or\n`attach_environment(config, reference)`, then `start_runtime_in(config, environment)`.\nUse typed `EnvironmentHandle` and `EnvironmentReference` objects. Stop the\nruntime before calling `release_environment(environment)` separately. Provider\navailability and reuse limits vary; task paths must remain strings for non-local\nenvironments. See the [environment lifecycle guide](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fsdk\u002Fpython.mdx#explicit-environment-lifecycle).\n\nUse `await fabric.runtime_status(runtime_id=runtime_id, agent_name=name)` to read recorded state and a safe discovery handle for a runtime started by the same `Fabric` instance. The client retains live runtime objects until successful stop. Add `environment=environment` for an OpenShell lookup through `fabric-agent-ctl status`, including from a later client process while the original server remains alive. `RuntimeStatusReport` reports `active`, `stopped`, or `failed`; `server_state` is present for server reads and null for direct local reads. Each client holds at most 128 runtime records, including pending starts. New starts evict the oldest successfully stopped records first; when active, failed, and pending runtimes fill the limit, startup raises `FabricStateError` with `code=\"runtime_limit_reached\"`. Retained stopped records have a null handle. Discovery handles omit environment variable values and arbitrary provider metadata; use the original `Runtime` for invocation and cleanup. Status reads perform no lifecycle operation or health probe. Use `Fabric.check()` when the consumer needs fresh health evidence.\n\nThe selected adapter owns the execution topology. The bundled Claude, Codex,\nDeep Agents, and Hermes Agent adapters retain their native client, graph\u002Fcheckpointer,\nor agent\u002Fdatabase inside one local host for the full runtime. Local `process`\nand `python` adapters use this host lifecycle; consumers do not select another\nlocal execution mechanism in `FabricConfig`. Do not replay an invocation after\na runtime failure. Stop the failed runtime and explicitly start a new one\naccording to the application's retry policy.\n\nThe lifecycle fragment below shows the available forms. It assumes the caller\nhas already set `config = to_fabric_config(job)` and chosen `base`, as described\nin the configuration example above:\n\n```python\nimport asyncio\n\nfrom nemo_fabric import Fabric\n\n\nasync def main() -> None:\n    fabric = Fabric()\n\n    # Single invocation\n    result = await fabric.run(config, base_dir=base, input=\"Review the changes.\")\n\n    # Multi-turn\n    async with await fabric.start_runtime(config, base_dir=base) as runtime:\n        first = await runtime.invoke(input=\"Inspect the repository\")\n        second = await runtime.invoke(input=\"Now review the latest patch\")\n\n    # Adapter-native OpenAI Chat Completions chunks\n    async with await fabric.start_runtime(config, base_dir=base) as runtime:\n        if runtime.supports_openai_streaming:\n            stream = runtime.invoke_openai_stream(input=\"Review the latest patch\")\n            async for chunk in stream:\n                print(chunk)\n            openai_streamed_result = await stream.result()\n\n    # NeMo Relay streaming\n    streaming_config = config.model_copy(deep=True).enable_relay()\n    async with await fabric.start_runtime(\n        streaming_config,\n        base_dir=base,\n        streaming=True,\n    ) as runtime:\n        stream = runtime.invoke_stream(input=\"Review the latest patch\")\n        async for record in stream:\n            print(record)\n        streamed_result = await stream.result()\n\n\nasyncio.run(main())\n```\n\nNeMo Fabric owns no application scheduling queue, worker pool, retry policy, or\nglobal concurrency policy. Each runtime still permits only one active\ninvocation; start independent runtimes for parallel work. The NeMo Relay\nstreaming path uses an internal bounded transport queue and TCP backpressure\nonly to carry one invocation's ATOF records. Treat `stream.result()` as\nauthoritative, and reconstruct nested work from ATOF `uuid` and `parent_uuid`\nfields rather than stream order.\n\nFor native OpenAI streaming, the SDK owns the authenticated loopback HTTP\ntransport, chunked NDJSON framing, and correlation values. Consumer code\nsupplies no listener or credentials. The adapter executes exactly one\ninvocation, and the terminal `RunResult` remains separate from the chunk stream.\nFully consume the stream or call `await stream.aclose()` before starting another\nturn. Awaiting `stream.result()` also drains and discards unread native OpenAI\nchunks, so consume the iterator first when the application needs every chunk.\n\n## Validate Before Running\n\nResolve and diagnose before spending work on a runtime, especially in a new\nenvironment or before relying on an optional capability:\n\n```python\nfabric = Fabric()\nplan = fabric.plan(config, base_dir=base)             # sync: adapter + capabilities\nreport = await fabric.doctor(config, base_dir=base)   # async: preflight checks\n\nprint(plan.adapter.adapter_id, report.status)\n```\n\n- Use `plan(...)` to confirm adapter selection and capability routing before\n  running. Planning validates `harness.settings` against the exact resolved\n  Adapter Descriptor and, when present, `workflow.settings` against the exact\n  resolved Adapter Target Descriptor.\n- Use `doctor(...)` to check adapter availability, resolution, environment\n  context, and declared requirements such as required environment variables. Its\n  aggregate `status` is `pass`, `warn`, or `fail`. Invalid, unknown, or\n  misspelled adapter settings fail before diagnostics or runtime startup. A\n  resolved descriptor without a settings schema accepts only an empty settings\n  map.\n- For a separate admission host, call public `inspect_adapter(config, descriptor)`\n  with matching catalog or canonical external metadata. The immutable\n  `AdapterCapabilityProfile` has `adapter_id`, `descriptor_sha256`, `skills`,\n  `mcp`, and `atif` fields. It does not import harness SDKs or read task-local\n  discovery paths. Missing metadata makes conservative claims and rejects\n  requested optional features. Pass `expected_descriptor_sha256=profile.descriptor_sha256`\n  to task-side `run()` or `start_runtime()` to reject descriptor drift before\n  startup. For a registered workflow, also pass\n  `target_descriptor=get_target_descriptor(config.workflow.target_id)` from the\n  matching catalog or canonical external metadata. The fingerprint then binds\n  both normalized descriptors, including the target factory and settings schema;\n  missing or mismatched metadata fails admission. Standalone fingerprints stay\n  unchanged. Attached services need separate admission. Declared support is not\n  runtime provenance or proof of an artifact.\n\n## Consume Results And Handle Errors\n\nEvery invocation that reaches the adapter boundary returns a normalized\n`RunResult`, even when the harness invocation itself failed. Inspect the failure\nfields before reading output:\n\n```python\nresult = await fabric.run(config, base_dir=base, input=\"Review the changes.\")\n\nif result.status == \"succeeded\":\n    use_output(result.output, result.artifacts, result.telemetry)\nelse:\n    handle_failure(result.status, result.error, result.events)  # failed, cancelled, ...\n```\n\n- Treat `status == \"succeeded\"` as the only success. Other terminal values\n  (`failed`, `cancelled`) are unsuccessful, so branch on `status`, not on\n  `error`. Read `status`, `error`, and `events` before processing `output`.\n- Capture `artifacts` and `telemetry` references as the returned evidence for\n  platforms and evaluations. Store and log `runtime_id`, `invocation_id`, and\n  `request_id` separately as opaque strings.\n- Catch `FabricError` subclasses for lifecycle failures that prevent a\n  normalized result: `FabricConfigError`, `FabricCapabilityError`,\n  `FabricRuntimeError`, `FabricStateError`, and `FabricNativeUnavailableError`.\n- The consumer owns retries and failure policy; NeMo Fabric does not retry by\n  default. `run(...)` and `async with` runtimes attempt cleanup automatically,\n  so prefer them over manual `stop()` — but shutdown is not guaranteed: `stop()`,\n  including the automatic call when an `async with` block exits, can raise\n  `FabricRuntimeError`. On a normal exit that error propagates; after an\n  invocation error the cleanup failure is attached to the original exception. Be\n  ready to handle a shutdown failure.\n\nRefer to [results-and-errors.md](references\u002Fresults-and-errors.md) for the full\nresult-field and error inventory, and\n[sdk-api-inventory.md](references\u002Fsdk-api-inventory.md) for when to use each\n`Fabric` and `Runtime` method.\n\n## Test And Validate The Integration\n\n- Write focused integration tests that build the consumer's `FabricConfig`,\n  assert `plan(...)` selects the expected adapter and capabilities, and — where\n  a harness and credentials are available — run one invocation and assert the\n  `RunResult` status and evidence.\n- `plan(...)` is credential-free — use it as the CI gate that validates adapter\n  selection and capability routing without a model or secrets. `doctor(...)` also\n  runs without calling a model, but it checks declared environment requirements\n  (such as required API-key variables) and returns `fail` when they are unset, so\n  run it where the environment is provisioned and read its per-check results.\n- Run the consumer project's own build and test commands. For a source checkout\n  of NeMo Fabric, `just build-all` rebuilds the native extension and\n  `just test-python` runs the Python suite.\n- Confirm the typed config is passed directly to NeMo Fabric and no non-public\n  imports were added.\n\n## Checklist\n\n- [ ] The consumer config object is translated directly into an in-memory `FabricConfig`.\n- [ ] Only public `nemo_fabric` symbols are imported; no `_native` or adapter internals.\n- [ ] The consumer config is built in memory and passed directly to NeMo Fabric.\n- [ ] The right lifecycle is chosen: `run(...)` for a single invocation,\n  `start_runtime(...)` with `async with` for multi-turn,\n  `invoke_openai_stream(...)` for descriptor-gated OpenAI chunks, or\n  `invoke_stream(...)` for raw NeMo Relay ATOF.\n- [ ] `plan(...)` and `doctor(...)` validate adapter selection, capabilities, and environment before execution.\n- [ ] Installation, adapter dependencies, and credentials are owned by the environment, not consumer code.\n- [ ] `RunResult` status, error, and events are inspected before output; artifacts and telemetry are captured.\n- [ ] `FabricError` subclasses are handled, including a `FabricRuntimeError` raised by shutdown; cleanup is delegated to `run(...)` or `async with` (attempted, not guaranteed).\n- [ ] Correlation IDs are stored and logged as opaque strings.\n- [ ] Focused integration tests pass and NeMo Fabric validation (`plan`\u002F`doctor`, tests) succeeds.\n\n## Related Documentation\n\nLink to these canonical sources instead of duplicating them:\n\n- [Python SDK guide](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fsdk\u002Fpython.mdx)\n- [Resource usage and stats](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fsdk\u002Fsystem-stats.mdx) for collection controls, local and remote scope, sample quality, and repeatable code-review and Harbor examples. Harbor accepts the SDK configuration through `fabric_system_stats`; omission uses before\u002Fafter collection, and explicit null disables invocation stats.\n- [NeMo Fabric overview](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fabout-nemo-fabric\u002Foverview.mdx) and\n  [installation guide](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fgetting-started\u002Finstall.mdx)\n- Generated API reference (public API index; the installed `nemo_fabric` type\n  stubs are authoritative for exact signatures, fields, and defaults):\n  [client](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.client.md),\n  [runtime](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.runtime.md),\n  [native OpenAI streaming](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.openai_streaming.md),\n  [Relay streaming](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.streaming.md),\n  [models](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.models.md),\n  [types](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.types.md),\n  [errors](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.errors.md)\n- Canonical in-memory config example:\n  [examples\u002Fcode_review_agent](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Ftree\u002Fmain\u002Fexamples\u002Fcode_review_agent)\n- Platform and evaluation-harness integration:\n  [examples\u002Fharbor](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Ftree\u002Fmain\u002Fexamples\u002Fharbor) and\n  [nemo_fabric.integrations.harbor](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Ftree\u002Fmain\u002Fsdk\u002Fpython\u002Fnemo-fabric-runtime\u002Fsrc\u002Fnemo_fabric\u002Fintegrations\u002Fharbor).\n  Omit `fabric_model_provider` to retain provider inference from the model name. Override it only when the selected adapter requires a different value; an OpenAI-compatible endpoint alone is not a reason to set `openai`. For example, keep the inferred `nvidia` provider for Mini-SWE and OpenHands with `nvidia\u002Fnemotron-3-ultra-550b-a55b`: both adapters add the LiteLLM `nvidia_nim\u002F` dispatch prefix. Overriding with `openai` passes this model ID unchanged to LiteLLM, which cannot infer its provider.\n  Use `fabric_model_settings` for adapter-declared `models.default.settings`;\n  a model is required and its descriptor still validates those settings. Keep\n  model credentials in Harbor's managed environment variables.\n  Harbor constructs a typed config from explicit agent inputs and transports it\n  inside a private transient run specification at the task-process boundary.\n  Follow the code-review example for consumer integration code; Harbor's\n  transport representation is an internal process-boundary contract.\n\n### Software Evidence\n\nInspect optional `RunResult.execution` for selected software inventories. Preserve full version values, status\u002Freasons, source, origin and original `observed_at` when forwarding. Context refs are result-local; participants describe installation users. Use `FabricConfig.provenance=ProvenanceConfig(enabled=False)` before startup to disable collectors on host and guest. Explicit owner snapshots use typed `ProvenanceConfig.reports` through existing configuration dispatch; guests never inspect the caller installation. Old results can omit execution evidence. Unknown or incomplete reports are not proof of equal environments.\n","# Integrate NVIDIA NeMo Fabric Through The Python SDK\n\nUse this skill when a consumer codebase — an application, service, evaluation\nharness, or platform — needs to run agent harnesses through NeMo Fabric's typed\nPython SDK. The consumer owns its own configuration object and translates it\ninto an in-memory `FabricConfig`; NeMo Fabric owns adapter selection, the runtime\nlifecycle, and normalized results.\n\n## Integration Boundary\n\nUse the public, in-memory contract. These rules keep a consumer integration\nsupported and upgrade-safe:\n\n- Import only from the public `nemo_fabric` package. Never import `_native` or\n  any adapter-internal module.\n- Build configuration as a typed `FabricConfig` in memory and pass it directly to\n  NeMo Fabric. Create every deployment or evaluation variant with ordinary Python\n  functions and `model_copy(deep=True)`. A platform integration can serialize\n  the typed config inside a private transient run specification when it crosses\n  a process boundary; that transport is not a public authoring format.\n- Let NeMo Fabric own harness control. Do not reimplement start, invoke, or stop\n  logic, and do not manage adapter threads, sessions, or processes directly.\n- Treat `runtime_id`, `invocation_id`, and `request_id` as opaque correlation\n  strings, not parsable or reusable state.\n\nRefer to [config-mapping.md](references\u002Fconfig-mapping.md) for how to translate a\nconsumer config object into `FabricConfig`, and for the full list of mechanics\nthat stay hidden behind this boundary.\n\n## Install And Set Up The Environment\n\nThe consumer or its execution environment owns installation; NeMo Fabric validates\nruntime assumptions but never installs harnesses or credentials at run time.\n\n- Choose supported Python interpreters for the runtime, Harbor, and adapter\n  environments from the\n  [installation guide](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fgetting-started\u002Finstall.mdx).\n- Install the runtime with `uv pip install nemo-fabric` (add the `harbor` extra\n  for the Harbor integration).\n- Select the harness adapter through `HarnessConfig.adapter_id`. To install the\n  NeMo Fabric runtime, adapter, and supported harness in one environment, use\n  `nemo-fabric[claude]`, `nemo-fabric[codex]`,\n  or `nemo-fabric[deepagents]`.\n- Install Hermes Agent separately from the Fabric adapter. Follow the\n  [Hermes integration guide](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fintegrations\u002Fharness\u002Fhermes\u002Fhermes.mdx)\n  for the current compatible interpreter, source checkout, Relay dependencies,\n  and adapter installation. The `nemo-fabric[hermes-agent]` extra does not\n  install Hermes Agent.\n- In a separate adapter environment, install\n  `nemo-fabric-adapters-\u003Cadapter>[harness]`. This installs the adapter and\n  supported harness dependencies without the NeMo Fabric runtime. Use `full`\n  instead when that adapter package provides package-installable optional\n  integrations.\n- Point the runtime to a separate adapter environment with `ADAPTER_PYTHON`.\n  Use matching NeMo Fabric release versions for the runtime and adapter package\n  unless a different pairing has been explicitly validated.\n- If the adapter environment already manages a compatible harness, install the\n  bare `nemo-fabric-adapters-\u003Cadapter>` distribution. Bare adapter\n  distributions contain only adapter-owned runtime dependencies.\n- LangChain Deep Agents and Hermes adapter packages provide `relay` and include\n  the NeMo Relay Python package in `full`. Claude and Codex do not provide\n  `relay`; their `harness` and `full` extras install the supported `nemo-relay`\n  CLI alongside the harness SDK.\n- Provide model credentials through environment variables named by the config\n  (`ModelConfig.api_key_env`), never as literals in code.\n- Forward other existing variables with `EnvironmentConfig.env_names`; only names are stored in configuration and run plans. `EnvironmentConfig.env` supplies literal values and does not expand `$NAME` references. Neither field loads a `.env` file.\n- Keep named environment values unchanged while a runtime or service is active. NeMo Fabric rejects changed or unset values before invocation; restart the runtime and any associated service after changing them. With Harbor, deliver values into the task environment through Harbor's managed environment first.\n- Confirm the native extension is importable; SDK calls raise\n  `FabricNativeUnavailableError` when it is missing.\n- For descriptor inspection without harness SDKs, install the separate `nemo-fabric-adapter-catalog` package and call `nemo_fabric_adapter_catalog.get_adapter_descriptor(adapter_id)` or `get_target_descriptor(target_id)`. Refer to the [catalog guide](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fsdk\u002Fpython\u002Fnemo-fabric-adapter-catalog\u002FREADME.md). Catalog resources do not register execution runners; unknown IDs raise `KeyError`. Validate against the task environment's descriptor before relying on a snapshot claim. Catalog source versions and fingerprints are not runtime-observed provenance.\n\n## Build The Typed Config From Consumer Config\n\nMap the consumer's application, job, or deployment object into a `FabricConfig`\nwith the public models and helper methods:\n\n```python\nfrom nemo_fabric import (\n    FabricConfig,\n    HarnessConfig,\n    InstructionConfig,\n    InstructionsConfig,\n    MetadataConfig,\n    ModelConfig,\n    RuntimeConfig,\n    ToolsConfig,\n)\n\n\ndef to_tools_config(job) -> ToolsConfig | None:\n    enabled = job.enabled_tools\n    blocked = list(job.blocked_tools)\n    if enabled is None and not blocked:\n        return None\n    return ToolsConfig(\n        enabled=None if enabled is None else list(enabled),\n        blocked=blocked,\n    )\n\n\ndef to_fabric_config(job) -> FabricConfig:\n    config = FabricConfig(\n        metadata=MetadataConfig(name=job.name),\n        harness=HarnessConfig(adapter_id=job.adapter_id, resolution=\"preinstalled\"),\n        models={\n            \"default\": ModelConfig(\n                provider=job.provider,\n                model=job.model,\n                api_key_env=job.api_key_env,\n                base_url=job.base_url,\n            )\n        },\n        instructions=(\n            InstructionsConfig(\n                system=InstructionConfig(\n                    content=job.system_instruction,\n                    mode=job.system_instruction_mode,\n                ),\n            )\n            if job.system_instruction is not None\n            else None\n        ),\n        runtime=RuntimeConfig(\n            input_schema=\"chat\",\n            output_schema=\"message\",\n            timeout_seconds=job.timeout_seconds,\n            max_turns=job.max_turns,\n        ),\n        tools=to_tools_config(job),\n    )\n    config.add_skill_path(job.skill_dir)\n    config.add_mcp_server(\n        \"github\",\n        transport=\"streamable-http\",\n        url=\"${GITHUB_MCP_URL}\",\n        exposure=\"harness_native\",\n    )\n    return config\n```\n\n- Shape capabilities with `ToolsConfig`, `add_tool_definition`, `block_tools`, `add_skill_path`,\n  `remove_skill_path`,\n  `add_mcp_server`, `remove_mcp_server`, and `enable_relay`.\n- Use `add_tool_definition` only when the selected adapter accepts\n  `tools.definitions` and publishes a `tool_definition_schema`.\n- Use a restricted `allowed_tools` list or non-empty `blocked_tools` on\n  `add_mcp_server` only when the selected adapter declares both `mcp` and\n  `mcp.tool_filters`. An unfiltered server requires only `mcp`.\n  `allowed_tools=None` exposes every discovered tool, while an empty list\n  exposes none; blocked tools are removed after applying that allowlist. Tool\n  names must be non-blank, and planning rejects a tool that appears in both\n  lists.\n- Configure MCP authentication only when the selected adapter declares\n  `mcp.auth.oauth2` or `mcp.auth.service_account`, matching the authentication\n  type.\n- Create deployment or evaluation variants with `model_copy(deep=True)` and\n  ordinary Python functions; each copy plans and runs independently.\n- Pass `base_dir=...` to any `Fabric` call when the config uses relative paths,\n  so skills, workspaces, and artifacts anchor to the consumer's own layout.\n\nThe repository [`code_review_agent` example](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Ftree\u002Fmain\u002Fexamples\u002Fcode_review_agent)\nshows this pattern end to end with complete Hermes Agent, Codex, Deep Agents,\nenvironment, MCP, and telemetry variants. Reuse it rather than duplicating config\nconstruction.\n\n## Choose A Lifecycle\n\nFor Hermes, embedded SDK execution is enabled and eager by default. Set `harness.settings.sdk.enabled=False` only for native-only runtimes with an enabled API, dashboard, or terminal interface; management through the SDK remains available, but invocation fails explicitly. Browser and terminal clients share one managed TUI backend. Native responses remain native even when Relay emits standard ATOF\u002FATIF; do not treat them as SDK `RunResult` objects. Follow the [Hermes invocation guides](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fintegrations\u002Fharness\u002Fhermes\u002Fhermes.mdx) for interface-specific installation and attachment.\n\nFor Deep Agents, mini-SWE-agent, and the LangGraph custom-agent example, pass the same UUID string through `RunRequest.relay_session_root` on each conversation turn to group Relay trajectories under one session. Core forwards the typed field as `AgentRunRequest.relay_session_root`; context keys do not control Relay propagation. An unusable UUID preserves per-request behavior. The remaining adapters do not consume this field.\n\nFor Hermes cold resume, configure `runtime.keep_state` and retain the complete\nartifact state tree. Persist `Runtime.session_ref.to_mapping()` in caller-owned\nstorage and pass `session_ref=SessionRef.from_mapping(saved_reference)`\nto `Fabric.start_runtime()`, `start_runtime_in()`, or `run()`. A new runtime ID\ndoes not change the selected session. Retention alone starts a fresh\nconversation. Never select the latest conversation implicitly. Agent names are\nlabels, while the reference's adapter must match. Handle `state_in_use` and\nmissing or incompatible session errors explicitly. Inspect\n`Runtime.recovery_warnings` before continuing an uncertain session. Send a new\n`RunRequest(..., acknowledge_recovery=True)` only after inspecting native and\nexternal state. Do not replay an interrupted request automatically. Keep\nownership and retry cleanup when stop is unconfirmed. Native Hermes API and\ndashboard behavior remains owned by Hermes.\n\nHermes `SessionRef` resume requires the SDK backend to be enabled. Native-only Hermes runtimes can retain state and report `RunPlan.capabilities.session_resume: false`. Explicit SDK session selection then fails with `session_resume_unsupported` before native startup.\n\nPick the smallest lifecycle the consumer needs:\n\n- **Single invocation** — one input, no retained state after the call.\n  `await Fabric().run(config, input=...)` runs the full start, invoke, and stop\n  cycle and returns a `RunResult`. Pass\n  `request=RunRequest(...)` instead of `input=...` when the invocation needs a\n  caller-owned request ID or context (the two are mutually exclusive).\n- **Stateful runtime** — ordered turns over one logical harness lifecycle. Start it with\n  `start_runtime(...)` and use the returned `Runtime` as an async context\n  manager so cleanup runs on exit — shutdown is attempted, not guaranteed\n  (`stop()` can raise `FabricRuntimeError`; see Consume Results And Handle\n  Errors). A runtime accepts one active invocation at a time; overlapping calls\n  raise `FabricStateError`.\n- **Native OpenAI stream** — adapter-native OpenAI Chat Completions chunks plus\n  a separate terminal normalized result. Check\n  `runtime.supports_openai_streaming`, call\n  `runtime.invoke_openai_stream(...)`, iterate the returned\n  `OpenAIInvokeStream`, and then await `stream.result()`. The selected adapter\n  descriptor must declare `capabilities.streaming`. Each yielded mapping has\n  `object == \"chat.completion.chunk\"`; an empty stream is valid. If iteration\n  stops early, call `await stream.aclose()` to drain without cancelling the\n  target invocation. This path does not require NeMo Relay or\n  `streaming=True`.\n- **NVIDIA NeMo Relay stream** — live, raw ATOF records plus a terminal normalized\n  result. Install `nemo-fabric[streaming]` to include the matching collector for\n  the default embedded streaming path. Enable NeMo Relay, pass `streaming=True`\n  to `start_runtime(...)`, call\n  `runtime.invoke_stream(...)`, iterate the returned `InvokeStream`, and then\n  await `stream.result()`. Iteration ending does not indicate invocation\n  success; invocation exceptions raise from `result()`, while harness-reported\n  failures remain normalized `RunResult` values. If iteration stops early,\n  call `await stream.aclose()` before starting another turn. `aclose()` waits\n  for the turn to finish; it does not cancel the harness invocation. The SDK\n  intentionally exposes only ATOF records generated by NeMo Relay. This path is\n  independent of native OpenAI streaming. The collector registers the request\n  before the agent is invoked, then routes the matching ATOF root scope and its\n  descendants by request ID and UUID ancestry. By default, streaming starts an\n  embedded collector. Set `launch_collector=False` to use an externally managed\n  collector; configure its base URL as the `nemo-fabric-stream` sink with\n  `transport=\"ndjson\"`. The runtime directs Relay to `\u003Cbase-url>\u002Fv1\u002Fatof` and\n  uses the collector control and stream endpoints. The bundled Pi adapter requires\n  the embedded collector. Do not set `launch_collector=False` for Pi streaming.\n  The embedded collector waits up to `completion_wait_timeout` seconds (1.0 by\n  default) for a late `agent_settled` marker. The collector limits each record to\n  1 MiB and each request queue to 1,024 records or 16 MiB of encoded\n  data. The `streaming=True` flag does not enable NeMo Relay by itself. Without\n  `streaming=True`, startup leaves the NeMo Relay configuration unchanged.\n\nFor explicit environment management, call `prepare_environment(config)` or\n`attach_environment(config, reference)`, then `start_runtime_in(config, environment)`.\nUse typed `EnvironmentHandle` and `EnvironmentReference` objects. Stop the\nruntime before calling `release_environment(environment)` separately. Provider\navailability and reuse limits vary; task paths must remain strings for non-local\nenvironments. See the [environment lifecycle guide](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fsdk\u002Fpython.mdx#explicit-environment-lifecycle).\n\nUse `await fabric.runtime_status(runtime_id=runtime_id, agent_name=name)` to read recorded state and a safe discovery handle for a runtime started by the same `Fabric` instance. The client retains live runtime objects until successful stop. Add `environment=environment` for an OpenShell lookup through `fabric-agent-ctl status`, including from a later client process while the original server remains alive. `RuntimeStatusReport` reports `active`, `stopped`, or `failed`; `server_state` is present for server reads and null for direct local reads. Each client holds at most 128 runtime records, including pending starts. New starts evict the oldest successfully stopped records first; when active, failed, and pending runtimes fill the limit, startup raises `FabricStateError` with `code=\"runtime_limit_reached\"`. Retained stopped records have a null handle. Discovery handles omit environment variable values and arbitrary provider metadata; use the original `Runtime` for invocation and cleanup. Status reads perform no lifecycle operation or health probe. Use `Fabric.check()` when the consumer needs fresh health evidence.\n\nThe selected adapter owns the execution topology. The bundled Claude, Codex,\nDeep Agents, and Hermes Agent adapters retain their native client, graph\u002Fcheckpointer,\nor agent\u002Fdatabase inside one local host for the full runtime. Local `process`\nand `python` adapters use this host lifecycle; consumers do not select another\nlocal execution mechanism in `FabricConfig`. Do not replay an invocation after\na runtime failure. Stop the failed runtime and explicitly start a new one\naccording to the application's retry policy.\n\nThe lifecycle fragment below shows the available forms. It assumes the caller\nhas already set `config = to_fabric_config(job)` and chosen `base`, as described\nin the configuration example above:\n\n```python\nimport asyncio\n\nfrom nemo_fabric import Fabric\n\n\nasync def main() -> None:\n    fabric = Fabric()\n\n    # Single invocation\n    result = await fabric.run(config, base_dir=base, input=\"Review the changes.\")\n\n    # Multi-turn\n    async with await fabric.start_runtime(config, base_dir=base) as runtime:\n        first = await runtime.invoke(input=\"Inspect the repository\")\n        second = await runtime.invoke(input=\"Now review the latest patch\")\n\n    # Adapter-native OpenAI Chat Completions chunks\n    async with await fabric.start_runtime(config, base_dir=base) as runtime:\n        if runtime.supports_openai_streaming:\n            stream = runtime.invoke_openai_stream(input=\"Review the latest patch\")\n            async for chunk in stream:\n                print(chunk)\n            openai_streamed_result = await stream.result()\n\n    # NeMo Relay streaming\n    streaming_config = config.model_copy(deep=True).enable_relay()\n    async with await fabric.start_runtime(\n        streaming_config,\n        base_dir=base,\n        streaming=True,\n    ) as runtime:\n        stream = runtime.invoke_stream(input=\"Review the latest patch\")\n        async for record in stream:\n            print(record)\n        streamed_result = await stream.result()\n\n\nasyncio.run(main())\n```\n\nNeMo Fabric owns no application scheduling queue, worker pool, retry policy, or\nglobal concurrency policy. Each runtime still permits only one active\ninvocation; start independent runtimes for parallel work. The NeMo Relay\nstreaming path uses an internal bounded transport queue and TCP backpressure\nonly to carry one invocation's ATOF records. Treat `stream.result()` as\nauthoritative, and reconstruct nested work from ATOF `uuid` and `parent_uuid`\nfields rather than stream order.\n\nFor native OpenAI streaming, the SDK owns the authenticated loopback HTTP\ntransport, chunked NDJSON framing, and correlation values. Consumer code\nsupplies no listener or credentials. The adapter executes exactly one\ninvocation, and the terminal `RunResult` remains separate from the chunk stream.\nFully consume the stream or call `await stream.aclose()` before starting another\nturn. Awaiting `stream.result()` also drains and discards unread native OpenAI\nchunks, so consume the iterator first when the application needs every chunk.\n\n## Validate Before Running\n\nResolve and diagnose before spending work on a runtime, especially in a new\nenvironment or before relying on an optional capability:\n\n```python\nfabric = Fabric()\nplan = fabric.plan(config, base_dir=base)             # sync: adapter + capabilities\nreport = await fabric.doctor(config, base_dir=base)   # async: preflight checks\n\nprint(plan.adapter.adapter_id, report.status)\n```\n\n- Use `plan(...)` to confirm adapter selection and capability routing before\n  running. Planning validates `harness.settings` against the exact resolved\n  Adapter Descriptor and, when present, `workflow.settings` against the exact\n  resolved Adapter Target Descriptor.\n- Use `doctor(...)` to check adapter availability, resolution, environment\n  context, and declared requirements such as required environment variables. Its\n  aggregate `status` is `pass`, `warn`, or `fail`. Invalid, unknown, or\n  misspelled adapter settings fail before diagnostics or runtime startup. A\n  resolved descriptor without a settings schema accepts only an empty settings\n  map.\n- For a separate admission host, call public `inspect_adapter(config, descriptor)`\n  with matching catalog or canonical external metadata. The immutable\n  `AdapterCapabilityProfile` has `adapter_id`, `descriptor_sha256`, `skills`,\n  `mcp`, and `atif` fields. It does not import harness SDKs or read task-local\n  discovery paths. Missing metadata makes conservative claims and rejects\n  requested optional features. Pass `expected_descriptor_sha256=profile.descriptor_sha256`\n  to task-side `run()` or `start_runtime()` to reject descriptor drift before\n  startup. For a registered workflow, also pass\n  `target_descriptor=get_target_descriptor(config.workflow.target_id)` from the\n  matching catalog or canonical external metadata. The fingerprint then binds\n  both normalized descriptors, including the target factory and settings schema;\n  missing or mismatched metadata fails admission. Standalone fingerprints stay\n  unchanged. Attached services need separate admission. Declared support is not\n  runtime provenance or proof of an artifact.\n\n## Consume Results And Handle Errors\n\nEvery invocation that reaches the adapter boundary returns a normalized\n`RunResult`, even when the harness invocation itself failed. Inspect the failure\nfields before reading output:\n\n```python\nresult = await fabric.run(config, base_dir=base, input=\"Review the changes.\")\n\nif result.status == \"succeeded\":\n    use_output(result.output, result.artifacts, result.telemetry)\nelse:\n    handle_failure(result.status, result.error, result.events)  # failed, cancelled, ...\n```\n\n- Treat `status == \"succeeded\"` as the only success. Other terminal values\n  (`failed`, `cancelled`) are unsuccessful, so branch on `status`, not on\n  `error`. Read `status`, `error`, and `events` before processing `output`.\n- Capture `artifacts` and `telemetry` references as the returned evidence for\n  platforms and evaluations. Store and log `runtime_id`, `invocation_id`, and\n  `request_id` separately as opaque strings.\n- Catch `FabricError` subclasses for lifecycle failures that prevent a\n  normalized result: `FabricConfigError`, `FabricCapabilityError`,\n  `FabricRuntimeError`, `FabricStateError`, and `FabricNativeUnavailableError`.\n- The consumer owns retries and failure policy; NeMo Fabric does not retry by\n  default. `run(...)` and `async with` runtimes attempt cleanup automatically,\n  so prefer them over manual `stop()` — but shutdown is not guaranteed: `stop()`,\n  including the automatic call when an `async with` block exits, can raise\n  `FabricRuntimeError`. On a normal exit that error propagates; after an\n  invocation error the cleanup failure is attached to the original exception. Be\n  ready to handle a shutdown failure.\n\nRefer to [results-and-errors.md](references\u002Fresults-and-errors.md) for the full\nresult-field and error inventory, and\n[sdk-api-inventory.md](references\u002Fsdk-api-inventory.md) for when to use each\n`Fabric` and `Runtime` method.\n\n## Test And Validate The Integration\n\n- Write focused integration tests that build the consumer's `FabricConfig`,\n  assert `plan(...)` selects the expected adapter and capabilities, and — where\n  a harness and credentials are available — run one invocation and assert the\n  `RunResult` status and evidence.\n- `plan(...)` is credential-free — use it as the CI gate that validates adapter\n  selection and capability routing without a model or secrets. `doctor(...)` also\n  runs without calling a model, but it checks declared environment requirements\n  (such as required API-key variables) and returns `fail` when they are unset, so\n  run it where the environment is provisioned and read its per-check results.\n- Run the consumer project's own build and test commands. For a source checkout\n  of NeMo Fabric, `just build-all` rebuilds the native extension and\n  `just test-python` runs the Python suite.\n- Confirm the typed config is passed directly to NeMo Fabric and no non-public\n  imports were added.\n\n## Checklist\n\n- [ ] The consumer config object is translated directly into an in-memory `FabricConfig`.\n- [ ] Only public `nemo_fabric` symbols are imported; no `_native` or adapter internals.\n- [ ] The consumer config is built in memory and passed directly to NeMo Fabric.\n- [ ] The right lifecycle is chosen: `run(...)` for a single invocation,\n  `start_runtime(...)` with `async with` for multi-turn,\n  `invoke_openai_stream(...)` for descriptor-gated OpenAI chunks, or\n  `invoke_stream(...)` for raw NeMo Relay ATOF.\n- [ ] `plan(...)` and `doctor(...)` validate adapter selection, capabilities, and environment before execution.\n- [ ] Installation, adapter dependencies, and credentials are owned by the environment, not consumer code.\n- [ ] `RunResult` status, error, and events are inspected before output; artifacts and telemetry are captured.\n- [ ] `FabricError` subclasses are handled, including a `FabricRuntimeError` raised by shutdown; cleanup is delegated to `run(...)` or `async with` (attempted, not guaranteed).\n- [ ] Correlation IDs are stored and logged as opaque strings.\n- [ ] Focused integration tests pass and NeMo Fabric validation (`plan`\u002F`doctor`, tests) succeeds.\n\n## Related Documentation\n\nLink to these canonical sources instead of duplicating them:\n\n- [Python SDK guide](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fsdk\u002Fpython.mdx)\n- [Resource usage and stats](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fsdk\u002Fsystem-stats.mdx) for collection controls, local and remote scope, sample quality, and repeatable code-review and Harbor examples. Harbor accepts the SDK configuration through `fabric_system_stats`; omission uses before\u002Fafter collection, and explicit null disables invocation stats.\n- [NeMo Fabric overview](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fabout-nemo-fabric\u002Foverview.mdx) and\n  [installation guide](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Fgetting-started\u002Finstall.mdx)\n- Generated API reference (public API index; the installed `nemo_fabric` type\n  stubs are authoritative for exact signatures, fields, and defaults):\n  [client](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.client.md),\n  [runtime](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.runtime.md),\n  [native OpenAI streaming](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.openai_streaming.md),\n  [Relay streaming](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.streaming.md),\n  [models](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.models.md),\n  [types](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.types.md),\n  [errors](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fdocs\u002Freference\u002Fapi\u002Fpython-library-reference\u002Fnemo_fabric.errors.md)\n- Canonical in-memory config example:\n  [examples\u002Fcode_review_agent](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Ftree\u002Fmain\u002Fexamples\u002Fcode_review_agent)\n- Platform and evaluation-harness integration:\n  [examples\u002Fharbor](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Ftree\u002Fmain\u002Fexamples\u002Fharbor) and\n  [nemo_fabric.integrations.harbor](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Ftree\u002Fmain\u002Fsdk\u002Fpython\u002Fnemo-fabric-runtime\u002Fsrc\u002Fnemo_fabric\u002Fintegrations\u002Fharbor).\n  Omit `fabric_model_provider` to retain provider inference from the model name. Override it only when the selected adapter requires a different value; an OpenAI-compatible endpoint alone is not a reason to set `openai`. For example, keep the inferred `nvidia` provider for Mini-SWE and OpenHands with `nvidia\u002Fnemotron-3-ultra-550b-a55b`: both adapters add the LiteLLM `nvidia_nim\u002F` dispatch prefix. Overriding with `openai` passes this model ID unchanged to LiteLLM, which cannot infer its provider.\n  Use `fabric_model_settings` for adapter-declared `models.default.settings`;\n  a model is required and its descriptor still validates those settings. Keep\n  model credentials in Harbor's managed environment variables.\n  Harbor constructs a typed config from explicit agent inputs and transports it\n  inside a private transient run specification at the task-process boundary.\n  Follow the code-review example for consumer integration code; Harbor's\n  transport representation is an internal process-boundary contract.\n\n### Software Evidence\n\nInspect optional `RunResult.execution` for selected software inventories. Preserve full version values, status\u002Freasons, source, origin and original `observed_at` when forwarding. Context refs are result-local; participants describe installation users. Use `FabricConfig.provenance=ProvenanceConfig(enabled=False)` before startup to disable collectors on host and guest. Explicit owner snapshots use typed `ProvenanceConfig.reports` through existing configuration dispatch; guests never inspect the caller installation. Old results can omit execution evidence. Unknown or incomplete reports are not proof of equal environments.\n",{"name":5,"license":15,"metadata":24,"description":7},{"author":25},"NVIDIA Corporation and Affiliates","main","910218f0891749c9364e814596e452f7258e23bb","skills\u002Fnemo-fabric-integrate",47,"https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric","https:\u002F\u002Fdocs.nvidia.com\u002Fnemo\u002Ffabric","https:\u002F\u002Fgithub.com\u002FNVIDIA","https:\u002F\u002Fnvidia.com","2026-11-14 16:17:16",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add NVIDIA\u002FNeMo-Fabric --skill nemo-fabric-integrate",{"tool":41,"command":42},"bunx","bunx skills add NVIDIA\u002FNeMo-Fabric --skill nemo-fabric-integrate",{"tool":44,"command":45},"pnpm","pnpm dlx skills add NVIDIA\u002FNeMo-Fabric --skill nemo-fabric-integrate","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fskills\u002Fnemo-fabric-integrate\u002FSKILL.md",true,[49,55,59,63,67,71,75],{"path":50,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":53,"sourceHtmlUrl":54},"BENCHMARK.md","REFERENCE","参考文档",11085,"https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fskills\u002Fnemo-fabric-integrate\u002FBENCHMARK.md",{"path":56,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":57,"sourceHtmlUrl":58},"evals\u002Fevals.json",7169,"https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fskills\u002Fnemo-fabric-integrate\u002Fevals\u002Fevals.json",{"path":60,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":61,"sourceHtmlUrl":62},"references\u002Fconfig-mapping.md",9159,"https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fskills\u002Fnemo-fabric-integrate\u002Freferences\u002Fconfig-mapping.md",{"path":64,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":65,"sourceHtmlUrl":66},"references\u002Fresults-and-errors.md",10663,"https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fskills\u002Fnemo-fabric-integrate\u002Freferences\u002Fresults-and-errors.md",{"path":68,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":69,"sourceHtmlUrl":70},"references\u002Fsdk-api-inventory.md",8094,"https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fskills\u002Fnemo-fabric-integrate\u002Freferences\u002Fsdk-api-inventory.md",{"path":72,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":73,"sourceHtmlUrl":74},"skill-card.md",8077,"https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fskills\u002Fnemo-fabric-integrate\u002Fskill-card.md",{"path":76,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":79,"sourceHtmlUrl":80},"skill.oms.sig","OTHER","其他",5329,"https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fskills\u002Fnemo-fabric-integrate\u002Fskill.oms.sig",[82,89,96,103,110,117],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M75SRD4HBPVRBVKHDNR5B8HA","default","Use this skill when asked to load the default test skill.","https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fdefault\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M75SRBBATGBDFVYR13ASYTE3","alternate","Use this skill when asked to load the alternate test skill.","https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Falternate\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":19},"01M75SQSTED8VQDQPD6G3WZJDV","swebench-debugging","Apply a focused reproduce-fix-test workflow to SWE-Bench repository tasks.","https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fexamples\u002Fharbor\u002Fswebench\u002Fskills\u002Fswebench-debugging\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":19},"01M75SQRJF20D2S50TX66NSH4A","code-review","Review Python changes for correctness risks and missing test coverage.","https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002Fexamples\u002Fcode_review_agent\u002Fskills\u002Fcode-review\u002FSKILL.md",[],[],{"skillNo":111,"name":112,"nameZh":6,"description":113,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":114,"categories":115,"keywords":116,"publishedAt":19},"01M75SQPE8FEH8JXQE41CN7EYS","validate-change","Choose and run the right NeMo Fabric validation matrix for a change instead of using one fixed test list","https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fvalidate-change\u002FSKILL.md",[],[],{"skillNo":118,"name":119,"nameZh":6,"description":120,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":121,"categories":122,"keywords":123,"publishedAt":19},"01M75SQKT76FTB57RTPHB5ZFQ2","update-project-version","Update the NVIDIA NeMo Fabric release version across Cargo, Python, and TypeScript package metadata, internal Python dependency pins, integration metadata, and lockfiles. Use when bumping, synchronizing, or auditing NeMo Fabric package versions for a release.","https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FNeMo-Fabric\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fupdate-project-version\u002FSKILL.md",[],[]]