docs: clarify runtime contracts and integration boundaries

[mnajafian-nv]

Overview

Clarifies the shared NeMo Relay runtime-contract vocabulary and routing for runtime concepts, integration boundaries, codecs, observability, and generated API reference docs.

This is a docs-only change; it does not change runtime behavior.

• 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.

Details

• Adds a Codecs concept page that separates typed value codecs, provider request codecs, and provider response codecs.
• Adds contributor guidance for shared runtime-contract docs ownership and review guardrails.
• Aligns the Concepts hub and Agent Runtime Primer on the same five-part runtime model.
• Clarifies install and quick-start routing for CLI usage, direct application bindings, and supported framework or agent-harness integrations.
• Tightens observability, ATOF, ATIF, plugin, event, and API-reference boundary language so docs do not overstate ownership or runtime behavior.

Validation:

• just docs
• PATH="$HOME/.local/nemo-relay-tools/bin:$PATH" uv run pre-commit run --all-files

Where should the reviewer start?

Start with docs/about-nemo-relay/concepts/codecs.mdx and docs/contribute/runtime-contract-docs.mdx, then review the routing updates in docs/getting-started/agent-runtime-primer.mdx, docs/getting-started/installation.mdx, and docs/getting-started/quick-start/index.mdx.

Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)

• N/A

Summary by CodeRabbit

• Documentation
  • Added “Codecs” concept page and linked it from the architecture “Related Concepts”.
  • Expanded the runtime model and boundary guidance (Scopes, Middleware, Plugins, Events, Subscribers/exporters), including event contract boundary and plugin failure boundaries.
  • Refined request vs response provider codec guidance across instrumentation and framework integration docs.
  • Updated installation/quick-start flows to emphasize boundary ownership/observation.
  • Added a runtime contract documentation contribution guide and refreshed glossary terminology; improved generated API reference guidance.
  • Clarified observability plugin expectations for ATOF/ATIF and downstream/export behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 57421d55-fed0-461f-b36f-889147f8894b

📥 Commits

Reviewing files that changed from the base of the PR and between 0b98b87 and 00b22c9.

📒 Files selected for processing (3)

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

📜 Recent review details

⏰ Context from checks skipped due to timeout. (2)

• GitHub Check: Check / Run
• GitHub Check: Preview docs

🧰 Additional context used

📓 Path-based instructions (12)

