nemo_flow/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 Flow Core
7//!
8//! The core runtime library for the NeMo Flow 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::NemoFlowContextState`]) 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//! - [`registry`] — [`SortedRegistry`](registry::SortedRegistry) — a priority-sorted, named collection used for
42//! all guardrail and intercept registries.
43//! - [`stream`] — [`stream::LlmStreamWrapper`] — a stream adapter that applies per-chunk
44//! intercepts and aggregates streaming LLM responses.
45//!
46//! ## Middleware Pipeline
47//!
48//! Both tool and LLM calls flow through a configurable middleware pipeline:
49//!
50//! 1. **Request intercepts** — transform the request before execution
51//! 2. **Sanitize request guardrails** — sanitize/normalize the request
52//! 3. **Conditional execution guardrails** — gate execution (reject if criteria not met)
53//! 4. **Execution intercepts** — optionally replace the execution function entirely
54//! 5. **Sanitize response guardrails** — sanitize/normalize the response
55//!
56//! All middleware is priority-ordered (ascending) and registered by name for
57//! easy addition and removal at runtime.
58pub mod api;
59pub mod codec;
60pub mod config_editor;
61mod context;
62pub mod error;
63pub mod json;
64pub mod observability;
65pub mod plugin;
66pub mod registry;
67#[doc(hidden)]
68pub mod shared_runtime;
69pub mod stream;
70
71#[cfg(test)]
72#[path = "../tests/unit/types_tests.rs"]
73mod types_tests;