Skip to content

Stepfork v0.1.0a1 - First Public Alpha

Introducing Stepfork

Stepfork turns a failed AI-agent run into a reproducible pytest regression test. It records what your agent did, replays it with dependencies frozen, diffs corrected behavior against the recording, and exports executable tests. All of it runs locally, without sending trace data anywhere.

What's included

  • Typed .sftrace trace bundles
  • Recording of agent executions
  • Tool and LLM boundary instrumentation
  • Local inspection
  • Structural validation
  • Best-effort secret redaction
  • SHA-256 integrity verification
  • Frozen dependency replay
  • Behavioral diffing
  • Executable pytest regression-test export

Demonstrations

Fully offline examples ship in the repository:

  • Quickstart - a single-tool order-notification agent and the minimal starting point.
  • Booking agent - a flight-search agent that books the wrong flight.
  • Refund agent - a refund-eligibility agent that denies an eligible refund.

Each demo records the buggy run, freeze-replays it without executing the external tool, diffs it against a corrected run, and exports a pytest regression test that fails on the buggy entrypoint and passes after the fix - a failure turned into a test, step for step.

Installation

Stepfork is not on PyPI for this alpha. Install from GitHub:

pip install "git+https://github.com/utsab345/stepfork.git@v0.1.0a1"

Or with uv:

uv pip install "git+https://github.com/utsab345/stepfork.git@v0.1.0a1"

Requires Python 3.11, 3.12, or 3.13.

Quickstart

Clone the repository and run a demo:

git clone https://github.com/utsab345/stepfork.git
cd stepfork
uv sync
uv run python examples/refund_agent/demo.py

Known limitations

  • Alpha API and schema may change before v1.0.
  • Manual instrumentation is required for supported boundaries.
  • No universal framework integration yet.
  • Frozen replay is not a sandbox.
  • Redaction is best-effort.
  • Not all agent behaviors can be deterministically replayed.
  • No automatic failure minimization yet.

Feedback and contributions

Found a bug or a trace that does not behave as expected? Open an issue with a reproducible example:

https://github.com/utsab345/stepfork/issues

License

Apache License 2.0.