{docs/**,README.md,CONTRIBUTING.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

{docs/**,README.md,CONTRIBUTING.md}: For docs-only changes, run targeted checks only if commands, package names, or examples changed. Use just docs for docs-site builds and just docs-linkcheck when links changed
Run docs site build with just docs

Files:

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

{docs/**,README.md,CONTRIBUTING.md,**/*.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Run docs link validation with just docs-linkcheck when links change

Files:

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

{docs/**,README.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Verify README and docs entry points still match current package names and paths for large or public-facing changes

Files:

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

{docs/**,examples/**,README.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Verify examples still run with documented commands for large or public-facing changes

Files:

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

{docs/**,README.md,**/Cargo.toml,**/package.json,**/*.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Ensure renamed public surfaces are reflected consistently in manifests and docs for large or public-facing changes

Files:

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

**/*.{md,mdx,py,sh,yaml,yml,toml,json}

📄 CodeRabbit inference engine (.agents/skills/contribute-docs/SKILL.md)

Keep package names, repo references, and build commands current

Files:

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

**/*.mdx

📄 CodeRabbit inference engine (.agents/skills/contribute-docs/SKILL.md)

In MDX files, top-of-file comments must use JSX comment delimiters: {/* to open and */} to close. Do not use HTML comments for MDX SPDX headers.

MDX top-of-file SPDX comments must use {/* ... */} delimiters instead of HTML comment delimiters (Must-Fix)

Files:

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

**/*.{html,md,mdx}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Include SPDX license header in HTML and Markdown files using HTML comment syntax

Files:

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

docs/**/*.{md,mdx}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Update embedded documentation snippets, patch docs, and binding-support notes if examples or supported bindings changed

Files:

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

docs/**

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Run just docs or ./scripts/build-docs.sh html to regenerate ignored Fern API reference pages before validation for documentation site changes

Files:

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

**

⚙️ CodeRabbit configuration file

**:

AGENTS.md

This file provides guidance to agents, including Claude Code and OpenAI Codex, when working in this repository.

Project Overview

NeMo Relay is a multi-language agent runtime framework for execution scopes, lifecycle events, middleware, plugins, and observability around tool and LLM calls. The core runtime is Rust. Primary supported bindings are Rust, Python, and Node.js. Go, WebAssembly, and the raw C FFI are experimental and source-first.

The shared runtime model is:

1. Scope stacks decide where work belongs and which scope-local behavior is visible.
2. Middleware registries decide what guardrails and intercepts run around managed calls.
3. Plugins install reusable runtime behavior from configuration.
4. Events record runtime behavior in ATOF form.
5. Subscribers and exporters consume events in-process or export them to ATIF, OpenTelemetry, OpenInference, or other backends.

Repository Structure

The repository layout separates the Rust runtime, language bindings, documentation,
integration patches, and agent-facing skills.

crates/
  core/       # Rust core runtime crate, published as nemo-relay
  adaptive/   # Adaptive runtime primitives and plugin components
  python/     # PyO3 native extension for the Python package
  ffi/        # Raw C ABI layer used by downstream bindings such as Go
  node/       # NAPI Node.js binding and JavaScript/TypeScript entry points
  wasm/       # wasm-bindgen WebAssembly binding and JS wrappers
python/
  nemo_relay/  # Python wrapper package: scopes, tools, LLM, middleware, typed helpers, plugins, adaptive helpers
  tests/      # Python tests
go/
  nemo_relay/  # Experimental Go CGo binding and tests
fern/         # Fern documentation site
scripts/      # Stable wrappers and helper scripts; build/test/docs entry points live in justfile
third_party/  # P...

Files:

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

{docs/**,README.md,CONTRIBUTING.md,RELEASING.md,SECURITY.md}

⚙️ CodeRabbit configuration file

{docs/**,README.md,CONTRIBUTING.md,RELEASING.md,SECURITY.md}: Review documentation for technical accuracy against the current API, command correctness, and consistency across language bindings.
Flag stale examples, missing SPDX headers where required, and instructions that no longer match CI or pre-commit behavior.

Files:

• docs/contribute/runtime-contract-docs.mdx
• docs/getting-started/quick-start/index.mdx
• docs/observability-plugin/about.mdx

🔇 Additional comments (10)

docs/contribute/runtime-contract-docs.mdx (4)

1-17: 📐 Maintainability & Code Quality

Verify MDX SPDX header format uses JSX delimiters.

Per the coding guidelines, MDX files must use JSX comment delimiters {/* ... */} for SPDX headers, not HTML comment syntax. Lines 1-17 are not visible in the provided snippet. Please confirm the header uses the correct format: {/* ... */} not <!-- ... -->.

Source: Coding guidelines

---

18-46: 📐 Maintainability & Code Quality

Verify all "Shared Contract Pages" files exist.

The list enumerates 14 concept/getting-started/reference pages that define the shared runtime model. Verify that all listed paths exist and are actual pages in the documentation. Line 37 includes opentelemetry.mdx—confirm this is a shared contract page that should be included in contributor coordination.

Source: Path instructions

---

47-82: LGTM!

---

83-123: LGTM!

docs/getting-started/quick-start/index.mdx (3)

12-22: LGTM!

---

42-85: LGTM!

---

119-120: LGTM!

docs/observability-plugin/about.mdx (3)

35-36: 🎯 Functional Correctness

Reference is complete; no action required.

The markdown link [Observability Configuration](/observability-plugin/configuration) is fully specified and valid. The sentence spans lines 36–38 due to source line wrapping, not an incomplete reference.

			> Likely an incorrect or invalid review comment.

---

1-20: 📐 Maintainability & Code Quality

SPDX header is correctly formatted, and the reference is complete.

The MDX file properly uses JSX comment delimiters ({/* ... */}) for the SPDX header on lines 7–8, which is the correct format per the coding guidelines. The "See" reference on line 36 is also complete—it continues on line 37 with a valid link to the configuration section. The file is well-structured and technically accurate.

			> Likely an incorrect or invalid review comment.

