docs: document experimental Switchyard integration#400
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughAdds documentation and navigation for the experimental Switchyard plugin, documents named ATOF endpoint configuration, and updates Switchyard integration examples with pinned-service setup and runtime behavior. ChangesSwitchyard integration
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
> [!WARNING] > **BREAKING CHANGE:** **[Rust source compatibility]** This PR adds `FlowError::Upstream` and new fields to the public `AtofEndpointConfig`, `AtofEndpointSectionConfig`, and `EmitMarkEventParams` types. Downstream exhaustive `FlowError` matches must handle the new variant, and direct struct literals must initialize the new fields or migrate to the provided constructor/builder APIs. Builder-based mark emission and default Relay configurations remain compatible. #### Overview This adds Relay's first-party integration with the [Switchyard](https://github.com/NVIDIA-NeMo/Switchyard) Decision API. The plugin routes buffered and streaming LLM requests through an external Switchyard service, executes the selected Relay-owned backend, and records causal model-routing optimization evidence. Switchyard owns provider-protocol translation through its `switchyard-translation` Rust library. Relay consumes that library only when the native Switchyard plugin is enabled; default Relay builds do not include either the plugin or the translation dependency. - [x] I confirm this contribution is my own work, or I have the right to submit it under this project's license. - [x] I searched existing issues and open pull requests, and this does not duplicate existing work. #### Details ##### Plugin and execution behavior - Add the standalone `nemo-relay-switchyard` first-party plugin. - Normalize stable Relay identity and build `switchyard.routing_request.v1` requests. - Validate selected routes and optional counterfactual baselines against exact Relay-owned backend bindings. - Support enforce and observe-only modes, six request-materialization modes, bounded retry-aware dispatch, protocol-specific trusted fallbacks, and no retry after the first upstream stream item. - Record one model-routing optimization contribution only after the selected route commits. Failed decisions, failed provider attempts, and fallback dispatches do not claim routing savings. - Preserve Switchyard routing metadata, including snapshot freshness, decision source, event count, and turn depth. - Continue using Relay's existing ATOF exporter and lifecycle; the plugin does not install local routers, feature accumulators, or a duplicate event subscriber. ##### Translation ownership and optional dependency Request, buffered-response, and SSE translation across OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages use Switchyard's public `switchyard-translation` library instead of a Relay-local translation engine. The dependency is pinned to the immutable topic-branch commit [`8f9db9a6a47f848cdff1d262276ba25a8ae9cbc8`](NVIDIA-NeMo/Switchyard@8f9db9a), which includes the Decision API series, StageRouter baseline/freshness behavior, and [Switchyard #46](NVIDIA-NeMo/Switchyard#46). The Relay CLI exposes this through `--features switchyard`: - Without that feature, `nemo-relay-cli` contains neither `nemo-relay-switchyard` nor `switchyard-translation`. - With that feature, the plugin and its pinned Switchyard translation library are compiled and registered. - Relay continues to own target bindings, credentials, dispatch, retries, fallbacks, lifecycle, and observability. - Relay retains narrow fail-open policy checks for provider extensions that cannot be translated without data loss. ##### Runtime requirements The current experimental deployment requires a separately running Switchyard service from the pinned topic commit. The plugin does not start or supervise that service. Switchyard availability is not a Relay startup requirement. It is a request-time dependency: connection failures, timeouts, malformed decisions, selected-route drift, unsupported extensions, and missing required identity fail open to the configured same-protocol default. ATOF-backed profiles additionally require Relay's ATOF HTTP exporter to target Switchyard's `/v1/atof/events` endpoint with preserved field names and environment-referenced authentication. The public examples document this service boundary, verify the exact Switchyard revision before startup, and intentionally remain manual compatibility workflows rather than production orchestration. ##### Optimization accounting and observability This PR builds on the plugin-neutral accounting contract merged in [NeMo Relay #389](#389). Applied routing contributions carry the selected and baseline model transition, decision identity, backend and tier, attempt, rollout mode, reason, and router metadata. Observe-only decisions remain visible as non-applied evidence. Relay core combines routing and other plugin contributions at LLM close while retaining explicit token evidence for downstream repricing. Existing requested, decision, retry, fallback, and error routing marks remain available alongside the canonical optimization contribution. The generic ATIF change that attributes `step.model_name` to the effective response model is intentionally separated into [NeMo Relay #399](#399). This PR still ensures translated provider responses carry the actual selected model; #399 independently controls how ATIF presents it. ##### Testing summary - `cargo fmt --all -- --check` - `cargo clippy -p nemo-relay-switchyard --all-targets -- -D warnings` - `cargo clippy -p nemo-relay-cli --features switchyard --all-targets -- -D warnings` - `cargo check -p nemo-relay-cli` — proves the default CLI builds without Switchyard. - `cargo check -p nemo-relay-cli --features switchyard` — proves the opt-in dependency path. - `cargo test -p nemo-relay-switchyard` — 31 passed. - `cargo test -p nemo-relay-cli gateway::tests` — 33 passed without the feature. - `cargo test -p nemo-relay-cli --features switchyard gateway::tests` — 33 passed with the feature. - `cargo test -p nemo-relay-cli --features switchyard --test switchyard_process_e2e` — buffered, streaming, retry, and fail-open process boundary passed after the split. - `examples/switchyard/run-real-e2e.sh` against the exact pinned Switchyard service — passed with the expected StageRouter route sequence `provider/weak`, `provider/strong`, `provider/strong`. - The pinned Switchyard translation crate separately passes 61 request, response, streaming, extension, and round-trip tests under Rust 1.93. ##### Previous feedback addressed - Split the implementation at repository ownership boundaries. - Replaced Relay's custom translation engine with the Switchyard-owned reusable library. - Kept the dependency compile-time optional for users who do not enable the Relay-native Switchyard plugin. - Removed in-process Random, LLM, and Cascade routers, Relay-side feature accumulation, duplicate Switchyard subscriptions, and the global fallback target. - Replaced literal credentials with environment-referenced headers and activation-time validation. - Hardened internal dispatch headers and structured upstream-failure metadata. - Standardized routing terminology on StageRouter. - Standardized model-routing evidence on Relay's shared optimization contract instead of adding a second post-call savings mark. - Moved generic ATIF effective-model attribution into focused PR #399. - Moved Fern documentation into focused experimental docs PR #400 so this functional PR remains code-focused. - Kept public examples free of internal-only providers, credentials, Visor source references, and private infrastructure assumptions. #### Where should the reviewer start? 1. `crates/switchyard/src/component.rs` — Decision API lifecycle, exact target and baseline validation, retries, fallback, and terminal route commitment. 2. `crates/switchyard/src/translation.rs` and `stream_translation.rs` — thin policy adapters over the Switchyard-owned translation library. 3. `crates/cli/Cargo.toml` and the `cfg(feature = "switchyard")` registration paths — compile-time optionality. 4. `crates/cli/src/gateway.rs` — reserved dispatch headers and structured retry-aware upstream failures. 5. `crates/cli/tests/switchyard_process_e2e.rs` — process-boundary buffered, streaming, and fail-open coverage. 6. `examples/switchyard/README.md` and `run-real-e2e.sh` — pinned experimental service workflow. #### Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to) - Relates to [NVIDIA/NeMo-Relay #389](#389). - Relates to [NVIDIA/NeMo-Relay #399](#399). - Relates to [NVIDIA/NeMo-Relay #400](#400). - Relates to [NVIDIA-NeMo/Switchyard #46](NVIDIA-NeMo/Switchyard#46). - Paired with the Switchyard Decision API topic series: - [NVIDIA-NeMo/Switchyard #8](NVIDIA-NeMo/Switchyard#8) - [NVIDIA-NeMo/Switchyard #9](NVIDIA-NeMo/Switchyard#9) - [NVIDIA-NeMo/Switchyard #11](NVIDIA-NeMo/Switchyard#11) - [NVIDIA-NeMo/Switchyard #35](NVIDIA-NeMo/Switchyard#35) Authors: - Bryan Bednarski (https://github.com/bbednarski9) Approvers: - Will Killian (https://github.com/willkill07) - Maryam Najafian (https://github.com/mnajafian-nv) - https://github.com/Salonijain27 URL: #369
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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.
Inline comments:
In `@docs/configure-plugins/switchyard/about.mdx`:
- Around line 34-38: Update the Switchyard plugin documentation near the ATOF
HTTP exporter requirement to state that the exporter targets the configured
atof_endpoint_url when provided, and otherwise derives the endpoint using
/v1/atof/events. Preserve the existing requirement for an enabled Relay ATOF
HTTP exporter.
- Around line 15-19: Revise the plugin description so it explicitly states that
provider-protocol translation is executed in Relay’s process via
switchyard-translation, while the Switchyard service only owns routing
decisions. Update the sentence describing Switchyard responsibilities without
changing the documented ownership of credentials, bindings, dispatch, retries,
fallbacks, or observability.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 07231d81-f764-40de-8eba-0082ae7744ac
📒 Files selected for processing (4)
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdxdocs/index.yml
📜 Review details
🧰 Additional context used
📓 Path-based instructions (7)
**/*.mdx
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/SKILL.md)
MDX top-of-file SPDX comments must use {/* ... */} delimiters instead of HTML comment delimiters (Must-Fix)
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
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
Update
README.md,fern/, package READMEs, and binding-support notes when public behavior, package names, examples, or supported bindings change.
**/*.{md,mdx}: Prefer the documented public API, not internal shortcuts
Keep package names, repo references, and build commands current
Keep release-process and release-notes guidance in repo-maintainer docs such asRELEASING.md, not as user-facing docs pages orCHANGELOG.md
Keep stable user-facing wrappers atscripts/root in docs and examples; only point at namespaced helper paths when documenting internal maintenance work
When detailed dynamic plugin guides exist, keep Rust native plugin examples, Python worker plugin examples, andgrpc-v1protocol details on separate pagesIf links in documentation change, run
just docs-linkcheck.
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdx
**/*.{md,markdown,mdx}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Add the SPDX license header to all Markdown/MDX documentation files using the HTML comment block form.
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdx
{docs,examples}/**/*
📄 CodeRabbit inference engine (.agents/skills/rename-surfaces/SKILL.md)
Update docs and examples.
Files:
docs/configure-plugins/about.mdxdocs/index.ymldocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdx
**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
**/*: Format changed files with the language-native formatter before the final lint/test pass.
If dynamic plugin behavior changed, usemaintain-dynamic-pluginsand include the native SDK, worker protocol, Python SDK, docs, packaging, and Codecov surfaces in the validation plan.
If code changes alter APIs, bindings, commands, paths, packaging behavior, observability/adaptive semantics, or documented best practices, update any dependent maintainer or consumer skills in the same branch.
During iteration, preferuv run pre-commit run --files <changed files...>.
Before review or handoff, runuv run pre-commit run --all-files.
Files:
docs/configure-plugins/about.mdxdocs/index.ymldocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdx
docs/**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
If documentation examples or commands under
docs/change, run the targeted docs checks appropriate to the change.
Files:
docs/configure-plugins/about.mdxdocs/index.ymldocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.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/configure-plugins/about.mdxdocs/index.ymldocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdx
🔇 Additional comments (5)
docs/configure-plugins/about.mdx (1)
36-37: LGTM!docs/index.yml (1)
43-45: LGTM!docs/configure-plugins/switchyard/about.mdx (1)
1-14: LGTM!Also applies to: 20-33, 39-68
docs/configure-plugins/switchyard/configuration.mdx (2)
1-175: LGTM!Also applies to: 180-298
176-179: 🎯 Functional Correctness
default_targetsis required, but its fields are optionalSwitchyardConfigrequires thedefault_targetsobject, yetProtocolDefaultsmarks each protocol field with#[serde(default)], so missing protocol entries deserialize to empty strings and are only checked for enabled inbound profiles.> Likely an incorrect or invalid review comment.
bbednarski9
changed the title
github-actions
Bot
added
size:L
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
crates/core/tests/unit/observability/plugin_component_tests.rs (1)
575-626: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winCover Leading and Trailing Whitespace Validation
" "exercises only the empty-after-trimming branch. Add a non-empty value such as" switchyard"and assert the whitespace-specific diagnostic.As per path instructions, tests should cover changed API error paths.
🤖 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 `@crates/core/tests/unit/observability/plugin_component_tests.rs` around lines 575 - 626, Add a separate endpoint fixture with a non-empty leading-whitespace name such as “ switchyard” in the test setup, then extend the assertions in the existing report validation test to require the whitespace-specific diagnostic for that endpoint’s name. Keep the existing blank-name assertion and endpoint indexing consistent with the updated fixture order.Source: Path instructions
docs/configure-plugins/observability/atof.mdx (1)
71-78: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winDocument
header_envin the Endpoint Field TableThe table says it describes each endpoint but omits
header_env, although the public config and Rust example expose it. Add its{}default and explain that it maps header names to environment variables containing their values.As per path instructions, documentation must be technically accurate against the current API.
🤖 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 `@docs/configure-plugins/observability/atof.mdx` around lines 71 - 78, Update the Endpoint Field Table in the observability configuration documentation to add the header_env field with a {} default. Describe it as a mapping from header names to environment variables that contain the corresponding header values, matching the current public configuration and Rust example.Source: Path instructions
🤖 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.
Inline comments:
In `@crates/switchyard/tests/unit/component_tests.rs`:
- Around line 260-262: Add a separate test case using Some(String::new())
alongside the existing whitespace case, and pass it to assert_invalid with the
validation error for an empty endpoint name, covering the name.trim().is_empty()
branch.
---
Outside diff comments:
In `@crates/core/tests/unit/observability/plugin_component_tests.rs`:
- Around line 575-626: Add a separate endpoint fixture with a non-empty
leading-whitespace name such as “ switchyard” in the test setup, then extend the
assertions in the existing report validation test to require the
whitespace-specific diagnostic for that endpoint’s name. Keep the existing
blank-name assertion and endpoint indexing consistent with the updated fixture
order.
In `@docs/configure-plugins/observability/atof.mdx`:
- Around line 71-78: Update the Endpoint Field Table in the observability
configuration documentation to add the header_env field with a {} default.
Describe it as a mapping from header names to environment variables that contain
the corresponding header values, matching the current public configuration and
Rust example.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: f6593a34-7dbb-469a-83ff-9cf837e46141
📒 Files selected for processing (15)
crates/core/src/observability/plugin_component.rscrates/core/tests/unit/observability/plugin_component_tests.rscrates/switchyard/README.mdcrates/switchyard/src/component.rscrates/switchyard/tests/unit/component_tests.rsdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdxexamples/switchyard/README.mdexamples/switchyard/hermes-ollama-plugins.tomlexamples/switchyard/plugins.tomlexamples/switchyard/real-e2e-plugins.tomlgo/nemo_relay/observability_plugin.gogo/nemo_relay/observability_plugin_test.go
📜 Review details
🧰 Additional context used
📓 Path-based instructions (32)
**/*.toml
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Add the SPDX license header to all TOML files using the
#comment form.
Files:
examples/switchyard/real-e2e-plugins.tomlexamples/switchyard/plugins.tomlexamples/switchyard/hermes-ollama-plugins.toml
{docs,examples}/**/*
📄 CodeRabbit inference engine (.agents/skills/rename-surfaces/SKILL.md)
Update docs and examples.
Files:
examples/switchyard/real-e2e-plugins.tomlexamples/switchyard/README.mdexamples/switchyard/plugins.tomlexamples/switchyard/hermes-ollama-plugins.tomldocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdx
**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
**/*: Format changed files with the language-native formatter before the final lint/test pass.
If dynamic plugin behavior changed, usemaintain-dynamic-pluginsand include the native SDK, worker protocol, Python SDK, docs, packaging, and Codecov surfaces in the validation plan.
If code changes alter APIs, bindings, commands, paths, packaging behavior, observability/adaptive semantics, or documented best practices, update any dependent maintainer or consumer skills in the same branch.
During iteration, preferuv run pre-commit run --files <changed files...>.
Before review or handoff, runuv run pre-commit run --all-files.
Files:
examples/switchyard/real-e2e-plugins.tomlcrates/switchyard/README.mdexamples/switchyard/README.mdexamples/switchyard/plugins.tomlgo/nemo_relay/observability_plugin.goexamples/switchyard/hermes-ollama-plugins.tomldocs/configure-plugins/observability/configuration.mdxcrates/core/src/observability/plugin_component.rsdocs/configure-plugins/switchyard/about.mdxgo/nemo_relay/observability_plugin_test.godocs/configure-plugins/observability/atof.mdxcrates/switchyard/src/component.rsdocs/configure-plugins/switchyard/configuration.mdxcrates/switchyard/tests/unit/component_tests.rscrates/core/tests/unit/observability/plugin_component_tests.rs
**/*.{md,rst,html,txt}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-brand-terminology.md)
**/*.{md,rst,html,txt}: Always spellNVIDIAin all caps. Do not useNvidia,nvidia,nVidia,nVIDIA, orNV.
Usean NVIDIAbefore a noun because the name starts with an 'en' sound.
Do not add a registered trademark symbol afterNVIDIAwhen referring to the company.
Use trademark symbols with product names only when the document type or legal guidance requires them.
Verify official capitalization, spacing, and hyphenation for product names.
Precede NVIDIA product names withNVIDIAon first mention when it is natural and accurate.
Do not rewrite product names for grammar or title-case rules.
Preserve third-party product names according to the owner's spelling.
Include the company name and full model qualifier on first use when it helps identify the model.
Preserve the official capitalization and punctuation of model names.
Use shorter family names only after the full name is established.
Spell out a term on first use and put the acronym in parentheses unless the acronym is widely understood by the intended audience.
Use the acronym on later mentions after it has been defined.
For long documents, reintroduce the full term if readers might lose context.
Form plurals of acronyms withs, not an apostrophe, such asGPUs.
In headings, common acronyms can remain abbreviated. Spell out the term in the first or second sentence of the body.
Common terms such asCPU,GPU,PC,API, andUIusually do not need to be spelled out for developer audiences.
Files:
crates/switchyard/README.mdexamples/switchyard/README.md
**/*.{md,rst,html}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-brand-terminology.md)
Link the first mention of a product name when the destination helps the reader.
Files:
crates/switchyard/README.mdexamples/switchyard/README.md
**/*.{md,rst,txt}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-guide.md)
Spell
NVIDIAin all caps. Do not useNvidia,nvidia, orNV.
Files:
crates/switchyard/README.mdexamples/switchyard/README.md
**/*.{md,rst}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-guide.md)
**/*.{md,rst}: Format commands, code elements, expressions, package names, file names, and paths as inline code.
Use descriptive link text. Avoid raw URLs and weak anchors such as "here" or "read more."
Use title case consistently for technical documentation headings.
Introduce code blocks, lists, tables, and images with complete sentences.
Write procedures as imperative steps. Keep steps parallel and split long procedures into smaller tasks.
Prefer active voice, present tense, short sentences, contractions, and plain English.
Usecanfor possibility and reservemayfor permission.
Useafterfor temporal relationships instead ofonce.
Preferrefer tooverseewhen the wording points readers to another resource.
Avoid culture-specific idioms, unnecessary Latinisms, jokes, and marketing exaggeration in technical docs.
Spell out months in body text, avoid ordinal dates, and use clear time zones.
Spell out whole numbers from zero through nine unless they are technical values, parameters, versions, or UI values.
Use numerals for 10 or greater and include commas in thousands.
Do not add trademark symbols to learning-oriented docs unless the source, platform, or legal guidance explicitly requires them.
Files:
crates/switchyard/README.mdexamples/switchyard/README.md
**/*.md
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-technical-docs.md)
**/*.md: Use title case consistently in technical documentation headings
Avoid quotation marks, ampersands, and exclamation marks in headings
Keep product, event, research, and whitepaper names in their official title case
Use title case for table headers
Do not force social-media sentence case into technical docs
Format code elements, commands, parameters, package names, and expressions in monospace
Format directories, file names, and paths in monospace using backticks
Use angle brackets inside monospace for variables inside paths, such as/home/<username>/.login
Format error messages and strings in quotation marks, keeping literal code strings in code formatting when clearer
Format UI buttons, menus, fields, and labels in bold
Use angle brackets between UI labels for menu paths, such as File > Save As
Use italics for new terms on first use, sparingly and only when introducing the term
Use italics for publication titles
Format keyboard shortcuts in plain text, such as Press Ctrl+Alt+Delete
Use owner/repo link text for GitHub repositories, preferring[NVIDIA/NeMo](link)over prose references like 'the GitHub repo'
Introduce every code block with a complete sentence
Do not make a code block complete the grammar of the previous sentence
Do not continue a sentence after a code block
Use syntax highlighting when the format supports it for code blocks
Avoid the word 'snippet' unless the surrounding docs already use it as a term of art
Keep inline method, function, and class references consistent with nearby docs, omitting empty parentheses for prose readability when no call is shown
Use descriptive anchor text that matches the destination title when possible for links
Avoid raw URLs in running text
Avoid generic anchor text such as 'here,' 'this page,' and 'read more'
Include acronyms in link text when a linked term includes an acronym
Do not link long sentences or multiple sentences
Avoid links that pull readers away from a procedure unless the link is a p...
Files:
crates/switchyard/README.mdexamples/switchyard/README.md
**/*.{md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
Update
README.md,fern/, package READMEs, and binding-support notes when public behavior, package names, examples, or supported bindings change.
**/*.{md,mdx}: Prefer the documented public API, not internal shortcuts
Keep package names, repo references, and build commands current
Keep release-process and release-notes guidance in repo-maintainer docs such asRELEASING.md, not as user-facing docs pages orCHANGELOG.md
Keep stable user-facing wrappers atscripts/root in docs and examples; only point at namespaced helper paths when documenting internal maintenance work
When detailed dynamic plugin guides exist, keep Rust native plugin examples, Python worker plugin examples, andgrpc-v1protocol details on separate pagesIf links in documentation change, run
just docs-linkcheck.
Files:
crates/switchyard/README.mdexamples/switchyard/README.mddocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdx
**/*.{md,markdown,mdx}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Add the SPDX license header to all Markdown/MDX documentation files using the HTML comment block form.
Files:
crates/switchyard/README.mdexamples/switchyard/README.mddocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdx
go/nemo_relay/**/*.go
📄 CodeRabbit inference engine (.agents/skills/test-go-binding/SKILL.md)
go/nemo_relay/**/*.go: Format changed Go packages withcd go/nemo_relay && go fmt ./...
Run Go tests withjust test-goto build and test the NeMo Relay Go binding
Usejust build-gowhen you want an explicit build-only pass or need the artifact for other work
Usejust ci=true test-gowhen you need the CI-style coverage and JUnit path
On macOS, setDYLD_LIBRARY_PATHto the../../target/releasedirectory before running the rawgo testcommand directlyUse
PascalCasefor public Go APIs.
Files:
go/nemo_relay/observability_plugin.gogo/nemo_relay/observability_plugin_test.go
**/*.go
📄 CodeRabbit inference engine (CONTRIBUTING.md)
When changing the experimental Go binding, format Go code with
gofmtand keepgo vet ./...passing.
Files:
go/nemo_relay/observability_plugin.gogo/nemo_relay/observability_plugin_test.go
**/*.{rs,py,go,js,ts,c,h}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Use language-appropriate naming conventions: Rust
snake_case, C FFI exports prefixednemo_relay_, GoPascalCase, Node.jscamelCase, and Pythonsnake_case.
Files:
go/nemo_relay/observability_plugin.gocrates/core/src/observability/plugin_component.rsgo/nemo_relay/observability_plugin_test.gocrates/switchyard/src/component.rscrates/switchyard/tests/unit/component_tests.rscrates/core/tests/unit/observability/plugin_component_tests.rs
**/*.{rs,go,js,ts}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Add the SPDX license header to all Rust, Go, JavaScript, and TypeScript source files using the corresponding
//comment form.
Files:
go/nemo_relay/observability_plugin.gocrates/core/src/observability/plugin_component.rsgo/nemo_relay/observability_plugin_test.gocrates/switchyard/src/component.rscrates/switchyard/tests/unit/component_tests.rscrates/core/tests/unit/observability/plugin_component_tests.rs
{crates/python/src/py_api/mod.rs,python/nemo_relay/**/*.py,python/nemo_relay/**/*.pyi,go/nemo_relay/**/*.go,crates/node/src/api/**/*.rs}
📄 CodeRabbit inference engine (.agents/skills/add-binding-feature/SKILL.md)
Update the language-native bindings for every exposed surface in Python, Go, and Node.js.
Files:
go/nemo_relay/observability_plugin.gogo/nemo_relay/observability_plugin_test.go
{python/nemo_relay/**/*.py,python/nemo_relay/**/*.pyi,go/nemo_relay/**/*.go}
📄 CodeRabbit inference engine (.agents/skills/add-binding-feature/SKILL.md)
Update language wrapper helpers such as Python wrapper modules, Python type stubs, and Go shorthand packages when the new behavior belongs in those helper layers.
Files:
go/nemo_relay/observability_plugin.gogo/nemo_relay/observability_plugin_test.go
**/*.{py,go,js,ts}
📄 CodeRabbit inference engine (.agents/skills/maintain-observability/SKILL.md)
Keep Python, Go, and Node.js config objects and subscriber/exporter methods aligned so all bindings expose the same logical knobs and semantics.
Files:
go/nemo_relay/observability_plugin.gogo/nemo_relay/observability_plugin_test.go
go/nemo_relay/**
📄 CodeRabbit inference engine (.agents/skills/maintain-optimizer/SKILL.md)
Keep shared plugin helpers in
go/nemo_relayaligned with plugin registration, composition, and lifecycle behavior.
Files:
go/nemo_relay/observability_plugin.gogo/nemo_relay/observability_plugin_test.go
**/*.{rs,py,go,js,ts}
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
If a language surface changed, always run that language's test target even when Rust core did not change.
Files:
go/nemo_relay/observability_plugin.gocrates/core/src/observability/plugin_component.rsgo/nemo_relay/observability_plugin_test.gocrates/switchyard/src/component.rscrates/switchyard/tests/unit/component_tests.rscrates/core/tests/unit/observability/plugin_component_tests.rs
go/nemo_relay/**/*
⚙️ CodeRabbit configuration file
go/nemo_relay/**/*: Review Go binding changes for cgo memory ownership, race safety, callback cleanup, idiomatic exported APIs, and parity with Rust/FFI behavior.
Any API change should include focused Go tests and consider race-test behavior.
Files:
go/nemo_relay/observability_plugin.gogo/nemo_relay/observability_plugin_test.go
**/*.mdx
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/SKILL.md)
MDX top-of-file SPDX comments must use {/* ... */} delimiters instead of HTML comment delimiters (Must-Fix)
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
Files:
docs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdx
docs/**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
If documentation examples or commands under
docs/change, run the targeted docs checks appropriate to the change.
Files:
docs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.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/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdx
**/*.rs
📄 CodeRabbit inference engine (.agents/skills/prepare-pr/SKILL.md)
**/*.rs: Any Rust change must runjust test-rust
Any Rust change must runcargo fmt --all
Any Rust change must runcargo clippy --workspace --all-targets -- -D warnings
**/*.rs: Runcargo fmt --allfor all FFI work since it is Rust work
Runjust test-rustto validate FFI changes
Runcargo clippy --workspace --all-targets -- -D warningsto enforce strict linting on FFI workWhen Rust files changed as part of Go work, also run
cargo fmt --all,just test-rust, andcargo clippy --workspace --all-targets -- -D warnings
**/*.rs: Runcargo fmt --allwhen Rust files are changed as part of Node work
Runcargo clippy --workspace --all-targets -- -D warningswhen Rust files are changed as part of Node work
Runjust test-rustwhen Rust files are changed as part of Node workWhen changing the core Rust runtime or Rust-facing API surface, format Rust code with
cargo fmt(rustfmt defaults), keepcargo clippy -- -D warningsclean, and satisfycargo deny checkperdeny.toml.
**/*.rs: If any Rust code changed, always runjust test-rust.
If any Rust code changed, also runcargo fmt --all.
If any Rust code changed, also runcargo clippy --workspace --all-targets -- -D warnings.
For Rust changes headed for review, runcargo fmt --allandcargo clippy --workspace --all-targets -- -D warningseven if relying on pre-commit.
Files:
crates/core/src/observability/plugin_component.rscrates/switchyard/src/component.rscrates/switchyard/tests/unit/component_tests.rscrates/core/tests/unit/observability/plugin_component_tests.rs
{crates/core,crates/adaptive}/**/*
📄 CodeRabbit inference engine (.agents/skills/prepare-pr/SKILL.md)
Changes to
crates/coreorcrates/adaptivemust run the full language matrix
Files:
crates/core/src/observability/plugin_component.rscrates/core/tests/unit/observability/plugin_component_tests.rs
crates/core/**/*.rs
📄 CodeRabbit inference engine (.agents/skills/test-go-binding/SKILL.md)
If the change touched
crates/coreor shared runtime semantics, also usevalidate-changefor broader validation
Files:
crates/core/src/observability/plugin_component.rscrates/core/tests/unit/observability/plugin_component_tests.rs
**/*.{rs,py}
📄 CodeRabbit inference engine (AGENTS.md)
Follow binding naming conventions in Rust and Python: use
snake_case.
Files:
crates/core/src/observability/plugin_component.rscrates/switchyard/src/component.rscrates/switchyard/tests/unit/component_tests.rscrates/core/tests/unit/observability/plugin_component_tests.rs
**/*.{rs,py,js,mjs,cjs,ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{rs,py,js,mjs,cjs,ts,tsx}: UseJson = serde_json::Valuein Rust-facing runtime APIs where the existing code expects JSON payloads.
UseResult<T>withFlowErrorin core runtime paths, and keep errors explicit and binding-appropriate at the wrapper layer.
Keep async behavior on the existing tokio-based model; bindings should preserve callback and future lifetimes rather than blocking or hiding async work unexpectedly.
Files:
crates/core/src/observability/plugin_component.rscrates/switchyard/src/component.rscrates/switchyard/tests/unit/component_tests.rscrates/core/tests/unit/observability/plugin_component_tests.rs
{crates/**/src/**/*.rs,python/**/*.py}
📄 CodeRabbit inference engine (.agents/skills/maintain-dynamic-plugins/SKILL.md)
Do not add tests under
src; Rust tests belong in cratetests/trees, and Python SDK tests belong underpython/tests.
Files:
crates/core/src/observability/plugin_component.rscrates/switchyard/src/component.rs
crates/{core,adaptive}/**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
If
crates/coreorcrates/adaptivechanged, run the full validation matrix across Rust, Python, Go, and Node.js.
Files:
crates/core/src/observability/plugin_component.rscrates/core/tests/unit/observability/plugin_component_tests.rs
crates/{core,adaptive}/**/*.rs
⚙️ CodeRabbit configuration file
crates/{core,adaptive}/**/*.rs: Review the Rust runtime for async correctness, scope isolation, middleware ordering, and event lifecycle regressions.
Pay close attention to task-local/thread-local scope propagation, callback lifetimes, stream finalization, and root_uuid isolation.
Public API changes should preserve existing behavior unless tests and docs show the intended migration path.
Files:
crates/core/src/observability/plugin_component.rscrates/core/tests/unit/observability/plugin_component_tests.rs
{crates/**/tests/**,python/tests/**,go/nemo_relay/**/*_test.go}
⚙️ CodeRabbit configuration file
{crates/**/tests/**,python/tests/**,go/nemo_relay/**/*_test.go}: Tests should cover the behavior promised by the changed API surface, including error paths and cross-request isolation where relevant.
Prefer assertions on lifecycle events, scope stacks, middleware ordering, and binding parity over shallow smoke tests.
Files:
go/nemo_relay/observability_plugin_test.gocrates/switchyard/tests/unit/component_tests.rscrates/core/tests/unit/observability/plugin_component_tests.rs
🧠 Learnings (1)
📚 Learning: 2026-07-14T02:53:59.997Z
Learnt from: willkill07
Repo: NVIDIA/NeMo-Relay PR: 415
File: docs/configure-plugins/observability/opentelemetry.mdx:98-113
Timestamp: 2026-07-14T02:53:59.997Z
Learning: In NeMo-Relay’s OpenTelemetry/OpenInference observability projection docs under docs/configure-plugins/observability/, document the projected-attribute contract as follows: (1) emit scalar top-level `data`/`metadata` fields as typed dotted OTLP attributes (for example, `nemo_relay.start.metadata.tenant`); (2) keep nested objects/arrays as JSON strings at their top-level OTLP attribute (rather than expanding them into nested OTLP attributes); and (3) do not reference the legacy `*_json` payload attributes (e.g., `data_json`, `metadata_json`, `input_json`) because they were intentionally removed as a breaking change.
Applied to files:
docs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/observability/atof.mdx
🔇 Additional comments (15)
crates/switchyard/README.md (1)
101-105: LGTM!examples/switchyard/README.md (1)
82-85: LGTM!examples/switchyard/hermes-ollama-plugins.toml (1)
16-16: LGTM!Also applies to: 64-64
examples/switchyard/plugins.toml (1)
17-17: LGTM!Also applies to: 64-64
examples/switchyard/real-e2e-plugins.toml (1)
16-16: LGTM!Also applies to: 62-62
crates/core/src/observability/plugin_component.rs (1)
190-192: 📐 Maintainability & Code QualityVerify Required Rust Validation
The supplied validation summary does not show the mandatory Rust checks for these changes.
crates/core/src/observability/plugin_component.rs#L190-L192: Runcargo fmt --all,cargo clippy --workspace --all-targets -- -D warnings, andjust test-rust.crates/core/tests/unit/observability/plugin_component_tests.rs#L207-L211: Include the updated tests in the same validation run.As per coding guidelines, any Rust change must run these checks.
Source: Coding guidelines
crates/core/tests/unit/observability/plugin_component_tests.rs (1)
309-309: LGTM!Also applies to: 633-690
docs/configure-plugins/observability/atof.mdx (1)
40-40: LGTM!Also applies to: 231-235
docs/configure-plugins/observability/configuration.mdx (1)
76-76: LGTM!Also applies to: 324-328
docs/configure-plugins/switchyard/configuration.mdx (1)
146-158: LGTM!Also applies to: 225-245, 276-278
go/nemo_relay/observability_plugin.go (1)
44-44: 📐 Maintainability & Code QualityRun the Required Go Validation
Please provide results for
go fmt ./...,go vet ./..., andjust test-gobefore handoff. As per coding guidelines, changed experimental Go bindings must be formatted and keepgo vet ./...passing.Source: Coding guidelines
go/nemo_relay/observability_plugin_test.go (1)
39-39: LGTM!Also applies to: 89-97
crates/switchyard/src/component.rs (1)
220-222: 📐 Maintainability & Code QualityRun the Required Rust Checks
Please provide results for
cargo fmt --all,cargo clippy --workspace --all-targets -- -D warnings, andjust test-rust. As per coding guidelines, all Rust changes require these checks before review or handoff.Source: Coding guidelines
crates/switchyard/tests/unit/component_tests.rs (1)
349-393: LGTM!Also applies to: 707-707, 839-851
docs/configure-plugins/switchyard/about.mdx (1)
18-20: LGTM!Also applies to: 39-40
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
crates/switchyard/README.md (1)
100-105: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick winDocument the required
field_name_policysetting.The guidance identifies the endpoint name, URL, and environment-backed authentication, but Switchyard validation also requires
field_name_policy = "preserve"andtransport = "http_post". Add those requirements or link to the complete endpoint contract so users do not configure an endpoint that fails startup validation.As per path instructions, documentation must remain technically accurate against the current API contract.
🤖 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 `@crates/switchyard/README.md` around lines 100 - 105, Update the ATOF-backed profile guidance in the Switchyard README to require Relay ATOF HTTP exporters to set field_name_policy to "preserve" and transport to "http_post", alongside the existing endpoint requirements. Ensure the documented configuration matches the current endpoint validation contract, or link to the complete contract.Source: Path instructions
🤖 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.
Inline comments:
In `@examples/switchyard/README.md`:
- Around line 72-78: Add a complete introductory sentence immediately before the
configuration-files bullets in the “Configuration Files” section, stating that
the examples use the listed files. Preserve the existing items and ensure each
bullet remains grammatically parallel and complete.
---
Outside diff comments:
In `@crates/switchyard/README.md`:
- Around line 100-105: Update the ATOF-backed profile guidance in the Switchyard
README to require Relay ATOF HTTP exporters to set field_name_policy to
"preserve" and transport to "http_post", alongside the existing endpoint
requirements. Ensure the documented configuration matches the current endpoint
validation contract, or link to the complete contract.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 10690be9-fe52-4545-a370-1c04414c429e
📒 Files selected for processing (6)
crates/switchyard/README.mddocs/configure-plugins/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdxexamples/switchyard/README.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (12)
**/*.mdx
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/SKILL.md)
MDX top-of-file SPDX comments must use {/* ... */} delimiters instead of HTML comment delimiters (Must-Fix)
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
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
Update
README.md,fern/, package READMEs, and binding-support notes when public behavior, package names, examples, or supported bindings change.
**/*.{md,mdx}: Prefer the documented public API, not internal shortcuts
Keep package names, repo references, and build commands current
Keep release-process and release-notes guidance in repo-maintainer docs such asRELEASING.md, not as user-facing docs pages orCHANGELOG.md
Keep stable user-facing wrappers atscripts/root in docs and examples; only point at namespaced helper paths when documenting internal maintenance work
When detailed dynamic plugin guides exist, keep Rust native plugin examples, Python worker plugin examples, andgrpc-v1protocol details on separate pagesIf links in documentation change, run
just docs-linkcheck.
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxexamples/switchyard/README.mdcrates/switchyard/README.mddocs/configure-plugins/switchyard/configuration.mdx
**/*.{md,markdown,mdx}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Add the SPDX license header to all Markdown/MDX documentation files using the HTML comment block form.
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxexamples/switchyard/README.mdcrates/switchyard/README.mddocs/configure-plugins/switchyard/configuration.mdx
{docs,examples}/**/*
📄 CodeRabbit inference engine (.agents/skills/rename-surfaces/SKILL.md)
Update docs and examples.
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxexamples/switchyard/README.mddocs/configure-plugins/switchyard/configuration.mdx
**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
**/*: Format changed files with the language-native formatter before the final lint/test pass.
If dynamic plugin behavior changed, usemaintain-dynamic-pluginsand include the native SDK, worker protocol, Python SDK, docs, packaging, and Codecov surfaces in the validation plan.
If code changes alter APIs, bindings, commands, paths, packaging behavior, observability/adaptive semantics, or documented best practices, update any dependent maintainer or consumer skills in the same branch.
During iteration, preferuv run pre-commit run --files <changed files...>.
Before review or handoff, runuv run pre-commit run --all-files.
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxexamples/switchyard/README.mdcrates/switchyard/README.mddocs/configure-plugins/switchyard/configuration.mdx
docs/**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
If documentation examples or commands under
docs/change, run the targeted docs checks appropriate to the change.
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.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/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdx
**/*.{md,rst,html,txt}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-brand-terminology.md)
**/*.{md,rst,html,txt}: Always spellNVIDIAin all caps. Do not useNvidia,nvidia,nVidia,nVIDIA, orNV.
Usean NVIDIAbefore a noun because the name starts with an 'en' sound.
Do not add a registered trademark symbol afterNVIDIAwhen referring to the company.
Use trademark symbols with product names only when the document type or legal guidance requires them.
Verify official capitalization, spacing, and hyphenation for product names.
Precede NVIDIA product names withNVIDIAon first mention when it is natural and accurate.
Do not rewrite product names for grammar or title-case rules.
Preserve third-party product names according to the owner's spelling.
Include the company name and full model qualifier on first use when it helps identify the model.
Preserve the official capitalization and punctuation of model names.
Use shorter family names only after the full name is established.
Spell out a term on first use and put the acronym in parentheses unless the acronym is widely understood by the intended audience.
Use the acronym on later mentions after it has been defined.
For long documents, reintroduce the full term if readers might lose context.
Form plurals of acronyms withs, not an apostrophe, such asGPUs.
In headings, common acronyms can remain abbreviated. Spell out the term in the first or second sentence of the body.
Common terms such asCPU,GPU,PC,API, andUIusually do not need to be spelled out for developer audiences.
Files:
examples/switchyard/README.mdcrates/switchyard/README.md
**/*.{md,rst,html}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-brand-terminology.md)
Link the first mention of a product name when the destination helps the reader.
Files:
examples/switchyard/README.mdcrates/switchyard/README.md
**/*.{md,rst,txt}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-guide.md)
Spell
NVIDIAin all caps. Do not useNvidia,nvidia, orNV.
Files:
examples/switchyard/README.mdcrates/switchyard/README.md
**/*.{md,rst}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-guide.md)
**/*.{md,rst}: Format commands, code elements, expressions, package names, file names, and paths as inline code.
Use descriptive link text. Avoid raw URLs and weak anchors such as "here" or "read more."
Use title case consistently for technical documentation headings.
Introduce code blocks, lists, tables, and images with complete sentences.
Write procedures as imperative steps. Keep steps parallel and split long procedures into smaller tasks.
Prefer active voice, present tense, short sentences, contractions, and plain English.
Usecanfor possibility and reservemayfor permission.
Useafterfor temporal relationships instead ofonce.
Preferrefer tooverseewhen the wording points readers to another resource.
Avoid culture-specific idioms, unnecessary Latinisms, jokes, and marketing exaggeration in technical docs.
Spell out months in body text, avoid ordinal dates, and use clear time zones.
Spell out whole numbers from zero through nine unless they are technical values, parameters, versions, or UI values.
Use numerals for 10 or greater and include commas in thousands.
Do not add trademark symbols to learning-oriented docs unless the source, platform, or legal guidance explicitly requires them.
Files:
examples/switchyard/README.mdcrates/switchyard/README.md
**/*.md
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-technical-docs.md)
**/*.md: Use title case consistently in technical documentation headings
Avoid quotation marks, ampersands, and exclamation marks in headings
Keep product, event, research, and whitepaper names in their official title case
Use title case for table headers
Do not force social-media sentence case into technical docs
Format code elements, commands, parameters, package names, and expressions in monospace
Format directories, file names, and paths in monospace using backticks
Use angle brackets inside monospace for variables inside paths, such as/home/<username>/.login
Format error messages and strings in quotation marks, keeping literal code strings in code formatting when clearer
Format UI buttons, menus, fields, and labels in bold
Use angle brackets between UI labels for menu paths, such as File > Save As
Use italics for new terms on first use, sparingly and only when introducing the term
Use italics for publication titles
Format keyboard shortcuts in plain text, such as Press Ctrl+Alt+Delete
Use owner/repo link text for GitHub repositories, preferring[NVIDIA/NeMo](link)over prose references like 'the GitHub repo'
Introduce every code block with a complete sentence
Do not make a code block complete the grammar of the previous sentence
Do not continue a sentence after a code block
Use syntax highlighting when the format supports it for code blocks
Avoid the word 'snippet' unless the surrounding docs already use it as a term of art
Keep inline method, function, and class references consistent with nearby docs, omitting empty parentheses for prose readability when no call is shown
Use descriptive anchor text that matches the destination title when possible for links
Avoid raw URLs in running text
Avoid generic anchor text such as 'here,' 'this page,' and 'read more'
Include acronyms in link text when a linked term includes an acronym
Do not link long sentences or multiple sentences
Avoid links that pull readers away from a procedure unless the link is a p...
Files:
examples/switchyard/README.mdcrates/switchyard/README.md
🧠 Learnings (1)
📚 Learning: 2026-07-14T02:53:59.997Z
Learnt from: willkill07
Repo: NVIDIA/NeMo-Relay PR: 415
File: docs/configure-plugins/observability/opentelemetry.mdx:98-113
Timestamp: 2026-07-14T02:53:59.997Z
Learning: In NeMo-Relay’s OpenTelemetry/OpenInference observability projection docs under docs/configure-plugins/observability/, document the projected-attribute contract as follows: (1) emit scalar top-level `data`/`metadata` fields as typed dotted OTLP attributes (for example, `nemo_relay.start.metadata.tenant`); (2) keep nested objects/arrays as JSON strings at their top-level OTLP attribute (rather than expanding them into nested OTLP attributes); and (3) do not reference the legacy `*_json` payload attributes (e.g., `data_json`, `metadata_json`, `input_json`) because they were intentionally removed as a breaking change.
Applied to files:
docs/configure-plugins/observability/atof.mdx
🔇 Additional comments (7)
docs/configure-plugins/observability/atof.mdx (1)
40-40: LGTM!Also applies to: 73-84, 236-240
crates/switchyard/README.md (1)
22-22: LGTM!Also applies to: 34-34, 46-46, 59-59, 73-76
examples/switchyard/README.md (1)
6-12: LGTM!Also applies to: 21-30, 48-48, 61-61, 80-91, 93-98
docs/configure-plugins/about.mdx (1)
36-38: LGTM!docs/configure-plugins/switchyard/about.mdx (2)
11-53: LGTM!
1-13: 📐 Maintainability & Code QualitySPDX headers already use the required MDX syntax Both
docs/configure-plugins/switchyard/about.mdxanddocs/configure-plugins/switchyard/configuration.mdxalready use{/* ... */}.> Likely an incorrect or invalid review comment.docs/configure-plugins/switchyard/configuration.mdx (1)
22-333: LGTM!
ec1fd8b to
f4f83a5
Compare
github-actions
Bot
added
size:M
bbednarski9
changed the title
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
f4f83a5 to
9b07e6f
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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.
Inline comments:
In `@docs/configure-plugins/observability/atof.mdx`:
- Line 40: Align the Switchyard ATOF validation in the component configuration
flow with the documented name-based selector: consume atof_endpoint_name and
match it against the endpoint name instead of validating URL plus http_post. The
sites docs/configure-plugins/observability/atof.mdx:40,
docs/configure-plugins/observability/configuration.mdx:76-76,
crates/switchyard/README.md:100-105,
examples/switchyard/hermes-ollama-plugins.toml:16-16,
examples/switchyard/plugins.toml:17-17, and
examples/switchyard/real-e2e-plugins.toml:16-16 require no direct changes
because they already define the intended contract.
In `@docs/configure-plugins/switchyard/configuration.mdx`:
- Around line 169-185: Update the Switchyard documentation references from
atof_endpoint_name to the actual SwitchyardConfig key atof_endpoint_url in
docs/configure-plugins/switchyard/configuration.mdx (lines 169-185),
docs/configure-plugins/switchyard/about.mdx (lines 40-44), and
crates/switchyard/README.md. Keep the documented endpoint behavior consistent
while using the existing code-level configuration name; do not rename the field
in code.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: a6514014-82f7-485e-97dd-19017da219c8
📒 Files selected for processing (11)
crates/switchyard/README.mddocs/configure-plugins/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdxdocs/index.ymlexamples/switchyard/README.mdexamples/switchyard/hermes-ollama-plugins.tomlexamples/switchyard/plugins.tomlexamples/switchyard/real-e2e-plugins.toml
📜 Review details
🧰 Additional context used
📓 Path-based instructions (13)
{docs,examples}/**/*
📄 CodeRabbit inference engine (.agents/skills/rename-surfaces/SKILL.md)
Update docs and examples.
Files:
docs/index.ymldocs/configure-plugins/about.mdxexamples/switchyard/hermes-ollama-plugins.tomlexamples/switchyard/real-e2e-plugins.tomlexamples/switchyard/plugins.tomldocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdxdocs/configure-plugins/observability/configuration.mdxexamples/switchyard/README.md
**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
**/*: Format changed files with the language-native formatter before the final lint/test pass.
If dynamic plugin behavior changed, usemaintain-dynamic-pluginsand include the native SDK, worker protocol, Python SDK, docs, packaging, and Codecov surfaces in the validation plan.
If code changes alter APIs, bindings, commands, paths, packaging behavior, observability/adaptive semantics, or documented best practices, update any dependent maintainer or consumer skills in the same branch.
During iteration, preferuv run pre-commit run --files <changed files...>.
Before review or handoff, runuv run pre-commit run --all-files.
Files:
docs/index.ymldocs/configure-plugins/about.mdxexamples/switchyard/hermes-ollama-plugins.tomlexamples/switchyard/real-e2e-plugins.tomlexamples/switchyard/plugins.tomldocs/configure-plugins/switchyard/about.mdxcrates/switchyard/README.mddocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdxdocs/configure-plugins/observability/configuration.mdxexamples/switchyard/README.md
docs/**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
If documentation examples or commands under
docs/change, run the targeted docs checks appropriate to the change.
Files:
docs/index.ymldocs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdxdocs/configure-plugins/observability/configuration.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/index.ymldocs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdxdocs/configure-plugins/observability/configuration.mdx
**/*.mdx
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/SKILL.md)
MDX top-of-file SPDX comments must use {/* ... */} delimiters instead of HTML comment delimiters (Must-Fix)
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
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdxdocs/configure-plugins/observability/configuration.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
Update
README.md,fern/, package READMEs, and binding-support notes when public behavior, package names, examples, or supported bindings change.
**/*.{md,mdx}: Prefer the documented public API, not internal shortcuts
Keep package names, repo references, and build commands current
Keep release-process and release-notes guidance in repo-maintainer docs such asRELEASING.md, not as user-facing docs pages orCHANGELOG.md
Keep stable user-facing wrappers atscripts/root in docs and examples; only point at namespaced helper paths when documenting internal maintenance work
When detailed dynamic plugin guides exist, keep Rust native plugin examples, Python worker plugin examples, andgrpc-v1protocol details on separate pagesIf links in documentation change, run
just docs-linkcheck.
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxcrates/switchyard/README.mddocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdxdocs/configure-plugins/observability/configuration.mdxexamples/switchyard/README.md
**/*.{md,markdown,mdx}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Add the SPDX license header to all Markdown/MDX documentation files using the HTML comment block form.
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/switchyard/about.mdxcrates/switchyard/README.mddocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/switchyard/configuration.mdxdocs/configure-plugins/observability/configuration.mdxexamples/switchyard/README.md
**/*.toml
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Add the SPDX license header to all TOML files using the
#comment form.
Files:
examples/switchyard/hermes-ollama-plugins.tomlexamples/switchyard/real-e2e-plugins.tomlexamples/switchyard/plugins.toml
**/*.{md,rst,html,txt}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-brand-terminology.md)
**/*.{md,rst,html,txt}: Always spellNVIDIAin all caps. Do not useNvidia,nvidia,nVidia,nVIDIA, orNV.
Usean NVIDIAbefore a noun because the name starts with an 'en' sound.
Do not add a registered trademark symbol afterNVIDIAwhen referring to the company.
Use trademark symbols with product names only when the document type or legal guidance requires them.
Verify official capitalization, spacing, and hyphenation for product names.
Precede NVIDIA product names withNVIDIAon first mention when it is natural and accurate.
Do not rewrite product names for grammar or title-case rules.
Preserve third-party product names according to the owner's spelling.
Include the company name and full model qualifier on first use when it helps identify the model.
Preserve the official capitalization and punctuation of model names.
Use shorter family names only after the full name is established.
Spell out a term on first use and put the acronym in parentheses unless the acronym is widely understood by the intended audience.
Use the acronym on later mentions after it has been defined.
For long documents, reintroduce the full term if readers might lose context.
Form plurals of acronyms withs, not an apostrophe, such asGPUs.
In headings, common acronyms can remain abbreviated. Spell out the term in the first or second sentence of the body.
Common terms such asCPU,GPU,PC,API, andUIusually do not need to be spelled out for developer audiences.
Files:
crates/switchyard/README.mdexamples/switchyard/README.md
**/*.{md,rst,html}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-brand-terminology.md)
Link the first mention of a product name when the destination helps the reader.
Files:
crates/switchyard/README.mdexamples/switchyard/README.md
**/*.{md,rst,txt}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-guide.md)
Spell
NVIDIAin all caps. Do not useNvidia,nvidia, orNV.
Files:
crates/switchyard/README.mdexamples/switchyard/README.md
**/*.{md,rst}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-guide.md)
**/*.{md,rst}: Format commands, code elements, expressions, package names, file names, and paths as inline code.
Use descriptive link text. Avoid raw URLs and weak anchors such as "here" or "read more."
Use title case consistently for technical documentation headings.
Introduce code blocks, lists, tables, and images with complete sentences.
Write procedures as imperative steps. Keep steps parallel and split long procedures into smaller tasks.
Prefer active voice, present tense, short sentences, contractions, and plain English.
Usecanfor possibility and reservemayfor permission.
Useafterfor temporal relationships instead ofonce.
Preferrefer tooverseewhen the wording points readers to another resource.
Avoid culture-specific idioms, unnecessary Latinisms, jokes, and marketing exaggeration in technical docs.
Spell out months in body text, avoid ordinal dates, and use clear time zones.
Spell out whole numbers from zero through nine unless they are technical values, parameters, versions, or UI values.
Use numerals for 10 or greater and include commas in thousands.
Do not add trademark symbols to learning-oriented docs unless the source, platform, or legal guidance explicitly requires them.
Files:
crates/switchyard/README.mdexamples/switchyard/README.md
**/*.md
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-technical-docs.md)
**/*.md: Use title case consistently in technical documentation headings
Avoid quotation marks, ampersands, and exclamation marks in headings
Keep product, event, research, and whitepaper names in their official title case
Use title case for table headers
Do not force social-media sentence case into technical docs
Format code elements, commands, parameters, package names, and expressions in monospace
Format directories, file names, and paths in monospace using backticks
Use angle brackets inside monospace for variables inside paths, such as/home/<username>/.login
Format error messages and strings in quotation marks, keeping literal code strings in code formatting when clearer
Format UI buttons, menus, fields, and labels in bold
Use angle brackets between UI labels for menu paths, such as File > Save As
Use italics for new terms on first use, sparingly and only when introducing the term
Use italics for publication titles
Format keyboard shortcuts in plain text, such as Press Ctrl+Alt+Delete
Use owner/repo link text for GitHub repositories, preferring[NVIDIA/NeMo](link)over prose references like 'the GitHub repo'
Introduce every code block with a complete sentence
Do not make a code block complete the grammar of the previous sentence
Do not continue a sentence after a code block
Use syntax highlighting when the format supports it for code blocks
Avoid the word 'snippet' unless the surrounding docs already use it as a term of art
Keep inline method, function, and class references consistent with nearby docs, omitting empty parentheses for prose readability when no call is shown
Use descriptive anchor text that matches the destination title when possible for links
Avoid raw URLs in running text
Avoid generic anchor text such as 'here,' 'this page,' and 'read more'
Include acronyms in link text when a linked term includes an acronym
Do not link long sentences or multiple sentences
Avoid links that pull readers away from a procedure unless the link is a p...
Files:
crates/switchyard/README.mdexamples/switchyard/README.md
🧠 Learnings (1)
📚 Learning: 2026-07-14T02:53:59.997Z
Learnt from: willkill07
Repo: NVIDIA/NeMo-Relay PR: 415
File: docs/configure-plugins/observability/opentelemetry.mdx:98-113
Timestamp: 2026-07-14T02:53:59.997Z
Learning: In NeMo-Relay’s OpenTelemetry/OpenInference observability projection docs under docs/configure-plugins/observability/, document the projected-attribute contract as follows: (1) emit scalar top-level `data`/`metadata` fields as typed dotted OTLP attributes (for example, `nemo_relay.start.metadata.tenant`); (2) keep nested objects/arrays as JSON strings at their top-level OTLP attribute (rather than expanding them into nested OTLP attributes); and (3) do not reference the legacy `*_json` payload attributes (e.g., `data_json`, `metadata_json`, `input_json`) because they were intentionally removed as a breaking change.
Applied to files:
docs/configure-plugins/observability/atof.mdxdocs/configure-plugins/observability/configuration.mdx
🔇 Additional comments (9)
crates/switchyard/README.md (1)
22-22: LGTM!Also applies to: 34-34, 46-46, 59-59, 73-76
examples/switchyard/README.md (3)
72-79: 📐 Maintainability & Code Quality | ⚡ Quick winAdd a lead-in sentence to the Configuration Files list.
This list still opens directly under the heading with no introductory sentence. As per coding guidelines, "All lists must have a complete lead-in sentence." This was already flagged on a prior commit for this exact range and remains unaddressed.
📝 Proposed fix
## Configuration Files +The examples use the following configuration files: + - `plugins.toml`: minimal plugin configuration example.Source: Coding guidelines
21-30: 📐 Maintainability & Code Quality | ⚡ Quick winState the required working directory before the clone command.
The clone target
../Switchyard-topic-nemo-relay-integrationis relative to the caller's working directory, but the instruction to run commands from the NeMo Relay checkout root only appears later, under "## Examples" (Line 43). A reader following the doc top-to-bottom can clone into the wrong location relative to what the scripts (andSWITCHYARD_ROOTdefault) expect.📝 Proposed fix
+Run the following commands from the root of the NeMo Relay checkout so the +cloned worktree lands next to it. + Clone the Switchyard repository next to the Relay checkout, then pin the required commit:
6-20: LGTM!Also applies to: 32-71, 80-99
docs/configure-plugins/switchyard/about.mdx (2)
15-23: LGTM!
1-14: LGTM!Also applies to: 24-39, 45-74
docs/configure-plugins/switchyard/configuration.mdx (1)
1-168: LGTM!Also applies to: 186-334
docs/configure-plugins/about.mdx (1)
36-38: LGTM!docs/index.yml (1)
43-45: LGTM!
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
examples/switchyard/README.md (1)
72-79: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winMissing lead-in sentence for the configuration-files list.
Still no introductory sentence before the bullet list; this was already flagged in a prior review round and remains unaddressed.
✏️ Suggested fix
## Configuration Files +The examples use the following configuration files: + - `plugins.toml`: minimal plugin configuration example.As per coding guidelines, "All lists must have a complete lead-in sentence."
🤖 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 `@examples/switchyard/README.md` around lines 72 - 79, Add a complete introductory sentence immediately before the configuration-files bullet list under “Configuration Files” in the README, clearly stating that the listed files provide the example’s configuration and supporting artifacts.Source: Coding guidelines
🤖 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.
Inline comments:
In `@docs/configure-plugins/switchyard/configuration.mdx`:
- Around line 131-141: Add a complete lead-in sentence immediately before the
“Decision API and Rollout Options” table, and apply the same treatment to the
“Context, Retries, and Inbound Protocols” and “Target Bindings and Trusted
Defaults” tables. Keep the existing table content unchanged and match the
lead-in style used by the other tables in the document.
- Around line 24-39: Rewrite step 5 to begin with an imperative verb, while
preserving its existing requirements for profiles depending on ATOF history,
including StageRouter.
---
Duplicate comments:
In `@examples/switchyard/README.md`:
- Around line 72-79: Add a complete introductory sentence immediately before the
configuration-files bullet list under “Configuration Files” in the README,
clearly stating that the listed files provide the example’s configuration and
supporting artifacts.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: d4c40586-a8fe-4256-bc84-250c6cb60b77
📒 Files selected for processing (8)
crates/switchyard/README.mddocs/configure-plugins/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdxdocs/index.ymlexamples/switchyard/README.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (12)
{docs,examples}/**/*
📄 CodeRabbit inference engine (.agents/skills/rename-surfaces/SKILL.md)
Update docs and examples.
Files:
docs/index.ymldocs/configure-plugins/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdxexamples/switchyard/README.md
**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
**/*: Format changed files with the language-native formatter before the final lint/test pass.
If dynamic plugin behavior changed, usemaintain-dynamic-pluginsand include the native SDK, worker protocol, Python SDK, docs, packaging, and Codecov surfaces in the validation plan.
If code changes alter APIs, bindings, commands, paths, packaging behavior, observability/adaptive semantics, or documented best practices, update any dependent maintainer or consumer skills in the same branch.
During iteration, preferuv run pre-commit run --files <changed files...>.
Before review or handoff, runuv run pre-commit run --all-files.
Files:
docs/index.ymldocs/configure-plugins/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdxexamples/switchyard/README.mdcrates/switchyard/README.md
docs/**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
If documentation examples or commands under
docs/change, run the targeted docs checks appropriate to the change.
Files:
docs/index.ymldocs/configure-plugins/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.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/index.ymldocs/configure-plugins/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdx
**/*.mdx
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/SKILL.md)
MDX top-of-file SPDX comments must use {/* ... */} delimiters instead of HTML comment delimiters (Must-Fix)
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
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
Update
README.md,fern/, package READMEs, and binding-support notes when public behavior, package names, examples, or supported bindings change.
**/*.{md,mdx}: Prefer the documented public API, not internal shortcuts
Keep package names, repo references, and build commands current
Keep release-process and release-notes guidance in repo-maintainer docs such asRELEASING.md, not as user-facing docs pages orCHANGELOG.md
Keep stable user-facing wrappers atscripts/root in docs and examples; only point at namespaced helper paths when documenting internal maintenance work
When detailed dynamic plugin guides exist, keep Rust native plugin examples, Python worker plugin examples, andgrpc-v1protocol details on separate pagesIf links in documentation change, run
just docs-linkcheck.
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdxexamples/switchyard/README.mdcrates/switchyard/README.md
**/*.{md,markdown,mdx}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Add the SPDX license header to all Markdown/MDX documentation files using the HTML comment block form.
Files:
docs/configure-plugins/about.mdxdocs/configure-plugins/observability/atof.mdxdocs/configure-plugins/observability/configuration.mdxdocs/configure-plugins/switchyard/about.mdxdocs/configure-plugins/switchyard/configuration.mdxexamples/switchyard/README.mdcrates/switchyard/README.md
**/*.{md,rst,html,txt}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-brand-terminology.md)
**/*.{md,rst,html,txt}: Always spellNVIDIAin all caps. Do not useNvidia,nvidia,nVidia,nVIDIA, orNV.
Usean NVIDIAbefore a noun because the name starts with an 'en' sound.
Do not add a registered trademark symbol afterNVIDIAwhen referring to the company.
Use trademark symbols with product names only when the document type or legal guidance requires them.
Verify official capitalization, spacing, and hyphenation for product names.
Precede NVIDIA product names withNVIDIAon first mention when it is natural and accurate.
Do not rewrite product names for grammar or title-case rules.
Preserve third-party product names according to the owner's spelling.
Include the company name and full model qualifier on first use when it helps identify the model.
Preserve the official capitalization and punctuation of model names.
Use shorter family names only after the full name is established.
Spell out a term on first use and put the acronym in parentheses unless the acronym is widely understood by the intended audience.
Use the acronym on later mentions after it has been defined.
For long documents, reintroduce the full term if readers might lose context.
Form plurals of acronyms withs, not an apostrophe, such asGPUs.
In headings, common acronyms can remain abbreviated. Spell out the term in the first or second sentence of the body.
Common terms such asCPU,GPU,PC,API, andUIusually do not need to be spelled out for developer audiences.
Files:
examples/switchyard/README.mdcrates/switchyard/README.md
**/*.{md,rst,html}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-brand-terminology.md)
Link the first mention of a product name when the destination helps the reader.
Files:
examples/switchyard/README.mdcrates/switchyard/README.md
**/*.{md,rst,txt}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-guide.md)
Spell
NVIDIAin all caps. Do not useNvidia,nvidia, orNV.
Files:
examples/switchyard/README.mdcrates/switchyard/README.md
**/*.{md,rst}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-guide.md)
**/*.{md,rst}: Format commands, code elements, expressions, package names, file names, and paths as inline code.
Use descriptive link text. Avoid raw URLs and weak anchors such as "here" or "read more."
Use title case consistently for technical documentation headings.
Introduce code blocks, lists, tables, and images with complete sentences.
Write procedures as imperative steps. Keep steps parallel and split long procedures into smaller tasks.
Prefer active voice, present tense, short sentences, contractions, and plain English.
Usecanfor possibility and reservemayfor permission.
Useafterfor temporal relationships instead ofonce.
Preferrefer tooverseewhen the wording points readers to another resource.
Avoid culture-specific idioms, unnecessary Latinisms, jokes, and marketing exaggeration in technical docs.
Spell out months in body text, avoid ordinal dates, and use clear time zones.
Spell out whole numbers from zero through nine unless they are technical values, parameters, versions, or UI values.
Use numerals for 10 or greater and include commas in thousands.
Do not add trademark symbols to learning-oriented docs unless the source, platform, or legal guidance explicitly requires them.
Files:
examples/switchyard/README.mdcrates/switchyard/README.md
**/*.md
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-technical-docs.md)
**/*.md: Use title case consistently in technical documentation headings
Avoid quotation marks, ampersands, and exclamation marks in headings
Keep product, event, research, and whitepaper names in their official title case
Use title case for table headers
Do not force social-media sentence case into technical docs
Format code elements, commands, parameters, package names, and expressions in monospace
Format directories, file names, and paths in monospace using backticks
Use angle brackets inside monospace for variables inside paths, such as/home/<username>/.login
Format error messages and strings in quotation marks, keeping literal code strings in code formatting when clearer
Format UI buttons, menus, fields, and labels in bold
Use angle brackets between UI labels for menu paths, such as File > Save As
Use italics for new terms on first use, sparingly and only when introducing the term
Use italics for publication titles
Format keyboard shortcuts in plain text, such as Press Ctrl+Alt+Delete
Use owner/repo link text for GitHub repositories, preferring[NVIDIA/NeMo](link)over prose references like 'the GitHub repo'
Introduce every code block with a complete sentence
Do not make a code block complete the grammar of the previous sentence
Do not continue a sentence after a code block
Use syntax highlighting when the format supports it for code blocks
Avoid the word 'snippet' unless the surrounding docs already use it as a term of art
Keep inline method, function, and class references consistent with nearby docs, omitting empty parentheses for prose readability when no call is shown
Use descriptive anchor text that matches the destination title when possible for links
Avoid raw URLs in running text
Avoid generic anchor text such as 'here,' 'this page,' and 'read more'
Include acronyms in link text when a linked term includes an acronym
Do not link long sentences or multiple sentences
Avoid links that pull readers away from a procedure unless the link is a p...
Files:
examples/switchyard/README.mdcrates/switchyard/README.md
🧠 Learnings (1)
📚 Learning: 2026-07-14T02:53:59.997Z
Learnt from: willkill07
Repo: NVIDIA/NeMo-Relay PR: 415
File: docs/configure-plugins/observability/opentelemetry.mdx:98-113
Timestamp: 2026-07-14T02:53:59.997Z
Learning: In NeMo-Relay’s OpenTelemetry/OpenInference observability projection docs under docs/configure-plugins/observability/, document the projected-attribute contract as follows: (1) emit scalar top-level `data`/`metadata` fields as typed dotted OTLP attributes (for example, `nemo_relay.start.metadata.tenant`); (2) keep nested objects/arrays as JSON strings at their top-level OTLP attribute (rather than expanding them into nested OTLP attributes); and (3) do not reference the legacy `*_json` payload attributes (e.g., `data_json`, `metadata_json`, `input_json`) because they were intentionally removed as a breaking change.
Applied to files:
docs/configure-plugins/observability/atof.mdxdocs/configure-plugins/observability/configuration.mdx
🔇 Additional comments (11)
docs/configure-plugins/observability/atof.mdx (1)
40-40: 🗄️ Data Integrity & IntegrationNamed-endpoint contract still unconfirmed against source.
This reintroduces the same open question flagged in a prior review round: the ATOF endpoint
namefield (and its consumption viaatof_endpoint_name) is documented here and expanded on in the new table rows (Lines 73-84) and Rust example (Lines 236-240), but the only available upstream struct snippet (AtofEndpointConfigincrates/core/src/observability/atof.rs:169-189) does not show anamefield. Please confirm the underlying crate (landing via companion PR#420) actually implements name-based endpoint selection before merging this doc set.Also applies to: 73-84, 236-240
docs/configure-plugins/observability/configuration.mdx (1)
76-76: 🗄️ Data Integrity & IntegrationSame named-endpoint contract concern as
atof.mdx.Duplicates the previously flagged, still-unresolved concern about whether
name/atof_endpoint_nameis actually consumed by the underlying ATOF/Switchyard config types.Also applies to: 324-328
crates/switchyard/README.md (2)
100-105: 🗄️ Data Integrity & IntegrationSame named-endpoint contract concern.
This restates the previously flagged, still-unresolved question of whether
atof_endpoint_nameis actually the field consumed bySwitchyardConfig/the ATOF exporter.
22-22: LGTM!Also applies to: 34-34, 46-46, 59-59, 73-76
docs/configure-plugins/switchyard/about.mdx (2)
41-44: 🗄️ Data Integrity & IntegrationSame named-endpoint contract concern as sibling docs.
Restates the still-open question about whether
atof_endpoint_namematches the actualSwitchyardConfigfield name in code (previously flagged against this same range).
15-22: LGTM!docs/configure-plugins/switchyard/configuration.mdx (1)
169-185: 🗄️ Data Integrity & IntegrationSame named-endpoint / field-name contract concern as sibling docs.
Restates the still-open, previously flagged question about whether
atof_endpoint_namematches the actualSwitchyardConfigfield consumed at runtime; the same field is used again at Lines 37-39, 59, 252, and 265 in this file.docs/configure-plugins/about.mdx (1)
36-38: LGTM!docs/index.yml (1)
43-45: LGTM!examples/switchyard/README.md (2)
21-30: LGTM!
86-88: Reinforces the open name-based-selector contract question.This statement that Switchyard "selects its HTTP ingestion destination by the observability endpoint name" depends on the same unresolved contract (
atof_endpoint_name/name) flagged in sibling docs — please confirm this matches the companion PR#420implementation before merge.
#### Overview Validate the ATOF delivery dependency for history-backed Switchyard profiles at Relay startup. This source change is split from #400 so the implementation and user-facing documentation can be reviewed independently. - [x] I confirm this contribution is my own work, or I have the right to submit it under this project's license. - [x] I searched existing issues and open pull requests, and this does not duplicate existing work. #### Details - Add an optional, unique `name` to observability ATOF stream sinks and expose it through the Python, Go, and Node plugin configuration helpers. - Replace the experimental Switchyard component's duplicated `atof_endpoint_url` setting with `atof_endpoint_name`. - When `context_mode = "atof_required"`, fail startup validation unless the name resolves to exactly one enabled `type = "stream"` ATOF sink that uses `http_post`, preserves canonical field names, and uses environment-referenced authentication headers. - Derive omitted sink transport and field-name policy values from core's public enum defaults while keeping `http_post` and `preserve` as explicit Switchyard requirements. - Keep `payload_only` profiles independent of ATOF delivery. - Add Rust, Python, Go, and Node coverage for stream-sink name serialization, uniqueness, context-sensitive validation, and disabled-protocol defaults. - Update all three Switchyard example plugin configurations to use observability config v2 `sinks`, including a named stream sink. - Keep the corresponding user-facing guides and README changes in #400. **Breaking change:** Experimental Switchyard configurations must replace `atof_endpoint_url` with `atof_endpoint_name`, and the corresponding observability ATOF stream sink must define the same `name`. Rust struct literals for `AtofStreamSinkSectionConfig` must initialize the new optional `name` field. #### Where should the reviewer start? 1. `crates/switchyard/src/component.rs` — context-sensitive cross-component startup validation. 2. `crates/switchyard/tests/unit/component_tests.rs` — accepted and rejected ATOF configurations. 3. `crates/core/src/observability/plugin_component.rs` — named stream-sink configuration and uniqueness validation. 4. `python/nemo_relay/observability.py`, `go/nemo_relay/observability_plugin.go`, and `crates/node/observability.d.ts` — typed plugin helpers for named stream sinks. 5. `examples/switchyard/plugins.toml` — minimal named-stream-sink configuration. #### Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to) - Relates to #400. - Relates to #369. - Relates to NVIDIA-NeMo/Switchyard#46. #### Validation - `cargo test --workspace --quiet` — full Rust workspace passed. - `uv run pytest -q python/tests --ignore=python/tests/integrations` — 528 passed. - `npm test --workspace=nemo-relay-node` — 264 passed. - `cargo build --release -p nemo-relay-ffi` followed by `go test -v ./...` with the FFI library path configured — all Go packages passed. - `cargo clippy --workspace --all-targets -- -D warnings` — passed. - `uv run pre-commit run --all-files` with the `just`-dependent protobuf hook and unchanged-lockfile attribution generators skipped — all remaining hooks passed. - `git diff --check` — passed. ## Summary by CodeRabbit - **New Features** - Added optional `name` identifiers for ATOF stream endpoint/sink configuration across exported types and schemas. - Switchyard now selects the ATOF stream endpoint by `atof_endpoint_name` (instead of URL-based selection). - **Bug Fixes** - Added validation for endpoint `name` (must be non-empty, trim-safe, and unique) and improved diagnostics for invalid values. - Strengthened “ATOF required” checks to ensure the selected named endpoint matches expected transport/policy/header requirements. - **Documentation / Examples** - Updated example configuration files to use `atof_endpoint_name` and per-sink endpoint `name`. Authors: - Bryan Bednarski (https://github.com/bbednarski9) Approvers: - Maryam Najafian (https://github.com/mnajafian-nv) - Will Killian (https://github.com/willkill07) URL: #420
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
|
/ok to test 779054b |
|
/merge |
3 participants
Overview
Document the experimental Switchyard integration, including its service boundary, Relay-owned dispatch model, target validation, fail-open behavior, and ATOF delivery requirements.
The source implementation and tests landed in #420. This documentation PR is now based on
mainafter the Switchyard publication, activation health-check, and same-protocol routing follow-ups.Details
Configure Plugins → Switchyard (Experimental)to the Fern navigation.context_mode = "atof_required"and configure the matching named observability stream sink.header_envfor ATOF stream sinks and recommend environment-referenced authentication.Where should the reviewer start?
docs/configure-plugins/switchyard/configuration.mdx— complete configuration and runtime behavior.docs/configure-plugins/switchyard/about.mdx— user-facing architecture and prerequisites.examples/switchyard/README.md— pinned compatibility workflow.Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)
Validation
fern check --warnings— zero errors; the unauthenticated redirect check was skipped with one warning.fern docs broken-links --strict— passed.git diff --check origin/main -- <changed-files>Summary by CodeRabbit