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//! - [`logging`] — Process operational logging (`log` facade + configurable stderr/file sinks).
38//! - [`observability`] — Built-in observability backends including
39//! [`atif::AtifExporter`](observability::atif::AtifExporter),
40//! [`otel::OpenTelemetrySubscriber`](observability::otel::OpenTelemetrySubscriber),
41//! with full, GenAI, or OpenInference projection.
42//! - [`stream`] — [`stream::LlmStreamWrapper`] — a stream adapter that applies per-chunk
43//! intercepts and aggregates streaming LLM responses.
44//!
45//! ## Middleware Pipeline
46//!
47//! Both tool and LLM calls flow through a configurable middleware pipeline:
48//!
49//! 1. **Request intercepts** — transform the request before execution
50//! 2. **Sanitize request guardrails** — sanitize/normalize the request
51//! 3. **Conditional execution guardrails** — gate execution (reject if criteria not met)
52//! 4. **Execution intercepts** — optionally replace the execution function entirely
53//! 5. **Sanitize response guardrails** — sanitize/normalize the response
54//!
55//! All middleware is priority-ordered (ascending) and registered by name for
56//! easy addition and removal at runtime.
57pub mod api;
58pub mod codec;
59pub mod config_editor;
60mod context;
61pub mod error;
62pub mod json;
63pub mod logging;
64pub mod observability;
65pub mod plugin;
66pub mod plugins;
67mod registry;
68#[doc(hidden)]
69pub mod shared_runtime;
70pub mod stream;
71
72#[cfg(test)]
73#[path = "../tests/unit/types_tests.rs"]
74mod types_tests;