---

21-60: 🎯 Functional Correctness

Section correctly prioritizes codecs over plugins for observability context.

Lines 21-39 describe a downstream contract for exporters, not the full five-part shared runtime model. The section correctly includes codecs (which provide normalized data for observability) rather than plugins (which are part of the broader shared runtime model but not directly relevant to exporter contracts). Codecs are documented in the conceptual docs as boundary translators that normalize request/response data when middleware, events, or exporters need stable shapes.

The terminology and ordering align with documented runtime semantics: scopes establish ownership, middleware controls execution, codecs normalize payloads for observability consumers, events record the stream, and subscribers/exporters consume or project that stream. This is intentional context-specific framing, not an inconsistency with the five-part shared runtime model.

---

Walkthrough

Adds a new codecs.mdx concept page and a runtime-contract-docs.mdx contributor guide defining shared terminology and review boundaries. Propagates codec request/response role distinctions, the five-part runtime model (Scopes, Middleware, Plugins, Events, Subscribers/exporters), and boundary-selection guidance across getting-started, concept, observability, integration, and glossary pages.

Changes

Runtime Contract Documentation Expansion

Layer / File(s)	Summary
New Codecs concept page and navigation wiring docs/about-nemo-relay/concepts/codecs.mdx, docs/about-nemo-relay/concepts/index.mdx, docs/about-nemo-relay/architecture.mdx	Creates the Codecs page covering typed-vs-provider codec distinctions, request/response responsibilities, and what codecs do not decide. Adds the Codecs card to the concepts index and a related-concept link in architecture.
Runtime contract contributor guide docs/contribute/runtime-contract-docs.mdx, docs/contribute/about.mdx	Adds the contributor guide defining shared contract pages, contract boundary constraints per topic (ATOF vs projections, Codecs vs ownership, Managed vs Explicit), a responsibilities table, and a review checklist. Links it from the contribute index.
Getting-started flow: runtime model and codec placement docs/getting-started/agent-runtime-primer.mdx, docs/getting-started/installation.mdx, docs/getting-started/quick-start/index.mdx	Rewrites the primer with the five-part runtime model and adds a codec node to the Mermaid diagram. Adds boundary-selection guidance to installation and quick-start, and introduces the Framework/Agent-Harness card grid section.
Concept page clarifications: events, framework integrations, plugins docs/about-nemo-relay/concepts/events.mdx, docs/about-nemo-relay/concepts/framework-integrations.mdx, docs/about-nemo-relay/concepts/plugins.mdx	Adds Event Contract Boundary subsection and ATOF/projection note to events. Adds scheduling/retry preservation, pipeline execution, and codec payload guidance to framework-integrations. Adds Failure Boundary subsection and Ownership and Scope clarification to plugins.
Observability and codec usage clarifications docs/observability-plugin/about.mdx, docs/observability-plugin/atif.mdx, docs/observability-plugin/atof.mdx, docs/integrate-into-frameworks/*, docs/instrument-applications/instrument-llm-call.mdx	Adds observability downstream contract and failure semantics. Adds projection boundary notes to ATIF and ATOF pages. Updates Provider Codecs guidance across integration and instrumentation pages to explicitly distinguish request vs response codec roles.
Glossary new terms and API reference guidance docs/resources/glossary.mdx, docs/reference/api/index.mdx	Adds Experimental Binding, Primary Binding, and Projection glossary entries. Expands Provider Adapter and Provider Codec entries for request/response codec roles. Expands api/index with a list of topics not reliably sourced from generated symbol references.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title follows Conventional Commits format with correct type (docs), lowercase scope, and concise imperative summary under 72 characters.
Description check	✅ Passed	Description includes all required template sections: Overview with confirmation checkboxes, detailed change list, reviewer starting point, and related issues reference.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

Fern docs preview: https://nvidia-preview-pull-request-294.docs.buildwithfern.com/nemo/relay (​https://nvidia-preview-pull-request-294.docs.buildwithfern.com/nemo/relay​)