Decision from raw signals

post/ds

Analyzes raw numeric series (signals) and answers your question using the candidate answers in options.

Use kind to choose the answer format: set (default, select all that apply), choice (pick one), or boolean (yes/no).

Body ParametersExpand Collapse

question: string

allow_abstain: optional boolean

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

Audio clips to decide over: each {b64, mime} or {url}. Only on deployments where /capabilities reports audio available.

b64: optional string

Base64-encoded audio bytes.

mime: optional string

MIME type for b64 content.

url: optional string

Public HTTP(S) audio URL.

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 string

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

SetDecision = object { evidence, latency_ms, mode, 14 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" or "audio"

The mode that ran. audio is reported when an audio clip was decided directly; it cannot be sent as a request mode.

Accepts one of the following:

"fast"

"deep"

"audio"

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: "set"

Accepts one of the following:

"set"

value: unknown

Options with probability ≥ 0.5, in request order.

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.

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, or (remaining) for documents that were never read because the context limit was already reached.

status: "included" or "skipped"

Accepts one of the following:

"included"

"skipped"

chars: optional number

Number of characters extracted.

reason: optional string

Why the document was skipped.

tokens: optional number

truncated: optional boolean

Present and true on an included document whose text was cut to fit the context limit (about 48,000 characters).

document_tokens: optional number

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

image_tokens: optional number

Image-specific subset of input_tokens.

input_tokens: optional number

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

probabilities: optional map[number]

Independent P(option applies) for each option. Does not sum to 1.

think_allowed: optional boolean

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

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" or "audio"

The mode that ran. audio is reported when an audio clip was decided directly; it cannot be sent as a request mode.

Accepts one of the following:

"fast"

"deep"

"audio"

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"

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, or (remaining) for documents that were never read because the context limit was already reached.

status: "included" or "skipped"

Accepts one of the following:

"included"

"skipped"

chars: optional number

Number of characters extracted.

reason: optional string

Why the document was skipped.

tokens: optional number

truncated: optional boolean

Present and true on an included document whose text was cut to fit the context limit (about 48,000 characters).

document_tokens: optional number

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

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.

read_as: optional map[unknown]

Present on /decide when outcomes is omitted: reports how Bivia auto-framed the question (read_as, question, choices, range).

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": "set",
  "value": {},
  "verification": {
    "performed": true,
    "result": "passed"
  },
  "abstain_reason": "low_confidence",
  "billable_tokens": 0,
  "document_notes": [
    {
      "document": "document",
      "status": "included",
      "chars": 0,
      "reason": "reason",
      "tokens": 0,
      "truncated": true
    }
  ],
  "document_tokens": 0,
  "image_tokens": 0,
  "input_tokens": 0,
  "probabilities": {
    "foo": 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": "set",
  "value": {},
  "verification": {
    "performed": true,
    "result": "passed"
  },
  "abstain_reason": "low_confidence",
  "billable_tokens": 0,
  "document_notes": [
    {
      "document": "document",
      "status": "included",
      "chars": 0,
      "reason": "reason",
      "tokens": 0,
      "truncated": true
    }
  ],
  "document_tokens": 0,
  "image_tokens": 0,
  "input_tokens": 0,
  "probabilities": {
    "foo": 0
  },
  "think_allowed": true
}