nvi

Text-to-SQL analytics agent over the BIRD financial warehouse (PKDD'99 Czech bank). Three-layer Plan / Analyses / Tools architecture, purpose-built runtime, soleprint-ui frontend, Langfuse observability via the sibling lng cluster.

Quick start

Prerequisites: the lng Langfuse cluster reachable from this host, and the soleprint-ui framework propagated into ui/framework (handled by spr). Set LANGFUSE_HOST and the Langfuse keys in .env (see .env.example).

Two equivalent paths — pick one.

Primary: kind + Tilt

make kind               # create kind-nvi cluster
make tilt-up            # build images, bring up postgres, api, ui, docs, gateway
make seed               # load BIRD financial into postgres (runs inside the api pod)

*.local.ar resolves via dnsmasq; the system Caddy at ~/wdir/ppl/local/Caddyfile proxies nvi.local.ar to the kind NodePort (localhost:8060). Reload after first install: sudo systemctl reload caddy.

Then open http://nvi.local.ar.

Alternative: docker-compose

For when you don't want a k8s cluster running.

make compose-up         # build + start (postgres, api, ui, docs)
make compose-seed       # load BIRD financial (runs inside the api container)

Then open http://localhost:8060 (ui) or http://localhost:8000 (api).

IDE setup (optional)

The app runs entirely in containers; uv sync on the host is only useful for editor/LSP support. Run uv sync yourself if you want a local .venv.

Layout

api/           FastAPI: Plan, Analyses, Tools, runtime
ui/app/        Vue 3 + soleprint-ui frontend
ui/framework/  soleprint-ui (managed by spr; gitignored)
docs/          hand-built HTML + Graphviz SVGs, served via nginx
seed/          BIRD financial loader
evals/         BIRD golden-set runner
ctrl/          Tiltfile, kind config, k8s manifests, Dockerfiles
def/           external reference notes (gitignored)

Why this shape

See docs/ (served at http://docs.nvi.local.ar:8060 once Tilt is up) and the approved plan at ~/.claude/plans/context-ref-file-home-mariano-wdir-nvi-floating-dream.md.