Skip to content

Stepfork v0.1.0a4 - Replay Hardening, OpenAI SDK, and LangGraph Alpha

This alpha tightens frozen replay correctness and adds the first two optional integration adapters: a minimal OpenAI Python SDK wrapper for synchronous, non-streaming chat completions, and a LangGraph adapter for synchronous chat models and function-based tools.

Highlights

  • Stricter replay matching for instrumented tool and LLM calls.
  • Clear divergence errors for stale recordings, changed prompts, changed models, changed request parameters, extra calls, and missing calls.
  • Recorded LLM/provider exceptions replay as recorded dependency failures.
  • Optional OpenAI Python SDK adapter installed with stepfork[openai].
  • Offline OpenAI example that records, replays, diffs, exports pytest tests, and verifies buggy-vs-fixed behavior without an API key or network call.
  • Optional LangGraph adapter installed with stepfork[langgraph], wrapping a BaseChatModel and function-based tools through explicit, instance-scoped wrappers (traced_chat_model, traced_tool).
  • Offline LangGraph example and a committed regression fixture that replay with zero model and tool executions, and no API key or network call.

Installation

pip install --pre stepfork

Install an extra only when you use that adapter:

pip install --pre "stepfork[openai]"
pip install --pre "stepfork[langgraph]"

Requires Python 3.11, 3.12, or 3.13. The package metadata declares >=3.11,<3.14.

Installing from the GitHub tag remains available as an alternative:

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

OpenAI Adapter Scope

Supported:

  • Explicit wrapper: stepfork.integrations.openai.chat_completions_create(client, **request)
  • Synchronous client.chat.completions.create(**request) call shape.
  • Non-streaming requests.
  • JSON-compatible request parameters and response payloads.
  • Frozen replay that returns the recorded response without invoking the SDK client.

Not supported yet:

  • Streaming responses.
  • Async clients.
  • Responses API.
  • OpenAI Agents SDK.
  • Automatic monkeypatching of existing SDK clients.
  • Non-JSON request parameters or response objects.

OpenAI request payloads, including message content, are recorded in the local .sftrace bundle as part of replay identity. Existing Stepfork redaction runs before persistence, but redaction is best-effort; do not place secrets in prompts, metadata, tool parameters, or custom request fields.

LangGraph Adapter Scope

Supported:

  • Synchronous BaseChatModel generation through stepfork.integrations.langgraph.traced_chat_model.
  • Function-based tools (plain functions, decorator form, or an existing BaseTool that exposes a func) through stepfork.integrations.langgraph.traced_tool.
  • Frozen replay that returns recorded model and tool outputs without executing the model, the tool body, or any remote endpoint.
  • Explicit, instance-scoped wrapping; no global monkeypatching.

Not supported yet:

  • Asynchronous invocation (ainvoke / _agenerate) inside a Stepfork context.
  • Streaming responses.
  • Retrievers, checkpointers, and arbitrary Runnable steps that are not explicitly wrapped.
  • Non-JSON tool return values without an explicit serializer=.

Model inputs (message content and tool arguments) are recorded in the local .sftrace bundle as part of replay identity. Stepfork's redaction runs before persistence, but redaction is best-effort; do not place secrets in prompts, metadata, or tool parameters.

Replay Correctness

Frozen replay now compares the next live instrumented call against the next recorded dependency call. It checks call kind, ordering, tool name or LLM provider/model identity, and normalized input fingerprints. Divergence is reported explicitly rather than reusing stale recorded output.

Legacy recordings remain loadable where practical. If a legacy bundle lacks the metadata required for strict validation, Stepfork reports that limitation instead of silently accepting incomplete evidence.

Verification

The release candidate was checked with:

  • Ruff lint and format checks.
  • MyPy strict checks.
  • Full pytest suite with coverage.
  • Package build.
  • Local wheel and sdist installation smoke tests, with and without the optional extras.
  • All five bundled demos: quickstart, booking_agent, refund_agent, openai_chat, and langgraph_agent.

Upgrade Guidance

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.

Feedback

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

License

Apache License 2.0.