Beveridge

System One decision models with open weights. Typed yes/no, choice and score decisions over any text, with a calibrated probability for every option, without generating text, on your own machines.

Give Beveridge a document (text, email, ticket, log or JSON) and typed questions. It returns typed answers: yes/no (noul), one of the options you describe (choice), or a level on a scale you define (score), each with calibrated probabilities. It never generates text, so there is nothing to parse and nothing to hallucinate, and it runs locally: your documents never leave your machines.

Installation

python -m pip install bev-decisions            # Beveridge-Large-C: laptop CPU or any GPU
python -m pip install "bev-decisions[pro]"     # adds Beveridge-Pro-C and Beveridge-Pro-C-Web: one GPU with about 60 GB

pip install beveridge installs the same package under the models' name (import beveridge or import bev).

Python 3.10 or newer. The first bev.load() downloads the model from Hugging Face and caches it; after that it works offline. Optional extras:

Quickstart

import bev

model = bev.load()   # Beveridge-Large-C (laptop or GPU); bev.load(bev.PRO_MODEL) for Beveridge-Pro-C (large GPU)

answers = model.decide(
    "Subject: Charged twice for order 88412. I was billed $49.99 twice on 3 October. Please refund one payment today, it's urgent.",
    {
        "team":   {"type": "choice", "instructions": "Which department should handle this message?",
                   "criteria": {"billing": "billing team", "refunds": "refunds team", "technical": "technical team"}},
        "urgent": {"type": "noul",   "instructions": "Does the customer explicitly ask for urgent or same-day handling?"},
        "severity": {"type": "score", "instructions": "How severe is the problem for the customer?",
                     "criteria": ["low", "medium", "high"]},
    },
)
answers["team"]      # {"choice": ..., "confidence": ..., "probabilities": {...}}
answers["urgent"]    # {"noul": P(yes), "probabilities": {"true": ..., "false": ...}}
answers["severity"]  # {"label": ..., "score": expected level, "confidence": ..., "probabilities": {...}}

More in examples/: fifteen short scripts, from a first yes/no question to complete automations, a voice assistant and a browser agent step.

Run with or without a GPU

bev.load() picks the best device it finds: an NVIDIA GPU (cuda), an Apple Silicon GPU (mps), otherwise the CPU. Choose one yourself with device=:

model = bev.load(device="cpu")                    # Beveridge-Large-C, no GPU needed
model = bev.load(device="cuda")                   # Beveridge-Large-C on an NVIDIA GPU
model = bev.load(device="mps")                    # Beveridge-Large-C on an Apple Silicon GPU
pro = bev.load(bev.PRO_MODEL, device="cuda")      # Beveridge-Pro-C: NVIDIA GPU with about 60 GB

bev "I was charged twice, please refund" --noul "Does the customer ask for a refund?" --device cpu

Beveridge-Pro-C needs a GPU with about 60 GB; without one, use Beveridge-Large-C, or route mode (below) to send only the unsure answers to a GPU machine.

Use cases

Automation examples

Complete scripts you can run and adapt (they use Beveridge-Large-C, so a laptop is enough):

# the pattern behind all three: ask, gate on confidence, let your code decide
answers = model.decide(email_text, bev.presets.get("ticket_triage"))
sure, review = bev.gate(answers, threshold=0.8)
if "department" in sure:
    route_to(sure["department"])
else:
    send_to_person(email_text)

Voice examples

Beveridge reads text, so it pairs well with open speech models: a caller's voice note is transcribed, Beveridge answers typed questions about it, fixed reply rules turn the answers into a reply, and a text-to-speech model speaks it. Same model, different questions: the video shows 23 use cases (customer service, bank card line, IT helpdesk, agentic AI and multi-agent routing, emergency line, telecom, engineering, lab notes, drug discovery, robotics, autonomous car and more).

pip install bev-decisions faster-whisper kokoro soundfile
python examples/14_voice_reply.py note.wav      # prints the transcript and decisions, writes reply.wav

