📚 Learning Mate

Your smart learning companion, crafting courses and guiding your progress.

---

🧑‍💻 Why I Built It

Learners waste an enormous amount of time bouncing between videos, notes, apps, flashcards, and tools that don’t talk to each other. The result is a fragmented workflow where the learner must plan their own curriculum, track progress manually, and guess what to study next. Even highly motivated people lose momentum because the learning process itself is disorganized.

Learning Mate solves this by unifying the entire learning journey inside one adaptive system. It generates a personalized path from the learner’s goals, provides structured instruction, creates quizzes and visual explanations on demand, adjusts difficulty in real time, and measures understanding with transparent feedback. Instead of juggling disconnected tools, users get a continuous learning flow that feels guided, coherent, and intelligently sequenced.

The value is simple: Learning Mate turns scattered effort into steady progress. It removes the planning burden, closes the gaps between resources, and gives learners a clear sense of mastery. Users spend less time managing their learning and more time actually learning.

Note

Learning Mate currently uses the Gemini model, with planned support for additional AI providers.

---

Features

• Automated & Interactive Course Creation Generates full courses, including structured lessons, quizzes, illustrations, and exercises, through a teaching agent.

• Personalized Course Suggestions Recommends learning paths based on user goals, interests, and initial questions.

• Adaptive Learning Flow Guides learners step-by-step, evaluates answers, and adjusts difficulty accordingly.

• Built-in Assessment Engine Generates quizzes, checks responses, scores performance, and tracks mastery.

• Visual Explanations Produces illustrations to simplify and clarify concepts.

• Web-Powered Insights Integrates web search to ensure current and reliable information.

• Persistent Session Management Saves history, artifacts, and progress for consistent long-term use.

• Modular Multi-Agent Architecture Separates responsibilities across planning, generation, search, evaluation, and imagery agents.

---

🤖 System Architecture Flow

The Learning Mate system employs a Multi-Agent System (MAS) architecture, organized hierarchically to separate user interaction from learning management.

1. Core Orchestration Agents

The system uses two primary orchestration agents that manage the flow and delegation:

• smart_friend_agent (Sunny): The main user interface responsible for initial user interaction, personalization, and delegating complex instructional tasks to the teacher_agent.
• teacher_agent: The core learning manager responsible for structuring the lesson workflow, enforcing learning progression, and invoking specialized content tools.

2. Shared Utilities (Foundational Tools)

Both the smart_friend_agent and the teacher_agent have direct access to these foundational, non-pedagogical tools (Agents used as tool, function tool) for context, retrieval, and visuals:

Agent (Used as tool)	Role
web_search_agent	Retrieves up-to-date external information.
image_generation_agent	Visual Aid Creation (Generates images based on prompts).

Tool (function as tool)	Role
load_memory	Context Retrieval (Fetches user preferences and historical state).
LoadArtifactsTool	Content Retrieval (Loads previously saved images or files for reuse).

3. Exclusive utilities (Pedagogical Tools)

The teacher_agent performs pedagogical steps (planning, content delivery, and evaluation) by calling these specialized agents as tools:

Agent (Used as tool)	Role
course_planning_agent	Curriculum Structuring and Lesson Sequencing.
quiz_generation_agent	Assessment Creation and Question Generation.
answer_evaluation_agent	Response Grading, Scoring, and Feedback Generation.

The design ensures modularity and persistence by treating specialized capabilities as callable Agent Tools.

Diagram

---

📦 Installation

1. Clone the repository:

git clone https://github.com/speedyk-005/Learning-mate.git
cd Learning-mate

2. Install dependencies (Python 3.11+ required):

pip install "google-adk>=1.15.0"

3. Ensure npx is installed for MCP tools. Guide: https://gist.github.com/cwsmith-160/e9c8ca80f23027f0495775aed77ec780#file-node_npx_install-md

4. Make the helper script executable:

chmod +x start_agent.sh

---

🪛 Setup

API Keys

Learning Mate requires:

• Google API Key – for Gemini LLM Get yours: https://aistudio.google.com/app/api-keys

• Tavily API Key – for web search via MCP Get yours: https://app.tavily.com/home

You can set them in your .env file (modify and rename .env.example file to .env) or set them directly in your shell. For example:

export GOOGLE_API_KEY="your_google_key_here"
export TAVILY_API_KEY="your_tavily_key_here"

---

▶ Running Learning Mate

Use the helper script:

./start_agent.sh

This script:

• Creates directories for sessions and artifacts.

• Configures storage:

  • .data/sessions.sqlite — session history
  • .data/artifacts/ — generated images and files

• Starts the ADK web server.

• Opens the development UI at: http://127.0.0.1:8000/dev-ui/?app=learning_mate

Alternative Commands

CLI mode:

adk run src/learning_mate

Web mode (temporary storage):

adk web "src"

---

📸 Screenshots

CLI (Screenshot 0)

---

Web ui (Screenshot 1-4)

Click to see

---

🗃 Directory Structure

.
├── images
│   ├── diagram.png
│   ├── logo.png
│   ├── Screenshot_0.png
│   ├── Screenshot_1.png
│   ├── Screenshot_2.png
│   ├── Screenshot_3.png
│   └── Screenshot_4.png
├── LICENSE
├── README.md
├── src
│   └── learning_mate
│       ├── agent.py
│       ├── __init__.py
│       ├── __pycache__/
│       ├── sub_agents (Agents that are used as tools)
│       │   ├── answer_evaluation_agent.py
│       │   ├── course_planning_agent.py
│       │   ├── image_generation_agent.py
│       │   ├── quiz_generation_agent.py
│       │   └── web_search_agent.py
│       └── utils.py
├── .data/ (Created automatically the first time you run ./start_agent)
└── start_agent.sh

---

Summary of Speed for the Student

Feature	Traditional Platforms	AI-Automated Interactive
Pacing	Fixed (Often slower for fast learners)	Variable (Moves at your personal speed)
Feedback on Questions	Slow (Hours/Days)	Instant (Seconds)
Content Updates	Slow (Manual revision cycle)	Fast (AI pulls current info dynamically via web search)

---

📜 License

MIT License — see License.