nemo_flow_ffi/lib.rs
1// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! C FFI layer for NeMo Flow.
5//!
6//! This crate exposes the NeMo Flow core runtime as a C-compatible shared library.
7//! It is consumed by the Go bindings via CGo and regenerates the committed
8//! `nemo_flow.h` header through `cbindgen` during Cargo builds. All exported
9//! symbols use the `nemo_flow_` prefix.
10//!
11//! # Middleware Pipeline
12//!
13//! When a tool or LLM call is executed end-to-end via the `_execute` functions,
14//! the runtime applies the following middleware pipeline in order:
15//!
16//! 1. **Request intercepts** -- transform the request before guardrails.
17//! 2. **Sanitize-request guardrails** -- validate/sanitize the request.
18//! 3. **Conditional-execution guardrails** -- gate whether the call proceeds.
19//! 4. **Execution intercepts** -- optionally replace the call implementation.
20//! 5. **Sanitize-response guardrails** -- validate/sanitize the response.
21//!
22//! # Error Handling
23//!
24//! Every `extern "C"` function returns an [`error::NemoFlowStatus`] code. On
25//! failure, call [`error::nemo_flow_last_error`] on the same thread to retrieve
26//! a human-readable error description. The error is stored in thread-local
27//! storage and is valid until the next FFI call on that thread.
28//!
29//! # Memory Ownership
30//!
31//! All opaque handles (`FfiScopeHandle`, `FfiToolHandle`, `FfiLLMHandle`, etc.)
32//! are heap-allocated and must be freed through their corresponding
33//! `nemo_flow_*_free` functions. C strings returned by accessor functions must
34//! be freed with `nemo_flow_string_free`.
35//!
36//! # Modules
37//!
38//! - [`api`] -- Top-level FFI entry points (scope, tool, LLM, guardrail, intercept,
39//! subscriber, ATIF exporter). Tool calls accept an optional `tool_call_id` and
40//! LLM calls accept an optional `model_name` for ATIF trajectory correlation.
41//! ATIF exporter functions (`nemo_flow_atif_exporter_*`) create, register,
42//! export, and clear trajectory data.
43//! - [`types`] -- C-compatible struct and enum definitions, plus event accessor
44//! functions (`nemo_flow_event_input`, `_output`, `_model_name`, `_tool_call_id`,
45//! `_parent_uuid`, `_scope_type`) and the `FfiAtifExporter`
46//! opaque handle.
47//! - [`error`] -- Status codes and thread-local error storage.
48//! - [`callable`] -- C function pointer typedefs and wrapper functions.
49//! - [`convert`] -- JSON and C-string conversion utilities.
50pub mod api;
51pub mod callable;
52pub mod convert;
53pub mod error;
54pub mod types;