A receipt¶
Every numeric fact carries a receipt: the document it was read from and where on the page its printed token sits.
| field | meaning |
|---|---|
source_id |
the document |
page |
0-based page index into the document's persisted page texts |
char_start, char_end |
the character span on that page |
value_token |
the token as PRINTED ("1,250", "(449.9)") — not the stored value |
byte_verified |
true only when re-slicing (page, char_start, char_end) reproduced value_token exactly |
attestation_method |
the rule that located it, or why none did (full form only) |
byte_verified governs the three offsets. When it is true they are all set and
the slice reproduces the token; when it is false they are null, because a fabricated
offset on a trust surface is worse than none. It is a claim about the LOCATION of a
printed token, never about the correctness of value.
attestation_method names the rule, strongest first: span (the token sits inside a
verbatim span already proven unique), row (the fact's own label was found on the page
and the token follows it exactly once), page, label. Unresolved values each mean
something different: absent (no printed form of the number occurs in the document at
all — the strongest warning this API emits), ambiguous (it occurs but could not be
pinned to this fact's row), short_token (a one-digit number, never looked for),
derived (a computed value, in no document by construction), no_token (the fact
carries no printed token to look for — every clause and passage row, and a claim
written without one), no_pages (the source has no page layer to attest against).
null means no attestor ran at all. That is the whole vocabulary of a delivered fact.
limma_ask's structured_citations carry five further values that never appear on
one: document (located by uniqueness alone, uncorroborated — the weakest), clause
and sentence (a prose citation whose region locates the clause body or the sentence,
not a token), and located_in_source / located_in_extracted_text from the
answer-time byte check over a quoted span — the first when the quote resolved to a
page and its verbatim_* offsets, the second when it was found exactly once in the
document's text but no page could be confirmed, so byte_verified is false and the
offsets are withheld. When a citation list is capped, the last citation's
attestation_method also names the overflow (sentence; N further sentence(s) ...).
The Citation schema in the verb reference is the contract.
A prose row is the common case of no_token: it has text, not a number, so there is
no token to find and the receipt fields stay null:
r = client.post("/v1/public/facts", json={
"workspace_id": WS, "question": "office in Berlin", "limit": 5})
for fact in r.json()["facts"]:
print(fact["kind"], "| method:", fact["attestation_method"],
"| byte_verified:", fact["byte_verified"], "| token:", fact["value_token"])
Reading one¶
r = client.post("/v1/public/facts", json={
"workspace_id": WS, "question": "revenue", "mode": "enumerate",
"coordinate": {"attribute": "revenue", "period": "FY2023"}})
fact = r.json()["facts"][0]
print("value:", fact["value"], "| printed:", fact["value_token"])
print("page:", fact["page"], "| span:", fact["char_start"], fact["char_end"])
print("byte_verified:", fact["byte_verified"], "| method:", fact["attestation_method"])
Re-reading it with limma_region¶
GET /v1/public/region hands back frame[start:end] verbatim — no trimming, no
normalisation — so you can check the receipt without trusting us. Pass page for a
page receipt; omit it to read the document frame (the only frame a source with no page
layer has — page_count: 0 in the reply).
r = client.post("/v1/public/facts", json={
"workspace_id": WS, "question": "revenue", "mode": "enumerate",
"coordinate": {"attribute": "revenue", "period": "FY2023"}})
fact = r.json()["facts"][0]
region = client.get("/v1/public/region", params={
"workspace_id": WS, "source_id": fact["source_id"],
"page": fact["page"], "start": fact["char_start"], "end": fact["char_end"]}).json()
print(region["frame"], region["page"], region["span"], repr(region["text"]))
print("reproduces the token:", region["text"] == fact["value_token"])
print("page_count:", region["page_count"], "| frame_length:", region["frame_length"])
Over MCP this is limma_region(source_id, start, end, page=..., workspace_id=...).
A stale pointer is an error, not a trimmed result¶
A span past the end of the frame means the receipt no longer addresses this document — it was written against a generation that has been superseded, or against a different frame. Limma refuses rather than clamping, because a clamped read would hand back plausible neighbouring bytes and let a dead pointer confirm text it never pointed at.
r = client.get("/v1/public/region", params={
"workspace_id": WS, "source_id": SOURCE, "page": 0, "start": 0, "end": 100000})
print(r.status_code, "|", "out of range" in r.json()["detail"], "| clamped:", "text" in r.json())
See supersession for how a receipt goes stale and how to find out.
What a receipt does not say¶
- It does not say the value is right. The EPS-stored-as-$600,000 class has a byte-true
token and a wrong stored
value; comparevaluewithvalue_tokenyourself. - It does not say the coordinate is right — that the number belongs to the entity, attribute and period it is filed under.
- On labelled rows, a one-digit token (
0,3,8) is never receipted by the label rules — see troubleshooting.