Skip to content

Stepfork v0.1.0a2 - First PyPI Alpha

Stepfork is now available on the Python Package Index. This is the first alpha distribution published with GitHub Actions trusted publishing (OpenID Connect), with no stored API token.

What is Stepfork

Stepfork turns a failed AI-agent run into a reproducible pytest regression test. It records what your agent did, replays it with instrumented dependencies frozen, diffs corrected behavior against the recording, and exports an executable test. Everything runs locally; trace data is not sent anywhere.

What's included

  • Typed .sftrace trace bundles
  • Recording of agent executions
  • Tool and LLM boundary instrumentation
  • Local inspection and structural validation
  • Best-effort secret redaction
  • SHA-256 integrity verification
  • Frozen replay of instrumented tool/LLM boundaries
  • Behavioral diffing
  • Executable pytest regression-test export
  • A command-line interface (stepfork)

Installation

pip install --pre stepfork

The --pre flag is required while Stepfork is a pre-release. Requires Python 3.11, 3.12, or 3.13.

Installing from the GitHub tag remains available as an alternative:

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

Quickstart

stepfork --version
stepfork --help

Runnable, fully offline examples ship in the repository (examples/quickstart, examples/booking_agent, examples/refund_agent). Each records a 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.

Supported Python versions

Python 3.11, 3.12, and 3.13. Continuous integration runs the full test suite on all three.

Known limitations

  • Alpha API and schema may change before v1.0.
  • Manual instrumentation is required; only instrumented boundaries are frozen.
  • No universal framework integration yet.
  • Frozen replay is not a sandbox and does not isolate arbitrary code.
  • Redaction is best-effort; do not rely on it for regulated data.
  • Not all agent behaviors can be deterministically replayed.
  • No automatic failure minimization.

Upgrade guidance

When a newer alpha is published, use:

pip install --pre --upgrade stepfork

Versions are published under PEP 440 pre-release identifiers (0.1.0aN) and are immutable on PyPI; a broken release is yanked and replaced by a new version, not overwritten.

Security considerations

  • Packages are built and uploaded by GitHub Actions with id-token: write scoped to the pypi environment; no long-lived PyPI token exists.
  • The publishing workflow runs only for a published GitHub Release whose tag matches src/stepfork/version.py.
  • Frozen replay does not sandbox untrusted code, and bundle integrity is not verified by default on replay/export. See the security documentation.

Feedback

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.