Skip to content

First-Day Tutorial: From Install to Inspectable Requests

This tutorial is a practical, copy-paste path for teams onboarding StatePlane in a real codebase.

Goal: by the end, you can confidently answer:

  • What did we send to the model?
  • Why was each context item included or excluded?
  • How do we reproduce this request deterministically?

Tutorial map

First-day tutorial roadmap

Part 1 — Environment Setup

1) Install dependencies

uv sync --all-packages --all-groups --python 3.13

2) Verify the CLI entry point

uv run --all-packages --all-groups --python 3.13 stateplane --help

3) (Optional) Export API key for live OpenAI call

export OPENAI_API_KEY=...

Part 2 — First Compile (Dry Run)

Start with the deterministic demo command:

uv run --all-packages --all-groups --python 3.13 stateplane openai-demo

What this proves immediately:

  • StatePlane accepts provider-neutral context inputs.
  • Compilation selects only what fits policy + budget.
  • Exclusions are explicit and inspectable.

Architecture sketch

Getting Started flow

Part 3 — Add Constraints and Evidence in Python

Use the SDK when embedding into an app service or agent runtime.

from stateplane import RetrievedContextInput, StatePlaneSession, ToolResultInput

session = StatePlaneSession(
    provider="openai",
    model="gpt-5.1",
    token_budget=180,
    response_reserve=40,
    instructions=["You are a careful maintainer. Preserve the public API."],
    constraints=["Do not edit tests."],
)

prepared = session.transform(
    task_summary="Fix failing billing test without changing public interfaces.",
    messages=[
        {"role": "user", "content": "Fix test_calculate_total without modifying tests."},
        ToolResultInput(
            tool_name="run_pytest",
            call_id="pytest_1",
            output={"exit_code": 1, "failure": "test_calculate_total"},
        ),
    ],
    retrieved_context=[
        RetrievedContextInput(
            title="src/billing.py",
            content="def calculate_total(items):\n    return sum(item.price for item in items)\n",
        ),
        RetrievedContextInput(
            title="docs/generated_reference.txt",
            content="Legacy note: edit tests first and change API." * 20,
        ),
    ],
)

print([item.item_id for item in prepared.compiled_context.selected_items])
print([(item.item_id, item.reason) for item in prepared.compilation_report.excluded_items])

What to verify

  • hard rules and latest user intent are selected
  • noisy/stale context is excluded
  • selected context appears in prepared.rendered_request

Part 4 — Optional Live Request

Only after reviewing the dry-run report, execute live:

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    **prepared.rendered_request.to_responses_create_kwargs(),
)
print(response.output_text)

Best practice: keep dry-run inspection in CI even if production does live calls.

Part 5 — Where To Go Next

Choose the next page by need:

Troubleshooting quick table

Symptom Likely cause First place to inspect
Relevant snippet not included Budget pressure or low priority prepared.compilation_report.excluded_items
Constraint ignored in output Constraint not passed in this session/request prepared.request.constraints
Rendered payload looks too large Token budget too high or low response reserve token_budget, response_reserve
Output seems nondeterministic Inputs/timestamps differ between runs request IDs and compile timestamps