LINE1 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}