# emnamastouri/mathtutorai architecture

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

- Interactive diagram: https://gitdiagram.com/emnamastouri/mathtutorai
- Repository: https://github.com/emnamastouri/mathtutorai

## Overview

MathTutorAI serves verified Tunisian Bac mathematics exercises and Socratic tutoring, with a teacher workspace. The student workflow enters through the Streamlit interface and service, which serves a bank exercise or requests generation through the hybrid bridge; generated content is built from a mathematical skeleton, formulated, then checked before delivery. Separate branches cover tutoring, teacher tools, and learner progress. Relationships reflect the README and source-index references; unsampled implementation details are represented only where documented, so some links are intentionally omitted.

Main entry points: [`src/pipeline.py`](https://github.com/emnamastouri/mathtutorai/blob/main/src/pipeline.py) (Hybrid generator), [`mtai/service.py`](https://github.com/emnamastouri/mathtutorai/blob/main/mtai/service.py) (Tutor service), [`mtai/teacher.py`](https://github.com/emnamastouri/mathtutorai/blob/main/mtai/teacher.py) (Teacher tools), [`app/streamlit_ui.py`](https://github.com/emnamastouri/mathtutorai/blob/main/app/streamlit_ui.py) (Streamlit interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and service"]
  node_ui["Streamlit interface<br/>[streamlit_ui.py]"]
  node_service["Tutor service<br/>[service.py]"]
  node_bank[("Exercise bank<br/>[bank.py]")]
  node_bridge["Hybrid bridge<br/>[hybrid_bridge.py]"]
end

subgraph group_generation["Exercise generation"]
  node_pipeline["Hybrid generator<br/>[pipeline.py]"]
  node_curriculum["Curriculum resolver<br/>[resolver.py]"]
  node_families["Generator registry<br/>[registry.py]"]
  node_skeletons["Verified skeletons"]
  node_formulation["LLM formulation<br/>[formulate.py]"]
  node_provider["Model provider<br/>[provider.py]"]
  node_retrieval["Bac example retrieval<br/>[retriever.py]"]
end

subgraph group_verification["Verification"]
  node_symbolic["Symbolic verifier<br/>[sympy_engine.py]"]
  node_postcheck["Post-formulation gates<br/>[post_llm.py]"]
  node_claims["Claim verification<br/>[claims.py]"]
  node_figures["Figures and tables<br/>[figures.py]"]
end

subgraph group_tutoring["Tutoring and learning"]
  node_tutor["Socratic tutor<br/>[socratic_tutor.py]"]
  node_guard["Answer leak guard<br/>[guard.py]"]
  node_learner[("Learner memory<br/>[learner_memory.py]")]
end

subgraph group_teacher["Teacher workspace"]
  node_teacher_tools["Teacher tools<br/>[teacher.py]"]
  node_teacher_agent["Teacher agent<br/>[teacher_agent.py]"]
end

node_student(("Student"))
node_teacher_user(("Teacher"))

node_student -->|"uses"| node_ui
node_teacher_user -->|"uses"| node_ui
node_ui -->|"calls"| node_service
node_service -->|"checks first"| node_bank
node_service -->|"builds system"| node_bridge
node_bridge -->|"runs generation"| node_pipeline
node_pipeline -->|"resolves scope"| node_curriculum
node_pipeline -->|"selects family"| node_families
node_families -->|"maps generators"| node_skeletons
node_pipeline -->|"builds skeleton"| node_skeletons
node_pipeline -->|"retrieves examples"| node_retrieval
node_pipeline -->|"formulates exercise"| node_formulation
node_formulation -->|"requests text"| node_provider
node_pipeline -->|"checks output"| node_postcheck
node_postcheck -->|"verifies contract"| node_symbolic
node_postcheck -->|"checks assertions"| node_claims
node_student -->|"requests tutoring"| node_service
node_service -->|"delegates dialogue"| node_tutor
node_tutor -->|"guards replies"| node_guard
node_tutor -->|"uses memory"| node_learner
node_teacher_user -->|"uses"| node_teacher_tools
node_ui -->|"opens workspace"| node_teacher_tools
node_teacher_tools -->|"validates exercises"| node_bank
node_teacher_tools -->|"renders figures"| node_figures
node_teacher_tools -.->|"delegates generation"| node_teacher_agent

click node_ui "https://github.com/emnamastouri/mathtutorai/blob/main/app/streamlit_ui.py"
click node_service "https://github.com/emnamastouri/mathtutorai/blob/main/mtai/service.py"
click node_bank "https://github.com/emnamastouri/mathtutorai/blob/main/mtai/bank.py"
click node_bridge "https://github.com/emnamastouri/mathtutorai/blob/main/app/hybrid_bridge.py"
click node_pipeline "https://github.com/emnamastouri/mathtutorai/blob/main/src/pipeline.py"
click node_curriculum "https://github.com/emnamastouri/mathtutorai/blob/main/src/curriculum/resolver.py"
click node_families "https://github.com/emnamastouri/mathtutorai/blob/main/src/generators/registry.py"
click node_skeletons "https://github.com/emnamastouri/mathtutorai/blob/main/core/verified_generator.py"
click node_formulation "https://github.com/emnamastouri/mathtutorai/blob/main/src/llm/formulate.py"
click node_provider "https://github.com/emnamastouri/mathtutorai/blob/main/src/llm/provider.py"
click node_retrieval "https://github.com/emnamastouri/mathtutorai/blob/main/src/rag/retriever.py"
click node_symbolic "https://github.com/emnamastouri/mathtutorai/blob/main/core/sympy_engine.py"
click node_postcheck "https://github.com/emnamastouri/mathtutorai/blob/main/src/verification/post_llm.py"
click node_claims "https://github.com/emnamastouri/mathtutorai/blob/main/src/verification/claims.py"
click node_figures "https://github.com/emnamastouri/mathtutorai/blob/main/core/figures.py"
click node_tutor "https://github.com/emnamastouri/mathtutorai/blob/main/src/tutor/socratic_tutor.py"
click node_guard "https://github.com/emnamastouri/mathtutorai/blob/main/mtai/guard.py"
click node_learner "https://github.com/emnamastouri/mathtutorai/blob/main/src/memory/learner_memory.py"
click node_teacher_tools "https://github.com/emnamastouri/mathtutorai/blob/main/mtai/teacher.py"
click node_teacher_agent "https://github.com/emnamastouri/mathtutorai/blob/main/core/teacher_agent.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_ui,node_service,node_bank,node_bridge toneBlue
class node_pipeline,node_curriculum,node_families,node_skeletons,node_formulation,node_provider,node_retrieval toneAmber
class node_symbolic,node_postcheck,node_claims,node_figures toneMint
class node_tutor,node_guard,node_learner toneRose
class node_teacher_tools,node_teacher_agent,node_student,node_teacher_user toneIndigo
```

## Components

### App and service

- [Streamlit interface](https://github.com/emnamastouri/mathtutorai/blob/main/app/streamlit_ui.py): `app/streamlit_ui.py`
- [Tutor service](https://github.com/emnamastouri/mathtutorai/blob/main/mtai/service.py): `mtai/service.py`
- [Exercise bank](https://github.com/emnamastouri/mathtutorai/blob/main/mtai/bank.py): `mtai/bank.py`
- [Hybrid bridge](https://github.com/emnamastouri/mathtutorai/blob/main/app/hybrid_bridge.py): `app/hybrid_bridge.py`

### Exercise generation

- [Hybrid generator](https://github.com/emnamastouri/mathtutorai/blob/main/src/pipeline.py): `src/pipeline.py`
- [Curriculum resolver](https://github.com/emnamastouri/mathtutorai/blob/main/src/curriculum/resolver.py): `src/curriculum/resolver.py`
- [Generator registry](https://github.com/emnamastouri/mathtutorai/blob/main/src/generators/registry.py): `src/generators/registry.py`
- [Verified skeletons](https://github.com/emnamastouri/mathtutorai/blob/main/core/verified_generator.py): `core/verified_generator.py`
- [LLM formulation](https://github.com/emnamastouri/mathtutorai/blob/main/src/llm/formulate.py): `src/llm/formulate.py`
- [Model provider](https://github.com/emnamastouri/mathtutorai/blob/main/src/llm/provider.py): `src/llm/provider.py`
- [Bac example retrieval](https://github.com/emnamastouri/mathtutorai/blob/main/src/rag/retriever.py): `src/rag/retriever.py`

### Verification

- [Symbolic verifier](https://github.com/emnamastouri/mathtutorai/blob/main/core/sympy_engine.py): `core/sympy_engine.py`
- [Post-formulation gates](https://github.com/emnamastouri/mathtutorai/blob/main/src/verification/post_llm.py): `src/verification/post_llm.py`
- [Claim verification](https://github.com/emnamastouri/mathtutorai/blob/main/src/verification/claims.py): `src/verification/claims.py`
- [Figures and tables](https://github.com/emnamastouri/mathtutorai/blob/main/core/figures.py): `core/figures.py`

### Tutoring and learning

- [Socratic tutor](https://github.com/emnamastouri/mathtutorai/blob/main/src/tutor/socratic_tutor.py): `src/tutor/socratic_tutor.py`
- [Answer leak guard](https://github.com/emnamastouri/mathtutorai/blob/main/mtai/guard.py): `mtai/guard.py`
- [Learner memory](https://github.com/emnamastouri/mathtutorai/blob/main/src/memory/learner_memory.py): `src/memory/learner_memory.py`

### Teacher workspace

- [Teacher tools](https://github.com/emnamastouri/mathtutorai/blob/main/mtai/teacher.py): `mtai/teacher.py`
- [Teacher agent](https://github.com/emnamastouri/mathtutorai/blob/main/core/teacher_agent.py): `core/teacher_agent.py`

### Other components

- **Student**
- **Teacher**

## Connections

- Student → Streamlit interface: uses (evidence: `README.md`)
- Teacher → Streamlit interface: uses (evidence: `README.md`)
- Streamlit interface → Tutor service: calls (evidence: `app/streamlit_ui.py`)
- Tutor service → Exercise bank: checks first (evidence: `mtai/service.py`)
- Tutor service → Hybrid bridge: builds system (evidence: `mtai/service.py`)
- Hybrid bridge → Hybrid generator: runs generation (evidence: `app/hybrid_bridge.py`)
- Hybrid generator → Curriculum resolver: resolves scope (evidence: `src/pipeline.py`)
- Hybrid generator → Generator registry: selects family (evidence: `src/pipeline.py`)
- Generator registry → Verified skeletons: maps generators (evidence: `src/generators/registry.py`)
- Hybrid generator → Verified skeletons: builds skeleton (evidence: `src/pipeline.py`)
- Hybrid generator → Bac example retrieval: retrieves examples (evidence: `src/pipeline.py`)
- Hybrid generator → LLM formulation: formulates exercise (evidence: `src/pipeline.py`)
- LLM formulation → Model provider: requests text (evidence: `src/llm/formulate.py`)
- Hybrid generator → Post-formulation gates: checks output (evidence: `src/pipeline.py`)
- Post-formulation gates → Symbolic verifier: verifies contract (evidence: `src/verification/post_llm.py`)
- Post-formulation gates → Claim verification: checks assertions (evidence: `src/verification/post_llm.py`)
- Student → Tutor service: requests tutoring (evidence: `README.md`)
- Tutor service → Socratic tutor: delegates dialogue (evidence: `mtai/service.py`)
- Socratic tutor → Answer leak guard: guards replies (evidence: `README.md`)
- Socratic tutor → Learner memory: uses memory (evidence: `src/tutor/socratic_tutor.py`)
- Teacher → Teacher tools: uses (evidence: `README.md`)
- Streamlit interface → Teacher tools: opens workspace (evidence: `app/streamlit_ui.py`)
- Teacher tools → Exercise bank: validates exercises (evidence: `mtai/teacher.py`)
- Teacher tools → Figures and tables: renders figures (evidence: `mtai/teacher.py`)
- Teacher tools → Teacher agent: delegates generation