Ground

documents.ground finds supplied text in a document and returns source locations. Use it to connect a value or quote back to evidence.

Ground locates text. It does not determine whether a claim is true.

Basic usage

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import GroundTarget

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    queued = client.documents.ground(
        upload,
        targets=[
            GroundTarget(id="revenue", text="$12.4 million"),
            GroundTarget(id="period", text="year ended December 31, 2025"),
        ],
        wait_seconds=30,
    )
    job = client.jobs.wait(queued.job_id, timeout=600)
    # Returns: succeeded Job; job.result is a GroundResult

    for target in job.result.targets:
        for match in target.matches:
            print(target.id, match.matched_text, match.location)

Method signature

def ground(
    source: DocumentSource | UploadResponse,
    *,
    targets: list[GroundTarget],
    options: GroundOptions | None = None,
    wait_seconds: int = 0,
    idempotency_key: str | None = None,
) -> Job

Parameters

Parameter	Type	Required	Description
`source`	`DocumentSource` or `UploadResponse`	Yes	Staged upload, URL, workspace file, or successful parse job
`targets`	`list[GroundTarget]`	Yes	1–30 quoted strings to locate
`options`	`GroundOptions`	No	Match cap, semantic threshold, previews, and experimental word-level matching
`wait_seconds`	`int`	No	Hold the submission request open for up to 300 seconds
`idempotency_key`	`str`	No	Override the key the SDK normally mints

Returns

A Job. After success, job.result is a GroundResult:

Field	Description
`targets`	One result per request target, in request order
`units`	Billable units
`transcript_url`	Authenticated grounding transcript for supported media

Define targets

Every target needs an ID and the text to locate:

from ndi_sdk.models.document_ops import GroundTarget

targets = [
    GroundTarget(
        id="contract_value",
        text="$1,200,000",
    ),
    GroundTarget(
        id="effective_date",
        text="January 1, 2026",
    ),
]

The ID is echoed in the result. Join request targets to results by id, not by quoted text.

Disambiguate repeated text

Add nearby context with hint:

from ndi_sdk.models.document_ops import GroundTarget

target = GroundTarget(
    id="ending_balance",
    text="$48,921.10",
    hint="Ending balance in the account summary",
)

On HTML sources, the visible occurrence nearest the hint ranks first. Without a hint, the first visible occurrence ranks first.

Match by meaning (deprecated)

semantic is deprecated for now. Don’t rely on it: a target with semantic=True can come back with status failed and error semantic_mode_deprecated. Quote the text exactly as it appears in the source.

Select a worksheet

Use sheet to narrow a workbook target to one tab:

from ndi_sdk.models.document_ops import GroundTarget

target = GroundTarget(
    id="net_income",
    text="4,821,000",
    sheet="Income Statement",
)

sheet is ignored for non-spreadsheet sources.

Configure matching

from ndi_sdk.models.document_ops import GroundOptions

options = GroundOptions(
    max_matches=5,
    minimum_semantic_score=0.8,
    include_previews=True,
)

Option	Default	Description
`max_matches`	`10`	Maximum matches per target, ranked best-first. Accepts 1–50
`minimum_semantic_score`	none	Drop semantic matches below this 0–1 score
`include_previews`	`false`	Mint crop URLs for matches with visual regions
`use_word_level_grounding`	`false`	Experimental OCR-word matching for PDF sources

minimum_semantic_score does not affect exact or normalized matches. require_visual_region exists in the model but is not supported by the current runtime; do not enable it.

Experimental word-level matching

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import GroundOptions, GroundTarget

with NdiClient() as client:
    upload = client.documents.create_upload("scanned-report.pdf")
    queued = client.documents.ground(
        upload,
        targets=[GroundTarget(id="total", text="$1,200.50")],
        options=GroundOptions(use_word_level_grounding=True),
    )
    # Returns: Job using experimental word-level PDF grounding

Targets shorter than two normalized characters fail with needle_too_short.

Response structure

Each target has an independent outcome:

# After client.jobs.wait returns a succeeded ground job:
result = ...

for target in result.targets:
    print(target.id)
    print(target.status)       # found, not_found, or failed
    print(target.error)        # set only when this target failed

    for match in target.matches:
        print(match.rank)
        print(match.matched_text)
        print(match.match_method)
        print(match.confidence)
        print(match.location)
        print(match.cropped_image_url)

not_found is a successful answer about the document; the job itself remains succeeded. failed means that target encountered an error. Matches are sorted best-first:

Field	Description
`rank`	One-based position for this target. It is not a confidence score
`matched_text`	Text found at the returned location
`match_method`	`exact`, `normalized`, or `semantic`
`confidence`	Optional 0–1 locator confidence
`location`	Typed source locator
`cropped_image_url`	Authenticated preview when requested and available

Location types

The location model follows the source:

`location.kind`	Source location
`page_region` / `visual_region`	Page and normalized polygons
`sheet_range` / `spreadsheet_range`	Worksheet and A1 range
`text_span` / `text_range`	Character offsets
`row_range`	Table rows and optional column
`jsonl_record`	JSONL record
`audio_range`	Start and end timestamps

Ground response format

Review target status, ranking, match methods, locator fields, and related artifacts.

