ReasonBlocksConfig: full configuration reference

Complete reference for the ReasonBlocksConfig dataclass — every tier toggle, token-saving lever, and routing field for assembling the full middleware stack.

ReasonBlocksConfig is a single dataclass that controls every ReasonBlocks capability. Instead of wiring individual middleware classes by hand, you fill in a config object and pass it to build_middleware(), which assembles the correct middleware stack in the right order automatically.

Complete example

from reasonblocks import ReasonBlocksAPI, ReasonBlocksConfig, build_middleware

api = ReasonBlocksAPI(api_key="rb_live_...")

config = ReasonBlocksConfig(
    # Tier toggles
    enable_e1=True,
    enable_e2=True,
    enable_e3=True,
    enable_monitor_steering=True,
    enable_general_monitor=False,
    enable_token_saving=True,
    enable_distillation=True,

    # Token-saving levers
    ts_compress_threshold_chars=1800,
    ts_keep_recent_tool_messages=2,
    ts_enable_early_exit=True,

    # General monitor levers
    gm_max_tool_calls=30,
    gm_cooldown=8,

    # Routing / scoping
    customer_id="acme",
    monitor_task_profile="coding",
)

middleware = build_middleware(
    config, api,
    score_fn=score_fn,
    fsm=fsm,
    state_manager=state_manager,
)

agent = create_agent(model=..., tools=..., middleware=middleware)

build_middleware() assembles the list in the correct order: ReasonBlocksMiddleware first, then GeneralMonitorMiddleware (if enabled), then TokenSavingMiddleware last so it compresses what earlier middleware injected before the LLM call goes out.

---

Tier toggles

These fields turn each major capability on or off.

enable_e1 · bool · default: "True"

Enable customer-scoped instance-level pattern injection. E1 retrieves the top-1 pattern from your customer’s pattern scope. Disable to stop E1 injections entirely without affecting E2, E3, or monitors.

enable_e2 · bool · default: "True"

Enable pattern-level injection keyed on the monitor state description. E2 retrieves patterns from the shared pattern store that match the current failure family detected by monitors.

enable_e3 · bool · default: "True"

Enable universal standing-rule injection. E3 fires on the first agent call of every run (scroll-all) to establish baseline guidance. Subsequent calls skip E3 unless the state changes.

enable_monitor_steering · bool · default: "True"

Enable server-side trajectory monitor evaluation. When fired, monitor results steer which E-trace tier retrieves and what gets injected into the system prompt.

enable_general_monitor · bool · default: "False"

Enable the v1 rule-firing general monitor pack. This opt-in pack runs five rule-based detectors (repeated attempts, error without diagnosis, exploration sprawl, idle response, low-novelty tail) with a per-rule cooldown. When enabled, GeneralMonitorMiddleware is inserted between ReasonBlocksMiddleware and TokenSavingMiddleware.

enable_token_saving · bool · default: "True"

Enable tool-output compression and the early-exit nudge. TokenSavingMiddleware is appended last in the stack so it compresses whatever earlier middleware has injected before the LLM call goes out.

enable_distillation · bool · default: "True"

Enable trace distillation. When True, the SDK submits completed session traces to the ReasonBlocks API at session end so new E1 patterns can be mined for future runs. Set to False to prevent trace data from this customer’s runs from being ingested — useful for staging environments or data-residency requirements.

---

Token-saving levers

These fields control how TokenSavingMiddleware compresses the message history and when it injects the early-exit nudge.

ts_compress_threshold_chars · int · default: "1800"

Character length above which a ToolMessage body is eligible for head+tail truncation. Tool messages shorter than this threshold are left untouched.

ts_head_keep_chars · int · default: "900"

Number of characters to keep from the beginning of a compressed tool message.

ts_tail_keep_chars · int · default: "700"

Number of characters to keep from the end of a compressed tool message. Combined with ts_head_keep_chars, the total kept content is at most 900 + 700 = 1600 chars plus an omission marker.

ts_keep_recent_tool_messages · int · default: "2"

Number of the most recent ToolMessage instances to leave uncompressed. The agent keeps full visibility into the step it is actively reasoning about.

