feat(nemo-agents): add fabric invocation wrapper and request/result objects

[mmogallapalli]

Summary

This PR adds the initial thin Platform runtime wrapper for Fabric-backed NeMo Agents as part of AIRCORE-898.

The main boundary established here is:

translated FabricConfig -> Platform runtime request -> Fabric Runtime -> Platform runtime result

The wrapper accepts an already-translated in-memory FabricConfig, starts an ephemeral Fabric runtime, invokes it once, relies on Fabric's async runtime context manager for cleanup, and normalizes the returned RunResult into a Platform-owned result shape.

Changes

• Added FabricRuntimeRequest as the internal Platform invocation request shape.
• Added FabricRuntimeResult as the normalized Platform result shape for Fabric invocations.
• Added run_fabric_agent_once(...) for one-shot execution through Fabric.start_runtime(...).
• Preserved Platform invocation context by mapping input, request_id, and caller_context into Fabric RunRequest.
• Added timeout handling around the ephemeral runtime lifecycle.
• Wrapped Fabric SDK lifecycle exceptions separately from failed normalized RunResult values.
• Added normalization from Fabric SDK result/mapping objects into plain Platform-owned values.
• Added focused unit coverage for lifecycle calls, async cleanup, request context propagation, timeout handling, lifecycle error wrapping, failed result handling, and result normalization.

Scope Boundary

This PR intentionally does not wire the wrapper into any user-facing nemo agents CLI/API flow yet.

Out of scope:

• Register CLI/API wiring.
• Deploy semantics.
• Invoke CLI/API wiring.
• Durable runtime/session management.
• Multi-turn or long-running managed runtime support.
• Runtime packaging/container dependency work.

Those are covered by follow-up AIRCORE-895 tickets. Managed multi-turn runtime/session lifecycle is tracked separately in AIRCORE-932.

Fabric Integration Notes

This follows the Fabric integration guidance by:

• Using only public nemo_fabric imports.
• Passing typed in-memory FabricConfig directly to Fabric.
• Passing base_dir through for relative config paths.
• Letting Fabric own harness start/invoke/stop behavior.
• Treating runtime_id, invocation_id, and request_id as opaque correlation IDs.
• Handling failed RunResult values separately from SDK lifecycle exceptions.

The one conscious Platform choice is to use Fabric.start_runtime(...) for the one-shot wrapper instead of Fabric.run(...), so the internal Platform boundary is built around the same runtime primitive that future managed-runtime support will extend.

Validation

Passed:

tools/lint/lint-python-style.sh plugins/nemo-agents/src/nemo_agents_plugin/fabric/runtime.py plugins/nemo-agents/tests/unit/test_fabric_runtime.py
uv run --frozen --group insights ty check --ignore unused-ignore-comment --exit-zero-on-warning plugins/nemo-agents/src/nemo_agents_plugin/fabric/runtime.py plugins/nemo-agents/tests/unit/test_fabric_runtime.py
uv run --frozen pytest plugins/nemo-agents/tests/unit/test_fabric_runtime.py plugins/nemo-agents/tests/unit/test_fabric_validation.py plugins/nemo-agents/tests/unit/test_fabric_translator.py

Result: 30 passed

Summary by CodeRabbit

• New Features
  • Added Fabric-backed single-run agent runtime support, including request/response result objects.
  • Preserves invocation context (IDs and caller context) and returns normalized outputs, artifacts, events, telemetry, and metadata.
  • Enforces configurable execution timeouts and maps failures into platform-friendly exceptions.
• Bug Fixes
  • Ensures runtime resources are properly cleaned up on success, failure, or timeout.
• Tests
  • Added unit tests covering runtime invocation, timeout wrapping, execution error handling, and result normalization.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: b999fe45-22d6-44d0-b984-7cbdf4027d4d

📥 Commits

Reviewing files that changed from the base of the PR and between 040a6b1 and 435de37.

📒 Files selected for processing (2)

• plugins/nemo-agents/src/nemo_agents_plugin/fabric/runtime.py
• plugins/nemo-agents/tests/unit/test_fabric_runtime.py

🚧 Files skipped from review as they are similar to previous changes (1)

• plugins/nemo-agents/src/nemo_agents_plugin/fabric/runtime.py

---

📝 Walkthrough

Walkthrough

Changes

