Choose the right tool

​

Before you ask

pip install ndi-cli
ndi login
ndi workspace create fy25-audit
ndi workspace use <workspace-id>
ndi files upload ./corpus --ingest
ndi workspace stats

​

Look before you ask

• POST /v1/workspaces/{workspace_id}/tools/folder-metadata lists a folder and finds files by name (name_contains), with each file’s exact path.
• POST /v1/workspaces/{workspace_id}/tools/file-metadata describes one file by path: its category, a summary, and its sections or tabs with their own summaries and key terms.

​

Pick in order

1. The question is an audit test over journal entries or a general ledger (approvals, posting dates, users, round amounts, cut-off): use journal-entry testing.
2. The question is about one file you can name: use file QA.
3. The question needs a calculation or comparison across one or more spreadsheets or table files: use table QA.
4. The question is one turn of a conversation: a follow-up to an earlier answer, or one the asker may need to clarify: use QA.
5. Anything else: use automatic search. When you already know the route, say so: --mode fact for a fact written in the documents (a number, a name, a date, a clause) that needs no reasoning; --mode agent for reasoning (comparing documents, explaining why, reconciling, several steps) or for filtering, ranking, or counting documents by their values, which the agent answers from the metadata catalog as a table. Unsure: omit --mode and the service picks.

​

Example prompts

​

File QA

• Returns: an answer and citations from the file. Pass output_schema (SDK and API) to get the answer as JSON in structured_answer.
• Use when: the question names one file, or you already know which file holds the answer.
• Do not use when: the answer could be in any of several files (automatic search); the question spans several workbooks (table QA).

ndi ask-file contracts/acme-msa.pdf "Summarize the termination clause"
ndi ask-file invoices/INV-1043.pdf "What is the invoice number, date, and total?"
ndi ask-file calls/q3-earnings.mp3 "What does the CFO say about full-year guidance?"
ndi ask-file finance/fixed-assets.xlsx "Which assets were disposed of this year?" --component Disposals

​

Table QA

• Returns: an answer, citations, any sources it could not use, and a preview of the rows behind the answer. Pass output_schema to get JSON in structured_answer.
• Use when: the answer has to be computed from tables, especially across several files.
• Do not use when: the files are PDFs or other documents (file QA or deep search); the question is an audit test over a ledger (journal-entry testing).

from ndi_sdk import NdiClient

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    answer = client.tools.query_tables(
        workspace_id,
        paths=["finance/trial-balance-fy25.xlsx", "finance/trial-balance-fy24.xlsx"],
        query="Which accounts moved more than 10 percent from last year?",
    )
    print(answer.answer)

curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/tools/query-tables" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paths":[{"path":"finance/trial-balance-fy25.xlsx"},{"path":"finance/trial-balance-fy24.xlsx"}],"query":"Which accounts moved more than 10 percent from last year?"}'

​

Journal-entry testing

• Returns: a job whose result has an answer, figures (each criterion with its count and population), criteria, discrepancies, and sql_receipts. exhausted means the run stopped before it finished; the answer is partial.
• Use when: the question is a journal-entry test: who posted or approved, when, at what amount, with what description, compared with what threshold or period.
• Do not use when: the question is about documents rather than ledger lines (automatic search); it is a calculation over a trial balance or another non-ledger workbook (table QA).

ndi je-testing "Find journal entries posted on weekends or public holidays" --path ledger/journal.xlsx
ndi je-testing "Test whether any posted journal line was approved by its own preparer" --path ledger/journal.xlsx
ndi je-testing "List manual entries posted after period end that are just below the 50,000 approval limit" --prefix ledger/
ndi je-testing "Find entries with round amounts over 100,000 and no description" --reasoning-effort high

​

Automatic search

• Returns: a job whose result has routing (the route taken), output (that route’s answer), and output_job_id. When the agent answers from the catalog, output.catalog is a table of matching documents with an exact total_matches; it carries up to 200 rows, and next_cursor pages the rest with ndi filtered-search --cursor. Pass output_schema (SDK and API) to get the answer as JSON in the route’s structured_answer.
• Use when: the question is about the workspace and no earlier rule in Pick in order matches.
• Know the route already? --mode fact for a stated fact, --mode agent for reasoning or a filtered list or count. Either runs with no routing step and keeps the automatic result shape.

