Built for the Krio Hackathon

An intelligent study companion that transforms your documents into interactive quizzes and flashcards using AI. Features a multi-agent architecture, spaced repetition learning, handwriting recognition, semantic document chunking with RAG, and comprehensive learning analytics.

• Features
• Architecture
• Tech Stack
• Getting Started
• Environment Variables
• API Reference
• AI Agent System
• Project Structure
• Contributing
• License

• Multi-format Upload: PDF, DOCX, TXT, Markdown, and images
• Semantic Chunking: AI-powered topic detection and boundary refinement using MC-Indexing/SCAN algorithms
• RAG Pipeline: Vector embeddings with pgvector for similarity search
• Concept Mapping: Automatic knowledge graph generation from documents

• Smart Question Generation: Multiple choice, true/false, written answer, fill-in-the-blank
• Style Learning: Analyzes sample questions to match your preferred format
• Flashcard Creation: Auto-generates study cards from document content
• Difficulty Levels: Easy, medium, and hard questions with proper distribution

• Interactive Quizzes: Practice, timed, and exam modes with configurable settings
• Flashcard Study: Flip cards with SM-2 spaced repetition scheduling
• Question Bank: Browse, filter, edit, and rate questions
• Notebook: Track wrong answers for targeted review

• Handwriting Recognition: Upload handwritten answers via GPT-4o Vision
• Partial Credit Grading: AI-assisted grading with detailed feedback breakdown
• Explanation Chat: Multi-turn conversations to understand concepts
• Exam Integrity: Focus/tab-switch detection for proctored assessments
• Chapter Organization: AI-powered document grouping and study guide generation

• Learning Score: AI-calculated score based on accuracy, consistency, improvement, and difficulty mastery
• Performance Charts: Interactive visualizations with ECharts
• Category Breakdown: Track progress across subjects
• Hardest Questions: Identify and focus on challenging topics
• PDF Export: Download analytics reports

• Google OAuth: Secure authentication
• Dark Mode: Eye-friendly theme
• Guided Tours: Interactive walkthroughs for new users
• Responsive Design: Works on desktop and mobile
• User Isolation: Each user sees only their own data

                    ┌─────────────────────┐
                    │  Controller Agent   │
                    │   (Orchestrator)    │
                    └──────────┬──────────┘
                               │
       ┌───────────┬───────────┼───────────┬───────────┐
       │           │           │           │           │
       ▼           ▼           ▼           ▼           ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Analysis │ │Generation│ │ Grading  │ │Handwriting│ │Explanation│
│  Agent   │ │  Agent   │ │  Agent   │ │  Agent   │ │  Agent   │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
     │              │           │           │            │
     │              │           │           │            │
     ▼              ▼           ▼           ▼            ▼
  Extracts      Creates     Grades      Recognizes    Provides
  Patterns    Questions    Answers     Handwriting  Explanations

1. Document Upload → Text extraction (PDF, DOCX, etc.)
2. Semantic Chunking → AI topic detection with 1000-token chunks
3. Embedding Generation → Vector storage in pgvector
4. Style Analysis → Extract patterns from sample questions
5. Content Generation → Questions/flashcards matching your style
6. Storage → Persist to PostgreSQL with full metadata

• Easiness Factor (EF): Starts at 2.5, adjusted based on recall quality
• Interval Growth: 1 day → 6 days → interval × EF (exponential)
• Quality Rating: 0-5 scale (0-2 = forgot, 3-5 = remembered)
• Smart Scheduling: Cards appear when optimal for retention

• Python 3.11+
• Node.js 18+
• PostgreSQL 15+ with pgvector extension
• Docker (optional)

# Clone the repository
git clone https://github.com/yourusername/studyforge.git
cd studyforge/quiz-flashcard-app

# Create environment file
cp .env.example .env
# Edit .env with your API keys

# Start all services
docker-compose up -d

# Access the application
# Frontend: http://localhost:3000
# Backend:  http://localhost:8000
# API Docs: http://localhost:8000/docs

cd quiz-flashcard-app/backend-python

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run migrations
alembic upgrade head

# Start server
uvicorn main:app --reload --port 8000

cd quiz-flashcard-app/frontend

# Install dependencies
npm install

# Start dev server
npm run dev

# Database
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/studyforge

# Environment
ENVIRONMENT=development  # or production
DEBUG=true

