Ledger understanding

client.workspaces.start_ledger_understanding measures the workspace’s ingested journal package — table roles, integrity, open questions, and optional GL parsing — and returns a Job whose result is a LedgerUnderstandingResult. client.workspaces.get_ledger_understanding reads the latest report without starting a run. A sibling of journal-entry testing, not a search. JET tests a criterion over the package; this reads the package so later tests start from a settled census. Without force, an unchanged package republishes the stored report instead of scanning again.

from ndi_sdk import NdiClient
from ndi_sdk.models.workspaces import LedgerUnderstandingConfig

with NdiClient() as client:
    client.workspaces.update(
        workspace_id,
        ledger_understanding=LedgerUnderstandingConfig(trigger="auto", gl_parsing=True),
    )
    job = client.jobs.wait(
        client.workspaces.start_ledger_understanding(workspace_id).job_id,
        timeout=3600,
    )
    report = job.result.report
    print(report.stale, report.blocking, report.parsing)
    stored = client.workspaces.get_ledger_understanding(workspace_id)
    print(stored.package_fingerprint, len(stored.tables))

With the llm engine, package_confirmation="required" (the default) stops discovery at source review: a person confirms the package and its columns before GL parsing runs. If the run later settles different columns, or the selection was confirmed by a model, parsing is skipped and report.parsing.confirmation_required lists the changes; confirm report.settled_structure as a structure review to parse. With package_confirmation="automatic", discovery can confirm a package and start its measured run automatically. When the result has follow_up_job_id, wait for that job before reading the final analysis. report.proposals.auto_confirmation explains the confirmation or why review is needed. report.auto_decisions records model choices, suggestions, and validation refusals; measured evidence still controls parsing.

Method signature

def start_ledger_understanding(
    workspace_id: UUID | str,
    *,
    force: bool = False,
    path_prefix: str | None = None,
    paths: Sequence[str] | None = None,
    selection_id: str | None = None,
    wait_seconds: int = 0,
    idempotency_key: str | None = None,
) -> Job

Parameters

Parameter	Type	Required	Description
`workspace_id`	`UUID` or `str`	Yes	Workspace that already holds an ingested ledger package
`force`	`bool`	No	Re-measure even when a report for this package already exists
`path_prefix`	`str`	No	Package folder, relative to the workspace
`paths`	`Sequence[str]`	No	Exact source paths, intersected with the folder
`selection_id`	`str`	No	Confirmed source selection from the console; cannot be combined with path selectors
`wait_seconds`	`int`	No	Hold the submission request open (max 300)
`idempotency_key`	`str`	No	Override the key the SDK normally mints

Returns

A Job whose result is a LedgerUnderstandingResult (result_type is ledger_understanding). The report also lives on result.report.

Read the latest report

def get_ledger_understanding(
    workspace_id: UUID | str,
    *,
    path_prefix: str | None = None,
    paths: Sequence[str] | None = None,
    selection_id: str | None = None,
) -> LedgerUnderstandingReport

GET returns the report itself, not a job. stale is true when the package has moved since this reading. A workspace that has never produced a report raises 404 ledger_understanding_not_found. For a confirmed source selection, pass the same selection_id to start and read. Changing selected content or adding dataset parts requires a new confirmation; force=True does not override that guard. A source selection is separate from the workspace default and keeps the primary population fixed when passed to JET.

Confirm sources

def list_ledger_sources(
    workspace_id: UUID | str,
    *,
    path_prefix: str | None = None,
    paths: Sequence[str] | None = None,
    selection_id: str | None = None,
    review_reading_id: str | None = None,
) -> SourceCatalog

def select_ledger_sources(
    workspace_id: UUID | str,
    *,
    primary_source_id: str,
    expected_catalog_revision: str,
    supporting_source_ids: Sequence[str] | None = None,
    review: SourceReviewReference | None = None,
    previous_selection_id: str | None = None,
    confirm_unrecognized_primary: bool = False,
) -> SelectionSummary

def get_ledger_selection(
    workspace_id: UUID | str,
    selection_id: UUID | str,
) -> SelectionDetails

list_ledger_sources is the review catalog. Pass review_reading_id from a reading that asked for source selection. select_ledger_sources freezes a primary and supporting sources against that catalog revision. Use the returned selection_id on start and get.

Workspace policy

create and update accept a ledger_understanding block. Updating replaces the block whole. package_scope=LedgerPackageScope(path_prefix="engagement") sets the default for automatic runs, reads and reviews. Import LedgerPackageScope from ndi_sdk.models.ledger_understanding. Empty request selectors use this default. Read a per-request package with the same selectors used to start it. See package scope and parse coverage.

Field	Default	Meaning
`trigger`	`"auto"`	`auto` chains a run after ingestion only when the workspace already holds a journal-line table. `always` chains after every ingestion that landed files. `off` stops chaining; it never refuses an explicit `start_ledger_understanding`
`gl_parsing`	`True`	Map each journal’s account / debit-credit groups to balanced sub-journals
`package_confirmation`	`"required"`	With the `llm` engine, `required` parses only a mapping a person confirmed; `automatic` lets the model confirm the package

A document-only corpus with trigger="auto" never starts a run: the predicate is over sidecars ingestion already wrote. When ingestion does chain a run, IngestionResult.ledger_understanding_job_id names it. Poll that id with jobs.wait.

Reading the report

Field	What it is
`stale`	The package has moved since this reading
`blocking`	Integrity found something that makes the population unfit to test
`tables`	One card per table: role, row count, journal key, balance share
`conventions`	What the numbers mean — journal key, amount bases, date roles
`integrity`	Findings and skipped checks. Empty findings is an answer
`join_graph`	Expected joins, measured in both directions
`open_questions`	Things the data could not settle, asked once each
`parsing`	GL-parse counts, never rows. `None` when parsing was off or skipped

report = client.workspaces.get_ledger_understanding(workspace_id)
if report.stale:
    client.workspaces.start_ledger_understanding(workspace_id, force=True)
if report.blocking:
    for finding in report.integrity.findings:
        print(finding.check, finding.severity, finding.count, finding.message)
for question in report.open_questions:
    print(question.id, question.question)

Conflicts

A second start_ledger_understanding while a run is already in flight returns 409 ledger_understanding_in_progress. Wait for the in-flight job, or read the current report with get_ledger_understanding. See Workspaces and the ledger-understanding API reference.

Get started

Core methods

Async and utilities

Method signature

Parameters

Returns

Read the latest report

Confirm sources

Workspace policy

Reading the report

Conflicts

​Method signature

​Parameters

​Returns

​Read the latest report

​Confirm sources

​Workspace policy

​Reading the report

​Conflicts

Method signature

Parameters

Returns

Read the latest report

Confirm sources

Workspace policy

Reading the report

Conflicts