ndi automatic-search "Anything about related-party transactions?"
ndi automatic-search "What was total revenue for FY2025?" --mode fact
ndi automatic-search "Which subsidiaries missed covenant tests, and by how much?" --mode agent
ndi automatic-search "How many purchase orders from Acme Corp in Q4 2025?" --mode agent --prefix purchasing/

​

QA

• Returns: a job whose result is an automatic_agent: answer (with citations, SQL receipts, session_id, and any clarification_questions) and, when the agent answered from the catalog, a catalog table. Pass output_schema on a turn to get that turn’s answer as JSON.
• Use when: the question follows up an earlier answer, or the asker can answer a question back.
• Do not use when: the question stands alone (automatic search can take the faster fact route). The CLI has no QA command; use the SDK or the API.

from ndi_sdk import NdiClient
from ndi_sdk.models.jobs import AutomaticAgentResult

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    first = client.jobs.wait(
        client.search.qa(workspace_id, query="What was total revenue for FY2025?").job_id,
        timeout=600,
    )
    if isinstance(first.result, AutomaticAgentResult) and first.result.answer.session_id:
        client.search.qa(workspace_id, query="And for FY2024?", session_id=first.result.answer.session_id)

​

Knowledge graph

from ndi_sdk import NdiClient

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    build = client.ingestion.build_knowledge_graph(workspace_id)
    client.jobs.wait(build.job_id, timeout=1800)

curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/knowledge-graph/builds" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

​

Deprecated tools

​

Fact search (deprecated)

• Returns: a job whose result has an answer, the evidences it is drawn from (each with its source file), and grounding_job_ids for exact locations in the source.
• Use when: the answer is written down somewhere: a figure, a name, a date, a clause, a definition.
• Do not use when: the question asks why or how, or compares sources (deep search); filters a list by value (filtered search); needs arithmetic over tables (table QA).

ndi automatic-search "What was total revenue for FY2025?" --mode fact
ndi automatic-search "What is the notice period in the Acme master services agreement?" --mode fact --prefix contracts/
ndi automatic-search "What interest rate applies to the revolving credit facility?" --mode fact --top-k 5

​

Deep search (deprecated)

• Returns: a job whose result has an answer, the evidences and claims behind it, receipts for any calculation it ran, and grounding_job_ids.
• Use when: the question compares sources, asks why, reconciles figures, or needs several steps to answer.
• Do not use when: a single stated fact answers it (fact search is faster); it is a filter or count over documents (filtered search); it is an audit test over a ledger (journal-entry testing).

ndi automatic-search "Why did gross margin fall compared with last year?" --mode agent
ndi automatic-search "Reconcile revenue in the MD&A with the income statement" --mode agent --prefix reports/fy25/

​

Filtered search (deprecated)

• Returns: a job whose result has rows, columns, total_matches, total_files, exhaustive, and next_cursor for the next page.
• Use when: the question has conditions such as “over 1,000 USD”, “dated in March”, “from vendor X”, “not yet paid”, or asks for “all”, “how many”, or “top N”.
• Do not use when: you want one fact or an explanation (automatic search); the rows are journal or ledger lines (journal-entry testing); you need arithmetic across workbooks (table QA).

ndi automatic-search "all invoices over 10000 USD dated in March 2025" --mode agent
ndi automatic-search "top 10 contracts by value signed in 2025, with counterparty and end date" --mode agent
ndi filtered-search --cursor <next_cursor>

​

Common mistakes

• --mode fact for a “why” question. The fact route quotes what is written; it does not explain or compare. Use --mode agent, or omit --mode.
• Starting a new search for a follow-up. Automatic search keeps no conversation; “and for FY2024?” means nothing on its own. Use QA with the previous turn’s session_id.
• File QA across many files. File QA reads exactly one file. If you do not know which file holds the answer, use automatic search.
• Automatic search over ledger lines. Its catalog lists documents and register entries. Tests over journal lines are journal-entry testing.
• Journal-entry testing on non-ledger data. A trial balance or a fixed asset register is table QA.
• Table QA on PDFs. Table QA reads spreadsheets and table files. Ask a PDF with file QA, or search across PDFs with automatic search.
• Asking before ingestion finishes. Every tool answers only from files that are already ingested.
• Expecting graph answers without a build. The knowledge graph does nothing until it has been built for the workspace.