feat: scaffold tolkien v0 — local-LLM classifier wrapper + CLI + eval

Initial skeleton for the deterministic compound-AI pipeline that turns
`tolkien deploy <name>` into a valinor scaffold. v0 wires one classifier
(`db_kind`) end-to-end against the Ollama-on-radagast backend so we can
iterate prompts with confidence before adding the rest.

- pyproject.toml: uv project, Python 3.13, httpx/pydantic/typer/pyyaml.
- src/tolkien/llm.py: single-turn /api/chat wrapper. JSON-mode + temp 0 +
  30m keep-alive. Pydantic schema validation on parse.
- src/tolkien/cli.py: `tolkien classify db-kind --doc <file>` runs the
  classifier and prints JSON. `tolkien deploy <name>` is stubbed.
- src/tolkien/prompts/db_kind.md: tight system prompt with 1-shot example
  and explicit "return ONLY JSON" guard.
- src/tolkien/schemas.py: DbKindResult pydantic model.
- eval/cases/mealie.yml + run_eval.py: regression harness. Currently
  one case (mealie); failures print field-level diffs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
João Pedro Battistella Nadas
2026-05-29 15:09:11 +02:00
commit 058362b87f
12 changed files with 365 additions and 0 deletions

49
README.md Normal file
View File

@@ -0,0 +1,49 @@
# tolkien
Local-LLM orchestrator that turns `tolkien deploy mealie` into a complete valinor
GitOps scaffold (config.yaml, values.yaml, CNPG cluster, Vault secrets, Terraform
stubs) ready for the operator to review and PR.
## Architecture
Compound-AI pipeline, not a ReAct loop. Each step in the deploy workflow is a
single LLM call that produces structured JSON — the surrounding logic is plain
Python. This shape works reliably on a CPU-served 7B model where a free-form
agent loop would drift.
```
deploy <name>
├── search.find_helm_chart()
├── classify.has_chart(results) — LLM, JSON
├── fetch.app_docs(url)
├── classify.db_kind(docs) — LLM, JSON
├── classify.needs_object_storage(docs)— LLM, JSON
├── classify.secrets_vs_config(env) — LLM, JSON
├── classify.storage_class(docs) — LLM, JSON
└── render.scaffold(facts) — Jinja2 → ./out/<name>/
```
## Backend
Ollama running on radagast (`http://radagast.jpnadas.xyz:11434`), serving
Qwen2.5-Coder-7B-Instruct Q4_K_M. See valinor/`ansible/playbooks/radagast-setup.yml`
for the host setup.
## v0 scope
- Single classifier (`db_kind`) wired end-to-end against the live model
- CLI: `tolkien classify db-kind --doc <file>` prints JSON
- Eval harness with one case (mealie)
- Output to stdout / `./out/`; no git push, no FastAPI, no Redis
v1 layers on FastAPI + Redis + a Gitea bot to push branches; v2 wires a Gitea
webhook for issue-comment triggers.
## Develop
```bash
uv sync
uv run tolkien --help
uv run pytest
uv run ruff check .
```