# AI Provider (choose one)
AI_PROVIDER=moonshot  # moonshot, openai, anthropic, groq, bedrock
AI_MODEL=kimi-k2-0711-preview

# Provider API Keys
MOONSHOT_API_KEY=your-key
OPENAI_API_KEY=your-key
ANTHROPIC_API_KEY=your-key

# Vision (for handwriting recognition)
VISION_PROVIDER=openai
VISION_MODEL=gpt-4o

# Embeddings
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-ada-002

# Authentication
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
JWT_SECRET_KEY=your-secret-key

# Monitoring
SENTRY_DSN=your-sentry-dsn

VITE_API_BASE_URL=http://localhost:8000
VITE_GOOGLE_CLIENT_ID=your-client-id

Agents communicate via the AgentMessage model stored in the database:

• Full audit trail of agent interactions
• Role, content, metadata, and timestamps
• Supports multi-turn conversations
• Accessible via /api/categories/{id}/agent-activity

quiz-flashcard-app/
├── backend-python/
│   ├── agents/               # AI agent implementations
│   │   ├── base_agent.py     # Abstract base class
│   │   ├── analysis_agent.py # Pattern extraction
│   │   ├── generation_agent.py # Q/A creation
│   │   ├── grading_agent.py  # Answer evaluation
│   │   ├── handwriting_agent.py # OCR
│   │   ├── explanation_agent.py # Help system
│   │   ├── chapter_agent.py  # Document organization
│   │   └── controller_agent.py # Orchestrator
│   ├── alembic/              # Database migrations
│   ├── config/               # Settings and configuration
│   ├── models/               # SQLAlchemy models
│   │   ├── user.py
│   │   ├── category.py
│   │   ├── document.py
│   │   ├── question.py
│   │   ├── flashcard.py
│   │   ├── quiz_session.py
│   │   ├── document_chunk.py # RAG chunks
│   │   └── ...
│   ├── routers/              # API endpoints
│   │   ├── auth.py
│   │   ├── categories.py
│   │   ├── documents.py
│   │   ├── quiz.py
│   │   ├── flashcards.py
│   │   ├── ai.py
│   │   ├── analytics.py
│   │   └── notebook.py
│   ├── schemas/              # Pydantic schemas
│   ├── services/             # Business logic
│   │   ├── ai_service.py     # LLM integration
│   │   ├── embedding_service.py # Vector embeddings
│   │   ├── chunking_service.py # Semantic chunking
│   │   ├── analytics_service.py # Learning score
│   │   └── ...
│   ├── main.py               # FastAPI app
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── components/       # Reusable UI
│   │   │   ├── Layout.tsx
│   │   │   ├── ExplanationChat.tsx
│   │   │   └── ...
│   │   ├── contexts/         # React contexts
│   │   │   ├── AuthContext.tsx
│   │   │   ├── ThemeContext.tsx
│   │   │   └── ...
│   │   ├── pages/            # Page components
│   │   │   ├── Home.tsx
│   │   │   ├── QuizSession.tsx
│   │   │   ├── FlashcardsPage.tsx
│   │   │   ├── AnalyticsDashboard.tsx
│   │   │   └── ...
│   │   ├── services/         # API client
│   │   │   └── api.ts
│   │   └── types/            # TypeScript types
│   ├── index.html
│   └── package.json
├── dev/                      # Development docs
├── docker-compose.yml
└── README.md

• User - Google OAuth profile
• Category - Study subjects with color/icon
• Document - Uploaded study materials
• Question - Quiz questions (all types)
• Flashcard - Study cards
• QuizSession - Quiz attempts
• FlashcardProgress - SM-2 scheduling data

• AIAnalysisResult - Style patterns
• PartialCreditGrade - Grading breakdown
• Handwriting - OCR results
• AgentMessage - Agent communication logs

• DocumentChunk - Semantic chunks with embeddings
• DocumentTopic - Detected topics
• DocumentConceptMap - Knowledge graph

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run tests: pytest (backend) / npm test (frontend)
5. Commit: git commit -m 'Add my feature'
6. Push: git push origin feature/my-feature
7. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• SuperMemo 2 Algorithm for spaced repetition
• MC-Indexing / SCAN for semantic chunking research
• OpenAI for AI models
• Anthropic for Claude models
• Built with Claude Code assistance