nemo_relay/lib.rs
1// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4#![deny(rustdoc::broken_intra_doc_links, rustdoc::private_intra_doc_links)]
5
6//! # NeMo Relay Core
7//!
8//! The core runtime library for the NeMo Relay multi-language agent framework. This crate
9//! provides execution scope management, lifecycle event tracking, and middleware pipelines
10//! (guardrails and intercepts) for tool and LLM calls.
11//!
12//! ## Architecture
13//!
14//! The runtime is organized around a **global context**
15//! ([`api::runtime::NemoRelayContextState`]) that holds all registered middleware
16//! (guardrails, intercepts, subscribers) and a **scope stack**
17//! ([`api::runtime::ScopeStack`]) that tracks the hierarchical execution context
18//! via task-local or thread-local storage.
19//!
20//! ## Primary Entry Points
21//!
22//! Most integrations start with the high-level lifecycle helpers in [`api`]:
23//!
24//! - [`api::scope::push_scope`] / [`api::scope::pop_scope`] create nested execution scopes.
25//! - [`api::tool::tool_call_execute`] runs a complete tool middleware pipeline.
26//! - [`api::llm::llm_call_execute`] and [`api::llm::llm_stream_call_execute`] run non-streaming
27//! and streaming LLM middleware pipelines.
28//! - [`api::registry`] exposes global and scope-local middleware registration APIs.
29//! - [`api::subscriber`] exposes lifecycle event subscriber registration APIs.
30//!
31//! ### Modules
32//!
33//! - [`api`] — Public API functions, handles, lifecycle event types, runtime helpers,
34//! and guardrail/intercept/subscriber registration. These are the primary entry points.
35//! - [`error`] — Error types ([`error::FlowError`]) and the [`error::Result`] type alias.
36//! - [`json`] — JSON type alias ([`json::Json`]) and the [`json::merge_json`] utility.
37//! - [`observability`] — Built-in observability backends including
38//! [`atif::AtifExporter`](observability::atif::AtifExporter),
39//! [`otel::OpenTelemetrySubscriber`](observability::otel::OpenTelemetrySubscriber),
40//! and [`openinference::OpenInferenceSubscriber`](observability::openinference::OpenInferenceSubscriber).
41//! - [`stream`] — [`stream::LlmStreamWrapper`] — a stream adapter that applies per-chunk
42//! intercepts and aggregates streaming LLM responses.
43//!
44//! ## Middleware Pipeline
45//!
46//! Both tool and LLM calls flow through a configurable middleware pipeline:
47//!
48//! 1. **Request intercepts** — transform the request before execution
49//! 2. **Sanitize request guardrails** — sanitize/normalize the request
50//! 3. **Conditional execution guardrails** — gate execution (reject if criteria not met)
51//! 4. **Execution intercepts** — optionally replace the execution function entirely
52//! 5. **Sanitize response guardrails** — sanitize/normalize the response
53//!
54//! All middleware is priority-ordered (ascending) and registered by name for
55//! easy addition and removal at runtime.
56pub mod api;
57pub mod codec;
58pub mod config_editor;
59mod context;
60pub mod error;
61pub mod json;
62pub mod observability;
63pub mod plugin;
64pub mod plugins;
65mod registry;
66#[doc(hidden)]
67pub mod shared_runtime;
68pub mod stream;
69
70#[cfg(test)]
71#[path = "../tests/unit/types_tests.rs"]
72mod types_tests;