7,0111
Tests
the checks that pin this engine's behavior
ENGINE 07
SFS-E07-KBN · CITED KNOWLEDGE · REV 2026-07-20 · PRODUCTION
PRODUCTION = runnable end-to-end, CI-backed, full test suite passing. All data fictional.
Knowledge Brain
Queryable institutional memory with a citation on every answer — or no answer
Knowledge Brain turns fictional meeting transcripts into a deterministic TF-IDF index for cited questions, paste-ready footnotes, meeting prep, and review-remediation handoffs. Its remediation path generates a cited, apply-ready prompt and a PENDING change log; a downstream AI or operator owns execution and confirmation of the workpaper changes.
A knowledge system earns trust by carrying each quote back to its meeting, date, timestamp, and speaker — and by refusing to answer when no source clears the relevance floor.
Architecture
functional block stack · static overviewSelect a layer
The stack preserves chain of custody from the transcript of record through retrieval and the downstream handoff. Select a layer for its plain-terms and engineering detail.
Key specifications
at a glanceWhat it does for you
plain termsFinance and tax decisions often survive only as meeting memory or buried notes. When the same position is needed in a workpaper, disclosure, or review response, an uncited paraphrase is not enough: the user needs the recorded words, who said them, and when — or an explicit refusal when the source is absent.
A workpaper assertion gets one traceable footnote7. Cite mode filters out open items, returns the best authoritative card, and renders its transcript text byte-identically with the meeting title, date, timestamp, and speaker attached.
An off-topic question produces a machine-readable refusal8. When no card clears the relevance floor, the CLI prints “No sourced answer — the brain does not guess” and exits 3 instead of filling the gap with a plausible answer.
A review meeting becomes a cited prompt, not an untracked edit9. The remediation command retrieves four fictional reviewer directives in spoken order and generates an apply-ready prompt plus a one-to-one change log at PENDING. A downstream AI or operator performs the edits and confirms their status.
Stored knowledge drift is re-derived only where the transcript supports it10. The integrity demo starts with four injected findings, re-derives three text-or-speaker corrections across two turns, and leaves the orphaned citation quarantined. The final verdict is ESCALATED with exit 3 because no utterance exists to support that record.
Functional block diagram
engineering · each block links to its sourcePlain terms
- Fictional Transcripts. timestamped meeting utterances
- Verbatim Extractor. selects recorded statements and review requests
- Corpus + TF-IDF Index. stores cited cards and ranks them by topic
- Ask · Cite · Prep. answers a question, supplies one footnote, or prepares a meeting
- Cited Output or Refusal. returns sourced text or says there is no sourced answer
- Review Directives. retrieves the reviewer's recorded corrections in spoken order
- Cited Apply-Ready Prompt. generates the prompt and a PENDING source-to-status map
- Downstream AI / Operator. performs the requested work outside the Brain
Engineering
- Fictional Transcripts. Meeting + ordered Utterance tuples form the transcript of record
- Verbatim Extractor. timestamp lookup creates byte-identical KnowledgeCards and ChangeDirectives
- Corpus + TF-IDF Index. BrainEngine builds a deterministic keyword/tag TF-IDF index over the fixed corpus
- Ask · Cite · Prep. ask returns ranked hits, cite filters to authoritative kinds, and prep separates settled positions from open items
- Cited Output or Refusal. citation_block binds the verbatim card text to its provenance; empty hits render REFUSAL
- Review Directives. directives_for matches a review title or topic, then orders citations by meeting, timestamp, and directive_id
- Cited Apply-Ready Prompt. Remediation contains ordered directives, the generated prompt, and one FixPacketEntry per directive at STATUS_PENDING
- Downstream AI / Operator. external execution and confirmation boundary; the Brain's handoff ends with the cited prompt and PENDING log
Instruction set
every public command| Command | Operation | Output | Exit | Artifacts |
|---|---|---|---|---|
python -m brain_engine | print the fictional corpus index | meeting, card-kind, topic, and provenance catalogue | 0 | none |
python -m brain_engine ask "<question>" | retrieve the best cited cards for a question | ranked cited answer(s) or explicit refusal | 0 sourced · 3 refusal | none |
python -m brain_engine "<question>" | use the equivalent bare-question form | ranked cited answer(s) or explicit refusal | 0 sourced · 3 refusal | none |
python -m brain_engine --cite "<assertion>" | return one paste-ready authoritative footnote | verbatim quote + provenance tag or refusal | 0 sourced · 3 refusal | none |
python -m brain_engine --prep "<topic>" | assemble cited prior positions and open items | meeting-prep briefing or refusal | 0 sourced · 3 refusal | none |
python -m brain_engine remediate "<review>" | generate a cited apply-ready remediation handoff | ordered directives + generated prompt | 0 sourced · 3 refusal · 2 missing topic | none |
python -m brain_engine --seed N | accept the compatibility seed argument | the unchanged hand-authored corpus; the current build ignores N | 0 | none |
python -m brain_engine --min-relevance R ask "<question>" | set the retrieval relevance floor | cited hits clearing R or refusal | 0 / 3 · 2 if R is outside [0,1] | none |
python -m brain_engine --out DIR | write all Markdown example deliverables | index, citation, prep, remediation, and change-log files | 0 | DIR/brain_index.md · citation_example.md · meeting_prep_example.md · remediation_prompt.md · change_log.md |
python run.py --out DIR | use the convenience entrypoint | the same five Markdown deliverables | 0 | DIR/*.md |
python -m brain_engine.loop | compare the clean knowledge corpus with its transcripts | CLEAN integrity-loop report | 0 | none |
python -m brain_engine.loop --demo | inject the documented internal knowledge-drift profile | ESCALATED after supported drift is re-derived and the orphan is held | 3 | none |
python -m brain_engine.loop --seed N | accept the loop's compatibility seed argument | the same fixed-corpus integrity verdict; the current build ignores N | 0 / 3 | none |
python -m brain_engine.loop --budget N | cap internal knowledge-remediation turns | final CLEAN, REMEDIATED, or ESCALATED verdict | 0 / 3 | none |
python -m brain_engine.loop --out DIR | write the knowledge-integrity report | integrity-loop verdict and report | 0 / 3 | DIR/integrity_loop_report.md |
python -m pytest -q | run the engine test suite | pytest session summary | 0 | none |
Benchmarks
measured demo results| Measure | Result |
|---|---|
| Engine tests11 | 7,011 tests live collection, not the README's historical sample output |
| Indexed fictional corpus12 | 15 knowledge cards across 5 meetings |
| Review handoff13 | 4 cited directives mapped one-to-one to PENDING entries |
| Integrity demo recovery14 | 3 corrections over 2 turns; 1 orphan quarantined |
Control characteristics
engineeringPlain terms
Every returned answer is tied to a recorded source. The remediation boundary ends with the generated cited prompt and PENDING log; execution and confirmation belong to the downstream user or system.
Engineering
Deterministic envelope. offline default mode.
| Severity | Verdict | Action |
|---|---|---|
| No internal knowledge drift | CLEAN | nothing is changed; exit 0 |
| All internal drift has transcript support | REMEDIATED | stored text or speaker is re-derived verbatim; exit 0 |
| Orphaned source or turn budget exhausted | ESCALATED | unsupported entries are held for a human; exit 3 |
- Citation chain: returned card text is byte-identical to its transcript utterance, with meeting title, date, HH:MM:SS timestamp, and speaker attached.
- Refuse-do-not-guess: ask, cite, prep, and remediation return no sourced content when retrieval or directive matching is empty.
- Stable retrieval: fixed corpus and relevance floor produce the same scores and ranked order, with card_id as the final tie-break.
- Handoff boundary: review remediation generates cited ordered directives, an apply-ready prompt, and PENDING log entries; downstream execution and confirmation are outside the Brain.
Ask. returns the best relevant cards with citation blocks, or refuses when no card clears the floor
Cite. returns one authoritative decision, rule, or definition as a paste-ready footnote; open items are excluded
Prep. groups relevant authoritative positions separately from open items for meeting preparation
Remediate. generates the cited apply-ready prompt and PENDING change-log handoff from recorded review directives
Integrity loop. compares stored cards and directives with the transcript of record, re-derives supported drift, and quarantines orphaned citations
Operating limits
what it refuses to do- The public runnable corpus is hand-authored and fully fictional; it demonstrates the ingest-and-query stage but does not record or transcribe a live meeting.15
- Retrieval is deterministic keyword/tag TF-IDF, not semantic embeddings or a language model; a query still needs terms that score against the indexed cards.16
- Open items can appear in meeting prep but cannot support cite mode; if no authoritative card clears the floor, the engine refuses.17
- The remediation output stops at a cited apply-ready prompt and a change log whose entries begin PENDING; a downstream AI or operator performs the workpaper edits and confirms status.18
- The integrity loop can re-derive stored knowledge text or speaker only when the cited transcript utterance exists. Orphaned citations are quarantined rather than repaired from a guess.19
See it run
brand animation
Integration
how to run itDistribution: public repository, MIT license.
git clone https://github.com/sophonfinance-wq/finance-automation-portfolio.git && cd finance-automation-portfolio/knowledge-brain-engine && python -m brain_engine
python -m brain_engine --cite "return of capital in excess of basis is a deemed gain"
python -m brain_engine remediate "Surplus Workpaper Review — Reviewer Corrections"
Substantiation
- 1py -3 -m pytest --collect-only -q -o addopts= (knowledge-brain-engine/); live collection verified 2026-07-20 and pinned in site-datasheets/counts.json
- 2python -m brain_engine (knowledge-brain-engine/) — live index reports 5 meetings; brain_engine/generate.py builds the five-meeting fictional corpus
- 3python -m brain_engine (knowledge-brain-engine/) — live index reports 15 knowledge cards
- 4brain_engine/model.py CARD_KINDS — decision, rule, definition, open-item; confirmed by the live index
- 5python -m brain_engine remediate "Surplus Workpaper Review — Reviewer Corrections" — live CLI emits 4 cited directives in spoken order
- 6brain_engine/cli.py main — ask, cite, prep, and remediate return 3 when no sourced result exists; confirmed with an off-topic live CLI query
- 7python -m brain_engine --cite "return of capital in excess of basis is a deemed gain"; brain_engine/engine.py cite; brain_engine/report.py render_citation
- 8python -m brain_engine ask "what is the office parking and lunch policy"; live exit 3; brain_engine/cli.py and brain_engine/report.py
- 9python -m brain_engine remediate "Surplus Workpaper Review — Reviewer Corrections"; brain_engine/engine.py remediate; knowledge-brain-engine/README.md Review → remediation
- 10python -m brain_engine.loop --demo (knowledge-brain-engine/); live demo output; brain_engine/loop.py
- 11py -3 -m pytest --collect-only -q -o addopts= (knowledge-brain-engine/); verified 2026-07-20 and pinned in site-datasheets/counts.json
- 12python -m brain_engine — live index summary; brain_engine/generate.py build_corpus
- 13python -m brain_engine remediate "Surplus Workpaper Review — Reviewer Corrections" — live CLI output; brain_engine/engine.py
- 14python -m brain_engine.loop --demo — live output reports 3 corrections, 2 turns, and 1 quarantined orphan
- 15knowledge-brain-engine/README.md — public runnable version over invented transcripts; brain_engine/generate.py module documentation
- 16brain_engine/engine.py — stdlib TF-IDF index, tokenization, weighted tags, and MIN_RELEVANCE
- 17brain_engine/model.py AUTHORITATIVE_KINDS; brain_engine/engine.py cite and prep
- 18knowledge-brain-engine/README.md Review → remediation; brain_engine/engine.py Remediation and STATUS_PENDING; brain_engine/report.py
- 19brain_engine/loop.py — REMEDIABLE excludes ORPHANED; integrity_loop and verdict_exit_code
Show us where the hours go.
One conversation: you describe the work that consumes your team's month; we tell you plainly what this engine can take over, what it can't, and what a scoped first phase would cost. Your people keep approval authority.
Book a free consultation