Where your notes finally click.
Seshio is an AI-powered learning platform that helps you make sense of what you're learning through grounded, retrieval-augmented conversations and active study practice.
Upload your materials, ask questions, and build understanding. Notes, summaries, quizzes, and study sessions emerge naturally from the process.
- ✨ Features
- 📌 Project Status
- 🚀 Quick Start
- 🧱 Tech Stack
- 📚 Documentation
- 💻 Development
- 🧠 Philosophy
- 🔬 Research & ML
- 👥 Who This Is For
- 🤝 Contributing
- ⚖️ License
- 🛟 Support
- 📚 Grounded Conversations - Ask questions with AI responses grounded in your uploaded materials
- 📁 Material Management - Upload and organize PDFs, text files, and documents in notebooks
- 🎯 Study Mode - Practice with AI-generated quizzes based on your materials
- ✍️ Content Generation - Generate summaries, outlines, and flashcards from your materials
- 🔒 Privacy-First - Your data is encrypted and never shared with third parties
- 🔬 ML Experimentation - Built-in framework for testing retrieval and learning strategies
Current Phase: Phase 3 Complete - Material Upload and Processing ✅
Completed Phases:
- ✅ Phase 1: Foundation and Infrastructure (Auth, Database, Onboarding)
- ✅ Phase 2: Notebook Management (CRUD, Context View, Search)
- ✅ Phase 3: Material Upload and Processing (File Upload, Text Extraction, Chunking, Embeddings)
Next Up: Phase 4 - Retrieval and Question Answering (Hybrid Search, RAG, Chat UI)
What's Working Now:
- User authentication and onboarding with archetype selection
- Create, manage, and organize notebooks
- Upload learning materials (PDF, DOCX, TXT, MD) with drag-and-drop
- Automatic text extraction and chunking (500-1000 tokens)
- Embedding generation via Gemini API (768-dim vectors)
- Background processing with Celery and status tracking
- 15 backend tests passing (100% success rate)
Progress Tracking:
- 📋 CHANGELOG.md - Completed tasks and version history
- 📝 tasks.md - Full implementation roadmap
- 🗺️ roadmap.md - High-level milestones
- Node.js 20+ and npm
- Python 3.11+ (Conda recommended)
- Docker and Docker Compose
- Supabase Account (for authentication and storage)
- Google AI Studio Account (for Gemini API key)
# 1. Clone and setup
git clone https://github.com/sakialabs/seshio
cd seshio
# 2. Create conda environment
conda create -n seshio python=3.11 -y
conda activate seshio
# 3. Install dependencies
cd backend && pip install -r requirements.txt && cd ..
cd frontend && npm install && cd ..
# 4. Configure environment variables
cp backend/.env.example backend/.env
cp frontend/.env.local.example frontend/.env.local
# Edit both files with your Supabase and Gemini credentials
# 5. Start services
docker-compose up -d postgres redis
# 6. Run migrations
cd backend && alembic upgrade head && cd ..
# 7. Start development servers
# Terminal 1: Backend
cd backend && uvicorn app.main:app --reload
# Terminal 2: Frontend
cd frontend && npm run devAccess the app:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/docs
For detailed setup instructions, see docs/setup.md.
Frontend: Next.js 15, TypeScript, Tailwind CSS, shadcn/ui, Supabase Client
Backend: FastAPI, PostgreSQL + pgvector, SQLAlchemy, Alembic, Celery, Redis, Supabase, Gemini AI
Infrastructure: Docker, Docker Compose, Conda
- Setup Guide - Detailed installation and configuration
- Testing Guide - Running tests and writing new ones
- Contributing Guide - How to contribute to Seshio
- Vision & Mission - What Seshio is and why it exists
- Design Document - System architecture and technical decisions
- Requirements - Functional and non-functional requirements
- Tasks - Implementation plan and progress
- Roadmap - High-level development timeline
- Changelog - Version history and completed work
# Start all services with Docker
docker-compose --profile full up -d
# Start only database services
docker-compose up -d postgres redis
# View logs
docker-compose logs -f
# Run tests
cd backend && pytest --cov
cd frontend && npm test
# Format code
cd backend && black . && ruff check .
cd frontend && npm run format && npm run lint
# Database migrations
cd backend && alembic upgrade headseshio/
├── frontend/ # Next.js frontend
│ ├── src/app/ # App router pages
│ ├── src/components/ # React components
│ └── src/lib/ # Utilities and API clients
├── backend/ # FastAPI backend
│ ├── app/api/ # API routes
│ ├── app/models/ # Database models
│ ├── app/services/ # Business logic
│ └── tests/ # Test suite
├── docs/ # Documentation
└── docker-compose.yml # Docker configuration
Seshio is built on these core principles:
- Clarity over complexity - If it's confusing, it's wrong
- Grounded by default - Answers come from your materials, not guesses
- Support, not pressure - No guilt, no hustle culture, just help when needed
- Small sessions win - Progress compounds through consistency, not intensity
- Human-first intelligence - AI assists learning, never replaces the learner
Read more in docs/vision.md.
Seshio is designed as both a learning platform and an applied ML research project. We explore:
- Retrieval-augmented generation (RAG)
- Hybrid retrieval (semantic + lexical)
- Study quality evaluation
- Adaptive quiz generation
- Feedback-driven model improvement
All experiments focus on measurable improvements to understanding and recall, not metrics alone.
Learn more in the Research & Experiments section.
- Students who want to understand, not just cram
- Learners managing complex material
- Builders exploring applied ML in education
- Anyone interested in retrieval, evaluation, and learning systems
We welcome contributions! Here's how to get started:
- Read the Contributing Guide
- Check the issue tracker for tasks
- Look for issues labeled
good first issueorhelp wanted - Fork the repo, make changes, and submit a PR
Before submitting:
- Run tests:
pytest(backend) andnpm test(frontend) - Format code:
black .(backend) andnpm run format(frontend) - Follow Conventional Commits
MIT License - see LICENSE for details.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: docs/
Built with 💖 for learners everywhere.