Mini-Muse research agent

# Mini-Muse — a research agent built on Meta Muse Spark

**Educational AI agent that shows undergraduates how an ordinary LLM app becomes an agent.**

Mini-Muse is a small chat app, in the style of ChatGPT or Claude, that uses Meta's **Muse Spark** model. It can:

- find real research papers,
- read your PDF,
- do safe calculations,
- write a cited research report, **but only after you click Approve.**

The whole project is ~1,600 lines of plain Python (no LangChain, no LangGraph, no vector database), so a student can read it end to end.

```
User Goal → Muse Spark → Decision → Tool Selection → Tool Execution → Observation
          → Next Decision … → Human Approval (enforced by code) → Final Result
```

This project is an educational prototype inspired by Meta Muse and is not an implementation or reproduction of Meta's proprietary Muse product.

![Mini-Muse asking for approval before writing the report](docs/images/approval.png)

📑 **Slides:** [`slides/Mini-Muse-Step-by-Step-Implementation.pptx`](slides/Mini-Muse-Step-by-Step-Implementation.pptx) is a 24-slide, step-by-step lecture on how this project was built, with speaker notes.

---

## Contents

1. [Quick start (5 minutes)](#1-quick-start-5-minutes)
2. [How to use it](#2-how-to-use-it)
3. [Connect the real Muse Spark (API key)](#3-connect-the-real-muse-spark-api-key)
4. [How it works](#4-how-it-works)
5. [Build it yourself, step by step](#5-build-it-yourself-step-by-step)
6. [Tests](#6-tests)
7. [Configuration](#7-configuration)
8. [Project structure](#8-project-structure)
9. [Safety, limitations and future work](#9-safety-limitations-and-future-work)

---

## 1. Quick start (5 minutes)

You need **Python 3.11 or newer** and **Git**. **No API key is needed to try it**: without a key the app runs in *mock mode* (see below).

**Windows (PowerShell):**
```powershell
git clone https://github.com/rajkumar898/muse-spark-research-agent.git
cd muse-spark-research-agent
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
streamlit run app.py
```

**macOS / Linux:**
```bash
git clone https://github.com/rajkumar898/muse-spark-research-agent.git
cd muse-spark-research-agent
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
streamlit run app.py
```

Open **http://localhost:8501** in your browser. Stop the app with **