Document decisions

September 20, 2026 · View on GitHub

POST /v1/documents/decide answers typed questions about plain text or JSON documents.

For each question, OpenDecision:

Serializes the document.
Keeps a small document intact.
Splits a long document by headings, paragraphs, and token limits.
Ranks sections for the question.
Runs the selected primitive on the relevant text.
Returns the answer and the source passages used.

The splitter and retriever contain no insurance or GDPR vocabulary.

Request

{
  "document": {
    "policy": {
      "collision": true,
      "deductible": 500
    },
    "claim": {
      "description": "The parked vehicle was rear-ended."
    }
  },
  "noul_mode": "both",
  "top_k": 4,
  "chunk_tokens": 384,
  "questions": {
    "covered": {
      "type": "noul",
      "instructions": "Is collision coverage active?"
    }
  }
}

Field	Meaning	Default
`document`	Plain text, JSON, or another JSON value	Required
`questions`	Named typed questions	Required
`noul_mode`	Evaluation mode for document `Noul` questions	`both`
`top_k`	Maximum relevant passages per answer	`4`
`chunk_tokens`	Maximum tokens in a document section	`384`

Noul modes

The mode applies only to Noul questions sent to the document endpoint.

`binary`

Returns a forced true or false answer with two probabilities.

{
  "mode": "binary",
  "answer": true,
  "status": "binary",
  "binary": {
    "answer": true,
    "probabilities": {"true": 0.82, "false": 0.18},
    "confidence": 0.82
  },
  "three_way": null
}

`three_way`

Returns an evidence relation:

supports maps to answer: true.
contradicts maps to answer: false.
unknown maps to answer: null.
A binary NLI backend can also return conflicted, which maps to answer: null.

`both`

Runs the binary and three-way evaluations and keeps both distributions.

Status	Meaning	Combined answer
`confirmed`	Binary and three-way agree.	`true` or `false`
`tentative`	Binary chooses an answer and three-way returns no answer.	Binary answer
`conflicted`	Binary and three-way disagree.	`null`

Binary and three-way scores measure different distributions. OpenDecision keeps them separate.

Example response:

{
  "type": "document_noul",
  "mode": "both",
  "answer": true,
  "status": "confirmed",
  "binary": {
    "answer": true,
    "probabilities": {"true": 0.82, "false": 0.18},
    "confidence": 0.82
  },
  "three_way": {
    "answer": true,
    "relation": "supports",
    "scores": {
      "supports": 0.76,
      "contradicts": 0.08,
      "unknown": 0.16
    }
  }
}

The numbers above only show the response shape.

How raw yes/no questions are compiled

A document Noul question without explicit criteria uses one visible template:

The answer to the question "<original question>" is yes.
The answer to the question "<original question>" is no.

The response includes both compiled statements in compiled and the compiler name in compiler.

Supply explicit criteria when exact wording matters:

{
  "type": "noul",
  "instructions": "Is the certificate current?",
  "criteria": {
    "true": "The supplier certificate is current.",
    "false": "The supplier certificate is expired."
  }
}

Evidence in responses

Every document answer includes its selected passages:

{
  "evidence": [
    {
      "id": "section-004",
      "text": "Collision coverage is active with a \$500 deductible.",
      "relevance": 0.93
    }
  ]
}

Relevance scores rank passages for the current question. Treat them as uncalibrated.