> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the ReasonBlocks SDK from PyPI and configure the client. Covers every constructor parameter, environment variables, and self-hosted deployments.

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

```bash theme={null}
pip install reasonblocks
```

To pin a specific version:

```bash theme={null}
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:

```bash theme={null}
pip install networkx
```

<Note>
  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.
</Note>

For local development:

```bash theme={null}
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](https://app.reasonblocks.com). Keys start with `rb_live_`.

<Warning>
  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.
</Warning>

```python theme={null}
import os
from reasonblocks import ReasonBlocks

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

## Constructor parameters

```python theme={null}
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",
)
```

<ParamField path="api_key" type="str" required>
  Your ReasonBlocks API key. The SDK does not auto-read it from the environment.
</ParamField>

<ParamField path="base_url" type="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.
</ParamField>

<ParamField path="token_budget" type="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.
</ParamField>

<ParamField path="fsm_thresholds" type="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](/concepts/fsm-states).
</ParamField>

<ParamField path="model_routing" type="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=...)`.
</ParamField>

<ParamField path="e_traces_enabled" type="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.
</ParamField>

<ParamField path="live_streaming_enabled" type="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.
</ParamField>

<ParamField path="task_profile" type="str" default="&#x22;coding&#x22;">
  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](/configuration/monitor-profiles) for the per-profile weight tables.
</ParamField>

<ParamField path="monitor_names" type="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.
</ParamField>

## 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`:

```python theme={null}
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

```bash theme={null}
python -c "import reasonblocks; print('ReasonBlocks installed')"
```

To check that constructor wiring is intact:

```python theme={null}
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.