Crate aimux_ffi

Expand description

aimux-ffi: C ABI for multi-language bindings.

Provides an opaque handle registry + JSON wire format + push callback stream. The C ABI is consumed by C/C++, Go, Kotlin, Java, Swift, and Flutter. Native bindings (Python / Node) bypass this layer and use aimux-providers directly.

§Errors

Every fallible C function returns *mut aimux_error_t: NULL on success (the result is written to the out-parameter), a heap-owned error value on failure (the out-parameter is left at its sentinel: handle 0, pointer NULL). Every non-NULL error has one code from aimux_error_code and one message from aimux_error_message, and is released exactly once with aimux_error_free. Codes 1..17 come from AiMuxError, 100..105 from RecordingError, and 200..206 identify failures detected while crossing the C ABI.

§Memory ownership

Every function returning *mut c_char — error getters included — transfers ownership to the caller, who MUST free it with aimux_free_string. Handles (u64) are released with aimux_drop_handle.
aimux_stream_text callbacks receive *const c_char pointers that are valid only for the duration of the callback. The callback must copy the data synchronously; the backing buffer is freed when the callback returns.

§Concurrency

All async provider work runs on a shared multi-threaded tokio runtime. The C ABI functions are synchronous: they block_on the runtime until the operation completes. Callbacks execute on the same thread/call-stack that invoked the FFI function, so they must not re-enter the FFI layer: a nested block_on on the same thread makes tokio panic (“Cannot start a runtime from within a runtime”). Rust’s non-unwind extern "C" ABI does not allow a panic to propagate — the process terminates (and under this workspace’s release profile, panic = "abort", it terminates at the panic site). Either way the re-entrant call must be rejected before it reaches the runtime; the thread-local guard in ffi_block_on does that (issue M7).

Structs§

aimux_error_t: The owned error returned by a failed C ABI invocation. Opaque to C: read it with the aimux_error_* getters, then release it once with aimux_error_free.

Constants§

Functions§

