GPTree Knowledge Execution Engine: a worked integration
Generated from real API responses and compared against on every test run, so a changed response shape fails a build rather than going unnoticed in a document nobody re-reads. Not hand-written, and not hand-edited.
It follows one integrator through the sequence a real sync performs: send a document, retry the send, send a revision, list what we hold, hand over a large file, ask a question, ask one the corpus cannot answer, and delete.
What this proves, and what it does not
Real here: ingest, delivery identity, the explicit delete, the background job, the judgment, coverage accounting, citation resolution against the stored bytes, and the refusal path.
Substituted here: lexical ranking (it needs Postgres, and this runs on the sqlite stand-in) and the model's sentence. So the ORDER of search results and the WORDING of an answer are not evidence of anything. Everything the engine decides around them is.
Ids and timestamps differ between runs, so they are shown as <id> and <timestamp>.
Long request bodies are shortened to their first line and ...; the request sent
carried the whole text.
1. Send a document
The Idempotency-Key is the caller's name for this DELIVERY. Send one every time: it
is what makes a retry after a timeout free and, more importantly, answerable.
POST /api/kee/v1/ingest
Idempotency-Key: nightly-2026-08-20:acme-msa:r1
{
"external_id": "contracts/acme-msa.md",
"title": "Acme Master Services Agreement",
"body": "## Section 1. Term ..."
}
201
{
"data": {
"action": "created",
"external_id": "contracts/acme-msa.md",
"artifact_id": "<id>",
"version_id": "<id>",
"spans": 2,
"event_sequence": 1,
"idempotent_replay": false
}
}
2. The same delivery again
The case a sync actually hits: the first call succeeded and the response was lost.
idempotent_replay: true says the work was already done, and event_sequence has NOT
advanced. Those two fields are the difference between a sync that converges and one
that re-sends its whole corpus to be sure.
POST /api/kee/v1/ingest
Idempotency-Key: nightly-2026-08-20:acme-msa:r1
{
"external_id": "contracts/acme-msa.md",
"title": "Acme Master Services Agreement",
"body": "the body is not consulted: the key already named this delivery"
}
201
{
"data": {
"action": "created",
"external_id": "contracts/acme-msa.md",
"artifact_id": "<id>",
"version_id": "<id>",
"spans": 2,
"event_sequence": 1,
"idempotent_replay": true
}
}
3. Send the amendment
A new delivery, a new key, a higher sequence. The engine treats supersession as a stewardship decision rather than an inference, so the amendment lands beside the agreement and a person confirms the relationship.
POST /api/kee/v1/ingest
Idempotency-Key: nightly-2026-08-20:acme-amendment-1:r1
{
"external_id": "contracts/acme-amendment-1.md",
"title": "Acme MSA Amendment 1",
"body": "## Amendment 1 ..."
}
201
{
"data": {
"action": "created",
"external_id": "contracts/acme-amendment-1.md",
"artifact_id": "<id>",
"version_id": "<id>",
"spans": 1,
"event_sequence": 2,
"idempotent_replay": false
}
}
4. What do you have from me
Filtered to this integration, and every entry carries the caller's OWN external_id
back. Without that a sync would have to keep its own mapping table, and any two
documents sharing a title would be indistinguishable.
GET /api/kee/v1/knowledge?source_slug=enterprise_push
200
{
"data": {
"items": [
{
"id": "<id>",
"title": "Acme MSA Amendment 1",
"origin": {
"source_type": "knowledge_source",
"label": "Knowledge source",
"source_id": null,
"project_id": null,
"conversation_id": null,
"source_slug": "enterprise_push",
"external_id": "contracts/acme-amendment-1.md"
},
"current_version": {
"version_id": "<id>",
"version_no": 1,
"ingested_at": "<timestamp>",
"chars": 81
},
"created_at": "<timestamp>"
},
{
"id": "<id>",
"title": "Acme Master Services Agreement",
"origin": {
"source_type": "knowledge_source",
"label": "Knowledge source",
"source_id": null,
"project_id": null,
"conversation_id": null,
"source_slug": "enterprise_push",
"external_id": "contracts/acme-msa.md"
},
"current_version": {
"version_id": "<id>",
"version_no": 1,
"ingested_at": "<timestamp>",
"chars": 150
},
"created_at": "<timestamp>"
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total": 2,
"last_page": 1
}
}
}
5. Hand over a large document
This body is small, so async: true asks for the queue explicitly. 202, not 201:
nothing is in the corpus yet. Bodies past the size ceiling and ALL file uploads take
this path automatically, because parsing a 340-page contract inside an HTTP request is
a timeout, and a timeout with no job id is the one failure a sync cannot recover from.
Poll through queued and running until succeeded or failed; there is no third
terminal state, and failed always carries a reason.
POST /api/kee/v1/ingest
Idempotency-Key: nightly-2026-08-20:acme-schedule-a:r1
{
"external_id": "contracts/acme-schedule-a.md",
"title": "Schedule A",
"body": "## Schedule A ...",
"async": true
}
202
{
"data": {
"job_id": "<id>",
"status": "queued",
"external_id": "contracts/acme-schedule-a.md",
"source_slug": "enterprise_push",
"action": null,
"artifact_id": null,
"version_id": null,
"spans": null,
"event_sequence": null,
"error": null,
"completed_at": null,
"idempotent_replay": false
}
}
GET /api/kee/v1/jobs/{job_id}
{
"data": {
"job_id": "<id>",
"status": "succeeded",
"external_id": "contracts/acme-schedule-a.md",
"source_slug": "enterprise_push",
"action": "created",
"artifact_id": "<id>",
"version_id": "<id>",
"spans": 1,
"event_sequence": 3,
"error": null,
"completed_at": "<timestamp>"
}
}
6. Ask a question
The answer is the least interesting part of this response. judgment.answer_support
counts how many sentences carry a citation; judgment.corpus_coverage reports how
much of the corpus was actually read, with a denominator. A partial read that reported
itself as complete is the bug this engine was built around.
POST /api/kee/v1/ask
{
"query": "how long is the term"
}
200
{
"data": {
"answer": "The initial term is thirty six months [S:<id>].",
"snapshot_id": "<id>",
"verification_status": "cited",
"refusal_reason": null,
"refusal_detail": null,
"stated_confidence": null,
"citations": {
"used_span_ids": [
"<id>"
],
"invented_markers_removed": 0,
"uncited_sentence_count": 0
},
"judgment": {
"answer_support": {
"sentences_total": 1,
"sentences_cited": 1,
"sentences_uncited": 0,
"spans_used": 1,
"spans_hash_verified": 1,
"invented_markers_removed": 0
},
"support_score": 1,
"corpus_coverage": {
"query_shape": "relevance",
"spans_considered": 1,
"spans_selected": 1,
"spans_dropped_verification": 0,
"spans_dropped_budget": 0,
"retrieval_truncated": false,
"documents": [
{
"artifact_version_id": "<id>",
"title": "Acme Master Services Agreement",
"spans_total": 2,
"spans_seen": 1,
"selection_strategy": "greedy_ranked",
"complete": false
}
],
"complete": true,
"index_status": "ready"
},
"known_gaps": [],
"verification_status": "cited",
"conflicts": {
"detected": 0,
"served": 0,
"pairs": [],
"detection": "lexical_v1"
},
"query_plan": {
"strategy": "ranked",
"query_shape": "relevance",
"reason": "the question is answerable from the most relevant passages",
"parameters": [],
"estimated_model_calls": 1,
"claims_completeness": false,
"read_strategy": "ranked",
"plan_fallback_reason": null
},
"execution": {
"stage": "drafted",
"terminal": true,
"stages_completed": [
"retrieved",
"drafted"
],
"remaining_actions": []
},
"assurance": {
"requested": "draft",
"applied": "draft",
"verification_mode": "shadow",
"reason": null
}
},
"evidence": [
{
"span_id": "<id>",
"quote_preview": "## Section 1. Term This Agreement continues for thirty six months from the Effective Date.",
"source_type": "knowledge_source",
"title": "Acme Master Services Agreement",
"source_document_id": null,
"source_conversation_id": null,
"version_id": "<id>",
"score": 1,
"authority": 0.92,
"support_count": 0,
"supported_by": [],
"conflicts_with": [],
"truncated": false
}
],
"retrieval": {
"mode": "lexical",
"query_shape": "relevance",
"watermark": "<timestamp>",
"index_status": "ready",
"embedding_coverage": "none"
},
"consistency": {
"mode": "latest_available",
"as_of_sequence": null,
"guarantees": {
"evidence_store": "best_effort",
"lexical_index": "best_effort"
}
}
}
}
Every [S:id] marker in the prose resolves to an exact passage, and the
resolution re-checks the stored bytes against the hash recorded at ingest.
available: false would mean the passage exists but no longer matches it.
GET /api/kee/v1/evidence/{span_id}
{
"data": {
"span_id": "<id>",
"available": true,
"quote": "## Section 1. Term\n\nThis Agreement continues for thirty six months from the Effective Date.",
"unavailable_reason": null,
"attestation": null,
"title": "Acme Master Services Agreement",
"source_type": "knowledge_source",
"source_document_id": null,
"source_conversation_id": null,
"version_id": "<id>",
"ingested_at": "<timestamp>"
}
}
7. Ask something the corpus cannot answer
THIS IS THE DEMO. Every other assistant in the room answers this question. The engine
declines, says so in verification_status, and does not spend a model call to do it.
A client should treat a refusal as the correct result rather than a failure, which is
why the MCP server says so in its handshake instructions.
POST /api/kee/v1/ask
{
"query": "how many customers asked for a refund after the outage"
}
200
{
"data": {
"answer": null,
"snapshot_id": "<id>",
"verification_status": "no_evidence",
"refusal_reason": "no_matching_evidence",
"refusal_detail": null,
"stated_confidence": null,
"citations": {
"used_span_ids": [],
"invented_markers_removed": 0,
"uncited_sentence_count": 0
},
"judgment": {
"answer_support": null,
"support_score": null,
"corpus_coverage": {
"query_shape": "coverage",
"spans_considered": 0,
"spans_selected": 0,
"spans_dropped_verification": 0,
"spans_dropped_budget": 0,
"retrieval_truncated": false,
"documents": [],
"complete": false,
"index_status": "ready"
},
"known_gaps": [],
"verification_status": "no_evidence",
"conflicts": {
"detected": 0,
"served": 0,
"pairs": [],
"detection": "lexical_v1"
},
"query_plan": {
"strategy": "ranked",
"query_shape": "coverage",
"reason": "coverage-shaped, but no single document is in scope, so position is undefined",
"parameters": [],
"estimated_model_calls": 1,
"claims_completeness": false,
"read_strategy": "ranked",
"plan_fallback_reason": null
},
"execution": {
"stage": "retrieved",
"terminal": true,
"stages_completed": [
"retrieved"
],
"remaining_actions": []
},
"assurance": {
"requested": "draft",
"applied": "draft",
"verification_mode": "shadow",
"reason": null
}
},
"evidence": [],
"retrieval": {
"mode": "lexical",
"query_shape": "coverage",
"watermark": "none",
"index_status": "ready",
"embedding_coverage": "none"
},
"consistency": {
"mode": "latest_available",
"as_of_sequence": null,
"guarantees": {
"evidence_store": "best_effort",
"lexical_index": "best_effort"
}
}
}
}
8. Delete
Deletion is ALWAYS explicit. A document you simply stop sending is not deleted, because "not in this batch" is also what a partial sync, a filtered query and a crashed job look like. The cost of that rule is that your sync has to notice removals itself; the benefit is that one bad run cannot erase a corpus.
DELETE /api/kee/v1/ingest/contracts/acme-schedule-a.md
Idempotency-Key: nightly-2026-08-20:delete:acme-schedule-a
200
{
"data": {
"action": "deleted",
"external_id": "contracts/acme-schedule-a.md",
"artifact_id": "<id>",
"event_sequence": 4,
"idempotent_replay": false
}
}
Repeating it, here without a key, succeeds and says which happened, so a converging sync and a looping one are distinguishable:
{
"data": {
"action": "already_deleted",
"external_id": "contracts/acme-schedule-a.md",
"artifact_id": "<id>",
"event_sequence": 4,
"idempotent_replay": false
}
}
An id we were never sent is a 404, not a cheerful 200. "I never sent you that" is a bug on the sync's side, and reporting success would let it delete nothing and believe it worked:
{
"error": "unknown_document",
"message": "No document with that external_id has been ingested by this account."
}
This page as raw markdown: /docs/worked-example.md. Everything at once: /docs/all.md. New to GPTree? Start with Learn.