Installation

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",
)

str

required

Your ReasonBlocks API key. The SDK does not auto-read it from the environment.

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.

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.

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.

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=...).

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.

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.

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.

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

Variable	Read by	Effect
`REASONBLOCKS_BASE_URL`	`reasonblocks._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_TIMEOUT`	`reasonblocks._settings` (at import time)	HTTP timeout in seconds for the underlying clients. Defaults to `10.0`.
`REASONBLOCKS_API_KEY`	Not 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.

Getting Started

Concepts

Using ReasonBlocks

Connectors and sync

Requirements

Install the package

Optional dependencies

API key

Constructor parameters

Environment variables

Self-hosted deployments

Verify your installation

​Requirements

​Install the package

​Optional dependencies

​API key

​Constructor parameters

​Environment variables

​Self-hosted deployments

​Verify your installation

Requirements

Install the package

Optional dependencies

API key

Constructor parameters

Environment variables

Self-hosted deployments

Verify your installation