> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/relay/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/relay/_mcp/server.

# Module callable

> C function pointer typedefs and wrapper functions for FFI callbacks.

Generated from `cargo doc --no-deps -p nemo-relay -p nemo-relay-adaptive -p nemo-relay-pii-redaction -p nemo-relay-ffi -p nemo-relay-types -p nemo-relay-plugin -p nemo-relay-worker-proto -p nemo-relay-worker`.

C function pointer typedefs and wrapper functions for FFI callbacks.

This module defines the callback signatures used by the C API for tool and LLM guardrails, intercepts, execution functions, and event subscribers. Each `pub type` alias corresponds to a C function pointer that appears in the generated `nemo_relay.h` header.

The `wrap_*` functions convert C callbacks (with opaque `user_data` pointers) into Rust closures that the core runtime can invoke. Registry-stored callbacks return `Arc`-backed closures, while one-shot or mutable callback shapes remain boxed. Each wrapper captures the user data and its optional free function in an `Arc<UserData>` so the closure is `Send + Sync` and the free function is called exactly once when all references are dropped.

## Structs

* [NemoRelayLlmSanitizeRequestContext](/reference/api/rust-library-reference/nemo-relay-ffi/callable/struct-nemorelayllmsanitizerequestcontext): Codec identity supplied to an LLM sanitizer. `codec_id` is null for `None` and `Opaque`, and is valid only for the duration of the callback.
* [NemoRelayLlmSanitizeResponseContext](/reference/api/rust-library-reference/nemo-relay-ffi/callable/struct-nemorelayllmsanitizeresponsecontext): Directional codec context supplied to an LLM response sanitizer.

## Enums

* [NemoRelayLlmSanitizeCodecKind](/reference/api/rust-library-reference/nemo-relay-ffi/callable/enum-nemorelayllmsanitizecodeckind): Codec identity kind supplied to an LLM sanitizer.

## Functions

* [wrap\_codec\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-codec-fn): Wrap a pair of C codec callbacks into an `Arc<dyn LlmCodec>`.
* [wrap\_collector\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-collector-fn): Wrap a C collector callback into a `Box<dyn FnMut(Json) -> Result<()> + Send>` for use by the core runtime. Each intercepted chunk Json is serialized to a JSON string and passed to the callback.
* [wrap\_event\_sanitize\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-event-sanitize-fn): Wrap a C event sanitizer callback into a Rust closure.
* [wrap\_event\_subscriber](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-event-subscriber): Wrap a C event subscriber callback into a Rust closure.
* [wrap\_finalizer\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-finalizer-fn): Wrap a C finalizer callback into a `Box<dyn FnOnce() -> Json + Send>` for use by the core runtime. The callback is invoked exactly once when the stream is exhausted. The returned C string is parsed as JSON and then freed.
* [wrap\_llm\_conditional\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-llm-conditional-fn): Wrap a C LLM conditional callback into a Rust closure.
* [wrap\_llm\_exec\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-llm-exec-fn): Wrap a C LLM execution callback into an async Rust closure. The C callback receives an `LlmRequest` serialized as a JSON string.
* [wrap\_llm\_exec\_intercept\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-llm-exec-intercept-fn): Wrap a C LLM execution intercept callback into an `Arc<dyn Fn(LlmRequest, LlmExecutionNextFn) -> ...>`.
* [wrap\_llm\_request\_intercept\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-llm-request-intercept-fn): Wrap a C LLM request intercept callback (annotated-aware) into a Rust `LlmRequestInterceptFn` closure. The callback receives the intercept name, the opaque `FfiLLMRequest`, and the annotated JSON (or null). It writes one owned canonical outcome JSON string.
* [wrap\_llm\_sanitize\_request\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-llm-sanitize-request-fn): Wrap a C LLM request sanitizer into a Rust closure.
* [wrap\_llm\_sanitize\_response\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-llm-sanitize-response-fn): Wrap a C LLM response sanitizer into a Rust closure.
* [wrap\_llm\_stream\_exec\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-llm-stream-exec-fn): Wrap a C LLM execution callback into an async Rust closure that returns a stream. The C callback returns the full response as a single JSON string, which is emitted as a single-item stream of Json values.
* [wrap\_llm\_stream\_exec\_intercept\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-llm-stream-exec-intercept-fn): Wrap a C LLM stream execution intercept callback. Since the C callback returns a single string (not a real stream), this wraps it as a single-item stream, same as `wrap_llm_stream_exec_fn`.
* [wrap\_tool\_conditional\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-tool-conditional-fn): Wrap a C tool conditional callback into a Rust closure for use by the core runtime.
* [wrap\_tool\_exec\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-tool-exec-fn): Wrap a C tool execution callback into an async Rust closure.
* [wrap\_tool\_exec\_intercept\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-tool-exec-intercept-fn): Wrap a C tool execution intercept callback into a [`ToolExecutionFn`](/reference/api/rust-library-reference/nemo-relay/api/runtime/callbacks/type-toolexecutionfn).
* [wrap\_tool\_request\_intercept\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-tool-request-intercept-fn): Wrap a C tool request intercept callback into a Rust closure for use by the core runtime.
* [wrap\_tool\_sanitize\_fn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/fn-wrap-tool-sanitize-fn): Wrap a C tool sanitize callback into a Rust closure for use by the core runtime.

