# Architecture note — <your system's name>

Fill in every line. A line you cannot fill in is a decision you have not made yet, or a
number you have not measured yet, and both are worth knowing before the system is used by
anyone but you. Replace the angle-bracket prompts with your own text; delete nothing.

Written by: <you> · Date: <YYYY-MM-DD> · Framework and version: <name and version you installed>

---

## 1. What it is for

One paragraph. The tasks this system is meant to do, and the tasks it is not.

<the paragraph>

**Out of scope, deliberately:** <the things you decided not to build, and why>

## 2. Roles and models

One row per role. The model column holds an alias from your gateway, not a file name, so
this table stays true when you swap the file behind the alias.

| Role | Alias | Model behind the alias | Why this size | Where it runs |
| --- | --- | --- | --- | --- |
| Router | <alias> | <model and quantisation> | <one line> | <machine> |
| Retrieval agent | <alias> | <model and quantisation> | <one line> | <machine> |
| Tool-using agent | <alias> | <model and quantisation> | <one line> | <machine> |
| Synthesiser | <alias> | <model and quantisation> | <one line> | <machine> |
| Embedding | <alias> | <model> | <one line> | <machine> |
| Reranker, if used | <alias> | <model> | <one line> | <machine> |

**Licence check.** Every model above: <licence names, and the date you read each model card>

## 3. The route the work takes

Draw or describe one task travelling through the system, naming what is sent to which model
and what comes back. If a reader cannot follow this without asking you a question, the
system is more complicated than its job.

<the walk-through>

**What happens when the router is wrong:** <the fallback, and what it costs>

**What happens when a specialist fails:** <the behaviour, not the intention>

## 4. Tools and their privileges

One row per tool. "Can it change anything?" is the column that matters; everything with a
yes in it needs a reason and a boundary.

| Tool | What it reads | What it can change | Boundary that enforces it | Approval needed |
| --- | --- | --- | --- | --- |
| <name> | <paths, index, nothing> | <none, or exactly what> | <path check, allow-list, container> | <never, or when> |

**The tool I was tempted to add and did not:** <which, and why not>

## 5. Limits

| Limit | Value | Why this value |
| --- | --- | --- |
| Maximum model requests per task | <n> | <one line> |
| Maximum tokens per task | <n> | <one line> |
| Wall-clock timeout per task | <n> s | <one line> |
| Maximum passages in a prompt | <n> | <one line> |
| Tool result truncation | <n> characters | <one line> |

## 6. Measured results

From `agent-eval.py`, on the task suite, with the date and the settings that produced them.
A cell you have not measured says "not measured", never a guess.

| Configuration | Tasks | Repeats | Success rate | Mean steps | Mean tokens | Mean seconds |
| --- | --- | --- | --- | --- | --- | --- |
| <scaffold and models> | <n> | <n> | <rate> | <n> | <n> | <n> |
| <a second configuration> | <n> | <n> | <rate> | <n> | <n> | <n> |

**Where it failed:** <task ids, and what the trajectories showed>

**Variance across repeats:** <the spread on the tasks that were not deterministic>

## 7. Cost

Cost per million tokens comes from your own `cost-model.py` run in Part 23. Copy the figure
and the inputs that produced it; a cost with no inputs behind it is not a measurement.

| Input | Value | Source |
| --- | --- | --- |
| Cost per million tokens | <value> | Part 23 cost model, run on <date> |
| Mean tokens per task | <value> | `agent-eval.py`, run on <date> |
| Cost per task | <value> | the two lines above, multiplied |
| Tasks per week, expected | <value> | <your own estimate, and how you made it> |
| Cost per week | <value> | the two lines above, multiplied |

**Compared with the single-model baseline:** <the same figures for one model answering
directly, and whether the extra roles paid for themselves>

## 8. What could go wrong

| Risk | How it would show | What is in place | What is not |
| --- | --- | --- | --- |
| Prompt injection through a document | <symptom> | <control> | <gap> |
| A tool reaching outside the workspace | <symptom> | <control> | <gap> |
| The router sending everything one way | <symptom> | <control> | <gap> |
| The suite passing while real tasks fail | <symptom> | <control> | <gap> |
| <your own> | <symptom> | <control> | <gap> |

## 9. What I would do next

Three things, in the order you would do them, each with the measurement that would tell you
whether it worked.

1. <change> — measured by <which number in section 6 or 7>
2. <change> — measured by <which number>
3. <change> — measured by <which number>

## 10. What I got wrong

The section that makes the rest of the note trustworthy. What you expected before you
measured, and what the measurement said instead.

<the paragraph>