std.belief

std.belief gives you a first-class calibrated-confidence type. Instead of juggling a running average and a count, you hold a Belief — a Beta distribution over the probability that some hypothesis is true — and feed it observations. Each observation is a soft Bernoulli update: alpha += conf, beta += 1 - conf, where conf is a confidence in [0, 1]. The posterior mean is your calibrated confidence.

from std.belief import Belief, prior, prior_with

Why it exists

AI pipelines constantly need to answer “how sure are we, given the evidence so far?” — and typically grow a hand-rolled tracker (often a ~120-line BeliefTracker). std.belief replaces that with a small, verified type. Crucially nothing about the distribution is hardcoded in the runtime: the prior is a parameter you choose, and the update rule is plain Sema you can read.

Constructing a belief

Start from a prior. prior() is the uniform Beta(1, 1) — maximally uncommitted. prior_with(alpha, beta) sets any prior via pseudo-counts, letting you encode a head start (e.g. a skeptical prior_with(1.0, 4.0)):

b = prior()                 # uniform Beta(1, 1); confidence() == 0.5
skeptical = prior_with(1.0, 4.0)   # starts around 0.2

Updating with evidence

update(conf) mutates the belief in place and records the new confidence in its history. Confidence values are soft — 1.0 is a fully-confident positive observation, 0.5 is uninformative, 0.0 a fully-confident negative:

b = prior()
b.update(0.9)     # strong positive evidence
b.update(0.8)
b.update(0.3)     # some negative evidence
print(b.confidence())   # posterior mean E[theta] = alpha / (alpha + beta)

For immutable state threading — for example inside an agent_loop.loop_until step, where a lambda may not mutate captured state — use bumped(conf), which returns a new belief instead of mutating:

from std.agent_loop import loop_until
from std.belief import prior

final = loop_until(
    prior(),
    max_iters=10,
    step=(s => s.bumped(observe_confidence())),
    done=(s => s.confidence() > 0.95),
)

Reading the belief

Method	Meaning
confidence()	Posterior mean alpha / (alpha + beta) — your calibrated confidence
mode()	Posterior mode (defined only when alpha > 1 and beta > 1)
variance()	Posterior variance — how tightly the belief is concentrated

b = prior_with(8.0, 2.0)
print(b.confidence())   # 0.8   — the point estimate
print(b.mode())         # ~0.875 — the most likely theta
print(b.variance())     # shrinks as evidence accumulates

Use variance() (or the width it implies) to decide when you have seen enough evidence to stop — a natural termination signal for agentic search.

Confidence is a calibrated quantity

Because a Belief is a real posterior, variance() gives you honest uncertainty, not just a point estimate. Pair it with the calibrated ~= similarity operator to turn fuzzy matches into evidence you can accumulate.

See the full signature list — all fields and effect rows — in the generated std.belief API reference.