docs: document LLM request and tool execution outcomes - #341
Merged
rapids-bot[bot] merged 4 commits intoJul 2, 2026
Conversation
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Enterprise Run ID: 📒 Files selected for processing (3)
💤 Files with no reviewable changes (3)
📜 Recent review details⏰ Context from checks skipped due to timeout. (1)
WalkthroughDocumentation standardizes LLM request-intercept and tool-execution intercept outcome contracts, updates code examples to use outcome objects, and adds reference pages for serialization, lifecycle, binding, and migration rules. ChangesIntercept Outcome Documentation
Estimated code review effort: 2 (Simple) | ~12 minutes Suggested labels: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
2 tasks
rapids-bot Bot
pushed a commit
that referenced
this pull request
Jul 1, 2026
#### Overview
Finalize one canonical LLM request-intercept outcome across the Rust runtime, built-in and adaptive plugins, native ABI v1, `grpc-v1` workers, public C FFI, Go, Python, Node.js, and WebAssembly.
Request intercepts can rewrite the provider request, carry an optional normalized annotation, and schedule ordered marks for the managed LLM lifecycle:
```json
{
"request": {"headers": {}, "content": {}},
"annotated_request": null,
"pending_marks": []
}
```
`request` is required. `annotated_request` defaults to `null`, and `pending_marks` defaults to an empty list. Each pending mark contains only its name, optional category and category profile, data, and metadata; Relay continues to own event UUIDs, parent UUIDs, and timestamps.
The finalized contract also defines one provider-body source of truth. Without a request codec, `outcome.request.content` is authoritative. With a codec, `outcome.annotated_request` is required and authoritative, `outcome.request.content` is read-only context, and `outcome.request.headers` remains writable.
- [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.
#### Why
Request intercepts run before Relay creates the managed LLM handle. A mark emitted directly from an intercept therefore cannot reliably attach to that future LLM scope. Returning pending mark specifications lets the lifecycle owner emit them at the correct boundary without leaking control data into provider requests, annotations, codecs, sanitizers, or execution intercepts.
Codec-aware interception also previously allowed two conflicting provider-body representations: an intercept could change both the raw request content and its normalized annotation, while Relay later encoded only the annotation. Making authority explicit prevents raw content edits from being silently discarded.
#### Details
- Make `LlmRequestInterceptOutcome` the only Rust callback result and keep one `register_llm_request_intercept` registration family for global, scope-local, plugin-context, and adaptive paths.
- Propagate each accepted request and annotation to the next intercept while appending pending marks in effective middleware order.
- Without a request codec, use `outcome.request.content` as the provider body.
- With a request codec, require `outcome.annotated_request`, encode the provider body from it, and allow header changes only through `outcome.request.headers`.
- Reject raw `request.content` mutations or missing annotations at the offending codec-path intercept, before later middleware, LLM lifecycle creation, mark emission, or provider invocation.
- Preserve marks from an intercept that breaks the chain; discard all accumulated marks if any intercept fails.
- Return the complete outcome from standalone request-intercept helpers. These helpers expose pending marks but do not emit them because they do not own an LLM lifecycle.
- After successful interception, create the LLM handle and capture one subscriber snapshot before emitting lifecycle events.
- Emit LLM start at `T`, every pending mark at `T + 1µs` in returned order with the LLM UUID as parent, and LLM end at or after `T + 1µs`.
- Apply the same behavior to streaming and non-streaming managed execution, including provider errors and stream finalization.
- Keep pending marks separate from provider-visible requests and annotations.
#### Boundary contracts
- **Native ABI v1:** return one host-owned outcome JSON string. Remove the private annotation-envelope transport and append required outcome-contract version fields to both host and plugin descriptor tables so stale binaries fail before callback invocation.
- **`grpc-v1`:** return one `JsonEnvelope` using schema `nemo.relay.LlmRequestInterceptOutcome@1`.
- **Public C FFI:** return one owned `char **out_outcome_json` and add `nemo_relay_llm_request_intercept_outcome_json_new`.
- **Go:** return `(LLMRequestInterceptOutcome, error)` and expose request, outcome, and pending-mark DTOs.
- **Python:** return `LLMRequestInterceptOutcome` and export `PendingMarkSpec`.
- **Node.js and WebAssembly:** return `{ request, annotated?, pendingMarks? }`. Binding-owned pending-mark DTOs use `categoryProfile`; canonical event and outcome JSON retains `category_profile`.
- **Rust native and worker SDKs:** expose only the canonical callback and registration method.
#### Breaking changes
This intentionally finalizes unpublished contracts in place:
- Rust and Python tuple results are removed.
- C and Go split outputs are removed.
- Mark-specific parallel registration variants are removed.
- The native annotation metadata envelope and fallback parser are removed.
- Native ABI host and plugin tables require the finalized outcome-contract field.
- The `grpc-v1` request-intercept result is replaced by the canonical outcome envelope.
- Codec-path intercepts must return an annotation and may no longer mutate raw `request.content`; malformed outcomes fail before lifecycle creation.
- Node.js and WebAssembly pending-mark objects use `categoryProfile` instead of the Rust/wire name `category_profile`.
All development native plugins and workers must rebuild against this version.
#### Where should the reviewer start?
1. `crates/types/src/api/event.rs` and `crates/types/src/api/llm.rs` for the canonical data contract.
2. `crates/core/src/api/runtime/state.rs`, `crates/core/src/api/shared.rs`, `crates/core/src/api/llm.rs`, and `crates/core/src/stream.rs` for chaining, codec authority, validation, and lifecycle behavior.
3. `crates/plugin/src/lib.rs`, `crates/core/src/plugin/dynamic/native.rs`, and `crates/core/src/plugin/dynamic/worker.rs` for native and worker boundaries.
4. `crates/ffi`, `go/nemo_relay`, `crates/python`, `crates/node`, and `crates/wasm` for binding contracts and DTO conversion.
5. `crates/core/tests/integration/middleware_tests.rs`, `crates/core/tests/integration/pipeline_tests.rs`, `crates/plugin/tests/typed_callbacks.rs`, and the binding tests for lifecycle, codec-authority, and boundary coverage.
The full contract, request-authority diagram, and migration notes are tracked in [companion documentation PR #341](#341), which should merge immediately after this PR.
#### Testing
- `cargo test --workspace --all-targets`
- `cargo clippy --workspace --all-targets -- -D warnings`
- `cargo fmt --all -- --check`
- Python codec and worker SDK coverage passes, including malformed codec-path outcomes and canonical worker envelopes.
- Node.js LLM suite: **38 passed**, including `categoryProfile` input/output conversion and codec-authority rejection.
- Go: all `go/nemo_relay/...` packages passed, including codec-authority coverage; `go vet ./...` passes.
- Native SDK: **52 passed**.
- Worker SDK: **9 passed**; worker protocol tests: **6 passed**.
- C FFI: unit and integration suites passed, including owned outcome allocation and malformed/null input coverage.
- WebAssembly native Rust tests: **13 passed**, including camelCase pending-mark DTO round trips and rejection of the wire-only `category_profile` spelling.
- Repository formatting, strict Clippy, Ruff, Prettier, type, lockfile, FFI-header, and applicable pre-commit checks pass.
`wasm-pack` and the `wasm32-unknown-unknown` Rust target were not available for the package-level Wasm suite. Environment-dependent socket and external-network tests were not used to validate these binding changes.
#### Related Issues
- Relates to #296
## Summary by CodeRabbit
* **New Features**
* LLM request intercepts can now return a unified outcome that includes the rewritten request, optional annotated request, and pending marks.
* Pending marks are now emitted alongside LLM lifecycle events and supported across SDKs and plugins.
* **Bug Fixes**
* Improved consistency of LLM event timing and parent/child relationships.
* Added stricter validation so intercepts that modify raw request content or omit required annotations are rejected when needed.
Authors:
- Bryan Bednarski (https://github.com/bbednarski9)
Approvers:
- Will Killian (https://github.com/willkill07)
URL: #327
bbednarski9
marked this pull request as ready for review
July 1, 2026 17:59
lvojtku
reviewed
Jul 1, 2026
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
Contributor
Author
rapids-bot Bot
pushed a commit
that referenced
this pull request
Jul 2, 2026
…350) ## Summary - make `ToolExecutionInterceptOutcome` the canonical return type for every registered tool execution intercept - keep the default tool callable and `next(args)` continuation as raw JSON while Relay retains downstream pending marks - use the existing global, scope-local, and plugin registration paths without a mark-specific registration API - emit ordered pending marks after the managed tool end event, parented to the Relay-owned tool UUID - carry the same contract through native plugins, `grpc-v1` workers, C, Go, Python, and Node ## Motivation Tool execution intercepts only learn the final result after execution, while Relay owns the managed tool lifecycle and its UUID. Returning a canonical outcome keeps plugin control data separate from the application-visible tool result and lets Relay materialize marks with correct parentage. This follows the outcome-return convention already used by LLM request intercepts instead of introducing a second registration family or an implementation-specific callback variant. ## Behavior - applications and sanitize-response guardrails receive only `outcome.result` - successful calls emit the tool end event first, followed by pending marks in effective middleware order - marks retain category, category profile, data, and metadata - repeated concurrent `next(...)` calls preserve invocation order rather than completion order - execution errors discard accumulated marks - the subscriber snapshot taken at tool start is reused for the end event and pending marks - legacy raw intercept results are rejected at public and dynamic-plugin boundaries ## Boundary contracts - Rust and native plugins return `ToolExecutionInterceptOutcome` - `grpc-v1` workers return a `ToolExecutionInterceptResult` containing the exact `nemo.relay.ToolExecutionInterceptOutcome@1` envelope - C callbacks return JSON with `result` and optional `pending_marks` - Go callbacks return `ToolExecutionInterceptOutcome` - Python callbacks return `ToolExecutionInterceptOutcome` - Node callbacks return `{ result, pendingMarks? }` ## Breaking changes - every registered tool execution intercept must return the canonical outcome type - the raw default tool callable and raw `next(args)` result are unchanged - existing registration names are unchanged; there is no parallel outcome-specific registration path - native plugins, workers, and language bindings must rebuild against current `main` ## Validation - `cargo test --workspace --all-targets -- --test-threads=1` - `cargo check --workspace --all-targets` - `cargo clippy --workspace --all-targets -- -D warnings` - `cargo fmt --all -- --check` - native plugin SDK: 53 tests passed - worker SDK: 11 tests passed - Node: 246 tests passed - Python: 496 tests passed, 39 optional-integration tests skipped - Go: `go test ./...` and `go vet ./...` - Ruff checks and formatting - `git diff --check` ## Documentation No documentation changes are included. Follow-up documentation remains in #341. ## Summary by CodeRabbit * **New Features** * Tool execution intercepts now return a typed, structured outcome containing `result` plus optional `pendingMarks`, with consistent support across Rust, Node, Python, Go, and the worker SDK. * Pending marks are emitted and associated deterministically with the correct tool execution lifecycle events. * **Bug Fixes** * Improved propagation/merging of downstream pending marks for pass-through, chaining, and global+scope-local flows. * Rejections for legacy, malformed, or nonconforming outcomes are clearer; event ordering/parent-child relationships are corrected. * **Documentation** * Updated API docs and type definitions to reflect the new outcome contract and `pendingMarks` timing semantics. * **Tests** * Expanded and adjusted coverage for the new typed outcome and mark-emission behavior. Authors: - Bryan Bednarski (https://github.com/bbednarski9) - Will Killian (https://github.com/willkill07) Approvers: - Will Killian (https://github.com/willkill07) URL: #350
lvojtku
approved these changes
Jul 2, 2026
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
lvojtku
approved these changes
Jul 2, 2026
willkill07
approved these changes
Jul 2, 2026
Contributor
Author
|
/merge |
This was referenced Jul 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
Document the canonical LLM request-intercept and tool-execution intercept outcome contracts.
Details
next(args)behavior, pending marks, end-before-mark lifecycle ordering, migration, and binding contracts.Where should the reviewer start?
docs/reference/llm-request-intercept-outcomes.mdxdocs/reference/tool-execution-intercept-outcomes.mdxdocs/instrument-applications/advanced-guide.mdxRelated Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)
Validation
git diff --checkSummary by CodeRabbit