# sanelemanyela/academic-truth-engine architecture

> Architecture diagram of the GitHub repository sanelemanyela/academic-truth-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sanelemanyela/academic-truth-engine
- Repository: https://github.com/sanelemanyela/academic-truth-engine

## Overview

Academic Truth Engine is a local, notebook-driven research assistant for answering questions from academic PDFs. Its principal workflow ingests and validates a PDF, recovers text with OCR when needed, creates citation-oriented semantic chunks, persists them in Chroma, retrieves evidence, and generates a grounded answer. Users can interact through a notebook Q&A loop or the injected widget UI; optional outputs include visual panels and structured briefs. The notebook’s implementation was not sampled, so those stage relationships are based on the README; source-level evidence is available for the UI query call and the local retriever packs.

Main entry points: [`Academic_Truth_Engine_v3.ipynb`](https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb) (Research notebook), [`mempalace_db`](https://github.com/sanelemanyela/academic-truth-engine/tree/main/mempalace_db) (Chroma memory), [`ate_ui.py`](https://github.com/sanelemanyela/academic-truth-engine/blob/main/ate_ui.py) (Q&A widget), [`academic_data/source_material.pdf`](https://github.com/sanelemanyela/academic-truth-engine/blob/main/academic_data/source_material.pdf) (Academic PDF)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Research workflow"]
  node_notebook["Research notebook"]
  node_pdf_source["Academic PDF"]
  node_pdf_ingestion["PDF ingestion"]
  node_text_recovery["Text and OCR"]
  node_semantic_chunks["Semantic chunks"]
end

subgraph group_memory["Memory and retrieval"]
  node_chroma[("Chroma memory")]
  node_query_rewriting["Query rewriting<br/>[base.py]"]
  node_hybrid_fusion["Hybrid fusion<br/>[base.py]"]
  node_evidence_retrieval["Evidence retrieval"]
end

subgraph group_answer["Answer and outputs"]
  node_answer_generation["Grounded answer"]
  node_model_service["Model inference"]
  node_visual_output["Visual panels"]
  node_brief_export["Brief export"]
end

subgraph group_interface["User interface"]
  node_widget_ui["Q&amp;A widget<br/>[ate_ui.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"asks questions"| node_widget_ui
node_researcher -->|"runs workflow"| node_notebook
node_widget_ui -->|"calls query"| node_notebook
node_pdf_source -->|"provides PDF"| node_pdf_ingestion
node_pdf_ingestion -->|"extracts text"| node_text_recovery
node_text_recovery -->|"builds chunks"| node_semantic_chunks
node_semantic_chunks -->|"persists chunks"| node_chroma
node_notebook -->|"ingests source"| node_pdf_ingestion
node_notebook -->|"runs retrieval"| node_evidence_retrieval
node_notebook -->|"generates answer"| node_answer_generation
node_notebook -.->|"renders optionally"| node_visual_output
node_notebook -.->|"exports optionally"| node_brief_export
node_query_rewriting -->|"rewrites queries"| node_evidence_retrieval
node_hybrid_fusion -->|"fuses retrievers"| node_evidence_retrieval
node_chroma -.->|"supplies memory"| node_evidence_retrieval
node_evidence_retrieval -->|"grounds response"| node_answer_generation
node_answer_generation -.->|"requests inference"| node_model_service

click node_notebook "https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb"
click node_pdf_source "https://github.com/sanelemanyela/academic-truth-engine/blob/main/academic_data/source_material.pdf"
click node_pdf_ingestion "https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb"
click node_text_recovery "https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb"
click node_semantic_chunks "https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb"
click node_chroma "https://github.com/sanelemanyela/academic-truth-engine/tree/main/mempalace_db"
click node_query_rewriting "https://github.com/sanelemanyela/academic-truth-engine/blob/main/query_rewriting_pack/llama_index/packs/fusion_retriever/query_rewrite/base.py"
click node_hybrid_fusion "https://github.com/sanelemanyela/academic-truth-engine/blob/main/query_rewriting_pack/llama_index/packs/fusion_retriever/hybrid_fusion/base.py"
click node_evidence_retrieval "https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb"
click node_answer_generation "https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb"
click node_visual_output "https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb"
click node_brief_export "https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb"
click node_widget_ui "https://github.com/sanelemanyela/academic-truth-engine/blob/main/ate_ui.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_notebook,node_pdf_source,node_pdf_ingestion,node_text_recovery,node_semantic_chunks toneBlue
class node_chroma,node_query_rewriting,node_hybrid_fusion,node_evidence_retrieval toneAmber
class node_answer_generation,node_model_service,node_visual_output,node_brief_export toneMint
class node_widget_ui toneRose
class node_researcher toneIndigo
```

## Components

### Research workflow

- [Research notebook](https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb): `Academic_Truth_Engine_v3.ipynb`
- [Academic PDF](https://github.com/sanelemanyela/academic-truth-engine/blob/main/academic_data/source_material.pdf): `academic_data/source_material.pdf`
- [PDF ingestion](https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb): `Academic_Truth_Engine_v3.ipynb`
- [Text and OCR](https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb): `Academic_Truth_Engine_v3.ipynb`
- [Semantic chunks](https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb): `Academic_Truth_Engine_v3.ipynb`

### Memory and retrieval

- [Chroma memory](https://github.com/sanelemanyela/academic-truth-engine/tree/main/mempalace_db): `mempalace_db`
- [Query rewriting](https://github.com/sanelemanyela/academic-truth-engine/blob/main/query_rewriting_pack/llama_index/packs/fusion_retriever/query_rewrite/base.py): `query_rewriting_pack/llama_index/packs/fusion_retriever/query_rewrite/base.py`
- [Hybrid fusion](https://github.com/sanelemanyela/academic-truth-engine/blob/main/query_rewriting_pack/llama_index/packs/fusion_retriever/hybrid_fusion/base.py): `query_rewriting_pack/llama_index/packs/fusion_retriever/hybrid_fusion/base.py`
- [Evidence retrieval](https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb): `Academic_Truth_Engine_v3.ipynb`

### Answer and outputs

- [Grounded answer](https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb): `Academic_Truth_Engine_v3.ipynb`
- **Model inference**
- [Visual panels](https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb): `Academic_Truth_Engine_v3.ipynb`
- [Brief export](https://github.com/sanelemanyela/academic-truth-engine/blob/main/Academic_Truth_Engine_v3.ipynb): `Academic_Truth_Engine_v3.ipynb`

### User interface

- [Q&A widget](https://github.com/sanelemanyela/academic-truth-engine/blob/main/ate_ui.py): `ate_ui.py`

### Other components

- **Researcher**

## Connections

- Researcher → Q&A widget: asks questions (evidence: `ate_ui.py`)
- Researcher → Research notebook: runs workflow (evidence: `ReadMe.md`)
- Q&A widget → Research notebook: calls query (evidence: `ate_ui.py`)
- Academic PDF → PDF ingestion: provides PDF (evidence: `ReadMe.md`)
- PDF ingestion → Text and OCR: extracts text (evidence: `ReadMe.md`)
- Text and OCR → Semantic chunks: builds chunks (evidence: `ReadMe.md`)
- Semantic chunks → Chroma memory: persists chunks (evidence: `ReadMe.md`)
- Research notebook → PDF ingestion: ingests source (evidence: `ReadMe.md`)
- Research notebook → Evidence retrieval: runs retrieval (evidence: `ReadMe.md`)
- Research notebook → Grounded answer: generates answer (evidence: `ReadMe.md`)
- Research notebook → Visual panels: renders optionally (evidence: `ReadMe.md`)
- Research notebook → Brief export: exports optionally (evidence: `ReadMe.md`)
- Query rewriting → Evidence retrieval: rewrites queries (evidence: `query_rewriting_pack/llama_index/packs/fusion_retriever/query_rewrite/base.py`)
- Hybrid fusion → Evidence retrieval: fuses retrievers (evidence: `query_rewriting_pack/llama_index/packs/fusion_retriever/hybrid_fusion/base.py`)
- Chroma memory → Evidence retrieval: supplies memory (evidence: `ReadMe.md`)
- Evidence retrieval → Grounded answer: grounds response (evidence: `ReadMe.md`)
- Grounded answer → Model inference: requests inference (evidence: `ReadMe.md`)
