All chapters
  1. Start hereA model knows only what it can see now
  2. Foundations · 1The context window: tokens, messages and order
  3. Foundations · 2Signals and authority: who is allowed to instruct the model
  4. Foundations · 3The context assembly pipeline: select, rank, deduplicate, pack
  5. Retrieval · 4Retrieval fundamentals: lexical search, embeddings, hybrid search, reranking
  6. Retrieval · 5RAG architecture: chunks, metadata, grounding, citations, freshness
  7. Budget · 6Context budgeting: truncation, dilution, token cost and caching
  8. Budget · 7Compression, summarization and compaction, with loss tests
  9. Agents · 8Coding-agent context: repository maps, instruction files, diffs and tool outputs
  10. Agents · 9Working context, durable memory and checkpoint state
  11. Agents · 10Dynamic context: just-in-time retrieval, selective tool disclosure, delegation
  12. Agents · 11Multi-agent context isolation and scoped handoffs
  13. Trust · 12Context security: injection, poisoning, access controls, tenant boundaries
  14. Trust · 13Measuring context quality: recall, utilization, grounding, ablation
  15. Practice · 14Frameworks and standards: what each one assembles for you
  16. Practice · 15Context in production: versions, drift, refresh, observability, incidents
  17. Practice · 16The insurance lab: one submission, every context decision
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Foundations · 3

The context assembly pipeline: select, rank, deduplicate, pack

The program that builds the window before each model call: gather candidates, filter, rank, remove duplicates, pack under a budget, and write down what was left out and why.

You will understand
The program that builds a window before every model call, stage by stage.
You will be able to
Read a context manifest: what was included, what was omitted, and the reason for each.
You will see
Why one missing stage turned eight correct cases into wrong ones.

The first version of the underwriting agent's assembler was short. For each model call it took everything that might be useful, in the order it arrived: all 63 fields of the submission, the provider's answer, the top ten passages from the policy search, five similar past decisions, and the history of the run. It pasted them into the window as plain text and stopped when the budget was full.

It worked on the demo case. Then the team ran all sixteen cases of the example through it, and eight came back wrong. Case UW-001 is the simplest of them: a roof of 31 years in wind zone C, which rule R-ROOF-01 says is not eligible. The first assembler's window contained R-ROOF-01. It also contained two other roof rules: the superseded 2025.4 version (limit 30 years) and a note that belongs to another tenant of the platform (limit 35 years). Both ranked above the current rule for the query, and in plain text the stand-in agent took the first roof limit it read: 35 years. A roof of 31 passed. The recommendation was approve.

No retrieval bug, no model bug. The assembler let two items into the window that should never have been candidates for this call, and it kept no record of having done so. When the reviewer asked why the agent approved, the only evidence was the final answer.

This page is about the assembler as a real program, with stages that each have one job, and an output that is not only a window but a record of every choice.

The assembler, in one sentence and one example#

Context assembly is the step that builds the window for one model call: it takes everything that could go in, decides what does, and puts it in order. The program that does it is the assembler.

The things it works with are context items: one unit that can be included or omitted as a whole. A passage of a policy document is one item. So is a group of related fields of the submission, one tool result, one past decision, one earlier turn of the run. Before the assembler has decided anything, an item is a candidate. After, it is either in the working set or omitted.

For UW-004, the roof conflict of SUB-1004, the current assembler starts with 43 candidates and ends with 23 included items. The script below runs the stages of examples/uw-context/assemble.py one by one and prints how many candidates remain after each. It was written for this page and run against the example.

from run import load_case
from assemble import (config, gather, select_stage, authorize_stage, freshness_stage,
                      rank_stage, dedupe_stage, cutoff_stage, pack)

case = load_case("UW-004")
cfg = config("ctx-2026.11")
cands, _ = gather(case, cfg)
omitted = []
print(f"{'candidates':12} {len(cands):3}")
stage = cands
for name, fn in [("select", select_stage), ("authorize", authorize_stage), ("freshness", freshness_stage)]:
    stage = fn(stage, cfg, omitted)
    print(f"{name:12} {len(stage):3}  omitted so far {len(omitted)}")
