Jarian Cottingham
bdb34e038d
- Process nested subQuestions (previously silently dropped) - Sanitize phase names for summary filenames (path traversal) - Proper urllib.request import (was __import__ hack) - Add README, MIT LICENSE, pyproject (activates CI lint/test/security) - 19 tests: validation, slug, question tree, Ollama fetch (mocked), end-to-end main()
109 lines
4.0 KiB
Markdown
109 lines
4.0 KiB
Markdown
# 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).
|