SRBN

srbn is a small Python library for reliable long-horizon work with language model systems. It does one thing: it runs a generator behind explicit checks, records every attempt, and stops only when the accepted output satisfies the declared tolerance or the policy says no further progress is certified.

It is a library, not an agent framework. There are no providers, planners, databases, background workers, or hidden orchestration layers in the core.

import srbn


def generate(prompt: str, feedback: str | None) -> str:
    if feedback:
        return "please approve the request"
    return "approve the request"


result = srbn.run(
    "Write a polite request",
    generate=generate,
    checks=[srbn.contains("please")],
)

assert result.ok
print(result.output)

Install

pip install srbn
# or
uv add srbn

Python 3.12+. The core package has zero runtime dependencies.

Model

Reliable long-horizon systems need to preserve checked state. SRBN expresses that requirement as a small control loop.

1. A generator proposes an output.
2. Checks report residuals.
3. Residuals are aggregated into a non-negative score.
4. Failed checks produce feedback for the next proposal.
5. The trace records the evidence used to accept, stop, or exhaust the run.

The score is a runtime proxy for Lyapunov or barrier energy. A score of 0.0 means the configured checks pass cleanly. A positive score means some declared condition remains unsatisfied.

With Policy(require_descent=True, on_no_descent="stop"), the loop also enforces a measured descent gate: a new attempt must reduce the score by more than min_descent, or the run stops with Status.STOPPED.

API

Built-in checks are intentionally plain:

checks = [
    srbn.contains("SELECT"),
    srbn.not_contains("DROP"),
    srbn.json_valid(),
]

Domain checks are just callables that return CheckResult.

def has_ticket_id(output: str) -> srbn.CheckResult:
    ok = "REQ-" in output
    return srbn.CheckResult(
        ok=ok,
        score=0.0 if ok else 1.0,
        feedback="" if ok else "Include a request id.",
        name="has_ticket_id",
        evidence={"required_prefix": "REQ-"},
    )

Structured State

Use stabilize when the state is not text.

def barrier(x: int) -> srbn.BarrierResult:
    residual = abs(x)
    return srbn.BarrierResult(
        ok=x == 0,
        score=float(residual),
        feedback="move toward zero",
        correction=-1 if x > 0 else 1,
        name="distance_to_zero",
    )


def update(x: int, result: srbn.BarrierResult) -> int:
    return x + int(result.correction or 0)


result = srbn.stabilize(3, barrier=barrier, update=update)
assert result.state == 0

What Belongs Outside Core

The core deliberately excludes:

• provider SDKs;
• tool execution;
• multi-agent orchestration;
• capability security;
• risk calibration;
• durable storage;
• domain-specific verifier suites.

Those are application or plugin concerns. The core stays small so it can be embedded anywhere.

Development

uv sync
uv run --with pytest python -m pytest projects/python/srbn/tests
uv run --with ruff python -m ruff check projects/python/srbn/src projects/python/srbn/tests

License

GNU Lesser General Public License v3.0 only.

Citing

If you use SRBN in research, cite the Stability Is All You Need paper series.