README.md

---
title: SocraticAI
emoji: 🎓
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# SocraticAI Tutor 🎓

SocraticAI is an AI-powered personalized tutoring system designed to guide students using the Socratic method. Instead of providing answers directly, the AI agent prompts students with guided hints and questions to help them arrive at the correct answers themselves.

The project is built with a **React + Vite** frontend and a **FastAPI + LangGraph** backend, fully containerized and ready to deploy on **Hugging Face Spaces** or any Docker-compatible hosting environment.

---

## 🚀 Key Features

*   **Socratic Dialogue Engine**: Implemented using LangGraph to evaluate student understanding, generate contextual hints, and guide the student constructively.
*   **Adaptive Hint System**: Tracks the student's progress and adjusts the hint level dynamically.
*   **Interactive Curriculum Selection**: Simple UI for selecting subjects, grades, and specific topics.
*   **Dynamic Knowledge Base (RAG)**: Ingests educational PDFs and documents into a vector store (Chroma DB) to ground the tutor's domain knowledge.
*   **Admin Panel**: Allows teachers or administrators to upload new curriculum PDFs and trigger knowledge ingestion instantly.

---

## 🛠️ Tech Stack

*   **Frontend**: React, Vite, React Markdown, Lucide Icons, Vanilla CSS
*   **Backend**: FastAPI, Uvicorn, LangChain / LangGraph (for agent orchestration)
*   **Vector Database**: Chroma DB
*   **Deployment**: Docker (Multi-stage build)

---

## 📁 Repository Structure

```text
├── frontend/                 # React frontend application
│   ├── src/                  # React components & application logic
│   ├── package.json          # Frontend dependencies and Vite configuration
│   └── dist/                 # Compiled static assets (generated on build)
├── data/                     # Source curriculum documents (organized by Grade/Subject)
├── chroma_db/                # Local database folder for vector storage
├── server.py                 # FastAPI application & entrypoint
├── socratic_graph.py         # Socratic Agent logic orchestrated with LangGraph
├── ingest.py                 # Document parsing and vector database ingestion pipeline
├── requirements.txt          # Python dependencies
├── Dockerfile                # Multi-stage production container configuration
└── README.md                 # Project documentation
```

---

## 💻 Running the Project Locally

To run both React and FastAPI concurrently during development, open **two separate terminal instances**:

### Terminal 1: FastAPI Backend
Start the backend server from the project's root directory:
```bash
# Install python requirements
pip install -r requirements.txt

# Run the FastAPI server with hot-reload enabled
uvicorn server:app --reload --port 8000
```
*The API will run at `http://localhost:8000`.*

### Terminal 2: React Frontend
Start the frontend development server from the `frontend/` subdirectory:
```bash
cd frontend

# Install Node dependencies
npm install

# Start the Vite development server
npm run dev
```
*The frontend will run at `http://localhost:5173` and proxy API calls to the backend on port 8000.*

---

## 🐳 Running Locally with Docker

You can test the exact production setup locally using Docker:

1. **Build the container**:
   ```bash
   docker build -t socratic-tutor .
   ```

2. **Run the container**:
   Ensure you pass your environment variables (like your LLM API keys):
   ```bash
   docker run -p 7860:7860 --env-file .env socratic-tutor
   ```
   *Access the fully combined application at `http://localhost:7860`.*

---

## 🌐 Deploying to Hugging Face Spaces

This repository is pre-configured to deploy directly to Hugging Face Spaces as a Docker Space:

1. Create a new Space on Hugging Face.
2. Choose **Docker** as the SDK.
3. Push your repository to Hugging Face.
4. Set your **Secrets & Variables** under the Space's Settings:
    *   `GOOGLE_API_KEY`: Your Gemini API key for the agent's LLM core.