How it works
Every request goes through the same four steps. Each one is visible in the response, so you can always see why an item was kept or removed.
The pipeline#
Contextwaise receives a question and a list of candidates, and returns the candidates worth sending. In order:
1. Cleanup#
Structured content is cleaned before anything is scored, because noise inflates tokens without adding meaning. Contextwaise recognizes the format of each candidate and removes what a model never needs:
| Format | What is removed |
|---|---|
| HTML | Scripts, styles, navigation, footers, cookie banners and markup. The text stays. |
| JSON | Empty fields (null, "", [], {}) and whitespace. |
| Test output | Passing tests and progress bars. Failures and the summary stay. |
| Logs | Repeated lines, collapsed into one. Errors are never removed. |
| File listings | Long path lists, grouped by folder. |
| Plain text | Nothing. Prose is never rewritten. |
Cleanup is deterministic: the same input always produces the same output. Items that were cleaned list what was removed in items[].cleaned, and savings are measured against the size you sent.
2. Relevance scoring#
A relevance model reads each candidate against the question and gives it a score on a fixed scale:
| Score | Meaning |
|---|---|
3 | Directly answers the question, or is essential to answering it. |
2 | Useful supporting evidence. |
1 | Loosely related background, not needed to answer. |
0 | Unrelated, or only shares surface words. |
Scores are expected values, so they can fall between levels (for example 2.4).
3. Selection#
Candidates are considered from the highest score down. Each one is kept unless:
- its score is below the threshold →
low_relevance; - it repeats an item already kept, even reworded or partly copied →
duplicate; - keeping it would exceed the token budget →
over_budget.
The threshold comes from the request's aggressiveness:
| Aggressiveness | Base threshold | Best for |
|---|---|---|
conservative | 0.9 | Answers where missing context is costly: legal, medical, finance. |
balanced | 1.4 | Most applications. The default. |
aggressive | 1.9 | High-volume flows where cost matters most. |
Kept items are returned in the order you sent them, never re-ranked, so your prompt keeps its structure.
4. The report#
The response explains every decision: the score and reason for each item, tokens and cost before and after, the threshold and budget applied, and how long each step took. See the response reference.
The quality check#
After the response is sent, so it never adds latency, Contextwaise checks whether the context it kept was enough to answer the question. The verdict tunes that agent's threshold for later requests:
- if the kept context was probably not enough, the agent starts keeping more;
- if it was clearly enough, the agent cuts a little more.
Loosening steps are three times larger than tightening ones, so answer quality recovers fast while savings grow gradually. The adjustment is bounded, so no run of verdicts can push an agent to extremes.
Each agent learns separately, which is why naming your call sites with agent matters. The check can be turned off in Settings → Optimization defaults; the base threshold then applies as is.
When scoring is unavailable#
Contextwaise never guesses. If the relevance model can't be reached after retries, the request fails with 503 scoring_unavailable rather than cutting your context on a weaker signal: a wrong cut would silently cost you answers, in any language.
Latency#
Most of a request's time is relevance scoring; cleanup and selection take a millisecond or two. report.timings breaks the total down by step, and report.latencyMs is measured from the moment the request arrives. Scoring runs on new items only: in a conversation, items already decided are reused instantly.