Adds a Fabric runtime boundary with typed requests/results, timeout and execution error mapping, invocation context propagation, recursive result normalization, and unit tests for lifecycle, timeout, failure, and conversion behavior.

Fabric runtime integration

Layer / File(s)	Summary
Runtime contracts and invocation context plugins/nemo-agents/src/nemo_agents_plugin/fabric/runtime.py	Defines frozen request/result dataclasses, execution and timeout exceptions, and Fabric request context propagation.
Ephemeral runtime execution plugins/nemo-agents/src/nemo_agents_plugin/fabric/runtime.py, plugins/nemo-agents/tests/unit/test_fabric_runtime.py	Starts and cleans up an ephemeral runtime, invokes it once, enforces timeouts, and wraps Fabric failures.
Run result normalization plugins/nemo-agents/src/nemo_agents_plugin/fabric/runtime.py, plugins/nemo-agents/tests/unit/test_fabric_runtime.py	Converts nested Fabric SDK values into plain Python structures and preserves normalized result fields and identifiers.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant run_fabric_agent_once
  participant Fabric
  participant FabricRuntime
  Caller->>run_fabric_agent_once: FabricRuntimeRequest
  run_fabric_agent_once->>Fabric: start_runtime(config, base_dir, overrides)
  Fabric-->>run_fabric_agent_once: ephemeral FabricRuntime
  run_fabric_agent_once->>FabricRuntime: invoke(RunRequest with input, context, request_id)
  FabricRuntime-->>run_fabric_agent_once: RunResult
  run_fabric_agent_once-->>Caller: FabricRuntimeResult or mapped exception

Loading

Suggested reviewers: stefan-kickoff, mikeknep

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: a Fabric invocation wrapper plus request and result objects.
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.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch mmogallapall/aircore-898-add-thin-platform-runtime-wrapper-around-fabric-sdk

---

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

[coderabbitai]

🧹 Nitpick comments (1)

plugins/nemo-agents/tests/unit/test_fabric_runtime.py (1)

52-86: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

invoke_error fixture support is never exercised.

_FakeRuntime supports raising an error from invoke() (Lines 57, 61, 83-84), but no test in this file sets invoke_error. Only the start-time FabricError path (test_wraps_fabric_lifecycle_errors) is covered — invoke-time FabricError handling inside the async with block is untested.

async def test_wraps_fabric_lifecycle_errors_during_invoke(self) -> None:
    fake_runtime = _FakeRuntime(invoke_error=fabric_runtime.FabricError("invoke failed"))
    fake_fabric = _FakeFabric(runtime=fake_runtime)
    request = FabricRuntimeRequest(
        fabric_config=cast(FabricConfig, object()),
        base_dir=Path("/tmp/agent"),
    )

    with pytest.raises(FabricRuntimeExecutionError, match="Fabric runtime invocation failed: invoke failed"):
        await run_fabric_agent_once(request, fabric=fake_fabric)

    assert fake_runtime.exited is True

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@plugins/nemo-agents/tests/unit/test_fabric_runtime.py` around lines 52 - 86,
Add a unit test beside test_wraps_fabric_lifecycle_errors that configures
_FakeRuntime with invoke_error set to FabricError and executes
run_fabric_agent_once. Assert FabricRuntimeExecutionError is raised with the
expected invocation-failure message, and verify fake_runtime.exited is true to
confirm async context cleanup.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@plugins/nemo-agents/tests/unit/test_fabric_runtime.py`:
- Around line 52-86: Add a unit test beside test_wraps_fabric_lifecycle_errors
that configures _FakeRuntime with invoke_error set to FabricError and executes
run_fabric_agent_once. Assert FabricRuntimeExecutionError is raised with the
expected invocation-failure message, and verify fake_runtime.exited is true to
confirm async context cleanup.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 5f94584f-4f46-41e5-b3a0-f5264f6ce0e3

📥 Commits

Reviewing files that changed from the base of the PR and between e9ddd3b and 040a6b1.

📒 Files selected for processing (2)

• plugins/nemo-agents/src/nemo_agents_plugin/fabric/runtime.py
• plugins/nemo-agents/tests/unit/test_fabric_runtime.py

[github-actions]

Suite	Lines Covered	Line Rate	Branch Rate
Unit Tests	26384/34035	77.5%	61.8%
Integration Tests	15177/32660	46.5%	18.7%

[mikeknep]

LGTM, just one nit, you can take it or leave it