get() is the one method you'll use. It embeds the query, serves a semantically-matching fresh unit, or retrieves + synthesizes a new one — always with the raw evidence retained.
Signature
ctx = cache.get(
query,
*,
namespace=None, # optional tenant/filter scope
related=3, # fold in up to N related units (0 to disable)
strategy=None, # override the ContextStrategy for this call
)
Just pass the question — the cache is keyed by the query's meaning, so similar phrasings reuse the same understanding.
Result
ctx.context # minimum decision-relevant payload: {"understanding": {...}, "raw": [...]}
ctx.understanding# the full structured understanding (dict)
ctx.evidence # all retained raw chunks — always reachable for specifics
ctx.raw_text # those chunks as one string
ctx.cache_hit # True if served from cache, False if just built
ctx.coverage # 0–1: how well the unit covers the query
ctx.escalated # True if it pulled fresh raw to cover the query
ctx.confidence # semantic match strength of the hit
ctx.related # list[Related] — cross-unit reuse (see below)
ctx.unit_id # the cached unit's id
ctx.namespace # the namespace this read used
Field reference
| Field | Type | Meaning |
|---|---|---|
context | dict | What to hand the LLM: projected understanding + raw (per strategy). |
understanding | dict | Full summary / claims / entities / facts. |
evidence | list[Chunk] | All retained raw — always reachable for specifics. |
cache_hit | bool | Served from cache vs. freshly built. |
coverage | float | Query terms represented in the unit (drives escalation). |
escalated | bool | Fresh raw was pulled because the hit under-covered. |
related | list[Related] | Related units: unit_id, relation, understanding, score. |
Examples
# the common case
ctx = cache.get("what is our leave policy?")
# multi-tenant isolation
ctx = cache.get("vacation rules", namespace="acme-corp")
# always include raw, and skip related expansion
from coalent import ContextStrategy
ctx = cache.get("leave policy", related=0, strategy=ContextStrategy.CONTEXT_RAW)
Next
- Context intelligence — coverage, escalation, strategies, related.
- Data model — every field on the supporting types.