Skip to content

Questions with citations over a corpus

A knowledge node adds every document the workflow processes to a searchable corpus. knowledge:ask then answers a question with claims that each carry a citation (document, page, quote) checked against the text; a claim the documents do not support is dropped instead of invented.

The documents are synthetic (invented names, amounts and accounts), generated by scripts/docs_examples.py:

The graph

parse → knowledge

The full version body (graph and schemas), as the API takes it:

{
  "graph": {
    "nodes": [
      {
        "id": "parse",
        "type": "parse"
      },
      {
        "id": "knowledge",
        "type": "knowledge",
        "config": {
          "index": "fts"
        }
      }
    ],
    "edges": [
      {
        "source": "parse",
        "target": "knowledge"
      }
    ]
  },
  "schemas": {}
}

Create it and run it

Set DX_BASE_URL and DX_API_KEY (see the quickstart), cd to docs/examples/gallery/corpus-questions/ and run any of the three. They do the same.

Python

# SPDX-License-Identifier: Apache-2.0
# expect: "status": "answered"
"""Questions with citations over a corpus: create the workflow, run it on the document and print what comes back."""

import json
import os
import secrets
import time
from pathlib import Path

import httpx

api = httpx.Client(
    base_url=os.environ["DX_BASE_URL"],
    headers={"Authorization": f"Bearer {os.environ['DX_API_KEY']}"},
    timeout=120,
)
name = f"corpus-questions-{secrets.token_hex(3)}"  # unique, so the example can run again

# 1. Create the workflow, add the version (graph + schemas), publish it, point `prod` at it.
workflow = api.post("/v1/workflows", json={"name": name}).raise_for_status().json()
version = (
    api.post(
        f"/v1/workflows/{workflow['id']}/versions",
        json=json.loads(Path("workflow.json").read_text()),
    )
    .raise_for_status()
    .json()
)
api.post(f"/v1/workflow-versions/{version['id']}:publish", json={}).raise_for_status()
api.put(
    f"/v1/workflows/{workflow['id']}/aliases/prod", json={"version_id": version["id"]}
).raise_for_status()

# 2. Run it on every document: each finished run adds its document to the corpus.
for path in ["travel-policy.pdf", "expense-policy.pdf", "security-policy.pdf"]:
    run = (
        api.post(
            "/v1/runs",
            data={"workflow": f"{name}@prod"},
            files=[("files", (path, Path(path).read_bytes(), "application/pdf"))],
        )
        .raise_for_status()
        .json()
    )
    api.get(f"/v1/runs/{run['id']}", params={"wait": 60}).raise_for_status()

# 3. Indexing is asynchronous: wait for the corpus, then ask with citations.
corpus = f"/v1/workflows/{workflow['id']}/knowledge"
while api.get(corpus).json()["indexed"] < 3:
    time.sleep(0.5)
answer = (
    api.post(
        f"{corpus}:ask", json={"question": "What is the daily meal allowance when travelling?"}
    )
    .raise_for_status()
    .json()
)

view = {
    "status": "abstained" if answer["abstained"] else "answered",
    "answer": answer["answer"],
    "citations": [
        {"page": c["page"], "quote": c["quote"], "verification": c["verification"]}
        for c in answer["citations"]
    ],
}
print(json.dumps(view, indent=2))

TypeScript

// SPDX-License-Identifier: Apache-2.0
// expect: "status": "answered"
// Questions with citations over a corpus: create the workflow, run it on the document and print what comes back.
// Node 22+: node --experimental-strip-types create.ts
import { readFileSync } from "node:fs";

const base = process.env.DX_BASE_URL as string;
const auth = { Authorization: `Bearer ${process.env.DX_API_KEY}` };
const name = `corpus-questions-${Math.random().toString(16).slice(2, 8)}`; // unique, so it can run again

async function call(path: string, init: RequestInit = {}): Promise<any> {
  const response = await fetch(base + path, { ...init, headers: { ...auth, ...init.headers } });
  if (!response.ok) throw new Error(`${response.status} ${path}: ${await response.text()}`);
  return response.json();
}
const json = (body: unknown): RequestInit => ({
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
});