Preview visual matches

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import GroundOptions, GroundTarget

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    job = client.jobs.wait(
        client.documents.ground(
            upload,
            targets=[GroundTarget(id="total", text="$1,200.50")],
            options=GroundOptions(include_previews=True),
            wait_seconds=30,
        ).job_id
    )
    # Returns: GroundResult with crop references where visual regions exist

    match = job.result.targets[0].matches[0]
    print(match.cropped_image_url)

The URL is authenticated and short-lived. Pass it directly to jobs.ground_crop to fetch the bytes through the SDK:

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import GroundOptions, GroundTarget

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    job = client.jobs.wait(
        client.documents.ground(
            upload,
            targets=[GroundTarget(id="total", text="$1,200.50")],
            options=GroundOptions(include_previews=True),
            wait_seconds=30,
        ).job_id
    )
    match = job.result.targets[0].matches[0]
    if match.cropped_image_url is not None:
        crop = client.jobs.ground_crop(
            job.job_id,
            match.cropped_image_url,
        )
        # Returns: crop bytes

Do not construct an artifact reference. The SDK accepts the complete returned URL and extracts its reference.

Reuse a parse

from ndi_sdk import NdiClient, ParseResultSource
from ndi_sdk.models.document_ops import GroundTarget

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    parsed = client.jobs.wait(
        client.documents.parse(upload, wait_seconds=30).job_id
    )
    queued = client.documents.ground(
        ParseResultSource(job_id=parsed.job_id),
        targets=[GroundTarget(id="total", text="$1,200.50")],
    )
    # Returns: Job; NDI reuses the successful ParseResult

Async ground

import asyncio

from ndi_sdk import AsyncNdiClient
from ndi_sdk.models.document_ops import GroundTarget


async def main() -> None:
    async with AsyncNdiClient() as client:
        upload = await client.documents.create_upload("report.pdf")
        queued = await client.documents.ground(
            upload,
            targets=[GroundTarget(id="total", text="$1,200.50")],
            wait_seconds=30,
        )
        job = await client.jobs.wait(queued.job_id, timeout=600)
        # Returns: succeeded Job with a GroundResult
        print(job.result.targets)


asyncio.run(main())

Complete example

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import GroundOptions, GroundTarget

targets = [
    GroundTarget(
        id="revenue",
        text="$12.4 million",
        hint="Revenue for the year ended December 31, 2025",
    ),
    GroundTarget(
        id="net_income",
        text="$2.1 million",
        hint="Net income in the consolidated statements",
    ),
    GroundTarget(
        id="termination",
        text="Either party may terminate on thirty days notice",
    ),
]

with NdiClient() as client:
    upload = client.documents.create_upload("annual-report.pdf")
    queued = client.documents.ground(
        upload,
        targets=targets,
        options=GroundOptions(
            max_matches=3,
            minimum_semantic_score=0.8,
            include_previews=True,
        ),
        wait_seconds=30,
    )
    job = client.jobs.wait(queued.job_id, timeout=600)
    # Returns: GroundResult with one ordered result per target

    for target in job.result.targets:
        if target.status == "found":
            best = target.matches[0]
            print(target.id, best.matched_text, best.location)
        else:
            print(target.id, target.status, target.error)

Error handling

from ndi_sdk import InvalidRequestError, JobFailedError, NdiClient
from ndi_sdk.models.document_ops import GroundTarget

with NdiClient() as client:
    try:
        queued = client.documents.ground(
            client.documents.create_upload("report.pdf"),
            targets=[GroundTarget(id="total", text="$1,200.50")],
        )
        job = client.jobs.wait(queued.job_id, timeout=600)
        # Returns: succeeded Job, or raises for request/job failure
    except InvalidRequestError as exc:
        print(exc.code, exc.message)
    except JobFailedError as exc:
        print(exc.job.status, exc.job.error)

Distinguish a failed job from per-target not_found and failed statuses. Common request errors include an empty target list, more than 30 targets, an unsupported option, or a source the current grounding path cannot read.

Best practices

Use exact source text

Quote the text as written. Semantic matching is deprecated for now.

Add nearby context

Use hint to rank the intended occurrence when a quote repeats.

Join on target ID

Treat the caller-defined ID as the stable key between request and response.

Handle not_found

A missing quote is a successful document-level answer, not an exception.

Get started

Core methods

Async and utilities

Basic usage

Method signature

Parameters

Returns

Define targets

Disambiguate repeated text

Match by meaning (deprecated)

Select a worksheet

Configure matching

Experimental word-level matching

Response structure

Location types

Ground response format

Preview visual matches

Reuse a parse

Async ground

Complete example

Error handling

Best practices

Use exact source text

Add nearby context

Join on target ID

Handle not_found

Next steps

​Basic usage

​Method signature

​Parameters

​Returns

​Define targets

​Disambiguate repeated text

​Match by meaning (deprecated)

​Select a worksheet

​Configure matching

​Experimental word-level matching

​Response structure

​Location types

Ground response format

​Preview visual matches

​Reuse a parse

​Async ground

​Complete example

​Error handling

​Best practices

Use exact source text

Add nearby context

Join on target ID

Handle not_found

​Next steps

Basic usage

Method signature

Parameters

Returns

Define targets

Disambiguate repeated text

Match by meaning (deprecated)

Select a worksheet

Configure matching

Experimental word-level matching

Response structure

Location types

Preview visual matches

Reuse a parse

Async ground

Complete example

Error handling

Best practices

Next steps