README.md

metadata

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

├── 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:

# 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:

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:

   docker build -t socratic-tutor .
   

2. Run the container: Ensure you pass your environment variables (like your LLM API keys):

   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.