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. |
Synthesis
What a Synthesizer returns.
| Field | Required | Default | Meaning |
|---|---|---|---|
understanding | Yes | — | Structured dict (summary, claims, entities, facts). |
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). Raw is always reachable via Result.evidence regardless.
Result & Related
See get() & Result for the full Result fields. A Related has unit_id, understanding, evidence, relation ("shared_entity" | "shared_source"), and score.
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.