# harshalwaghare18/ai-math-mentor architecture

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

- Interactive diagram: https://gitdiagram.com/harshalwaghare18/ai-math-mentor
- Repository: https://github.com/harshalwaghare18/ai-math-mentor

## Overview

AI Math Mentor is a Streamlit JEE-math tutor with text, image, and audio inputs. The documented workflow turns user input into a parsed problem, routes it, retrieves relevant math knowledge, generates and verifies a solution, then presents an explanation and feedback UI. The README describes that six-stage agent pipeline, while the sampled app excerpt also shows an inline Groq-solving path; it does not show app-to-agent calls. OCR, transcription, knowledge retrieval, and memory are represented by their sampled implementations, but the excerpt does not establish that all are wired into the app’s runtime.

Main entry points: [`app.py`](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/app.py) (Streamlit app), [`agents/solver_agent.py`](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/agents/solver_agent.py) (Math solver), [`rag/knowledge_base.py`](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/rag/knowledge_base.py) (Math knowledge base), [`utils/ocr_handler.py`](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/utils/ocr_handler.py) (Image OCR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Input and presentation"]
  node_app["Streamlit app<br/>[app.py]"]
  node_image["Image OCR<br/>[ocr_handler.py]"]
  node_audio["Audio transcription<br/>[audio_handler.py]"]
  node_trace["Trace and feedback<br/>[app.py]"]
end

subgraph group_pipeline["Solution pipeline"]
  node_parser["Problem parser<br/>[parser_agent.py]"]
  node_router["Intent router<br/>[router_agent.py]"]
  node_solver["Math solver<br/>[solver_agent.py]"]
  node_verifier["Solution verifier<br/>[verifier_agent.py]"]
  node_explainer["Solution explainer<br/>[explainer_agent.py]"]
end

subgraph group_knowledge["Knowledge and memory"]
  node_kb[("Math knowledge base<br/>[knowledge_base.py]")]
  node_docs["Math reference docs"]
  node_memory[("Attempt memory<br/>[memory_manager.py]")]
end

subgraph group_services["External services"]
  node_groq{{"Groq LLM and Whisper"}}
  node_tesseract{{"Tesseract OCR"}}
  node_openai{{"OpenAI embeddings and LLM"}}
end

node_user(("Student"))

node_user -->|"submits problem"| node_app
node_app -.->|"extracts image text"| node_image
node_app -.->|"transcribes audio"| node_audio
node_app -.->|"passes input"| node_parser
node_parser -.->|"parsed problem"| node_router
node_router -.->|"selects strategy"| node_solver
node_solver -->|"retrieves context"| node_kb
node_kb -->|"indexes text"| node_docs
node_solver -.->|"solution for review"| node_verifier
node_verifier -.->|"verified solution"| node_explainer
node_explainer -.->|"presents explanation"| node_app
node_app -->|"renders trace"| node_trace
node_app -->|"requests completion"| node_groq
node_app -.->|"stores attempts"| node_memory
node_image -->|"runs OCR"| node_tesseract
node_audio -->|"requests transcription"| node_openai
node_kb -->|"embeds documents"| node_openai

click node_app "https://github.com/harshalwaghare18/ai-math-mentor/blob/main/app.py"
click node_image "https://github.com/harshalwaghare18/ai-math-mentor/blob/main/utils/ocr_handler.py"
click node_audio "https://github.com/harshalwaghare18/ai-math-mentor/blob/main/utils/audio_handler.py"
click node_trace "https://github.com/harshalwaghare18/ai-math-mentor/blob/main/app.py"
click node_parser "https://github.com/harshalwaghare18/ai-math-mentor/blob/main/agents/parser_agent.py"
click node_router "https://github.com/harshalwaghare18/ai-math-mentor/blob/main/agents/router_agent.py"
click node_solver "https://github.com/harshalwaghare18/ai-math-mentor/blob/main/agents/solver_agent.py"
click node_verifier "https://github.com/harshalwaghare18/ai-math-mentor/blob/main/agents/verifier_agent.py"
click node_explainer "https://github.com/harshalwaghare18/ai-math-mentor/blob/main/agents/explainer_agent.py"
click node_kb "https://github.com/harshalwaghare18/ai-math-mentor/blob/main/rag/knowledge_base.py"
click node_docs "https://github.com/harshalwaghare18/ai-math-mentor/tree/main/rag/kb_docs"
click node_memory "https://github.com/harshalwaghare18/ai-math-mentor/blob/main/memory/memory_manager.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_app,node_image,node_audio,node_trace toneBlue
class node_parser,node_router,node_solver,node_verifier,node_explainer toneAmber
class node_kb,node_docs,node_memory toneMint
class node_groq,node_tesseract,node_openai toneRose
class node_user toneIndigo
```

## Components

### Input and presentation

- [Streamlit app](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/app.py): `app.py`
- [Image OCR](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/utils/ocr_handler.py): `utils/ocr_handler.py`
- [Audio transcription](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/utils/audio_handler.py): `utils/audio_handler.py`
- [Trace and feedback](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/app.py): `app.py`

### Solution pipeline

- [Problem parser](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/agents/parser_agent.py): `agents/parser_agent.py`
- [Intent router](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/agents/router_agent.py): `agents/router_agent.py`
- [Math solver](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/agents/solver_agent.py): `agents/solver_agent.py`
- [Solution verifier](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/agents/verifier_agent.py): `agents/verifier_agent.py`
- [Solution explainer](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/agents/explainer_agent.py): `agents/explainer_agent.py`

### Knowledge and memory

- [Math knowledge base](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/rag/knowledge_base.py): `rag/knowledge_base.py`
- [Math reference docs](https://github.com/harshalwaghare18/ai-math-mentor/tree/main/rag/kb_docs): `rag/kb_docs`
- [Attempt memory](https://github.com/harshalwaghare18/ai-math-mentor/blob/main/memory/memory_manager.py): `memory/memory_manager.py`

### External services

- **Groq LLM and Whisper**
- **Tesseract OCR**
- **OpenAI embeddings and LLM**

### Other components

- **Student**

## Connections

- Student → Streamlit app: submits problem (evidence: `README.md`)
- Streamlit app → Image OCR: extracts image text (evidence: `README.md`)
- Streamlit app → Audio transcription: transcribes audio (evidence: `README.md`)
- Streamlit app → Problem parser: passes input (evidence: `README.md`)
- Problem parser → Intent router: parsed problem (evidence: `README.md`)
- Intent router → Math solver: selects strategy (evidence: `README.md`)
- Math solver → Math knowledge base: retrieves context (evidence: `agents/solver_agent.py`)
- Math knowledge base → Math reference docs: indexes text (evidence: `rag/knowledge_base.py`)
- Math solver → Solution verifier: solution for review (evidence: `README.md`)
- Solution verifier → Solution explainer: verified solution (evidence: `README.md`)
- Solution explainer → Streamlit app: presents explanation (evidence: `README.md`)
- Streamlit app → Trace and feedback: renders trace (evidence: `app.py`)
- Streamlit app → Groq LLM and Whisper: requests completion (evidence: `app.py`)
- Streamlit app → Attempt memory: stores attempts
- Image OCR → Tesseract OCR: runs OCR (evidence: `utils/ocr_handler.py`)
- Audio transcription → OpenAI embeddings and LLM: requests transcription (evidence: `utils/audio_handler.py`)
- Math knowledge base → OpenAI embeddings and LLM: embeds documents (evidence: `rag/knowledge_base.py`)
