> ## 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.

# ETrace: retrieved steering pattern

> Reference for the ETrace dataclass — the raw shape of patterns the SDK retrieves from rb-api before rendering them into system-prompt injections.

When the middleware decides the agent needs steering, it queries rb-api's pattern store and receives one or more `ETrace` objects. Each `ETrace` represents a single retrieved pattern — an instance-level memory, an abstracted failure signature, or a universal heuristic — keyed by similarity to the current trace context. The middleware then renders the best matches into the system prompt for the next LLM call.

```python theme={null}
from reasonblocks.types import ETrace
```

<Note>
  `ETrace` is an internal data type. The middleware does not return `ETrace` instances to user code; injection text rendered from these patterns is captured in `StepLogEntry.intervention_texts` (full text) and `StepLogEntry.injections` (preview). The `StepAssessment` dataclass in `reasonblocks.types` is vestigial — no public API path produces it. Read this page when you are working at the rb-api boundary or implementing a custom injection class.
</Note>

## Fields

<ResponseField name="tier" type="str" required>
  The tier of the retrieved pattern. One of:

  * **`"e1"`** — Instance-level. A specific prior trace that closely matches the current one. Most specific.
  * **`"e2"`** — Pattern-level. An abstracted failure signature derived from multiple traces.
  * **`"e3"`** — Universal. A general heuristic fired on the very first call and as a fallback when nothing more specific matches.
</ResponseField>

<ResponseField name="similarity" type="float">
  Cosine similarity score in `[0.0, 1.0]` reported by the server. Higher means a better match. Default `0.0`.
</ResponseField>

<ResponseField name="pattern_id" type="str">
  Identifier for this pattern in the rb-api pattern store. Empty string if the pattern was not persisted (e.g. a transient monitor-derived steering text).
</ResponseField>

<ResponseField name="fields" type="dict[str, Any]">
  Raw payload from the Qdrant point. The shape varies by tier; see `reasonblocks/schemas/pattern_schema.json` in the SDK repo for the full schema. The middleware passes this dict to `reasonblocks.format_routing.render_pattern(tier, model_id, fields)` to produce the final injection text once the post-routing model is known.
</ResponseField>

<ResponseField name="failure_type" type="str | None">
  Categorical failure label from the server's monitor evaluation (for example a loop or contradiction label). `None` when the pattern is not associated with a specific monitor failure.
</ResponseField>

<ResponseField name="model_family" type="str">
  The model family the pattern was originally recorded against (`"haiku"`, `"sonnet"`, `"opus"`, etc.). Empty string when the pattern is model-agnostic.
</ResponseField>

<ResponseField name="level" type="str">
  Legacy alias for `tier`, kept so older callers that read `level` still work. New code should read `tier`.
</ResponseField>

<ResponseField name="source_trace_id" type="str | None">
  The `run_id` of the trace that originally produced this pattern. Typically populated for `e1` patterns; `None` for `e3` universals and for manually authored entries.
</ResponseField>

## Where ETrace surfaces

`ETrace` is constructed inside the SDK's injection layer (`reasonblocks.injections.e1`, `e2`, `e3`) from rb-api responses. The middleware then wraps the retrieved patterns in `PendingInjection` objects and renders them into a single string appended to the system prompt in `wrap_model_call`.

User-visible artefacts of this pipeline appear on `StepLogEntry`:

* `injection_sources` — names of the injection classes that fired (e.g. `"E1Injection"`).
* `injections` — short previews of the rendered text (≤150 chars).
* `intervention_texts` — the full rendered injection text per source.
* `monitors_fired` and `failure_type` — metadata propagated from the server's monitor evaluation.

To inspect the raw `ETrace` itself, you would either subclass `BaseInjection` and override `retrieve()`, or call `ReasonBlocksAPI.fetch_e1_pattern` / `fetch_e2_patterns` / `fetch_e3_patterns` directly. There is no public middleware accessor that returns `ETrace` instances after a run.

## Constructing an ETrace

```python theme={null}
from reasonblocks.types import ETrace

pattern = ETrace(
    tier="e1",
    similarity=0.87,
    pattern_id="pat_01hz9x4kj2",
    fields={
        "title": "Avoid re-reading unchanged files",
        "guidance": "If your last observation showed no diff, do not read the file again.",
    },
    failure_type="loop",
    model_family="sonnet",
    source_trace_id="run-2024-11-05-abc",
)
```

<Tip>
  If you only want to know what the middleware injected and why, inspect `StepLogEntry.intervention_texts`, `StepLogEntry.injection_sources`, and `StepLogEntry.failure_type` after the run. Reach for `ETrace` only when you are extending the retrieval pipeline yourself.
</Tip>