xonecas.io
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