Skip to content
1        10        20        30        40        50        60        70        80        90        100       110       120       130       140       150       160       170       180       190       200       210       220       230       240       250       260       270       280       290       300       310       3201//! The chat agent. One call to `answer` is one request: it opens a private lake2//! session, lets the model query it through two tools, and returns the answer3//! along with every query that ran.45const std = @import("std");6const Config = @import("config.zig").Config;7const llm = @import("llm.zig");8const session = @import("session.zig");910const log = std.log.scoped(.chat);1112const max_steps = 8;13const max_rows_for_model = 50;14const max_cell_chars = 120;15/// Keeps one chat inside the reverse proxy's request timeout. A query cannot be16/// checked while it runs, so this budget is tested between steps.17const max_answer_ms = 45_000;18const too_slow_text = "That question needs more match data than I can look through at once. Try a recent period, such as the last day or week.";1920pub const Message = struct {21    role: []const u8,22    content: []const u8,23};2425pub const Answer = struct {26    text: []const u8,27    queries: []const session.QueryOutput,28};2930const system_prompt =31    \\You are Totenschloss, a friendly guide to Deadlock (Valve's hero shooter) statistics.32    \\People chatting with you are players, not engineers. Talk like a knowledgeable fan:33    \\plain words, short answers, the key numbers.34    \\35    \\Behind the scenes you can look things up with the tools: describe_tables shows what data exists,36    \\and run_sql runs a read-only query. Use them freely, but never show that machinery in your replies:37    \\no code, no SQL, no table or column names, no error messages, no talk of databases or permissions.38    \\If a lookup fails, quietly try another way or say that you could not find that information.39    \\40    \\Data notes for yourself (never repeat them as jargon):41    \\- lake.leaderboard and lake.hero_leaderboard are small; query them directly.42    \\- lake.match_player is enormous: hundreds of millions of player rows across hundreds of gigabytes.43    \\  Only query it with a recent start_time window (for example WHERE start_time > now() - INTERVAL 1 DAY)44    \\  or a narrow match_id range. A full-history scan cannot finish.45    \\- lake.match_player_latest removes duplicate rows, but it reads the whole match history before filtering.46    \\  Never use it without a start_time or match_id filter.47    \\- When a question spans matches and does not name a period ("which heroes win the most games?",48    \\  "who wins the most?"), use the last 24 hours and say which period you used. If someone asks for all49    \\  time, explain that a full-history scan is too large and offer the last day or week instead.50    \\- Wins are rows where won is true; games are all rows. Aggregate rather than listing raw rows; you see 50 at a time.51    \\52    \\How to reply:53    \\- Answer the question directly, with the numbers people care about, in a sentence or a short list.54    \\- If the question is vague, ask one simple follow-up question, for example "Do you mean the top players of this season or of all time?"55    \\- When a player asks what you can do, suggest questions in everyday words, such as "Who are the top players in Europe?",56    \\  "Which heroes win the most games?", or "What have player 12345 been playing lately?"57    \\- Say when numbers are approximate or incomplete. Do not invent data.58    \\- Reply in the language the player writes in.59;6061const tools_json =62    \\[{"name":"describe_tables","description":"List the lake tables with their columns and types. Call it before writing SQL against a table you have not described yet in this conversation.","input_schema":{"type":"object","properties":{},"additionalProperties":false}},63    \\{"name":"run_sql","description":"Run one read-only DuckDB SELECT against lake.<table>. You receive at most 50 rows, so aggregate in SQL and use LIMIT.","input_schema":{"type":"object","properties":{"sql":{"type":"string","description":"A single SELECT statement."}},"required":["sql"],"additionalProperties":false}}]64;6566/// Answers `question` with the model, given earlier turns in `history`.67/// `history` must already be validated (roles user/assistant, non-empty content).68pub fn answer(69    allocator: std.mem.Allocator,70    cfg: *const Config,71    model: *llm.Client,72    history: []const Message,73    question: []const u8,74) !Answer {75    var sess = try session.Session.open(allocator, cfg);76    defer sess.deinit();77    return converse(allocator, model, &sess, history, question);78}7980/// The agent loop, with the model and the tool session left generic so tests can81/// supply fakes instead of a network model and a real lake.82fn converse(83    allocator: std.mem.Allocator,84    model: anytype,85    sess: anytype,86    history: []const Message,87    question: []const u8,88) !Answer {89    var conversation = std.ArrayList([]const u8).init(allocator);90    for (history) |turn| {91        try conversation.append(try std.json.stringifyAlloc(allocator, turn, .{}));92    }93    try conversation.append(try std.json.stringifyAlloc(allocator, Message{ .role = "user", .content = question }, .{}));9495    var queries = std.ArrayList(session.QueryOutput).init(allocator);96    const started_ms = std.time.milliTimestamp();97    var step: usize = 0;98    while (step < max_steps) : (step += 1) {99        if (std.time.milliTimestamp() - started_ms >= max_answer_ms) {100            log.warn("answer budget reached for question: {s}", .{question});101            return .{ .text = too_slow_text, .queries = queries.items };102        }103        const reply = try model.complete(allocator, system_prompt, tools_json, conversation.items);104        if (reply.tool_uses.len == 0) {105            return .{ .text = reply.text, .queries = queries.items };106        }107108        const content_json = try std.json.stringifyAlloc(allocator, reply.content, .{});109        try conversation.append(try std.fmt.allocPrint(allocator, "{{\"role\":\"assistant\",\"content\":{s}}}", .{content_json}));110111        var results = std.ArrayList(u8).init(allocator);112        const writer = results.writer();113        try writer.writeAll("{\"role\":\"user\",\"content\":[");114        for (reply.tool_uses, 0..) |tool_use, index| {115            if (index > 0) try writer.writeByte(',');116            const outcome = try runTool(allocator, sess, tool_use, &queries);117            try writer.writeAll("{\"type\":\"tool_result\",\"tool_use_id\":");118            try std.json.stringify(tool_use.id, .{}, writer);119            try writer.writeAll(",\"content\":");120            try std.json.stringify(outcome.text, .{}, writer);121            if (outcome.is_error) try writer.writeAll(",\"is_error\":true");122            try writer.writeByte('}');123        }124        try writer.writeAll("]}");125        try conversation.append(results.items);126    }127128    log.warn("step limit reached for question: {s}", .{question});129    return .{130        .text = "I could not reach an answer within the step limit. Try a narrower question.",131        .queries = queries.items,132    };133}134135const ToolOutcome = struct {136    text: []const u8,137    is_error: bool,138};139140fn runTool(141    allocator: std.mem.Allocator,142    sess: anytype,143    tool_use: llm.ToolUse,144    queries: *std.ArrayList(session.QueryOutput),145) !ToolOutcome {146    if (std.mem.eql(u8, tool_use.name, "describe_tables")) {147        return .{ .text = try sess.describe(allocator), .is_error = false };148    }149    if (std.mem.eql(u8, tool_use.name, "run_sql")) {150        const sql = sqlArgument(tool_use.input) orelse151            return .{ .text = "run_sql needs a non-empty \"sql\" string", .is_error = true };152        const output = try sess.runQuery(allocator, sql);153        try queries.append(output);154        if (output.error_message) |message| return .{ .text = message, .is_error = true };155        return .{ .text = try formatForModel(allocator, output), .is_error = false };156    }157    return .{ .text = "unknown tool", .is_error = true };158}159160fn sqlArgument(input: std.json.Value) ?[]const u8 {161    const object = switch (input) {162        .object => |object| object,163        else => return null,164    };165    const sql = switch (object.get("sql") orelse return null) {166        .string => |text| text,167        else => return null,168    };169    return if (std.mem.trim(u8, sql, " \t\r\n").len == 0) null else sql;170}171172/// Renders a query result as a small pipe-separated table for the model.173fn formatForModel(allocator: std.mem.Allocator, output: session.QueryOutput) ![]const u8 {174    var out = std.ArrayList(u8).init(allocator);175    const writer = out.writer();176177    for (output.columns, 0..) |column, index| {178        if (index > 0) try writer.writeAll(" | ");179        try writer.writeAll(column);180    }181    try writer.writeByte('\n');182183    const shown = @min(output.rows.len, max_rows_for_model);184    for (output.rows[0..shown]) |row| {185        for (row, 0..) |cell, index| {186            if (index > 0) try writer.writeAll(" | ");187            const text = cell orelse "NULL";188            try writer.writeAll(if (text.len > max_cell_chars) text[0..max_cell_chars] else text);189        }190        try writer.writeByte('\n');191    }192193    if (output.total_rows > shown) {194        try writer.print("({d} rows in total, showing the first {d})\n", .{ output.total_rows, shown });195    } else {196        try writer.print("({d} rows)\n", .{output.total_rows});197    }198    return out.items;199}200201const testing = std.testing;202203test "formatForModel renders a pipe table with NULLs" {204    var arena = std.heap.ArenaAllocator.init(testing.allocator);205    defer arena.deinit();206207    const rows = [_][]const ?[]const u8{208        &.{ "Abrams", "12", null },209        &.{ "Bebop", "3", "mvp" },210    };211    const text = try formatForModel(arena.allocator(), .{212        .sql = "SELECT hero, games, note FROM somewhere",213        .columns = &.{ "hero", "games", "note" },214        .rows = rows[0..],215        .total_rows = 2,216    });217    try testing.expectEqualStrings(218        "hero | games | note\nAbrams | 12 | NULL\nBebop | 3 | mvp\n(2 rows)\n",219        text,220    );221}222223test "formatForModel truncates long cells and caps the rows shown" {224    var arena = std.heap.ArenaAllocator.init(testing.allocator);225    defer arena.deinit();226    const a = arena.allocator();227228    const long = "x" ** (max_cell_chars + 10);229    const long_rows = [_][]const ?[]const u8{&.{long}};230    const truncated = try formatForModel(a, .{231        .sql = "SELECT note",232        .columns = &.{"note"},233        .rows = long_rows[0..],234        .total_rows = 1,235    });236    try testing.expect(std.mem.indexOf(u8, truncated, "x" ** max_cell_chars) != null);237    try testing.expect(std.mem.indexOf(u8, truncated, "x" ** (max_cell_chars + 1)) == null);238239    var cells = [_]?[]const u8{"value"};240    var many_rows: [max_rows_for_model + 10][]const ?[]const u8 = undefined;241    for (&many_rows) |*row| row.* = &cells;242    const capped = try formatForModel(a, .{243        .sql = "SELECT value FROM many",244        .columns = &.{"value"},245        .rows = many_rows[0..],246        .total_rows = max_rows_for_model + 10,247    });248    const note = try std.fmt.allocPrint(249        a,250        "({d} rows in total, showing the first {d})\n",251        .{ max_rows_for_model + 10, max_rows_for_model },252    );253    try testing.expect(std.mem.endsWith(u8, capped, note));254255    // One header line, the capped body, and the note.256    var lines = std.mem.splitScalar(u8, std.mem.trimRight(u8, capped, "\n"), '\n');257    var line_count: usize = 0;258    while (lines.next()) |_| line_count += 1;259    try testing.expectEqual(max_rows_for_model + 2, line_count);260}261262test "formatForModel handles a query with no rows" {263    var arena = std.heap.ArenaAllocator.init(testing.allocator);264    defer arena.deinit();265    const text = try formatForModel(arena.allocator(), .{266        .sql = "SELECT 1 WHERE false",267        .columns = &.{"answer"},268        .rows = &.{},269        .total_rows = 0,270    });271    try testing.expectEqualStrings("answer\n(0 rows)\n", text);272}273274test "sqlArgument only accepts a non-empty string parameter" {275    var arena = std.heap.ArenaAllocator.init(testing.allocator);276    defer arena.deinit();277    const a = arena.allocator();278279    var object = std.json.ObjectMap.init(a);280    try object.put("sql", .{ .string = "SELECT 1" });281    try testing.expectEqualStrings("SELECT 1", sqlArgument(.{ .object = object }).?);282283    object.put("sql", .{ .string = "  \n\t " }) catch unreachable;284    try testing.expect(sqlArgument(.{ .object = object }) == null);285286    object.put("sql", .{ .integer = 1 }) catch unreachable;287    try testing.expect(sqlArgument(.{ .object = object }) == null);288289    const empty = std.json.ObjectMap.init(a);290    try testing.expect(sqlArgument(.{ .object = empty }) == null);291    try testing.expect(sqlArgument(.null) == null);292    try testing.expect(sqlArgument(.{ .string = "SELECT 1" }) == null);293}294295// ---- Agent loop tests, with a fake model and a fake lake session -------------296297const FakeModel = struct {298    replies: []const llm.Reply,299    index: usize = 0,300    calls: usize = 0,301    last_count: usize = 0,302    last_message: []const u8 = "",303304    fn complete(305        self: *FakeModel,306        allocator: std.mem.Allocator,307        system: []const u8,308        tool_definitions: []const u8,309        messages: []const []const u8,310    ) !llm.Reply {311        _ = allocator;312        _ = system;313        _ = tool_definitions;314        self.calls += 1;315        self.last_count = messages.len;316        self.last_message = messages[messages.len - 1];317        const reply = self.replies[@min(self.index, self.replies.len - 1)];318        if (self.index < self.replies.len) self.index += 1;319        return reply;320    }321};322323const FakeSession = struct {324    describe_calls: usize = 0,325    query_calls: usize = 0,326    last_sql: []const u8 = "",327    output: session.QueryOutput = .{ .sql = "" },328329    fn describe(self: *FakeSession, allocator: std.mem.Allocator) ![]const u8 {330        _ = allocator;331        self.describe_calls += 1;332        return "lake.heroes (id INTEGER)";333    }334335    fn runQuery(self: *FakeSession, allocator: std.mem.Allocator, sql: []const u8) !session.QueryOutput {336        _ = allocator;337        self.query_calls += 1;338        self.last_sql = sql;339        var output = self.output;340        output.sql = sql;341        return output;342    }343};344345fn textReply(allocator: std.mem.Allocator, text: []const u8) !llm.Reply {346    return .{347        .content = try std.json.parseFromSliceLeaky(std.json.Value, allocator, "[]", .{}),348        .text = text,349        .tool_uses = &.{},350    };351}352353fn toolReply(354    allocator: std.mem.Allocator,355    id: []const u8,356    name: []const u8,357    input_json: []const u8,358) !llm.Reply {359    const uses = try allocator.alloc(llm.ToolUse, 1);360    uses[0] = .{361        .id = id,362        .name = name,363        .input = try std.json.parseFromSliceLeaky(std.json.Value, allocator, input_json, .{}),364    };365    return .{366        .content = try std.json.parseFromSliceLeaky(std.json.Value, allocator, "[]", .{}),367        .text = "",368        .tool_uses = uses,369    };370}371372fn userMessageText(allocator: std.mem.Allocator, message: []const u8) ![]const u8 {373    const value = try std.json.parseFromSliceLeaky(std.json.Value, allocator, message, .{});374    return value.object.get("content").?.string;375}376377test "converse answers a plain question without opening the lake session" {378    var arena = std.heap.ArenaAllocator.init(testing.allocator);379    defer arena.deinit();380    const a = arena.allocator();381382    const history = [_]Message{383        .{ .role = "user", .content = "hello" },384        .{ .role = "assistant", .content = "hi, ask me about Deadlock" },385    };386    var model = FakeModel{ .replies = &.{try textReply(a, "42 players.")} };387    var sess = FakeSession{};388389    const result = try converse(a, &model, &sess, &history, "how many players?");390    try testing.expectEqualStrings("42 players.", result.text);391    try testing.expectEqual(@as(usize, 0), result.queries.len);392    try testing.expectEqual(@as(usize, 1), model.calls);393    try testing.expectEqual(@as(usize, 3), model.last_count);394    try testing.expectEqual(@as(usize, 0), sess.query_calls);395    try testing.expectEqualStrings("how many players?", try userMessageText(a, model.last_message));396}397398test "converse runs run_sql and feeds the formatted rows back to the model" {399    var arena = std.heap.ArenaAllocator.init(testing.allocator);400    defer arena.deinit();401    const a = arena.allocator();402403    var sess = FakeSession{ .output = .{404        .sql = "",405        .columns = &.{"n"},406        .rows = &.{&.{"1"}},407        .total_rows = 1,408    } };409    var model = FakeModel{ .replies = &.{410        try toolReply(a, "toolu_1", "run_sql", "{\"sql\":\"SELECT 1 AS n\"}"),411        try textReply(a, "There is one row."),412    } };413414    const result = try converse(a, &model, &sess, &.{}, "how many?");415    try testing.expectEqualStrings("There is one row.", result.text);416    try testing.expectEqual(@as(usize, 1), result.queries.len);417    try testing.expectEqual(@as(usize, 1), sess.query_calls);418    try testing.expectEqualStrings("SELECT 1 AS n", sess.last_sql);419    try testing.expect(std.mem.indexOf(u8, model.last_message, "tool_result") != null);420    try testing.expect(std.mem.indexOf(u8, model.last_message, "toolu_1") != null);421    // `last_message` is the serialized JSON tool-result message, so its newlines422    // reach us as the two characters \ and n.423    try testing.expect(std.mem.indexOf(u8, model.last_message, "n\\n1\\n(1 rows)") != null);424    try testing.expectEqual(@as(usize, 2), model.calls);425}426427test "converse dispatches describe_tables" {428    var arena = std.heap.ArenaAllocator.init(testing.allocator);429    defer arena.deinit();430    const a = arena.allocator();431432    var sess = FakeSession{};433    var model = FakeModel{ .replies = &.{434        try toolReply(a, "toolu_2", "describe_tables", "{}"),435        try textReply(a, "Here is what I can look up."),436    } };437438    const result = try converse(a, &model, &sess, &.{}, "what tables are there?");439    try testing.expectEqualStrings("Here is what I can look up.", result.text);440    try testing.expectEqual(@as(usize, 1), sess.describe_calls);441    try testing.expectEqual(@as(usize, 0), sess.query_calls);442    try testing.expect(std.mem.indexOf(u8, model.last_message, "lake.heroes") != null);443}444445test "converse reports unknown tools and missing sql as tool errors" {446    var arena = std.heap.ArenaAllocator.init(testing.allocator);447    defer arena.deinit();448    const a = arena.allocator();449450    var sess = FakeSession{};451    var unknown = FakeModel{ .replies = &.{452        try toolReply(a, "toolu_3", "drop_everything", "{}"),453        try textReply(a, "I cannot do that."),454    } };455    _ = try converse(a, &unknown, &sess, &.{}, "drop the database");456    try testing.expect(std.mem.indexOf(u8, unknown.last_message, "unknown tool") != null);457    try testing.expect(std.mem.indexOf(u8, unknown.last_message, "is_error") != null);458459    var blank = FakeModel{ .replies = &.{460        try toolReply(a, "toolu_4", "run_sql", "{\"sql\":\"   \"}"),461        try textReply(a, "I need a real query."),462    } };463    _ = try converse(a, &blank, &sess, &.{}, "run something");464    try testing.expect(std.mem.indexOf(u8, blank.last_message, "run_sql needs") != null);465    try testing.expectEqual(@as(usize, 0), sess.query_calls);466}467468test "converse passes a sql error back as an error tool result" {469    var arena = std.heap.ArenaAllocator.init(testing.allocator);470    defer arena.deinit();471    const a = arena.allocator();472473    var sess = FakeSession{ .output = .{ .sql = "", .error_message = "no such column: nope" } };474    var model = FakeModel{ .replies = &.{475        try toolReply(a, "toolu_5", "run_sql", "{\"sql\":\"SELECT nope\"}"),476        try textReply(a, "That column does not exist."),477    } };478479    const result = try converse(a, &model, &sess, &.{}, "look up nope");480    try testing.expectEqualStrings("That column does not exist.", result.text);481    try testing.expectEqual(@as(usize, 1), result.queries.len);482    try testing.expect(std.mem.indexOf(u8, model.last_message, "no such column") != null);483    try testing.expect(std.mem.indexOf(u8, model.last_message, "is_error") != null);484}485486test "converse stops at the step limit and keeps the queries so far" {487    var arena = std.heap.ArenaAllocator.init(testing.allocator);488    defer arena.deinit();489    const a = arena.allocator();490491    var sess = FakeSession{};492    var model = FakeModel{ .replies = &.{493        try toolReply(a, "toolu_6", "run_sql", "{\"sql\":\"SELECT 1\"}"),494    } };495496    const result = try converse(a, &model, &sess, &.{}, "loop forever");497    try testing.expect(std.mem.indexOf(u8, result.text, "step limit") != null);498    try testing.expectEqual(@as(usize, max_steps), model.calls);499    try testing.expectEqual(max_steps, result.queries.len);500}