# 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 .
```