Perception
Ground
Find where each quote appears in a document, with its exact location.
POST /v1/documents/ground finds where each target quote appears in a document. It locates text; it doesn't check whether a claim is true.
# 1. Upload the file to your account (see Uploads)
GRANT=$(curl -s https://console.nace.ai/v1/documents/upload-grants \
-H "Authorization: Bearer $NACE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "path": "report.pdf" }')
WORKSPACE_ID=$(jq -r .workspace_id <<< "$GRANT")
FILE_ID=$(curl -s "$(jq -r .upload_url <<< "$GRANT")" \
-H "X-Upload-Token: $(jq -r .token <<< "$GRANT")" \
-F file=@report.pdf \
-F 'metadata={"path":"report.pdf"};type=application/json' | jq -r .result.file.file_id)
# 2. Run the tool on it
curl "https://console.nace.ai/v1/documents/ground?wait_seconds=60" \
-H "Authorization: Bearer $NACE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source": {
"type": "workspace_file",
"workspace_id": "'"$WORKSPACE_ID"'",
"file_id": "'"$FILE_ID"'"
},
"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" }
]
}'The source can be a url, a workspace_file or a parse_result. See Sources. Ground reads the whole document: it takes no page_ranges or parse_mode, and a request with either is refused with 422.
Configuration
POST /v1/documents/ground has several groups of options. Each example is a whole request with that option set, for the file you uploaded above. For the SDKs and the CLI, see the Python, TypeScript and CLI pages.
Target options
The quotes to find. Give each an id of your own and its text, and add a hint, pages or a sheet when the quote is easy to mistake.
curl https://console.nace.ai/v1/documents/ground \
-H "Authorization: Bearer $NACE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source": {
"type": "workspace_file",
"workspace_id": "'"$WORKSPACE_ID"'",
"file_id": "'"$FILE_ID"'"
},
"targets": [
{ "id": "signer", "text": "Jane Smith", "hint": "Signed on behalf of the supplier" }
]
}'| Option | Default | What it does |
|---|---|---|
targets | Required | 1 to 30 quotes, each with your own id and its text. |
targets[].hint | None | Nearby text that picks the right occurrence of a quote that appears more than once. |
targets[].page_hints | None | One-based pages to search first. |
targets[].sheet | None | The workbook tab to look in. |
targets[].semantic | false | true makes text a description of what to find instead of a quote. On the exact-match runtime, the sentences, table cells, lines, blocks, sections (a heading with its text) or table rows that answer it come back best first, up to options.max_matches, each with its location. hint and page_hints steer the pick. A target whose answer isn't in the document is not_found. On those deployments, if the model that picks is unavailable, only that target is failed with error: native_2_semantic_unavailable and the job still succeeds. It's set per target; there's no top-level semantic. Every hit for a semantic target reports match_method: semantic (see match_method below). |
Some deployments ground PDF, Word and PowerPoint sources with an exact-match runtime. It places every hit on the document's own text, read from its text layer or, on scans, from OCR. Where a note on this page says "exact-match runtime", it applies only on those deployments.
To find text you can only describe, set semantic: true on the target and put the description in text.
curl https://console.nace.ai/v1/documents/ground \
-H "Authorization: Bearer $NACE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source": {
"type": "workspace_file",
"workspace_id": "'"$WORKSPACE_ID"'",
"file_id": "'"$FILE_ID"'"
},
"targets": [
{ "id": "total_due", "text": "the total amount due", "semantic": true }
]
}'On an HTML source, Ground matches the text a browser would show: script and style contents, hidden elements and attribute values are skipped. On a JSON source, a quote can be a key, a value, or an object pattern that one node must match.
Match limits
How many locations to return per target, and which semantic matches to keep.
curl https://console.nace.ai/v1/documents/ground \
-H "Authorization: Bearer $NACE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source": {
"type": "workspace_file",
"workspace_id": "'"$WORKSPACE_ID"'",
"file_id": "'"$FILE_ID"'"
},
"targets": [
{ "id": "total", "text": "1,200.50" }
],
"options": { "max_matches": 5 }
}'| Option | Default | What it does |
|---|---|---|
options.max_matches | 10 | How many locations to return per target, from 1 to 50. |
options.minimum_semantic_score | None | From 0 to 1. Drops semantic matches that score lower. Exact and normalized matches are kept. It applies to audio and video sources. It has no effect on PDF, Word and PowerPoint sources. |
Previews
Link a cropped image of each visual hit.
curl https://console.nace.ai/v1/documents/ground \
-H "Authorization: Bearer $NACE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source": {
"type": "workspace_file",
"workspace_id": "'"$WORKSPACE_ID"'",
"file_id": "'"$FILE_ID"'"
},
"targets": [
{ "id": "total", "text": "1,200.50" }
],
"options": { "include_previews": true }
}'| Option | Default | What it does |
|---|---|---|
options.include_previews | false | When true, each visual hit links a cropped image. |
Result
A finished ground has result.result_type: "ground" and one entry in result.targets per request target, in request order:
{
"result_type": "ground",
"targets": [
{
"id": "total",
"status": "found",
"matches": [
{
"rank": 1,
"matched_text": "1,200.50",
"match_method": "normalized",
"confidence": null,
"location": { "kind": "text_span", "page": 1, "char_start": 120, "char_end": 128 },
"cropped_image_url": null
}
]
}
],
"units": 1
}Targets
| Field | What it holds |
|---|---|
id | Your id from the request. Join on this, not on the quote text. |
status | found with at least one match, not_found when the quote isn't in the document (the job still succeeded), or failed with an error, for example native_2_semantic_unavailable when the model that picks a semantic target is unavailable on the exact-match runtime. A quote too short or too common to place is not_found. |
matches | Locations, best first. Empty when not_found. |
Matches
| Field | What it holds |
|---|---|
rank | Position in matches, starting at 1 for each target. 1 is the place to use. It's a position, not a score. |
matched_text | The text actually found, which can differ from the quote when the match isn't exact. |
match_method | The method reported for this hit: exact, normalized or semantic. Every hit for a semantic: true target is semantic. Visual matching on images can report semantic even for a text query. On the exact-match runtime, a hit for a quote is usually exact or normalized, and a fuzzy OCR hit on a scanned page reports semantic. Inspect matched_text and the highlighted region; the query setting alone does not establish an exact match. |
confidence | A 0 to 1 locator score when one is available, otherwise null. |
location | Where the quote is: page_region, text_span, sheet_range, json_pointer, jsonl_record, row_range or audio_range. See Parse blocks. |
cropped_image_url | A crop of the region with options.include_previews, otherwise null. |
The location kind depends on the file you ground in:
| File | location.kind |
|---|---|
| PDF or image | page_region |
| Plain text, HTML or email | text_span |
| Workbook or CSV | sheet_range |
| Parquet | row_range |
| JSON | json_pointer |
| JSONL | jsonl_record |
| Audio or video | audio_range |
For HTML and email, text_span offsets count from the start of the uploaded file, tags and headers included. Crops and transcripts link to https://console.nace.ai/v1/documents/jobs/{id}/... and open with your API key. See Jobs and results.
Ground reads every file type, including audio, video and JSONL. See Format support.