valordb 0.4.0

VALORDB — a sovereign, grounded CLI + Python client over every published Board of Veterans' Appeals decision + Title 38. Statistics are computed by the corpus, never the model.

VALORDB

Veterans Appeals Library & Outcomes Research — in your terminal.

A sovereign, grounded CLI and Python client over every published Board of Veterans' Appeals (BVA) decision (1992–present, ~1.86 million) wired to the Title 38 statutes and regulations (38 U.S.C. + 38 CFR) that govern them.

pip install valordb
valordb

---

Why this is different: the model is never the source of a fact

Legal research tools that let an LLM free-text statistics and citations are a liability — the model will confidently invent a grant rate or a regulation that doesn't exist. VALORDB makes that structurally impossible:

• Statistics are computed by the corpus, injected into the prompt as a locked VERIFIED_FACTS block, and any number the model emits that isn't traceable to that block is struck after generation.
• Citations are verified against the actual Title 38 store — anything that doesn't resolve is flagged, and M21 manual cites outside the mirror are flagged (VALORDB mirrors only part of M21).
• The model's job is reduced to explaining fixed facts. It may not compute, infer, rank, or invent a statistic or a citation.

The grounded analyst runs on your own Ollama — nothing leaves your machine.

---

Quick start

Interactive (a research workstation)

valordb

  ██╗   ██╗ █████╗ ██╗      ██████╗ ██████╗ ██████╗ ██████╗
  ██║   ██║██╔══██╗██║     ██╔═══██╗██╔══██╗██╔══██╗██╔══██╗
  ╚██╗ ██╔╝██╔══██║██║     ██║   ██║██╔══██╗██║  ██║██╔══██╗
   ╚════╝  ╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚═════╝ ╚═════╝
  VALORDB CLI — valordb.org

valordb> ask PTSD and sleep apnea claimed together, under Title 38
valordb> conditions sleep apnea
valordb> law usc-38-1110
valordb> upgrade

One-shot / scriptable

valordb ask "overview of Sleep Apnea + PTSD claims" --mode attorney
valordb kpi --json | jq .rates
valordb conditions "sleep apnea"
valordb dimension judge
valordb law cfr-38-3.310

As a Python library

from valordb import VALORDB

db = VALORDB(api_key="vk_firm_…")          # or set VALORDB_API_KEY
print(db.kpi()["rates"])                    # corpus headline rates
c = db.conditions()
print(c.rate("sleep apnea"))                # 0.4171  (any-grant)
print(c.together("PTSD", "sleep apnea"))    # real co-occurrence rate + N
print(db.law("usc-38-1110")["heading"])     # a Title 38 section (free)

---

Commands

Command	What it does
ask <q> [--mode veteran|attorney]	Grounded analyst on your local Ollama — corpus-locked stats, verified cites
kpi	Headline outcome rates (any-grant / grant / remand / deny)
conditions [name]	Per-condition any-grant + N, AMA-vs-Legacy split, co-occurrence
dimension <dim>	Breakdown by judge, regional_office, condition, rep_type, …
law <id>	A Title 38 section, verbatim — free, e.g. usc-38-1110, cfr-38-3.310
m21 <id>	An M21 manual section — free (sub-regulatory; partial mirror)
search <q>	Search Title 38 + M21 by keyword/citation — free (decision-corpus search is Firm+, coming)
setup	Guided local-AI install — offers to install Ollama + pull a tiny model for ask
config	Configure the AI engine — Ollama (localhost/LAN + any port), BYOK cloud, or Claude Code CLI (-p)
info	Your key: tier + quota
key [<vk_…>] · login · logout	Show / set / paste / remove your license key
upgrade	Subscribe / upgrade — purchase through the CLI (Firm+ for the API)
site · help · quit	Open the site · reference · exit

---

Tiers

The Title 38 & M21 law is free to read (here and on valordb.org). The analytics, decision search, grounded AI, and API/CLI are paid:

Tier	Price	Adds
Veteran	Free	Read the complete Title 38 + M21 (no key)
Professional	$49/mo	The web analytics dashboard + Attorney-grade AI
Firm	$149/mo	REST API + this CLI + bulk export + team (5 seats)
Enterprise	$499/mo	Full API + white-label + SLA + sovereign on-site appliance

valordb upgrade runs a Paddle checkout from the terminal and saves your key. Veterans and non-profits — discounts available; email [e-mail].

---

Configuration

Precedence: environment variable → ~/.valordb/config.toml.

Setting	Env	Config	Default
License key	VALORDB_API_KEY	[auth] api_key	—
API base	VALORDB_URL	—	https://valordb.org
Ollama host	VALORDB_OLLAMA / OLLAMA_HOST	[ai] ollama_host	http://localhost:11434
Ollama model	VALORDB_MODEL	[ai] model	first installed

export VALORDB_API_KEY=vk_firm_…
export VALORDB_OLLAMA=http://192.168.0.92:11434   # a LAN Ollama box works from the CLI

The key is stored at ~/.valordb/config.toml (chmod 600) and never logged.

---

For agents & automation

The CLI is a thin client over the keyed REST API (/api/v1, Firm+). Anything that can send an X-API-Key header — including an Ollama tool/agent or an MCP server — can call the same endpoints directly (JSON in, JSON out). Use --json for machine output. Endpoints: status, kpi, conditions, kpi/dimension/{dim}, law/{id}.

---

Sovereignty & privacy

• The grounded ask runs entirely on your Ollama (local or LAN). Your question and the corpus context never leave your machine.
• The optional httpx extra (pip install valordb[httpx]) uses httpx instead of urllib for API calls. The importable SDK only needs requests.

---

Legal

Legal information, not legal advice. VALORDB surfaces public decisions, statutes, and regulations and how the Board has historically ruled. It does not interpret your claim and is not a substitute for an accredited representative or attorney. VA claims carry hard deadlines and one-shot effective-date consequences — verify everything against the controlling law and accredited help (va.gov/ogc).

The BVA corpus is public record. Per-judge and per-office rates reflect docket and case mix, not a controlled measure of adjudicator favorability.

---

Created by Joseph C. McGinty Jr. · © 2026 ResilientMind AI LLC · valordb.org