docs(relay): document the native integration

[afourniernv]

Draft dependency: this guide describes the routing-mark schemas from #604 and the answer/fallback fields from #612. Its installation link is completed by #628. This PR should merge after those changes.

What

• Adds a published NeMo Relay integration guide and links it from the docs home page and navigation.
• Explains which requests Switchyard handles and what happens to other Relay calls.
• Shows the in-process request flow and Relay trace relationship with two Mermaid diagrams.
• Documents format translation, streaming, session state, routing marks and metrics, fallback reporting, and data handling.
• Links directly to the relevant Relay 0.8.3 documentation for plugins, middleware, scopes, subscribers, OpenTelemetry, and OpenInference.

Why

The native plugin landed in #528, but the published Switchyard docs currently send readers straight to the crate README. That README covers configuration, but it does not explain which work remains inside Switchyard, what Relay records, how unmatched models behave, or what downstream subscribers can rely on.

This page documents the Switchyard-specific behavior and links to Relay for the surrounding runtime and exporter behavior.

Version compatibility

The plugin manifest remains the source of truth and currently accepts Relay >=0.8.1,<0.9.0 with native plugin API 1. The external links are pinned to the Relay 0.8.3 documentation so they do not drift to an unsupported release.

Notes for reviewers

Start with How Requests Flow, then State and Identity and Routing Telemetry. The streaming and data-handling limits are called out separately.

This changes only the published documentation and mkdocs.yml. It does not change Rust, Python, TOML, or Relay APIs.

Validation

• cd docs && make publish
• Parsed and rendered both Mermaid diagrams with Mermaid CLI
• Verified all linked Relay documentation pages return HTTP 200
• git diff --check

Summary by CodeRabbit

• Documentation
  • Added a comprehensive guide for integrating Switchyard with NeMo Relay through its native plugin system.
  • Documented setup, compatibility, routing, streaming, state handling, telemetry, metrics, and request data behavior.
  • Updated documentation links and navigation to make the NeMo Relay integration guide easier to find.

[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: e7af7202-354b-4054-9a4b-64650fb395d0

📥 Commits

Reviewing files that changed from the base of the PR and between 7a23989 and 627f2bb.

📒 Files selected for processing (3)

• docs/index.md
• docs/integrations/nemo_relay.md
• mkdocs.yml

Included review availability: Your plan provides up to 12 included reviews per hour; 11 remain after this review.

---

Walkthrough

The PR adds a NeMo Relay integration guide, updates existing documentation links, and adds the guide to the MkDocs navigation. The guide covers setup, routing, supported APIs, state, telemetry, metrics, and data handling.

Changes

NeMo Relay documentation

Layer / File(s)	Summary
Integration scope and setup docs/integrations/nemo_relay.md, docs/index.md, mkdocs.yml	The documentation defines native plugin deployment, compatibility requirements, route reuse, and navigation links.
Request routing and execution docs/integrations/nemo_relay.md	The guide describes model matching, provider translation, retries, fallback, supported APIs, streaming, and conversion behavior.
State and observability contracts docs/integrations/nemo_relay.md	The guide defines request state, correlation metadata, routing records, marks, metrics, and telemetry data boundaries.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 627f2

This publishes the NeMo Relay integration guide and links it from the documentation home page and navigation. No current merge-blocking risk remains.

Poem

A rabbit reads the Relay guide,
Plugin routes hop side to side.
Streams flow softly, marks align,
Metrics sparkle line by line.
Switchyard and Relay now rhyme.

🚥 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 and concisely identifies the main change: documenting the native NeMo Relay integration.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
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.

---

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

[bbednarski9]

Suggested change

	[native plugin system](https://docs.nvidia.com/nemo/relay/v0.8.3/build-plugins/native/about).
	[native dynamic plugin system](https://docs.nvidia.com/nemo/relay/v0.8.3/build-plugins/native/about).

[bbednarski9]

dont fix link to version or will get stale

Suggested change

	[NeMo Relay](https://docs.nvidia.com/nemo/relay/v0.8.3/about-nemo-relay/overview#integrating-with-relay)
	deployment through Relay's
	[NeMo Relay runtime](https://docs.nvidia.com/nemo/relay/about-nemo-relay/overview)
	though Relay's

[bbednarski9]

Suggested change

	Using the strongest model for every request is simple, but routine work may not
	Switchyard's routing algorithms are optimized to select the best model, in terms of both cost
	and performance, for your next LLM request or step in an agentic trajectory. Our integration
	with NeMo-Relay brings first-class support for these algorithms to your favorite coding agent
	harnesses. In short, any harness integration in NeMo-Relay that can load manifest-driven plugins can now configure and use any core Switchyard router.

[bbednarski9]

https://docs.nvidia.com/nemo/relay/configure-plugins/model-pricing

[bbednarski9]

Can we change the relay docs references from being specific to 0.8.3 to just the latest release, which is the default?

[bbednarski9]

Can we add a note to the doc that the plugin requires:
relay = ">=0.8.0,<1.0"