Perception
Ground
client.documents.ground(params, options?) finds where each quote appears. It takes the shared parameters and:
| Parameter | Type | Required | Description |
|---|---|---|---|
targets | Array<{ id, text, hint?, sheet?, semantic?, page_hints? }> | Yes | 1 to 30 quotes to find. See targets. |
options | { max_matches?, include_previews?, minimum_semantic_score? } | No | How many matches, and whether to link previews. See options. |
Ground takes no page_ranges and no parse_mode, and semantic belongs on each target: a top-level semantic is refused with 422.
Each object option takes these keys:
targets
One entry per quote, each an object:
| Key | Type | Default | Description |
|---|---|---|---|
targets[].id | string | Required | Your id for the quote, echoed on its result. |
targets[].text | string | Required | The quote to find. |
targets[].hint | string | None | Nearby text that tells a repeated quote apart. |
targets[].page_hints | Array<number> | None | One-based pages to search first. |
targets[].sheet | string | None | The workbook tab to search. Ignored for other sources. |
targets[].semantic | boolean | false | Deprecated. true fails that target with semantic_mode_deprecated on PDF, Word and PowerPoint sources. |
options
| Key | Type | Default | Description |
|---|---|---|---|
options.max_matches | number | 10 | The locations to return per target, from 1 to 50. |
options.minimum_semantic_score | number | None | From 0 to 1. Drops weaker semantic matches. It does nothing on PDF, Word and PowerPoint. |
options.include_previews | boolean | false | Link a cropped image for each visual hit. |
const job = await client.documents.ground({
source: { type: "url", url: "https://example.com/report.pdf", file_name: "report.pdf" },
targets: [
{ id: "total", text: "1,200.50" },
{ id: "signer", text: "Jane Smith", hint: "Signed on behalf of the supplier" },
{ id: "late_fee", text: "Late payment fee" },
],
});
const done = await client.jobs.wait(job.job_id);job.result is a plain object (unknown in the types):
- Each target has
id,statusandmatches. - Each match has
rank,matched_text,match_method,confidence,cropped_image_urlandlocation. locationhas akindthat decides its other keys:page_region:page,polygonstext_span:page,char_start,char_endsheet_range:sheet,a1_rangerow_range:start_row,end_row,columnjson_pointer:pointerjsonl_record:row_offset,columnaudio_range:start_ms,end_ms
See Matches.