entropic.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#pragma once
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#include <entropic/entropic_config.h>
#include <entropic/entropic_export.h>
#include <entropic/types/error.h>
#include <entropic/types/hooks.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ── Lifecycle ────────────────────────────────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_create(entropic_handle_t* handle);
 
ENTROPIC_EXPORT entropic_error_t entropic_configure(
    entropic_handle_t handle,
    const char* config_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_configure_from_file(
    entropic_handle_t handle,
    const char* config_path);
 
ENTROPIC_EXPORT entropic_error_t entropic_configure_dir(
    entropic_handle_t handle,
    const char* project_dir);
 
ENTROPIC_EXPORT void entropic_destroy(entropic_handle_t handle);
 
/* ── Version ──────────────────────────────────────────── */
 
ENTROPIC_EXPORT const char* entropic_version(void);
 
ENTROPIC_EXPORT int entropic_api_version(void);
 
ENTROPIC_EXPORT int64_t entropic_seconds_since_last_activity(
    entropic_handle_t handle);
 
/* ── Memory ───────────────────────────────────────────── */
 
ENTROPIC_EXPORT void* entropic_alloc(size_t size);
 
ENTROPIC_EXPORT void entropic_free(void* ptr);
 
/* ── Execution ────────────────────────────────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_run(
    entropic_handle_t handle,
    const char* input,
    char** result_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_run_as(
    entropic_handle_t handle,
    const char* tier_or_identity,
    const char* input,
    char** result_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_run_batch(
    entropic_handle_t handle,
    const char** tiers,
    const char** prompts,
    size_t n,
    char** result_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_run_streaming(
    entropic_handle_t handle,
    const char* input,
    void (*on_token)(const char* token, size_t len, void* user_data),
    void* user_data,
    int* cancel_flag);
 
ENTROPIC_EXPORT entropic_error_t entropic_run_messages(
    entropic_handle_t handle,
    const char* messages_json,
    char** result_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_run_messages_streaming(
    entropic_handle_t handle,
    const char* messages_json,
    void (*on_token)(const char* token, size_t len, void* user_data),
    void* user_data,
    int* cancel_flag);
 
ENTROPIC_EXPORT entropic_error_t entropic_set_stream_observer(
    entropic_handle_t handle,
    void (*observer)(const char* token, size_t len, void* user_data),
    void* user_data);
 
ENTROPIC_EXPORT entropic_error_t entropic_set_state_observer(
    entropic_handle_t handle,
    void (*observer)(int state, void* user_data),
    void* user_data);
 
ENTROPIC_EXPORT entropic_error_t entropic_set_critique_callbacks(
    entropic_handle_t handle,
    void (*start_cb)(void* user_data),
    void (*end_cb)(void* user_data),
    void* user_data);
 
ENTROPIC_EXPORT entropic_error_t entropic_interrupt(entropic_handle_t handle);
 
ENTROPIC_EXPORT entropic_error_t entropic_interrupt_session(
    entropic_handle_t handle,
    const char* session_key);
 
/* ── Mid-generation message queue (v2.1.10, gh#40) ────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_queue_user_message(
    entropic_handle_t handle,
    const char* message);
 
ENTROPIC_EXPORT entropic_error_t entropic_user_message_queue_depth(
    entropic_handle_t handle,
    size_t* count);
 
ENTROPIC_EXPORT entropic_error_t entropic_clear_user_message_queue(
    entropic_handle_t handle);
 
ENTROPIC_EXPORT entropic_error_t entropic_set_queue_observer(
    entropic_handle_t handle,
    void (*observer)(const char* consumed,
                     size_t remaining,
                     void* user_data),
    void* user_data);
 
/* ── Speculative decoding (v2.1.11, gh#36) ─────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_speculative_compat(
    entropic_handle_t handle,
    int* compatible,
    char** diagnostic);
 
/* ── VRAM-aware tier residency (v2.2.4, gh#57) ────────── */
 
typedef enum {
    ENTROPIC_RESIDENCY_LOADED = 0,            
    ENTROPIC_RESIDENCY_EVICTED = 1,           
    ENTROPIC_RESIDENCY_ACTIVATION_SWAP = 2,   
} entropic_residency_event_t;
 
typedef void (*entropic_residency_observer_t)(
    entropic_residency_event_t event,
    const char* tier_name,
    const char* model_path,
    size_t footprint_bytes,
    void* user_data);
 
ENTROPIC_EXPORT entropic_error_t entropic_set_residency_observer(
    entropic_handle_t handle,
    entropic_residency_observer_t observer,
    void* user_data);
 
ENTROPIC_EXPORT entropic_error_t entropic_residency_snapshot(
    entropic_handle_t handle,
    char** out_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_release_model(
    entropic_handle_t handle,
    const char* tier_name);
 
/* ── Conversation Context (v2.0.1) ───────────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_context_clear(
    entropic_handle_t handle);
 
ENTROPIC_EXPORT entropic_error_t entropic_context_get(
    entropic_handle_t handle,
    char** messages_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_run_session(
    entropic_handle_t handle,
    const char* session_key,
    const char* input,
    char** result_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_run_session_as(
    entropic_handle_t handle,
    const char* session_key,
    const char* tier_or_identity,
    const char* input,
    char** result_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_run_session_streaming(
    entropic_handle_t handle,
    const char* session_key,
    const char* input,
    void (*on_token)(const char* token, size_t len, void* user_data),
    void* user_data,
    int* cancel_flag);
 
ENTROPIC_EXPORT entropic_error_t entropic_run_session_streaming_as(
    entropic_handle_t handle,
    const char* session_key,
    const char* tier_or_identity,
    const char* input,
    void (*on_token)(const char* token, size_t len, void* user_data),
    void* user_data,
    int* cancel_flag);
 
ENTROPIC_EXPORT entropic_error_t entropic_session_context_get(
    entropic_handle_t handle,
    const char* session_key,
    char** messages_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_session_context_set(
    entropic_handle_t handle,
    const char* session_key,
    const char* messages_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_session_context_count(
    entropic_handle_t handle,
    const char* session_key,
    size_t* count);
 
ENTROPIC_EXPORT entropic_error_t entropic_session_context_clear(
    entropic_handle_t handle,
    const char* session_key);
 
ENTROPIC_EXPORT entropic_error_t entropic_session_drop(
    entropic_handle_t handle,
    const char* session_key);
 
ENTROPIC_EXPORT entropic_error_t entropic_session_list(
    entropic_handle_t handle,
    char** sessions_json);
 
/* ── Named Workspaces (v2.13.0, gh#166) ───────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_workspace_create(
    entropic_handle_t handle,
    const char* name,
    const char* dir);
 
ENTROPIC_EXPORT entropic_error_t entropic_session_bind_workspace(
    entropic_handle_t handle,
    const char* session_key,
    const char* name);
 
ENTROPIC_EXPORT entropic_error_t entropic_workspace_set_app_context(
    entropic_handle_t handle,
    const char* name,
    const char* app_context);
 
ENTROPIC_EXPORT entropic_error_t entropic_context_count(
    entropic_handle_t handle,
    size_t* count);
 
ENTROPIC_EXPORT entropic_error_t entropic_context_usage(
    entropic_handle_t handle,
    size_t* tokens_used,
    size_t* capacity);
 
ENTROPIC_EXPORT entropic_error_t entropic_state_save(
    entropic_handle_t handle,
    const char* tier_name,
    const char* path);
 
ENTROPIC_EXPORT entropic_error_t entropic_state_load(
    entropic_handle_t handle,
    const char* tier_name,
    const char* path);
 
ENTROPIC_EXPORT entropic_error_t entropic_metrics_json(
    entropic_handle_t handle,
    char** out);
 
/* ── Delegation Callbacks (v2.1.5, gh#29) ──────────────── */
 
typedef enum {
    ENT_DECISION_ACCEPT = 0,
    ENT_DECISION_REJECT = 1
} ent_decision_t;
 
typedef struct {
    const char* delegation_id;   
    const char* target_tier;     
    const char* task;            
    int depth;                   
    int is_pipeline;             
} ent_delegation_request_t;
 
typedef struct {
    const char* delegation_id;   
    const char* target_tier;     
    int success;                 
    const char* summary;         
    const char* patch;           
    size_t patch_len;            
    const char* const* files_touched; 
    size_t files_touched_len;    
} ent_delegation_result_t;
 
typedef ent_decision_t (*ent_delegation_start_cb)(
    const ent_delegation_request_t* req, void* user_data);
 
typedef ent_decision_t (*ent_delegation_complete_cb)(
    const ent_delegation_result_t* res, void* user_data);
 
ENTROPIC_EXPORT entropic_error_t entropic_set_delegation_callbacks(
    entropic_handle_t handle,
    ent_delegation_start_cb on_start,
    ent_delegation_complete_cb on_complete,
    void* user_data);
 
/* ── Outside-Root Path Approval (v2.13.0) ─────────────── */
 
typedef enum {
    ENT_PATH_ACCESS_READ = 0,
    ENT_PATH_ACCESS_WRITE = 1
} ent_path_access_t;
 
typedef struct {
    const char* path;         
    const char* root;         
    const char* tool;         
    ent_path_access_t access; 
    const char* session_key;  
} ent_path_approval_request_t;
 
typedef ent_decision_t (*ent_path_approval_cb)(
    const ent_path_approval_request_t* req, void* user_data);
 
ENTROPIC_EXPORT entropic_error_t entropic_set_path_approval_callback(
    entropic_handle_t handle,
    ent_path_approval_cb cb,
    void* user_data);
 
/* ── Validation Retry Controls (v2.1.5, gh#30) ───────── */
 
typedef void (*ent_validation_attempt_boundary_cb)(
    int attempt_n, void* user_data);
 
ENTROPIC_EXPORT entropic_error_t entropic_validation_set_auto_retry(
    entropic_handle_t handle,
    int enabled);
 
ENTROPIC_EXPORT entropic_error_t entropic_validation_resume_retry(
    entropic_handle_t handle);
 
ENTROPIC_EXPORT entropic_error_t entropic_validation_accept_last(
    entropic_handle_t handle);
 
ENTROPIC_EXPORT entropic_error_t entropic_set_attempt_boundary_cb(
    entropic_handle_t handle,
    ent_validation_attempt_boundary_cb cb,
    void* user_data);
 
/* ── External MCP Servers (v1.8.7) ───────────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_register_mcp_server(
    entropic_handle_t handle,
    const char* name,
    const char* config_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_deregister_mcp_server(
    entropic_handle_t handle,
    const char* name);
 
ENTROPIC_EXPORT char* entropic_list_mcp_servers(
    entropic_handle_t handle);
 
/* ── Storage (v1.8.8) ────────────────────────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_storage_open(
    entropic_handle_t handle,
    const char* db_path);
 
ENTROPIC_EXPORT entropic_error_t entropic_storage_close(
    entropic_handle_t handle);
 
/* ── Identity (v1.8.9) ───────────────────────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_load_identity(
    entropic_handle_t handle,
    const char* identity_name);
 
ENTROPIC_EXPORT entropic_error_t entropic_get_identity(
    entropic_handle_t handle,
    char** identity_json);
 
/* ── Hooks (v1.9.1) ──────────────────────────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_register_hook(
    entropic_handle_t handle,
    entropic_hook_point_t hook_point,
    entropic_hook_callback_t callback,
    void* user_data,
    int priority);
 
ENTROPIC_EXPORT entropic_error_t entropic_deregister_hook(
    entropic_handle_t handle,
    entropic_hook_point_t hook_point,
    entropic_hook_callback_t callback,
    void* user_data);
 
/* ── LoRA Adapters (v1.9.2) ───────────────────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_adapter_load(
    entropic_handle_t handle,
    const char* adapter_name,
    const char* adapter_path,
    const char* base_model_path,
    float scale);
 
ENTROPIC_EXPORT entropic_error_t entropic_adapter_unload(
    entropic_handle_t handle,
    const char* adapter_name);
 
ENTROPIC_EXPORT entropic_error_t entropic_adapter_swap(
    entropic_handle_t handle,
    const char* adapter_name);
 
ENTROPIC_EXPORT int entropic_adapter_state(
    entropic_handle_t handle,
    const char* adapter_name);
 
ENTROPIC_EXPORT char* entropic_adapter_info(
    entropic_handle_t handle,
    const char* adapter_name);
 
ENTROPIC_EXPORT char* entropic_adapter_list(entropic_handle_t handle);
 
/* ── Grammar Registry (v1.9.3) ───────────────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_grammar_register(
    entropic_handle_t handle,
    const char* key,
    const char* gbnf_content);
 
ENTROPIC_EXPORT entropic_error_t entropic_grammar_register_file(
    entropic_handle_t handle,
    const char* key,
    const char* path);
 
ENTROPIC_EXPORT entropic_error_t entropic_grammar_deregister(
    entropic_handle_t handle,
    const char* key);
 
ENTROPIC_EXPORT char* entropic_grammar_get(
    entropic_handle_t handle,
    const char* key);
 
ENTROPIC_EXPORT char* entropic_grammar_validate(const char* gbnf_content);
 
ENTROPIC_EXPORT char* entropic_grammar_list(entropic_handle_t handle);
 
/* ── GPU Resource Profiles (v1.9.7) ──────────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_profile_register(
    entropic_handle_t handle,
    const char* profile_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_profile_deregister(
    entropic_handle_t handle,
    const char* name);
 
ENTROPIC_EXPORT char* entropic_profile_get(
    entropic_handle_t handle,
    const char* name);
 
ENTROPIC_EXPORT char* entropic_profile_list(entropic_handle_t handle);
 
/* ── Throughput Query (v1.9.7) ───────────────────────── */
 
ENTROPIC_EXPORT double entropic_throughput_tok_per_sec(
    entropic_handle_t handle,
    const char* model_path);
 
ENTROPIC_EXPORT void entropic_throughput_reset(
    entropic_handle_t handle,
    const char* model_path);
 
/* ── MCP Authorization (v1.9.4) ──────────────────────── */
 
typedef enum {
    ENTROPIC_MCP_ACCESS_NONE  = 0, 
    ENTROPIC_MCP_ACCESS_READ  = 1, 
    ENTROPIC_MCP_ACCESS_WRITE = 2, 
} entropic_mcp_access_level_t;
 
ENTROPIC_EXPORT entropic_error_t entropic_grant_mcp_key(
    entropic_handle_t handle,
    const char* identity_name,
    const char* pattern,
    entropic_mcp_access_level_t level);
 
ENTROPIC_EXPORT entropic_error_t entropic_revoke_mcp_key(
    entropic_handle_t handle,
    const char* identity_name,
    const char* pattern);
 
ENTROPIC_EXPORT int entropic_check_mcp_key(
    entropic_handle_t handle,
    const char* identity_name,
    const char* tool_name,
    entropic_mcp_access_level_t level);
 
ENTROPIC_EXPORT char* entropic_list_mcp_keys(
    entropic_handle_t handle,
    const char* identity_name);
 
ENTROPIC_EXPORT entropic_error_t entropic_grant_mcp_key_from(
    entropic_handle_t handle,
    const char* granter,
    const char* grantee,
    const char* pattern,
    entropic_mcp_access_level_t level);
 
ENTROPIC_EXPORT char* entropic_serialize_mcp_keys(
    entropic_handle_t handle);
 
ENTROPIC_EXPORT entropic_error_t entropic_deserialize_mcp_keys(
    entropic_handle_t handle,
    const char* json);
 
/* ── Audit (v1.9.5) ──────────────────────────────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_audit_flush(
    entropic_handle_t handle);
 
ENTROPIC_EXPORT entropic_error_t entropic_audit_count(
    entropic_handle_t handle,
    size_t* count);
 
ENTROPIC_EXPORT entropic_error_t entropic_audit_read(
    entropic_handle_t handle,
    const char* path,
    const char* filter_json,
    char** result_json);
 
/* ── Dynamic Identity Management (v1.9.6) ────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_create_identity(
    entropic_handle_t handle,
    const char* config_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_update_identity(
    entropic_handle_t handle,
    const char* name,
    const char* config_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_destroy_identity(
    entropic_handle_t handle,
    const char* name);
 
ENTROPIC_EXPORT char* entropic_get_identity_config(
    entropic_handle_t handle,
    const char* name);
 
ENTROPIC_EXPORT char* entropic_list_identities(
    entropic_handle_t handle);
 
ENTROPIC_EXPORT entropic_error_t entropic_identity_count(
    entropic_handle_t handle,
    size_t* total,
    size_t* dynamic);
 
/* ── Compaction Hooks (v1.9.9) ───────────────────────── */
 
typedef int (*entropic_compactor_fn)(
    const char* messages_json,
    const char* config_json,
    char** out_messages,
    char** out_summary,
    void* user_data);
 
ENTROPIC_EXPORT entropic_error_t entropic_compact(
    entropic_handle_t handle,
    const char* identity,
    char** result_json);
 
ENTROPIC_EXPORT entropic_error_t entropic_register_compactor(
    entropic_handle_t handle,
    const char* identity,
    entropic_compactor_fn compactor,
    void* user_data);
 
ENTROPIC_EXPORT entropic_error_t entropic_deregister_compactor(
    entropic_handle_t handle,
    const char* identity);
 
ENTROPIC_EXPORT entropic_error_t entropic_get_default_compactor(
    entropic_handle_t handle,
    entropic_compactor_fn* compactor,
    void** user_data);
 
/* ── Log-Probability Evaluation (v1.9.10) ────────────── */
 
typedef struct entropic_logprob_result {
    float* logprobs;        
    int32_t* tokens;        
    float perplexity;       
    float total_logprob;    
    int n_tokens;           
    int n_logprobs;         
} entropic_logprob_result_t;
 
ENTROPIC_EXPORT entropic_error_t entropic_get_logprobs(
    entropic_handle_t handle,
    const char* model_id,
    const int32_t* tokens,
    int n_tokens,
    entropic_logprob_result_t* result);
 
ENTROPIC_EXPORT entropic_error_t entropic_compute_perplexity(
    entropic_handle_t handle,
    const char* model_id,
    const int32_t* tokens,
    int n_tokens,
    float* perplexity);
 
ENTROPIC_EXPORT void entropic_free_logprob_result(
    entropic_logprob_result_t* result);
 
/* ── Constitutional Validation (v1.9.8) ──────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_validation_set_enabled(
    entropic_handle_t handle,
    bool enabled);
 
ENTROPIC_EXPORT entropic_error_t entropic_validation_set_identity(
    entropic_handle_t handle,
    const char* identity_name,
    bool enabled);
 
ENTROPIC_EXPORT char* entropic_validation_last_result(
    entropic_handle_t handle);
 
/* ── Vision / Multimodal (v1.9.11) ────────────────────── */
 
ENTROPIC_EXPORT int entropic_model_has_vision(
    entropic_handle_t handle,
    const char* model_id);
 
/* ── Diagnose / Self-Inspection (v1.9.12) ─────────────── */
 
ENTROPIC_EXPORT entropic_error_t entropic_get_diagnostic_prompt(
    entropic_handle_t handle,
    char** prompt_out);
 
#ifdef __cplusplus
}
#endif