Speech to text: faster-whisper (MIT). Text to speech: Kokoro-82M (Apache-2.0), stock voices only; the demo uses no real person's voice. Use cases outside the areas Beveridge was tested on are illustrations. Beveridge can make mistakes; keep a person in the loop for important decisions.

Web browsing

Beveridge-Pro-C-Web (bev.WEB_MODEL) is Beveridge-Pro-C with web browsing added: it picks the next step of a browser agent (click, type, wait, done) and the element it applies to, with a probability for every option, and keeps Beveridge-Pro-C's results on documents. Next step on web pages from site types it never saw: 98.2% (Beveridge-Pro-C: 49.4%). Live in the open-source browser loop jev-ultrafast: hotel search 3/3 (median 1.86 s) and Wikipedia 3/3 (median 4.88 s) on one H200.

web = bev.load(bev.WEB_MODEL)       # one GPU with about 60 GB; downloads Gemma 4 from Google's repository and Beveridge's adapter

examples/15_browser_step.py shows one step: the page and the goal in, the operation and the element out, unsure steps sent to a person. Keep a person in the loop for anything that buys, sends, deletes or signs.

Decision primitives

Up to 16 questions per call. Beveridge-Large-C reads the document once for all of them; Beveridge-Pro-C answers each question in its own scoring pass (questions with more than 26 options take a second round). Keep each question narrow and combine the answers in your code. Describe options in a few words that tell them apart, add an "other" option when nothing may fit, and keep the option order stable between calls.

Confidence gating

sure, review = bev.gate(answers, threshold=0.8)   # sure: {name: value}; review: answers below the threshold
if "team" in sure:
    route(ticket, sure["team"])
else:
    send_to_person(ticket)

Choose the threshold on a few hundred labelled examples of your own (see Evaluate on your data).

Route mode

router = bev.Router(load_strong=True, threshold=0.8)    # Beveridge-Large-C first, unsure answers asked again on Beveridge-Pro-C
result = router.decide(text, questions)
result["answers"], result["routing"]                    # routing: {"team": "fast", "urgent": "strong"}

Modes: "cascade" (default), "fast", "strong".

Schema-driven decisions

from typing import Literal
from pydantic import BaseModel, Field

class Ticket(BaseModel):
    urgent: bool = Field(description="Does the customer explicitly ask for urgent or same-day handling?")
    team: Literal["billing", "technical", "shipping"] = Field(description="Which department should handle this message?")

ticket = bev.decide_as(model, text, Ticket)     # Ticket(urgent=True, team='billing')

Workflow presets

bev.presets.names()   # ['request_safety', 'review_sentiment', 'security_log', 'service_alert', 'ticket_triage']
model.decide(text, bev.presets.get("security_log"))
model.decide(invoice, {"over_limit": bev.presets.over_limit("$8,900"), "big": bev.presets.count_above("$250.00")})

Batch processing

results = model.decide_batch([(text, questions) for text in texts], batch_size=8)

Command line

bev "I was charged twice, please refund" --noul "Does the customer ask for a refund?" --model sathiskumarjothi0/Beveridge-Pro-C
bev --file ticket.txt --preset ticket_triage --min-confidence 0.8
bev --file alert.txt --score "How severe is this?" --levels low medium high
bev --batch tickets.txt --preset ticket_triage
bev presets

Self-hosting

pip install "bev-decisions[serve]"
bev serve --model sathiskumarjothi0/Beveridge-Pro-C --port 8000     # POST /v1/decide, /v1/batch; GET /v1/presets, /health
docker compose -f compose.cuda.yaml up                         # the same server in a GPU container
pip install "bev-decisions[mcp]"
bev mcp --model sathiskumarjothi0/Beveridge-Pro-C                    # MCP tools: decide, decide_preset, list_presets

