A complete reference for the types you'll touch. Short version: on the source-facing types, only artifact_id is required.
Chunk
A piece of retrieved evidence your Retriever returns.
| Field | Required | Default | Meaning |
|---|---|---|---|
artifact_id | Yes | — | The source's natural id (document id, row key, URL, tool identity). |
text | Yes | — | The content. |
version | No | "" | A native revision (Confluence version, git sha, ETag…). |
content_hash | No | "" | Hash of the content; computed for you when absent. |
meta | No | None | New in v0.7 Ingest metadata (Mapping[str, str]). Recognized keys title / source / date feed the metadata-first default pool header ([title | source | date]) and constraints= matching; extras are preserved on the unit. Meta-less chunks are byte-identical to pre-0.7. |
Synthesis
What a Synthesizer returns.
| Field | Required | Default | Meaning |
|---|---|---|---|
understanding | Yes | — | Structured dict. With the extractive default (extract=True, New in v0.4) the substance is claims — a query-independent list of atomic, source-grounded claims — and summary may be terse or empty (entities / facts optional). extract=False restores the v0.3 prose-summary shape. |
used | No | [] | Indices of the chunks actually used → precise provenance. |
ok | No | True | False = synthesis failed; the cache degrades instead of caching garbage. |
ChangeEvent
A "this source changed" signal. Usually produced by source_changed / a connector.
| Field | Required | Default | Meaning |
|---|---|---|---|
artifact_id | Yes | — | Which source changed (must match provenance). |
version | No | "" | New revision. |
content_hash | No | "" | Hash of new content (most precise skip-no-op check). |
kind | No | "update" | "delete" evicts the unit. |
FreshnessPolicy
| Field | Default | Meaning |
|---|---|---|
max_age | None | Seconds before a unit is revalidated on read. |
revalidate | None | `(artifact_id) -> (text, version) |
ContextStrategy
CONTEXT_FIRST (default — raw only when escalated) · CONTEXT_RAW (always) · CONTEXT_ONLY (never). The strategy shapes the unit path's payload; on the default pool path the payload is the packed claim pool, Result.evidence is [] on non-escalated serves, and raw is reached via drill(unit_id) (or appended by escalation).
Result & Related
See get() & Result for the full Result fields — including the v0.7 provenance-and-doubt surface (sources, max_source_age_s, probes, probe_coverage, gaps, parent_read_id). A Related has unit_id, understanding, evidence, relation ("shared_entity" | "shared_source"), and score.
RepairReport
New in v0.7 Returned by repair(read_id) — the pump's receipt.
| Field | Meaning |
|---|---|
read_id | The read this repair consumed. |
candidates_seen | Candidate spans considered — the read's banked detector fires + constraints matches, plus bridge candidates derived at repair time, de-duplicated. |
extracted | Claim strings the BYO extractor returned across all calls. |
rejected | Extracted claims refused by mechanical admission hygiene (antecedent-free pronoun subjects, truncated claims). |
admitted | Survivors of dedup appended to their owning units (≤ 8 per call). |
claims | One provenance dict per admitted claim: {claim, unit_id, span, source, origin, via, ts} — the same record appended under understanding["_repair_provenance"]. |
units_touched | The units that grew. |
InvalidationResult
Returned by source_changed / invalidate: dirtied, skipped_unchanged, deleted (lists of unit ids), and matched_units (int — 0 means the change matched nothing).
Next
- get() & Result — the read result in full.
- Examples — these types in real code.