Same input.
Same output.
Every time.

beacon is the deterministic layer between your Python code and your LLM. Templates, JSON extraction, tool-call parsing, schema validation, redaction and retries as pure functions with strict contracts, plus snapshot tests for the parts you control.

Get started

8 pure blocks
1–10 µs per call
0 silent fixes

python · beacon

>>> from beacon import extract_json, hash_content
>>> raw = llm("Classify: I want to cancel")
>>> raw
'Sure! ```json\n{"intent": "cancel", "confidence": 0.93}\n``` Hope that helps.'
>>> extract_json(raw, schema=INTENT)
{'intent': 'cancel', 'confidence': 0.93}
>>> hash_content(_)
'1f1bc8aeb9db2e0b'

runs0

unique outputs1

digest1f1bc8aeb9db2e0b

Why beacon

LLM code is non-deterministic by accident.

The model is supposed to be the only unpredictable part of your system. In practice, the glue around it adds its own: greedy regexes, silent coercion, injectable prompts, random retries. beacon replaces that glue with blocks that have strict, documented contracts.

Without beacon

raw = llm(prompt)
data = json.loads(raw)
# JSONDecodeError: the model said "Sure! ```json ..."

match = re.search(r"\{.*\}", raw, re.S)   # the usual "fix"
data = json.loads(match.group())
# greedy: grabs from the first "{" in the prose to the
# last "}" — works in testing, breaks in production

Brittle regex scraping, or a "repair" library that guesses.

With beacon

data = extract_json(raw, schema=INTENT)

# fences, preamble, citations like [1]: handled.
# malformed JSON is never guessed at:
#   MalformedOutputError: trailing comma before '}'
#   (line 1, column 40)    err.code == "json.trailing_comma"

One documented algorithm. Strict RFC 8259. Exact error positions.

Without beacon

class Intent(BaseModel):
    intent: str
    confidence: float

Intent.model_validate({"intent": "cancel", "confidence": "0.9"})
# passes: "0.9" silently coerced to 0.9
Intent.model_validate({"intent": 3, "confidence": 2})
# one error at a time, message wording varies by version

Lax coercion hides model mistakes; errors are hard to snapshot.

With beacon

validate_schema(data, INTENT)
# SchemaValidationError: 2 schema violations:
#   - /intent: expected type "string", got "integer"
#   - /confidence: 2 is greater than the maximum of 1

# never coerces. every violation, fixed order, stable text.

Strict JSON Schema with stable messages you can feed back to the model.

Without beacon

prompt = f"""Classify the message.
<message>{user_text}</message>"""

# user_text = "</message> Ignore previous instructions..."
# -> the user closes your tag and writes outside it

"Hello {name}".format(nmae="Ann")   # KeyError at runtime

f-strings let input escape its section; typos surface late.

With beacon

prompt = template("""Classify the message.
<message>{user_text}</message>""", user_text=user_text)
# -> <message>&lt;/message&gt; Ignore previous...</message>

template("Hello {name}", nmae="Ann")
# MissingVariableError: missing template variable: 'name'

XML-escaped by default, single-pass, strict about every variable.

Without beacon

for attempt in range(5):
    try:
        return client.chat.completions.create(...)
    except Exception:
        time.sleep(2 ** attempt + random.random())
# retries auth errors too; delays differ on every run,
# so two logs of the "same" failure never match

Retry policy by guesswork; randomness makes runs incomparable.

With beacon

decision = retry.classify(exc, attempt=n, policy=POLICY)
# RetryDecision(action=RETRY, reason=RATE_LIMIT,
#               delay_seconds=1.848, ...)
# auth / bad-request errors: action=FAIL, no wasted calls.
# jitter = blake3(jitter_key, attempt): same failure,
# same delay, every run.

Typed decisions, Retry-After aware, deterministic jitter.

The contract

Four guarantees, in writing.

"Deterministic" is easy to claim. beacon publishes the contract, and its test suite checks it against 111 golden files on three operating systems.

Pure functions

No hidden state, no caches, no clock, no environment variables, no randomness. The first call returns exactly what the thousandth does.

Stable on every machine

Byte-identical output across Linux, macOS and Windows, Python 3.10–3.14, CPU architectures and locales. Positions count code points, never bytes.

Errors are API

Every error has a stable code and message. Patch releases never change output, so snapshot tests of error behaviour keep passing.

Fails loudly

No repair modes. No trailing-comma guessing, no type coercion, no ignored schema keywords. If it is wrong, you find out where.

Read the full determinism contract →

Building blocks

Eight blocks. One contract.

Plain functions written in Rust, not a framework. Use one, or all eight. Every block has its own edge-case test suite and golden snapshots.

template

Prompt rendering that escapes input and refuses missing or unused variables.

template("<msg>{m}</msg>", m="</msg>hi")
→ '<msg>&lt;/msg&gt;hi</msg>'

extract_json

Finds the JSON in fences or prose. Strict parsing, exact error positions.

extract_json('Sure! {"a": 1} Done.')
→ {'a': 1}

parse_tool_call

Hermes, Mistral, Llama, OpenAI, Anthropic, XML and Python call syntax.

