62 lines
2.1 KiB
Markdown
62 lines
2.1 KiB
Markdown
# 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`.
|