# EduSmart AI Tutor

An AI-powered personalized learning platform exposed through a **Model Context Protocol (MCP)
server**, so an MCP-compatible AI client (Claude, ChatGPT Apps SDK, or any MCP host) can tutor a
student through a real learning-workflow platform — knowledge retrieval, assessment, mastery
tracking, and personalized recommendations — not a generic chatbot with a system prompt.

```
Student → AI Tutor → Knowledge → Assessment → Mastery → Next Action → Demonstrated Competence
```

## What this is

- A **relational learner model** (PostgreSQL/SQLite): students, courses, a skill prerequisite
  graph, mastery, attempts, assessments, projects, and an append-only learning history.
- A **real RAG pipeline**: document ingestion → chunking → embeddings → a FAISS vector index →
  a retriever that joins back to source metadata for attribution.
- A **deterministic-first learning engine**: mastery calculation, prerequisite resolution, and
  the `get_next_learning_action` recommendation are pure functions — no LLM call decides them.
- An **LLM provider abstraction** (stub / OpenAI / Anthropic) used only where language
  generation genuinely helps: explaining a concept, generating novel questions, and grading
  free-text conceptual answers.
- A **LangGraph tutor workflow** that routes a request through explicit nodes (classify intent →
  load student state → teach/practice/assessment/project → update learning state → recommend
  next step) instead of an unconstrained agent loop.
- A **17-tool MCP server** (`app/mcp/server.py`) plus an equivalent REST API (`app/main.py`),
  both thin adapters over the same authorization-enforcing service layer.

## Status

**59 automated tests, all passing**, across unit, integration, MCP, RAG, and evaluation suites —
run `python -m pytest tests/ -q` to verify. See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for a
phase-by-phase IMPLEMENTED/TESTED/PARTIALLY-IMPLEMENTED breakdown (Docker was written but not
executed in this build environment; everything else has been run for real, not just written).

## Quick start

```bash
python -m venv .venv && source .venv/Scripts/activate   # or .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
python -m alembic upgrade head
python scripts/seed_data.py
python scripts/ingest_documents.py
uvicorn app.main:app --reload &            # REST API on :8000
python scripts/run_mcp_server.py &         # MCP server on :8765
python -m pytest tests/ -q                 # 59 passed
```

Full setup, every command explained, and known pitfalls: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

## Documentation

| Doc | Covers |
|---|---|
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System diagram, layering, deterministic-vs-LLM decisions, technology inventory |
| [MCP.md](docs/MCP.md) | The 17 MCP tools, authentication approach, security boundaries, ChatGPT integration readiness |
| [RAG.md](docs/RAG.md) | Ingestion → chunking → embeddings → FAISS → retrieval, and why each part is swappable |
| [DATABASE.md](docs/DATABASE.md) | Schema (24 tables), ER diagram, PostgreSQL/SQLite portability |
| [SECURITY.md](docs/SECURITY.md) | Authn/authz model, prompt-injection defenses, what's out of scope |
| [EVALUATION.md](docs/EVALUATION.md) | Real measured retrieval/grading/mastery-model results |
| [DEPLOYMENT.md](docs/DEPLOYMENT.md) | Docker Compose, configuration, production gaps |
| [API.md](docs/API.md) | REST endpoint reference |
| [DEVELOPMENT.md](docs/DEVELOPMENT.md) | Full local setup, test suite layout, phase-by-phase status |

## License

MIT — see [LICENSE](LICENSE).