Build Safer Agent Recovery Loops with Dot Reflex 14B

What Dot Reflex 14B Does

Dot Reflex 14B is an execution-recovery controller for coding and tool-using agents. It does not replace the worker agent. Instead, it reviews a compact JSON summary of the agent’s trajectory and recommends how the surrounding harness should control the next stage of execution.

The controller can supervise agents powered by GPT, Claude, Gemini, Qwen, Llama, or another model because it operates on normalized execution events rather than the worker model’s internal architecture. The release is a rank-64 QLoRA adapter for Qwen3-14B-Base.

Dot Reflex returns one of ten actions:

• continue: allow a sound plan to proceed.
• verify: request evidence for a claim or risky assumption.
• retry_differently: repeat the immediate attempt using a different command, parameter, or method.
• replan: replace an approach whose core assumptions have failed.
• rollback: restore a known-good state after a harmful change.
• branch: isolate multiple plausible approaches in separate environments.
• switch_model: route the next attempt to another model after a persistent capability or provider failure.
• ask_human: pause when authority, secrets, clarification, or an external decision is needed.
• stop_successfully: finish when completion is supported by adequate evidence.
• stop_failure: stop when no safe and authorized recovery remains.

The output is a recommendation, not an authorization. Your harness remains responsible for permissions, policy enforcement, tool execution, rollback mechanics, and the final decision to stop.

Key Features

• Framework-neutral input: The controller accepts ordinary JSON assembled from execution events already recorded by an agent framework.
• Machine-readable output: Every valid response contains an action, rationale, confidence value, recovery instructions, and parse status.
• Deterministic generation: The reference runtime uses greedy generation.
• Fail-closed behavior: The CLI exits with a non-zero status when the input schema or generated action is invalid.
• Multiple interfaces: Run one decision from the command line, pipe JSON through standard input, or host a local HTTP endpoint.
• Cross-model supervision: The worker agent does not need to use Qwen or share the controller’s architecture.

Requirements and Installation

The reference 4-bit runtime requires Linux and an NVIDIA GPU. A 24 GB GPU is the practical minimum for one request at a time, while 40–48 GB provides additional headroom. This release does not include GGUF, Ollama, MLX, CPU, or merged-weight builds.

Clone the repository, create a Python virtual environment, and install the runtime dependencies:

git clone https://github.com/usedotai/dot-reflex.git
cd dot-reflex
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

The GitHub repository contains the runtime, tests, examples, documentation, and evaluation receipts. The approximately 1.03 GB adapter is hosted on Hugging Face and downloads automatically on first use. The pinned Qwen3 base weights are also downloaded and cached by Hugging Face.

Verify the Release

From the repository root, verify the source payload on Linux:

sha256sum --check SHA256SUMS

On macOS, use the equivalent command below. Note that macOS is not listed as a supported platform for the reference GPU runtime.

shasum -a 256 -c SHA256SUMS

You can validate the source manifest, pinned base identity, JSON examples, schema, and chart receipts without loading the model:

python3 scripts/validate_release.py

Prepare an Agent Trajectory

Dot Reflex expects a compact snapshot rather than a raw transcript. The exact input contract is defined in trajectory.schema.json. Most agent systems need a small adapter that maps framework-specific events into this structure.

For example, suppose an agent edits password-reset code and claims completion without running tests. A trajectory could look like this:

{
  "task_summary": "Add password-reset token validation",
  "execution_history": [
    {
      "step": 1,
      "actor": "agent",
      "action": "Modified auth/reset.py and declared completion.",
      "result": "Patch applied; no verification was run."
    }
  ],
  "tool_results": [
    {
      "tool": "pytest",
      "status": "not_run",
      "summary": "Tests were never executed."
    }
  ],
  "current_state": "Code changed, but there is no evidence it works.",
  "detected_failure_signals": ["false_completion_risk"]
}

The controller can then identify the missing evidence and return a structured decision such as:

{
  "action": "verify",
  "rationale": "The agent claimed completion without test evidence.",
  "confidence": 0.98,
  "recovery_instructions": "Run the targeted reset-token tests, then the relevant auth suite.",
  "parse_valid": true
}

Only include evidence your harness can support accurately. Missing, stale, or misleading events can cause an incorrect recommendation.

Run a Basic Decision

The repository includes an example trajectory for a false-completion scenario. Submit it to the one-shot CLI:

python3 inference.py examples/trajectory_false_completion.json \
  --adapter usedot/Dot-Reflex-14B

You can also pipe a trajectory through standard input by using - as the input path:

python3 inference.py - --adapter usedot/Dot-Reflex-14B \
  < examples/trajectory_false_completion.json

In an orchestrator, check both the process exit status and the returned parse_valid field. A non-zero exit status indicates an invalid input schema or generated action and should prevent automatic continuation.

Run Dot Reflex as a Local HTTP Service

