initial commit, moved libpanto over from the pantograph repo

1 files changed, 223 insertions, 0 deletions

diff --git a/libpanto-c/include/panto.h b/libpanto-c/include/panto.h
new file mode 100644
index 0000000..4302bb8
--- /dev/null
+++ b/libpanto-c/include/panto.h
@@ -0,0 +1,223 @@
+#ifndef PANTO_H
+#define PANTO_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#if defined(_WIN32)
+#define PANTO_EXPORT __declspec(dllexport)
+#else
+#define PANTO_EXPORT __attribute__((visibility("default")))
+#endif
+
+typedef struct PantoAgent PantoAgent;
+typedef struct PantoStream PantoStream;
+typedef struct PantoConversation PantoConversation;
+typedef struct PantoSession PantoSession;
+typedef struct PantoSessionStore PantoSessionStore;
+
+typedef struct { const uint8_t *ptr; size_t len; } PantoSlice;
+
+typedef enum { PANTO_OK = 0, PANTO_ERROR = 1 } PantoStatus;
+typedef enum { PANTO_NEXT_EVENT = 0, PANTO_NEXT_DONE = 1, PANTO_NEXT_ERROR = 2 } PantoNextStatus;
+typedef enum { PANTO_OPENAI_CHAT = 0, PANTO_ANTHROPIC_MESSAGES = 1, PANTO_OPENAI_RESPONSES = 2, PANTO_OPENAI_CODEX_RESPONSES = 3 } PantoAPIStyle;
+typedef enum { PANTO_REASONING_DEFAULT = 0, PANTO_REASONING_OFF, PANTO_REASONING_MINIMAL, PANTO_REASONING_LOW, PANTO_REASONING_MEDIUM, PANTO_REASONING_HIGH } PantoReasoningEffort;
+typedef enum { PANTO_THINKING_DISABLED = 0, PANTO_THINKING_ENABLED, PANTO_THINKING_ADAPTIVE } PantoThinking;
+typedef enum { PANTO_EFFORT_LOW = 0, PANTO_EFFORT_MEDIUM, PANTO_EFFORT_HIGH, PANTO_EFFORT_XHIGH, PANTO_EFFORT_MAX } PantoEffort;
+typedef enum { PANTO_ROLE_SYSTEM = 0, PANTO_ROLE_USER, PANTO_ROLE_ASSISTANT } PantoMessageRole;
+typedef enum { PANTO_BLOCK_TEXT = 0, PANTO_BLOCK_THINKING, PANTO_BLOCK_TOOL_USE, PANTO_BLOCK_TOOL_RESULT, PANTO_BLOCK_SYSTEM, PANTO_BLOCK_COMPACTION_SUMMARY } PantoContentBlockTag;
+typedef enum { PANTO_SYSTEM_APPEND = 0, PANTO_SYSTEM_REPLACE } PantoSystemMode;
+typedef enum { PANTO_EVENT_MESSAGE_START = 0, PANTO_EVENT_BLOCK_START, PANTO_EVENT_TOOL_DETAILS, PANTO_EVENT_CONTENT_DELTA, PANTO_EVENT_BLOCK_COMPLETE, PANTO_EVENT_MESSAGE_COMPLETE, PANTO_EVENT_PROVIDER_RETRY, PANTO_EVENT_TOOL_DISPATCH_START, PANTO_EVENT_TOOL_DISPATCH_RESULT, PANTO_EVENT_TOOL_DISPATCH_COMPLETE, PANTO_EVENT_TURN_COMPLETE } PantoEventTag;
+
+typedef struct { uint64_t input, output, cache_read, cache_write, reasoning; } PantoUsage;
+typedef struct { PantoAPIStyle api_style; PantoSlice base_url; PantoSlice model; PantoReasoningEffort reasoning; PantoThinking thinking; PantoEffort effort; bool has_thinking_budget_tokens; uint32_t thinking_budget_tokens; bool thinking_interleaved; } PantoWireIdentity;
+typedef struct { PantoSlice id, created, modified, last_user_message, base_url, model; size_t message_count; PantoAPIStyle api_style; PantoReasoningEffort reasoning; } PantoSessionInfo;
+typedef struct { PantoSessionInfo *ptr; size_t len; } PantoSessionInfoList;
+typedef struct { bool found; PantoSession *session; } PantoSessionResult;
+typedef struct { const char *api_key, *base_url, *model; PantoReasoningEffort reasoning; uint32_t max_tokens; } PantoOpenAIChatConfig;
+typedef struct { const char *api_key, *base_url, *model; PantoReasoningEffort reasoning; uint32_t max_tokens; } PantoOpenAIResponsesConfig;
+typedef struct { const char *api_key, *base_url, *model, *api_version; uint32_t max_tokens; PantoThinking thinking; PantoEffort effort; bool has_thinking_budget_tokens; uint32_t thinking_budget_tokens; bool thinking_interleaved; } PantoAnthropicMessagesConfig;
+typedef struct { PantoAPIStyle tag; union { PantoOpenAIChatConfig openai_chat; PantoAnthropicMessagesConfig anthropic_messages; PantoOpenAIResponsesConfig openai_responses; } data; } PantoProviderConfig;
+typedef struct { uint32_t keep_verbatim; bool has_model; PantoProviderConfig model; bool has_compaction_prompt; const char *compaction_prompt; } PantoCompactionConfig;
+typedef struct { size_t max_attempts; uint64_t initial_delay_ms, max_delay_ms; double multiplier; bool jitter; } PantoRetryConfig;
+typedef struct { PantoProviderConfig provider; PantoCompactionConfig compaction; PantoRetryConfig retry; } PantoConfig;
+
+typedef struct { PantoContentBlockTag block_type; size_t index; } PantoBlockStart;
+typedef struct { size_t index; PantoSlice id, name; } PantoToolDetails;
+typedef struct { size_t index; PantoSlice delta; } PantoContentDelta;
+typedef struct { size_t index; PantoContentBlockTag block_type; } PantoBlockComplete;
+/* One assistant message finished streaming. `message_index` indexes the
+ * agent's live conversation (`panto_agent_conversation`), whose tail is this
+ * message when the event is delivered; fetch its `block_count` blocks from
+ * there for full content. `usage` is the wire-reported token usage. */
+typedef struct { PantoMessageRole role; size_t message_index; size_t block_count; bool has_usage; PantoUsage usage; } PantoMessageComplete;
+typedef struct { bool compacted; size_t kept_turns; size_t summarized_messages; } PantoCompactionResult;
+typedef struct { size_t attempt, max_attempts; uint64_t delay_ms; PantoSlice error_name; bool has_status_code; uint16_t status_code; bool has_retry_after_ms; uint64_t retry_after_ms; PantoSlice message; bool compaction; } PantoProviderRetry;
+typedef struct { size_t count; } PantoToolDispatchStart;
+typedef struct { size_t message_index; } PantoToolDispatchComplete;
+
+typedef struct { PantoEventTag tag; union { PantoMessageRole message_start; PantoBlockStart block_start; PantoToolDetails tool_details; PantoContentDelta content_delta; PantoBlockComplete block_complete; PantoMessageComplete message_complete; PantoProviderRetry provider_retry; PantoToolDispatchStart tool_dispatch_start; PantoToolDispatchComplete tool_dispatch_result; PantoToolDispatchComplete tool_dispatch_complete; } data; } PantoEvent;
+
+/* One content block of a message being appended. A flattened, borrow-only
+ * view: every slice points into the in-memory message and is valid only for
+ * the duration of the append_messages call. `text` carries the Text body,
+ * Thinking text, ToolUse input JSON, concatenated ToolResult text, or
+ * System/CompactionSummary text depending on `tag`. `tool_id` is the ToolUse
+ * id or ToolResult tool_use_id; `tool_name` is the ToolUse name; `is_error`
+ * is the ToolResult error flag; `system_mode` is the System block mode;
+ * `thinking_signature` is the Thinking signature (empty when absent), and the
+ * `thinking_signature_*` fields record the provider/style/model that emitted
+ * it. To replay a thinking block faithfully (Anthropic drops thinking blocks
+ * whose signature lacks a matching origin) a store must persist the signature
+ * AND all three origin fields, then feed them back via the message builder. */
+typedef struct {
+  PantoContentBlockTag tag;
+  PantoSlice text;
+  PantoSlice tool_id;
+  PantoSlice tool_name;
+  bool is_error;
+  PantoSystemMode system_mode;
+  PantoSlice thinking_signature;
+  PantoAPIStyle thinking_signature_api_style;
+  PantoSlice thinking_signature_base_url;
+  PantoSlice thinking_signature_model;
+} PantoOwnedContentBlock;
+
+/* `api_style`/`base_url`/`model`/`reasoning` are the per-message wire identity
+ * (the provider that produced this message), which can drift within a single
+ * conversation (compaction on a different model, a mid-chat model switch). A
+ * store should persist these per message rather than from static config. */
+typedef struct { PantoMessageRole role; bool has_usage; PantoUsage usage; bool has_metadata; PantoSlice metadata; PantoAPIStyle api_style; PantoSlice base_url; PantoSlice model; PantoReasoningEffort reasoning; const PantoOwnedContentBlock *content; size_t content_len; } PantoPersistentMessage;
+
+typedef struct {
+  PantoStatus (*create)(void *ctx, PantoSession **out);
+  PantoStatus (*list)(void *ctx, PantoSessionInfoList *out);
+  void (*free_session_infos)(void *ctx, PantoSessionInfoList infos);
+  PantoStatus (*resolve)(void *ctx, PantoSlice id, PantoSessionResult *out);
+  PantoStatus (*latest)(void *ctx, PantoSessionResult *out);
+  PantoStatus (*load)(void *ctx, PantoSlice id, PantoConversation **out);
+  PantoStatus (*append_messages)(void *ctx, PantoSlice session_id, const PantoPersistentMessage *messages, size_t len);
+  void (*destroy)(void *ctx);
+} PantoSessionStoreVTable;
+
+PANTO_EXPORT void panto_init(void);
+PANTO_EXPORT void panto_deinit(void);
+PANTO_EXPORT PantoSlice panto_last_error(void);
+PANTO_EXPORT void panto_error_free(PantoSlice s);
+PANTO_EXPORT PantoStatus panto_conversation_create(PantoConversation **out);
+PANTO_EXPORT void panto_conversation_destroy(PantoConversation *conversation);
+PANTO_EXPORT size_t panto_conversation_message_count(PantoConversation *conversation);
+PANTO_EXPORT PantoMessageRole panto_conversation_message_role(PantoConversation *conversation, size_t index);
+PANTO_EXPORT bool panto_conversation_message_has_usage(PantoConversation *conversation, size_t index);
+PANTO_EXPORT PantoUsage panto_conversation_message_usage(PantoConversation *conversation, size_t index);
+PANTO_EXPORT size_t panto_conversation_message_block_count(PantoConversation *conversation, size_t message_index);
+PANTO_EXPORT PantoContentBlockTag panto_conversation_block_tag(PantoConversation *conversation, size_t message_index, size_t block_index);
+PANTO_EXPORT PantoSlice panto_conversation_block_text(PantoConversation *conversation, size_t message_index, size_t block_index);
+PANTO_EXPORT PantoSlice panto_conversation_block_tool_id(PantoConversation *conversation, size_t message_index, size_t block_index);
+PANTO_EXPORT PantoSlice panto_conversation_block_tool_name(PantoConversation *conversation, size_t message_index, size_t block_index);
+PANTO_EXPORT bool panto_conversation_block_tool_result_is_error(PantoConversation *conversation, size_t message_index, size_t block_index);
+PANTO_EXPORT PantoSystemMode panto_conversation_block_system_mode(PantoConversation *conversation, size_t message_index, size_t block_index);
+PANTO_EXPORT PantoStatus panto_conversation_add_system_message(PantoConversation *conversation, const char *text);
+PANTO_EXPORT PantoStatus panto_conversation_replace_system_message(PantoConversation *conversation, const char *text);
+PANTO_EXPORT PantoStatus panto_conversation_add_user_text(PantoConversation *conversation, const char *text);
+PANTO_EXPORT PantoStatus panto_conversation_add_assistant_text(PantoConversation *conversation, const char *text, bool has_usage, PantoUsage usage);
+PANTO_EXPORT PantoStatus panto_conversation_add_compaction_summary(PantoConversation *conversation, const char *text);
+
+/* Rich, block-level message builder. Accumulate content blocks, then commit
+ * the whole message to a conversation in one call — the path for rebuilding a
+ * persisted conversation that contains tool calls or thinking. The builder
+ * uses the same allocator as the conversation it is committed to.
+ *
+ * Usage: create -> add_* (one per block, in order) -> conversation_add_message.
+ * `panto_conversation_add_message` ALWAYS consumes the builder (it is freed on
+ * both success and failure); do not destroy it afterwards. Call
+ * `panto_message_builder_destroy` only to discard a builder you never commit.
+ * Each `text`/`signature`/etc. argument is copied. */
+typedef struct PantoMessageBuilder PantoMessageBuilder;
+PANTO_EXPORT PantoMessageBuilder *panto_message_builder_create(PantoMessageRole role);
+PANTO_EXPORT void panto_message_builder_destroy(PantoMessageBuilder *builder);
+PANTO_EXPORT PantoStatus panto_message_builder_add_text(PantoMessageBuilder *builder, const char *text);
+/* `signature` may be NULL/empty when the provider emitted no signature, in
+ * which case the `signature_*` origin args are ignored. When a signature is
+ * supplied you may pass the origin (style/base_url/model) it was produced
+ * under so the block can be replayed; an Anthropic request drops thinking
+ * blocks whose signature origin does not match the request's base_url/model.
+ * The origin args are OPTIONAL: pass PANTO_API_STYLE 0 and NULL base_url/model
+ * to omit them and instead rely on the enclosing message's identity (see
+ * `panto_message_builder_set_identity`), which is the preferred, per-message
+ * source of truth — no per-block identity copy required. */
+PANTO_EXPORT PantoStatus panto_message_builder_add_thinking(PantoMessageBuilder *builder, const char *text, const char *signature, PantoAPIStyle signature_api_style, const char *signature_base_url, const char *signature_model);
+PANTO_EXPORT PantoStatus panto_message_builder_add_tool_use(PantoMessageBuilder *builder, const char *id, const char *name, const char *input);
+PANTO_EXPORT PantoStatus panto_message_builder_add_tool_result(PantoMessageBuilder *builder, const char *tool_use_id, const char *text, bool is_error);
+PANTO_EXPORT PantoStatus panto_message_builder_add_system(PantoMessageBuilder *builder, const char *text, PantoSystemMode mode);
+/* Attach the wire identity (provider/style/model + reasoning) that produced
+ * this message. This is the per-message source of truth for replaying thinking
+ * signatures and is preserved through compaction, so a kept-verbatim turn is
+ * not re-stamped with the compaction model. Strings are copied. Optional; when
+ * omitted, thinking replay relies on each block's own signature origin. */
+PANTO_EXPORT PantoStatus panto_message_builder_set_identity(PantoMessageBuilder *builder, PantoAPIStyle api_style, const char *base_url, const char *model, PantoReasoningEffort reasoning);
+/* Commit the builder's blocks as one message of the builder's role. Consumes
+ * (frees) the builder. `usage` applies to assistant turns; pass has_usage=false
+ * otherwise. */
+PANTO_EXPORT PantoStatus panto_conversation_add_message(PantoConversation *conversation, PantoMessageBuilder *builder, bool has_usage, PantoUsage usage);
+PANTO_EXPORT PantoStatus panto_session_create_null(PantoSession **out);
+PANTO_EXPORT PantoStatus panto_session_create(PantoSessionStore *store, PantoSessionInfo info, PantoSession **out);
+PANTO_EXPORT void panto_session_destroy(PantoSession *session);
+PANTO_EXPORT PantoStatus panto_session_store_create(void *ctx, const PantoSessionStoreVTable *vtable, PantoSessionStore **out);
+PANTO_EXPORT void panto_session_store_destroy(PantoSessionStore *store);
+PANTO_EXPORT PantoStatus panto_null_store_create(PantoSessionStore **out);
+PANTO_EXPORT PantoStatus panto_file_system_jsonl_store_create(const char *dir, const char *metadata, PantoSessionStore **out);
+PANTO_EXPORT PantoStatus panto_session_store_create_session(PantoSessionStore *store, PantoSession **out);
+PANTO_EXPORT PantoStatus panto_session_store_list(PantoSessionStore *store, PantoSessionInfoList *out);
+PANTO_EXPORT void panto_session_info_list_destroy(PantoSessionInfoList infos);
+PANTO_EXPORT PantoStatus panto_session_store_resolve(PantoSessionStore *store, const char *id, PantoSessionResult *out);
+PANTO_EXPORT PantoStatus panto_session_store_latest(PantoSessionStore *store, PantoSessionResult *out);
+PANTO_EXPORT PantoStatus panto_session_load(PantoSession *session, PantoConversation **out);
+PANTO_EXPORT PantoStatus panto_agent_create(const PantoConfig *config, PantoSession *session, PantoConversation *conversation, PantoAgent **out);
+PANTO_EXPORT PantoConversation *panto_agent_conversation(PantoAgent *agent);
+PANTO_EXPORT void panto_agent_destroy(PantoAgent *agent);
+PANTO_EXPORT PantoSlice panto_agent_session_id(PantoAgent *agent);
+PANTO_EXPORT PantoStatus panto_agent_set_config(PantoAgent *agent, const PantoConfig *config);
+PANTO_EXPORT PantoStatus panto_agent_add_system_message(PantoAgent *agent, const char *text);
+PANTO_EXPORT PantoStatus panto_agent_set_system_prompt(PantoAgent *agent, const char *text);
+PANTO_EXPORT PantoStatus panto_agent_compact(PantoAgent *agent, const char *override_system_prompt, const char *extra_instructions, PantoCompactionResult *out);
+/* Open a turn from a user-role message built with the PantoMessageBuilder API
+ * (the same builder used to rebuild persisted messages): one `add_text` block
+ * for a plain chat turn, or `add_tool_result` blocks to resume after the
+ * embedder handled tool calls itself. Consumes `user_message` (the builder is
+ * destroyed); do not reuse or destroy it afterwards. */
+PANTO_EXPORT PantoStatus panto_agent_run(PantoAgent *agent, PantoMessageBuilder *user_message, PantoStream **out);
+/* Reset a failed stream back to its turn-open boundary so the caller can
+ * resume panto_stream_next() after changing the agent config (e.g. catch a
+ * terminal bad-request, swap the provider config, and retry the SAME turn
+ * without re-appending the user message). Errors if the stream has not
+ * failed. */
+PANTO_EXPORT PantoStatus panto_stream_reopen(PantoStream *stream);
+PANTO_EXPORT void panto_stream_destroy(PantoStream *stream);
+PANTO_EXPORT PantoNextStatus panto_stream_next(PantoStream *stream, PantoEvent *out);
+PANTO_EXPORT void panto_event_free(PantoEvent *event);
+
+/* Go/callback-oriented tool ABI. */
+typedef struct { PantoSlice name, description, schema_json; } PantoToolDecl;
+typedef struct { PantoSlice media_type; bool has_media_type; PantoSlice data; } PantoMediaPart;
+typedef enum { PANTO_RESULT_TEXT = 0, PANTO_RESULT_MEDIA = 1 } PantoResultPartTag;
+typedef struct { PantoResultPartTag tag; union { PantoSlice text; PantoMediaPart media; } data; } PantoResultPart;
+typedef struct { PantoResultPart *ptr; size_t len; } PantoResultParts;
+typedef struct { PantoSlice tool_name, input; } PantoToolCall;
+typedef struct { bool ok; PantoResultParts parts; PantoSlice error; } PantoToolCallResult;
+typedef PantoStatus (*PantoToolInvokeFn)(void *ctx, PantoSlice input, PantoResultParts *out);
+typedef PantoStatus (*PantoToolSourceInvokeBatchFn)(void *ctx, const PantoToolCall *calls, PantoToolCallResult *results, size_t len);
+typedef void (*PantoToolDestroyFn)(void *ctx);
+PANTO_EXPORT PantoStatus panto_agent_register_tool(PantoAgent *agent, PantoToolDecl decl, void *ctx, PantoToolInvokeFn invoke, PantoToolDestroyFn destroy);
+PANTO_EXPORT PantoStatus panto_agent_register_tool_source(PantoAgent *agent, PantoSlice name, const PantoToolDecl *decls, size_t len, void *ctx, PantoToolSourceInvokeBatchFn invoke_batch, PantoToolDestroyFn destroy);
+PANTO_EXPORT PantoResultParts panto_result_parts_text(const char *text);
+PANTO_EXPORT void panto_result_parts_destroy(PantoResultParts parts);
+#ifdef __cplusplus
+}
+#endif
+#endif