entropic.h File Reference

Public C API for the Entropic inference engine. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <entropic/entropic_config.h>
#include <entropic/entropic_export.h>
#include <entropic/types/error.h>
#include <entropic/types/hooks.h>

Include dependency graph for entropic.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	ent_delegation_request_t
	Request describing a delegation that is about to run. More...
struct	ent_delegation_result_t
	Result of a finalized delegation, delivered to the consumer. More...
struct	entropic_logprob_result
	Per-token log-probability result. More...

Typedefs
typedef void(*	entropic_residency_observer_t) (entropic_residency_event_t event, const char *tier_name, const char *model_path, size_t footprint_bytes, void *user_data)
	Residency observer callback.
typedef ent_decision_t(*	ent_delegation_start_cb) (const ent_delegation_request_t *req, void *user_data)
	Callback fired before a delegation runs.
typedef ent_decision_t(*	ent_delegation_complete_cb) (const ent_delegation_result_t *res, void *user_data)
	Callback fired after a delegation produces a patch.
typedef void(*	ent_validation_attempt_boundary_cb) (int attempt_n, void *user_data)
	Stream-side callback fired between constitutional revision passes.
typedef int(*	entropic_compactor_fn) (const char *messages_json, const char *config_json, char **out_messages, char **out_summary, void *user_data)
	Compactor function type.
typedef struct entropic_logprob_result	entropic_logprob_result_t
	Per-token log-probability result.

Enumerations
enum	entropic_residency_event_t { ENTROPIC_RESIDENCY_LOADED = 0 , ENTROPIC_RESIDENCY_EVICTED = 1 , ENTROPIC_RESIDENCY_ACTIVATION_SWAP = 2 }
	Reasons fired by entropic_residency_observer_t. More...
enum	ent_decision_t { ENT_DECISION_ACCEPT = 0 , ENT_DECISION_REJECT = 1 }
	Consumer decision returned from delegation callbacks. More...
enum	entropic_mcp_access_level_t { ENTROPIC_MCP_ACCESS_NONE = 0 , ENTROPIC_MCP_ACCESS_READ = 1 , ENTROPIC_MCP_ACCESS_WRITE = 2 }
	Access level enum for MCP authorization. More...

Functions
ENTROPIC_EXPORT entropic_error_t	entropic_create (entropic_handle_t *handle)
	Create a new engine instance.
ENTROPIC_EXPORT entropic_error_t	entropic_configure (entropic_handle_t handle, const char *config_json)
	Configure the engine from a JSON config string.
ENTROPIC_EXPORT entropic_error_t	entropic_configure_from_file (entropic_handle_t handle, const char *config_path)
	Configure engine from a YAML or JSON config file.
ENTROPIC_EXPORT entropic_error_t	entropic_configure_dir (entropic_handle_t handle, const char *project_dir)
	Configure engine using layered config resolution.
ENTROPIC_EXPORT void	entropic_destroy (entropic_handle_t handle)
	Destroy an engine instance and free all resources.
ENTROPIC_EXPORT const char *	entropic_version (void)
	Get the library version string.
ENTROPIC_EXPORT int	entropic_api_version (void)
	Get the C API version number.