stage = rank_stage(stage)
stage = dedupe_stage(stage, cfg, omitted)
print(f"{'dedupe':12} {len(stage):3}  omitted so far {len(omitted)}")
stage = cutoff_stage(stage, cfg, omitted)
print(f"{'cut at k':12} {len(stage):3}  omitted so far {len(omitted)}")
included, dropped, used = pack(stage, cfg["budget"], cfg["shares"], cfg["mode"])
print(f"{'pack':12} {len(included):3}  omitted so far {len(omitted) + len(dropped)}  tokens {sum(used.values())} of {cfg['budget']}")
candidates    43
select        34  omitted so far 9
authorize     34  omitted so far 9
freshness     28  omitted so far 15
dedupe        24  omitted so far 19
cut at k      23  omitted so far 20
pack          23  omitted so far 20  tokens 2288 of 2800

Every candidate ends in exactly one of two lists, and the counts add up: 23 included plus 20 omitted is 43. That invariant is the first test the example's unit tests check, and it is the property that lets a reviewer trust the record.

Diagram: The assembler for one model call · 43 candidates in, 23 items and a manifest out (UW-004)

Read left to right. Filters come first, then ranking, then the cuts that depend on rank, then packing. Every stage that removes an item writes it into the manifest with one reason. Click a stage to see what it removed in case UW-004.

  1. 1 · Gather
    1. Candidates: Everything this call could use: instructions, tools, 15 field groups, tool results, ten passages, five decisions, history.
  2. 2 · Filter (before ranking)
    1. Select: Drops what this step does not need.
    2. Authorize: Drops what this agent may not read: tenant first, then audience.
    3. Freshness: Drops items of a policy version no longer in force.
  3. 3 · Rank and cut
    1. Rank: Orders passages and past decisions by retrieval score.
    2. Deduplicate: Drops a passage that nearly repeats a better-ranked kept one.
    3. Cut at k: Keeps the top 5 passages and the top 3 past decisions.
  4. 4 · Pack and record
    1. Pack: Fits items into the budget, each kind in its own share; over_budget for what does not fit.
    2. Manifest: The record of the window: each included item with its reason, each omitted item with its omission reason.

The stages, and why each comes where it does#

Each stage has one job and one omission reason. The order is not arbitrary; it follows a rule that a backend engineer already knows from SQL: filter before you sort.

Gather. Collect every candidate the call could use: the system instruction, the new turn, the tool definitions, fifteen field groups (the 63 fields), the tool results of every attempt so far, the top ten passages of search_guidance, the top five of find_similar_decisions, and the run's earlier turns.

Select. Drop what this step does not need. The recommend step asks for six field groups (roof, exposure, identity, size, protection, losses). Contact details, billing and the broker's own data stay out with the reason not_requested. In UW-004 that is nine items.

Authorize. Drop what this agent may not read, tenant first, then audience. A passage owned by another tenant is omitted as other_tenant; a document written for another team (a reinsurance treaty memo, in case UW-201) as unauthorized. In UW-004 the retriever already applied these filters before ranking, so nothing reaches this stage to be removed.

Freshness. Drop what belongs to a policy version no longer in force: the 2025.4 roof chunks, and past decisions that were made under 2025.4. Reason superseded; six items in UW-004.

Rank. Put the passages and the past decisions in order of relevance, using the retrieval scores (the next page explains them).

Deduplicate. Drop a passage that nearly repeats a better-ranked passage already kept. The example measures overlap of terms and treats 0.8 or more as a duplicate. In UW-004 four copies of one bulletin go, reason duplicate.

Cut at k. Keep the top 5 passages and the top 3 past decisions; the rest are below_rank_cutoff.

Pack. Fit what remains into the budget, each kind of content inside its own share. Anything that does not fit is over_budget, and a tool output that is too long may be trimmed instead (the Budgeting page covers this). In UW-004 everything fits: 2,288 of 2,800 tokens.

Before AI. In SQL, WHERE runs before ORDER BY ... LIMIT. If you sorted ten rows and then filtered out the ones the user may not see, you might return three rows instead of ten, and you would have spent the ranking on rows that never mattered. An assembler has the same rule with higher stakes: rank before you filter, and a passage the agent may not read can still win a slot, or, worse, the filter is forgotten and it reaches the model. The comparison stops at one point: a SQL WHERE is exact, while relevance ranking is an estimate, which is why the later stages exist.

The record: a context manifest#

The output of the assembler is two things. The window, which goes to the model. And the context manifest: the record of one assembled window, with every included item, its size and the reason it is in, and every omitted item with its omission reason, one value from a fixed list.

