# Local AI Stack — Mac Edition

A complete local AI tutor running on your Mac. No Docker, no cloud, no
internet needed after setup. Four pieces, in order of how deeply they
"teach" the model:

1. **System prompt** (Modelfile) — instructions baked into the model's
   identity.
2. **LlamaIndex on your notes** — the model can look up your own files.
3. **LlamaIndex on Karpathy's blog** — same trick, bigger library.
4. **Hermes agent** — the model can use tools (calculator, files, dates).

## Quick start

```bash
chmod +x setup_mac.sh
./setup_mac.sh
```

That installs Homebrew, Ollama, three models, Python deps, builds the
`kru-ai` custom model, clones Karpathy's blog, and creates a starter
`notes/` folder. Total time: 5–15 minutes depending on your internet.

## Files in this folder

| File | What it is |
| --- | --- |
| `Modelfile` | The "in the bones" system prompt for `kru-ai` |
| `requirements.txt` | Python packages: `llama-index` + Ollama plug-ins |
| `tutor.py` | RAG over your own `notes/` folder |
| `karpathy_tutor.py` | RAG over `karpathy_blog/_posts/`, with saved index |
| `agent.py` | Hermes 3 + four tools (multiply, divide, dates, read-notes) |
| `setup_mac.sh` | Installs everything in one go |

## Try it

```bash
# 1. Talk to the system-prompt-baked tutor
ollama run kru-ai

# 2. Ask questions about your own notes
source .venv/bin/activate
python tutor.py

# 3. Ask questions about Karpathy's writing
python karpathy_tutor.py

# 4. Watch an agent decide which tool to use
python agent.py
```

## When things go wrong

- **"command not found: ollama"** — open the Ollama app from your
  Applications folder once. It needs to be running.
- **First Karpathy index takes forever** — that's normal, ~3–5 minutes.
  The second run is instant because the index is saved to disk. If you
  ever want to re-index, delete the `karpathy_index/` folder.
- **`pip install` fails on lxml or similar** — `xcode-select --install`.
- **Apple Silicon vs Intel** — Ollama supports both. Intel Macs run the
  models on CPU and will be much slower. Try smaller models like
  `llama3.2:1b` if responses crawl.

## What each piece teaches you

- **Modelfile** teaches *identity and tone*. Cheap, instant, but the
  model still doesn't *know* anything new.
- **LlamaIndex** teaches *retrieval* — the model never memorises your
  notes, it looks them up at question-time. That's why it can cite
  exactly which file the answer came from.
- **Karpathy corpus** is the same trick at scale — proves RAG works on
  any folder of markdown.
- **Hermes agent** teaches *action*. The model can now affect the
  world (read files, do math) instead of only producing text.