# MasterMind

AI-driven project planning. MasterMind feeds a project proposal and a structured
question set through a local LLM (Ollama) in fixed execution phases, producing a
written plan plus per-phase summaries you can review before writing any code.

It is built around the **IDIOT method** — a project execution framework that breaks
any project into five ordered phases:

1. **Investigation** — audience, goals, sub-problems, prior art, tech choice
2. **Design** — architecture, required tech, cost, scale
3. **Implementation** — build the design piece by piece
4. **Optimization** — improve without sacrificing quality
5. **Testing** — user-proposed tests, derived test cases, unit/E2E tests
6. **Follow-up** — suggested next steps

`questions.json` encodes the full question tree for each phase (including nested
sub-questions); `IDIOTMethod.txt` is the human-readable framework document.

## How it works

```
proposal + IDIOT method + system prompt
        │
        ▼
┌──────────────────────────────┐
│ Investigation  (N questions) │ ──► question_001.txt … question_NNN.txt
├──────────────────────────────┤
│ Design           (N questions) │ ──► design_summary.txt
├──────────────────────────────┤
│ Implementation … Follow-up     │ ──► … _summary.txt
└──────────────────────────────┘
        │
        ▼
experiment_results.json  (per-phase index of summary files)
```

- Each question is sent to the model with the project proposal, the IDIOT method,
  and a **sliding context window** (the last 5 accumulated answers) so context
  stays bounded on long runs.
- After every phase, a second model call writes a concise per-phase summary.
- All outputs land in a folder named after your project.

## Requirements

- Python 3.10+
- [Ollama](https://ollama.com) running locally (default: `http://localhost:11434`)
- A model pulled locally, e.g.:

```bash
ollama pull gpt-oss:20b
```

## Quickstart

```bash
python3 scripts/mastermind_cli.py \
  --project "Meilisearch UI" \
  --proposal "ProjectProposals/Meilisearch UI/proposal.txt" \
  --idiot IDIOTMethod.txt \
  --prompt-file "ProjectProposals/Meilisearch UI/system-prompt.txt" \
  --model gpt-oss:20b
```

Outputs appear in `./Meilisearch UI/`.

## Options

| Flag | Default | Description |
| --- | --- | --- |
| `--project NAME` | required | Project name; a folder with this name stores the outputs (alphanumeric, `-`, `_` only) |
| `--proposal PATH` | required | Project proposal document (text) |
| `--idiot PATH` | required | IDIOT method document (text) |
| `--prompt-file PATH` | `system_prompt.txt` | System prompt file |
| `--model NAME` | `gpt-oss:20b` | One of `gpt-oss:20b`, `qwen3:30b`, `devstral:24b`, `llama3.3:70b` |
| `--questions-file PATH` | `questions.json` (repo root) | Question tree JSON |
| `--output-dir PATH` | current directory | Where the project folder is created (must be under the current directory) |
| `--ollama-url URL` | `$OLLAMA_URL` or `http://localhost:11434/api/generate` | Ollama endpoint |
| `--api-key KEY` | `$OLLAMA_API_KEY` | Optional bearer token for Ollama |
| `--timeout SECONDS` | `120` | Per-request timeout |

The question tree supports nested `subQuestions`, which are asked in depth-first
order. Empty questions are skipped.

## Project layout

```
.
├── IDIOTMethod.txt                 # The IDIOT execution framework
├── questions.json                  # Phase → question tree
├── ProjectProposals/
│   └── Meilisearch UI/             # Example proposal + system prompt
├── scripts/
│   └── mastermind_cli.py           # The CLI
└── tests/
    └── test_mastermind_cli.py
```

## Testing

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## License

MIT — see [LICENSE](LICENSE).