## Type Aliases

* [NemoRelayCodecDecodeCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaycodecdecodecb): Callback for Codec decode: translates an opaque `FfiLLMRequest` into an `AnnotatedLLMRequest` JSON string. Returns a heap-allocated C string on success, or null on error (after setting the last error message).
* [NemoRelayCodecDecodeFn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaycodecdecodefn): Nullable version of [`NemoRelayCodecDecodeCb`](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaycodecdecodecb) for use as an optional parameter in FFI execute functions. Pass null to indicate no codec.
* [NemoRelayCodecEncodeCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaycodecencodecb): Callback for Codec encode: merges structured changes back into opaque request content. Receives the annotated request as a JSON C string and the original `FfiLLMRequest`. Returns a heap-allocated JSON C string representing the new `LlmRequest` content on success, or null on error.
* [NemoRelayCodecEncodeFn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaycodecencodefn): Nullable version of [`NemoRelayCodecEncodeCb`](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaycodecencodecb) for use as an optional parameter in FFI execute functions. Pass null to indicate no codec.
* [NemoRelayCollectorCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaycollectorcb): Callback for collecting intercepted stream chunks. Invoked with each chunk (after stream execution intercepts have been applied) as a null-terminated C string. The string is only valid for the duration of the call.
* [NemoRelayEventSanitizeCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelayeventsanitizecb): Callback for mark and scope event sanitizers. The returned JSON string transfers to Relay and is freed exactly once.
* [NemoRelayEventSubscriberCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelayeventsubscribercb): Callback for event subscribers. Invoked on each lifecycle event emitted by the runtime. The `FfiEvent` pointer is only valid for the duration of the call.
* [NemoRelayFinalizerCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelayfinalizercb): Callback for finalizing a collected stream. Invoked once when the stream is exhausted. Must return a JSON C string representing the aggregated response. The returned string must be allocated with `malloc` or equivalent; the runtime will free it.
* [NemoRelayFreeFn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelayfreefn): Optional destructor for user data passed to callbacks. Called when the runtime no longer needs the associated callback.
* [NemoRelayLlmConditionalCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelayllmconditionalcb): Callback for LLM conditional execution guardrails. Returns NULL to allow execution, or an error message string to reject.
* [NemoRelayLlmExecCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelayllmexeccb): Callback for LLM execution (default callable). Receives a native JSON C string, returns the response as a JSON C string.
* [NemoRelayLlmExecInterceptCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelayllmexecinterceptcb): Callback for LLM execution intercepts with middleware chain support. Receives native JSON C string plus a `next` callback and its context.
* [NemoRelayLlmExecNextFn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelayllmexecnextfn): Runtime-provided "next" callback for LLM execution middleware chain. Takes a native JSON C string, returns a response JSON C string. `next_ctx` is borrowed and valid only until the intercept callback returns; callers must not retain it or invoke `next_fn` asynchronously. The returned string belongs to the caller and must be released with `nemo_relay_string_free`.
* [NemoRelayLlmRequestInterceptCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelayllmrequestinterceptcb): C callback type for LLM request intercepts with unified annotated-aware signature. Receives the intercept name, the opaque `FfiLLMRequest`, and optionally the annotated request as a JSON C string (null if no Codec resolved). Writes one owned canonical outcome JSON string to `out_outcome_json`. Any non-null string written there must be allocated by `nemo_relay_llm_request_intercept_outcome_json_new` or by an allocation compatible with `nemo_relay_string_free`. Ownership transfers to Relay when the callback returns; the callback must not free or reuse the string afterward. Relay frees it exactly once, even when the callback returns an error status. With a Codec, the outcome must preserve request content and return the annotation; only request headers and annotation fields are writable. Returns `NemoRelayStatus`.
* [NemoRelayLlmSanitizeRequestCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelayllmsanitizerequestcb): LLM request sanitizer. It receives the request first and its codec context second. Return null to omit the observability payload. The request is borrowed, but returning that same pointer is supported as a pass-through. Any other non-null result transfers ownership to Relay.
* [NemoRelayLlmSanitizeResponseCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelayllmsanitizeresponsecb): LLM response sanitizer. It receives response JSON first and its codec context second. Return null to omit the observability payload. The response is borrowed, but returning that same pointer is supported as a pass-through. Any other non-null result transfers ownership to Relay.
* [NemoRelayPluginRegisterCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaypluginregistercb): Callback for plugin registration. Receives plugin config JSON and a plugin context pointer that is only valid for the duration of the call.
* [NemoRelayPluginValidateCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaypluginvalidatecb): Callback for plugin validation. Receives plugin config JSON and returns a JSON array of diagnostics.
* [NemoRelayToolConditionalCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaytoolconditionalcb): Callback for tool conditional execution guardrails. Receives tool name and arguments as JSON. Returns NULL to allow execution, or an error message string to reject.
* [NemoRelayToolExecCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaytoolexeccb): Callback for tool execution (default callable). Receives arguments as JSON, returns result as JSON. The returned string must be allocated with `malloc` or equivalent.
* [NemoRelayToolExecInterceptCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaytoolexecinterceptcb): Callback for tool execution intercepts. Receives arguments as JSON plus a `next` callback and its context. Call `next_fn(args, next_ctx)` to invoke the next layer in the middleware chain, or return directly to short-circuit. The `result` field is passed to the remaining middleware and application; `pending_marks` are Relay-owned lifecycle metadata emitted after the tool-end event and are not included in the application-visible result. The returned JSON must contain a `result` field and may contain a `pending_marks` array. The returned string must be allocated with `malloc` or an equivalent allocation compatible with `nemo_relay_string_free`. Ownership transfers to Relay when the callback returns; the callback must not free or reuse the string afterward, and Relay frees it exactly once.
* [NemoRelayToolExecNextFn](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaytoolexecnextfn): Runtime-provided "next" callback for tool execution middleware chain. Call this from an intercept to invoke the next layer (or original function). `next_ctx` is borrowed and valid only until the intercept callback returns; callers must not retain it or invoke `next_fn` asynchronously. The returned string belongs to the caller and must be released with `nemo_relay_string_free`.
* [NemoRelayToolSanitizeCb](/reference/api/rust-library-reference/nemo-relay-ffi/callable/type-nemorelaytoolsanitizecb): Callback for tool request/response sanitization guardrails and intercepts. Receives tool name and arguments as JSON, returns sanitized arguments as JSON. The returned string must be allocated with `malloc` or equivalent.