entropic.cpp File Reference

librentropic facade — C API implementation. More...

#include "engine_handle.h"
#include <entropic/config/loader.h>
#include <entropic/mcp/servers/entropic_server.h>
#include <entropic/entropic.h>
#include <entropic/prompts/manager.h>
#include <entropic/types/logging.h>
#include "llama_cpp_backend.h"
#include <entropic/inference/interface_factory.h>
#include <entropic/inference/orchestrator.h>
#include <entropic/interfaces/i_inference_backend.h>
#include <entropic/types/messages_json.h>
#include "json_serializers.h"
#include "utf8_safe.h"
#include "../inference/tool_call_serialize.h"
#include <nlohmann/json.hpp>
#include <atomic>
#include <cstdlib>
#include <fstream>
#include <vector>
#include <cstring>
#include <filesystem>
#include <new>
#include <stdexcept>
#include <string>

Include dependency graph for entropic.cpp:

Go to the source code of this file.

Functions
template<typename Fn >
static entropic_error_t	c_api_try (entropic_handle_t handle, Fn &&fn)
	Run a C-API entry-point body inside an exception barrier.
static char *	alloc_cstr (const char *src)
	Allocate a C string copy via the engine allocator.
static char *	alloc_cstr (const std::string &src)
	Allocate a C string copy from std::string.
const char *	entropic_last_error (entropic_handle_t handle)
	Read the per-handle last_error under api_mutex.
static entropic_error_t	check_orchestrator (entropic_handle_t h)
	Check handle prerequisites for orchestrator APIs.
static entropic_error_t	check_mcp_auth (entropic_handle_t h)
	Check handle prerequisites for MCP auth APIs.
static entropic_error_t	check_identity (entropic_handle_t h)
	Check handle prerequisites for identity manager APIs.
static entropic::InferenceBackend *	require_active_backend (entropic_handle_t h, const char *tier_name)
	Resolve tier name to an ACTIVE backend, or throw.
entropic_error_t	entropic_create (entropic_handle_t *handle)
	Create a new engine instance.
static std::vector< std::string >	resolve_allowed_tools (entropic_engine *h, const std::string &tier)
	Post-parse config setup: load bundled models, set configured.
static std::vector< std::string >	filter_tools (const nlohmann::json &all_tools, const std::vector< std::string > &allowed)
	Filter tool definitions by allowed list.
static int	facade_get_tool_prompt (const char *tier, char **result, void *user_data)
	Build formatted tool prompt for a tier.
static void	wire_external_interrupt (entropic_handle_t h)
	Wire engine interrupt propagation into MCP transports (P1-10).
static void	rewire_stream_observer (entropic_handle_t h)
	Propagate any pre-configure stream observer to the new engine.
static void	rewire_queue_observer (entropic_handle_t h)
	Propagate any pre-configure queue observer to the new engine.
static void	rewire_state_observer (entropic_handle_t h)
	Propagate any pre-configure state observer to the new engine.
