Vey

A machine-native decision runtime for fast, typed decisions without autoregressive generation.

Vey is a runtime, not a single neural model. It composes narrow, independently measured mechanisms and emits no output tokens. Version 2 adds CRUX, a semantic decision engine, and this repository now ships the trained CRUX comparator weights (comparator.pt).

What this repository ships

artifact	what it is	fetched how
comparator.pt	the trained CRUX ordinal comparator (fine-tuned ModernBERT-base encoder + ordinal head, ~150M params)	committed here (Git LFS)
CRUX NLI backbone	tasksource/ModernBERT-base-nli, frozen, used stock for categorical predicates	fetched at run time
semantic encoder (Vey 1 lanes)	mixedbread-ai/mxbai-embed-xsmall-v1, 24.1M, frozen	fetched at run time

No upstream weights are duplicated here. The upstream models are fetched at run time and their copyright and attribution remain with their authors.

CRUX comparator (comparator.pt)

CRUX grounds a natural-language decision into typed evidence, then executes it deterministically. The learned component is an antisymmetric ordinal comparator: for an axis and two option texts A and B,

f(axis, A, B) = head(CLS_encode("On {axis}: A = {A} | B = {B}"))
r(A, B)       = 0.5 * (f(axis, A, B) - f(axis, B, A))   # antisymmetric by construction
q_i           = mean_{j != i} r(i, j)                    # permutation-invariant potential

comparator.pt is a torch state file:

{"model_id": "tasksource/ModernBERT-base-nli",
 "enc": <fine-tuned encoder state_dict>,
 "head": <ordinal head state_dict>}

Categorical predicates (permitted, supports tools, a numeric floor) are grounded by the stock frozen NLI model; no neural component owns the final decision, which a deterministic microcode executor makes.

Use with the vey package

pip install vey
export VEY_CRUX_COMPARATOR_HF=fazinahamed/vey     # optional: this repo is the default

import vey

r = vey.decide(
    question="Choose the option with the most headroom.",
    candidates={
        "a": "ample headroom and generous capacity",
        "b": "very little headroom, tight on capacity",
        "c": "a moderate amount of headroom",
    },
    explain=True,
)
r.answer                       # "a"
r.decision_mode                # "crux"
r.certificate.to_dict()        # versioned machine evidence, not generated text

The structured lane runs with no artifact at all; the crux lane loads comparator.pt on first use. Point VEY_CRUX_COMPARATOR at a local comparator.pt, or VEY_CRUX_COMPARATOR_HF at repo_id[@revision], to override.

Benchmarks (immutable, preregistered, run-once)

Preregistered zero-shot Snake control benchmarks. Numbers are the values measured at each run and are not retro-edited.

variant	system	params	food	agreement	permutation
planner-assisted (seeds 711-714)	CRUX	~150M	136	1.000	1.000
planner-assisted	Laya	421M	81	0.910	0.880
raw-consequence (seeds 611-614)	CRUX	~150M	155	0.971	0.965
raw-consequence	Laya	421M	17	0.404	0.433

The raw-consequence gap (155 vs 17 food) is the load-bearing result: CRUX reconstructs the decision from grounded consequences rather than reading verdict labels. A later architectural change reached 1.000 order- and rename-invariance on 1,500 held-out generic decisions, at a disclosed cost of 0.951 to 0.914 composition accuracy. See the repository benchmarks doc.

Vey 1 lanes (unchanged)

lane	mechanism	role
structured	exact scoring over typed candidates, online reliability, exact history	structured decisions
semantic (fixed)	frozen encoder + trained pooled head	known label sets
semantic (open)	frozen encoder + cosine over cached candidate embeddings	novel candidate sets
retrieval	BM25 + semantic, fused by reciprocal rank fusion	documents
long context	BM25 sentence selection, then the encoder	long states
act	ToolCard selection, typed extraction, exact schema compiler	tool calls
trust	calibrated risk + deterministic policy	abstention, escalation

Vey 1 timings (Intel i5-12400F, CPU, batch=1): semantic decision 2.6 to 2.9 ms p50; long-context decision 9 to 11 ms p95; closed-set intent 0.884 / 0.832 / 0.780 on Banking77 / CLINC150 / MASSIVE.

Intended use

Closed-set routing, matching against a candidate set that may change between calls, priority decisions over qualitative option consequences (CRUX), and typed tool-call construction where a missing required value becomes ASK_FOR_INFO.

Not intended use

Vey is not a language model and does not replace one. It produces no open-ended text and performs no general reasoning. The CRUX comparator is a decision primitive, not a chat model.

Limitations

• The CRUX comparator is fine-tuned, not frozen-zero-shot; its behavior reflects the training axes.
• OOD detection at a tight false-abstain budget is weak (Vey 1 lanes).
• Tool calls are conservative; Vey prefers to ask over guessing.
• The open matcher returns similarity scores, not calibrated probabilities.
• English only.

Source

• GitHub: https://github.com/fazin-ahamed/vey
• Documentation: https://github.com/fazin-ahamed/vey/tree/main/docs
• CRUX API: https://github.com/fazin-ahamed/vey/blob/main/docs/CRUX.md
• Issue tracker: https://github.com/fazin-ahamed/vey/issues

License

Vey code is Apache-2.0. The CRUX comparator is fine-tuned from tasksource/ModernBERT-base-nli; the default Vey 1 encoder is a separate Apache-2.0 work by the Mixedbread AI authors.