Here is the head of the UW-004 manifest (real output of python3 run.py --case UW-004 --show manifest, shortened to one included item):

{
  "case_id": "UW-004",
  "submission_id": "SUB-1004",
  "run_id": "run-7f3a",
  "attempt_number": 1,
  "step": "recommend",
  "trace_id": "0c17c0046d4371b42858072814d7b4ca",
  "span_id": "37a35f9ab76de709",
  "policy_version": "2026.2",
  "context_version": "ctx-2026.11",
  "budget": {"total": 2800, "used_total": 2288},
  "included": [
    {"item_id": "INS-SYSTEM", "evidence_id": null, "kind": "instruction", "bucket": "instructions", "tokens": 257, "reason": "required: system instruction"}
  ],
  "omitted": [
    {"item_id": "EV-GUIDE-0202", "evidence_id": "EV-GUIDE-0202", "kind": "policy_passage", "bucket": "policy", "tokens": 112, "omission_reason": "superseded", "detail": "filtered before similarity; would have ranked 3"}
  ]
}

Three parts of it carry the weight. The identifiers say exactly which model call it describes: the submission, the run, the attempt and the step, plus the trace and span where the same call appears in the run's telemetry. The versions say which policy and which assembly configuration produced it. And the two lists answer the two questions of this site that a final answer cannot: what did the model see, and what was left out. The detail field of the omitted 2025.4 chunk says something a reviewer would otherwise never learn: it would have ranked third.

The fixed list of reasons is short on purpose:

Omission reasonMeaningIn UW-004
not_requestedThis step does not need it9 field groups
unauthorizedThe agent's role may not read it0
other_tenantIt belongs to another tenant0
supersededIt belongs to a version no longer in force2 policy chunks, 4 past decisions
duplicateIt nearly repeats an included item4 bulletin copies
below_rank_cutoffIt ranked below the top k for its kind1 bulletin
over_budgetIt did not fit in its share of the budget0

A fixed list matters more than it looks. A free-text reason ("seemed irrelevant") cannot be counted, alerted on or compared between two versions. Seven reasons can. When the share of over_budget omissions jumps after a deployment, you know where to look.

Pick a case in the lab below and read its manifest. Filter by reason to see what each stage removed.

CaseIncludedOmittedOmissions by reasonRecommendation
UW-0042320not_requested 9, superseded 6, duplicate 4, below_rank_cutoff 1escalate, R-ROOF-03
UW-001 (first version, ctx-2026.10)347below_rank_cutoff 7approve (expected decline)

The agent here is a scripted stand-in, so these results show how the mechanism works, not how good any model is.

The eight cases, and the stages that fixed them#

The team compared the two versions of the assembler on all sixteen cases. The first version, ctx-2026.10, had no selection, no authorization or freshness filters, no deduplication, lexical retrieval only, one flat budget and no labels. The current one, ctx-2026.11, has all of them.

UW-001  shared 1   2147   34/7   approve      -                        decline      FAIL
UW-005  shared 1   2177   34/7   approve      -                        decline      FAIL
UW-007  shared 1   2149   34/7   approve      -                        decline      FAIL
UW-201  site   1   2150   34/7   approve      -                        decline      FAIL
UW-202  site   1   2800   23/18  approve      -                        decline      FAIL
UW-204  site   1   2144   34/7   approve      -                        decline      FAIL
UW-205  site   1   2177   34/7   approve      -                        decline      FAIL
UW-206  site   1   2129   34/7   approve      -                        decline      FAIL
8/16 match the expected recommendation

Those are the failing rows of python3 run.py --context-version ctx-2026.10. With the current version, all sixteen cases match. Every failure is an approve where the expected answer is decline, which is the dangerous direction for an insurer: a roof the guidance excludes, recommended for cover. The roofs in these cases are 26 to 31 years old, so the limit the agent reads decides everything.

Reading the first-version windows shows three causes, not eight.

Cause in the first versionCasesWhat the current version does
The first roof limit in the window was another tenant's (35 years), followed by the superseded 2025.4 limit (30 years), then the current one (25 years)UW-001, UW-007, UW-201, UW-204, UW-205, UW-206Authorize (tenant, then audience) and freshness, both before similarity; labels with version, status and tenant
The broker's "approve" note was read as an orderUW-005Labels and delimiters (Signals)
A 4,031-token report filled the flat budget and pushed every passage outUW-202Pack with shares; trim the tool output (Budgeting)

