@@ -1,20 +1,12 @@
1-//! The provider contract: one streaming request in, one assistant message out,
2-//! with deltas delivered through a sink.
3-
41 const std = @import("std");
52 const types = @import("types.zig");
63 const http = @import("http.zig");
74 const util = @import("util.zig");
85
96 pub const Event = union(enum) {
10- /// Assistant text delta.
117 text: []const u8,
12- /// Reasoning delta.
138 reasoning: []const u8,
14- /// A tool call block began; the name is known but arguments have not
15- /// finished streaming.
169 tool_start: []const u8,
17- /// A tool call block finished.
1810 tool_call: types.ToolCall,
1911 };
2012
@@ -27,8 +19,6 @@ pub const Sink = struct {
2719 }
2820 };
2921
30-/// JSON written byte-for-byte as it stands, never re-encoded. The struct field
31-/// that holds it supplies the key.
3222 pub const Raw = struct {
3323 bytes: []const u8 = "",
3424
@@ -39,8 +29,6 @@ pub const Raw = struct {
3929 }
4030 };
4131
42-/// A provider error value: a message string, or an object carrying one under
43-/// "message". An empty string is no error at all.
4432 pub const ErrField = struct {
4533 message: ?[]const u8 = null,
4634
@@ -59,7 +47,6 @@ pub const ErrField = struct {
5947 }
6048 };
6149
62-/// A token count a provider may send as an integer or a float.
6350 pub const Count = struct {
6451 value: u64 = 0,
6552
@@ -75,13 +62,10 @@ pub const Count = struct {
7562 };
7663
7764 pub const Request = struct {
78- /// Long-lived allocator: the returned message's content outlives the step.
7965 pers: std.mem.Allocator,
80- /// Per-step arena: the request body and each parsed event. Reset freely.
8166 scratch: std.mem.Allocator,
8267 model: *const types.Model,
8368 system_prompt: []const u8,
84- /// A pre-serialized JSON array of tool schemas, verbatim.
8569 tools_json: []const u8,
8670 messages: []const types.Message,
8771 effort: []const u8,
@@ -89,35 +73,17 @@ pub const Request = struct {
8973 cancel: *const std.atomic.Value(bool),
9074 };
9175
92-/// An untrusted stream index is a hint, never a size. Anything past this is
93-/// treated like a missing index so a hostile chunk cannot force an allocation.
9476 pub const max_stream_index = 10_000;
9577
96-/// How one wire reaches its provider: the URL, the key header, and the body
97-/// encoder. Everything else about the request is the same for all four.
9878 pub const Wire = struct {
99- /// The header the api key travels in, and the prefix its value carries.
100- /// An empty key sends no header at all.
10179 key_header: []const u8,
10280 key_prefix: []const u8 = "",
103- /// A protocol version header, sent verbatim when its name is not empty.
10481 version: [2][]const u8 = .{ "", "" },
105- /// The path appended to the model's base URL, after any trailing slash.
106- /// `build_url` overrides it for a provider whose URL is not base plus path.
10782 path: []const u8 = "",
10883 build_url: ?*const fn (std.mem.Allocator, Request) anyerror![]u8 = null,
10984 build_body: *const fn (Request) anyerror![]u8,
11085 };
11186
112-/// The request life cycle every wire shares, over a `State` that carries
113-/// `req`, `sink`, `arena`, `msg`, `stream_error` and `failed`, and handles each
114-/// payload through `State.handle`. `finalize` moves the accumulated state into
115-/// `msg`.
116-///
117-/// A stream that fails or is cancelled still finalizes first: the text the
118-/// model did stream belongs in the transcript, and dropping it would lose a
119-/// turn the user can see and cannot recover. A tool call whose arguments never
120-/// finished is not emitted, so a partial call is never handed to a tool.
12187 pub fn run(
12288 comptime State: type,
12389 comptime Chunk: type,
@@ -140,10 +106,6 @@ pub fn run(
140106
141107 var st = State{ .req = req, .sink = sink, .arena = &arena, .msg = &msg };
142108
143- // A stream that did not run to the end can leave a tool call with a name
144- // but truncated arguments. Such a call is not a call the model finished
145- // making, so `finalize` drops it rather than emit arguments to run; the
146- // transport's own stop reason is the one the message keeps.
147109 const complete = try post(req, url, hdrs, body, .{ .ctx = &st, .onEvent = onData(State, Chunk) }, &msg);
148110 st.failed = !complete;
149111 const reason = msg.stop_reason;
@@ -161,16 +123,11 @@ pub fn run(
161123 return msg;
162124 }
163125
164-/// The SSE hook every wire shares: parse one payload into the wire's `Chunk`
165-/// type and hand it to `State.handle`. The arena is reset before the next
166-/// payload, so nothing may keep a pointer into the chunk.
167126 fn onData(comptime State: type, comptime Chunk: type) *const fn (ctx: *anyopaque, data: []const u8) void {
168127 return struct {
169128 fn hook(ctx: *anyopaque, data: []const u8) void {
170129 const st: *State = @ptrCast(@alignCast(ctx));
171130 defer _ = st.arena.reset(.retain_capacity);
172- // The sentinel OpenAI-compatible streams send in place of a final
173- // event. It is not JSON, and it is not a failure.
174131 if (std.mem.eql(u8, std.mem.trim(u8, data, " \r\n"), "[DONE]")) return;
175132 const chunk = std.json.parseFromSliceLeaky(Chunk, st.arena.allocator(), data, .{ .ignore_unknown_fields = true }) catch |e| {
176133 if (e != error.OutOfMemory and st.stream_error == null) st.stream_error = "stream: invalid JSON chunk";
@@ -183,9 +140,6 @@ fn onData(comptime State: type, comptime Chunk: type) *const fn (ctx: *anyopaque
183140 }.hook;
184141 }
185142
186-/// Grows `list` so `index` exists, and returns the element there. An untrusted
187-/// stream index is a hint, never a size: anything outside the sane range
188-/// appends instead, so a hostile chunk cannot force an allocation.
189143 pub fn blockAt(comptime T: type, list: *std.ArrayList(T), a: std.mem.Allocator, index: i64) !*T {
190144 const idx: usize = if (index >= 0 and index <= max_stream_index)
191145 @intCast(index)
@@ -195,9 +149,6 @@ pub fn blockAt(comptime T: type, list: *std.ArrayList(T), a: std.mem.Allocator,
195149 return &list.items[idx];
196150 }
197151
198-/// Runs one streaming request. Transport and protocol failures are recorded in
199-/// the returned message's `stop_reason`/`error_message`; only a failure to
200-/// allocate is an error.
201152 pub fn stream(req: Request, sink: Sink) std.mem.Allocator.Error!types.AssistantMessage {
202153 if (std.mem.eql(u8, req.model.api, "openai-completions")) {
203154 return @import("api/openai_completions.zig").stream(req, sink);
@@ -227,9 +178,6 @@ fn newAssistant(req: Request) types.AssistantMessage {
227178 };
228179 }
229180
230-/// The header list every request shares: content negotiation, the wire's own
231-/// key and version headers, then the caller's custom and session headers. A
232-/// header with an empty value is left out entirely.
233181 fn wireHeaders(a: std.mem.Allocator, req: Request, wire: Wire) ![]http.Header {
234182 var list: std.ArrayList(http.Header) = .empty;
235183 errdefer list.deinit(a);
@@ -257,9 +205,6 @@ fn wireHeaders(a: std.mem.Allocator, req: Request, wire: Wire) ![]http.Header {
257205 return list.toOwnedSlice(a);
258206 }
259207
260-/// Sends the request and maps a transport failure onto `msg`. Returns false
261-/// once the caller must return `msg` as-is; true when the stream completed and
262-/// the caller should proceed to finalize.
263208 fn post(req: Request, url: []const u8, hdrs: []const http.Header, body: []const u8, handler: http.SseHandler, msg: *types.AssistantMessage) std.mem.Allocator.Error!bool {
264209 var err_body: ?[]const u8 = null;
265210 http.postSse(req.scratch, url, hdrs, body, handler, req.cancel, &err_body) catch |e| {
@@ -284,17 +229,13 @@ fn post(req: Request, url: []const u8, hdrs: []const http.Header, body: []const
284229 return true;
285230 }
286231
287-/// One tool call as the provider streams it. The wires differ only in where
288-/// the pieces arrive; the shape and the accumulation are the same.
289232 pub const Call = struct {
290233 id: []const u8 = "",
291234 name: []const u8 = "",
292235 args: std.ArrayList(u8) = .empty,
293236 started: bool = false,
294- /// Google's continuation data, replayed on the next request.
295237 thought_signature: ?[]const u8 = null,
296238
297- /// Records the name and announces the call the first time one arrives.
298239 pub fn announce(self: *Call, a: std.mem.Allocator, sink: Sink, name: []const u8) !void {
299240 if (self.name.len == 0) self.name = try a.dupe(u8, name);
300241 if (!self.started and self.name.len > 0) {
@@ -304,9 +245,6 @@ pub const Call = struct {
304245 }
305246 };
306247
307-/// Appends every call the stream finished with, and says whether there was
308-/// one. A stream that failed left arguments truncated, so its calls are
309-/// dropped: a partial call is not a call the model finished making.
310248 pub fn appendCalls(msg: *types.AssistantMessage, sink: Sink, a: std.mem.Allocator, calls: []const Call, failed: bool) !bool {
311249 if (failed) return false;
312250 var any = false;
@@ -328,13 +266,10 @@ pub fn appendCalls(msg: *types.AssistantMessage, sink: Sink, a: std.mem.Allocato
328266 return any;
329267 }
330268
331-/// A call's arguments, or an empty object when the provider streamed none.
332269 pub fn argumentsOrObject(args: []const u8) []const u8 {
333270 return if (args.len > 0) args else "{}";
334271 }
335272
336-/// Records the tokens a response cost and prices them. The total is the
337-/// provider's own when it reported one, and the sum of the parts otherwise.
338273 pub fn finishUsage(msg: *types.AssistantMessage, model: *const types.Model, usage: types.Usage) void {
339274 var u = usage;
340275 if (u.total_tokens == 0) u.total_tokens = u.input + u.output + u.cache_read + u.cache_write;
@@ -350,7 +285,6 @@ pub fn finishUsage(msg: *types.AssistantMessage, model: *const types.Model, usag
350285 msg.usage = u;
351286 }
352287
353-/// A non-empty string field, or null.
354288 pub fn stringField(obj: std.json.ObjectMap, key: []const u8) ?[]const u8 {
355289 const v = obj.get(key) orelse return null;
356290 return switch (v) {
@@ -359,11 +293,6 @@ pub fn stringField(obj: std.json.ObjectMap, key: []const u8) ?[]const u8 {
359293 };
360294 }
361295
362-/// How one provider frames its `tools` array value: `open` and `close` bound
363-/// it, and each element is `entry` wrapped around the call's schema under
364-/// `params_key`. The key `"tools"` is supplied by the struct field that holds
365-/// the value. A provider with no tools writes nothing at all, which is also how
366-/// an unparsable `tools_json` is treated.
367296 pub const ToolsForm = struct {
368297 open: []const u8,
369298 entry: []const u8,
@@ -372,9 +301,6 @@ pub const ToolsForm = struct {
372301 close: []const u8,
373302 };
374303
375-/// A request's `tools` array, rendered verbatim from the flat `tools_json` the
376-/// session recorded, in the wire form `form` describes. It is written as an
377-/// array value, so the caller's struct field supplies the key.
378304 pub const Tools = struct {
379305 a: std.mem.Allocator,
380306 json: []const u8,
@@ -387,9 +313,6 @@ pub const Tools = struct {
387313 }
388314 };
389315
390-/// Writes the `tools` array in the wire form `form` describes, from the flat
391-/// `tools_json` array the session recorded. Nothing at all is written when
392-/// there is no tool, which is also how an unparsable `tools_json` is treated.
393316 pub fn writeTools(w: *std.Io.Writer, a: std.mem.Allocator, tools_json: []const u8, form: ToolsForm) !void {
394317 if (tools_json.len == 0) return;
395318 const root = std.json.parseFromSliceLeaky(std.json.Value, a, tools_json, .{}) catch return;
@@ -411,9 +334,6 @@ pub fn writeTools(w: *std.Io.Writer, a: std.mem.Allocator, tools_json: []const u
411334 try w.writeAll(form.close);
412335 }
413336
414-/// `"name":"…","description":"…","<params_key>":<schema>` — the body every
415-/// provider's tool encoding shares. A schema that names no parameters is sent
416-/// as `{}` rather than panicking on a session log written by another version.
417337 fn writeToolBody(w: *std.Io.Writer, obj: std.json.ObjectMap, params_key: []const u8) !void {
418338 try w.writeAll("\"name\":");
419339 try std.json.Stringify.encodeJsonString(stringField(obj, "name") orelse "", .{}, w);
@@ -429,7 +349,6 @@ fn writeToolBody(w: *std.Io.Writer, obj: std.json.ObjectMap, params_key: []const
429349 }
430350 }
431351
432-/// `base_url` plus one path segment, with a trailing slash on the base ignored.
433352 fn buildUrl(a: std.mem.Allocator, base: []const u8, path: []const u8) ![]u8 {
434353 return std.fmt.allocPrint(a, "{s}{s}", .{ std.mem.trimEnd(u8, base, "/"), path });
435354 }