7814
Ta
tiny-c-agent / files
tiny-c-agent / src / provider.h
3.2 KB
1// tiny providers: the uniform streaming contract of every API format. 2// 3// Each adapter under src/api/ implements one wire format behind 4// tiny_provider_stream(). Callers pass a resolved model, the transcript, and a 5// cancel flag; the adapter emits deltas and returns the final assistant message. 6 7#ifndef TINY_PROVIDER_H 8#define TINY_PROVIDER_H 9 10#include <stdbool.h> 11#include <stddef.h> 12 13#include "config.h" 14#include "message.h" 15 16typedef struct { 17 const char *provider; // provider id, echoed into the response metadata 18 const char *model; // model id sent on the wire 19 const char *base_url; // API root, without the endpoint path 20 tiny_api api; 21 const char *api_key; // NULL when the endpoint needs no key 22 // The effort actually sent, after clamping the configured desire to what 23 // the model accepts. NULL lets the provider decide. 24 const char *effort; 25 // Whether the model accepts image input. Gates whether `read` attaches 26 // images. The generated catalog will set this per model. 27 bool supports_images; 28 // The largest reply the model accepts, from the catalog. 0 when unknown. 29 // The context readout uses it to tell when the next request could not fit. 30 long max_tokens; 31 // Providers that route by conversation send this header with the session 32 // id. NULL when the provider does not need one. 33 const char *session_header; 34} tiny_model; 35 36typedef struct { 37 const char *name; 38 const char *description; 39 const char *parameters; // a JSON Schema object string 40} tiny_tool; 41 42typedef struct { 43 const char *system_prompt; // NULL or empty to omit 44 const tiny_tool *tools; 45 size_t tools_len; 46 const tiny_message *messages; 47 size_t messages_len; 48} tiny_context; 49 50typedef struct { 51 const char *effort; // NULL to let the provider decide; off/…/max otherwise 52 long max_tokens; // 0 to omit 53 const char *session_id; // NULL to omit 54} tiny_stream_opts; 55 56typedef enum { 57 TINY_STREAM_TEXT_DELTA, 58 TINY_STREAM_REASONING_DELTA, 59 TINY_STREAM_TOOL_CALL_START, // a tool call block began; name is known 60 TINY_STREAM_TOOL_CALL, // a tool call block finished 61} tiny_stream_type; 62 63typedef struct { 64 tiny_stream_type type; 65 const char *delta; // delta events, borrowed for the callback 66 const char *tool_call_id; // TOOL_CALL 67 const char *tool_name; // TOOL_CALL 68 const char *tool_arguments; // TOOL_CALL, a JSON object string 69} tiny_stream_event; 70 71typedef void (*tiny_stream_fn)(const tiny_stream_event *event, void *user); 72 73// Runs one streaming request. Deltas go through emit; out receives the final 74// assistant message (blocks, stop_reason, usage). Returns 0 when the request 75// completed, even if the model stopped with "error" or "aborted" (recorded in 76// out->stop_reason), and -1 with *err set on a transport or protocol failure. 77// The cancel flag is polled for prompt aborts and may be NULL. 78int tiny_provider_stream(const tiny_model *model, const tiny_context *ctx, 79 const tiny_stream_opts *opts, 80 tiny_stream_fn emit, void *user, 81 const volatile bool *cancel, 82 tiny_message *out, char **err); 83 84#endif