core.librarian
core.librarian
Zone A — the Librarian: core RAG query agent over the thought-graph (BUILD-SPEC §9).
Semantic retrieval over the AUTHORED mirror + grounded reasoning under the Constitution, with a deterministic grounding self-check before returning. The de-identified research criteria seam (§16) lands with the airlock (Phase 8).
Librarian
dataclass
server
instance-attribute
embedder
instance-attribute
store
instance-attribute
tier = 'routine'
class-attribute
instance-attribute
k = 5
class-attribute
instance-attribute
raw = None
class-attribute
instance-attribute
retrieve(query, *, provenances=MIRROR_READABLE)
Semantic retrieval over the thought-graph. Defaults to the mirror
(AUTHORED-only); the assistant tier (Phase 3+) may widen provenances.
With a raw store wired, each hit is verified to reproduce from its content-addressed
source before it is returned (fail-closed integrity, audit G9.5): a tampered/unreproducible
row is dropped (logged) rather than cited to the model under a clean digest.
context_for(query, retrievals, *, history=None)
Constitution outermost; role; retrieved grounding; history; the query last.
answer(query, *, history=None, provenances=MIRROR_READABLE, judge=None, think=None)
research_criteria(query, *, proposer=None, from_year=None, publication_types=(), max_results=50)
Emit de-identified research criteria for the outbound airlock (§16).
The proposer (default: the deterministic keyword extractor; or a model-backed one)
only suggests terms — deidentify() is the enforcer that scrubs PII and rejects
free narrative. The corpus never enters this path; only the query's topical terms,
de-identified, can leave (Invariant 11).
LibrarianAnswer
dataclass
text
instance-attribute
sources
instance-attribute
check
instance-attribute
Retrieval
dataclass
title
instance-attribute
source_path
instance-attribute
text
instance-attribute
distance
instance-attribute
provenance
instance-attribute
digest = ''
class-attribute
instance-attribute
build_librarian(config=None, *, k=5)
Wire a Librarian against the real configured stores and models.
librarian
The Librarian — the core RAG query agent over the thought-graph (BUILD-SPEC §9).
The owner's primary interface to their own mind: semantic retrieval over the AUTHORED corpus (the mirror — defaults to MIRROR_READABLE so observed exhaust can never leak in, the firewall from design-notes/observed-data-and-the-assistant-tier.md), then grounded reasoning with the Constitution as the outermost frame (Invariant 6).
Per mirror, not oracle (Constitution §III.2) it presents synthesis as a lens on the
owner's own notes, cites only the notes it actually retrieved, and says plainly when the
corpus does not cover the question. Before returning, it runs the Constitution pre-return
check (core.selfcheck): the deterministic grounding check verifies every cited note
resolves to a retrieved source.
Airlock seam (Phase 8, §16): the librarian also emits de-identified research criteria
for the outbound fetchers (research_criteria). The model only proposes terms; the
de-identification enforcement lives in core.research.criteria (the model advises, code acts).
logger = logging.getLogger(__name__)
module-attribute
LIBRARIAN_ROLE = "You are the Librarian of a sealed personal mind-palace: a mirror onto the owner's own notes, not an oracle.\n\nGround every substantive claim in the retrieved notes below. Cite the notes you draw on by title in double brackets, e.g. [[note title]]. Never cite a note that is not in the retrieved context, and never invent notes, quotes, facts, or citations.\n\nWhen the retrieved notes do not answer the question, say so plainly instead of guessing. Surface uncertainty. Offer the patterns and options you see and let the owner draw the conclusions — the judgment is theirs."
module-attribute
NO_CONTEXT = 'No notes were retrieved for this query; the corpus has nothing on it.'
module-attribute
TermProposer = Callable[[str], 'tuple[str, list[str]]']
module-attribute
CRITERIA_PROPOSER_ROLE = "You turn a personal question into de-identified literature-search terms. Output ONLY a short topic label and 3-8 generic medical/scientific search terms. Strip every personal detail — no names, dates, places, employers, or first-person narrative. Terms must be generic topical phrases a literature database would understand (e.g. 'migraine prophylaxis', 'chronic stress'). Reply as: 'topic: <label>' then one term per line."
module-attribute
Retrieval
dataclass
title
instance-attribute
source_path
instance-attribute
text
instance-attribute
distance
instance-attribute
provenance
instance-attribute
digest = ''
class-attribute
instance-attribute
LibrarianAnswer
dataclass
text
instance-attribute
sources
instance-attribute
check
instance-attribute
Librarian
dataclass
server
instance-attribute
embedder
instance-attribute
store
instance-attribute
tier = 'routine'
class-attribute
instance-attribute
k = 5
class-attribute
instance-attribute
raw = None
class-attribute
instance-attribute
retrieve(query, *, provenances=MIRROR_READABLE)
Semantic retrieval over the thought-graph. Defaults to the mirror
(AUTHORED-only); the assistant tier (Phase 3+) may widen provenances.
With a raw store wired, each hit is verified to reproduce from its content-addressed
source before it is returned (fail-closed integrity, audit G9.5): a tampered/unreproducible
row is dropped (logged) rather than cited to the model under a clean digest.
context_for(query, retrievals, *, history=None)
Constitution outermost; role; retrieved grounding; history; the query last.
answer(query, *, history=None, provenances=MIRROR_READABLE, judge=None, think=None)
research_criteria(query, *, proposer=None, from_year=None, publication_types=(), max_results=50)
Emit de-identified research criteria for the outbound airlock (§16).
The proposer (default: the deterministic keyword extractor; or a model-backed one)
only suggests terms — deidentify() is the enforcer that scrubs PII and rejects
free narrative. The corpus never enters this path; only the query's topical terms,
de-identified, can leave (Invariant 11).
build_librarian(config=None, *, k=5)
Wire a Librarian against the real configured stores and models.
model_term_proposer(server, *, tier='routine')
A richer proposer that asks the local model to suggest de-identified terms.
The model only advises; its output is still scrubbed by deidentify() before anything
can cross the airlock. Parsing is forgiving — a malformed reply degrades to whatever
clean terms it yields (and deidentify raises if none remain).