How princ3kr/notebook-lm-mini works
1. This repository is an AI tutoring system centered on a technical knowledge graph. The main runtime is Python, with a Streamlit UI entrypoint in app.py, and the core application logic split into services under src/services.
2. The project has two major phases: content ingestion and interactive tutoring. Ingestion turns a PDF textbook chapter into structured concept data; tutoring uses that structure to guide a student through a personalized learning path.
3. src/services/pdf_service.py is the document intake boundary. From the README, it converts PDFs into clean text/Markdown, chunks the content, and prepares it for downstream extraction. This is the first step that transforms unstructured textbook content into machine-readable units.
4. src/services/llm_service.py is the LLM integration layer. The README indicates Groq is used for extraction and pedagogical reasoning, so this service likely centralizes model calls and prompt/response handling rather than letting the rest of the code talk to the LLM directly.
5. The concept and learning-state domain is modeled in src/models/. concept.py, diagnoses.py, intent.py, and state.py suggest typed schemas for extracted concepts, quiz/diagnostic results, parsed student intent, and session state. This is the main consistency boundary between LLM output, graph storage, and tutoring logic.
6. src/services/graph_service.py is the knowledge-graph boundary. The README says concepts and relationships are stored in Neo4j, so this service likely owns graph construction, traversal, and lookup operations such as prerequisites, subtopics, and related concepts.
7. src/database/neo4j_conn.py is the infrastructure adapter for Neo4j connectivity. It isolates database configuration and session management from the rest of the system, keeping graph operations in graph_service.py and connection details in the database layer.
8. Student progress persistence is separated from the concept graph. src/database/student_db.py likely manages per-user/session data such as mastery scores, prior answers, and learning history; the README describes this as TinyDB-backed session management, so this is the stateful memory of the tutor while Neo4j is the shared knowledge base.
9. The tutoring workflow is split into distinct services: intent_service.py parses what the learner is asking for, planner_service.py chooses a learning path, diagnoser_service.py evaluates understanding, and tutor_service.py coordinates the actual teaching loop. This separation is important: intent, planning, assessment, and explanation are different responsibilities.
10. src/services/tutor_lesson_utils.py appears to hold helper logic shared by lesson delivery and remediation. In architectural terms, this is a support layer for composing lesson steps rather than a primary subsystem.
11. The end-to-end data flow is: PDF upload → text/chunk extraction → concept and relationship extraction → validation into structured JSON/models → Neo4j graph ingestion → student request parsing → path planning based on mastery and graph structure → diagnostic questioning → tutoring/remediation → session state persistence.
12. The repository also includes py-notebook/ with concept JSON files and a notebook, which looks like an experimentation and inspection area for graph/content processing. assets/workflow.svg is a documentation artifact for the system diagram rather than part of runtime execution.
13. Overall, the main architectural boundaries are: UI vs. orchestration, unstructured document processing vs. structured graph storage, shared knowledge graph vs. per-student session memory, and model/LLM output vs. validated domain schemas. That separation is what makes the tutoring flow adaptive and reproducible.
Main entry points: tutor_service.py Tutor Core · planner_service.py Planner · llm_service.py LLM Gateway · diagnoser_service.py Diagnoser
Components 17
Ingestion
Document intake and knowledge-graph construction
- PDF Intake · Converts PDFs into clean text, chunks, and extractable units
src/services/pdf_service.py - LLM Gateway · Centralized Groq prompt and response handling
src/services/llm_service.py - Graph Service · Builds and queries concept relationships in Neo4j
src/services/graph_service.py
Tutoring
Interactive planning, diagnosis, and lesson delivery
- Intent Service · Interprets learner questions and goals
src/services/intent_service.py - Planner · Selects the next concepts and study sequence
src/services/planner_service.py - Diagnoser · Evaluates understanding and drives diagnosis questions
src/services/diagnoser_service.py - Tutor Core · Coordinates intent, planning, diagnosis, and teaching
src/services/tutor_service.py - Lesson Utils · Shared helpers for lesson composition and remediation
src/services/tutor_lesson_utils.py
Data
Persistence and domain schemas
- Concepts · Structured concept representation for extracted knowledge
src/models/concept.py - Neo4j Conn · Connection and session boundary for Neo4j
src/database/neo4j_conn.py - Student DB · TinyDB-backed per-student history and mastery state
src/database/student_db.py - Intent · Typed representation of parsed learner intent
src/models/intent.py - Session State · Current learner and tutor session state
src/models/state.py - Diagnoses · Typed assessment and diagnosis results
src/models/diagnoses.py
Experiments
Notebook artifacts and extracted concept samples
- Concept JSON · Extracted concept artifacts used for inspection and experimentation
py-notebook/concepts.json - Notebook · Exploration and testing workspace for graph/content processing
py-notebook/testing.ipynb
Connections 20
- App → PDF Intake: ingest content · UI can trigger document intake and processing
- App → Tutor Core: start tutoring · UI routes learner interaction into the tutoring loop
- PDF Intake → LLM Gateway: extract structure · Document chunks are turned into structured concepts via LLM calls
- LLM Gateway → Concepts: populate · LLM output is validated into concept schema
- Concepts → Graph Service: load graph · Validated concepts become graph ingestion input
- Graph Service → Neo4j Conn: persist/query · Graph operations are executed through the Neo4j adapter
- Intent Service → LLM Gateway: parse intent · Learner requests are interpreted with model assistance
- Intent Service → Intent: validate · Parsed requests are normalized into intent schema
- Tutor Core → Intent Service: understand request · Tutor first determines what the learner wants
- Tutor Core → Planner: plan path · Tutor delegates learning-path selection to planner
- Tutor Core → Diagnoser: assess mastery · Tutor invokes diagnosis during the teaching loop
- Tutor Core → Student DB: read/write memory · Tutor persists progress and retrieves session history
- Planner → Graph Service: traverse concepts · Planning depends on graph structure and relationships
- Planner → Student DB: use history · Planning adapts to prior performance and mastery
- Planner → Session State: update state · Planner refines session state as the path changes
- Diagnoser → LLM Gateway: generate checks · Diagnostic questions and reasoning can be LLM-assisted
- Diagnoser → Diagnoses: record results · Assessment outcomes are structured as diagnosis data
- Tutor Core → Lesson Utils: compose lessons · Shared lesson helpers support explanation and remediation
- Tutor Core → Session State: track session · Tutor maintains current interaction state
- Concept JSON → Notebook: inspect · Notebook explores extracted concept artifacts