Notice what the table does not claim. The current version changed several stages at once, so this comparison cannot say which single stage was necessary. To learn that, you remove one stage at a time and rerun the cases, which is an ablation of the configuration; Measuring shows the method.

Common confusion. "Fixing the assembler" did not make the model smarter. The stand-in agent is the same script in both runs. Only its window changed. That is the point of this page: a large share of what looks like model error is a window that held the wrong things.
For a coding agent. A coding agent's harness also assembles: the instruction file is always in, a repository map may be, a file is read on request, and old tool results are cleared after a while. When the agent edits the wrong file, the same question applies: which items were in that call's window, and which were left out? Most coding-agent products do not expose a manifest; Coding agents shows what you can still observe.
What this is not. The manifest is not the run's log or trace. It describes the input of one model call. The trace of the run, with its spans, timings and tool calls, belongs to observability: Observability Engineering. The manifest carries the trace_id and span_id so that the two can be joined.
Invariants worth testing in your own assemblerFive properties that hold for every manifest, and how the example tests them

The example's unit tests (test_context.py) check properties that do not depend on any case. They are worth copying, because they catch the silent failures.

InvariantWhy
Every candidate appears in exactly one list: included or omittedNothing disappears without a record
Every omission reason is in the fixed listReasons can be counted and compared
Included tokens per share stay within the share's limitThe budget is enforced, not hoped for
No included item has another tenant, an unauthorized audience or a superseded statusFilters are applied, whatever the ranking
The same inputs and the same context version give the same manifestAssembly is deterministic, so a difference means an input changed

The last one is the foundation of incident analysis. If assembly is deterministic, a window can be rebuilt from its inputs and its context_version. If it is not (because of a random tie-break, a clock read inside a stage, or an unordered set), you must store every window in full to explain anything later.

For a Principal engineer: design choices with real costsFilter placement, manifest size, and who owns the assembler

Filter inside the retriever or after it. The example filters by tenant, audience and status before similarity is computed, so a blocked chunk cannot use up a top-k slot. Filtering after retrieval is simpler to bolt on and fails quietly: ask for the top 10, remove 6, and the window has 4 passages, none of which may be the one you needed. Vector stores differ in whether a metadata filter runs before or after the approximate nearest-neighbor search; RAG and Frameworks say what the documentation of each tool states.

Record omissions that never reached ranking. A filtered chunk is invisible to a manifest unless the assembler asks "would this have ranked?" The example lists blocked chunks that would have made the top ten without the filter, with the rank they would have had. That costs a second scoring pass and is the only way to answer "did the filter hide something relevant?".

Manifest size and retention. A manifest of ids, sizes and reasons is a few kilobytes per call. A stored window is the full text, often containing personal or confidential data. Keep manifests for every call; keep full windows only where policy allows and for as long as policy allows, and rebuild the rest from versioned inputs.

Ownership. The assembler encodes business rules (what may be read, which version is in force, what a step needs). It deserves the same review, tests and release process as the eligibility rules. Teams that treat it as glue code inside a prompt template tend to discover their omission rules during an incident.

A checklist for your assembler#

CheckWhy
Assembly is a separate, testable function with named stagesYou can test and version it like other code
Authorization and freshness run before ranking and before top-kA blocked item must not take a slot or reach the model
Every call produces a manifest with included and omitted listsAnswers "what did the model see, what was left out"
Omission reasons come from a fixed listThey can be counted, alerted on and compared
The manifest carries submission, run, attempt, step, trace and span idsIt can be joined with the run's telemetry
The manifest carries the policy version and the context versionYou can tell which configuration built it
Assembly is deterministic for the same inputsA window can be rebuilt instead of stored

In one breath#

Before every model call, a program decides what the model will see: it gathers candidates, keeps what the step needs, removes what the agent may not read and what is out of date, ranks the rest, drops near-duplicates, cuts at k and packs under a budget. Make that program explicit, filter before you rank, and have it write a manifest of every item it included and every item it left out with a reason from a fixed list. Then a wrong answer stops being a mystery about the model and becomes a question you can answer from a record.

What comes next#

The assembler's most uncertain stage is the one this page passed over in a line: ranking. Which of 31 chunks is relevant to "roof age on the application and from the provider differ"? The next page, Retrieval, explains the four ways of answering that question (matching words, comparing meaning, combining both, and reranking a short list) and where each one fails.