Decision from raw signals

post/ds

Makes a decision based on raw numeric signals. The server profiles the signal data (statistics, distribution, anomalies) and folds the analysis into context before deciding.

kind selects the decision type: set (default, multi-select), choice (pick one), or boolean (yes/no). Candidates must be in options.

Body ParametersExpand Collapse

question: string

allow_abstain: optional boolean

documents: optional array of object { b64, filename, mime, url }

b64: optional string

Base64-encoded file bytes.

filename: optional string

Helps format detection (e.g., memo.txt, contract.pdf).

mime: optional string

MIME type of the document.

url: optional string

Public HTTP(S) URL to fetch the document from.

domain: optional string

images: optional array of object { b64, mime, url }

b64: optional string

Base64-encoded image bytes (raw base64, not a data: URL). Pair with mime.

mime: optional string

MIME type for b64 content. Must be an image/* type.

url: optional string

Public HTTP(S) image URL. The server fetches it within a shared 60-second budget.

kind: optional "set" or "choice" or "boolean"

Which decision type to use.

Accepts one of the following:

"set"

"choice"

"boolean"

mode: optional "fast" or "deep"

fast — single-pass inference (lowest latency, default). deep — adds a verification step for higher confidence on hard questions. Any other value is rejected (422).

Accepts one of the following:

"fast"

"deep"

options: optional array of unknown

Candidate answers. Required for useful choice or set results.

signals: optional array of object { data, channels, dtype, 2 more }

Raw numeric signals to analyze.

data: unknown

Signal data as [channels][timesteps] (list of lists). Each inner list is one channel of samples.

channels: optional number

Number of channels (required when data is a base64 buffer).

dtype: optional string

Data type when data is a base64 buffer.

fs: optional number

Sample rate in Hz.

name: optional string

Human-readable name for the signal.

state: optional string

think: optional boolean

ReturnsExpand Collapse

CategoricalDecision = object { evidence, latency_ms, mode, 16 more }

evidence: object { spans }

spans: optional array of object { end, start, text }

Character ranges in the input text that support the decision.

end: number

Exclusive character offset.

start: number

Inclusive character offset into the state text.

text: string

The quoted substring.

latency_ms: number

Server-side processing time in milliseconds.

mode: "fast" or "deep"

Accepts one of the following:

"fast"

"deep"

model: string

The model that produced this decision.

status: "answered" or "abstained"

answered — the model produced a confident answer. abstained — the model was not confident enough; value is null.

Accepts one of the following:

"answered"

"abstained"

thought: boolean

Whether a reasoning trace was actually generated.

type: "decide" or "choice" or "boolean"

Accepts one of the following:

"decide"

"choice"

"boolean"

value: unknown

verification: object { performed, result }

performed: boolean

Whether the verification step ran (only in deep mode).

result: "passed" or "conflict" or "insufficient" or "not_applicable"

passed — verification confirmed the answer. conflict — verification disagreed (triggers abstention in deep mode). insufficient — not enough evidence to verify. not_applicable — verification was not performed (fast mode).

Accepts one of the following:

"passed"

"conflict"

"insufficient"

"not_applicable"

abstain_reason: optional "low_confidence" or "readout_disagreement" or "insufficient_evidence" or "unresolved_after_thinking"

Why the model abstained. null when status is answered.

low_confidence — probability mass was too spread out.
readout_disagreement — deep verification found a conflict.
insufficient_evidence — not enough context to decide.
unresolved_after_thinking — reasoning did not resolve ambiguity.

Accepts one of the following:

"low_confidence"

"readout_disagreement"

"insufficient_evidence"

"unresolved_after_thinking"

billable_tokens: optional number

Billing token count = max(1000, input_tokens). This is the number used for usage metering, with a per-decision floor of 1,000 tokens.

distribution: optional map[number]

Probability of each label, summing to 1. Present even on abstention. For boolean decisions, keys are yes and no.

document_notes: optional array of object { document, status, chars, 3 more }

Per-document extraction status. Present when documents were sent.

document: string

Filename or URL of the document.

status: "included" or "truncated" or "skipped"

Accepts one of the following:

"included"

"truncated"

"skipped"

chars: optional number

Number of characters extracted.

reason: optional string

Why the document was truncated or skipped.

tokens: optional number

truncated: optional boolean

document_tokens: optional number

Document-specific subset of input_tokens. Present when documents were sent.

grounded: optional boolean

true when the answer is grounded in the provided context (a direct readout). false when the answer is free-form generation.

image_tokens: optional number

Image-specific subset of input_tokens.

input_tokens: optional number

Total tokens processed (text + images + documents + audio).

probability: optional number

P(value). Omitted when the model abstains.

think_allowed: optional boolean

Whether thinking was allowed for this call. Only present in fast mode.

Decision from raw signals

curl https://api.articul8.ai/bivia/ds \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $A8_API_KEY" \
    -d '{
          "question": "Which analysis method fits this signal?"
        }'

{
  "evidence": {
    "spans": [
      {
        "end": 0,
        "start": 0,
        "text": "text"
      }
    ]
  },
  "latency_ms": 0,
  "mode": "fast",
  "model": "dec-1",
  "status": "answered",
  "thought": true,
  "type": "decide",
  "value": {},
  "verification": {
    "performed": true,
    "result": "passed"
  },
  "abstain_reason": "low_confidence",
  "billable_tokens": 0,
  "distribution": {
    "foo": 0
  },
  "document_notes": [
    {
      "document": "document",
      "status": "included",
      "chars": 0,
      "reason": "reason",
      "tokens": 0,
      "truncated": true
    }
  ],
  "document_tokens": 0,
  "grounded": true,
  "image_tokens": 0,
  "input_tokens": 0,
  "probability": 0,
  "think_allowed": true
}

Returns Examples

{
  "evidence": {
    "spans": [
      {
        "end": 0,
        "start": 0,
        "text": "text"
      }
    ]
  },
  "latency_ms": 0,
  "mode": "fast",
  "model": "dec-1",
  "status": "answered",
  "thought": true,
  "type": "decide",
  "value": {},
  "verification": {
    "performed": true,
    "result": "passed"
  },
  "abstain_reason": "low_confidence",
  "billable_tokens": 0,
  "distribution": {
    "foo": 0
  },
  "document_notes": [
    {
      "document": "document",
      "status": "included",
      "chars": 0,
      "reason": "reason",
      "tokens": 0,
      "truncated": true
    }
  ],
  "document_tokens": 0,
  "grounded": true,
  "image_tokens": 0,
  "input_tokens": 0,
  "probability": 0,
  "think_allowed": true
}