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.

📑 Slides: 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)
2. How to use it
3. Connect the real Muse Spark (API key)
4. How it works
5. Build it yourself, step by step
6. Tests
7. Configuration
8. Project structure
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):

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:

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 **