Physics AI Tutor

Physics AI Tutor is an AI-assisted learning platform for high school physics students.

I previously worked as a high school physics teacher in Japan for three years. Through teaching experience, I noticed that many students struggled not only with understanding physics concepts but also with formulating the right questions.

This project aims to help students learn physics by combining:

• Structured educational knowledge management
• Semantic search using vector embeddings
• Retrieval-Augmented Generation (RAG)
• Human review workflows for AI-generated content

The goal is to build a reliable AI tutor that explains physics based on verified educational knowledge.

---

Live Application

https://ai-tutor.pencil-net.com

---

Getting Started

To run the project locally, see docs/development.md.

Documentation

• docs/development.md: local setup, testing, environment variables
• docs/database.md: database schema and Alembic migrations
• docs/api.md: REST API reference
• docs/security.md: security model and practices
• AGENTS.md: conventions for contributors and coding agents

---

Screenshots

English UI mode, with question and answer content still in Japanese (see Features).

Home / question list

AI similarity search results

Question detail page

Login page for admin

Manage questions (Admin page)

Edit question (Admin page)

---

System Architecture

flowchart LR
    User[User Browser]

    Frontend[Next.js Frontend]

    Backend[FastAPI Backend]

    DB[(Supabase PostgreSQL)]

    Embedding[OpenAI Embedding API]

    LLM[DeepSeek API]


    User --> Frontend

    Frontend --> Backend

    Backend --> DB

    Backend --> Embedding

    Backend --> LLM

The backend acts as the central application layer, connecting the frontend, knowledge database, embedding service, and LLM generation service.

---

AI/RAG Architecture

The application is designed to minimize unnecessary LLM usage by prioritizing existing educational knowledge.

flowchart TB
    U[User Question]

    EXACT{Exact Match Search}

    EXIST[Reuse Existing QA]

    EMB[Generate Embedding]

    SEARCH[Vector Similarity Search]

    DB[(PostgreSQL + pgvector)]

    SIM{High Similarity QA?}

    CONTEXT[Build RAG Context]

    LLM[DeepSeek LLM Generation]

    ANSWER[AI Tutor Answer]

    SAVE[Store Generated QA - UNREVIEWED]

    REVIEW[Admin Review]

    NEXT[Suggest Next Questions - Concept-based Recommendation]


    U --> EXACT

    EXACT -->|Found| EXIST
    EXACT -->|Not Found| EMB

    EMB --> SEARCH
    SEARCH <--> DB

    SEARCH --> SIM

    SIM -->|Yes| EXIST
    SIM -->|No| CONTEXT

    CONTEXT --> LLM
    LLM --> ANSWER

    ANSWER --> SAVE
    SAVE --> DB

    DB --> REVIEW
    REVIEW --> DB

    EXIST --> NEXT
    ANSWER --> NEXT

Design Principles

• Prefer existing verified knowledge over generating new answers
• Reduce unnecessary LLM API calls
• Ground AI responses with retrieved educational content
• Improve knowledge quality through human review

---

Features

AI-assisted Physics Question Answering

• Search existing physics explanations using semantic similarity
• Retrieve relevant educational content before generation
• Generate AI answers using Retrieval-Augmented Generation (RAG)
• Store generated answers for future knowledge reuse

Semantic Question Search

• Generate embeddings for physics questions
• Store vectors using PostgreSQL + pgvector
• Search similar questions using cosine similarity
• Reuse existing knowledge before calling LLMs

Knowledge Management

• Admin dashboard for educational content management
• Review workflow for AI-generated answers
• Separate approved content from unreviewed AI outputs; only approved content is shown to students

Authentication and Authorization

• JWT-based authentication with HttpOnly cookies
• Role-based access control
• Admin-only management operations

Responsive Web Application

• Next.js-based frontend
• Responsive UI for desktop and mobile browsers
• Japanese / English UI switching support

---

Tech Stack

Backend

• Python
• FastAPI
• SQLAlchemy
• PostgreSQL
• pgvector
• Alembic
• pytest

Frontend

• Next.js (App Router)
• React
• TypeScript
• Tailwind CSS

Infrastructure

• Docker Compose
• Vercel
• Render
• Supabase PostgreSQL

AI

• OpenAI Embedding API (text-embedding-3-small)
• DeepSeek API for LLM generation

---

Project Structure

physics-ai-tutor
├── backend
│   ├── physics_ai_tutor     # FastAPI application
│   ├── tests                # Backend tests
│   ├── alembic              # Database migrations
│   └── pyproject.toml
│
├── frontend
│   ├── src                  # Next.js application
│   ├── public
│   └── package.json
│
├── docs
│   ├── development.md       # Development guide
│   ├── database.md          # Schema and migration guide
│   ├── api.md               # API reference
│   └── security.md          # Security guide
│
├── docker-compose.yml
├── AGENTS.md                # Project rules (CLAUDE.md links here)
├── README.md
└── LICENSE

---

Deployment

Production environment:

• Frontend: Vercel
• Backend: Render
• Database: Supabase PostgreSQL

---

Roadmap and Issues

Issues are tracked inside the repository with git-bug, so no external tracker is needed. The roadmap is the issue labelled epic:

git bug termui          # browse and edit issues
git bug bug -l epic     # the roadmap

See docs/development.md for the labels and workflow.

---

License

This project is licensed under the MIT License.