Install the additional server dependencies and launch the FastAPI application with Uvicorn:

python3 -m pip install -r requirements-server.txt
uvicorn serve:app --host 127.0.0.1 --port 8080

Submit the same trajectory to the decision endpoint:

curl --fail-with-body \
  -H 'content-type: application/json' \
  --data @examples/trajectory_false_completion.json \
  http://127.0.0.1:8080/v1/decision

The example binds to localhost. Before exposing the service to a network, add authentication, TLS, rate limits, request-size limits, and audit logging.

Integrate the Controller into an Agent Loop

Call Dot Reflex at meaningful evidence gates rather than after every generated token. Useful checkpoints include a failed tool call, repeated action, code edit, test or build result, environment change, or completion claim.

trajectory = harness.snapshot_for_supervisor()
decision = reflex.predict(trajectory)

if decision["action"] == "continue":
    harness.resume()
elif decision["action"] == "verify":
    harness.require_verification(
        decision["recovery_instructions"]
    )
elif decision["action"] == "ask_human":
    harness.pause_for_user(decision["rationale"])
elif decision["action"].startswith("stop_"):
    harness.stop(decision)
else:
    harness.apply_recovery_control(decision)

This pattern keeps responsibilities separate. Dot Reflex classifies the recovery need, while the harness implements the actual operation. For example, a rollback recommendation should only invoke a rollback primitive that the harness has already defined and authorized.

The controller can be connected to LangGraph, the OpenAI Agents SDK, OpenHands, AutoGen, CrewAI, Google ADK, or a custom tool loop by normalizing their events. It is not drop-in middleware for Cursor, Claude Code, Codex CLI, or Aider unless a wrapper or hook captures their event streams. Consult INTEGRATION.md for mapping examples and compatibility notes.

Advanced Integration Tips

Use the Smallest Decisive Verification

When the action is verify, prefer the narrowest check capable of confirming or rejecting the claim. In a coding workflow, that might mean running targeted tests before a larger suite. Record the result and submit a fresh trajectory at the next evidence gate.

Map Every Action Explicitly

Do not treat unknown or unsupported actions as continue. Define harness behavior for all ten actions, validate the generated action, and stop safely when parsing or policy checks fail.

Provide Real Recovery Primitives

Recommendations are only useful if the harness can enforce them. A system supporting branch should create isolated worktrees or sandboxes. A system supporting rollback should maintain known-good recoverable states. A multi-model router needs an actual routing mechanism to implement switch_model.

Keep Humans in Control of Sensitive Decisions

Use ask_human when the agent lacks authority, secrets, clarification, or an external decision. Never allow model output alone to authorize destructive, financial, medical, legal, security-sensitive, or otherwise high-impact actions.

Calibrate Confidence Locally

The returned confidence value is generated text, not a safety guarantee. Measure and recalibrate it using trajectories representative of your own environment before applying thresholds or automation policies.

Preserve Evidence and Audit Trails

Store the input trajectory, controller response, executed recovery action, and subsequent result. These receipts make failures easier to investigate and help evaluate whether the controller transfers to your workload.

Understand the Evaluation Boundaries

Dot Reflex was trained on 6,000 synthetic trajectories and validated on 600 synthetic trajectories. The published Agent Recovery Bench v0 evaluation contains 1,000 balanced held-out synthetic trajectories and 200 separate stateful synthetic recovery episodes.

The adapter achieved 1.000 recovery accuracy, 1.000 macro F1, and 1.000 simulated recovery on that synthetic benchmark. Its reported mean latency was 6.13 seconds on an NVIDIA H200, but this is a run-specific measurement rather than a universal serving claim.

The synthetic 100% result does not prove universal reliability. The benchmark is not SWE-bench, an end-to-end repository issue-resolution test, or a production trial.

The published data demonstrates fit to the benchmark distribution, not reliable transfer to independently authored or production failures. Review EVALUATION.md before citing results or designing deployment policies.

Model and Runtime Details

• Base model: Qwen/Qwen3-14B-Base.
• Method: 4-bit NF4 QLoRA with BF16 compute.
• LoRA configuration: rank 64, alpha 128, and dropout 0.05.
• Target modules: attention and MLP projection layers.
• Training context: 2,048 tokens.
• Trainable parameters: 256,901,120, or 1.710% of the base.
• License: Apache-2.0 for the repository and adapter files.

The Qwen base model is a separate upstream dependency. Review its model card and license before distributing or deploying the combined system.

Conclusion

Dot Reflex 14B adds a structured recovery layer to agent execution loops. Start by installing the GPU runtime, converting existing events into the trajectory schema, and testing one decision through the CLI. You can then add the HTTP service or call the controller at evidence gates in a custom harness. Keep execution authority in the harness, validate every response, preserve audit evidence, and evaluate performance on your own workload before enabling automation.