# 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

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

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