Quickstart

From install to a priced cost graph in five minutes. The demo costs $0 and needs no API key.

1. Install

pip install stepcost              # Python ≥ 3.11 · one dependency (pydantic)
pip install "stepcost[langchain]"  # optional: LangChain/LangGraph integration

2. Run the demo agent ($0)

The quickstart instruments a three-step agent (plan → retrieve → execute) with simulated token usage — no API calls, no spend:

curl -sO https://raw.githubusercontent.com/bronette/stepcost/main/sdk/python/examples/quickstart.py
python quickstart.py
trace total: $0.0152
by step:     {'plan': 0.000288, 'retrieve': 0.00016, 'execute': 0.01475}

3. Render the report

stepcost report ~/.stepcost/quickstart.db

You get the account summary (by feature, by customer, by kind, top traces, waste flags), and --trace <id> renders the per-run cost tree with per-node tokens and dollars. See Report CLI & sync for the full anatomy.

4. Instrument your own agent

Two context managers and one record() call:

from stepcost import StepCost, agent_step, llm_call

cc = StepCost(project="my-app", sink="sqlite:///~/.stepcost/my-app.db")

with cc.trace(feature_id="support-bot", customer_id="acme") as trace:
    with agent_step("answer"):
        with llm_call(model="gpt-4o-mini", provider="openai") as call:
            response = openai_client.chat.completions.create(...)
            call.record(response)   # invoice-safe token + $ extraction

print(trace.total_usd, trace.by_step)

trace(...) opens a run and carries your business dimensions (feature_id, customer_id, team_id, ...).
agent_step("name") marks a logical step — costs of everything inside roll up to it.
call.record(response) extracts usage from OpenAI (Chat Completions, Responses API, embeddings) and Anthropic response objects. No extractor for your provider? Use call.record_usage(input_tokens=..., output_tokens=...).

Already on LangChain, LangGraph, or LiteLLM — or calling the OpenAI/Anthropic SDKs directly? You don't need any of the above: one callback or wrapper instruments everything with zero code changes per call site.

5. Durability, for free

No flush() calls needed: spans persist when each trace exits and again at process exit. Sink failures re-queue instead of dropping. Concurrent asyncio agents under one trace keep correct parent/child attribution.

6. Optional: reconcile against your real bill

With an organization admin key, pull what your provider says it will bill into the same database and get drift + coverage on every report:

export ANTHROPIC_ADMIN_KEY=sk-ant-admin01-...
stepcost sync anthropic ~/.stepcost/my-app.db --days 7
stepcost report ~/.stepcost/my-app.db

Details in Report CLI & sync.

← Overview Integrations →