Skip to content

Lightpanda: the headless browser designed for AI and automation

tools: fence extract's value shapes and examples

Adrià Arrufat1e8ea4e988e6
diff --git a/src/browser/tools.zig b/src/browser/tools.zig
index d6f0ecbde..ceb4ea26c 100644
--- a/src/browser/tools.zig
+++ b/src/browser/tools.zig
@@ -529,21 +529,25 @@ pub const Tool = enum {
.extract => .{
.description =
\\Extract structured data from the current page (navigate first). `schema` is a JSON object (passed as a string) mapping output field names to CSS-selector specs. It is NOT a JSON Schema — no "type"/"properties" wrappers; the keys ARE your output fields. Value shapes:
- \\ "<sel>" → first match's text (trimmed; null if no match)
- \\ ["<sel>"] → every match's text (string[])
- \\ {"selector":"<sel>","attr":"<name>"} → first match's attribute value (href/src resolved to absolute URLs)
- \\ [{"selector":"<sel>","attr":"<name>"}] → every match's attribute (string[])
- \\ [{"selector":"<sel>","fields":{…}}] → one object per match; field selectors resolve relative to that match and accept any shape above ("" = the match's own text; nest arrays for per-item sub-lists)
+ \\```text
+ \\"<sel>" → first match's text (trimmed; null if no match)
+ \\["<sel>"] → every match's text (string[])
+ \\{"selector":"<sel>","attr":"<name>"} → first match's attribute value (href/src resolved to absolute URLs)
+ \\[{"selector":"<sel>","attr":"<name>"}] → every match's attribute (string[])
+ \\[{"selector":"<sel>","fields":{…}}] → one object per match; field selectors resolve relative to that match and accept any shape above ("" = the match's own text; nest arrays for per-item sub-lists)
+ \\```
\\Add "limit": N inside any array's object spec to cap matches.
\\Every extracted value is a string or null — parse numbers downstream. An empty array is a valid result, but if ALL top-level keys miss, the call errors: inspect the page (tree/markdown) and retry with corrected selectors.
\\Finish data tasks with extract — it is the only read recorded as a replayable `extract(...)` script call; answers lifted from `markdown` text in chat are not.
\\
\\Examples (schema → result):
- \\ {"karma": "#karma"} → {"karma":"42"}
- \\ {"items": [".story .title"]} → {"items":["Title 1","Title 2"]}
- \\ {"top3": [{"selector":".story .title","limit":3}]} → {"top3":["A","B","C"]}
- \\ {"links": [{"selector":"a.title","attr":"href"}]} → {"links":["https://site/a","https://site/b"]}
- \\ {"stories": [{"selector":".athing","fields":{"title":".titleline","rank":".rank"}}]} → {"stories":[{"title":"Foo","rank":"1"}]}
+ \\```text
+ \\{"karma": "#karma"} → {"karma":"42"}
+ \\{"items": [".story .title"]} → {"items":["Title 1","Title 2"]}
+ \\{"top3": [{"selector":".story .title","limit":3}]} → {"top3":["A","B","C"]}
+ \\{"links": [{"selector":"a.title","attr":"href"}]} → {"links":["https://site/a","https://site/b"]}
+ \\{"stories": [{"selector":".athing","fields":{"title":".titleline","rank":".rank"}}]} → {"stories":[{"title":"Foo","rank":"1"}]}
+ \\```
,
.summary = "Extract structured data via a CSS-selector schema",
.input_schema = minify(
diff --git a/src/docs.zig b/src/docs.zig
index 8cce99a1d..fc0edccf9 100644
--- a/src/docs.zig
+++ b/src/docs.zig
@@ -273,33 +273,10 @@ const Cell = struct {
}
};
-/// Prose for MDX: outside code spans, `<` would open JSX and `{` an
-/// expression. Tool descriptions are written for models, so a run of
-/// indented lines after a line ending in `:` is an aligned listing (extract's
-/// value shapes), kept verbatim in a fence instead of reflowing.
+/// Prose for MDX: outside code spans and fences, `<` would open JSX and `{`
+/// an expression.
fn writeText(w: *Writer, s: []const u8) Writer.Error!void {
- var lines = std.mem.splitScalar(u8, s, '\n');
- var prev: []const u8 = "";
- var in_fence = false;
- var first = true;
- while (lines.next()) |line| : (first = false) {
- const indented = std.mem.startsWith(u8, line, " ");
- if (!in_fence and indented and std.mem.endsWith(u8, prev, ":")) {
- try w.writeAll("\n\n```text");
- in_fence = true;
- } else if (in_fence and !indented) {
- try w.writeAll("\n```\n");
- in_fence = false;
- }
- if (!first) try w.writeAll("\n");
- if (in_fence) {
- try w.writeAll(line[2..]);
- } else {
- try writeEscaped(w, line, false);
- }
- prev = line;
- }
- if (in_fence) try w.writeAll("\n```");
+ try writeEscaped(w, s, false);
}
fn writeCode(w: *Writer, s: []const u8, cell: bool) Writer.Error!void {
@@ -389,9 +366,9 @@ test "docs: escaping leaves code spans alone" {
try testing.expectEqualStrings("a &lt;b> \\{c\\} `x\\|<y>{}` d\\|e f `open", aw.written());
}
-test "docs: an indented listing after a colon is fenced" {
+test "docs: prose keeps fenced blocks verbatim" {
var aw: Writer.Allocating = .init(testing.allocator);
defer aw.deinit();
- try writeText(&aw.writer, "Shapes:\n \"<sel>\" → text\n {a} → b\nAfter <x>.");
- try testing.expectEqualStrings("Shapes:\n\n```text\n\"<sel>\" → text\n{a} → b\n```\n\nAfter &lt;x>.", aw.written());
+ try writeText(&aw.writer, "Shapes:\n```text\n\"<sel>\" → {a}\n```\nAfter <x>.");
+ try testing.expectEqualStrings("Shapes:\n```text\n\"<sel>\" → {a}\n```\nAfter &lt;x>.", aw.written());
}