static void	rewire_critique_callbacks (entropic_handle_t h)
	Propagate pre-configure critique callbacks to a newly- constructed ConstitutionalValidator (gh#50, v2.1.12).
static void	rewire_observers (entropic_handle_t h)
	Re-bind every pre-configure observer to the new engine.
static void	populate_tier_info (entropic_handle_t h, const std::filesystem::path &data_dir, const std::string &shared_prefix)
	Register per-tier ChildContextInfo with the engine.
static bool	si_create_delegation (const char *parent_id, const char *delegating_tier, const char *target_tier, const char *task, int max_turns, std::string &delegation_id, std::string &child_conversation_id, void *user_data)
	Initialize persistence: storage + session logger.
static bool	si_create_conversation (const char *title, std::string &conversation_id, void *user_data)
	StorageInterface bridge: create_conversation trampoline.
static bool	si_complete_delegation (const char *delegation_id, const char *status, const char *summary, void *user_data)
	StorageInterface bridge: complete_delegation trampoline.
static bool	si_save_conversation (const char *conversation_id, const char *messages_json, void *user_data)
	StorageInterface bridge: save_conversation trampoline.
static bool	si_save_snapshot (const char *conversation_id, const char *messages_json, void *user_data)
	StorageInterface bridge: save_snapshot trampoline.
static bool	si_load_delegation_with_messages (const char *delegation_id, std::string &result_json, void *user_data)
	StorageInterface bridge: load_delegation_with_messages.
static entropic::StorageInterface	build_storage_iface (entropic::SqliteStorageBackend *sb)
	Build a populated StorageInterface bound to sb.
static void	init_persistence (entropic_handle_t h)
	Initialize persistence: storage + session logger + StorageInterface.
static std::vector< std::string >	collect_delegatable_tiers (const entropic::ParsedConfig &config)
	Collect valid delegation targets from handoff_rules.
static void	init_mcp_servers (entropic_handle_t h, const std::filesystem::path &data_dir)
	Initialize MCP servers with resolved working directory.
static std::string	build_shared_prompt_prefix (entropic_handle_t h, const std::filesystem::path &data_dir)
	Build shared system prompt prefix (constitution + app_context).
static void	thread_frontmatter_sampler (entropic::TierConfig &tc, const entropic::prompts::IdentityFrontmatter &fm)
	Cache per-tier frontmatter fields (allowed_tools, validation_rules, relay).
static void	apply_identity_frontmatter (entropic_handle_t h, const std::string &name, const entropic::prompts::IdentityFrontmatter &fm)
	Apply a parsed identity's frontmatter to the engine handle.
static void	cache_tier_allowed_tools (entropic_handle_t h, const std::filesystem::path &data_dir)
	Cache per-tier frontmatter fields from identity files.
static void	thread_frontmatter_samplers (entropic_handle_t h, const std::filesystem::path &data_dir)
	Thread per-tier frontmatter SAMPLERS into config pre-orchestrator.
static char *	tool_history_json_thunk (size_t count, void *ud)
	Wire the ToolExecutor and attach it to the engine.
static void	wire_tool_executor (entropic_handle_t h)
	Wire the ToolExecutor and attach it to the engine.
static char *	sp_get_validation (void *ud)
	Return the validator's last verdict as JSON for ON_COMPLETE.
static void	wire_hooks_and_validator (entropic_handle_t h, entropic::InferenceInterface &iface, const std::string &constitution_text)
	Wire hook dispatch and attach the constitutional validator.
static char *	sp_get_config (void *ud)
	State provider: get_config.
static std::string	build_assembled_prompt_for_tier (entropic_engine *h, const std::string &tier_name)
	Build the assembled system prompt the engine would send for a given tier (constitution + app_context + identity body + tool defs).
static char *	sp_get_identities (void *ud)
	State provider: get_identities.
static char *	sp_get_tools (void *ud)
	State provider: get_tools.
static char *	sp_get_history (int max_entries, void *ud)
	State provider: get_history — conversation context snapshot.
static char *	sp_get_residency (void *ud)
	State provider: get_residency — VRAM residency snapshot.
static char *	sp_get_state (void *ud)
	State provider: get_state (runtime environment).
static char *	sp_get_metrics (void *ud)
	State provider: get_metrics.
static char *	sp_get_docs (const char *section, void *ud)
	State provider: get_docs.
static char *	sp_search_delegations (const char *query, int max_results, void *ud)
	State provider: search_delegations (gh#32, v2.1.6).
static char *	sp_load_delegation_conversation (const char *delegation_id, void *ud)
	State provider: load_delegation_conversation (gh#32, v2.1.6).
static void	wire_state_provider (entropic_handle_t h)
	Wire state provider to the EntropicServer.
static void	wire_tier_validation_rules (entropic_handle_t h)
	Pass per-identity validation rules to the validator.
static entropic::LoopConfig	build_loop_config (entropic_handle_t h)
	Build LoopConfig from parsed config.
static void	start_external_bridge (entropic_handle_t h)
	Start the external MCP bridge if enabled in config.
static entropic_error_t	reject_if_configured (entropic_handle_t h)
	Post-parse config setup: subsystem construction + wiring.
static entropic_error_t	init_orchestrator (entropic_handle_t h, const std::filesystem::path &data_dir)
	Shared body of all entropic_configure* entry points.
static void	init_engine_and_interfaces (entropic_handle_t h, const std::filesystem::path &data_dir)
	Build the engine + inference interfaces (configure step 2).
static void	wire_prompts_and_persistence (entropic_handle_t h, const std::filesystem::path &data_dir)
	Assemble prompts + wire validation/persistence (config step 3).
static entropic_error_t	configure_common (entropic_handle_t h)
	Shared body of all entropic_configure* entry points.
static entropic_error_t	do_configure_json (entropic_handle_t handle, const char *config_json)
	entropic_configure body — wrapped by c_api_try in the public entry.
entropic_error_t	entropic_configure (entropic_handle_t handle, const char *config_json)
	Configure the engine from a JSON/YAML config string.
static entropic_error_t	do_configure_from_file (entropic_handle_t handle, const char *config_path)
	entropic_configure_from_file body — wrapped by c_api_try.
entropic_error_t	entropic_configure_from_file (entropic_handle_t handle, const char *config_path)
	Configure the engine from a YAML config file.
static entropic_error_t	do_configure_dir (entropic_handle_t handle, const char *project_dir)
	entropic_configure_dir body — wrapped by c_api_try.
entropic_error_t	entropic_configure_dir (entropic_handle_t handle, const char *project_dir)
	Configure using layered resolution (project dir).
void	entropic_destroy (entropic_handle_t handle)
	Destroy an engine instance.
const char *	entropic_version (void)
	Get the library version string.
int	entropic_api_version (void)
	Get the plugin API version number.
int64_t	entropic_seconds_since_last_activity (entropic_handle_t handle)
	gh#35: idle-time accessor for host-side idle-exit policies.
void *	entropic_alloc (size_t size)
	Allocate memory using the engine's allocator.
void	entropic_free (void *ptr)
	Free memory allocated by the engine.
entropic_error_t	entropic_run (entropic_handle_t handle, const char *input, char **result_json)
	Single-turn blocking agentic run.
static entropic_error_t	run_as_inner (entropic_handle_t handle, const char *tier, const char *input, char **result_json)
	Run + serialize for entropic_run_as (gh#99).
entropic_error_t	entropic_run_as (entropic_handle_t handle, const char *tier_or_identity, const char *input, char **result_json)
	Single-turn blocking run under a named tier (gh#99).
static std::string	serialize_batch_results (const std::vector< entropic::GenerationResult > &results)
	Serialize batch results to a JSON array string (gh#98).
static std::vector< std::vector< entropic::Message > >	build_batch_messages (entropic_handle_t handle, const char **tiers, const char **prompts, size_t n, std::vector< std::string > &tiers_out)
	Build per-request messages for entropic_run_batch (gh#98).
entropic_error_t	entropic_run_batch (entropic_handle_t handle, const char **tiers, const char **prompts, size_t n, char **result_json)
	Same-prefix batch run on a shared resident model (gh#98).
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 generation — delegates entirely to engine.
static std::vector< entropic::Message >	parse_and_check_vision (entropic_handle_t handle, const char *messages_json, entropic_error_t &out_rc)
	Parse messages_json and check vision-tier availability (gh#37/gh#41).
static entropic_error_t	run_messages_inner (entropic_handle_t handle, const char *messages_json, char **result_json)
	Blocking multimodal run (gh#37, v2.1.8).
entropic_error_t	entropic_run_messages (entropic_handle_t handle, const char *messages_json, char **result_json)
	Blocking multimodal agentic run (gh#37, v2.1.8).
static entropic_error_t	run_messages_stream_inner (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 multimodal run (gh#37, v2.1.8).
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 multimodal agentic run (gh#37, v2.1.8).
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_error_t	entropic_validation_set_auto_retry (entropic_handle_t handle, int enabled)
	Toggle automatic constitutional revision.
entropic_error_t	entropic_validation_resume_retry (entropic_handle_t handle)
	Resume a paused constitutional revision pass.
entropic_error_t	entropic_validation_accept_last (entropic_handle_t handle)
	Accept the last paused attempt as the final answer.
entropic_error_t	entropic_set_attempt_boundary_cb (entropic_handle_t handle, ent_validation_attempt_boundary_cb cb, void *user_data)
	Register attempt-boundary callback on the validator.
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 delegation start/complete callbacks (gh#29, v2.1.5).
entropic_error_t	entropic_set_state_observer (entropic_handle_t handle, void(*observer)(int state, void *user_data), void *user_data)
	Register a state-change observer on the handle.
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 critique start/end callbacks on the handle (gh#50, v2.1.12).
entropic_error_t	entropic_interrupt (entropic_handle_t handle)
	Interrupt a running generation (thread-safe).
entropic_error_t	entropic_queue_user_message (entropic_handle_t handle, const char *message)
	Enqueue a follow-up user message while a run is in flight.
entropic_error_t	entropic_user_message_queue_depth (entropic_handle_t handle, size_t *count)
	Snapshot the mid-gen queue depth.
entropic_error_t	entropic_clear_user_message_queue (entropic_handle_t handle)
	Drop all queued mid-gen user messages.
entropic_error_t	entropic_set_queue_observer (entropic_handle_t handle, void(*observer)(const char *, size_t, void *), void *user_data)
	Register the queue-consumption observer.
entropic_error_t	entropic_context_clear (entropic_handle_t handle)
	Clear conversation history.
entropic_error_t	entropic_context_get (entropic_handle_t handle, char **messages_json)
	Get conversation as JSON array.
entropic_error_t	entropic_context_count (entropic_handle_t handle, size_t *count)
	Get conversation message count.
entropic_error_t	entropic_context_usage (entropic_handle_t handle, size_t *tokens_used, size_t *capacity)
	Read current context-window pressure (gh#39, v2.1.8).
static entropic_error_t	do_state_save (entropic_handle_t handle, const char *tier_name, const char *path)
	Save tier's KV cache to file body (gh#23 v2.3.25).
entropic_error_t	entropic_state_save (entropic_handle_t handle, const char *tier_name, const char *path)
	Save a tier's KV cache to a file (gh#23 v2.3.25, MVP item 13).
static bool	read_state_file (const char *path, std::vector< uint8_t > &out_buf)
	Load tier's KV cache from file body (gh#23 v2.3.25).
static entropic_error_t	do_state_load (entropic_handle_t handle, const char *tier_name, const char *path)
	Load tier's KV cache from file body (gh#23 v2.3.25).
entropic_error_t	entropic_state_load (entropic_handle_t handle, const char *tier_name, const char *path)
	Restore a tier's KV cache from a file (gh#23 v2.3.25).
entropic_error_t	entropic_metrics_json (entropic_handle_t handle, char **out)
	Get loop metrics as JSON (flat + per_tier).
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_error_t	entropic_adapter_unload (entropic_handle_t handle, const char *adapter_name)
	Unload a LoRA adapter.
entropic_error_t	entropic_adapter_swap (entropic_handle_t handle, const char *adapter_name)
	Swap active LoRA adapter.
int	entropic_adapter_state (entropic_handle_t handle, const char *adapter_name)
	Query adapter lifecycle state.
char *	entropic_adapter_info (entropic_handle_t handle, const char *adapter_name)
	Get adapter info as JSON string.
char *	entropic_adapter_list (entropic_handle_t handle)
	List all known adapters as a JSON array.
entropic_error_t	entropic_grammar_register (entropic_handle_t handle, const char *key, const char *gbnf_content)
	Register a grammar by key with GBNF content.
entropic_error_t	entropic_grammar_register_file (entropic_handle_t handle, const char *key, const char *path)
	Register a grammar from a GBNF file.
entropic_error_t	entropic_grammar_deregister (entropic_handle_t handle, const char *key)
	Remove a grammar from the registry.
char *	entropic_grammar_get (entropic_handle_t handle, const char *key)
	Get grammar GBNF content by key.
char *	entropic_grammar_validate (const char *gbnf_content)
	Validate a GBNF grammar string without registering.
char *	entropic_grammar_list (entropic_handle_t handle)
	List all registered grammars as a JSON array.
entropic_error_t	entropic_profile_register (entropic_handle_t handle, const char *profile_json)
	Register a custom GPU resource profile from JSON.
entropic_error_t	entropic_profile_deregister (entropic_handle_t handle, const char *name)
	Remove a GPU resource profile by name.
char *	entropic_profile_get (entropic_handle_t handle, const char *name)
	Get a GPU resource profile by name as JSON.
char *	entropic_profile_list (entropic_handle_t handle)
	List all registered profile names as a JSON array.
double	entropic_throughput_tok_per_sec (entropic_handle_t handle, const char *model_path)
	Get EWMA throughput estimate in tokens per second.
void	entropic_throughput_reset (entropic_handle_t handle, const char *model_path)
	Reset throughput tracking data.
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_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.
int	entropic_check_mcp_key (entropic_handle_t handle, const char *identity_name, const char *tool_name, entropic_mcp_access_level_t level)
	Check MCP key authorization for an identity.
char *	entropic_list_mcp_keys (entropic_handle_t handle, const char *identity_name)
	List MCP keys for an identity as JSON array.
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.
char *	entropic_serialize_mcp_keys (entropic_handle_t handle)
	Serialize all identity key sets to JSON.
entropic_error_t	entropic_deserialize_mcp_keys (entropic_handle_t handle, const char *json)
	Deserialize all identity key sets from JSON.
entropic_error_t	entropic_create_identity (entropic_handle_t handle, const char *config_json)
	Create a dynamic identity from JSON config.
entropic_error_t	entropic_update_identity (entropic_handle_t handle, const char *name, const char *config_json)
	Update an existing dynamic identity.
entropic_error_t	entropic_destroy_identity (entropic_handle_t handle, const char *name)
	Destroy a dynamic identity.
char *	entropic_get_identity_config (entropic_handle_t handle, const char *name)
	Get identity config as JSON by name.
char *	entropic_list_identities (entropic_handle_t handle)
	List all identity names as JSON array.
entropic_error_t	entropic_identity_count (entropic_handle_t handle, size_t *total, size_t *dynamic)
	Get identity count (total and dynamic).
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_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.
void	entropic_free_logprob_result (entropic_logprob_result_t *result)
	Free internal arrays of a logprob result.
int	entropic_model_has_vision (entropic_handle_t handle, const char *model_id)
	Check if a model has vision (multimodal) capability.
entropic_error_t	entropic_validation_set_enabled (entropic_handle_t handle, bool enabled)
	Enable or disable constitutional validation globally.
entropic_error_t	entropic_validation_set_identity (entropic_handle_t handle, const char *identity_name, bool enabled)
	Set per-identity validation override.
char *	entropic_validation_last_result (entropic_handle_t handle)
	Get last validation result as JSON.
entropic_error_t	entropic_get_diagnostic_prompt (entropic_handle_t handle, char **prompt_out)
	Get diagnostic prompt text for /diagnose command (stub).
entropic_error_t	entropic_speculative_compat (entropic_handle_t handle, int *compatible, char **diagnostic)
	Query speculative-decoding compatibility for the configured target/draft pair.
entropic_error_t	entropic_set_residency_observer (entropic_handle_t handle, entropic_residency_observer_t observer, void *user_data)
	Register a residency observer on the orchestrator.
entropic_error_t	entropic_residency_snapshot (entropic_handle_t handle, char **out_json)
	Return the engine's current residency-set snapshot as JSON.

Variables
static auto	s_log = entropic::log::get("facade")
static thread_local std::string	s_last_error_cache
static thread_local char	s_pre_create_error [512] = ""

Detailed Description

librentropic facade — C API implementation.

Owns the EntropicEngine handle struct and implements lifecycle (create/configure/destroy), generation, and subsystem stubs. Stubs are wired to real subsystems across Phases 0-5.

Version

2.0.0

Definition in file entropic.cpp.

Function Documentation

alloc_cstr() [1/2]

static char * alloc_cstr ( const char *  src )

static

Allocate a C string copy via the engine allocator.

Uses entropic_alloc so the caller can free with entropic_free(). Returns NULL on allocation failure (OOM).

Parameters

src	Source string (null-terminated).

Returns

Heap-allocated copy, or NULL on OOM. @req REQ-API-008

Version

2.0.1

Definition at line 106 of file entropic.cpp.

alloc_cstr() [2/2]

static char * alloc_cstr ( const std::string &  src )

static

Allocate a C string copy from std::string.

Parameters

src	Source string.

Returns

Heap-allocated copy, or NULL on OOM. @req REQ-API-008

Version

2.0.1

Definition at line 121 of file entropic.cpp.

apply_identity_frontmatter()

static void apply_identity_frontmatter ( entropic_handle_t  h, const std::string &  name, const entropic::prompts::IdentityFrontmatter &  fm  )

static

Apply a parsed identity's frontmatter to the engine handle.

Parameters

h	Engine handle.
name	Tier name.
fm	Parsed frontmatter. @req REQ-API-013

Version

2.7.3

Definition at line 894 of file entropic.cpp.

build_assembled_prompt_for_tier()

static std::string build_assembled_prompt_for_tier ( entropic_engine *  h, const std::string &  tier_name  )

static

Build the assembled system prompt the engine would send for a given tier (constitution + app_context + identity body + tool defs).

Returns "" on any failure.

Demo ask #3 (v2.1.0). Static parts only — does NOT include the per-turn iteration / validation reminders, since those are runtime-dependent. Runtime augmentations live in ResponseGenerator::inject_engine_state_reminder.

@utility

Version

2.11.0

Definition at line 1206 of file entropic.cpp.

build_batch_messages()

static std::vector< std::vector< entropic::Message > > build_batch_messages ( entropic_handle_t  handle, const char **  tiers, const char **  prompts, size_t  n, std::vector< std::string > &  tiers_out  )

static

Build per-request messages for entropic_run_batch (gh#98).

Each request becomes [system(tier prompt), user(prompt)] so same-tier requests share a prompt prefix the backend can prefill once.

Parameters

	handle	Engine handle (for per-tier system prompts).
	tiers	C array of tier names (entries may be NULL → default).
	prompts	C array of user prompts.
	n	Request count.
[out]	tiers_out	Normalized tier strings ("" for NULL/default).

Returns

Per-request message lists. @utility

Version

2.8.0

Definition at line 2199 of file entropic.cpp.

build_loop_config()

static entropic::LoopConfig build_loop_config ( entropic_handle_t  h )

static

Build LoopConfig from parsed config.

Parameters

h	Engine handle with config populated.

Returns

Populated LoopConfig. @utility

Version

2.9.6

Definition at line 1513 of file entropic.cpp.

build_shared_prompt_prefix()

static std::string build_shared_prompt_prefix ( entropic_handle_t  h, const std::filesystem::path &  data_dir  )

static

Build shared system prompt prefix (constitution + app_context).

Parameters

h	Engine handle with config loaded.
data_dir	Bundled data directory.

Returns

Concatenated prefix string. @utility

Version

2.11.0

Definition at line 820 of file entropic.cpp.

build_storage_iface()

static entropic::StorageInterface build_storage_iface ( entropic::SqliteStorageBackend *  sb )

static

Build a populated StorageInterface bound to sb.

gh#32 (v2.1.6): pre-2.1.6 nothing called AgentEngine::set_storage so the engine's StorageInterface fields were all nullptr and the delegation/compaction storage paths were dead code. This builder closes that gap.

Parameters

sb	Storage backend (non-owning).

Returns

StorageInterface ready to pass to AgentEngine::set_storage. @dg_internal

Version

2.1.12

Definition at line 715 of file entropic.cpp.

c_api_try()

template<typename Fn >

static entropic_error_t c_api_try ( entropic_handle_t  handle, Fn &&  fn  )

static

Run a C-API entry-point body inside an exception barrier.

gh#74 (v2.3.13): every extern "C" function in this translation unit MUST guarantee that no C++ exception escapes back into the caller (per docs/architecture-cpp.md's "exceptions do not cross .so boundaries" rule). Wraps the body in try/catch and maps the three exception families we've actually seen to documented error codes:

• std::filesystem::filesystem_error → ENTROPIC_ERROR_IO
• nlohmann::json::exception → ENTROPIC_ERROR_INVALID_CONFIG
• any other std::exception → ENTROPIC_ERROR_INTERNAL

The handle's last_error is populated with what() when handle is non-null so consumers can read it via entropic_last_error(). Logs at error level on every catch so the operator sees the exception type alongside the C error code that surfaced.

Rolled out incrementally — v2.3.13 covers the three configure entry points that gh#74 reported as visibly leaking. Other extern-C functions can wrap their bodies the same way as needed.

Parameters

handle	Engine handle for last_error write (may be NULL).
fn	Body returning the natural success / error code.

Returns

fn()'s return value on no exception; mapped error code otherwise. @req REQ-ABI-002

Version

2.3.13

Definition at line 75 of file entropic.cpp.

cache_tier_allowed_tools()

static void cache_tier_allowed_tools ( entropic_handle_t  h, const std::filesystem::path &  data_dir  )

static

Cache per-tier frontmatter fields from identity files.

Parameters

h	Engine handle with config + engine constructed.
data_dir	Bundled data directory. @req REQ-API-013

Version

2.5.2

Definition at line 921 of file entropic.cpp.

check_identity()

static entropic_error_t check_identity ( entropic_handle_t  h )

static

Check handle prerequisites for identity manager APIs.

Parameters

h	Engine handle.

Returns

ENTROPIC_OK if valid, error code otherwise. @req REQ-API-005

Version

2.0.0

Definition at line 199 of file entropic.cpp.

check_mcp_auth()

static entropic_error_t check_mcp_auth ( entropic_handle_t  h )

static

Check handle prerequisites for MCP auth APIs.

Parameters

h	Engine handle.

Returns

ENTROPIC_OK if valid, error code otherwise. @req REQ-API-005

Version

2.0.0

Definition at line 184 of file entropic.cpp.

check_orchestrator()

static entropic_error_t check_orchestrator ( entropic_handle_t  h )

static

Check handle prerequisites for orchestrator APIs.

Parameters

h	Engine handle.

Returns

ENTROPIC_OK if valid, error code otherwise. @req REQ-API-005

Version

2.0.0

Definition at line 169 of file entropic.cpp.

collect_delegatable_tiers()

static std::vector< std::string > collect_delegatable_tiers ( const entropic::ParsedConfig &  config )

static

Collect valid delegation targets from handoff_rules.

Only tiers that appear as TARGETS in handoff_rules are included. Sources are excluded — a tier should not appear in its own delegate enum (self-delegation creates a worktree cycle for no purpose and confuses small models).

When handoff_rules is empty, falls back to all configured tiers except the default tier (preserves delegation for simple configs that define multiple tiers without explicit routing).

Parameters

config

Parsed engine config.

Returns

Deduplicated tier names for delegate/pipeline schemas. @utility

Version

2.0.6

Definition at line 770 of file entropic.cpp.

configure_common()

static entropic_error_t configure_common ( entropic_handle_t  h )

static

Shared body of all entropic_configure* entry points.

Returns

ENTROPIC_OK on success, else the first failing step's error code. @req REQ-API-004

Version

2.7.3

Definition at line 1725 of file entropic.cpp.

do_configure_dir()

static entropic_error_t do_configure_dir ( entropic_handle_t  handle, const char *  project_dir  )

static

entropic_configure_dir body — wrapped by c_api_try.

Returns

ENTROPIC_OK on success, else the configure error code. @req REQ-API-004 @req REQ-CFG-001 @req REQ-ABI-002

Version

2.3.13

Definition at line 1866 of file entropic.cpp.

do_configure_from_file()

static entropic_error_t do_configure_from_file ( entropic_handle_t  handle, const char *  config_path  )

static

entropic_configure_from_file body — wrapped by c_api_try.

Returns

ENTROPIC_OK on success, else the configure error code. @req REQ-API-004 @req REQ-ABI-002

Version

2.3.13

Definition at line 1811 of file entropic.cpp.

do_configure_json()

static entropic_error_t do_configure_json ( entropic_handle_t  handle, const char *  config_json  )

static

entropic_configure body — wrapped by c_api_try in the public entry.

Returns

ENTROPIC_OK on success, else the configure error code. @req REQ-API-004 @req REQ-ABI-002

Version

2.9.5

Definition at line 1758 of file entropic.cpp.

do_state_load()

static entropic_error_t do_state_load ( entropic_handle_t  handle, const char *  tier_name, const char *  path  )

static

Load tier's KV cache from file body (gh#23 v2.3.25).

@dg_internal

Version

2.3.25

Definition at line 2971 of file entropic.cpp.

do_state_save()

static entropic_error_t do_state_save ( entropic_handle_t  handle, const char *  tier_name, const char *  path  )

static

Save tier's KV cache to file body (gh#23 v2.3.25).

@dg_internal

Version

2.3.25

Definition at line 2910 of file entropic.cpp.

entropic_adapter_info()

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

Get adapter info as JSON string.

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. @req REQ-INFER-023 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.2

Definition at line 3193 of file entropic.cpp.

entropic_adapter_list()

char * entropic_adapter_list

(

entropic_handle_t

handle

)

List all known adapters as a JSON array.

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. @req REQ-INFER-023 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.2

Definition at line 3225 of file entropic.cpp.

entropic_adapter_load()

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.

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. @req REQ-INFER-023 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.2

Definition at line 3040 of file entropic.cpp.

entropic_adapter_state()

int entropic_adapter_state	(	entropic_handle_t	handle,
		const char *	adapter_name
	)

Query adapter lifecycle state.

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. @req REQ-INFER-023 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3162 of file entropic.cpp.

entropic_adapter_swap()

entropic_error_t entropic_adapter_swap	(	entropic_handle_t	handle,
		const char *	adapter_name
	)

Swap active LoRA adapter.

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. @req REQ-INFER-023 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3125 of file entropic.cpp.

entropic_adapter_unload()

entropic_error_t entropic_adapter_unload	(	entropic_handle_t	handle,
		const char *	adapter_name
	)

Unload a LoRA adapter.

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. @req REQ-INFER-023 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3085 of file entropic.cpp.

entropic_alloc()

void * entropic_alloc

(

size_t

size

)

Allocate memory using the engine's allocator.

Returns

Pointer to allocated memory, or NULL on failure. @req REQ-API-008 @req REQ-ABI-001

Version

1.8.0

Definition at line 2007 of file entropic.cpp.

entropic_api_version()

int entropic_api_version

(

void

)

Get the plugin API version number.

Get the C API version number.

Returns

API version integer. @req REQ-TYPE-002 @req REQ-ABI-001

Version

2.0.0

Definition at line 1982 of file entropic.cpp.

entropic_check_mcp_key()

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

Check MCP key authorization for an identity.

Check if a tool call is authorized for an identity.

Returns

1 if authorized, 0 if denied, -1 on error. @req REQ-MCP-010 @req REQ-API-005

Version

2.0.0

Definition at line 3699 of file entropic.cpp.

entropic_clear_user_message_queue()

entropic_error_t entropic_clear_user_message_queue

(

entropic_handle_t

handle

)

Drop all queued mid-gen user messages.

Drop all queued user messages.

Returns

ENTROPIC_OK on success (a benign no-op before configure), ENTROPIC_ERROR_INVALID_HANDLE when handle is NULL. @req REQ-API-005 @req REQ-ABI-001

Version

2.1.10

Definition at line 2786 of file entropic.cpp.

entropic_compute_perplexity()

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 wrapper — resolves the tier backend and calls InferenceBackend::compute_perplexity().

Returns

ENTROPIC_OK on success, error code on failure. @req REQ-INFER-024 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 4036 of file entropic.cpp.

entropic_configure()

entropic_error_t entropic_configure	(	entropic_handle_t	handle,
		const char *	config_json
	)

Configure the engine from a JSON/YAML config string.

Configure the engine from a JSON config string.

Returns

ENTROPIC_OK on success. @req REQ-API-004 @req REQ-API-005 @req REQ-ABI-001 @req REQ-ABI-002

Version

2.0.2

Definition at line 1792 of file entropic.cpp.

entropic_configure_dir()

entropic_error_t entropic_configure_dir	(	entropic_handle_t	handle,
		const char *	project_dir
	)

Configure using layered resolution (project dir).

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. @req REQ-API-004 @req REQ-CFG-001 @req REQ-API-005 @req REQ-ABI-001 @req REQ-ABI-002

Version

2.1.6

Definition at line 1913 of file entropic.cpp.

entropic_configure_from_file()

entropic_error_t entropic_configure_from_file	(	entropic_handle_t	handle,
		const char *	config_path
	)

Configure the engine from a YAML config file.

Configure engine from a YAML or JSON config file.

Returns

ENTROPIC_OK on success. @req REQ-API-004 @req REQ-API-005 @req REQ-ABI-001 @req REQ-ABI-002

Version

2.0.5

Definition at line 1846 of file entropic.cpp.

entropic_context_clear()

entropic_error_t entropic_context_clear

(

entropic_handle_t

handle

)

Clear conversation history.

Clear conversation history, starting a new session.

Parameters

handle

Engine handle returned by entropic_create.

Returns

ENTROPIC_OK on success. @req REQ-API-005 @req REQ-ABI-001

Version

2.0.1

Definition at line 2832 of file entropic.cpp.

entropic_context_count()

entropic_error_t entropic_context_count	(	entropic_handle_t	handle,
		size_t *	count
	)

Get conversation message count.

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. @req REQ-API-005 @req REQ-ABI-001

Version

2.0.1

Definition at line 2868 of file entropic.cpp.

entropic_context_get()

entropic_error_t entropic_context_get	(	entropic_handle_t	handle,
		char **	messages_json
	)

Get conversation as JSON array.

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. @req REQ-SAFE-001 @req REQ-API-008 @req REQ-API-005

Version

2.0.1

Definition at line 2849 of file entropic.cpp.

entropic_context_usage()

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

Read current context-window pressure (gh#39, v2.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. @req REQ-API-005 @req REQ-ABI-001

Version

2.1.8

Definition at line 2891 of file entropic.cpp.

entropic_create()

entropic_error_t entropic_create

(

entropic_handle_t *

handle

)

Create a new engine instance.

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. @req REQ-API-002 @req REQ-API-003 @req REQ-ABI-001

Version

2.0.2

Definition at line 248 of file entropic.cpp.

entropic_create_identity()

entropic_error_t entropic_create_identity	(	entropic_handle_t	handle,
		const char *	config_json
	)

Create a dynamic identity from JSON config.

Create a dynamic identity.

Returns

ENTROPIC_OK on success. @req REQ-IDEN-002 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3823 of file entropic.cpp.

entropic_deserialize_mcp_keys()

entropic_error_t entropic_deserialize_mcp_keys	(	entropic_handle_t	handle,
		const char *	json
	)

Deserialize all identity key sets from JSON.

Returns

ENTROPIC_OK on success. @req REQ-MCP-010 @req REQ-API-005

Version

2.0.0

Definition at line 3800 of file entropic.cpp.

entropic_destroy()

void entropic_destroy

(

entropic_handle_t

handle

)

Destroy an engine instance.

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.

@req REQ-API-002 @req REQ-API-003 @req REQ-ABI-001

Version

2.0.8

Definition at line 1934 of file entropic.cpp.

entropic_destroy_identity()

entropic_error_t entropic_destroy_identity	(	entropic_handle_t	handle,
		const char *	name
	)

Destroy a dynamic identity.

Returns

ENTROPIC_OK on success. @req REQ-IDEN-002 @req REQ-API-005

Version

2.0.0

Definition at line 3889 of file entropic.cpp.

entropic_free()

void entropic_free

(

void *

ptr

)

Free memory allocated by the engine.

Free a string allocated by the server.

Free memory allocated by the engine or entropic_alloc().

@req REQ-API-008 @req REQ-ABI-001

Version

1.8.0

Definition at line 2018 of file entropic.cpp.

entropic_free_logprob_result()

void entropic_free_logprob_result

(

entropic_logprob_result_t *

result

)

Free internal arrays of a logprob result.

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

@req REQ-API-008 @req REQ-ABI-001

Version

1.9.10

Definition at line 4069 of file entropic.cpp.

entropic_get_diagnostic_prompt()

entropic_error_t entropic_get_diagnostic_prompt	(	entropic_handle_t	handle,
		char **	prompt_out
	)

Get diagnostic prompt text for /diagnose command (stub).

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. @req REQ-API-008 @req REQ-API-005

Version

2.0.2

Definition at line 4191 of file entropic.cpp.

entropic_get_identity_config()

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

Get identity config as JSON by name.

Get identity configuration as JSON by name.

Returns

JSON string (caller frees), or NULL if not found. @req REQ-IDEN-002 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.2

Definition at line 3910 of file entropic.cpp.

entropic_get_logprobs()

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.

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. @req REQ-INFER-024 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3989 of file entropic.cpp.

entropic_grammar_deregister()

entropic_error_t entropic_grammar_deregister	(	entropic_handle_t	handle,
		const char *	key
	)

Remove a grammar from the registry.

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. @req REQ-INFER-007 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3327 of file entropic.cpp.

entropic_grammar_get()

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

Get grammar GBNF content by key.

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. @req REQ-INFER-007 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.2

Definition at line 3360 of file entropic.cpp.

entropic_grammar_list()

char * entropic_grammar_list

(

entropic_handle_t

handle

)

List all registered grammars as a JSON array.

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. @req REQ-INFER-007 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.2

Definition at line 3416 of file entropic.cpp.

entropic_grammar_register()

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

Register a grammar by key with GBNF content.

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. @req REQ-INFER-007 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3257 of file entropic.cpp.

entropic_grammar_register_file()

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

Register a grammar from a GBNF file.

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. @req REQ-INFER-007 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3292 of file entropic.cpp.

entropic_grammar_validate()

char * entropic_grammar_validate

(

const char *

gbnf_content

)

Validate a GBNF grammar string without registering.

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. @req REQ-INFER-007 @req REQ-API-008 @req REQ-ABI-001 @req REQ-ABI-002

Version

2.0.2

Definition at line 3392 of file entropic.cpp.

entropic_grant_mcp_key()

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.

Returns

ENTROPIC_OK on success. @req REQ-MCP-010 @req REQ-API-005

Version

2.0.0

Definition at line 3657 of file entropic.cpp.

entropic_grant_mcp_key_from()

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.

Returns

ENTROPIC_OK on success. @req REQ-MCP-010 @req REQ-API-005

Version

2.0.0

Definition at line 3753 of file entropic.cpp.

entropic_identity_count()

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

Get identity count (total and dynamic).

Get identity count.

Returns

ENTROPIC_OK on success. @req REQ-IDEN-002 @req REQ-API-005

Version

2.0.0

Definition at line 3959 of file entropic.cpp.

entropic_interrupt()

entropic_error_t entropic_interrupt

(

entropic_handle_t

handle

)

Interrupt a running generation (thread-safe).

Interrupt a running generation.

Parameters

handle

Engine handle returned by entropic_create.

Returns

ENTROPIC_OK if interrupted. @req REQ-API-009 @req REQ-LOOP-006 @req REQ-API-005

Version

2.0.0

Definition at line 2719 of file entropic.cpp.

entropic_last_error()

const char * entropic_last_error

(

entropic_handle_t

handle

)

Read the per-handle last_error under api_mutex.

Get the last error message for a handle.

Pre-v2.2.6 the public symbol lived in src/types/error.cpp and ignored its handle parameter (v1.8.0 TODO never done). Moved here because the private engine_handle struct is only visible in the facade. Returns a thread-local cache copy so the pointer stays valid until the same thread reads again — matches the v1.8.0 contract documented in include/entropic/types/error.h.

Returns

Thread-local copy of this handle's last error message; the empty string when there is none. Never NULL, never freed by the caller. @req REQ-API-007 @req REQ-API-003 @req REQ-ABI-001

Version

2.2.6

Definition at line 155 of file entropic.cpp.

entropic_list_identities()

char * entropic_list_identities

(

entropic_handle_t

handle

)

List all identity names as JSON array.

Returns

JSON array string (caller frees), or NULL. @req REQ-IDEN-002 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.2

Definition at line 3939 of file entropic.cpp.

entropic_list_mcp_keys()

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

List MCP keys for an identity as JSON array.

List all MCP keys for an identity as JSON.

Returns

JSON array string (caller frees), or NULL on error. @req REQ-MCP-010 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.2

Definition at line 3723 of file entropic.cpp.

entropic_metrics_json()

entropic_error_t entropic_metrics_json	(	entropic_handle_t	handle,
		char **	out
	)

Get loop metrics as JSON (flat + per_tier).

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. @req REQ-API-008 @req REQ-API-005

Version

2.0.6-rc16.2

Definition at line 3016 of file entropic.cpp.

entropic_model_has_vision()

int entropic_model_has_vision	(	entropic_handle_t	handle,
		const char *	model_id
	)

Check if a model has vision (multimodal) capability.

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. @req REQ-INFER-025 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 4095 of file entropic.cpp.

entropic_profile_deregister()

entropic_error_t entropic_profile_deregister	(	entropic_handle_t	handle,
		const char *	name
	)

Remove a GPU resource profile by name.

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. @req REQ-INFER-019 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3496 of file entropic.cpp.

entropic_profile_get()

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

Get a GPU resource profile by name as JSON.

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. @req REQ-INFER-019 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.2

Definition at line 3531 of file entropic.cpp.

entropic_profile_list()

char * entropic_profile_list

(

entropic_handle_t

handle

)

List all registered profile names as a JSON array.

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. @req REQ-INFER-019 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.2

Definition at line 3568 of file entropic.cpp.

entropic_profile_register()

entropic_error_t entropic_profile_register	(	entropic_handle_t	handle,
		const char *	profile_json
	)

Register a custom GPU resource profile from JSON.

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. @req REQ-INFER-019 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3454 of file entropic.cpp.

entropic_queue_user_message()

entropic_error_t entropic_queue_user_message	(	entropic_handle_t	handle,
		const char *	message
	)

Enqueue a follow-up user message while a run is in flight.

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.

Returns

ENTROPIC_OK on success; INVALID_HANDLE for a NULL handle, INVALID_ARGUMENT for a NULL message, INVALID_STATE when no run is in flight, QUEUE_FULL when the bounded queue is at capacity. @req REQ-API-005 @req REQ-ABI-001

Version

2.1.10

Definition at line 2745 of file entropic.cpp.

entropic_residency_snapshot()

entropic_error_t entropic_residency_snapshot	(	entropic_handle_t	handle,
		char **	out_json
	)

Return the engine's current residency-set snapshot as JSON.

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.

Returns

ENTROPIC_OK on success; INVALID_HANDLE for a NULL handle or out_json, INVALID_STATE when no orchestrator exists. @req REQ-INFER-019 @req REQ-API-008 @req REQ-API-005

Version

2.2.4

Definition at line 4329 of file entropic.cpp.

entropic_revoke_mcp_key()

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.

Returns

ENTROPIC_OK on success. @req REQ-MCP-010 @req REQ-API-005

Version

2.0.0

Definition at line 3679 of file entropic.cpp.

entropic_run()

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

Single-turn blocking agentic run.

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 @req REQ-API-009 @req REQ-API-010 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.9.5

Definition at line 2043 of file entropic.cpp.

entropic_run_as()

entropic_error_t entropic_run_as	(	entropic_handle_t	handle,
		const char *	tier_or_identity,
		const char *	input,
		char **	result_json
	)

Single-turn blocking run under a named tier (gh#99).

Single-turn agentic run under a named tier (gh#99).

Per-call tier/grammar/identity selection on the shared resident model: runs input under tier_or_identity's grammar + system prompt + samplers with no 2nd model load and no reconfigure. Same result contract as entropic_run().

Parameters

handle	Engine handle returned by entropic_create.
tier_or_identity	Tier name to run this call under.
input	Null-terminated user input string.
result_json	Out: newly allocated JSON result (caller frees with entropic_free).

Returns

ENTROPIC_OK on success; ENTROPIC_ERROR_IDENTITY_NOT_FOUND for an unknown tier; other error codes per entropic_run(). @req REQ-API-009 @req REQ-API-010 @req REQ-API-008 @req REQ-API-005

Version

2.9.5

Definition at line 2139 of file entropic.cpp.

entropic_run_batch()

entropic_error_t entropic_run_batch	(	entropic_handle_t	handle,
		const char **	tiers,
		const char **	prompts,
		size_t	n,
		char **	result_json
	)

Same-prefix batch run on a shared resident model (gh#98).

Runs N independent same-prefix requests together: the shared prompt prefix is prefilled once and fanned out, each request sampled under its tier's grammar. One-shot generations (no agentic loop) — suited to per-tick game agents. Results are returned as a single JSON array string.

Parameters

	handle	Engine handle.
	tiers	C array of N tier names (entries may be NULL → default tier).
	prompts	C array of N user prompts.
	n	Request count.
[out]	result_json	JSON array of N {content, finish_reason, tool_calls}. Caller frees with entropic_free().

Returns

ENTROPIC_OK on success; error codes per entropic_run(). @req REQ-API-009 @req REQ-INFER-018 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.9.5

Definition at line 2246 of file entropic.cpp.

entropic_run_messages()

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

Blocking multimodal agentic run (gh#37, v2.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. @req REQ-API-009 @req REQ-INFER-025 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.9.5

Definition at line 2420 of file entropic.cpp.

entropic_run_messages_streaming()

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 multimodal agentic run (gh#37, v2.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. @req REQ-API-009 @req REQ-INFER-025 @req REQ-API-005 @req REQ-ABI-002

Version

2.9.5

Definition at line 2489 of file entropic.cpp.

entropic_run_streaming()

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 generation — delegates entirely to engine.

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. @req REQ-API-009 @req REQ-API-010 @req REQ-API-005 @req REQ-ABI-002

Version

2.9.5

Definition at line 2301 of file entropic.cpp.

entropic_seconds_since_last_activity()

int64_t entropic_seconds_since_last_activity

(

entropic_handle_t

handle

)

gh#35: idle-time accessor for host-side idle-exit policies.

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

Returns

Seconds since the most recent run on this handle; 0 when the handle is NULL or no run has happened yet. @req REQ-API-005 @req REQ-ABI-001

Version

2.3.0

Definition at line 1994 of file entropic.cpp.

entropic_serialize_mcp_keys()

char * entropic_serialize_mcp_keys

(

entropic_handle_t

handle

)

Serialize all identity key sets to JSON.

Returns

JSON string (caller frees), or NULL on error. @req REQ-MCP-010 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.2

Definition at line 3778 of file entropic.cpp.

entropic_set_attempt_boundary_cb()

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

Register attempt-boundary callback on the validator.

Register an attempt-boundary callback for the validator.

Returns

ENTROPIC_OK on success, ENTROPIC_ERROR_INVALID_HANDLE when handle is NULL. @req REQ-API-010 @req REQ-VALID-003 @req REQ-API-005

Version

2.1.5

Definition at line 2600 of file entropic.cpp.

entropic_set_critique_callbacks()

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 critique start/end callbacks on the handle (gh#50, v2.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. @req REQ-API-010 @req REQ-VALID-002 @req REQ-API-005

Version

2.1.12

Definition at line 2693 of file entropic.cpp.

entropic_set_delegation_callbacks()

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 delegation start/complete callbacks (gh#29, v2.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. @req REQ-API-010 @req REQ-DELEG-002 @req REQ-API-005

Version

2.1.5

Definition at line 2623 of file entropic.cpp.

entropic_set_queue_observer()

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

Register the queue-consumption observer.

Stores on the handle so pre-configure registration is preserved, then forwards to the engine if it exists. The engine member is the source of truth at fire time — set_callbacks() shuffles in the streaming path do not touch this slot.

Returns

ENTROPIC_OK on success, ENTROPIC_ERROR_INVALID_HANDLE when handle is NULL. @req REQ-API-010 @req REQ-API-005

Version

2.1.10

Definition at line 2809 of file entropic.cpp.

entropic_set_residency_observer()

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

Register a residency observer on the orchestrator.

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.

Returns

ENTROPIC_OK on success, ENTROPIC_ERROR_INVALID_HANDLE when handle is NULL. @req REQ-API-010 @req REQ-INFER-019 @req REQ-API-005

Version

2.2.4

Definition at line 4283 of file entropic.cpp.

entropic_set_state_observer()

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

Register a state-change observer on the handle.

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. @req REQ-API-010 @req REQ-LOOP-001 @req REQ-API-005

Version

2.1.10

Definition at line 2654 of file entropic.cpp.

entropic_set_stream_observer()

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.

Parameters

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

Returns

ENTROPIC_OK on success. @req REQ-API-010 @req REQ-API-005

Version

2.0.6-rc16

Definition at line 2523 of file entropic.cpp.

entropic_speculative_compat()

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

Query speculative-decoding compatibility for the configured target/draft pair.

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. @req REQ-INFER-016 @req REQ-API-008 @req REQ-API-005

Version

2.1.11

Definition at line 4245 of file entropic.cpp.

entropic_state_load()

entropic_error_t entropic_state_load	(	entropic_handle_t	handle,
		const char *	tier_name,
		const char *	path
	)

Restore a tier's KV cache from a file (gh#23 v2.3.25).

Restore a tier's KV-cache state from a file (gh#23 MVP item 13).

Returns

ENTROPIC_OK on success. @req REQ-API-005 @req REQ-ABI-001 @req REQ-ABI-002

Version

2.3.25

Definition at line 2989 of file entropic.cpp.

entropic_state_save()

entropic_error_t entropic_state_save	(	entropic_handle_t	handle,
		const char *	tier_name,
		const char *	path
	)

Save a tier's KV cache to a file (gh#23 v2.3.25, MVP item 13).

Save a tier's KV-cache state to a file (gh#23 MVP item 13).

Returns

ENTROPIC_OK on success. @req REQ-API-005 @req REQ-ABI-001 @req REQ-ABI-002

Version

2.3.25

Definition at line 2931 of file entropic.cpp.

entropic_throughput_reset()

void entropic_throughput_reset	(	entropic_handle_t	handle,
		const char *	model_path
	)

Reset throughput tracking data.

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. @req REQ-INFER-021 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3630 of file entropic.cpp.

entropic_throughput_tok_per_sec()

double entropic_throughput_tok_per_sec	(	entropic_handle_t	handle,
		const char *	model_path
	)

Get EWMA throughput estimate in tokens per second.

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. @req REQ-INFER-021 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3600 of file entropic.cpp.

entropic_update_identity()

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

Update an existing dynamic identity.

Update a dynamic identity.

Returns

ENTROPIC_OK on success. @req REQ-IDEN-002 @req REQ-API-005 @req REQ-ABI-002

Version

2.0.0

Definition at line 3856 of file entropic.cpp.

entropic_user_message_queue_depth()

entropic_error_t entropic_user_message_queue_depth	(	entropic_handle_t	handle,
		size_t *	count
	)

Snapshot the mid-gen queue depth.

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

Returns

ENTROPIC_OK on success (depth 0 when the engine is not built), INVALID_HANDLE for a NULL handle, INVALID_ARGUMENT for a NULL count. @req REQ-API-005 @req REQ-ABI-001

Version

2.1.10

Definition at line 2769 of file entropic.cpp.

entropic_validation_accept_last()

entropic_error_t entropic_validation_accept_last

(

entropic_handle_t

handle

)

Accept the last paused attempt as the final answer.

Finalize the last attempt as the turn's response.

Returns

ENTROPIC_OK on success, ENTROPIC_ERROR_INVALID_HANDLE when handle is NULL, ENTROPIC_ERROR_INVALID_STATE when no validator exists. @req REQ-VALID-003 @req REQ-API-005

Version

2.1.5

Definition at line 2583 of file entropic.cpp.

entropic_validation_last_result()

char * entropic_validation_last_result

(

entropic_handle_t

handle

)

Get last validation result as JSON.

Get the last validation result as JSON.

Returns

JSON string (caller frees), or NULL if no result. @req REQ-VALID-001 @req REQ-API-008 @req REQ-API-005 @req REQ-ABI-002

Version

2.10.0

Definition at line 4166 of file entropic.cpp.

entropic_validation_resume_retry()

entropic_error_t entropic_validation_resume_retry

(

entropic_handle_t

handle

)

Resume a paused constitutional revision pass.

Opt the engine into running the constitutional revision pass.

Returns

ENTROPIC_OK on success, ENTROPIC_ERROR_INVALID_HANDLE when handle is NULL, ENTROPIC_ERROR_INVALID_STATE when no validator exists. @req REQ-VALID-003 @req REQ-API-005

Version

2.1.5

Definition at line 2566 of file entropic.cpp.

entropic_validation_set_auto_retry()

entropic_error_t entropic_validation_set_auto_retry	(	entropic_handle_t	handle,
		int	enabled
	)

Toggle automatic constitutional revision.

Toggle automatic constitutional revision after rejection.

Returns

ENTROPIC_OK on success, ENTROPIC_ERROR_INVALID_HANDLE when handle is NULL. @req REQ-VALID-003 @req REQ-API-005

Version

2.1.5

Definition at line 2548 of file entropic.cpp.

entropic_validation_set_enabled()

entropic_error_t entropic_validation_set_enabled	(	entropic_handle_t	handle,
		bool	enabled
	)

Enable or disable constitutional validation globally.

Enable or disable constitutional validation.

Returns

ENTROPIC_OK on success. @req REQ-VALID-001 @req REQ-API-005

Version

2.0.2

Definition at line 4124 of file entropic.cpp.

entropic_validation_set_identity()

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

Set per-identity validation override.

Returns

ENTROPIC_OK on success. @req REQ-VALID-001 @req REQ-API-005

Version

2.0.0

Definition at line 4142 of file entropic.cpp.

entropic_version()

const char * entropic_version

(

void

)

Get the library version string.

Returns

Static version string. @req REQ-API-008 @req REQ-ABI-001

Version

1.8.0

Definition at line 1971 of file entropic.cpp.

facade_get_tool_prompt()

static int facade_get_tool_prompt ( const char *  tier, char **  result, void *  user_data  )

static

Build formatted tool prompt for a tier.

gh#87 (v2.7.0): returns the per-tier-filtered tool defs as a structured MCP JSON array ([{name, description, inputSchema}, ...]), NOT an adapter-formatted prompt string. The defs flow into params.tools and common_chat renders them in the model's native format — so no adapter format_tools and no system-message string injection. The field's contract ("tool definitions for tier") is unchanged; only the payload shape evolved from formatted-prompt to structured-JSON.

Parameters

tier	Tier name.
result	Output: heap-allocated JSON-array string. Caller frees.
user_data	Engine handle.

Returns

0 on success, non-zero if no tools available. @callback

Version

2.7.0

Definition at line 375 of file entropic.cpp.

filter_tools()

static std::vector< std::string > filter_tools ( const nlohmann::json &  all_tools, const std::vector< std::string > &  allowed  )

static

Filter tool definitions by allowed list.

Parameters

all_tools	Parsed JSON array of all tool definitions.
allowed	Allowed tool names (empty = no filter).

Returns

JSON strings of matching tools. @utility

Version

2.0.4

Definition at line 343 of file entropic.cpp.

init_engine_and_interfaces()

static void init_engine_and_interfaces ( entropic_handle_t  h, const std::filesystem::path &  data_dir  )

static

Build the engine + inference interfaces (configure step 2).

Extracted from configure_common to keep it knots-clean. Creates the MCP-auth + identity managers, the per-handle orchestrator interface (gh#58), the AgentEngine, and rewires observers/interrupt/tools.

Parameters

h	Engine handle.
data_dir	Resolved data directory. @dg_internal

Version

2.3.8

Definition at line 1650 of file entropic.cpp.

init_mcp_servers()

static void init_mcp_servers ( entropic_handle_t  h, const std::filesystem::path &  data_dir  )

static

Initialize MCP servers with resolved working directory.

Parameters

h	Engine handle with config loaded.
data_dir	Bundled data directory path. @dg_internal

Version

2.10.1

Definition at line 793 of file entropic.cpp.

init_orchestrator()

static entropic_error_t init_orchestrator ( entropic_handle_t  h, const std::filesystem::path &  data_dir  )

static

Shared body of all entropic_configure* entry points.

@dg_internal

Version

2.2.6

Construct the orchestrator + grammar fallback for a handle.

Extracted from configure_common in v2.2.9 to keep SLOC under the knots gate after v2.2.6's per-handle InterfaceContext wiring grew the body past 50 lines.

Returns

ENTROPIC_OK on success, an error code when orchestrator construction fails. @req REQ-API-013 @req REQ-API-004

Version

2.2.9

Definition at line 1622 of file entropic.cpp.

init_persistence()

static void init_persistence ( entropic_handle_t  h )

static

Initialize persistence: storage + session logger + StorageInterface.

@dg_internal

Version

2.1.6

Definition at line 733 of file entropic.cpp.

parse_and_check_vision()

static std::vector< entropic::Message > parse_and_check_vision ( entropic_handle_t  handle, const char *  messages_json, entropic_error_t &  out_rc  )

static

Parse messages_json and check vision-tier availability (gh#37/gh#41).

Parses the wire-format messages array via the shared utility and, if any message carries image content_parts, verifies that the orchestrator has at least one tier whose capabilities includes "vision". Returns the parsed vector on success; throws on parse failure (caller catches and maps to ENTROPIC_ERROR_*).

Parameters

	handle	Engine handle (already validated by caller).
	messages_json	Caller-provided JSON array string.
[out]	out_rc	Set to ENTROPIC_OK on success, or to a specific error code (NO_VISION_TIER) when validation fails.

Returns

Parsed messages on success, empty vector on failure. @dg_internal

Version

2.1.8

Definition at line 2352 of file entropic.cpp.

populate_tier_info()

static void populate_tier_info ( entropic_handle_t  h, const std::filesystem::path &  data_dir, const std::string &  shared_prefix  )

static

Register per-tier ChildContextInfo with the engine.

Extracted from configure_common to keep that function under the 50-SLOC quality gate. Iterates the configured tiers, resolves each identity file, and registers the assembled context with the engine.

Parameters

h	Engine handle (engine must be constructed).
data_dir	Resolved data directory for identity files.
shared_prefix	Prefix assembled from constitution + app context. @utility

Version

2.9.20

Definition at line 529 of file entropic.cpp.

read_state_file()

static bool read_state_file ( const char *  path, std::vector< uint8_t > &  out_buf  )

static

Load tier's KV cache from file body (gh#23 v2.3.25).

@dg_internal

Version

2.3.25

Read the entire contents of path into out_buf.

Returns

true on success (file exists, non-empty, read fully). @utility

Version

2.3.25

Definition at line 2955 of file entropic.cpp.

reject_if_configured()

static entropic_error_t reject_if_configured ( entropic_handle_t  h )

static

Post-parse config setup: subsystem construction + wiring.

v2.1.10 (gh#40 + fallout): observer rewiring at engine construction is bundled into rewire_observers so pre-configure stream, queue, and state observers all survive engine construction AND the EngineCallbacks shuffle that run_streaming performs.

Parameters

h	Engine handle with config populated.

Returns

ENTROPIC_OK or error code. @dg_internal

Version

2.1.10.1

Refuse a second configure on the same handle (gh#58).

Re-configure would leak raw pointers captured during the first pass into subsystems that already wired against the original orchestrator/engine/mcp_auth.

Returns

ENTROPIC_OK when the handle is not yet configured, ENTROPIC_ERROR_INVALID_STATE when it already is. @req REQ-API-004

Version

2.2.5

Definition at line 1597 of file entropic.cpp.

require_active_backend()

static entropic::InferenceBackend * require_active_backend ( entropic_handle_t  h, const char *  tier_name  )

static

Resolve tier name to an ACTIVE backend, or throw.

Parameters

h	Engine handle (must have orchestrator).
tier_name	Tier name string.

Returns

Non-null backend pointer in ACTIVE state.

Exceptions

std::runtime_error

if tier not found or not active. @dg_internal

Version

2.0.0

Definition at line 218 of file entropic.cpp.

resolve_allowed_tools()

static std::vector< std::string > resolve_allowed_tools ( entropic_engine *  h, const std::string &  tier  )

static

Post-parse config setup: load bundled models, set configured.

Parameters

h	Engine handle.

Returns

ENTROPIC_OK or error code. @dg_internal

Version

2.0.0

Pre-load bundled models from default locations.

Tries compile-time and source-tree data dirs before config is parsed, so registry keys resolve during config loading.

Parameters

h	Engine handle. @dg_internal

Version

2.0.1

Resolve allowed_tools list for a tier.

Checks identity config first, then model config fallback. Empty result means all tools are allowed (no filter).

Parameters

h	Engine handle.
tier	Tier name.

Returns

Allowed tool names (empty = all allowed). @utility

Version

2.0.4

Definition at line 317 of file entropic.cpp.

rewire_critique_callbacks()

static void rewire_critique_callbacks ( entropic_handle_t  h )

static

Propagate pre-configure critique callbacks to a newly- constructed ConstitutionalValidator (gh#50, v2.1.12).

Same pattern as rewire_state_observer: the handle owns the authoritative slot; configure_common reconstructs the validator each call, so the rewire helper re-applies the consumer's registered callbacks after every (re)construction.

Parameters

h	Engine handle with validator just constructed (or NULL). @req REQ-API-010

Version

2.1.12

Definition at line 489 of file entropic.cpp.

rewire_observers()

static void rewire_observers ( entropic_handle_t  h )

static

Re-bind every pre-configure observer to the new engine.

Aggregates the three rewire helpers so configure_common stays under the SLOC ceiling. (gh#40 fallout, v2.1.10)

Parameters

h	Engine handle with engine just constructed. @req REQ-API-010

Version

2.1.12

Definition at line 509 of file entropic.cpp.

rewire_queue_observer()

static void rewire_queue_observer ( entropic_handle_t  h )

static

Propagate any pre-configure queue observer to the new engine.

Sibling of rewire_stream_observer for the mid-gen queue consumption callback (gh#40, v2.1.10). Re-binds the handle-stored observer when the AgentEngine is constructed so observers never miss queue-consumption events on a late-bound engine.

Parameters

h	Engine handle with engine just constructed. @req REQ-API-010

Version

2.1.10

Definition at line 450 of file entropic.cpp.

rewire_state_observer()

static void rewire_state_observer ( entropic_handle_t  h )

static

Propagate any pre-configure state observer to the new engine.

gh#40 fallout (v2.1.10): pre-existing behavior wired the observer via engine->set_callbacks(), which is wiped by run_streaming. Re-bind through the persistent slot so pre-configure registrations survive engine construction AND streaming runs.

Parameters

h	Engine handle with engine just constructed. @req REQ-API-010

Version

2.1.10

Definition at line 469 of file entropic.cpp.

rewire_stream_observer()

static void rewire_stream_observer ( entropic_handle_t  h )

static

Propagate any pre-configure stream observer to the new engine.

Handles the edge case where a caller registers a stream observer before entropic_configure() — the handle stores it on arrival, and this helper re-binds it when the AgentEngine is constructed so observers never miss tokens on a late-bound engine. (P0-1)

Parameters

h	Engine handle with engine just constructed. @req REQ-API-010

Version

2.0.6-rc16

Definition at line 431 of file entropic.cpp.

run_as_inner()

static entropic_error_t run_as_inner ( entropic_handle_t  handle, const char *  tier, const char *  input, char **  result_json  )

static

Run + serialize for entropic_run_as (gh#99).

Extracted so entropic_run_as stays within the knots returns gate. @utility

Returns

ENTROPIC_OK or ENTROPIC_ERROR_GENERATE_FAILED.

Version

2.8.0

Definition at line 2093 of file entropic.cpp.

run_messages_inner()

static entropic_error_t run_messages_inner ( entropic_handle_t  handle, const char *  messages_json, char **  result_json  )

static

Blocking multimodal run (gh#37, v2.1.8).

@dg_internal

Version

2.1.8

Inner blocking-run dispatch — no front validation (gh#37).

Caller has already verified handle, args, and engine pointer. Parses messages, runs the multimodal vision check, dispatches the turn, serializes the result, and fires the synthetic stream-observer completion sentinel. Returns the canonical entropic_error_t status — single exit.

@dg_internal

Version

2.1.8

Definition at line 2384 of file entropic.cpp.

run_messages_stream_inner()

static entropic_error_t run_messages_stream_inner ( 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  )

static

Streaming multimodal run (gh#37, v2.1.8).

@dg_internal

Version

2.1.8

Inner streaming dispatch — no front validation (gh#37). @dg_internal

Version

2.1.8

Definition at line 2451 of file entropic.cpp.

serialize_batch_results()

static std::string serialize_batch_results ( const std::vector< entropic::GenerationResult > &  results )

static

Serialize batch results to a JSON array string (gh#98).

Parameters

results

Per-request generation results.

Returns

JSON array: [{content, finish_reason, tool_calls}, ...]. @utility

Version

2.10.0

Definition at line 2171 of file entropic.cpp.

si_complete_delegation()

static bool si_complete_delegation ( const char *  delegation_id, const char *  status, const char *  summary, void *  user_data  )

static

StorageInterface bridge: complete_delegation trampoline.

@callback

Version

2.1.6

Definition at line 616 of file entropic.cpp.

si_create_conversation()

static bool si_create_conversation ( const char *  title, std::string &  conversation_id, void *  user_data  )

static

StorageInterface bridge: create_conversation trampoline.

Forwards AgentEngine::run's root-conversation creation to the SqliteStorageBackend. Pre-v2.1.12 (gh#48) the interface had no create_conversation callback, so the root conversation row was never inserted and every subsequent delegation's FK to conversations(id) failed silently against the empty parent id.

@callback

Version

2.1.12

Definition at line 601 of file entropic.cpp.

si_create_delegation()

static bool si_create_delegation ( const char *  parent_id, const char *  delegating_tier, const char *  target_tier, const char *  task, int  max_turns, std::string &  delegation_id, std::string &  child_conversation_id, void *  user_data  )

static

Initialize persistence: storage + session logger.

Parameters

h	Engine handle with config.log_dir set. @dg_internal

Version

2.0.1

StorageInterface bridge: create_delegation trampoline.

Translates the engine's StorageInterface callback into a call against SqliteStorageBackend::create_delegation. gh#32 (v2.1.6) closes a pre-existing wiring gap: the engine declared the interface but the facade never populated it, so per-delegation storage records were silently dropped. This is the bridge that finally connects them.

@callback

Version

2.1.6

Definition at line 574 of file entropic.cpp.

si_load_delegation_with_messages()

static bool si_load_delegation_with_messages ( const char *  delegation_id, std::string &  result_json, void *  user_data  )

static

StorageInterface bridge: load_delegation_with_messages.

Resolves delegation id → child_conversation_id → conversation messages, then returns the composed JSON with target_tier and messages at the top level. Used by entropic.resume_delegation (gh#32, v2.1.6).

@callback

Version

2.1.6

Definition at line 669 of file entropic.cpp.

si_save_conversation()

static bool si_save_conversation ( const char *  conversation_id, const char *  messages_json, void *  user_data  )

static

StorageInterface bridge: save_conversation trampoline.

@callback

Version

2.1.6

Definition at line 632 of file entropic.cpp.

si_save_snapshot()

static bool si_save_snapshot ( const char *  conversation_id, const char *  messages_json, void *  user_data  )

static

StorageInterface bridge: save_snapshot trampoline.

@callback

Version

2.1.6

Definition at line 648 of file entropic.cpp.

sp_get_config()

static char * sp_get_config ( void *  ud )

static

State provider: get_config.

@callback

Version

2.0.6

Definition at line 1183 of file entropic.cpp.

sp_get_docs()

static char * sp_get_docs ( const char *  section, void *  ud  )

static

State provider: get_docs.

@callback

Version

2.0.6

Definition at line 1407 of file entropic.cpp.

sp_get_history()

static char * sp_get_history ( int  max_entries, void *  ud  )

static

State provider: get_history — conversation context snapshot.

@callback

Returns the current conversation as a JSON array of {role, content_preview, token_count_est} objects, suitable for context_inspect MCP tool and inspect –target history. (P2-16)

Content previews are truncated at 200 bytes on a UTF-8 codepoint boundary via entropic::facade::utf8_safe_substr — byte-indexed truncation would slice multi-byte codepoints and cause arr.dump() below to throw nlohmann::json::type_error.316 (gh#56).

Parameters

max_entries	Maximum messages to return (0 = all).
ud	Engine handle.

Returns

JSON array string (caller frees via free()).

Version

2.2.3

Definition at line 1291 of file entropic.cpp.

sp_get_identities()

static char * sp_get_identities ( void *  ud )

static

State provider: get_identities.

Returns an array of objects per tier: [{"name":"lead","assembled_prompt":"…"}, ...]

The assembled_prompt is the static system prompt the engine would send for that tier (constitution + app_context + identity body + tool defs), excluding per-turn runtime augmentations. Demo ask #3: lets entropic.inspect identity <tier> return what the model actually sees, without running inference. (v2.1.0)

@callback

Version

2.1.0

Definition at line 1249 of file entropic.cpp.

sp_get_metrics()

static char * sp_get_metrics ( void *  ud )

static

State provider: get_metrics.

Returns LoopMetrics from the most recent run plus a per-tier accumulator as JSON. Flat fields: iterations, tool_calls, tokens_used, errors, duration_ms (all zero before any run). The per_tier object maps tier name → metrics since engine start. (P2-15 + follow-up)

@callback

Version

2.0.6-rc16.2

Definition at line 1377 of file entropic.cpp.

sp_get_residency()

static char * sp_get_residency ( void *  ud )

static

State provider: get_residency — VRAM residency snapshot.

@callback

Backs the engine's introspection surface for "what models are loaded right now". Mirrors the C ABI entropic_residency_snapshot JSON schema. Returns an empty residency object when the orchestrator is not yet constructed (pre-configure). (gh#57)

Parameters

ud	Engine handle.

Returns

JSON object string (caller frees via free()).

Version

2.2.4

Definition at line 1328 of file entropic.cpp.

sp_get_state()

static char * sp_get_state ( void *  ud )

static

State provider: get_state (runtime environment).

@callback

Version

2.0.6

Definition at line 1343 of file entropic.cpp.

sp_get_tools()

static char * sp_get_tools ( void *  ud )

static

State provider: get_tools.

@callback

Version

2.0.6

Definition at line 1267 of file entropic.cpp.

sp_get_validation()

static char * sp_get_validation ( void *  ud )

static

Return the validator's last verdict as JSON for ON_COMPLETE.

Shape: {ran, verdict, violations[], revisions_applied}. Verdict is a string from {passed, revised, rejected_reverted_length, rejected_max_revisions}. Returns malloc'd buffer; engine frees. (E3, 2.0.6-rc17)

Parameters

ud	entropic_engine handle.

Returns

JSON string or NULL if validator not configured. @callback

Version

2.1.5

Definition at line 1060 of file entropic.cpp.

sp_load_delegation_conversation()

static char * sp_load_delegation_conversation ( const char *  delegation_id, void *  ud  )

static

State provider: load_delegation_conversation (gh#32, v2.1.6).

Delegates to the engine-facing StorageInterface bridge so both surfaces stay in lockstep.

@callback

Version

2.1.6

Definition at line 1444 of file entropic.cpp.

sp_search_delegations()

static char * sp_search_delegations ( const char *  query, int  max_results, void *  ud  )

static

State provider: search_delegations (gh#32, v2.1.6).

Substring-search past delegation result summaries via the SQLite storage backend. Returns NULL if no storage is configured.

@callback

Version

2.1.6

Definition at line 1422 of file entropic.cpp.

start_external_bridge()

static void start_external_bridge ( entropic_handle_t  h )

static

Start the external MCP bridge if enabled in config.

Creates an ExternalBridge listening on a unix domain socket so external MCP clients (Claude Code, etc.) can talk to the running engine without spawning a separate process.

Parameters

h	Engine handle (must be fully configured). @req REQ-BRIDGE-001

Version

2.0.8

Definition at line 1559 of file entropic.cpp.

thread_frontmatter_sampler()

static void thread_frontmatter_sampler ( entropic::TierConfig &  tc, const entropic::prompts::IdentityFrontmatter &  fm  )

static

Cache per-tier frontmatter fields (allowed_tools, validation_rules, relay).

Parameters

h	Engine handle with config + engine constructed.
data_dir	Bundled data directory. @dg_internal

Version

2.0.11

Thread frontmatter sampler optionals into a tier config.

gh#82/gh#85: each knob copies only when the frontmatter set it, so the orchestrator's per-tier resolution can apply it as the tier baseline. Extracted from apply_identity_frontmatter to keep that function under the cognitive-complexity gate.

Parameters

tc	Tier config (mutated).
fm	Parsed identity frontmatter. @req REQ-API-013

Version

2.7.4

Definition at line 856 of file entropic.cpp.

thread_frontmatter_samplers()

static void thread_frontmatter_samplers ( entropic_handle_t  h, const std::filesystem::path &  data_dir  )

static

Thread per-tier frontmatter SAMPLERS into config pre-orchestrator.

gh#94 (v2.7.3): the orchestrator snapshots h->config BY VALUE in init_orchestrator() (config_ = config). The engine-bound frontmatter wiring (cache_tier_allowed_tools → apply_identity_frontmatter) necessarily runs LATER, after the engine exists. Threading sampler knobs there left them in h->config but never in the orchestrator's frozen copy, so every tier silently ran GenerationParams defaults regardless of frontmatter. This pass threads ONLY the dependency-free sampler knobs into each tier BEFORE init_orchestrator, so the snapshot carries them. The engine-dependent wiring (allowed_tools, relay_single_delegate, tool_executor) stays in wire_prompts_and_persistence.

Parameters

h	Engine handle (config tiers mutated in place).
data_dir	Bundled data directory (identity file resolution). @req REQ-API-013

Version

2.7.3

Definition at line 966 of file entropic.cpp.

tool_history_json_thunk()

static char * tool_history_json_thunk ( size_t  count, void *  ud  )

static

Wire the ToolExecutor and attach it to the engine.

Parameters

h	Engine handle with engine + server_manager constructed. @dg_internal

Version

2.0.3

C-safe accessor for ToolExecutor's history (P1-11).

Extracted to satisfy the 3-return complexity gate.

Parameters

count	Max entries to serialize.
ud	ToolExecutor pointer.

Returns

malloc'd JSON string, or nullptr when empty/unset. @utility

Version

2.0.6-rc16

Definition at line 1003 of file entropic.cpp.

wire_external_interrupt()

static void wire_external_interrupt ( entropic_handle_t  h )

static

Wire engine interrupt propagation into MCP transports (P1-10).

Extracted from configure_common to keep that function under the 50-SLOC quality gate. On first interrupt(), the lambda calls ServerManager::interrupt_external_tools() which trips the cancel flag in every StdioTransport so in-flight reads return within ~100ms.

Parameters

h	Engine handle with engine and server_manager constructed. @utility

Version

2.0.6-rc16

Definition at line 411 of file entropic.cpp.

wire_hooks_and_validator()

static void wire_hooks_and_validator ( entropic_handle_t  h, entropic::InferenceInterface &  iface, const std::string &  constitution_text  )

static

Wire hook dispatch and attach the constitutional validator.

Bridges the handle's HookRegistry to the engine's HookInterface (function-pointer indirection required by the .so boundary). If constitutional validation is enabled and constitution text was loaded, constructs and attaches the validator as a POST_GENERATE hook.

Parameters

h	Engine handle with engine constructed.
iface	Inference interface (passed to validator for critique generation).
constitution_text	Constitution text (may be empty). @dg_internal

Version

2.10.3

Definition at line 1118 of file entropic.cpp.

wire_prompts_and_persistence()

static void wire_prompts_and_persistence ( entropic_handle_t  h, const std::filesystem::path &  data_dir  )

static

Assemble prompts + wire validation/persistence (config step 3).

Extracted from configure_common to keep it knots-clean.

Parameters

h	Engine handle.
data_dir	Resolved data directory. @dg_internal

Version

2.9.19

Definition at line 1698 of file entropic.cpp.

wire_state_provider()

static void wire_state_provider ( entropic_handle_t  h )

static

Wire state provider to the EntropicServer.

v2.2.4 (gh#57): registers the additional get_residency callback so the engine's introspection surface reflects the current VRAM residency set alongside config/identities/tools/history/metrics.

Parameters

h	Engine handle with all subsystems constructed. @dg_internal

Version

2.2.4

Definition at line 1469 of file entropic.cpp.

wire_tier_validation_rules()

static void wire_tier_validation_rules ( entropic_handle_t  h )

static

Pass per-identity validation rules to the validator.

Parameters

h	Engine handle with validator + tier_validation_rules populated. @dg_internal

Version

2.0.6

Definition at line 1499 of file entropic.cpp.

wire_tool_executor()

static void wire_tool_executor ( entropic_handle_t  h )

static

Wire the ToolExecutor and attach it to the engine.

Constructs the ToolExecutor from existing subsystems, builds the ToolExecutionInterface bridge (process_tool_calls + history_json thunk), and registers it with the AgentEngine.

Parameters

h	Engine handle with engine + server_manager constructed. @req REQ-API-013 @req REQ-MCP-014

Version

2.0.6-rc16

Definition at line 1028 of file entropic.cpp.

Variable Documentation

s_last_error_cache

thread_local std::string s_last_error_cache

static

Definition at line 134 of file entropic.cpp.

s_log

auto s_log = entropic::log::get("facade")

static

Definition at line 42 of file entropic.cpp.

s_pre_create_error

thread_local char s_pre_create_error[512] = ""

static

Definition at line 135 of file entropic.cpp.