santhosh-omlabs/velo-base

Velo Base 1.0

Velo is a compact, CPU-fast typed-decision specialist: given a JSON state and typed questions (choice, noul, score), it returns a calibrated probability distribution per question. Version 1.0 is a refittable base sealed on LocalLLaMA/typed-decisions.

Not a neural net. Not an LLM. Classical stack: HistGradientBoosting soft heads + dict/state features + TF-IDF→TruncatedSVD(256) + optional customer-service distill blend + clip_renorm + per-qtype temperature. English-only specialist for schemas shaped like the training workflows. Intended as a base you can refit onto vertical typed-decision labels.

• Author: Santhosh Reddy
• License: Apache-2.0
• Code + package: this repo ships velo_base/ · also on GitHub: santhosh-omlabs/velo-base

Honesty box

Claim	Status
Sealed accuracy 0.7535 on official typed-decisions test (400 cases / 2,000 decisions)	Measured — artifacts/seal_v1.json
~98.4% of published Laya accuracy (0.766); ~103.6% of TypeSafe Jev 1.13 (0.727)	Published/known figures — we did not re-run Laya/Jev on our ultra-fresh robustness suite
p50 latency ~32 ms per 5-decision case on our eval host	Measured; Laya p50 on the same host was ~740 ms (artifacts/laya_latency.json)
Installed weights ~177 MB	checkpoints/hybrid/bundle.pkl
Presentation must-bar ≥60%	PASS; stretch ≥72% FAIL on some modes (documented)

Hard floors for this release: accuracy ≥ 0.752, p50 ≤ 35 ms, size ≤ 200 MB — all met.

Sealed metrics (calibrated default)

Metric	Velo Base 1.0
Accuracy	0.7535
Soft accuracy	~0.557
Brier	~0.072 (clip-best ~0.069)
ECE	~0.120
NLL	~0.647
Score MAE	~0.265
within-1	0.986
Top-50% selective	~0.894
p50 latency	~32 ms
Package size	~177 MB

By workflow (calibrated accuracy): agent_trace_observability 0.726 · customer_service 0.708 · invoice_processing 0.844 · security_incidents 0.734.

Full tables: BENCHMARK.md · MODEL_CARD.md · artifacts/seal_v1.json. Robustness: docs/ROBUSTNESS.md.

Quickstart (from this Hugging Face repo)

# Option A — snapshot download (pulls LFS weights)
pip install huggingface_hub scikit-learn numpy
python - <<'PY'
from huggingface_hub import snapshot_download
from pathlib import Path
import json, sys

root = Path(snapshot_download("santhosh-omlabs/velo-base"))
sys.path.insert(0, str(root))
from velo_base import load_bundle, predict

bundle = load_bundle(root / "checkpoints" / "hybrid")
case = json.loads((root / "examples" / "customer_service_case.json").read_text())
print(json.dumps(
    predict(bundle, case["state"], case["questions"], case["workflow"], mode="calibrated"),
    indent=2,
))
PY

# Option B — clone then install the shipped package
git lfs install
git clone https://huggingface.co/santhosh-omlabs/velo-base
cd velo-base
pip install -r requirements.txt
# or: pip install -e .
export PYTHONPATH=$PWD
python -m velo_base --ckpt checkpoints/hybrid --case-json examples/invoice_processing_case.json --mode calibrated

# Option C — GitHub package + HF weights only
pip install "git+https://github.com/santhosh-omlabs/velo-base.git"
python - <<'PY'
from huggingface_hub import hf_hub_download
from pathlib import Path
from velo_base import load_bundle, predict
import json

ckpt = Path(hf_hub_download("santhosh-omlabs/velo-base", "checkpoints/hybrid/bundle.pkl")).parent
# also fetch meta.json next to the pickle
hf_hub_download("santhosh-omlabs/velo-base", "checkpoints/hybrid/meta.json")
case = json.load(open(hf_hub_download("santhosh-omlabs/velo-base", "examples/security_incidents_case.json")))
print(predict(load_bundle(ckpt), case["state"], case["questions"], case["workflow"], mode="calibrated"))
PY

Runtime needs NumPy and scikit-learn. Hugging Face datasets is only needed to download the benchmark for sealed eval. PyTorch is not required for the production checkpoint.

Four workflow demos live under examples/:
agent_trace_observability, customer_service, invoice_processing, security_incidents (*_case.json + *_pred.json).

What it is / what it is not

Is: classical specialist (~91 HGBR heads, ~898k tree nodes, ~7.7M SVD floats); trained supervised on LocalLLaMA/typed-decisions revision ea9306458d6e9563628369a3d1e72e362fb381d2; packaged for vertical refit (docs/FINE_TUNING.md).

Is not: an open-ended LLM; a quant trading engine; a claim of SOTA over all typed-decision systems; a guarantee of transfer outside schemas that look like the training workflows.

Architecture (one paragraph)

Trees won after a small neural attempt failed the size/latency floors. Soft heads are HistGradientBoosting regressors over a concatenated dict-feature vector and a TF-IDF→SVD(256) text table, with a light CS distill blend on the customer-service workflow, then clip_renorm and per-qtype temperature. Inference runs prepare_state first so wrappers, aliases, casing, and date/unicode presentation noise are normalized without weight refits. See docs/ARCHITECTURE.md.

Files

Path	Contents
checkpoints/hybrid/bundle.pkl	Sealed weights (~177 MB, LFS)
checkpoints/hybrid/meta.json	Seal summary / floors
velo_base/	Inference package (usable after pip install -e . or PYTHONPATH)
examples/	One real test-split case + prediction per workflow
artifacts/	seal_v1.json, robustness, quality gates, Laya same-host latency, hardware
docs/	Getting started, fine-tuning, robustness, architecture
BENCHMARK.md / MODEL_CARD.md	Full metrics & intended use

Citation / license

Copyright 2026 Santhosh Reddy. Apache License 2.0 — see LICENSE and NOTICE.

Please credit the benchmark dataset: Hugging Face LocalLLaMA/typed-decisions (Apache-2.0), revision ea9306458d6e9563628369a3d1e72e362fb381d2.