ts_enable_compression · bool · default: "True"

Master toggle for tool-output head+tail compression. Set to False to disable compression while keeping the early-exit nudge active.

ts_enable_early_exit · bool · default: "True"

Enable the early-exit nudge. Once the agent has made at least ts_early_exit_min_call_index model calls, the middleware checks for loop-like signals (streak, hedge, diversity) and injects a HumanMessage telling the agent to stop and submit its current best answer.

ts_early_exit_min_call_index · int · default: "40"

Minimum number of model calls before the early-exit nudge can fire. Prevents premature exits on short runs.

---

Perplexity compression

Perplexity compression applies word-level keep/drop decisions to stale messages, going further than head+tail truncation. It is off by default and requires you to supply a WordClassifier callable.

ts_enable_perplexity_compression · bool · default: "False"

Enable LLMLingua-2-style word-level compression on stale messages. Requires ts_perplexity_classifier to be set. When the classifier is None, perplexity compression is silently skipped even if this flag is True.

ts_perplexity_classifier · WordClassifier | None · default: "None"

A WordClassifier callable with signature (list[str]) -> list[bool]. Each True in the output means the corresponding word is kept. Use reasonblocks.token_saving.make_anthropic_classifier to create a production classifier backed by Claude Haiku.

import anthropic
from reasonblocks.token_saving import make_anthropic_classifier

classifier = make_anthropic_classifier(
    client=anthropic.Anthropic(),
    model="claude-haiku-4-5-20251001",
    target_keep_ratio=0.5,
)

config = ReasonBlocksConfig(
    ts_enable_perplexity_compression=True,
    ts_perplexity_classifier=classifier,
)

ts_perplexity_recent_cutoff · int · default: "3"

Messages within the last N model calls keep full fidelity — perplexity compression does not touch them. Calls 0 through N-1 back are in the “recent” tier.

ts_perplexity_mid_cutoff · int · default: "10"

Messages between ts_perplexity_recent_cutoff and this cutoff use the mid keep ratio. Messages older than this cutoff use the old keep ratio.

ts_perplexity_keep_ratio_mid · float · default: "0.55"

Target word-keep ratio for messages in the mid tier. A value of 0.55 means roughly 55% of words in mid-tier messages are retained.

ts_perplexity_keep_ratio_old · float · default: "0.30"

Target word-keep ratio for old-tier messages (older than ts_perplexity_mid_cutoff calls). More aggressive than the mid ratio.

ts_perplexity_window_words · int · default: "50"

Number of words per classifier window. Smaller windows produce finer-grained decisions at the cost of more classifier API calls. Larger windows are coarser but cheaper.

---

General monitor levers

These fields apply only when enable_general_monitor=True.

gm_max_tool_calls · int · default: "30"

Total tool-call budget for the general monitor. Several detectors (exploration sprawl, idle response, low-novelty tail) use this as the reference limit for their proportional thresholds.

gm_cooldown · int · default: "8"

Minimum number of model calls between firings of the same rule. Prevents repeated injections from the same detector on consecutive steps.

---

Routing and scoping

customer_id · str | None · default: "None"

Customer identifier used by E1 retrieval to narrow pattern search to this customer’s scope. When None, E1 retrieves from the global pattern store. Set this to the same customer identifier you use in your user database — for example, your tenant ID or organization slug.

monitor_task_profile · str · default: "\"coding\""

Server-side monitor weight profile. Built-in values are "coding" (default), "pr_review", and "qa". Each profile shifts which monitors are weighted most heavily. See monitor weight profiles for the exact weight differences between profiles.

monitor_weights · dict[str, float] | None · default: "None"

Optional per-monitor weight override applied on top of the profile. Partial dicts are accepted — monitors not listed fall through to the profile, then to server defaults. Unknown monitor names are dropped server-side, and negative weights are clamped to 0.

# Boost loop-detection sensitivity and reduce hedging weight
config = ReasonBlocksConfig(
    monitor_task_profile="coding",
    monitor_weights={"streak": 0.5, "hedge": 0.05},
)