How Hartley works
States, questions, calibrated answers, one read, and 'not enough evidence'.
Six ideas cover everything the API does. Once they click, the reference is just field names.
The state
The state is whatever your questions are about: an agent run with its system prompt, messages and tool calls; a support ticket; a document; a screen; a row from a table. Send it as a string or as any JSON. Hartley only sees what you send, so include the evidence the question needs.
A state can be up to the model's context: 16K tokens for hartley-1, 32K for hartley-1-flash.
Questions
A question is something you want decided about the state, in plain language, with the kind of answer you want:
| Type | Asks | You get |
|---|---|---|
noul | a yes or no question | the probability of yes |
choice | pick one of your options (2 to 255) | the most likely option and a probability for each |
score | rate on your scale (2 to 10 levels) | the expected level and a probability for each |
extract | pull a value out of the state (an amount, a date, a name, a phrase) | the span of the state that holds it, or "not stated" |
You name each question, and the answers come back under the same names. Questions are not fixed labels: write a new one whenever you need it, and Hartley answers it on the next call. Question types has the details; Writing good questions has the craft.
One read, every question
Hartley reads the state once and answers every question from that read. Asking twenty questions about one trace costs little more than asking one, because you pay for the input once and the output is free.
So ask the questions you actually care about, separately. Five small questions beat one compound one, and cost about the same.
Decisions, not text
Hartley never writes. Every answer is a probability distribution over the options you defined, or, for extract, a pointer to a span of your own input. That has practical consequences:
- Nothing to parse. No JSON-mode, no retries on malformed output, no regex over a paragraph.
- Nothing invented. An answer is always one of your options, on your scale, or text that is literally in your state. A model that doesn't write has nothing to hallucinate.
- Nothing to wait for. No tokens are generated, so an answer arrives in about the time it takes to read the state.
Hartley can still be wrong about a decision. What it can't do is make up an answer you didn't offer.
Calibrated probabilities
Hartley is trained to be honest about uncertainty. Its probabilities are calibrated: across many answers given at 0.9, about 90% are right; at 0.6, about 60%.
That is what makes the numbers usable. You can put a threshold on them, automate everything above it and send everything below it to a person or a larger model, and know roughly how many mistakes the automated share will contain.
Two related fields come with every choice and score answer: confidence, how peaked the distribution is (1 when all the probability is on one option, 0 when it is spread evenly), and probabilities, the full distribution. See Acting on confidence.
"Not enough evidence"
Every question gets one extra option you don't have to define: abstain. Its probability, reported as abstain, is how strongly Hartley thinks the state doesn't contain the evidence to answer.
A high abstain is not an error. It usually means the trace doesn't show what you asked about: the tool result wasn't included, the conversation was cut off, the question is about something that never happened. Treat it as a signal, route it, or fix the state you send. You can turn it off with options.abstain: false.