> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextmoca.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Operating points and models
> An opaque, immutable label naming a frozen configuration — what it guarantees, what it deliberately does not, and why Needlepath never calls a model.
## What an operating point is
```json theme={null}
"budget": { "max_context_tokens": 4000, "operating_point": "np-2026-07-r2" }
```
An **operating point** is an opaque, versioned label that names a frozen engine
configuration server-side. Everything that tunes selection — thresholds,
weightings, tier sizes, gate parameters — is resolved from the label. None of it
appears in your request, and none of it crosses the wire.
That is a contract property rather than an omission. It is what lets us retune
without breaking you, and it is what makes a result citable.
## Three rules
A published label never changes meaning. Retuning mints a **new** label
(`np-2026-07-r2`, `np-2026-08-r1`, …); it never edits an existing one.
Every response returns `policy_version`, the resolved frozen version behind the
label that actually ran. Record it alongside your results and a result file
becomes self-describing.
Always send `budget.operating_point`. Read the registry to see what exists.
## Always pin it
If you omit `operating_point`, you inherit the server's current default — and
**that default moves when a new label is minted**. Nothing about your code
changes, and your behaviour does.
An unpinned caller is the single most common way results end up attributed to a
configuration nobody chose. If you compare two runs, log two numbers, or publish
anything, pin the label.
## The registry
```bash theme={null}
curl -sS "https://$NEEDLEPATH_HOST/v1/operating-points" \
-H "Authorization: Bearer $NEEDLEPATH_API_KEY"
```
```json theme={null}
{
"default": "np-2026-07-r2",
"operating_points": [
{ "label": "np-2026-07-r1", "policy_version": "np-2026-07-r1" },
{ "label": "np-2026-07-r2", "policy_version": "np-2026-07-r2" }
]
}
```
`default` is the label applied when you omit one. It is reported so you can see
what you would have inherited — not so you can rely on it.
## The trade-off, stated plainly
We would rather you read this here than infer it later.
| | |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Verifiable** | A response names the exact frozen version that produced it. |
| **Re-runnable** | Cite the label, call the endpoint, get the same behaviour. A label we publish stays resolvable. |
| **Not inspectable** | The mapping from label to configuration, and the method behind it, are not disclosed. You can confirm *what* was produced and reproduce it; you cannot read *how*. |
## A label pins a configuration, not an engine build
This is the subtlety that catches people, and it matters if you are comparing
against a number you recorded months ago.
A label names a **configuration**. It does not name the *engine build* serving
it. Requesting a historical label from a current deployment reproduces that
configuration on today's engine — which is the right behaviour, and which is not
the same thing as reproducing figures published from the build the label was
minted against.
The practical rule: **compare like with like by pinning both the label and the
date you measured.** If a comparison matters, re-measure your baseline rather
than reaching back for an old number under an old label.
## Choosing a label
Use the current default label unless you have a reason not to. Older labels stay
in the registry so that work citing them stays resolvable; they are not
"stable" versions to prefer, and they are not tuned differently from the current
one unless the release notes say so.
When a new label is minted, the migration is a one-line change and there is no
deadline attached to it — the old label keeps resolving.
## Models
Needlepath **never calls a model.** It has no model key, makes no inference
request, and has no opinion about which provider you use. It reads your records
and returns a subset of them. That is the whole surface.
Three consequences worth stating:
The token counts in a request and response come from a deterministic
**heuristic**, not from any provider's tokenizer. That is deliberate: it makes
the numbers reproducible with no model dependency and no per-provider drift.
It also means the counts will not match your provider's, and the direction is
consistent — the heuristic reads roughly 20–25% *under* an exact tokenizer on
ordinary prose. Use it for budgeting against `max_context_tokens` and for
checking the [per-request ceiling](/limits#per-request-ceilings); use your
provider's count when you need their exact number.
There is no downstream inference call in the selection path, so there is no
third party to disclose on it. See [Retention and trust](/retention-and-trust).
Set it from what your downstream call can actually accept, minus whatever else
you are putting in the prompt. Needlepath does not know your model's window
and will not infer one.
## A note on `max_context_tokens`
Set it from your real downstream constraint and leave it there.
**Set it from your downstream constraint, not by sweeping.** Selections at
different budgets are different computations: a larger allowance is not
guaranteed to contain — or to beat — a smaller one. So do not sweep the budget
looking for a quality optimum, and do not put it behind a user-facing
"quality vs cost" dial.
If your budget is genuinely uncertain, the right tool is
[adaptive mode](/concepts/adaptive-budget), which lets the engine escalate its
own budget along a ladder you define, rather than you guessing a single number.