SemanticRun

Temporal replays code. LangGraph orchestrates graphs.
SemanticRun freezes what your agent already committed — and resumes with proof of what drifted.

Python 3.11+ License: MIT PyPI Status

Artifact-aware durable agent environment for Python.
Survive crashes, human waits, model swaps, and tool drift — without redoing completed work or silently replaying side effects.

from semanticrun import SemanticRun, PolicyMapping

env = SemanticRun.open("./runs.db")

run = env.start(
    intent="Onboard lead_42",
    plan=["research", "draft", "approve", "send"],
    policies=PolicyMapping(
        tool_result_hash_mismatch="revalidate",
        model_id_changed="fail_fast",
        outbound_payload_divergence="fail_fast",
    ),
)

for step in run.steps():  # completed steps skipped on resume
    if step.name == "research":
        lead = step.tool("crm_lookup", lambda: crm.lookup("lead_42"),
                         hash_exclude=["created_at"])
    elif step.name == "draft":
        draft = step.llm(lambda: llm.draft(lead), model="gpt-4.1")
        step.remember("draft_email", draft)
    elif step.name == "approve":
        step.require_approval("send_email", {"draft": draft})
    elif step.name == "send":
        step.tool("send_email", lambda: mail.send(draft),
                  side_effect="external",
                  outbound={"to": lead["email"], "body": draft})

run = env.resume(run_id, artifacts=...)  # matrix + policies; cursor continues

Day-one proof: drift recovery

Pause an agent mid-run, inject drift, resume three ways.
Suite: benchmarks/drift_recovery/ (OpenRouter free models when OPENROUTER_API_KEY is set; deterministic stub otherwise).

Drift injected Naive restart Blind resume SemanticRun
Model ID swap continues blind continues blind abort (model_id_changed)
File edit while waiting continues blind continues blind abort (file_tree_hash_mismatch)
Tool schema change continues blind continues blind revalidate
Tool result drift continues blind continues blind revalidate
Re-synthesized outbound re-sends re-sends abort (outbound_payload_divergence)

Score (5/5 scenarios): naive restart safe 0/5 · blind resume safe 0/5 · SemanticRun safe 5/5

That is the visceral loop Temporal had for distributed systems: feel the failure, then watch the environment refuse it. Papers describing the failure mode are not the product proof — this suite is.

python benchmarks/drift_recovery/run_suite.py

Why SemanticRun

Temporal LangGraph SemanticRun
Core idea Replay workflow code Orchestrate agent graphs Diff committed artifacts on resume
Durability Event history Checkpointers Sync checkpoints + plan cursor
Drift (tools / models / files) App-level App-level Divergence matrix + enforced policies
Side effects Activity semantics App-managed Outbound payload hash gate

Not a Temporal or LangGraph plugin — the environment your agent runs in when the question is “what already happened, and is it still true?”

Install

pip install SemanticRun

# from source:
pip install -e ".[dev]"
pytest
python examples/survive_the_swap.py

What you get

  • Durable plan cursor — run.steps() skips finished work after resume
  • Sync checkpoints — written before the step returns (SQLite)
  • Divergence matrix — mechanical diffs; no LLM guessing
  • Enforced policies — fail_fast / revalidate / strict_reset
  • Outbound replay gate — refuse divergent external side effects

License

MIT

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for rockybalboan19 from gravatar.com rockybalboan19

Credits

Author: ysharmcode

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

dev

Tags

agents checkpointing durable-execution semanticrun

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

semanticrun-0.4.2.tar.gz (212.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

semanticrun-0.4.2-py3-none-any.whl (35.8 kB view details)

Uploaded Python 3

File details

Details for the file semanticrun-0.4.2.tar.gz.

File metadata

  • Download URL: semanticrun-0.4.2.tar.gz
  • Upload date:
  • Size: 212.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for semanticrun-0.4.2.tar.gz
Algorithm Hash digest
SHA256 51a5cafd8f8f6c0e64705cef56debeebfd47df1230f83b65be4f57da49dcd637
MD5 7a241c00bfa16e2eae85709e36e7538c
BLAKE2b-256 74bd9e66da10cbfc60b0c99834baa9b4f4c1635e91f903798a352d27ea49e48a

See more details on using hashes here.

Provenance

The following attestation bundles were made for semanticrun-0.4.2.tar.gz:

Publisher: publish.yml on rockybalboan19/SemanticRun

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file semanticrun-0.4.2-py3-none-any.whl.

File metadata

  • Download URL: semanticrun-0.4.2-py3-none-any.whl
  • Upload date:
  • Size: 35.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for semanticrun-0.4.2-py3-none-any.whl
Algorithm Hash digest
SHA256 f0e501fc4e7950e031fa1084baa8c939f78a6a0e31caec7ac1c009a9fe923424
MD5 7b4f39c92e63985a089eaf2575b8e230
BLAKE2b-256 907e66ac2b19c096ed4c1cddfbf05b700381a0fa75d1c09986b73d3c9e6f0e05

See more details on using hashes here.

Provenance

The following attestation bundles were made for semanticrun-0.4.2-py3-none-any.whl:

Publisher: publish.yml on rockybalboan19/SemanticRun

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.4.2 This release

2 files

0.4.1

2 files

0.4.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page