Transform textbooks into engaging, autonomous classroom experiences
Senku is an AI-powered autonomous teaching system that brings the best of classroom teaching to digital learning. Unlike traditional chatbots or Q&A systems, Senku actively teaches entire textbooks with natural speech, structured curriculum, and intelligent pacing—just like a real teacher.
Most AI learning tools (ChatGPT, Grok, etc.) are reactive—they wait for you to ask questions. This approach has fundamental limitations:
- ❌ No structured learning path - Students don't know what they don't know
- ❌ Passive engagement - Requires constant user input and motivation
- ❌ Fragmented knowledge - Learning happens in disconnected chunks
- ❌ No curriculum planning - Missing the big picture and learning progression
✅ Autonomous Teaching - Senku actively teaches you, not the other way around
✅ Structured Curriculum - Automatically extracts and follows a logical learning path
✅ Natural Classroom Experience - Engaging voice, pacing, and delivery like a real teacher
✅ Complete Coverage - Teaches entire textbooks systematically, nothing gets missed
✅ Intelligent Pacing - Pauses, emphasis, and rhythm designed for comprehension
✅ Offline-First - Works completely offline with local AI models and TTS
Think of it this way: Would you rather ask a book questions, or have an expert teacher guide you through it? Senku is the latter.
- Python 3.8 or higher
- Git
- 4GB+ RAM recommended
-
Clone the repository
git clone https://github.com/aswinms926/Tutor.git cd Tutor/senku -
Install dependencies
pip install -r requirements.txt
-
Set up environment variables
Create a
.envfile in thesenkufolder:# Required: Gemini API for curriculum extraction and lecture generation GEMINI_API_KEY=your_gemini_api_key_here # Optional: Inworld AI for premium TTS # If not provided or if API fails, system automatically uses offline Piper TTS INWORLD_API_KEY=your_inworld_api_key_here INWORLD_API_SECRET=your_inworld_api_secret_here
Get your API keys:
- Gemini API (Required): https://makersuite.google.com/app/apikey
- Inworld AI (Optional): https://studio.inworld.ai/
Note: Senku works completely offline for TTS! If Inworld API is unavailable or fails, the system automatically falls back to offline Piper TTS. Your teaching sessions will continue uninterrupted.
-
Run the application
python api_server.py
-
Open your browser
Navigate to: http://localhost:5000
- Drag and drop any PDF textbook into the upload zone
- Senku will process it and extract the curriculum automatically
- Supports textbooks of any size (tested with 500-700 page books)
- View the automatically extracted chapters and topics
- See the structured learning path Senku will follow
- Click "Start Autonomous Teaching"
- Sit back and learn as Senku teaches the entire curriculum
- Natural voice with intelligent pacing and emphasis
- Follow along with synchronized text highlighting
- Pause/Resume - Take breaks when needed
- Stop - End the session and upload a new textbook
senku/
├── api_server.py # Flask API server
├── senku.py # Main entry point
├── config.py # Configuration management
├── requirements.txt # Python dependencies
│
├── ingestion/ # PDF processing & curriculum extraction
│ ├── pdf_processor.py
│ └── curriculum_extractor.py
│
├── teaching/ # Autonomous teaching engine
│ ├── autonomous_teacher.py
│ ├── lecture_generator.py
│ └── tts_engine.py
│
├── vector_store/ # RAG system for context-aware teaching
│ └── chroma_store.py
│
├── web/ # Modern web interface
│ ├── index.html
│ ├── app.js
│ └── styles.css
│
└── data/ # Storage
├── audio_cache/ # Cached TTS audio
└── chroma_db/ # Vector database
Want to integrate Senku into your existing classroom dashboard or LMS?
See INTEGRATION.md for complete integration documentation, including:
- ✅ REST API reference
- ✅ React/JavaScript examples
- ✅ Python/Flask backend integration
- ✅ Complete working examples
- ✅ Security best practices
- ✅ Attendance tracking integration
Quick Start:
// Start teaching session from your dashboard
const response = await fetch('http://localhost:5000/api/teach', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ pdf_hash: 'your_pdf_hash', voice_enabled: true })
});- Teaches entire textbooks without user intervention
- Follows extracted curriculum systematically
- Natural classroom-like delivery
- Automatically identifies chapters, sections, and topics
- Creates a structured learning path
- Adapts to different textbook formats
- Natural speech with pauses and emphasis
- Offline TTS fallback for privacy
- Audio caching for instant replay
- Lectures cached for instant access
- Audio cached to save processing time
- Resume teaching from where you left off
- Clean, intuitive design
- Real-time progress tracking
- Responsive on all devices
- Backend: Python, Flask
- AI/ML: Google Gemini, ChromaDB, Sentence Transformers
- TTS: Inworld AI (with offline fallback)
- Frontend: Vanilla JavaScript, HTML5, CSS3
- Storage: Local file system, SQLite
Edit config.py to customize:
- API endpoints and ports
- Model selection (Gemini, OpenAI, etc.)
- TTS settings
- Cache behavior
- Teaching parameters
This is a team project. To contribute:
-
Create a feature branch
git checkout -b feature/your-feature-name
-
Make your changes and commit
git add . git commit -m "Description of changes"
-
Push to the repository
git push origin feature/your-feature-name
-
Create a pull request for review
- Check if port 5000 is already in use
- Verify all dependencies are installed:
pip install -r requirements.txt
- Ensure pygame is installed
- Check system audio settings
- Verify TTS API keys in
.envfile
- Ensure the PDF is not password-protected
- Check available disk space for vector database
- Try with a smaller PDF first
- Verify Gemini API key is valid
- Check internet connection
- Ensure the PDF has clear chapter/section structure
[Add your license here]
[Add team member names and roles]
Built with passion for transforming education through AI.
Remember: Senku doesn't just answer questions—it teaches. That's the difference between a tool and a teacher.