eSanju - AI Learning Companion 🎓

An intelligent, personalized tutoring system powered by AI agents that delivers customized educational experiences tailored to individual student needs.

Overview

eSanju is a comprehensive AI-driven tutoring platform built with CrewAI and Streamlit that creates personalized learning experiences. The system uses intelligent agents to research content, create learning plans, prepare materials, and deliver engaging lessons adapted to each student's learning style and objectives.

Features

• Personalized Learning Paths: Custom-tailored education based on student profile, learning style, and objectives
• Multi-Subject Support: Mathematics, Portuguese, English, Science, History, and Programming
• Adaptive Difficulty Levels: Content adjusts based on student comprehension and engagement
• Multiple Learning Styles: Visual, Auditory, Reading/Writing, and Kinesthetic learning support
• Progress Tracking: Real-time monitoring of student achievements and understanding levels
• Interactive Tutoring: Follow-up questions, assessments, and immediate feedback
• Multi-Language Support: English, Portuguese, and French instruction
• Curriculum Alignment: Content aligned with Portugal, UK, and Angola education curricula

Project Structure

.
├── tutor.py                 # Main Streamlit application
├── src/
│   ├── tutoring_agents.py   # AI agent definitions
│   ├── tutoring_tasks.py    # Task definitions for the tutoring crew
│   └── tutoring_crew.py     # Crew orchestration
├── tools/
│   ├── browser_tools.py     # Web scraping and content extraction
│   ├── calculator_tools.py  # Mathematical calculation utilities
│   ├── email_tool.py        # Email draft creation
│   └── image_tools.py       # Visual aid generation
├── data/
│   ├── learning_plan_*.md   # Generated learning plans
│   ├── lesson_*.md          # Delivered lessons
│   ├── learning_research_*.md # Research findings
│   └── lesson_materials_*.md # Prepared lesson materials
└── logs/
    └── tutoring_crew_logs_*.txt # Execution logs

Key Components

Agents

1. Senior Tutor: Expert educator responsible for lesson delivery and feedback
2. Tutor Assistant: Support professional handling materials, progress monitoring, and practice explanations

Workflow

The tutoring system follows this workflow:

1. Assessment: Evaluate student's current knowledge and learning needs
2. Research: Gather information about the subject and learning objectives
3. Planning: Create a comprehensive, structured learning plan
4. Materials: Prepare engaging lesson materials and resources
5. Delivery: Deliver interactive, personalized lessons
6. Progress Tracking: Monitor student advancement
7. Feedback: Provide comprehensive feedback and recommendations

Installation

Prerequisites

• Python 3.8+
• Ollama (for local LLM)
• Streamlit
• CrewAI and dependencies

Setup

1. Clone the repository:

git clone <repository-url>
cd tutor

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Set up environment variables in .env:

LANGTRACE_KEY=your_key_here
BROWSERLESS_API_KEY=your_key_here
SERPER_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here

5. Start Ollama:

ollama serve

6. Pull the required models:

ollama pull gemma2-9b-32k
ollama pull granite-embedding:278m

Usage

Running the Application

streamlit run tutor.py

The application will open in your browser at http://localhost:8501

Using the Interface

1. Start Learning Tab 📚

   • Enter your name and basic information
   • Select your grade level and preferred language
   • Choose your subject and learning objectives
   • Select your learning style preferences
   • Set session duration and time preference

2. Learning Tips Tab 💡

   • Access study strategies and techniques
   • Review active learning methods
   • Access learning resources and PDFs

3. Progress Tracker Tab 📊

   • View your learning journey statistics
   • Monitor understanding level progression
   • Interact with your AI tutor
   • Ask follow-up questions

Technology Stack

• Frontend: Streamlit
• AI Framework: CrewAI with Claude Haiku 4.5
• LLM: Ollama (local) with Gemma2 9B
• Embeddings: Granite Embedding Model
• Backend: Python
• Graph Processing: LangGraph
• Tools: LangChain, SerperDev, Web Scraping

Supported Subjects & Topics

Mathematics

• Algebra
• Numbers and Operations
• Geometry
• Calculus
• Statistics
• Approximations
• Polynomial Decomposition

Languages

• Portuguese (Grammar, Literature, Writing, Vocabulary)
• English (Grammar, Literature, Writing, Vocabulary)

Sciences

• Biology
• Chemistry
• Physics
• Environmental Science

Humanities

• World History
• US History
• European History
• Ancient Civilizations

Technology

• Python
• Java
• Web Development
• Data Science

Configuration

Learning Objectives

Students define SMART learning objectives:

• Specific: Clear and well-defined
• Measurable: Quantifiable outcomes
• Achievable: Realistic goals
• Relevant: Connected to student needs
• Time-bound: Specific timeframes

Curriculum Support

• 🇵🇹 Portugal Education Curriculum
• 🇬🇧 United Kingdom Curriculum
• 🇦🇴 Angola Education Curriculum

Output Files

The system generates several output files during operation:

• data/learning_plan_TIMESTAMP.md - Comprehensive learning plan
• data/learning_research_TIMESTAMP.md - Research findings
• data/lesson_materials_TIMESTAMP.md - Prepared materials
• data/lesson_TIMESTAMP.md - Delivered lesson content
• logs/tutoring_crew_logs_TIMESTAMP.txt - Detailed execution logs

Evaluation & Testing

For evaluating AI agent responses and model performance, the system includes:

• Student response evaluation functions
• Understanding level tracking
• Progress metrics monitoring
• Follow-up question generation
• Difficulty analysis

Best Practices

When using eSanju:

1. Set Clear Goals: Define specific, measurable learning objectives
2. Choose Your Style: Select learning methods that work best for you
3. Stay Consistent: Regular practice leads to better results
4. Track Progress: Monitor improvements and celebrate wins
5. Ask Questions: Actively engage with the tutor
6. Practice Regularly: Use spaced repetition and active recall

Troubleshooting

Ollama Connection Issues

• Ensure Ollama is running: ollama serve
• Check the connection URL: http://localhost:11434
• Verify models are downloaded: ollama list

Model Issues

• Pull required models: ollama pull gemma2-9b-32k
• Ensure sufficient disk space and RAM

API Key Issues

• Verify all keys in .env file
• Check API quotas and limits
• Ensure keys have proper permissions

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request with clear descriptions

License

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

Support

For issues, questions, or suggestions, please open an issue on the repository or contact the development team.

Acknowledgments

• Built with CrewAI
• Powered by Ollama
• Frontend by Streamlit
• Language models from Meta and Google

Roadmap

• Advanced analytics dashboard
• Parent/Teacher portal for monitoring
• Peer collaboration features
• Gamification elements
• Mobile application
• Advanced assessment tools
• Integration with learning management systems
• Voice-based interaction
• Adaptive learning algorithms

---

Version: 1.0.0
Last Updated: December 2024
Status: Active Development