feat(api)!: redesign Python SDK API and lifecycle contracts

[AnuradhaKaruppiah]

Summary

This PR gives Fabric one Python-first SDK and runtime model:

FabricConfig -> Fabric -> RunPlan -> Runtime -> RunResult

• makes Fabric the entry point for path-backed and typed in-memory configuration;
• adds Pydantic models and helpers for config, profiles, requests, MCP, skills, and telemetry;
• removes public session lifecycle APIs and redundant runtime mode, runtime transport, and telemetry mode fields;
• uses run() for one-shot start/invoke/stop and start_runtime() for ordered multi-turn work;
• keeps harness conversation state inside adapters and leaves retries, scheduling, and concurrency across runtimes to applications;
• aligns the Rust core, CLI, Codex and Hermes adapters, Harbor integration, schemas, docs, examples, and tests with the same contract.

Validation

• uv run --no-sync pytest -q — 212 passed, 3 skipped
• cargo test --workspace --locked — 46 passed
• cargo fmt --all -- --check
• Python, Rust, wheel, docs, and DCO checks pass in CI

Review path

Start with docs/sdk/python.mdx, then review:

1. python/src/nemo_fabric/client.py, models.py, and runtime.py
2. crates/fabric-core/src/config.rs and runtime.rs
3. the Codex, Hermes, and Harbor adapters

Related issues

Closes FABRIC-2, FABRIC-39

• I confirm this contribution is my own work, or I have the right to submit it under this project's license.
• I searched existing issues and open pull requests, and this does not duplicate existing work.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

This PR migrates Fabric's lifecycle model from session-based ("session_id", RuntimeMode, Transport) to runtime-based (runtime_id, Runtime/RuntimeStatus, start_runtime). It adds adapter contract_version validation, adds Pydantic authoring models (FabricConfigModel, RunRequestModel), renames FabricClient→Fabric, updates the CLI with --set config overrides and session-less chat, updates adapters (codex-cli, hermes-cli, hermes-sdk) to use runtime-id-based state/session mapping, and refreshes examples and documentation extensively (including Rust doc link version bumps to 1.94.0).

Changes

Runtime lifecycle migration

Layer / File(s)	Summary
Rust core: adapter contract_version and runtime model crates/fabric-core/src/config.rs, crates/fabric-core/src/doctor.rs, crates/fabric-core/src/lib.rs, crates/fabric-core/src/runtime.rs, crates/fabric-core/src/schema.rs	Adds ADAPTER_CONTRACT_VERSION validation, removes RuntimeMode/Transport/session_id/mode fields, derives runtime capabilities from adapter descriptors, and simplifies telemetry mode handling.
Fabric CLI: --set overrides and session-less chat crates/fabric-cli/src/main.rs	Adds dotted --set config overrides to inspect/plan/doctor/run/chat; removes session_id from chat loop, prompt, and request context.
Adapters: runtime_id-based session mapping adapters/codex-cli/*, adapters/hermes-cli/*, adapters/hermes-sdk/*, adapters/common/*	Adds contract_version to manifests; switches state/session helpers from session_id to runtime_id keys.
Python SDK: Fabric/Runtime/FabricConfigModel API python/src/nemo_fabric/*.py	Introduces Pydantic models, renames FabricClient→Fabric, replaces Session/SessionStatus with Runtime/RuntimeStatus, updates config sources and exports.
Harbor integration: Fabric client and profile mappings python/src/nemo_fabric/integrations/harbor/*	Guards optional Harbor import, invokes Fabric(), loads profiles as plain dicts.
Examples and profiles examples/code-review-agent/*, integrations/harbor/demo/*, pyproject.toml	Removes runtime mode/transport/telemetry mode fields from example YAML; adds pydantic dependency.
Conceptual docs: session to runtime terminology POC-TO-MVP-PLAN.md, README.md, docs/getting-started/*, docs/index.yml, docs/sdk/python.mdx, docs/reference/api/python-library-reference/*	Updates docs, adds new Python SDK guide, renames session APIs to runtime APIs.
Rust API reference regeneration docs/reference/api/rust-library-reference/**	Regenerates Rust API docs for struct/enum changes and bumps rustdoc link versions to 1.94.0.

Estimated code review effort: 4 (Complex) | ~75 minutes

Sequence Diagram(s)

sequenceDiagram
    participant App as Caller App
    participant Fabric as Fabric (SDK client)
    participant Runtime as Runtime
    participant CoreRT as fabric-core runtime
    participant Adapter as Process/Python Adapter

    App->>Fabric: start_runtime(agent, profiles, overrides)
    Fabric->>CoreRT: resolve_run_plan + start runtime
    CoreRT->>Adapter: start() -> RuntimeHandle(runtime_id)
    CoreRT-->>Fabric: RuntimeHandle
    Fabric-->>App: Runtime instance

    loop multi-turn invocation
        App->>Runtime: invoke(request)
        Runtime->>CoreRT: adapter_invocation(runtime_context{runtime_id})
        CoreRT->>Adapter: run invocation payload
        Adapter-->>CoreRT: RunResult
        CoreRT-->>Runtime: RunResult
        Runtime-->>App: RunResult
    end

    App->>Runtime: stop()
    Runtime->>CoreRT: stop_runtime(runtime_id)
    CoreRT->>Adapter: shutdown
    Runtime-->>App: RuntimeStatus.STOPPED

Loading

Estimated code review effort

Estimated code review effort: 4 (Complex) | ~75 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title follows Conventional Commits, matches the PR scope, and stays within the length limit.
Description check	✅ Passed	The description includes overview, review path, validation, related issues, and confirmation checkboxes, so it is mostly complete.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[AnuradhaKaruppiah]

@CodeRabbit review full

[coderabbitai]

@AnuradhaKaruppiah Resuming with a full review of all changes in this PR.

✅ Action performed

Full review finished.

[AnuradhaKaruppiah]

/ok to test 75b2ee6

[github-actions]

📖 Fern docs preview: https://nvidia-preview-pull-request-39.docs.buildwithfern.com/nemo/fabric

[AjayThorve]

Approving.

The implementation is aligned with the SDK contract we discussed and carries it consistently across the Rust core, Python API, adapters, schemas, docs, and examples.
I also validated the current head with a real Codex agent: both one-shot and multi-turn execution completed an actual repository repair, preserved runtime/thread state across turns, passed the external test suite, and produced correctly isolated patch artifacts.
There are expected hardening follow-ups, but nothing I consider blocking for the MVP.