Ground

client.documents.ground(source, *, targets, **options)

Parameter	Type	Required	Description
`source`	`str \| UrlSource \| WorkspaceFileSource \| ParseResultSource`	Yes	The document to search.
`targets`	`list[dict]`	Yes	1 to 30 quotes to find. See `targets`.
`options`	`dict`	No	How many matches, and whether to link previews. See `options`.

semantic belongs on each target; there is no top-level semantic. Ground takes neither page_ranges nor parse_mode.

Each dict option takes these keys:

targets

One entry per quote, each a dict:

Key	Type	Default	Description
`targets[].id`	`str`	Required	Your id for the quote, echoed on its result.
`targets[].text`	`str`	Required	The quote to find.
`targets[].hint`	`str`	None	Nearby text that tells a repeated quote apart.
`targets[].page_hints`	`list[int]`	None	One-based pages to search first.
`targets[].sheet`	`str`	None	The workbook tab to search. Ignored for other sources.
`targets[].semantic`	`bool`	`False`	Deprecated. `True` fails that target with `semantic_mode_deprecated` on PDF, Word and PowerPoint sources.

options

Key	Type	Default	Description
`options.max_matches`	`int`	`10`	The locations to return per target, from 1 to 50.
`options.minimum_semantic_score`	`float`	None	From 0 to 1. Drops weaker semantic matches. It does nothing on PDF, Word and PowerPoint.
`options.include_previews`	`bool`	`False`	Link a cropped image for each visual hit.

ground.py

from nace_sdk import NaceClient

with NaceClient() as client:
    job = client.documents.ground(
        "https://example.com/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"},
        ],
        wait_seconds=60,
    )
    if job.status != "succeeded":
        job = client.jobs.wait(job.job_id)

for target in job.result["targets"]:
    print(target["id"], target["status"], target["matches"][:1])

job.result is a plain dict:

Each target has id, status and matches.
Each match has rank, matched_text, match_method, confidence, cropped_image_url and location.
location has a kind that decides its other keys:
- page_region: page, polygons
- text_span: page, char_start, char_end
- sheet_range: sheet, a1_range
- row_range: start_row, end_row, column
- json_pointer: pointer
- jsonl_record: row_offset, column
- audio_range: start_ms, end_ms

See Matches.

targetsCopy Anchor Link

optionsCopy Anchor Link

On this page

targets

options