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