ENTROPIC_EXPORT int64_t	entropic_seconds_since_last_activity (entropic_handle_t handle)
	Seconds since the engine last serviced a run (gh#35, v2.3.0).
ENTROPIC_EXPORT void *	entropic_alloc (size_t size)
	Allocate memory using the engine's allocator.
ENTROPIC_EXPORT void	entropic_free (void *ptr)
	Free memory allocated by the engine or entropic_alloc().
ENTROPIC_EXPORT entropic_error_t	entropic_run (entropic_handle_t handle, const char *input, char **result_json)
	Synchronous agentic loop.
ENTROPIC_EXPORT entropic_error_t	entropic_run_streaming (entropic_handle_t handle, const char *input, void(*on_token)(const char *token, size_t len, void *user_data), void *user_data, int *cancel_flag)
	Streaming agentic loop with token callback.
ENTROPIC_EXPORT entropic_error_t	entropic_run_messages (entropic_handle_t handle, const char *messages_json, char **result_json)
	Multimodal-aware agentic run with messages-array input (gh#37).
ENTROPIC_EXPORT entropic_error_t	entropic_run_messages_streaming (entropic_handle_t handle, const char *messages_json, void(*on_token)(const char *token, size_t len, void *user_data), void *user_data, int *cancel_flag)
	Streaming variant of entropic_run_messages (gh#37).
ENTROPIC_EXPORT entropic_error_t	entropic_set_stream_observer (entropic_handle_t handle, void(*observer)(const char *token, size_t len, void *user_data), void *user_data)
	Set a global stream observer callback.
ENTROPIC_EXPORT entropic_error_t	entropic_set_state_observer (entropic_handle_t handle, void(*observer)(int state, void *user_data), void *user_data)
	Register an engine state-change observer.
ENTROPIC_EXPORT entropic_error_t	entropic_set_critique_callbacks (entropic_handle_t handle, void(*start_cb)(void *user_data), void(*end_cb)(void *user_data), void *user_data)
	Register start/end callbacks for constitutional critique generation (gh#50, v2.1.12).
ENTROPIC_EXPORT entropic_error_t	entropic_interrupt (entropic_handle_t handle)
	Interrupt a running generation.
ENTROPIC_EXPORT entropic_error_t	entropic_queue_user_message (entropic_handle_t handle, const char *message)
	Queue a user message to be injected at the next top-level turn boundary.
ENTROPIC_EXPORT entropic_error_t	entropic_user_message_queue_depth (entropic_handle_t handle, size_t *count)
	Query the current depth of the mid-gen user-message queue.
ENTROPIC_EXPORT entropic_error_t	entropic_clear_user_message_queue (entropic_handle_t handle)
	Drop all queued user messages.
ENTROPIC_EXPORT entropic_error_t	entropic_set_queue_observer (entropic_handle_t handle, void(*observer)(const char *consumed, size_t remaining, void *user_data), void *user_data)
	Register an observer for queue-consumption events.
ENTROPIC_EXPORT entropic_error_t	entropic_speculative_compat (entropic_handle_t handle, int *compatible, char **diagnostic)
	Query whether the configured target/draft pair is compatible for speculative decoding.
ENTROPIC_EXPORT entropic_error_t	entropic_set_residency_observer (entropic_handle_t handle, entropic_residency_observer_t observer, void *user_data)
	Register a residency observer on a handle.
ENTROPIC_EXPORT entropic_error_t	entropic_residency_snapshot (entropic_handle_t handle, char **out_json)
	Snapshot of the engine's current VRAM residency set.
ENTROPIC_EXPORT entropic_error_t	entropic_context_clear (entropic_handle_t handle)
	Clear conversation history, starting a new session.
ENTROPIC_EXPORT entropic_error_t	entropic_context_get (entropic_handle_t handle, char **messages_json)
	Get the current conversation history as a JSON array.
ENTROPIC_EXPORT entropic_error_t	entropic_context_count (entropic_handle_t handle, size_t *count)
	Get the number of messages in the conversation.
ENTROPIC_EXPORT entropic_error_t	entropic_context_usage (entropic_handle_t handle, size_t *tokens_used, size_t *capacity)
	Read current context-window pressure for the active tier.
ENTROPIC_EXPORT entropic_error_t	entropic_metrics_json (entropic_handle_t handle, char **out)
	Get loop metrics from the most recent run as JSON.
ENTROPIC_EXPORT entropic_error_t	entropic_set_delegation_callbacks (entropic_handle_t handle, ent_delegation_start_cb on_start, ent_delegation_complete_cb on_complete, void *user_data)
	Register start/complete callbacks for delegations.
ENTROPIC_EXPORT entropic_error_t	entropic_validation_set_auto_retry (entropic_handle_t handle, int enabled)
	Toggle automatic constitutional revision after rejection.
ENTROPIC_EXPORT entropic_error_t	entropic_validation_resume_retry (entropic_handle_t handle)
	Opt the engine into running the constitutional revision pass.
ENTROPIC_EXPORT entropic_error_t	entropic_validation_accept_last (entropic_handle_t handle)
	Finalize the last attempt as the turn's response.
ENTROPIC_EXPORT entropic_error_t	entropic_set_attempt_boundary_cb (entropic_handle_t handle, ent_validation_attempt_boundary_cb cb, void *user_data)
	Register an attempt-boundary callback for the validator.
ENTROPIC_EXPORT entropic_error_t	entropic_register_mcp_server (entropic_handle_t handle, const char *name, const char *config_json)
	Register an external MCP server at runtime.
ENTROPIC_EXPORT entropic_error_t	entropic_deregister_mcp_server (entropic_handle_t handle, const char *name)
	Deregister an external MCP server.
ENTROPIC_EXPORT char *	entropic_list_mcp_servers (entropic_handle_t handle)
	List all MCP servers with status information.
ENTROPIC_EXPORT entropic_error_t	entropic_storage_open (entropic_handle_t handle, const char *db_path)
	Open or create a SQLite storage backend.
ENTROPIC_EXPORT entropic_error_t	entropic_storage_close (entropic_handle_t handle)
	Close the storage backend and flush pending writes.
ENTROPIC_EXPORT entropic_error_t	entropic_load_identity (entropic_handle_t handle, const char *identity_name)
	Load an identity by name from the configuration.
ENTROPIC_EXPORT entropic_error_t	entropic_get_identity (entropic_handle_t handle, char **identity_json)
	Get the current active identity as a JSON string.
ENTROPIC_EXPORT entropic_error_t	entropic_register_hook (entropic_handle_t handle, entropic_hook_point_t hook_point, entropic_hook_callback_t callback, void *user_data, int priority)
	Register a callback for an engine hook point.
ENTROPIC_EXPORT entropic_error_t	entropic_deregister_hook (entropic_handle_t handle, entropic_hook_point_t hook_point, entropic_hook_callback_t callback, void *user_data)
	Deregister a previously registered hook callback.
ENTROPIC_EXPORT entropic_error_t	entropic_adapter_load (entropic_handle_t handle, const char *adapter_name, const char *adapter_path, const char *base_model_path, float scale)
	Load a LoRA adapter into RAM.
ENTROPIC_EXPORT entropic_error_t	entropic_adapter_unload (entropic_handle_t handle, const char *adapter_name)
	Unload a LoRA adapter.
ENTROPIC_EXPORT entropic_error_t	entropic_adapter_swap (entropic_handle_t handle, const char *adapter_name)
	Swap the active LoRA adapter.
ENTROPIC_EXPORT int	entropic_adapter_state (entropic_handle_t handle, const char *adapter_name)
	Query adapter state.
ENTROPIC_EXPORT char *	entropic_adapter_info (entropic_handle_t handle, const char *adapter_name)
	Get adapter info as JSON.
ENTROPIC_EXPORT char *	entropic_adapter_list (entropic_handle_t handle)
	List all adapters as JSON array.
ENTROPIC_EXPORT entropic_error_t	entropic_grammar_register (entropic_handle_t handle, const char *key, const char *gbnf_content)
	Register a grammar by key from a GBNF content string.
ENTROPIC_EXPORT entropic_error_t	entropic_grammar_register_file (entropic_handle_t handle, const char *key, const char *path)
	Register a grammar from a file path.
ENTROPIC_EXPORT entropic_error_t	entropic_grammar_deregister (entropic_handle_t handle, const char *key)
	Remove a grammar from the registry.
ENTROPIC_EXPORT char *	entropic_grammar_get (entropic_handle_t handle, const char *key)
	Get grammar content by key.
ENTROPIC_EXPORT char *	entropic_grammar_validate (const char *gbnf_content)
	Validate a GBNF grammar string without registering.
ENTROPIC_EXPORT char *	entropic_grammar_list (entropic_handle_t handle)
	List all registered grammars as JSON array.
ENTROPIC_EXPORT entropic_error_t	entropic_profile_register (entropic_handle_t handle, const char *profile_json)
	Register a custom GPU resource profile.
ENTROPIC_EXPORT entropic_error_t	entropic_profile_deregister (entropic_handle_t handle, const char *name)
	Remove a GPU resource profile.
ENTROPIC_EXPORT char *	entropic_profile_get (entropic_handle_t handle, const char *name)
	Get a profile by name as JSON.
ENTROPIC_EXPORT char *	entropic_profile_list (entropic_handle_t handle)
	List all registered profiles as JSON array.
ENTROPIC_EXPORT double	entropic_throughput_tok_per_sec (entropic_handle_t handle, const char *model_path)
	Get current throughput estimate for a model.
ENTROPIC_EXPORT void	entropic_throughput_reset (entropic_handle_t handle, const char *model_path)
	Reset throughput tracking data for a model.
ENTROPIC_EXPORT entropic_error_t	entropic_grant_mcp_key (entropic_handle_t handle, const char *identity_name, const char *pattern, entropic_mcp_access_level_t level)
	Grant an MCP tool key to an identity.
ENTROPIC_EXPORT entropic_error_t	entropic_revoke_mcp_key (entropic_handle_t handle, const char *identity_name, const char *pattern)
	Revoke an MCP tool key from an identity.
ENTROPIC_EXPORT int	entropic_check_mcp_key (entropic_handle_t handle, const char *identity_name, const char *tool_name, entropic_mcp_access_level_t level)
	Check if a tool call is authorized for an identity.
ENTROPIC_EXPORT char *	entropic_list_mcp_keys (entropic_handle_t handle, const char *identity_name)
	List all MCP keys for an identity as JSON.
ENTROPIC_EXPORT entropic_error_t	entropic_grant_mcp_key_from (entropic_handle_t handle, const char *granter, const char *grantee, const char *pattern, entropic_mcp_access_level_t level)
	Grant a key from one identity to another.
ENTROPIC_EXPORT char *	entropic_serialize_mcp_keys (entropic_handle_t handle)
	Serialize all identity key sets to JSON.
ENTROPIC_EXPORT entropic_error_t	entropic_deserialize_mcp_keys (entropic_handle_t handle, const char *json)
	Deserialize all identity key sets from JSON.
ENTROPIC_EXPORT entropic_error_t	entropic_audit_flush (entropic_handle_t handle)
	Flush the audit logger to disk immediately.
ENTROPIC_EXPORT entropic_error_t	entropic_audit_count (entropic_handle_t handle, size_t *count)
	Get the number of audit log entries recorded this session.
ENTROPIC_EXPORT entropic_error_t	entropic_audit_read (entropic_handle_t handle, const char *path, const char *filter_json, char **result_json)
	Read audit log entries from a JSONL file.
ENTROPIC_EXPORT entropic_error_t	entropic_create_identity (entropic_handle_t handle, const char *config_json)
	Create a dynamic identity.
ENTROPIC_EXPORT entropic_error_t	entropic_update_identity (entropic_handle_t handle, const char *name, const char *config_json)
	Update a dynamic identity.
ENTROPIC_EXPORT entropic_error_t	entropic_destroy_identity (entropic_handle_t handle, const char *name)
	Destroy a dynamic identity.
ENTROPIC_EXPORT char *	entropic_get_identity_config (entropic_handle_t handle, const char *name)
	Get identity configuration as JSON by name.
ENTROPIC_EXPORT char *	entropic_list_identities (entropic_handle_t handle)
	List all identity names as JSON array.
ENTROPIC_EXPORT entropic_error_t	entropic_identity_count (entropic_handle_t handle, size_t *total, size_t *dynamic)
	Get identity count.
ENTROPIC_EXPORT entropic_error_t	entropic_compact (entropic_handle_t handle, const char *identity, char **result_json)
	Trigger compaction on the current context.
ENTROPIC_EXPORT entropic_error_t	entropic_register_compactor (entropic_handle_t handle, const char *identity, entropic_compactor_fn compactor, void *user_data)
	Register a custom compactor for an identity.
ENTROPIC_EXPORT entropic_error_t	entropic_deregister_compactor (entropic_handle_t handle, const char *identity)
	Deregister a custom compactor for an identity.
ENTROPIC_EXPORT entropic_error_t	entropic_get_default_compactor (entropic_handle_t handle, entropic_compactor_fn *compactor, void **user_data)
	Get the built-in default compactor function pointer.
ENTROPIC_EXPORT entropic_error_t	entropic_get_logprobs (entropic_handle_t handle, const char *model_id, const int32_t *tokens, int n_tokens, entropic_logprob_result_t *result)
	Evaluate per-token log-probabilities for a token sequence.
ENTROPIC_EXPORT entropic_error_t	entropic_compute_perplexity (entropic_handle_t handle, const char *model_id, const int32_t *tokens, int n_tokens, float *perplexity)
	Compute perplexity for a token sequence.
ENTROPIC_EXPORT void	entropic_free_logprob_result (entropic_logprob_result_t *result)
	Free internal arrays of a logprob result.
ENTROPIC_EXPORT entropic_error_t	entropic_validation_set_enabled (entropic_handle_t handle, bool enabled)
	Enable or disable constitutional validation.
ENTROPIC_EXPORT entropic_error_t	entropic_validation_set_identity (entropic_handle_t handle, const char *identity_name, bool enabled)
	Set per-identity validation override.
ENTROPIC_EXPORT char *	entropic_validation_last_result (entropic_handle_t handle)
	Get the last validation result as JSON.
ENTROPIC_EXPORT int	entropic_model_has_vision (entropic_handle_t handle, const char *model_id)
	Check if a model has vision capability.
ENTROPIC_EXPORT entropic_error_t	entropic_get_diagnostic_prompt (entropic_handle_t handle, char **prompt_out)
	Get the diagnostic prompt text for /diagnose command.

Detailed Description

Public C API for the Entropic inference engine.

This is the unified facade. Most consumers link against librentropic and include only this header. All functions are pure C — no C++ types cross this boundary.

Lifecycle

entropic_handle_t h = NULL;
entropic_create(&h);
entropic_configure(h, config_json);
entropic_run(h, "Hello", &result);
entropic_free(result);
entropic_destroy(h);

Thread safety

Each function documents its thread safety class:

• Thread-safe: callable from any thread at any time.
• Serialized per-handle: one call at a time per handle; different handles are fully independent.
• Single-threaded init/destroy: must not race with any other call on the same handle.

Error handling

Functions returning entropic_error_t set per-handle error state on failure. Call entropic_last_error(handle) for the detailed message.

Memory ownership

Functions returning char* transfer ownership to the caller. Free with entropic_free(). Consumers providing buffers the engine will free (e.g., hook modified_json) MUST allocate with entropic_alloc(). Strings returned as const char* are owned by the handle and valid until the next call on that handle.

Version

1.9.10

Definition in file entropic.h.

Typedef Documentation

ent_delegation_complete_cb

typedef ent_decision_t(* ent_delegation_complete_cb) (const ent_delegation_result_t *res, void *user_data)

Callback fired after a delegation produces a patch.

Invoked once per delegation (and once per pipeline as a whole — the pipeline shares a single sandbox). The engine discards the sandbox directory regardless of the consumer's return value.

Default-deny behavior

If no callback is registered (NULL), the engine writes the patch to ~/.entropic/sandbox/<session-id>/pending/<delegation-id>.patch and logs at WARN — a diagnostic fallback, not a delivery channel (path is session-scoped). Same path is used when the registered callback returns ENT_DECISION_REJECT.

Parameters

res	Result descriptor (engine-owned, callback-scoped).
user_data	Pointer passed to entropic_set_delegation_callbacks.

Returns

ENT_DECISION_ACCEPT if the consumer took responsibility for the patch (the engine simply discards the sandbox); ENT_DECISION_REJECT to dump the patch to the pending dir for later inspection.

Version

2.1.5

Definition at line 956 of file entropic.h.

ent_delegation_start_cb

typedef ent_decision_t(* ent_delegation_start_cb) (const ent_delegation_request_t *req, void *user_data)

Callback fired before a delegation runs.

The consumer can return ENT_DECISION_REJECT to abort the delegation before any child loop runs (defense-in-depth gate for user consent or policy enforcement). On REJECT the engine records a failure result and returns control to the parent loop without spawning a child.

Parameters

req	Request descriptor (engine-owned, callback-scoped).
user_data	Pointer passed to entropic_set_delegation_callbacks.

Returns

ENT_DECISION_ACCEPT to proceed, ENT_DECISION_REJECT to abort.

Version

2.1.5

Definition at line 931 of file entropic.h.

ent_validation_attempt_boundary_cb

typedef void(* ent_validation_attempt_boundary_cb) (int attempt_n, void *user_data)

Stream-side callback fired between constitutional revision passes.

Lets consumers split rendered output between attempt N and attempt N+1 cleanly instead of inferring boundaries from rejection timing. Fires immediately before the engine begins re-streaming a revised attempt.

Parameters

attempt_n	Index of the attempt about to start (1-based — the first revision pass after the original generation is N=1).
user_data	Pointer passed to entropic_set_attempt_boundary_cb.

Version

2.1.5

Definition at line 1003 of file entropic.h.

entropic_compactor_fn

typedef int(* entropic_compactor_fn) (const char *messages_json, const char *config_json, char **out_messages, char **out_summary, void *user_data)

Compactor function type.

A compactor takes a JSON array of messages, a configuration JSON, and produces a compacted JSON array of messages plus a summary string.

Parameters

messages_json	JSON array of messages to compact.
config_json	Compaction configuration (threshold, identity, etc.).
out_messages	Output: compacted messages JSON. Caller frees with entropic_free().
out_summary	Output: summary text. Caller frees with entropic_free(). May be NULL.
user_data	Opaque pointer from registration.

Returns

0 on success, non-zero on failure.

Config JSON schema:

{
  "identity": "eng",
  "token_count": 12000,
  "max_tokens": 16384,
  "threshold_percent": 0.75,
  "force": false
}

@callback

Version

1.9.10

Definition at line 1966 of file entropic.h.

entropic_logprob_result_t

typedef struct entropic_logprob_result entropic_logprob_result_t

Per-token log-probability result.

Contains per-token log-probabilities for a sequence evaluated against a loaded model. The logprobs array has (n_tokens - 1) entries: logprobs[i] is the log-probability of tokens[i+1] given tokens[0..i].

The struct itself is caller-owned (stack or heap). The internal logprobs and tokens arrays are engine-allocated and must be freed via entropic_free_logprob_result().

Version

1.9.10

entropic_residency_observer_t

typedef void(* entropic_residency_observer_t) (entropic_residency_event_t event, const char *tier_name, const char *model_path, size_t footprint_bytes, void *user_data)

Residency observer callback.

Fires from the engine thread synchronously with the corresponding orchestrator lifecycle transition, while the residency-set mutex is held. The callback MUST NOT call back into entropic on the same handle — keep it short (log / counter increment / queue-and-return).

Parameters

event	One of entropic_residency_event_t.
tier_name	Tier whose backing model entered/left VRAM. NUL-terminated, valid only for the callback's duration.
model_path	Resolved GGUF path for the model. NUL-terminated, valid only for the callback's duration.
footprint_bytes	Tracked VRAM footprint (weights + KV + headroom estimate). 0 if the engine could not estimate.
user_data	Opaque pointer registered alongside the callback. @callback

Version

2.2.4

Definition at line 678 of file entropic.h.

Enumeration Type Documentation

ent_decision_t

enum ent_decision_t

Consumer decision returned from delegation callbacks.

Used by both ent_delegation_start_cb (gate the delegation before it runs) and ent_delegation_complete_cb (decide what to do with the resulting patch).

Version

2.1.5

Definition at line 870 of file entropic.h.

entropic_mcp_access_level_t

enum entropic_mcp_access_level_t

Access level enum for MCP authorization.

Version

1.9.4

Enumerator
ENTROPIC_MCP_ACCESS_NONE	No access.
ENTROPIC_MCP_ACCESS_READ	Read-only operations.
ENTROPIC_MCP_ACCESS_WRITE	Read + write operations.

Definition at line 1617 of file entropic.h.

entropic_residency_event_t

enum entropic_residency_event_t

Reasons fired by entropic_residency_observer_t.

Stable contract — values are part of the C ABI. New reasons are appended; existing values do not change.

Version

2.2.4

Enumerator
ENTROPIC_RESIDENCY_LOADED	Tier model just loaded into VRAM.
ENTROPIC_RESIDENCY_EVICTED	Tier model just unloaded to free VRAM.
ENTROPIC_RESIDENCY_ACTIVATION_SWAP	Active tier swapped without unload (multi-resident hit)

Definition at line 653 of file entropic.h.

Function Documentation

entropic_adapter_info()

ENTROPIC_EXPORT char * entropic_adapter_info	(	entropic_handle_t	handle,
		const char *	adapter_name
	)

Get adapter info as JSON.

Parameters

handle	Engine handle.
adapter_name	Adapter identifier.

Returns

JSON string with adapter metadata. Caller frees with entropic_free(). NULL if adapter not found.

@threadsafety Serialized per-handle.

Version

1.9.2

Memory ownership

Caller must free returned string with entropic_free().

Get adapter info as JSON.

Returns a JSON object with name, state, scale, ram_bytes, path, tier_name, and base_model_path. Caller frees with entropic_free().

Returns

JSON string (caller frees), or NULL on error.

Definition at line 2535 of file entropic.cpp.

entropic_adapter_list()

ENTROPIC_EXPORT char * entropic_adapter_list

(

entropic_handle_t

handle

)

List all adapters as JSON array.

Parameters

handle

Engine handle.

Returns

JSON array of AdapterInfo objects. Caller frees with entropic_free().

@threadsafety Serialized per-handle.

Version

1.9.2

Memory ownership

Caller must free returned string with entropic_free().

List all adapters as JSON array.

Returns a JSON array of objects, each with name, state, scale, and tier_name. Caller frees with entropic_free().

Returns

JSON array string (caller frees), or NULL on error.

Definition at line 2564 of file entropic.cpp.

entropic_adapter_load()

ENTROPIC_EXPORT entropic_error_t entropic_adapter_load	(	entropic_handle_t	handle,
		const char *	adapter_name,
		const char *	adapter_path,
		const char *	base_model_path,
		float	scale
	)

Load a LoRA adapter into RAM.

Parameters

handle	Engine handle.
adapter_name	Unique adapter identifier.
adapter_path	Path to the LoRA .gguf file.
base_model_path	Base model this adapter targets (must be loaded).
scale	LoRA scaling factor (1.0 = full strength).

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_MODEL_NOT_FOUND — base model not loaded.
• ENTROPIC_ERROR_ADAPTER_LOAD_FAILED — adapter file invalid.
• ENTROPIC_ERROR_INVALID_CONFIG — adapter already loaded.

@threadsafety Serialized per-handle.

Version

1.9.2

Requires a configured engine. The adapter_manager needs llama_model* pointers that are only available from a loaded backend, so this delegates through the orchestrator's backend for the given tier. base_model_path is resolved to a tier via model path matching.

Returns

ENTROPIC_OK on success, error code on failure.

Definition at line 2391 of file entropic.cpp.

entropic_adapter_state()

ENTROPIC_EXPORT int entropic_adapter_state	(	entropic_handle_t	handle,
		const char *	adapter_name
	)

Query adapter state.

Parameters

handle	Engine handle.
adapter_name	Adapter identifier.

Returns

State as int: 0=COLD, 1=WARM, 2=HOT. -1 if not found.

@threadsafety Thread-safe.

Version

1.9.2

Query adapter state.

Returns the AdapterState as an integer: 0=COLD, 1=WARM, 2=HOT. Returns -1 if the handle is invalid or adapter name not found.

Returns

AdapterState as int, or -1 on error.

Definition at line 2507 of file entropic.cpp.

entropic_adapter_swap()

ENTROPIC_EXPORT entropic_error_t entropic_adapter_swap	(	entropic_handle_t	handle,
		const char *	adapter_name
	)

Swap the active LoRA adapter.

Parameters

handle	Engine handle.
adapter_name	Adapter to activate (must be WARM or HOT).

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_ADAPTER_NOT_FOUND — adapter not loaded.
• ENTROPIC_ERROR_ADAPTER_SWAP_FAILED — swap failed.
• ENTROPIC_ERROR_ADAPTER_CANCELLED — hook cancelled.

@threadsafety Serialized per-handle.

Version

1.9.2

Swap the active LoRA adapter.

Adapter swap requires llama_context* for activation/deactivation. The C API cannot safely provide this — use tier-based adapter configuration for lifecycle management.

Returns

ENTROPIC_OK on success, error code on failure.

Definition at line 2472 of file entropic.cpp.

entropic_adapter_unload()

ENTROPIC_EXPORT entropic_error_t entropic_adapter_unload	(	entropic_handle_t	handle,
		const char *	adapter_name
	)

Unload a LoRA adapter.

Parameters

handle	Engine handle.
adapter_name	Adapter to unload.

Returns

ENTROPIC_OK on success. Idempotent if already COLD.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

@threadsafety Serialized per-handle.

Version

1.9.2

Adapter unload requires llama_context* for deactivation if HOT. The C API cannot safely provide this — use tier-based adapter configuration for lifecycle management.

Returns

ENTROPIC_OK on success, error code on failure.

Definition at line 2434 of file entropic.cpp.

entropic_alloc()

ENTROPIC_EXPORT void * entropic_alloc

(

size_t

size

)

Allocate memory using the engine's allocator.

All cross-boundary allocations (hook modified_json, consumer-provided strings that the engine will free) MUST use this function. Paired with entropic_free().

Parameters

size	Number of bytes to allocate.

Returns

Pointer to allocated memory, or NULL on failure.

@threadsafety Thread-safe.

Version

1.8.0

Returns

Pointer to allocated memory, or NULL on failure. @utility

Version

1.8.0

Definition at line 1728 of file entropic.cpp.

entropic_api_version()

ENTROPIC_EXPORT int entropic_api_version

(

void

)

Get the C API version number.

Returns an integer starting at 1. Incremented on breaking changes: signature changes, function removals, enum renumbering, or behavior changes. Adding new functions does NOT increment this value.

Compare with ENTROPIC_API_VERSION at compile time for version checks.

Returns

API version integer.

@threadsafety Thread-safe.

Version

1.8.0

See also

ENTROPIC_API_VERSION (compile-time constant in entropic_config.h)

Get the C API version number.

Returns

API version integer. @utility

Version

2.0.0

Definition at line 1707 of file entropic.cpp.

entropic_audit_count()

ENTROPIC_EXPORT entropic_error_t entropic_audit_count	(	entropic_handle_t	handle,
		size_t *	count
	)

Get the number of audit log entries recorded this session.

Parameters

	handle	Engine handle.
[out]	count	Output: number of entries recorded.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — count is NULL.
• ENTROPIC_ERROR_INVALID_CONFIG — no audit logger configured.

@threadsafety Lock-free read.

Version

1.9.5

Get the number of audit log entries recorded this session.

Returns

ENTROPIC_OK on success.

Definition at line 47 of file entropic_audit.cpp.

entropic_audit_flush()

ENTROPIC_EXPORT entropic_error_t entropic_audit_flush

(

entropic_handle_t

handle

)

Flush the audit logger to disk immediately.

Parameters

handle

Engine handle.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_CONFIG — no audit logger configured.

@threadsafety Serialized per-handle.

Version

1.9.5

Flush the audit logger to disk immediately.

Returns

ENTROPIC_OK on success.

Definition at line 32 of file entropic_audit.cpp.

entropic_audit_read()

ENTROPIC_EXPORT entropic_error_t entropic_audit_read	(	entropic_handle_t	handle,
		const char *	path,
		const char *	filter_json,
		char **	result_json
	)

Read audit log entries from a JSONL file.

Reads and parses entries from an audit.jsonl file. No tool calls are executed — this is inspection only.

Parameters

	handle	Engine handle.
	path	Path to audit.jsonl file (null-terminated).
	filter_json	Filter criteria as JSON, or NULL for no filter. Format: {"caller_id": "eng", "tool_name": "filesystem.*"} All fields optional. Absent fields match everything.
[out]	result_json	Output: JSON array of audit entries. Caller must free with entropic_free().

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — path or result_json is NULL.
• ENTROPIC_ERROR_INVALID_CONFIG — path cannot be read.

@threadsafety Serialized per-handle.

Version

1.9.5

Parameters

path	Filesystem path to the JSONL audit log file.
result_json	Out-param: newly allocated JSON string (caller owns; free with entropic_free).

Returns

ENTROPIC_OK on success.

Definition at line 67 of file entropic_audit.cpp.

entropic_check_mcp_key()

ENTROPIC_EXPORT int entropic_check_mcp_key	(	entropic_handle_t	handle,
		const char *	identity_name,
		const char *	tool_name,
		entropic_mcp_access_level_t	level
	)

Check if a tool call is authorized for an identity.

Parameters

handle	Engine handle.
identity_name	Identity/tier name (null-terminated).
tool_name	Fully-qualified tool name (null-terminated).
level	Required access level.

Returns

1 if authorized, 0 if denied, -1 on error.

@threadsafety Thread-safe.

Version

1.9.4

Check if a tool call is authorized for an identity.

Returns

1 if authorized, 0 if denied, -1 on error.

Definition at line 3006 of file entropic.cpp.

entropic_clear_user_message_queue()

ENTROPIC_EXPORT entropic_error_t entropic_clear_user_message_queue

(

entropic_handle_t

handle

)

Drop all queued user messages.

Consumer-initiated retract. Does NOT affect the in-flight turn — only the not-yet-consumed pending messages are discarded.

@threadsafety Thread-safe.

Parameters

handle

Engine handle.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

Version

2.1.10

Drop all queued user messages.

Definition at line 2245 of file entropic.cpp.

entropic_compact()

ENTROPIC_EXPORT entropic_error_t entropic_compact	(	entropic_handle_t	handle,
		const char *	identity,
		char **	result_json
	)

Trigger compaction on the current context.

Forces compaction regardless of threshold. Runs through the full pipeline: PRE_COMPACT hooks -> compactor -> POST_COMPACT hooks.

Parameters

handle	Engine handle.
identity	Identity context for compactor selection (NULL = current).
result_json	Output: compaction result JSON. Caller frees with entropic_free(). NULL if no compaction occurred (e.g., cancelled by hook).

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE
• ENTROPIC_ERROR_COMPACTION_FAILED

@threadsafety Serialized per-handle.

Version

1.9.9

Trigger compaction on the current context.

Parameters

handle	Engine handle returned by entropic_create.
identity	Identity name from configured tier set.
result_json	Out-param: newly allocated JSON string (caller owns; free with entropic_free).

Returns

ENTROPIC_OK on success.

Definition at line 43 of file entropic_compaction.cpp.

entropic_compute_perplexity()

ENTROPIC_EXPORT entropic_error_t entropic_compute_perplexity	(	entropic_handle_t	handle,
		const char *	model_id,
		const int32_t *	tokens,
		int	n_tokens,
		float *	perplexity
	)

Compute perplexity for a token sequence.

Convenience — calls entropic_get_logprobs() internally and returns only the perplexity value.

Parameters

handle	Engine handle.
model_id	Model identifier (tier name or model key).
tokens	Array of token IDs to evaluate.
n_tokens	Number of tokens (minimum 2).
perplexity	Output: perplexity value.

Returns

ENTROPIC_OK on success. Same error codes as entropic_get_logprobs().

@threadsafety Same as entropic_get_logprobs().

Version

1.9.10

Convenience wrapper — resolves the tier backend and calls InferenceBackend::compute_perplexity().

Returns

ENTROPIC_OK on success, error code on failure.

Definition at line 3318 of file entropic.cpp.

entropic_configure()

ENTROPIC_EXPORT entropic_error_t entropic_configure	(	entropic_handle_t	handle,
		const char *	config_json
	)

Configure the engine from a JSON config string.

Parses the JSON, validates against the config schema, resolves model paths, and prepares the engine for operation. Does NOT load models (that happens on first generate or explicit activate).

JSON is used at the C API boundary because it's universal — any language can produce it. Config FILES are YAML (parsed by ryml inside librentropic-config.so). Use entropic_configure_from_file() to load YAML config files directly without manual JSON conversion.

Parameters

handle	Engine handle.
config_json	JSON string with engine configuration.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — config_json is NULL.
• ENTROPIC_ERROR_INVALID_CONFIG — config validation failed.

@threadsafety Serialized per-handle.

Version

1.8.0

Configure the engine from a JSON config string.

Returns

ENTROPIC_OK on success.

Definition at line 1526 of file entropic.cpp.

entropic_configure_dir()

ENTROPIC_EXPORT entropic_error_t entropic_configure_dir	(	entropic_handle_t	handle,
		const char *	project_dir
	)

Configure engine using layered config resolution.

Loads configuration in priority order (highest wins):

1. Compiled defaults
2. Bundled default (data/default_config.yaml)
3. Global config (~/.entropic/config.yaml)
4. Project config ({project_dir}/config.local.yaml)
5. Environment variables (ENTROPIC_*)

This is the recommended configuration path for most consumers. The project_dir also sets the working directory for log files and session state (e.g., ".hello-world", ".entropic").

Parameters

handle	Engine handle.
project_dir	Project config directory (null-terminated). Contains config.local.yaml and receives session logs. Pass NULL or "" to use only global + bundled defaults.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_CONFIG — config validation failed.

@threadsafety Serialized per-handle.

Version

2.0.1

Configure engine using layered config resolution.

Loads bundled default → global → project config.local.yaml → env. Sets config.log_dir to project_dir if not already set. gh#31 (v2.1.6): propagates project_dir to AgentEngine::set_project_dir so sandbox snapshots use the configured tree rather than CWD.

Returns

ENTROPIC_OK on success.

Definition at line 1605 of file entropic.cpp.

entropic_configure_from_file()

ENTROPIC_EXPORT entropic_error_t entropic_configure_from_file	(	entropic_handle_t	handle,
		const char *	config_path
	)

Configure engine from a YAML or JSON config file.

Convenience wrapper that reads the file, parses it (YAML via ryml or JSON via nlohmann/json based on extension), and applies the configuration.

Parameters

handle	Engine handle.
config_path	Path to YAML (.yaml/.yml) or JSON (.json) config file.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — config_path is NULL.
• ENTROPIC_ERROR_INVALID_CONFIG — config validation failed.
• ENTROPIC_ERROR_IO — file not found or unreadable.

@threadsafety Serialized per-handle.

Version

1.8.0

Configure engine from a YAML or JSON config file.

Returns

ENTROPIC_OK on success.

Definition at line 1556 of file entropic.cpp.

entropic_context_clear()

ENTROPIC_EXPORT entropic_error_t entropic_context_clear

(

entropic_handle_t

handle

)

Clear conversation history, starting a new session.

Removes all messages (system, user, assistant, tool) from the conversation. The next entropic_run() call starts fresh with only the system prompt.

Parameters

handle

Engine handle.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

@threadsafety Serialized per-handle.

Version

2.0.1

Clear conversation history, starting a new session.

Parameters

handle

Engine handle returned by entropic_create.

Returns

ENTROPIC_OK on success.

Definition at line 2287 of file entropic.cpp.

entropic_context_count()

ENTROPIC_EXPORT entropic_error_t entropic_context_count	(	entropic_handle_t	handle,
		size_t *	count
	)

Get the number of messages in the conversation.

Parameters

	handle	Engine handle.
[out]	count	Output: number of messages.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — count is NULL.

@threadsafety Thread-safe (read-only).

Version

2.0.1

Get the number of messages in the conversation.

Parameters

handle	Engine handle returned by entropic_create.
count	Out-param: receives the token count.

Returns

ENTROPIC_OK on success.

Definition at line 2320 of file entropic.cpp.

entropic_context_get()

ENTROPIC_EXPORT entropic_error_t entropic_context_get	(	entropic_handle_t	handle,
		char **	messages_json
	)

Get the current conversation history as a JSON array.

Returns the full message history including system prompt, user messages, assistant responses, and tool call results.

Parameters

	handle	Engine handle.
[out]	messages_json	Output: JSON array of message objects. Each object has "role" and "content" fields. Caller must free with entropic_free().

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — messages_json is NULL.

@threadsafety Serialized per-handle.

Version

2.0.1

Memory ownership

Caller must free *messages_json with entropic_free().

Get the current conversation history as a JSON array.

Parameters

handle	Engine handle returned by entropic_create.
messages_json	Out-param: newly allocated JSON string (caller owns; free with entropic_free).

Returns

ENTROPIC_OK on success.

Definition at line 2302 of file entropic.cpp.

entropic_context_usage()

ENTROPIC_EXPORT entropic_error_t entropic_context_usage	(	entropic_handle_t	handle,
		size_t *	tokens_used,
		size_t *	capacity
	)

Read current context-window pressure for the active tier.

Returns the same (used, capacity) pair the engine's core.context_manager logs at info level. Cheap — counts tokens across the current conversation against the active tier's context_length. Suitable for ~1 Hz consumer polling (e.g. a "6727/32768 tokens (20%)" UI gauge).

Parameters

	handle	Engine handle.
[out]	tokens_used	Output: tokens currently in the conversation.
[out]	capacity	Output: configured context_length for the active tier.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — either out pointer is NULL.
• ENTROPIC_ERROR_INVALID_STATE — engine has no active tier (rare; before first tier_lock / configure).

@threadsafety Serialized per-handle (api_mutex).

Version

2.1.8

Read current context-window pressure for the active tier.

Mirrors the Context: N/M tokens (P%) line emitted by core.context_manager. Reads from the engine's existing context_usage(messages) helper against the current conversation.

Parameters

handle	Engine handle.
tokens_used	Out-param: tokens in the current conversation.
capacity	Out-param: active tier's configured context_length.

Returns

ENTROPIC_OK on success.

Definition at line 2342 of file entropic.cpp.

entropic_create()

ENTROPIC_EXPORT entropic_error_t entropic_create

(

entropic_handle_t *

handle

)

Create a new engine instance.

Allocates and initializes an engine handle. The engine is idle until entropic_configure() is called.

Parameters

[out]

handle

Pointer to receive the new handle. Set to NULL on failure.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_ARGUMENT — handle is NULL.
• ENTROPIC_ERROR_OUT_OF_MEMORY — allocation failed.

@threadsafety Single-threaded init/destroy.

Version

1.8.0

Allocates the engine handle struct and initializes Phase 0 members (hook_registry, api_mutex, last_error, state flags). Subsystem pointers remain null until entropic_configure().

Returns

ENTROPIC_OK on success.

Definition at line 181 of file entropic.cpp.

entropic_create_identity()

ENTROPIC_EXPORT entropic_error_t entropic_create_identity	(	entropic_handle_t	handle,
		const char *	config_json
	)

Create a dynamic identity.

Parameters

handle	Engine handle.
config_json	Identity configuration as JSON string. Required fields: "name", "system_prompt", "focus" (array, min 1). Optional fields: "examples", "grammar_id", "auto_chain", "allowed_tools", "bash_commands", "mcp_keys", "adapter_path", "max_output_tokens", "temperature", "repeat_penalty", "enable_thinking", "interstitial", "routable", "explicit_completion", "phases".

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — config_json is NULL.
• ENTROPIC_ERROR_INVALID_CONFIG — validation failed.
• ENTROPIC_ERROR_LIMIT_REACHED — max_identities exceeded.
• ENTROPIC_ERROR_ALREADY_EXISTS — name already taken.

@threadsafety Serialized per-handle.

Version

1.9.6

Create a dynamic identity.

Returns

ENTROPIC_OK on success.

Definition at line 3120 of file entropic.cpp.

entropic_deregister_compactor()

ENTROPIC_EXPORT entropic_error_t entropic_deregister_compactor	(	entropic_handle_t	handle,
		const char *	identity
	)

Deregister a custom compactor for an identity.

After deregistration, the identity falls back to the global custom compactor (if any), then to the built-in default.

Parameters

handle	Engine handle.
identity	Identity name, or "" for global fallback.

Returns

ENTROPIC_OK on success (idempotent).

• ENTROPIC_ERROR_INVALID_HANDLE

@threadsafety Serialized per-handle.

Version

1.9.9

Parameters

handle	Engine handle returned by entropic_create.
identity	Identity name from configured tier set.

Returns

ENTROPIC_OK on success.

Definition at line 100 of file entropic_compaction.cpp.

entropic_deregister_hook()

ENTROPIC_EXPORT entropic_error_t entropic_deregister_hook	(	entropic_handle_t	handle,
		entropic_hook_point_t	hook_point,
		entropic_hook_callback_t	callback,
		void *	user_data
	)

Deregister a previously registered hook callback.

Matches on (hook_point, callback, user_data) triple. If no match is found, returns ENTROPIC_OK (idempotent).

Parameters

handle	Engine handle.
hook_point	The hook point to deregister from.
callback	The callback function pointer to remove.
user_data	The user_data that was passed during registration.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

@threadsafety Serialized per-handle.

Version

1.9.1

Returns

ENTROPIC_OK on success.

Definition at line 68 of file entropic_hooks.cpp.

entropic_deregister_mcp_server()

ENTROPIC_EXPORT entropic_error_t entropic_deregister_mcp_server	(	entropic_handle_t	handle,
		const char *	name
	)

Deregister an external MCP server.

Disconnects and removes the server. In-progress tool calls are not interrupted but subsequent calls will fail.

Parameters

handle	Engine handle.
name	Server name to remove (null-terminated).

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — name is NULL.
• ENTROPIC_ERROR_SERVER_NOT_FOUND — name not registered.

@threadsafety Serialized per-handle.

Version

1.8.7

Parameters

handle	Engine handle returned by entropic_create.
name	MCP server name (must be unique).

Returns

ENTROPIC_OK or error code.

Definition at line 138 of file entropic_mcp.cpp.

entropic_deserialize_mcp_keys()

ENTROPIC_EXPORT entropic_error_t entropic_deserialize_mcp_keys	(	entropic_handle_t	handle,
		const char *	json
	)

Deserialize all identity key sets from JSON.

Replaces all current key sets with the deserialized state.

Parameters

handle	Engine handle.
json	JSON object string.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — json is NULL.
• ENTROPIC_ERROR_INVALID_CONFIG — parse failure.

@threadsafety Serialized per-handle.

Version

1.9.4

Returns

ENTROPIC_OK on success.

Definition at line 3099 of file entropic.cpp.

entropic_destroy()

ENTROPIC_EXPORT void entropic_destroy

(

entropic_handle_t

handle

)

Destroy an engine instance and free all resources.

Unloads models, closes storage, destroys all child objects. After this call, the handle is invalid. Passing NULL is a no-op.

Parameters

handle

Engine handle to destroy (NULL-safe).

@threadsafety Single-threaded init/destroy. Must not race with any other call on the same handle.

Version

1.8.0

Destroy an engine instance and free all resources.

Tears down subsystems in reverse creation order. Each subsystem pointer is null-safe. After this call, the handle is invalid.

Definition at line 1661 of file entropic.cpp.

entropic_destroy_identity()

ENTROPIC_EXPORT entropic_error_t entropic_destroy_identity	(	entropic_handle_t	handle,
		const char *	name
	)

Destroy a dynamic identity.

Parameters

handle	Engine handle.
name	Identity name (null-terminated).

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — name is NULL.
• ENTROPIC_ERROR_IDENTITY_NOT_FOUND — identity doesn't exist.
• ENTROPIC_ERROR_PERMISSION_DENIED — identity is static.
• ENTROPIC_ERROR_IN_USE — identity active in delegation.

@threadsafety Serialized per-handle.

Version

1.9.6

Returns

ENTROPIC_OK on success.

Definition at line 3183 of file entropic.cpp.

entropic_free()

ENTROPIC_EXPORT void entropic_free

(

void *

ptr

)

Free memory allocated by the engine or entropic_alloc().

All char* return values that transfer ownership MUST be freed with this function. Passing NULL is a no-op.

Parameters

ptr	Pointer to free (from engine return value or entropic_alloc).

@threadsafety Thread-safe.

Version

1.8.0

Free memory allocated by the engine or entropic_alloc().

@utility

Version

1.8.0

Definition at line 1738 of file entropic.cpp.

entropic_free_logprob_result()

ENTROPIC_EXPORT void entropic_free_logprob_result

(

entropic_logprob_result_t *

result

)

Free internal arrays of a logprob result.

Frees the logprobs and tokens arrays, then NULLs the pointers to prevent double-free. The result struct itself is caller-owned and is NOT freed.

Parameters

result

Pointer to result struct. NULL-safe (no-op).

Version

1.9.10

Frees logprobs and tokens arrays, then NULLs the pointers to prevent double-free. The struct itself is caller-owned.

@utility

Version

1.9.10

Definition at line 3350 of file entropic.cpp.

entropic_get_default_compactor()

ENTROPIC_EXPORT entropic_error_t entropic_get_default_compactor	(	entropic_handle_t	handle,
		entropic_compactor_fn *	compactor,
		void **	user_data
	)

Get the built-in default compactor function pointer.

Useful for consumers that want to wrap the default behavior (e.g., add logging, metrics, or post-processing around it).

Parameters

handle	Engine handle.
compactor	Output: default compactor function pointer.
user_data	Output: user_data to pass to the default compactor.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE
• ENTROPIC_ERROR_INVALID_ARGUMENT (NULL compactor output)

@threadsafety Serialized per-handle.

Version

1.9.9

Parameters

handle	Engine handle returned by entropic_create.
compactor	Out-param: receives function pointer to current compactor.
user_data	Opaque pointer passed back to the callback.

Returns

ENTROPIC_OK on success.

Definition at line 123 of file entropic_compaction.cpp.

entropic_get_diagnostic_prompt()

ENTROPIC_EXPORT entropic_error_t entropic_get_diagnostic_prompt	(	entropic_handle_t	handle,
		char **	prompt_out
	)

Get the diagnostic prompt text for /diagnose command.

Returns the bundled diagnostic prompt that consumers inject as a user message to trigger model self-diagnosis. The prompt instructs the model to call entropic.diagnose and produce structured self-assessment.

Parameters

	handle	Engine handle.
[out]	prompt_out	Output: diagnostic prompt string. Caller must free with entropic_free().

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

Memory ownership

Caller must free returned string with entropic_free().

@threadsafety Serialized per-handle.

Version

1.9.12

Get the diagnostic prompt text for /diagnose command.

Parameters

handle	Engine handle returned by entropic_create.
prompt_out	Out-param: newly allocated JSON string (caller owns; free with entropic_free).

Returns

ENTROPIC_OK on success, error code on failure.

Definition at line 3464 of file entropic.cpp.

entropic_get_identity()

ENTROPIC_EXPORT entropic_error_t entropic_get_identity	(	entropic_handle_t	handle,
		char **	identity_json
	)

Get the current active identity as a JSON string.

Returns a JSON object with identity name, system prompt hash, allowed_tools list, and phase configuration.

Parameters

	handle	Engine handle.
[out]	identity_json	Output: JSON string. Caller must free with entropic_free().

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — identity_json is NULL.
• ENTROPIC_ERROR_IDENTITY_NOT_FOUND — no identity loaded.

@threadsafety Serialized per-handle.

Version

1.8.9

Memory ownership

Caller must free *identity_json with entropic_free().

Get the current active identity as a JSON string.

Parameters

handle	Engine handle returned by entropic_create.
identity_json	Out-param: newly allocated JSON string (caller owns; free with entropic_free).

Returns

ENTROPIC_OK on success, error otherwise.

Definition at line 68 of file entropic_identity.cpp.

entropic_get_identity_config()

ENTROPIC_EXPORT char * entropic_get_identity_config	(	entropic_handle_t	handle,
		const char *	name
	)

Get identity configuration as JSON by name.

Parameters

handle	Engine handle.
name	Identity name (null-terminated).

Returns

JSON string of identity config. Caller frees with entropic_free(). NULL if identity not found or handle is NULL.

@threadsafety Serialized per-handle.

Version

1.9.6

Memory ownership

Caller must free returned string with entropic_free().

Get identity configuration as JSON by name.

Returns

JSON string (caller frees), or NULL if not found.

Definition at line 3201 of file entropic.cpp.

entropic_get_logprobs()

ENTROPIC_EXPORT entropic_error_t entropic_get_logprobs	(	entropic_handle_t	handle,
		const char *	model_id,
		const int32_t *	tokens,
		int	n_tokens,
		entropic_logprob_result_t *	result
	)

Evaluate per-token log-probabilities for a token sequence.

Runs the token sequence through the model and returns the log-probability of each token given its preceding context. Evaluation-only — no sampling, no generation, no KV cache mutation visible to ongoing generation.

Parameters

handle	Engine handle.
model_id	Model identifier (tier name or model key).
tokens	Array of token IDs to evaluate.
n_tokens	Number of tokens (minimum 2).
result	Output: logprob result. Caller frees internal arrays with entropic_free_logprob_result().

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE
• ENTROPIC_ERROR_MODEL_NOT_FOUND (unknown model_id)
• ENTROPIC_ERROR_MODEL_NOT_ACTIVE (model not ACTIVE)
• ENTROPIC_ERROR_EVAL_CONTEXT_FULL (exceeds n_ctx)
• ENTROPIC_ERROR_INVALID_CONFIG (n_tokens < 2)
• ENTROPIC_ERROR_EVAL_FAILED (llama_decode error)

@threadsafety Serialized per-model via eval_mutex. Does not block generation on the same model.

Version

1.9.10

Resolves model_id as a tier name, retrieves the backend, and delegates to InferenceBackend::evaluate_logprobs(). The result arrays are engine-allocated — free with entropic_free_logprob_result().

Returns

ENTROPIC_OK on success, error code on failure.

Definition at line 3273 of file entropic.cpp.

entropic_grammar_deregister()

ENTROPIC_EXPORT entropic_error_t entropic_grammar_deregister	(	entropic_handle_t	handle,
		const char *	key
	)

Remove a grammar from the registry.

Parameters

handle	Engine handle.
key	Grammar name (null-terminated).

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — key is NULL.
• ENTROPIC_ERROR_GRAMMAR_NOT_FOUND — key not registered.

@threadsafety Serialized per-handle.

Version

1.9.3

Delegates to GrammarRegistry::deregister(). Bundled grammars can also be removed (allows overriding defaults).

Returns

ENTROPIC_OK on success, ENTROPIC_ERROR_GRAMMAR_NOT_FOUND if key not registered.

Definition at line 2660 of file entropic.cpp.

entropic_grammar_get()

ENTROPIC_EXPORT char * entropic_grammar_get	(	entropic_handle_t	handle,
		const char *	key
	)

Get grammar content by key.

Parameters

handle	Engine handle.
key	Grammar name (null-terminated).

Returns

GBNF content string. Caller frees with entropic_free(). NULL if key not found.

@threadsafety Serialized per-handle.

Version

1.9.3

Memory ownership

Caller must free returned string with entropic_free().

Get grammar content by key.

Returns the raw GBNF content string for the named grammar. Caller frees with entropic_free().

Returns

GBNF string (caller frees), or NULL if not found.

Definition at line 2690 of file entropic.cpp.

entropic_grammar_list()

ENTROPIC_EXPORT char * entropic_grammar_list

(

entropic_handle_t

handle

)

List all registered grammars as JSON array.

Parameters

handle

Engine handle.

Returns

JSON array of grammar metadata objects: [{"key":"compactor","source":"bundled","validated":true}, ...] Content strings are NOT included (use entropic_grammar_get). Caller frees with entropic_free().

@threadsafety Serialized per-handle.

Version

1.9.3

Memory ownership

Caller must free returned string with entropic_free().

List all registered grammars as JSON array.

Returns metadata for each grammar: key, source, validated flag, and error string. Content is omitted for efficiency. Caller frees with entropic_free().

Returns

JSON array string (caller frees), or NULL on error.

Definition at line 2740 of file entropic.cpp.

entropic_grammar_register()

ENTROPIC_EXPORT entropic_error_t entropic_grammar_register	(	entropic_handle_t	handle,
		const char *	key,
		const char *	gbnf_content
	)

Register a grammar by key from a GBNF content string.

Parameters

handle	Engine handle.
key	Unique grammar name (null-terminated).
gbnf_content	Raw GBNF grammar string (null-terminated).

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — key or gbnf_content is NULL.
• ENTROPIC_ERROR_INVALID_CONFIG — key already exists.

@threadsafety Serialized per-handle.

Version

1.9.3

Register a grammar by key from a GBNF content string.

Delegates to GrammarRegistry::register_grammar(). The grammar is validated on registration; invalid grammars are still stored with error metadata.

Returns

ENTROPIC_OK on success, ENTROPIC_ERROR_ALREADY_EXISTS if key already registered.

Definition at line 2594 of file entropic.cpp.

entropic_grammar_register_file()

ENTROPIC_EXPORT entropic_error_t entropic_grammar_register_file	(	entropic_handle_t	handle,
		const char *	key,
		const char *	path
	)

Register a grammar from a file path.

Parameters

handle	Engine handle.
key	Grammar name (if NULL, uses filename stem).
path	Path to .gbnf file (null-terminated).

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — path is NULL.
• ENTROPIC_ERROR_INVALID_CONFIG — key already exists.
• ENTROPIC_ERROR_LOAD_FAILED — file unreadable.

@threadsafety Serialized per-handle.

Version

1.9.3

Register a grammar from a file path.

Delegates to GrammarRegistry::register_from_file(). File is read, validated, and stored under the given key.

Returns

ENTROPIC_OK on success, ENTROPIC_ERROR_IO if file unreadable, ENTROPIC_ERROR_ALREADY_EXISTS if key exists.

Definition at line 2627 of file entropic.cpp.

entropic_grammar_validate()

ENTROPIC_EXPORT char * entropic_grammar_validate

(

const char *

gbnf_content

)

Validate a GBNF grammar string without registering.

Parameters

gbnf_content

Raw GBNF string to validate (null-terminated).

Returns

NULL on success (valid grammar). Error description string on failure. Caller frees with entropic_free().

Note

This is a static function — does not require an engine handle. Can be called before engine initialization.

@threadsafety Thread-safe.

Version

1.9.3

Memory ownership

Caller must free non-NULL returned string with entropic_free().

Stateless validation — does not require a handle or loaded model. Delegates to GrammarRegistry::validate().

Returns

NULL if valid; error description string (caller frees) if invalid. @utility

Version

2.0.2

Definition at line 2719 of file entropic.cpp.

entropic_grant_mcp_key()

ENTROPIC_EXPORT entropic_error_t entropic_grant_mcp_key	(	entropic_handle_t	handle,
		const char *	identity_name,
		const char *	pattern,
		entropic_mcp_access_level_t	level
	)

Grant an MCP tool key to an identity.

If the identity has no key set, one is created automatically (enabling enforcement).

Parameters

handle	Engine handle.
identity_name	Identity/tier name (null-terminated).
pattern	Tool pattern string (null-terminated).
level	Access level to grant.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — identity_name or pattern is NULL.

@threadsafety Serialized per-handle.

Version

1.9.4

Returns

ENTROPIC_OK on success.

Definition at line 2966 of file entropic.cpp.

entropic_grant_mcp_key_from()

ENTROPIC_EXPORT entropic_error_t entropic_grant_mcp_key_from	(	entropic_handle_t	handle,
		const char *	granter,
		const char *	grantee,
		const char *	pattern,
		entropic_mcp_access_level_t	level
	)

Grant a key from one identity to another.

The granter must possess the key at >= the granted level.

Parameters

handle	Engine handle.
granter	Granting identity (null-terminated).
grantee	Receiving identity (null-terminated).
pattern	Tool pattern to grant (null-terminated).
level	Access level to grant.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_IDENTITY_NOT_FOUND — either identity not registered.
• ENTROPIC_ERROR_PERMISSION_DENIED — granter lacks the key.

@threadsafety Serialized per-handle.

Version

1.9.4

Returns

ENTROPIC_OK on success.

Definition at line 3056 of file entropic.cpp.

entropic_identity_count()

ENTROPIC_EXPORT entropic_error_t entropic_identity_count	(	entropic_handle_t	handle,
		size_t *	total,
		size_t *	dynamic
	)

Get identity count.

Parameters

handle	Engine handle.
total	Output: total identity count (static + dynamic).
dynamic	Output: dynamic identity count only. Pass NULL to skip.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — total is NULL.

@threadsafety Thread-safe.

Version

1.9.6

Get identity count.

Returns

ENTROPIC_OK on success.

Definition at line 3246 of file entropic.cpp.

entropic_interrupt()

ENTROPIC_EXPORT entropic_error_t entropic_interrupt

(

entropic_handle_t

handle

)

Interrupt a running generation.

Signals the engine to abort the current entropic_run() or entropic_run_streaming() call. The interrupted call returns ENTROPIC_ERROR_INTERRUPTED. If nothing is running, returns ENTROPIC_ERROR_NOT_RUNNING.

Parameters

handle

Engine handle.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_NOT_RUNNING — nothing to interrupt.

@threadsafety Thread-safe. Designed for cross-thread cancellation.

Version

1.8.4

Interrupt a running generation.

Parameters

handle

Engine handle returned by entropic_create.

Returns

ENTROPIC_OK if interrupted.

Definition at line 2190 of file entropic.cpp.

entropic_list_identities()

ENTROPIC_EXPORT char * entropic_list_identities

(

entropic_handle_t

handle

)

List all identity names as JSON array.

Parameters

handle

Engine handle.

Returns

JSON array of identity name strings. Caller frees with entropic_free(). NULL on error.

@threadsafety Serialized per-handle.

Version

1.9.6

Memory ownership

Caller must free returned string with entropic_free().

Returns

JSON array string (caller frees), or NULL.

Definition at line 3227 of file entropic.cpp.

entropic_list_mcp_keys()

ENTROPIC_EXPORT char * entropic_list_mcp_keys	(	entropic_handle_t	handle,
		const char *	identity_name
	)

List all MCP keys for an identity as JSON.

Parameters

handle	Engine handle.
identity_name	Identity/tier name (null-terminated).

Returns

JSON array of key objects. Caller frees with entropic_free(). NULL if identity not found or error.

@threadsafety Serialized per-handle.

Version

1.9.4

Memory ownership

Caller must free returned string with entropic_free().

List all MCP keys for an identity as JSON.

Returns

JSON array string (caller frees), or NULL on error.

Definition at line 3027 of file entropic.cpp.

entropic_list_mcp_servers()

ENTROPIC_EXPORT char * entropic_list_mcp_servers

(

entropic_handle_t

handle

)

List all MCP servers with status information.

Returns both in-process and external servers.

Parameters

handle

Engine handle.

Returns

JSON string: {"servers":{"name":{...ServerInfo...},...}}. Caller must free with entropic_free(). NULL on error.

@threadsafety Serialized per-handle.

Version

1.8.7

Memory ownership

Caller must free returned string with entropic_free().

List all MCP servers with status information.

Parameters

handle

Engine handle returned by entropic_create.

Returns

JSON string (caller frees), or NULL.

Definition at line 166 of file entropic_mcp.cpp.

entropic_load_identity()

ENTROPIC_EXPORT entropic_error_t entropic_load_identity	(	entropic_handle_t	handle,
		const char *	identity_name
	)

Load an identity by name from the configuration.

Resolves the identity name against the loaded config, loads the identity's system prompt and tool filter, and sets it as the active identity for subsequent entropic_run() calls.

Parameters

handle	Engine handle.
identity_name	Null-terminated identity name (e.g., "eng", "lead").

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — identity_name is NULL.
• ENTROPIC_ERROR_IDENTITY_NOT_FOUND — name not in config.
• ENTROPIC_ERROR_INVALID_CONFIG — identity config malformed.

@threadsafety Serialized per-handle.

Version

1.8.9

Load an identity by name from the configuration.

Parameters

handle	Engine handle returned by entropic_create.
identity_name	Identity name from configured tier set.

Returns

ENTROPIC_OK if identity exists, error otherwise.

Definition at line 44 of file entropic_identity.cpp.

entropic_metrics_json()

ENTROPIC_EXPORT entropic_error_t entropic_metrics_json	(	entropic_handle_t	handle,
		char **	out
	)

Get loop metrics from the most recent run as JSON.

Populates *out with a malloc'd JSON string containing flat fields (iterations, tool_calls, tokens_used, errors, duration_ms) and a per_tier object keyed by tier name. Caller must entropic_free(*out).

Parameters

	handle	Engine handle.
[out]	out	Output: malloc'd JSON string. Caller frees via entropic_free().

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — out is NULL.

@threadsafety Thread-safe (read-only).

Version

2.0.6-rc16.2

Get loop metrics from the most recent run as JSON.

Reuses the state-provider sp_get_metrics builder so handle_status and the entropic.inspect tool return the same shape. (P2-15 follow-up, 2.0.6-rc16.2)

Parameters

	handle	Engine handle.
[out]	out	Output JSON; caller frees via entropic_free.

Returns

ENTROPIC_OK on success.

Definition at line 2369 of file entropic.cpp.

entropic_model_has_vision()

ENTROPIC_EXPORT int entropic_model_has_vision	(	entropic_handle_t	handle,
		const char *	model_id
	)

Check if a model has vision capability.

Returns 1 when the specified model has an mmproj loaded (vision encoder active). Returns 0 for text-only models or unknown model_id.

Parameters

handle	Engine handle.
model_id	Model identifier (tier name, e.g. "primary").

Returns

1 if vision-capable (mmproj loaded), 0 if text-only.

@threadsafety Serialized per-handle.

Version

1.9.11

Check if a model has vision capability.

Resolves model_id as a tier name, retrieves the backend, and queries BackendCapability::VISION. Returns 1 if the model has an mmproj loaded, 0 if text-only.

Returns

1 if vision-capable, 0 if text-only or error.

Definition at line 3374 of file entropic.cpp.

entropic_profile_deregister()

ENTROPIC_EXPORT entropic_error_t entropic_profile_deregister	(	entropic_handle_t	handle,
		const char *	name
	)

Remove a GPU resource profile.

Parameters

handle	Engine handle.
name	Profile name (null-terminated).

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_PROFILE_NOT_FOUND — name not registered.

@threadsafety Serialized per-handle.

Version

1.9.7

Remove a GPU resource profile.

Delegates to ProfileRegistry::deregister(). Bundled profiles can be removed.

Returns

ENTROPIC_OK on success, ENTROPIC_ERROR_PROFILE_NOT_FOUND if name not registered.

Definition at line 2816 of file entropic.cpp.

entropic_profile_get()

ENTROPIC_EXPORT char * entropic_profile_get	(	entropic_handle_t	handle,
		const char *	name
	)

Get a profile by name as JSON.

Parameters

handle	Engine handle.
name	Profile name (null-terminated).

Returns

JSON string of GPUResourceProfile fields. NULL if handle is NULL or name not found.

Memory ownership

Caller must free returned string with entropic_free().

@threadsafety Serialized per-handle.

Version

1.9.7

Get a profile by name as JSON.

Returns the profile as a JSON object with name, n_batch, n_threads, n_threads_batch, and description. Falls back to "balanced" if name not found (see ProfileRegistry::get). Caller frees with entropic_free().

Returns

JSON string (caller frees), or NULL on error.

Definition at line 2848 of file entropic.cpp.

entropic_profile_list()

ENTROPIC_EXPORT char * entropic_profile_list

(

entropic_handle_t

handle

)

List all registered profiles as JSON array.

Parameters

handle

Engine handle.

Returns

JSON array of profile objects. NULL if handle is NULL.

Memory ownership

Caller must free returned string with entropic_free().

@threadsafety Serialized per-handle.

Version

1.9.7

List all registered profiles as JSON array.

Returns a sorted JSON array of profile name strings. Caller frees with entropic_free().

Returns

JSON array string (caller frees), or NULL on error.

Definition at line 2882 of file entropic.cpp.

entropic_profile_register()

ENTROPIC_EXPORT entropic_error_t entropic_profile_register	(	entropic_handle_t	handle,
		const char *	profile_json
	)

Register a custom GPU resource profile.

Parameters

handle	Engine handle.
profile_json	JSON string: {"name":"...", "n_batch":N, "n_threads":N, "n_threads_batch":N, "description":"..."}. Only "name" is required; other fields default.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — profile_json is NULL.
• ENTROPIC_ERROR_ALREADY_EXISTS — name already registered.

@threadsafety Serialized per-handle.

Version

1.9.7

Register a custom GPU resource profile.

Parses the JSON string into a GPUResourceProfile and delegates to ProfileRegistry::register_profile(). Required JSON fields: "name". Optional: "n_batch", "n_threads", "n_threads_batch", "description".

Returns

ENTROPIC_OK on success, ENTROPIC_ERROR_ALREADY_EXISTS if name exists, ENTROPIC_ERROR_INVALID_ARGUMENT on parse error.

Definition at line 2776 of file entropic.cpp.

entropic_queue_user_message()

ENTROPIC_EXPORT entropic_error_t entropic_queue_user_message	(	entropic_handle_t	handle,
		const char *	message
	)

Queue a user message to be injected at the next top-level turn boundary.

The queued message is appended to a bounded FIFO inside the engine and consumed automatically when the current top-level turn reaches AgentState::COMPLETE — i.e. when the currently-running entropic_run / entropic_run_streaming / entropic_run_messages* call finishes its agent loop. The engine then immediately seeds a fresh turn with the dequeued message under the same per-call on_token wiring, so streaming consumers see a clean per-turn token stream without protocol changes.

The queue is NOT a cancellation primitive: it does not interrupt the in-flight turn. Consumers wanting to stop the current turn should use entropic_interrupt.

The queue drain triggers only at top-level COMPLETE. Delegation boundaries (parent loop resuming after a child loop returns) are NOT drain points — injecting a fresh user message there would corrupt the parent's reasoning context.

@threadsafety Thread-safe. Designed to be called from a different thread than the one running the agent loop.

Parameters

handle	Engine handle.
message	Null-terminated UTF-8 user input text.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — message is NULL.
• ENTROPIC_ERROR_INVALID_STATE — no run is currently in flight on this handle (just call entropic_run_streaming directly).
• ENTROPIC_ERROR_QUEUE_FULL — queue is at message_queue_capacity (default 8). Retry after a turn completes, or call entropic_clear_user_message_queue.

Version

2.1.10

Queue a user message to be injected at the next top-level turn boundary.

Pure passthrough to the engine's thread-safe queue primitive. Does NOT take api_mutex — entropic_run_streaming holds nothing while the agent loop is running, so this call must be lock-disjoint from the run path to avoid deadlock. The engine's per-queue mutex guarantees thread safety on the queue itself.

Definition at line 2211 of file entropic.cpp.

entropic_register_compactor()

ENTROPIC_EXPORT entropic_error_t entropic_register_compactor	(	entropic_handle_t	handle,
		const char *	identity,
		entropic_compactor_fn	compactor,
		void *	user_data
	)

Register a custom compactor for an identity.

Replaces the default compaction strategy for the specified identity. Pass identity="" to set a global fallback for all identities without a per-identity compactor.

Resolution order: per-identity -> global custom ("") -> built-in default. Only one compactor per identity. Re-registering replaces the previous.

Parameters

handle	Engine handle.
identity	Identity name, or "" for global fallback.
compactor	Compactor function pointer.
user_data	Opaque pointer passed to compactor on each call.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE
• ENTROPIC_ERROR_INVALID_CONFIG (NULL compactor)

@threadsafety Serialized per-handle.

Version

1.9.9

Parameters

handle	Engine handle returned by entropic_create.
identity	Identity name from configured tier set.
compactor	Function pointer to consumer-supplied compactor.
user_data	Opaque pointer passed back to the callback.

Returns

ENTROPIC_OK on success.

Definition at line 72 of file entropic_compaction.cpp.

entropic_register_hook()

ENTROPIC_EXPORT entropic_error_t entropic_register_hook	(	entropic_handle_t	handle,
		entropic_hook_point_t	hook_point,
		entropic_hook_callback_t	callback,
		void *	user_data,
		int	priority
	)

Register a callback for an engine hook point.

Multiple callbacks can be registered for the same hook point. They execute in ascending priority order (0 = highest priority). A pre-hook returning non-zero cancels the operation. A pre-hook returning modified JSON (via context_json out-param) modifies the operation's input.

Parameters

handle	Engine handle.
hook_point	The hook point to register for.
callback	Function pointer invoked when the hook fires.
user_data	Opaque pointer passed to callback.
priority	Execution priority (0 = first, higher = later).

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — callback is NULL.
• ENTROPIC_ERROR_INVALID_CONFIG — invalid hook_point value.

@threadsafety Serialized per-handle.

Version

1.9.1

Register a callback for an engine hook point.

Returns

ENTROPIC_OK on success.

Definition at line 42 of file entropic_hooks.cpp.

entropic_register_mcp_server()

ENTROPIC_EXPORT entropic_error_t entropic_register_mcp_server	(	entropic_handle_t	handle,
		const char *	name,
		const char *	config_json
	)

Register an external MCP server at runtime.

Connects to the server immediately. For stdio: spawns child process. For SSE: connects to HTTP endpoint.

Parameters

handle	Engine handle.
name	Unique server name (null-terminated).
config_json	JSON configuration: Stdio: {"command":"...","args":[...],"env":{...}} SSE: {"url":"http://..."}

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — name or config_json is NULL.
• ENTROPIC_ERROR_SERVER_ALREADY_EXISTS — name already registered.
• ENTROPIC_ERROR_CONNECTION_FAILED — transport connect failed.

@threadsafety Serialized per-handle.

Version

1.8.7

Register an external MCP server at runtime.

Definition at line 105 of file entropic_mcp.cpp.

entropic_residency_snapshot()

ENTROPIC_EXPORT entropic_error_t entropic_residency_snapshot	(	entropic_handle_t	handle,
		char **	out_json
	)

Snapshot of the engine's current VRAM residency set.

Returns a JSON object describing every tier-backing model currently resident in VRAM, the engine's VRAM budget, and per-model footprint accounting. Suitable for consumer Models-tab "what is loaded right now" widgets.

JSON shape:

{
  "vram_total_bytes":     17179869184,
  "vram_headroom_bytes":   2147483648,
  "vram_budget_bytes":    17179869184,
  "backend":              "cuda",
  "residency": [
    {
      "tier":              "lead_explorer",
      "model_path":        "/.../qwen3_6_a3b.gguf",
      "footprint_bytes":   14000000000,
      "weights_bytes":     13100000000,
      "kv_cache_bytes":      450000000,
      "headroom_bytes":      450000000,
      "last_activation_ms": 12345
    }
  ]
}

last_activation_ms is monotonic milliseconds since engine start at the most recent activation of that tier (lower = older = first LRU eviction candidate). When VRAM capacity is unknown (non-CUDA build, detection failed), vram_total_bytes is 0 and backend is "unknown"; the residency array is still populated.

Parameters

	handle	Engine handle.
[out]	out_json	Heap-allocated NUL-terminated JSON string. Caller frees with entropic_free_string.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle/out_json is NULL.
• ENTROPIC_ERROR_INVALID_STATE — engine not configured.
• ENTROPIC_ERROR_OUT_OF_MEMORY — allocation failed.

Version

2.2.4

Snapshot of the engine's current VRAM residency set.

Delegates to ModelOrchestrator::residency_snapshot_json which holds the swap mutex briefly for a consistent read of the loaded tier set and footprint accounting. The returned string is heap-allocated and must be freed by the caller with entropic_free_string.

Definition at line 3592 of file entropic.cpp.

entropic_revoke_mcp_key()

ENTROPIC_EXPORT entropic_error_t entropic_revoke_mcp_key	(	entropic_handle_t	handle,
		const char *	identity_name,
		const char *	pattern
	)

Revoke an MCP tool key from an identity.

Parameters

handle	Engine handle.
identity_name	Identity/tier name (null-terminated).
pattern	Tool pattern string (null-terminated).

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — identity_name or pattern is NULL.
• ENTROPIC_ERROR_IDENTITY_NOT_FOUND — identity not registered.

@threadsafety Serialized per-handle.

Version

1.9.4

Returns

ENTROPIC_OK on success.

Definition at line 2987 of file entropic.cpp.

entropic_run()

ENTROPIC_EXPORT entropic_error_t entropic_run	(	entropic_handle_t	handle,
		const char *	input,
		char **	result_json
	)

Synchronous agentic loop.

Runs the full agentic loop: generate, parse tool calls, execute tools, re-generate until complete. Blocks until the loop finishes or is interrupted via entropic_interrupt().

Parameters

	handle	Engine handle.
	input	User message (null-terminated).
[out]	result_json	JSON result string. Caller must free with entropic_free().

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_STATE — engine not configured.
• ENTROPIC_ERROR_GENERATE_FAILED — inference error.
• ENTROPIC_ERROR_ALREADY_RUNNING — another run in progress.
• ENTROPIC_ERROR_INTERRUPTED — cancelled via entropic_interrupt().

@threadsafety Serialized per-handle.

Version

1.8.4

Memory ownership

Caller must free *result_json with entropic_free().

Synchronous agentic loop.

Appends the user input to the conversation, runs the engine loop synchronously to completion (or interrupt/error), and returns the serialized result.

Parameters

handle	Engine handle returned by entropic_create.
input	Null-terminated user input string.
result_json	Out-parameter receiving a newly allocated JSON result string (caller owns, free with entropic_free).

Returns

ENTROPIC_OK on success, error code otherwise. @req REQ-API-002

Version

2.0.6-rc16.2

Definition at line 1758 of file entropic.cpp.

entropic_run_messages()

ENTROPIC_EXPORT entropic_error_t entropic_run_messages	(	entropic_handle_t	handle,
		const char *	messages_json,
		char **	result_json
	)

Multimodal-aware agentic run with messages-array input (gh#37).

Identical contract to entropic_run() except the input is a JSON array of message objects (OpenAI-compatible content arrays). Each message may carry content as a string OR as an array of content parts ({"type":"text","text":...} or {"type":"image","path":...,"url":...}). Image content parts survive end-to-end into the inference backend.

The existing entropic_run() entry point is preserved unchanged for back-compat; consumers that don't need multimodal input keep using it (no JSON serialize/parse on their fast path).

Routing: when any message carries an image part, the orchestrator routes to a tier whose capabilities includes vision. If no such tier is configured, ENTROPIC_ERROR_NO_VISION_TIER is returned with diagnostics identifying the active tier and any vision-capable tiers (if any).

Parameters

handle	Engine handle.
messages_json	JSON array of message objects (UTF-8, null-terminated).
result_json	Out-param: newly allocated JSON result string. Caller frees with entropic_free().

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — messages_json / result_json is NULL or malformed.
• ENTROPIC_ERROR_INVALID_STATE — engine not configured.
• ENTROPIC_ERROR_NO_VISION_TIER — image content but no vision-capable tier configured (gh#41).
• ENTROPIC_ERROR_GENERATE_FAILED — inference error.

@threadsafety Serialized per-handle.

Version

2.1.8

Multimodal-aware agentic run with messages-array input (gh#37).

Front-line argument validation, then dispatches to run_messages_inner() under a try/catch that maps unexpected exceptions to ENTROPIC_ERROR_GENERATE_FAILED. See the public declaration in entropic.h for the full error matrix.

Parameters

handle	Engine handle.
messages_json	JSON array of message objects.
result_json	Out-param: malloc'd JSON result. Caller frees.

Returns

ENTROPIC_OK or one of the documented error codes.

Definition at line 1924 of file entropic.cpp.

entropic_run_messages_streaming()

ENTROPIC_EXPORT entropic_error_t entropic_run_messages_streaming	(	entropic_handle_t	handle,
		const char *	messages_json,
		void(*)(const char *token, size_t len, void *user_data)	on_token,
		void *	user_data,
		int *	cancel_flag
	)

Streaming variant of entropic_run_messages (gh#37).

Same multimodal input contract as entropic_run_messages, with per-token streaming through on_token. The first token may be delayed by vision-encoder latency when image content is present.

Parameters

handle	Engine handle.
messages_json	JSON array of message objects.
on_token	Per-token callback. Must not call back into API.
user_data	Forwarded to on_token.
cancel_flag	Optional int* set to non-zero to cancel.

Returns

ENTROPIC_OK on success. See entropic_run_messages() for error codes.

@threadsafety Serialized per-handle.

Version

2.1.8

Streaming variant of entropic_run_messages (gh#37).

Streaming sibling of entropic_run_messages. Same validation

• try/catch shape; dispatches to run_messages_stream_inner() under a try/catch. The first token may be delayed by vision-encoder latency when image content is present.

Parameters

handle	Engine handle.
messages_json	JSON array of message objects.
on_token	Per-token callback (UTF-8 filtered).
user_data	Forwarded to on_token.
cancel_flag	Optional int*; non-zero cancels.

Returns

ENTROPIC_OK or one of the documented error codes.

Definition at line 1987 of file entropic.cpp.

entropic_run_streaming()

ENTROPIC_EXPORT entropic_error_t entropic_run_streaming	(	entropic_handle_t	handle,
		const char *	input,
		void(*)(const char *token, size_t len, void *user_data)	on_token,
		void *	user_data,
		int *	cancel_flag
	)

Streaming agentic loop with token callback.

Same as entropic_run() but invokes on_token for each generated token. The token pointer is valid only for the callback duration — copy if retention is needed.

Parameters

handle	Engine handle.
input	User message (null-terminated).
on_token	Called for each generated token. Must not call back into the entropic API (deadlock risk).
user_data	Forwarded to on_token.
cancel_flag	Pointer to int. Set to non-zero to cancel. May be NULL.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_STATE — engine not configured.
• ENTROPIC_ERROR_GENERATE_FAILED — inference error.
• ENTROPIC_ERROR_ALREADY_RUNNING — another run in progress.
• ENTROPIC_ERROR_CANCELLED — cancelled via cancel_flag.
• ENTROPIC_ERROR_INTERRUPTED — cancelled via entropic_interrupt().

@threadsafety Serialized per-handle.

Version

1.8.4

Streaming agentic loop with token callback.

Parameters

handle	Engine handle returned by entropic_create.
input	User message to generate a response for.
on_token	Callback invoked for each generated token.
user_data	Opaque pointer passed back to the callback.
cancel_flag	Optional pointer; set *cancel_flag to non-zero from another thread to stop generation.

Returns

ENTROPIC_OK on success.

Definition at line 1813 of file entropic.cpp.

entropic_seconds_since_last_activity()

ENTROPIC_EXPORT int64_t entropic_seconds_since_last_activity

(

entropic_handle_t

handle

)

Seconds since the engine last serviced a run (gh#35, v2.3.0).

Returns the wall-clock seconds delta between now and the entry time of the most recent entropic_run* call on this handle. Returns 0 when no run has ever happened on this handle (no activity to be idle relative to).

Intended for host-side idle-exit policies: a headless entropic serve or sassafras-class consumer process can poll this at its own cadence and call entropic_destroy once the engine has been idle for longer than the host's configured threshold. The engine itself does NOT auto-exit — that's a host policy decision.

Parameters

handle

Engine handle. May be NULL.

Returns

Seconds idle, or 0 if handle is NULL / no activity yet.

@threadsafety Thread-safe.

Version

2.3.0

Seconds since the engine last serviced a run (gh#35, v2.3.0).

@utility

Version

2.3.0

Definition at line 1716 of file entropic.cpp.

entropic_serialize_mcp_keys()

ENTROPIC_EXPORT char * entropic_serialize_mcp_keys

(

entropic_handle_t

handle

)

Serialize all identity key sets to JSON.

Parameters

handle

Engine handle.

Returns

JSON object string. Caller frees with entropic_free().

@threadsafety Serialized per-handle.

Version

1.9.4

Memory ownership

Caller must free returned string with entropic_free().

Returns

JSON string (caller frees), or NULL on error.

Definition at line 3078 of file entropic.cpp.

entropic_set_attempt_boundary_cb()

ENTROPIC_EXPORT entropic_error_t entropic_set_attempt_boundary_cb	(	entropic_handle_t	handle,
		ent_validation_attempt_boundary_cb	cb,
		void *	user_data
	)

Register an attempt-boundary callback for the validator.

Fires once per revision pass with the upcoming attempt number. Pass NULL to clear. The callback runs on the engine's generation thread — keep it short and non-blocking.

Parameters

handle	Engine handle.
cb	Attempt-boundary callback (NULL to clear).
user_data	Pointer forwarded to cb.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

@threadsafety Serialized per-handle.

Version

2.1.5

Register an attempt-boundary callback for the validator.

Definition at line 2079 of file entropic.cpp.

entropic_set_critique_callbacks()

ENTROPIC_EXPORT entropic_error_t entropic_set_critique_callbacks	(	entropic_handle_t	handle,
		void(*)(void *user_data)	start_cb,
		void(*)(void *user_data)	end_cb,
		void *	user_data
	)

Register start/end callbacks for constitutional critique generation (gh#50, v2.1.12).

The constitutional validator's critique pass typically runs for 20-30 seconds while AgentState stays parked at EXECUTING (no transition signals it). Consumers that want a "validating response…" UI indicator can register these callbacks to bracket that window precisely.

start_cb fires immediately before the synchronous inference_->generate() call inside run_critique(); end_cb fires immediately after it returns (regardless of success or failure). Both fire even when the critique pass produces no violations.

The slot is independent of the legacy EngineCallbacks struct — it survives entropic_run_streaming's internal callback shuffle and any entropic_configure* reconstruction (the handle owns the authoritative slot and re-applies it to each newly-built validator). Pass NULL for either callback to opt out of just that edge; pass NULL for both to clear the slot.

Parameters

handle	Engine handle.
start_cb	Pre-critique callback (NULL to disable).
end_cb	Post-critique callback (NULL to disable).
user_data	Forwarded to both callbacks verbatim.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

@threadsafety Thread-safe. Callbacks may be reassigned at any time; the validator snapshots the slot under a mutex before each fire so an in-flight critique cannot tear a partial reassignment.

Version

2.1.12

Register start/end callbacks for constitutional critique generation (gh#50, v2.1.12).

Saves the callback pair on the handle (the authoritative slot) and re-applies to the current ConstitutionalValidator if one is already constructed. Subsequent entropic_configure* calls rebuild the validator; the rewire_critique_callbacks helper re-applies this slot from the handle automatically.

Parameters

handle	Engine handle.
start_cb	Pre-critique callback (NULL to disable).
end_cb	Post-critique callback (NULL to disable).
user_data	Forwarded to both callbacks.

Returns

ENTROPIC_OK on success.

Definition at line 2166 of file entropic.cpp.

entropic_set_delegation_callbacks()

ENTROPIC_EXPORT entropic_error_t entropic_set_delegation_callbacks	(	entropic_handle_t	handle,
		ent_delegation_start_cb	on_start,
		ent_delegation_complete_cb	on_complete,
		void *	user_data
	)

Register start/complete callbacks for delegations.

Both callbacks are optional. Passing NULL for either clears that slot. A typical consumer registers on_complete to receive patches and (optionally) on_start to gate or audit delegations before they run.

Replaces the pre-2.1.5 silent auto-merge-to-develop behavior that caused gh#29 (engine corrupting the user's repo state). The engine never writes to the user's project directory; the consumer applies patches with user consent.

Parameters

handle	Engine handle.
on_start	Pre-delegation gate callback (NULL to clear).
on_complete	Post-delegation result callback (NULL to clear).
user_data	Pointer forwarded to both callbacks.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

@threadsafety Serialized per-handle. Callbacks may fire from the engine thread or a child-loop delegation thread.

Version

2.1.5

Register start/complete callbacks for delegations.

Parameters

handle	Engine handle.
on_start	Pre-delegation gate (nullable clears).
on_complete	Post-delegation result (nullable clears).
user_data	Forwarded to both callbacks.

Returns

ENTROPIC_OK on success.

Definition at line 2100 of file entropic.cpp.

entropic_set_queue_observer()

ENTROPIC_EXPORT entropic_error_t entropic_set_queue_observer	(	entropic_handle_t	handle,
		void(*)(const char *consumed, size_t remaining, void *user_data)	observer,
		void *	user_data
	)

Register an observer for queue-consumption events.

Fires immediately before the engine seeds the next turn with a popped queued message. Lets consumer UIs clear the "queued" badge for the corresponding scrollback item.

The consumed buffer is valid only for the callback's duration — copy it if the consumer needs to hold it. remaining reflects the queue depth after the pop (i.e. messages still waiting).

Pass observer=NULL to clear.

@threadsafety Callback fires from the engine thread between turns. Must be thread-safe.

Parameters

handle	Engine handle.
observer	Callback (consumed_text, remaining_depth, user_data).
user_data	Forwarded to observer.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

Version

2.1.10

entropic_set_residency_observer()

ENTROPIC_EXPORT entropic_error_t entropic_set_residency_observer	(	entropic_handle_t	handle,
		entropic_residency_observer_t	observer,
		void *	user_data
	)

Register a residency observer on a handle.

Only one observer per handle. Passing observer=NULL clears it. Surface for consumer UIs (Models tabs, dashboards) to track which tier models are currently in VRAM without polling entropic_residency_snapshot.

Parameters

handle	Engine handle.
observer	Callback, or NULL to clear.
user_data	Forwarded to observer.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

Version

2.2.4

Register a residency observer on a handle.

Stores the C callback + user_data on the handle and bridges to the orchestrator's std::function slot via a small capture lambda. The orchestrator fires the lambda synchronously on each load / evict / activation_swap transition; the lambda forwards to the C callback with the residency-event enum, tier name, model path, and footprint.

Definition at line 3550 of file entropic.cpp.

entropic_set_state_observer()

ENTROPIC_EXPORT entropic_error_t entropic_set_state_observer	(	entropic_handle_t	handle,
		void(*)(int state, void *user_data)	observer,
		void *	user_data
	)

Register an engine state-change observer.

Fires on every AgentState transition. State integers map 1:1 to entropic_agent_state_t. Used by async subscribers (e.g. the external MCP bridge) to project engine-side phases — PLANNING, EXECUTING, WAITING_TOOL, VERIFYING, DELEGATING — onto user-visible task status. Pass observer=NULL to clear.

@threadsafety Callback may fire from the engine thread or a child-loop delegation thread. Must be thread-safe.

Parameters

handle	Engine handle.
observer	State-change callback (state_int, user_data).
user_data	Forwarded to observer.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

Version

2.0.6-rc16.2

Register an engine state-change observer.

v2.1.10 (gh#40 fallout): routes through the engine's persistent state_observer slot rather than the legacy EngineCallbacks.on_state_change. The legacy path is wiped by run_streaming's set_callbacks() shuffle, which silently broke the documented external-MCP-bridge use case for streaming runs.

Parameters

handle	Engine handle.
observer	State observer (NULL to clear).
user_data	Forwarded to observer.

Returns

ENTROPIC_OK on success.

Definition at line 2129 of file entropic.cpp.

entropic_set_stream_observer()

ENTROPIC_EXPORT entropic_error_t entropic_set_stream_observer	(	entropic_handle_t	handle,
		void(*)(const char *token, size_t len, void *user_data)	observer,
		void *	user_data
	)

Set a global stream observer callback.

Fires for every token generated from every entry point — interactive entropic_run_streaming(), non-streaming entropic_run(), and delegate child-loop generations. Runs alongside any per-call on_token callback registered via entropic_run_streaming(). Registration before entropic_configure() is allowed — the observer is wired to the engine when it is constructed.

At the end of any entropic_run() or entropic_run_streaming() call, the observer is invoked once with (token="", len=0) as a synthetic completion sentinel so consumers can detect end-of-turn regardless of the entry point.

Use case: TUI consumers register this once to observe activity from both interactive input and external MCP bridge requests.

@threadsafety The observer may be invoked from the engine thread servicing the current run (serialized per-handle) and from the external-bridge worker thread that drives async MCP ask tasks. Consumer callbacks must be thread-safe.

Parameters

handle	Engine handle.
observer	Token callback (same signature as on_token). NULL to clear.
user_data	Forwarded to observer.

Returns

ENTROPIC_OK on success.

Version

2.0.6-rc16

Parameters

handle	Engine handle.
observer	Token callback (NULL to clear).
user_data	Forwarded to observer.

Returns

ENTROPIC_OK on success.

Definition at line 2017 of file entropic.cpp.

entropic_speculative_compat()

ENTROPIC_EXPORT entropic_error_t entropic_speculative_compat	(	entropic_handle_t	handle,
		int *	compatible,
		char **	diagnostic
	)

Query whether the configured target/draft pair is compatible for speculative decoding.

Inspects the active main tier (verifier) and the configured draft model (inference.speculative.draft_model) for:

• target architecture is NOT recurrent (Mamba/RWKV/hybrid)
• matching tokenizer vocab type, BOS/EOS, vocab size
• prefix-equal token texts in the overlap range

No model state is allocated for the query — purely metadata-level inspection on the already-loaded models. The check is exposed as a separate entrypoint (rather than only at generate time) so consumers can validate a planned pairing during configuration and surface a clear diagnostic before kicking off a turn.

Parameters

	handle	Engine handle.
[out]	compatible	1 if the pair is compatible, 0 otherwise. Required (must be non-NULL).
[out]	diagnostic	On *compatible == 0, a heap-allocated NUL-terminated string identifying the failed rule. On compatible pairs, set to NULL. Caller frees with entropic_free_string. May be NULL if the caller does not want the diagnostic text.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle/compatible is NULL.
• ENTROPIC_ERROR_INVALID_STATE — engine not configured.

Version

2.1.11

Query whether the configured target/draft pair is compatible for speculative decoding.

Delegates to ModelOrchestrator::check_speculative_compat(). The orchestrator owns both sides of the pairing (active main tier as target, "draft" role on the secondary loader as draft) and runs the architecture + tokenizer rules from entropic::speculative::check_compat.

Parameters

handle	Engine handle.
compatible	Required out-param: 1 when compatible.
diagnostic	Optional out-param: heap-allocated diagnostic string on incompatibility (NULL on compatible pair). Caller frees with entropic_free_string.

Returns

ENTROPIC_OK / ENTROPIC_ERROR_INVALID_HANDLE / ENTROPIC_ERROR_INVALID_STATE.

Definition at line 3516 of file entropic.cpp.

entropic_storage_close()

ENTROPIC_EXPORT entropic_error_t entropic_storage_close

(

entropic_handle_t

handle

)

Close the storage backend and flush pending writes.

No-op if storage was never opened.

Parameters

handle

Engine handle.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

@threadsafety Serialized per-handle.

Version

1.8.8

Close the storage backend and flush pending writes.

Parameters

handle

Engine handle returned by entropic_create.

Returns

ENTROPIC_OK (no-op if storage not opened).

Definition at line 63 of file entropic_storage.cpp.

entropic_storage_open()

ENTROPIC_EXPORT entropic_error_t entropic_storage_open	(	entropic_handle_t	handle,
		const char *	db_path
	)

Open or create a SQLite storage backend.

Initializes persistent storage for conversations, delegations, and session logs. The database file is created if it does not exist. Storage is optional — the engine operates in-memory without it.

Parameters

handle	Engine handle.
db_path	Path to SQLite database file.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — db_path is NULL.
• ENTROPIC_ERROR_STORAGE_FAILED — database open/init failed.

@threadsafety Serialized per-handle.

Version

1.8.8

Parameters

handle	Engine handle returned by entropic_create.
db_path	Filesystem path to the SQLite database file.

Returns

ENTROPIC_OK on success.

Definition at line 30 of file entropic_storage.cpp.

entropic_throughput_reset()

ENTROPIC_EXPORT void entropic_throughput_reset	(	entropic_handle_t	handle,
		const char *	model_path
	)

Reset throughput tracking data for a model.

Parameters

handle	Engine handle.
model_path	Model path. NULL = reset all models.

@threadsafety Serialized per-handle.

Version

1.9.7

Reset throughput tracking data for a model.

Clears all recorded samples. model_path is accepted for API compatibility but the orchestrator tracks a single global throughput.

Parameters

handle	Engine handle returned by entropic_create.
model_path	Path or registry key identifying the model whose throughput should be reset.

Definition at line 2940 of file entropic.cpp.

entropic_throughput_tok_per_sec()

ENTROPIC_EXPORT double entropic_throughput_tok_per_sec	(	entropic_handle_t	handle,
		const char *	model_path
	)

Get current throughput estimate for a model.

Parameters

handle	Engine handle.
model_path	Path to the model (same key as ModelConfig.path).

Returns

Tokens per second (EWMA). 0.0 if no data or handle is NULL.

@threadsafety Serialized per-handle.

Version

1.9.7

Get current throughput estimate for a model.

Delegates to ThroughputTracker::tok_per_sec(). Returns the smoothed estimate from recent generations. model_path is accepted for API compatibility but the orchestrator tracks a single global throughput (one tracker, not per-model).

Returns

Tokens per second estimate, or 0.0 on error/no data.

Definition at line 2912 of file entropic.cpp.

entropic_update_identity()

ENTROPIC_EXPORT entropic_error_t entropic_update_identity	(	entropic_handle_t	handle,
		const char *	name,
		const char *	config_json
	)

Update a dynamic identity.

Parameters

handle	Engine handle.
name	Identity name (null-terminated).
config_json	Full replacement config as JSON string.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — name or config_json is NULL.
• ENTROPIC_ERROR_IDENTITY_NOT_FOUND — identity doesn't exist.
• ENTROPIC_ERROR_PERMISSION_DENIED — identity is static.
• ENTROPIC_ERROR_INVALID_CONFIG — validation failed.

@threadsafety Serialized per-handle.

Version

1.9.6

Update a dynamic identity.

Returns

ENTROPIC_OK on success.

Definition at line 3151 of file entropic.cpp.

entropic_user_message_queue_depth()

ENTROPIC_EXPORT entropic_error_t entropic_user_message_queue_depth	(	entropic_handle_t	handle,
		size_t *	count
	)

Query the current depth of the mid-gen user-message queue.

Snapshot value — may be stale by the time the caller reads it if the engine consumes a message concurrently. Intended for consumer UI feedback ("3 queued"), not for synchronization.

@threadsafety Thread-safe.

Parameters

handle	Engine handle.
count	Out-param: receives the queue depth.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — count is NULL.

Version

2.1.10

Query the current depth of the mid-gen user-message queue.

Definition at line 2231 of file entropic.cpp.

entropic_validation_accept_last()

ENTROPIC_EXPORT entropic_error_t entropic_validation_accept_last

(

entropic_handle_t

handle

)

Finalize the last attempt as the turn's response.

Used after entropic_validation_set_auto_retry(handle, false) has paused the engine on a critique rejection: instructs the engine to keep the rejected attempt as-is (i.e. the user overrode the validator). Clears the paused validation state and updates the last validation result to verdict passed_consumer_override.

Parameters

handle

Engine handle.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_STATE — no paused validation.

@threadsafety Serialized per-handle.

Version

2.1.5

Finalize the last attempt as the turn's response.

Definition at line 2066 of file entropic.cpp.

entropic_validation_last_result()

ENTROPIC_EXPORT char * entropic_validation_last_result

(

entropic_handle_t

handle

)

Get the last validation result as JSON.

Parameters

handle

Engine handle.

Returns

JSON string with validation metadata from the last generation. NULL if no validation has run. Caller frees with entropic_free().

Return format: {"was_revised": false, "revision_count": 0, "compliant": true, "violations": [], "tier": "eng"}

Memory ownership

Caller must free returned string with entropic_free().

@threadsafety Serialized per-handle.

Version

1.9.8

Get the last validation result as JSON.

Returns

JSON string (caller frees), or NULL if no result.

Definition at line 3440 of file entropic.cpp.

entropic_validation_resume_retry()

ENTROPIC_EXPORT entropic_error_t entropic_validation_resume_retry

(

entropic_handle_t

handle

)

Opt the engine into running the constitutional revision pass.

Resumes auto-revision for the currently paused validation state (set by the most recent entropic_run() when auto-retry was disabled and a critique failed). Runs synchronously and updates the conversation with the revised content. If no validation is paused this is a no-op.

Parameters

handle

Engine handle.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_STATE — no paused validation.

@threadsafety Serialized per-handle.

Version

2.1.5

Opt the engine into running the constitutional revision pass.

Definition at line 2053 of file entropic.cpp.

entropic_validation_set_auto_retry()

ENTROPIC_EXPORT entropic_error_t entropic_validation_set_auto_retry	(	entropic_handle_t	handle,
		int	enabled
	)

Toggle automatic constitutional revision after rejection.

When enabled is true (the default), the engine immediately injects critique feedback into the conversation and re-streams attempt N+1 after each failing constitutional pass. When enabled is false, the engine instead stops after the first failing critique and surfaces the rejection through entropic_validation_last_result() with verdict paused_pending_consumer. The consumer is then expected to call either entropic_validation_resume_retry() (opt into revision) or entropic_validation_accept_last() (treat the rejected attempt as the final answer).

Parameters

handle	Engine handle.
enabled	True to restore default auto-revision (the pre-2.1.5 behavior); false to disable it.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

@threadsafety Thread-safe.

Version

2.1.5

Toggle automatic constitutional revision after rejection.

Definition at line 2039 of file entropic.cpp.

entropic_validation_set_enabled()

ENTROPIC_EXPORT entropic_error_t entropic_validation_set_enabled	(	entropic_handle_t	handle,
		bool	enabled
	)

Enable or disable constitutional validation.

When disabled, the POST_GENERATE hook is deregistered (zero overhead). When re-enabled, it is re-registered.

Parameters

handle	Engine handle.
enabled	true to enable, false to disable.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.

@threadsafety Serialized per-handle.

Version

1.9.8

Enable or disable constitutional validation.

Returns

ENTROPIC_OK on success.

Definition at line 3402 of file entropic.cpp.

entropic_validation_set_identity()

ENTROPIC_EXPORT entropic_error_t entropic_validation_set_identity	(	entropic_handle_t	handle,
		const char *	identity_name,
		bool	enabled
	)

Set per-identity validation override.

Parameters

handle	Engine handle.
identity_name	Identity name (null-terminated).
enabled	true to enable, false to disable for this identity.

Returns

ENTROPIC_OK on success.

• ENTROPIC_ERROR_INVALID_HANDLE — handle is NULL.
• ENTROPIC_ERROR_INVALID_ARGUMENT — identity_name is NULL.

@threadsafety Serialized per-handle.

Version

1.9.8

Returns

ENTROPIC_OK on success.

Definition at line 3419 of file entropic.cpp.

entropic_version()

ENTROPIC_EXPORT const char * entropic_version

(

void

)

Get the library version string.

Returns the full semver string (e.g., "1.8.9"). The pointer has static lifetime — valid for the entire process.

Returns

Static null-terminated version string. Never NULL. Do NOT free.

@threadsafety Thread-safe.

Version

1.8.0

Returns

Static version string. @utility

Version

1.8.0

Definition at line 1697 of file entropic.cpp.