FSM states

DifficultyFSM tracks how hard your agent is working over the last several steps. After scoring a step, the FSM looks at the recent difficulty history and transitions between states that summarize the trajectory — coasting, working normally, struggling, or stalled for an extended window. The current state gates E-trace retrieval, sets monitor injection cooldowns, and selects the model when model_routing is configured.

States

State	Meaning	E-trace pipeline	Monitor cooldown
`INIT`	Starting state, before any step has been scored.	E3 only (first call).	n/a
`FAST`	Recent window is consistently easy.	Skipped entirely — no Qdrant, no embeddings.	every 5 steps
`NORMAL`	Default operating state.	Full E1 / E2 / E3 pipeline.	every 3 steps
`SLOW`	Recent window is consistently hard.	Full pipeline. Routes to mapped model if any.	every 2 steps
`SKIP`	High difficulty has persisted for a long window.	Same as `SLOW`.	every 2 steps
`END`	Defined in the enum but unreachable through the built-in transition function. Reserved for future use.	n/a	n/a

END is part of FSMState for forward compatibility but the shipped DifficultyFSM.transition never returns it. Treat it as inert today.

Defaults

DifficultyFSM is constructed with these defaults:

Parameter	Default	Purpose
`fast_threshold`	`0.2`	A step at or below this score counts as “easy”.
`slow_threshold`	`0.6`	A step at or above this score counts as “hard”.
`skip_threshold`	`0.85`	A step at or above this score counts toward the `SKIP` gate.
`hysteresis_margin`	`0.1`	Buffer applied when leaving `FAST` or `SLOW` to prevent oscillation.
`fast_window`	`6`	Number of consecutive easy steps required to enter `FAST` from `NORMAL`.
`slow_window`	`5`	Number of consecutive hard steps required to enter `SLOW` from `NORMAL`.
`skip_window`	`35`	Number of consecutive very-hard steps required to enter `SKIP` from `SLOW`.

Transition rules

From INIT: the very next scored step transitions to NORMAL. From NORMAL:

Enter FAST if the last fast_window (default 6) steps all scored strictly below fast_threshold (0.2).
Enter SLOW if the last slow_window (default 5) steps all scored strictly above slow_threshold (0.6).
Otherwise stay NORMAL.

From FAST:

Return to NORMAL if the current score exceeds fast_threshold + hysteresis_margin (0.3).
Otherwise stay FAST.

From SLOW or SKIP:

Return to NORMAL if the current score drops below slow_threshold - hysteresis_margin (0.5).
Enter SKIP from SLOW if the last skip_window (default 35) steps all scored strictly above skip_threshold (0.85).
Otherwise stay in the current state.

The hysteresis margin prevents the FSM from rapidly flipping when scores hover near a threshold. A single easy step does not exit SLOW — the score must drop meaningfully below the boundary.

What each state does

FAST skips the full E-trace pipeline. Monitor evaluation still runs (loop detection is most useful when the agent is moving fast and might miss that it’s looping). The monitor injection cooldown stretches to every 5 steps so guidance does not pile up on a healthy run. NORMAL runs the full pipeline: monitors evaluate server-side, E1 is queried if the gate allows it, E2 retrieves up to two patterns, and E3 fires only if it has not already (it fires once on step 0). SLOW runs the full pipeline and, if model_routing maps "SLOW" to a model, the request is overridden to that model. The cooldown shrinks to every 2 steps so guidance arrives more frequently. SKIP shares SLOW’s routing and cooldown. It surfaces in the dashboard as a separate state so you can distinguish brief difficulty from extended stalls.

Configuring thresholds

Pass any subset of the FSM parameters via fsm_thresholds. Unspecified values keep their defaults.

from reasonblocks import ReasonBlocks

rb = ReasonBlocks(
    api_key="rb_live_...",
    fsm_thresholds={
        "fast_threshold": 0.15,
        "slow_threshold": 0.65,
        "skip_threshold": 0.90,
        "hysteresis_margin": 0.08,
        "fast_window": 8,
        "slow_window": 4,
    },
)

Configuring model routing

model_routing is a separate dict keyed by FSM state name. Map any subset of "FAST", "NORMAL", "SLOW", "SKIP" to a model identifier; states without a mapping use whatever model the agent was created with.

rb = ReasonBlocks(
    api_key="rb_live_...",
    model_routing={
        "FAST": "anthropic:claude-haiku-4-5-20251001",
        "SLOW": "anthropic:claude-sonnet-4-6",
        "SKIP": "anthropic:claude-sonnet-4-6",
    },
)

A common pattern is to leave NORMAL on your default model, route FAST to a cheaper Haiku-class model, and route SLOW/SKIP to Sonnet-class. This concentrates compute budget on the steps where it matters.

What the FSM does not do

It does not transition to SKIP or any other state based on token_budget. The token budget is tracked-only and exposed via TraceStateManager.get_budget_used().
It does not advance to END on a final answer. The transition function never reaches END today.
It does not consume monitor signals. Monitor evaluation is independent of FSM state — both run on every scored step.

Getting Started

Concepts

Using ReasonBlocks

Connectors and sync

States

Defaults

Transition rules

What each state does

Configuring thresholds

Configuring model routing

What the FSM does not do

​States

​Defaults

​Transition rules

​What each state does

​Configuring thresholds

​Configuring model routing

​What the FSM does not do

States

Defaults

Transition rules

What each state does

Configuring thresholds

Configuring model routing

What the FSM does not do