// 1. Create the workflow, add the version (graph + schemas), publish it, point `prod` at it.
const workflow = await call("/v1/workflows", json({ name }));
const version = await call(
  `/v1/workflows/${workflow.id}/versions`,
  json(JSON.parse(readFileSync("workflow.json", "utf8"))),
);
await call(`/v1/workflow-versions/${version.id}:publish`, json({}));
await call(`/v1/workflows/${workflow.id}/aliases/prod`, {
  ...json({ version_id: version.id }),
  method: "PUT",
});

// 2. Run it on every document: each finished run adds its document to the corpus.
for (const path of ["travel-policy.pdf", "expense-policy.pdf", "security-policy.pdf"]) {
  const form = new FormData();
  form.append("workflow", `${name}@prod`);
  form.append("files", new Blob([readFileSync(path)], { type: "application/pdf" }), path);
  const started = await call("/v1/runs", { method: "POST", body: form });
  await call(`/v1/runs/${started.id}?wait=60`);
}

// 3. Indexing is asynchronous: wait for the corpus, then ask with citations.
const corpus = `/v1/workflows/${workflow.id}/knowledge`;
while ((await call(corpus)).indexed < 3) await new Promise((r) => setTimeout(r, 500));
const answer = await call(`${corpus}:ask`, json({ question: "What is the daily meal allowance when travelling?" }));

const view = {
  status: answer.abstained ? "abstained" : "answered",
  answer: answer.answer,
  citations: answer.citations.map((c: any) => ({
    page: c.page,
    quote: c.quote,
    verification: c.verification,
  })),
};
console.log(JSON.stringify(view, null, 2));

curl

#!/usr/bin/env bash
# SPDX-License-Identifier: Apache-2.0
# expect: "status": "answered"
# Questions with citations over a corpus: create the workflow, run it on the document and print what comes back.
# Needs curl and jq; DX_BASE_URL and DX_API_KEY in the environment.
set -euo pipefail
api() { curl -sS --fail-with-body -H "Authorization: Bearer $DX_API_KEY" "$@"; }
JSON='Content-Type: application/json'
NAME="corpus-questions-$RANDOM$RANDOM"  # unique, so the example can run again

# 1. Create the workflow, add the version (graph + schemas), publish it, point `prod` at it.
WORKFLOW=$(api -X POST "$DX_BASE_URL/v1/workflows" -H "$JSON" -d "{\"name\": \"$NAME\"}" | jq -r .id)
VERSION=$(api -X POST "$DX_BASE_URL/v1/workflows/$WORKFLOW/versions" -H "$JSON" -d @workflow.json | jq -r .id)
api -X POST "$DX_BASE_URL/v1/workflow-versions/$VERSION:publish" -H "$JSON" -d '{}' > /dev/null
api -X PUT "$DX_BASE_URL/v1/workflows/$WORKFLOW/aliases/prod" -H "$JSON" \
  -d "{\"version_id\": \"$VERSION\"}" > /dev/null

# 2. Run it on every document: each finished run adds its document to the corpus.
for FILE in travel-policy.pdf expense-policy.pdf security-policy.pdf; do
  RUN=$(api -X POST "$DX_BASE_URL/v1/runs" -F "workflow=$NAME@prod" -F "files=@$FILE" | jq -r .id)
  api "$DX_BASE_URL/v1/runs/$RUN?wait=60" > /dev/null
done

# 3. Indexing is asynchronous: wait for the corpus, then ask with citations.
CORPUS="$DX_BASE_URL/v1/workflows/$WORKFLOW/knowledge"
until [ "$(api "$CORPUS" | jq .indexed)" -ge 3 ]; do sleep 0.5; done
api -X POST "$CORPUS:ask" -H "$JSON" -d "{\"question\": \"What is the daily meal allowance when travelling?\"}" \
  | jq '{status: (if .abstained then "abstained" else "answered" end), answer: .answer, citations: [.citations[] | {page, quote, verification}]}'

Response

Produced by running the script above against a server with the fake model and these documents; make docs runs all the examples again and fails if an answer changes.

{
  "status": "answered",
  "answer": "The daily meal allowance is 35 EUR per day of travel.",
  "citations": [
    {
      "page": 1,
      "quote": "Daily meal allowance: 35 EUR per day of travel.",
      "verification": "verified"
    }
  ]
}