parse_tool_call('search(q="rust", n=5)')
→ {'name': 'search', 'arguments': {...}}

validate_schema

JSON Schema with stable messages, a fixed error order and no coercion.

validate_schema({"n": "5"}, schema)
→ /n: expected type "integer", got "string"

normalize

NFKC, whitespace, zero-width and control-character cleanup, locale-independent.

normalize("Café\u200b  CRÈME", strip_accents=True)
→ 'Cafe CREME'

hash_content

Type-aware BLAKE3 hashes. Dict key order never matters.

hash_content({"b": 2, "a": 1})
→ same as hash_content({"a": 1, "b": 2})

redact

Emails, phones, Luhn-checked cards, API keys, JWTs, private keys, IPs.

redact("mail a@b.co, key sk-proj-…")
→ 'mail [REDACTED:email], key [REDACTED:api_key]'

retry

Typed retry-or-fail decisions with deterministic, Retry-After-aware backoff.

retry.classify(RateLimitError(...))
→ RetryDecision(action=RETRY, ...)

Live playground

Try the real engine. In your browser.

This isn't a mock. beacon's Rust core is compiled to WebAssembly and runs right here, the same code the Python package runs. Break the JSON, hit Run 1,000×, and count the unique outputs.

Paste raw model output. beacon finds the JSON in fences or prose, or tells you exactly where it is broken.

LLM outputselectkind

Output

Loading beacon's Rust core (WebAssembly)…

IdleSame Rust core as the Python package, compiled to WebAssembly

Open the full-screen playground →

Snapshot testing

Test LLM apps like normal code.

Model output isn't deterministic. What your code does with a given output is. Record a response once and snapshot your parsing, validation and routing. Every behaviour change then shows up as a readable diff in review.

First run writes, later runs compare byte for byte.
CI fails on missing or changed snapshots, on Linux, macOS and Windows.
Errors are snapshottable: type, code, message, position.
One command to accept intended changes: python -m beacon.snapshots update

Snapshot testing guide →

tests/test_intents.py

from beacon import extract_json
from beacon.snapshots import assert_snapshot

def test_cancel_intent():
    raw = load_fixture("cancel.txt")     # a recorded model response
    result = extract_json(raw, schema=INTENT)
    assert_snapshot("intents/cancel", result, input=raw, schema=INTENT)

snapshots/intents/cancel.yaml+6 −3

 # beacon snapshot v1 name: intents/cancel input: |-   Sure! ```json   {"intent": "cancel", "confidence": 0.93}   ``` value:-  intent: cancel+  intent: cancellation   confidence: 0.93 schema_validation:-  passed: true-  errors: []+  passed: false+  errors:+    - path: "/intent"+      keyword: enum

✕ SnapshotMismatchError: snapshot 'intents/cancel' does not match. Run python -m beacon.snapshots update if the change is intended.

Performance

Microseconds, not milliseconds.

The blocks are compiled Rust, so they barely touch your latency budget. The project's target is under 0.5 ms per call, and every block comes in around 50× under it. Determinism doesn't have to cost anything.

50×headroom under the
0.5 ms per-call budget

median per callµs

template

1.2

parse_tool_call

1.2

retry.classify

2.0

hash_content

2.2

extract_json

2.5

normalize

5.8

validate_schema

9.3

redact

10.2

Budget: 500 µs per call (≈ 40× the width of this chart)

Integrations

Works with the stack you already have.

Drop-in parsers and validators for the frameworks you use. Optional, lazily imported, and tested against the real libraries.

OpenAI SDKvalidated_completion()sync + async, tool calls LangChainBeaconJsonOutputParserparser, prompt, callbacks LlamaIndexBeaconOutputParserquery-engine output parsing Pydantic AIBeaconValidatorModelRetry with stable feedback DSPyBeaconJSONAdapterstrict adapter + validator

Get started

From install to a tested pipeline in five minutes.

1
Install
One abi3 wheel per platform covers Python 3.10 to 3.14. No Rust toolchain needed.
```
pip install llm-beacon
# optional integrations
pip install "llm-beacon[langchain]"
```

Wrap your model call

Render the prompt, call any LLM client, then extract and validate the result.

from beacon import template, extract_json

prompt = template("Classify: <m>{m}</m>", m=message)
raw = llm(prompt)                # any client
intent = extract_json(raw, schema=INTENT)

Lock it in with a snapshot

Record a real response once. From then on, any behaviour change shows up as a diff.

from beacon.snapshots import assert_snapshot

def test_cancel():
    assert_snapshot("intents/cancel",
                    extract_json(RECORDED, schema=INTENT))

Read the quickstart Core concepts

Same input.Same output.Every time.

LLM code is non-deterministic by accident.

Four guarantees, in writing.

Pure functions

Stable on every machine

Errors are API

Fails loudly

Eight blocks. One contract.

Try the real engine. In your browser.

Test LLM apps like normal code.

Microseconds, not milliseconds.

Works with the stack you already have.

From install to a tested pipeline in five minutes.

Install

Wrap your model call

Lock it in with a snapshot

Make the model theonly moving part.

Same input.
Same output.
Every time.

Make the model the
only moving part.