aimux_abort_signal_abort: Request cancellation for an abort-signal handle.
aimux_abort_signal_drop: Release an abort-signal handle.
aimux_abort_signal_new: Create a per-call abort signal for a cancelable FFI operation.
aimux_anthropic_aws_new: Create an Anthropic-on-AWS model instance (API key + region).
aimux_anthropic_aws_new_with_base: Create an Anthropic-on-AWS model instance with a custom base URL.
aimux_anthropic_new: Create an Anthropic model instance. AiMuxError: invalid model id.
aimux_anthropic_new_with_base: Create an Anthropic model instance with a custom base URL.
aimux_apply_tool_call_repair: Resolve one invalid tool call against a host’s repair reply (RFC-0035).
aimux_apply_tool_call_repair_to_result: Apply a repair reply to a whole result document (RFC-0035).
aimux_azure_new: Create an Azure OpenAI model instance (API key + resource name).
aimux_azure_new_with_base: Create an Azure OpenAI model instance with a custom base URL (required, in place of resource_name).
aimux_bedrock_new: Create a Bedrock model instance (AWS SigV4 credentials).
aimux_bedrock_new_with_base: Create a Bedrock model instance with a custom base URL.
aimux_codex_refresh: Refresh a Codex subscription access token (RFC-0018 §3.2).
aimux_cohere_embedding_new
aimux_cohere_embedding_new_with_base
aimux_cohere_new: Create a Cohere model instance. AiMuxError: invalid model id.
aimux_cohere_new_with_base: Create a Cohere model instance with a custom base URL.
aimux_cohere_reranking_new: Create a Cohere reranking model instance.
aimux_cohere_reranking_new_with_base
aimux_consume_stream_text: Consume a stream to completion and write the aggregated result (M11, RFC-0016). Synchronous — blocks until the stream finishes.
aimux_drop_handle: Release a handle previously returned by aimux_*_new (any handle type — a transcription session’s driver task is aborted and joined as well, so aimux_transcription_session_drop is only a clearer name for the same thing).
aimux_embed: Generate embeddings. values_json is a JSON array of strings. Writes EmbeddingResult JSON (caller frees).
aimux_error_available_tools: AIMUX_E_NO_SUCH_TOOL: the available tool names as a JSON string array, or NULL when no tool set was supplied.
aimux_error_code: Machine-readable code (aimux_error_code_t); AIMUX_OK for NULL.
aimux_error_free: Release a returned error. NULL-safe; call exactly once.
aimux_error_message: Human-readable description for every code; NULL only for NULL.
aimux_error_model_id: AIMUX_E_NO_SUCH_MODEL: the model id that was asked for.
aimux_error_model_type: AIMUX_E_NO_SUCH_MODEL: the model type it was asked for as.
aimux_error_original_error: AIMUX_E_TOOL_CALL_REPAIR: the original lookup/parse/validation error as externally-tagged wire JSON — the same encoding as ToolCall.error.
aimux_error_provider_code: AIMUX_E_API_CALL: the provider’s own error code, e.g. “insufficient_quota”.
aimux_error_provider_data: AIMUX_E_API_CALL: parsed provider error data as a JSON string.
aimux_error_provider_id: AIMUX_E_NO_SUCH_PROVIDER: the provider id that was asked for.
aimux_error_provider_message: AIMUX_E_API_CALL: the failure’s own text (“slow down”), without the composed prefix message carries (“API call error: HTTP 429: slow down”).
aimux_error_request_body_values: AIMUX_E_API_CALL: sanitized request body values as a JSON string; NULL when the request carried none (JSON null).
aimux_error_response_body: AIMUX_E_API_CALL: raw response body.
aimux_error_response_headers: AIMUX_E_API_CALL: sanitized response headers as one JSON object string of name → value pairs, e.g. {"retry-after-ms":"1500"}.
aimux_error_retry_count: AIMUX_E_RETRY: number of recorded attempt errors; 0 under any other code or for NULL.
aimux_error_retry_error_at: AIMUX_E_RETRY: the attempt error at index (0-based, oldest first; the last entry is the final attempt) as a NEW owned error the caller reads with these same getters and releases with aimux_error_free, independently of the parent. NULL when index is out of range or under any other code.
aimux_error_retry_ms: AIMUX_E_API_CALL: retry hint in ms (0 = retry now), or -1 when none.
aimux_error_retry_reason: AIMUX_E_RETRY: why retrying stopped — the wire name of RetryErrorReason: “maxRetriesExceeded” or “errorNotRetryable”.
aimux_error_retryable: 1 when retrying may help, 0 when it will not — the core’s verdict. Do not infer it from status: a statusless AIMUX_E_API_CALL may be either.
aimux_error_status: HTTP status: the observed status under AIMUX_E_API_CALL, 401 by definition under AIMUX_E_TOKEN_EXPIRED, -1 otherwise or when no response was observed (AiMuxError::status_code).
aimux_error_tool_input: AIMUX_E_INVALID_TOOL_INPUT / AIMUX_E_NO_SUCH_TOOL: the raw argument text the model produced, or NULL when unavailable.
aimux_error_tool_name: AIMUX_E_NO_SUCH_TOOL / AIMUX_E_INVALID_TOOL_INPUT: the tool name the model called.
aimux_error_url: AIMUX_E_API_CALL: sanitized request URL.
aimux_file_upload
aimux_free_string^⚠: Free a C string previously returned by any aimux function that hands out *mut c_char — result JSON, error getters.
aimux_generate_object: Generate a structured JSON object from the model (M12, RFC-0016).
aimux_generate_text: Non-streaming generation.
aimux_generate_text_as_openai: Non-streaming text generation with OpenAI Chat Completions output.
aimux_generate_text_result_as_openai: Convert a serialized GenerateTextResult into a serialized ChatCompletion.
aimux_get_model_specs: Fetch the community model catalogue (anya2a). Writes a JSON-serialized Catalogue (provider → model_id → ModelSpec).
aimux_google_embedding_new
aimux_google_embedding_new_with_base
aimux_google_image_new
aimux_google_image_new_with_base
aimux_google_video_new: Create a Google video model instance.
aimux_google_video_new_with_base
aimux_image_generate
aimux_init_logging: Initialize the global logger. Idempotent — safe to call any number of times from any thread; only the first call has an effect.
aimux_init_proxy: Set the global proxy configuration (M6, RFC-0016). Must be called before the first aimux_generate_text / aimux_stream_text call; a no-op if the shared HTTP client is already initialised.
aimux_init_recording: Start recording (RFC-0023 P1/P2): writes complete Recording JSONL to {dir}/recordings.jsonl (dir auto-created). Recording is opt-in. Calling again with a different dir replaces the recorder.
aimux_init_recording_ring: Start in-memory bounded recording (RFC-0023 P6): RingRecorder with cap entries, FIFO eviction, dropped-count queryable. cap == 0 is AiMuxError::InvalidArgument.
aimux_init_recording_ring_default: No-argument variant of aimux_init_recording_ring: initialize the global recorder with a RingRecorder at the library default capacity (2048 entries, aimux_core::recording::RingRecorder::default). Ordinary callers should prefer this entry point and leave the ring size to the library; pass an explicit cap via aimux_init_recording_ring only when a different size is required.
aimux_list_sessions: Query: all known sessions (RFC-0024). Writes a serialized SessionView[].
aimux_mistral_new: Create a Mistral model instance. AiMuxError: invalid model id.
aimux_mistral_new_with_base: Create a Mistral model instance with a custom base URL.
aimux_moa_new: Create a MoaModel (RFC-0022) over the given reference handles + one aggregator handle. The new handle is a model handle (works with aimux_generate_text / aimux_stream_text); free it with aimux_drop_handle.
aimux_mock_replay_new: Create a mock replay model from recorded JSONL (RFC-0023 P3). recordings is one Recording JSON per line. The handle works with aimux_generate_text / aimux_stream_text (no real API is sent).
aimux_openai_embedding_new: Create an OpenAI embedding model instance.
aimux_openai_embedding_new_with_base
aimux_openai_files_new
aimux_openai_files_new_with_base
aimux_openai_image_new
aimux_openai_image_new_with_base
aimux_openai_new: Create an OpenAI model instance. AiMuxError: invalid model id.
aimux_openai_new_with_base: Create an OpenAI model instance with a custom base URL.
aimux_openai_speech_new
aimux_openai_speech_new_with_base
aimux_openai_transcription_new
aimux_openai_transcription_new_with_base
aimux_provider_from_env: Convenience: create a language model by provider name, reading the API key from the provider’s env var.
aimux_provider_handle_new: Create a provider handle (RFC-0027) for a registry-backed provider.
aimux_provider_list_models: List models on a provider handle (RFC-0027 runtime discovery).
aimux_provider_model: Build a language model from a provider handle + model_id (RFC-0027).
aimux_provider_new: Create a language model from the registry by provider name (RFC-0017 phase 4).
aimux_recording_flush: Flush the global recorder (blocks until JSONL is on disk; no-op for the ring recorder). Write failures are not reported here — see aimux_recording_try_flush.
aimux_recording_stop: Stop recording: global recorder = None (new calls are unrecorded).
aimux_recording_try_flush: Flush the global recorder and report write failures (see #136).
aimux_register_providers: Register external OpenAI-compatible providers from a JSON config string (RFC-0020). config_json is { "providers": [ { "name": ..., "base_url": ..., ... }, ... ] }. Entries override same-named built-ins or add new ones. Malformed JSON text is InvalidWireJson; a well-formed document the registry rejects is AiMuxError::InvalidArgument.
aimux_rerank: Rerank documents. opts_json is JSON-serialized RerankingCallOptions (must contain query and documents). Writes RerankingResult JSON.
aimux_router_new: Create a RouterModel (RFC-0021) over the given child-model handles. The new handle is itself a model handle (works with aimux_generate_text / aimux_stream_text); free it with aimux_drop_handle.
aimux_search: Execute a search. opts_json is JSON-serialized SearchCallOptions (must contain query). Writes SearchResult JSON.
aimux_session_calls: Query: all calls of a session, ordered by step (RFC-0024).
aimux_session_infer_init: Enable/disable the global session inferer (RFC-0024, opt-in, off by default). Explicit session_id values always win regardless. enabled nonzero = on.
aimux_session_store_init: Register the global session store (RFC-0024). Replaces any previous one. Until called, calls are not grouped and the session query functions return empty results.
aimux_speech_generate
aimux_stream_text: Streaming generation with push callbacks.
aimux_stream_text_as_openai: Streaming text generation with OpenAI Chat Completions output.
aimux_stream_text_as_openai_with_abort: Cancelable streaming OpenAI-compatible output (see aimux_stream_text_with_abort).
aimux_stream_text_with_abort: Stream text with a per-call abort signal.
aimux_tavily_search_new: Create a Tavily search model instance. model_id is accepted for API symmetry but ignored (Tavily uses a fixed endpoint).
aimux_tavily_search_new_with_base
aimux_tool_call_repair_context: Build the repair argument for one invalid tool call (RFC-0035).
aimux_trace_aggregate: Query: aggregated probe statistics, filtered by filter_json (a serialized TraceFilter; pass "{}" for all rows — NULL is NullPointer). Writes JSON TraceStats[]; caller frees with aimux_free_string.
aimux_trace_clear: Clear all probe records of a trace handle. Fails only for a dead handle.
aimux_trace_export_jsonl: Export all probe records as JSONL (one TraceRecord per line). Writes a string with embedded newlines; caller frees with aimux_free_string.
aimux_trace_new: Wrap a model handle in a probe layer (RFC-0015). The new handle can be used with aimux_generate_text / aimux_stream_text (probed) and with the aimux_trace_* query functions; release with aimux_drop_handle.
aimux_trace_new_audited: Wrap a model handle in a probe layer WITH the built-in rules auditor (RFC-0015 §4). strict nonzero = strict mode (self-hosted single instance); zero = shared mode (safe default). Release with aimux_drop_handle.
aimux_trace_session_chain: Query: one session’s chain view. Writes JSON SessionChainView; caller frees with aimux_free_string. An unknown session_id is a lookup miss on a caller-supplied value and is reported as AiMuxError::InvalidArgument (“unknown session”), not as an invalid C handle — the id is a string key, not a registry handle.
aimux_trace_session_trajectory: Query: one session’s per-step cache-hit trajectory (RFC-0024 §4.3). Writes a JSON array of SessionStepStat (empty for unknown sessions); caller frees with aimux_free_string.
aimux_transcription_generate
aimux_transcription_input_done: Signal end-of-audio (the audio stream ends; the provider flushes). Safe to call multiple times. Fails only for a dead session handle.
aimux_transcription_next_part: Pull the next transcription part (JSON-serialized TranscriptionStreamPart; free with aimux_free_string).
aimux_transcription_push_audio: Push one binary audio chunk into the session. Blocking: waits while the internal channel is full (backpressure propagation; the caller’s capture loop throttles). Must not be called from within an aimux callback (re-entrancy guard rejects it).
aimux_transcription_session_drop: Terminate a transcription session and release it: aborts the driver, joins (bounded), and drops the handle. Safe with 0 or an unknown handle.
aimux_transcription_session_new: Start a transcription streaming session (RFC-0028 Phase 2). Internally spawns the driver task immediately; audio is then pushed with aimux_transcription_push_audio and parts pulled with aimux_transcription_next_part.
aimux_vertex_new: Create a Vertex AI model instance (GCP bearer token).
aimux_vertex_new_with_base: Create a Vertex AI model instance with a custom base URL.
aimux_video_generate: Generate video. opts_json is JSON-serialized VideoCallOptions (must contain prompt). Writes VideoResult JSON.
aimux_xai_new: Create an xAI model instance. AiMuxError: invalid model id.
aimux_xai_new_with_base: Create an xAI model instance with a custom base URL.

Crate aimux_ffi

Crate aimux_ffi Copy item path

§Errors

§Memory ownership

§Concurrency

Structs§

Constants§

Functions§

Crate aimux_ffi