Skip to main content
ReasonBlocks is a standard Python package on PyPI. Installation is one pip command. This page covers requirements, the full constructor signature, and the environment variables involved.

​
Requirements

  • Python 3.10 or later
  • langchain>=1.0
  • httpx>=0.27
Both langchain and httpx are declared as required dependencies and install automatically.

​
Install the package

pip install reasonblocks
To pin a specific version: 
pip install "reasonblocks==0.1.0"

​
Optional dependencies

ImportGraph (Python import graph + blast-radius queries) requires networkx, which is not installed automatically. If you plan to use ImportGraph, install it separately: 
pip install networkx
The middleware, CodebaseMemory, E-trace injection, and the local monitor suite have no dependency on networkx. You only need it if you call ImportGraph directly.
For local development: 
pip install "reasonblocks[dev]"

​
API key

The SDK requires an API key to authenticate with the ReasonBlocks API. Get yours from the Quickstart page in the ReasonBlocks dashboard. Keys start with rb_live_.
The ReasonBlocks constructor does not read REASONBLOCKS_API_KEY from the environment. You must pass api_key explicitly. Storing the key in an env var is still recommended — your code reads it.
import os
from reasonblocks import ReasonBlocks

rb = ReasonBlocks(api_key=os.environ["REASONBLOCKS_API_KEY"])

​
Constructor parameters

from reasonblocks import ReasonBlocks

rb = ReasonBlocks(
    api_key="rb_live_...",
    base_url="https://your-rb-api-host.example.com",
    token_budget=100_000,
    fsm_thresholds={
        "fast_threshold": 0.2,
        "slow_threshold": 0.6,
        "skip_threshold": 0.85,
    },
    model_routing={
        "FAST":   "anthropic:claude-haiku-4-5-20251001",
        "NORMAL": "anthropic:claude-sonnet-4-6",
        "SLOW":   "anthropic:claude-sonnet-4-6",
        "SKIP":   "anthropic:claude-sonnet-4-6",
    },
    e_traces_enabled=True,
    live_streaming_enabled=True,
    task_profile="coding",
)
​
api_key
str
required
Your ReasonBlocks API key. The SDK does not auto-read it from the environment.
​
base_url
str | None
default:"None"
Override the rb-api origin. When unset, the underlying HTTP clients fall back to the REASONBLOCKS_BASE_URL env var, then to the hosted production endpoint. Set this when running rb-api on a self-hosted host or locally.
​
token_budget
int | None
default:"None"
Maximum token count tracked per run. Tracked-only — the FSM does not transition to SKIP based on budget consumption; the value is exposed via TraceStateManager.get_budget_used() for callers that want to query it.
​
fsm_thresholds
dict[str, float] | None
default:"None"
Override DifficultyFSM thresholds. Recognized keys: fast_threshold, slow_threshold, skip_threshold, hysteresis_margin, fast_window, slow_window, skip_window. Unspecified values keep their defaults. See FSM states.
​
model_routing
dict[str, str] | None
default:"None"
Map FSM state names ("FAST", "NORMAL", "SLOW", "SKIP") to model identifiers. When the middleware enters a state with a mapping, it overrides the model for that step via request.override(model=...).
​
e_traces_enabled
bool
default:"True"
When False, E1/E2/E3 injections are not registered, so retrieval calls to rb-api never fire. The monitor steering injection still runs.
​
live_streaming_enabled
bool
default:"True"
Stream run_start / step / run_finish events to rb-api as the run unfolds. Set to False for offline mode — the local step_log still populates.
​
task_profile
str
default:"\"coding\""
Server-side monitor weight preset. Built-in profiles: coding (default), pr_review (tuned for read-only review agents), and qa (tuned for question-answering agents). The value is forwarded to /monitors/evaluate and to MonitorSteeringInjection. See Monitor profiles for the per-profile weight tables.
​
monitor_names
list[str] | None
default:"None"
Accepted for backward compatibility but currently a no-op. The built-in monitor suite runs server-side and ignores any local list. Custom monitors require a custom injection.

​
Environment variables

VariableRead byEffect
REASONBLOCKS_BASE_URLreasonblocks._settings (at import time)Default base URL for ReasonBlocksAPI, MonitorClient, and CodebaseMemory when base_url is not passed. Falls back to the hosted production endpoint.
REASONBLOCKS_API_TIMEOUTreasonblocks._settings (at import time)HTTP timeout in seconds for the underlying clients. Defaults to 10.0.
REASONBLOCKS_API_KEYNot read by the SDK.Pass it to ReasonBlocks(api_key=...) explicitly. Storing it in this env var and reading it from your own code is the conventional pattern.

​
Self-hosted deployments

If you run rb-api yourself, point the SDK at it via base_url: 
import os
from reasonblocks import ReasonBlocks

rb = ReasonBlocks(
    api_key=os.environ["REASONBLOCKS_API_KEY"],
    base_url=os.environ.get("REASONBLOCKS_BASE_URL", "http://localhost:9000"),
    e_traces_enabled=True,
)
When REASONBLOCKS_BASE_URL is not set, the underlying clients fall back to the hosted production endpoint baked into reasonblocks._settings.DEFAULT_BASE_URL.

​
Verify your installation

python -c "import reasonblocks; print('ReasonBlocks installed')"
To check that constructor wiring is intact: 
from reasonblocks import ReasonBlocks

rb = ReasonBlocks(api_key="rb_live_...")
mw = rb.middleware(agent_name="test")
print("Middleware created:", mw)
If no exception is raised, the install is healthy.