StatePlane SDK

stateplane is the supported customer-facing package.

If you are new to it, start with:

• Getting Started
• OpenAI Parameter Tutorial

This page is the parameter map. It tells you where each public argument lives and where to see it in action.

Primary Onboarding Surface

The shortest supported path is still:

from stateplane import StatePlaneSession

session = StatePlaneSession(...)
prepared = session.transform(
    task_summary="...",
    messages=messages,
)

Main Imports

• StatePlaneSession
• MessageInput
• ToolCallInput
• ToolResultInput
• ToolEvidenceInput
• RetrievedContextInput
• build_compilation_request()
• prepare_openai_request()
• run_openai_request()

Session Constructor Parameters

Parameter	What it controls	See it in the tutorial
provider	target provider identity	Baseline
model	default model name	Baseline
token_budget	total prompt budget	Baseline
response_reserve	output budget reserved for the model	Baseline
instructions	persistent developer instructions	Persistent Instructions
constraints	must-keep hard rules	Hard Constraints
tool_specs	tool metadata on the request boundary	Advanced Appendix
memory_records	attached memory records	Advanced Appendix
policy_rules	attached policy rules	Advanced Appendix
compile_config	low-level compile config payload	Advanced Appendix

build() / transform() Parameters

Parameter	What it controls	See it in the tutorial
task_summary	task framing for compilation and rendering	Baseline
messages	transcript and inline tool events	Baseline and Transcript Tool Events
instructions	per-call instructions appended after session defaults	Persistent Instructions
constraints	per-call constraints appended after session defaults	Hard Constraints
retrieved_context	supplemental retrieved snippets	Retrieved Supplemental Context
tool_evidence	supplemental machine evidence outside the transcript	Supplemental Machine Evidence
model	preparation-time model override on transform()	Staged vs One-Shot Flow

Advanced Parameters

Parameter	What it controls	See it in the tutorial
user_message	bucket-mode input when you do not have a transcript	Advanced Appendix
extra_context_items	pre-normalized ContextItems injected directly	Advanced Appendix
request_id	stable request identity	Advanced Appendix
run_id	stable run identity	Advanced Appendix
step_id	stable step identity	Advanced Appendix
created_at	builder-level timestamp fallback	Advanced Appendix
build_compilation_request(...)	stateless bucket-mode helper	Advanced Appendix

Output Checklist

When you are trying to understand what a parameter changed, inspect outputs in this order:

1. prepared.request
2. prepared.compilation_report
3. prepared.rendered_request
4. optional live answer

The tutorial follows that same order in every step:

• what the argument means
• what changed in prepared.request
• what changed in receipts
• what changed in the OpenAI payload
• what may change in the live answer

Minimal Example

If you want the shortest copy-paste example instead of the walkthrough:

• OpenAI Context Demo

Structured Stateful Workflow

If you want the flagship stateful path, start with:

• Structured Coding-Agent State with OpenAI

That workflow uses the same StatePlaneSession surface, but through the additive stateful APIs:

from stateplane import StatePlaneSession

session = StatePlaneSession.local(
    ".stateplane/demo.db",
    session_id="repo-maintainer-demo",
    token_budget=8000,
)
session.record_goal(title="Fix parser and CLI failures", run_id="run-1")
session.record_user_constraint(
    key="edit_tests",
    value=False,
    text="Do not edit tests.",
    strength="hard",
    run_id="run-1",
)
projection = session.coding_projection()
snapshot_text = session.explain_snapshot(current_goal="Now fix the related CLI failure.")
request = session.prepare_openai_request(
    model="gpt-5-mini",
    instructions="You are a careful repo-maintenance agent.",
    user_input="Now fix the related CLI failure.",
    run_id="run-2",
)

The important additive methods are:

• StatePlaneSession.local(...)
• record_goal(...)
• record_user_constraint(...)
• record_test_run(...)
• record_file_patch(...)
• record_decision(...)
• record_procedure(...)
• record_risk(...)
• coding_projection()
• replay_coding_projection(...)
• explain_snapshot(...)
• prepare_openai_request(...)

Replay and Artifact Workflow

If you want to inspect what changed between runs instead of only preparing the next request, the same session surface now supports:

• start_run(...)
• complete_run(...)
• fail_run(...)
• list_runs()
• replay(...)
• replay_counterfactual(...)
• diff_runs(...)
• diff_events(...)
• export_run_artifacts(...)

That workflow is shown in:

• Replay and Diff a Coding-Agent Run