MCP client configuration: {"mcpServers": {"bev": {"command": "bev", "args": ["mcp", "--model", "sathiskumarjothi0/Beveridge-Pro-C"]}}}. The server listens on 127.0.0.1 and has no authentication; put it behind your own gateway (TLS, authentication, rate limits) before exposing it.

Benchmarks

Accuracy (%) = correct answers ÷ questions on held-out test sets; the same cases for every system (October 2026). Bold = best in the row; – = not run. * = an area Beveridge was not built for. Question-by-question results are on the Hugging Face model card.

How much of the work can you automate?

Hand over the most confident answers first: the share you can automate while those decisions stay at least 95% correct. Example: "76% at 95%" means 3 of every 4 decisions are taken automatically and at least 95% of them are right; the rest go to a person. Answers given with the same confidence are handed over together, so a system whose "100% sure" answers are only 94% right reaches 0% at the 95% target. Beveridge-Bench, typed decisions and Aegis 2.0, 10,238 answers per system.

Size and speed

Accuracy on the same 10,238 answers against total parameters (log scale), for every system with a published size: Beveridge-Large-C (0.4B) and Beveridge-Pro-C (25.8B) are more accurate than LLMs of 31B to 675B.

Beveridge, one document with 3 questions, package from PyPI: Beveridge-Large-C 4.9 ms per decision on one NVIDIA H200, 17 ms on an Apple M4 Pro laptop GPU, 60 ms on its CPU; Beveridge-Pro-C 22 ms on one H200. Jev and the LLMs were measured through their cloud APIs (median per decision, including network and queueing): Jev 98 ms, the five LLMs 4.1 to 7.0 s.

Decisions on documents

Public classification tests

Areas Beveridge was not built for

Calibration of Beveridge-Large-C (confidence = the probability of the answer given; ECE 0 is perfect):

Calibration of Beveridge-Pro-C (confidence = the probability of the answer given; ECE 0 is perfect):

Evaluate on your data

bev eval my_cases.jsonl --threshold 0.8

Each line: {"state": "...", "questions": {...}, "labels": {"name": answer}}. Reports, per question type: accuracy (correct ÷ questions), ECE (Σ over 10 confidence bins of share of answers × |accuracy − mean confidence|; 0 is perfect; example: a bin with 40% of the answers at mean confidence 0.95 and 90% right adds 0.4 × 0.05 = 0.02) and, at the threshold, the share of answers and their accuracy.

Limits

• English only; 4,096 tokens per call (longer text is cut at the end); no images.
• Knowledge-heavy decisions (case law, finance topic labels) are the weakest area; check them on your own data.
• Answers can change when the options are shuffled for a small share of questions; keep option order stable.
• For decisions with serious consequences, validate on your own data and keep a person in the loop.
• Questions with more than 26 options run as a tournament on Beveridge-Pro-C: lower accuracy, less calibrated confidence.

Contributing and security

Issues and pull requests are welcome; run pip install -e ".[all,dev]", ruff check src tests examples and pytest (the tests need no model download). Report security problems privately through GitHub: Security → Report a vulnerability.

Support

If Beveridge is useful to you, you can support its development: buymeacoffee.com/sjothi

About the name

Beveridge is named after Sir William Beveridge (1879–1963), the British economist, born in British India and educated in England, whose 1942 Beveridge Report laid the foundations of the modern welfare state and of the National Health Service (NHS), built for the good of future generations. The name is a reminder of what we want from the model: dependable, fair decisions that serve people, made carefully and checked against the facts.

Other models on Hugging Face are called Bev; they are not related to this project. The package keeps its short name: pip install bev-decisions, import bev.

Licence

Apache-2.0, © 2026 Dr. Sathiskumar JOTHI: the package and the models, commercial use allowed. Beveridge-Pro-C is built on Gemma 4 (Apache-2.0) by Google; Beveridge-Large-C on ModernBERT-large (Apache-2.0) by Answer.AI and LightOn.