ukvet: UK Companies House

ukvet — AI Due-Diligence Agent for UK Companies

Vet any UK company in 30 seconds — cited, evaluated, open source.

[CI] [PyPI] [License: MIT]

[ukvet-mcp demo in Claude Desktop]

Status: Phase 6 (launch) Completed. ukvet-mcp 0.1.0 is on PyPI and in the official MCP Registry (io.github.FraidoonOmarzai/ukvet-mcp). The agent, UI and evaluation harness are built, tested and gated in CI.

Quickstart

1. Use the data layer in Claude Desktop (2 minutes)

You need uv and a free Companies House REST API key (create one here, live environment).

$env:CH_API_KEY="your-key"; uvx ukvet-mcp --check      # prints OK if the key works

Then add this to claude_desktop_config.json and restart Claude Desktop:

{  "mcpServers": {    "ukvet": {      "command": "uvx",      "args": ["ukvet-mcp"],      "env": { "CH_API_KEY": "your-key" }    }  }}

Full guide: packages/ukvet-mcp and its PyPI page.

2. Run the full agent and UI (Docker)

git clone https://github.com/fraidoonomarzai/ukvet.gitcd ukvetcopy .env.example .env          # add CH_API_KEY (LLM settings are optional)docker compose up --build       # API http://localhost:8000/docs, UI http://localhost:8501

With no LLM_PROVIDER set, reports use a template narrative and cost nothing. With one set, the LLM writes the wording and every sentence must pass the citation check, or the template is used instead.

What it does

Enter a UK company name or number. ukvet checks official Companies House records and returns a risk report answering:

1. Is it active, dissolved or insolvent?
2. How old is it?
3. Who are the directors?
4. Are its accounts or confirmation statement overdue?
5. Who controls it?
6. Does it have secured debts (charges)?
7. Any insolvency history?
8. Have its directors run companies that failed?
9. Any recent changes of directors or address?
10. What are the red flags?

Every fact is cited to the official record. When data is missing, ukvet says so instead of guessing.

How it's built

Facts, red flags and the risk level come from deterministic code and rules. The LLM is one node: it sees only verified facts, has no tools, and every claim it writes is checked. Architecture: docs/08-architecture.md

Results

Measured on a versioned set of 48 companies (30 dev, 18 test). Full tables, intervals and failure analysis: docs/eval-report.md and docs/results.md.

Baseline (Claude Haiku 5.5, all 48 companies)

Model comparison (test split: 18 reports, about 155 claims each)

Recommendation: keep Claude Haiku 5.5 as the default; the open-weight path is supported by a settings change. Accuracy differences are within the noise on this test set.

Limitations (read these)

• M1 is agreement with an oracle I wrote, hand-checked against the live website for 10 companies. It does not prove every field is true, and a 100% score means the set is not yet hard enough to find new retrieval bugs.
• M2 and M4 are mechanical checks (IDs, dates, numbers, names, forbidden wording). Whether a cited fact fully supports a sentence, and fairness of wording, were not measured.
• The test split is 18 reports; one open-weight model, one run each; latency and cost are from one network and one GPU.
• Prompt injection: one payload (a company name) put attacker-chosen text into Claude's report on 3 of 3 host companies. The risk level and red flags did not change. This is an open follow-up, and M6 measures resistance to the listed payloads only.
• Labels and rules were written by one person.

Development

Requires Python 3.12+ and uv. Commands below are shown for PowerShell; on Linux or macOS the same uv run ... commands work (a Makefile is provided as a shortcut where make is available).

git clone https://github.com/fraidoonomarzai/ukvet.gitcd ukvetcopy .env.example .env                 # add your Companies House API keyuv sync --all-groups --all-packages    # install dependenciesuv run ruff check .                    # lintuv run ruff format --check .           # formattinguv run mypy                            # type checkuv run pytest                          # tests

Run it

# .env: CH_API_KEY=...   (optional: LLM_PROVIDER / LLM_MODEL / LLM_API_KEY, see .env.example)uv run ukvet-check --full 00445790     # terminal, no UIdocker compose up --build              # API (http://localhost:8000/docs) + UI (http://localhost:8501)

With no LLM_PROVIDER set, reports use a template narrative and cost nothing. With one set, the LLM writes the wording and every sentence must pass the citation check, or the template is used instead.

Run the evaluation

uv run ukvet-evals demo-build                      # synthetic demo set, proves the harness worksuv run ukvet-evals run --dataset demouv run ukvet-evals run --dataset v0.1 --split dev  # real set, dev split, free (template mode)uv run ukvet-evals gate --dataset v0.1             # compare with the baseline; fails if worse

Observability and safety (Phase 4)

# .env (all optional): LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST#   UKVET_TRACE_CONTENT=redacted (default, names are masked) or full (synthetic data only)#   UKVET_PRICE_IN_GBP_PER_MTOK / UKVET_PRICE_OUT_GBP_PER_MTOK  (cost is shown only when set)uv sync --all-groups --all-packages --extra observability
# live latency (M7), cost (M8) and tool calls (M9); needs CH_API_KEY and an LLM keyuv run python scripts/phase4_metrics.py --file numbers.txt --out evals/results/phase4
# prompt-injection resistance (M6): record once, then replay for freeuv run ukvet-evals extend-injection --dataset v0.1uv run ukvet-evals injection --dataset v0.1 --llm record --model <model>uv run ukvet-evals injection --dataset v0.1 --llm replay --model <model>

Tracing is off unless both Langfuse keys are set, and it can never break a report. Targets: M6 injection resistance 95% or more, M7 p95 latency under 30 s, M8 cost under £0.05 per report, M9 tool calls per report tracked as a baseline. M6 measures resistance to the listed payloads only; it is not proof of safety. Measured results are in evals/results/.

Model comparison (Phase 5)

# one env file per model; copy the one you want over .envuv run python scripts/phase5_check_endpoint.py        # smoke-test an OpenAI-compatible endpoint (vLLM)uv run ukvet-evals run --dataset v0.1 --split test --llm record --model <model-id> --confirm-test-split "reason" --out evals/results/v0.1-test-<name>uv run python scripts/phase4_metrics.py --file numbers.txt --label <name> --out evals/results/phase5-live-<name>uv run ukvet-evals compare --init                     # create evals/comparison.json, fill it inuv run ukvet-evals compare                            # writes docs/results.md; refuses unfair comparisons

Both models must run on the same dataset version, split, prompts and git commit; compare refuses different datasets or splits and warns about the rest. How the open-weight model was served: ADR-008 and docs/PHASE-5-GPU-SETUP.md.

More documents

Architecture and ADRs · Evaluation report · Model comparison · Threat model · Decision log · All docs

Disclaimer

ukvet is informational only. It is not legal, financial or credit advice. Reports are based on public records at the time of retrieval, which may be incomplete or out of date. Always verify before making decisions. ukvet is not affiliated with Companies House.

Attribution

Contains public sector information licensed under the Open Government Licence v3.0 (Companies House).

Licence

Code: MIT © 2026 Fraidoon Omarzai