# Adaptive AI Fundamentals Tutor

A text-based Google ADK tutor for beginner learners aged 10-18. It adapts explanations and examples to the learner's age band, interests, prior knowledge, and goal.

## Setup

1. Create and activate a Python 3.11+ virtual environment.
2. Install dependencies from `requirements.txt`.
3. Copy `.env.example` to `.env` and set `DEEPSEEK_API_KEY`.
4. Run the agent with the Google ADK web interface from the project directory.

The API key must stay in `.env` or the process environment. Do not commit `.env`.

## Current scope

The tutor is one `LlmAgent` with:

- ADK function tools for learner profiles, current lesson, quiz results, and progress
- A local read-only curriculum MCP server for approved lessons, activities, and quizzes
- DeepSeek through LiteLLM

The curriculum server is started automatically by ADK through stdio. Its tools are:

- `get_lesson`
- `get_activity`
- `get_quiz`

The package is deliberately organized so specialist lesson, quiz, activity, and safety agents can be added later.

The tutor should not collect identifying information from learners. Use an age band instead of an exact age.

## MCP smoke test

Run this from the project root after installing dependencies:

```powershell
.\.venv\Scripts\python.exe tests\test_curriculum_mcp.py
```

Expected output includes:

```text
mcp-discovery-ok ['get_activity', 'get_lesson', 'get_quiz']
```
## Architecture and future work

The current tutor is a prompt-driven `LlmAgent`. The LLM guides the conversation and decides when to call the available ADK function tools and curriculum MCP tools. It does not currently use a predefined multi-agent or graph-based workflow.

The project is kept modular so the workflow can evolve. Future versions may explore ADK workflow agents for sequential, parallel, or iterative tasks, along with multi-agent collaboration or custom routing for more complex tutoring scenarios. These are potential enhancements, not part of the current implementation.