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
// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
//! C FFI layer for NeMo Flow.
//!
//! This crate exposes the NeMo Flow core runtime as a C-compatible shared library.
//! It is consumed by the Go bindings via CGo and regenerates the committed
//! `nemo_flow.h` header through `cbindgen` during Cargo builds. All exported
//! symbols use the `nemo_flow_` prefix.
//!
//! # Middleware Pipeline
//!
//! When a tool or LLM call is executed end-to-end via the `_execute` functions,
//! the runtime applies the following middleware pipeline in order:
//!
//! 1. **Request intercepts** -- transform the request before guardrails.
//! 2. **Sanitize-request guardrails** -- validate/sanitize the request.
//! 3. **Conditional-execution guardrails** -- gate whether the call proceeds.
//! 4. **Execution intercepts** -- optionally replace the call implementation.
//! 5. **Sanitize-response guardrails** -- validate/sanitize the response.
//!
//! # Error Handling
//!
//! Every `extern "C"` function returns an [`error::NemoFlowStatus`] code. On
//! failure, call [`error::nemo_flow_last_error`] on the same thread to retrieve
//! a human-readable error description. The error is stored in thread-local
//! storage and is valid until the next FFI call on that thread.
//!
//! # Memory Ownership
//!
//! All opaque handles (`FfiScopeHandle`, `FfiToolHandle`, `FfiLLMHandle`, etc.)
//! are heap-allocated and must be freed through their corresponding
//! `nemo_flow_*_free` functions. C strings returned by accessor functions must
//! be freed with `nemo_flow_string_free`.
//!
//! # Modules
//!
//! - [`api`] -- Top-level FFI entry points (scope, tool, LLM, guardrail, intercept,
//! subscriber, ATIF exporter). Tool calls accept an optional `tool_call_id` and
//! LLM calls accept an optional `model_name` for ATIF trajectory correlation.
//! ATIF exporter functions (`nemo_flow_atif_exporter_*`) create, register,
//! export, and clear trajectory data.
//! - [`types`] -- C-compatible struct and enum definitions, plus event accessor
//! functions (`nemo_flow_event_input`, `_output`, `_model_name`, `_tool_call_id`,
//! `_parent_uuid`, `_scope_type`) and the `FfiAtifExporter`
//! opaque handle.
//! - [`error`] -- Status codes and thread-local error storage.
//! - [`callable`] -- C function pointer typedefs and wrapper functions.
//! - [`convert`] -- JSON and C-string conversion utilities.