Module arrow 

Unofficial bulk Arrow IPC endpoint (POST /v1/arrow, opt-in). Unofficial Arrow bulk endpoint: POST /v1/arrow.

Inspired by the proposal in “What if Jev spoke Arrow?”: one request carries many independent states plus a single shared question map, and the answer comes back as an Apache Arrow IPC stream: one row per state, one column per question.

This surface is not part of the TypeSafe wire contract. It is flag-gated (openkindd --arrow on), absent from openapi.yaml, and must never leak into the /v1/systemone shapes or the SDK compatibility tests. See docs/ARROW.md for the full mapping and its limits.

Wire shape (JSON in, Arrow out):

{
  "model": "jev-latest",
  "states": ["Please refund the shoes.", {"cart": ["shoes"]}],
  "questions": { "refund": { "type": "noul", "instructions": "Is a refund being requested?" } }
}

Each question id becomes an Arrow column whose type encodes the answer:

Jev type	Arrow type	Field metadata
Noul	float64	jev.type = "noul"
Choice	struct<choice: uint8, confidence: float64, probabilities: fixed_size_list<float64>[N]>	jev.type = "choice", labels (JSON array, sorted option keys)
Score	struct<score: float64, confidence: float64, probabilities: fixed_size_list<float64>[N]>	jev.type = "score", legend (JSON array of level descriptions in rubric order)

Columns are ordered by question id (lexicographic). Row i is the answer for states[i]. All fields are non-nullable: the endpoint evaluates every state or fails the whole request.

Structs

ArrowBatchRequest

Bulk evaluation request body for POST /v1/arrow.

Constants

ARROW_BATCH_TIMEOUT

Queue-inclusive deadline for the complete bulk evaluation and encoding.

ARROW_CONTENT_TYPE

Content-Type of the Arrow IPC stream response.

ARROW_MAPPING_VERSION

Value of META_ARROW_VERSION in every response stream.

MAX_ARROW_RESPONSE_BYTES

Maximum projected column-buffer size and encoded IPC response size (64 MiB).

MAX_ARROW_STATES

Maximum number of states in one bulk request. Mirrors the DoS budget of openkind_core::MAX_QUESTIONS_PER_REQUEST; beyond this, callers chunk their states across requests.

MAX_CHOICE_LABELS

Maximum number of Choice options a question may have on this endpoint. The choice child column is a uint8 index into labels, so more than 256 options cannot be represented; core allows up to openkind_core::MAX_CRITERIA_OPTIONS on /v1/systemone.

META_ARROW_VERSION

Schema metadata: format version of this unofficial mapping.

META_JEV_TYPE

Field metadata on every question column: the Jev question type.

META_LABELS

Field metadata on Choice columns: JSON array of option keys, sorted.

META_LEGEND

Field metadata on Score columns: JSON array of level descriptions, in rubric order.

META_MODEL

Schema metadata: model that performed the evaluation.

META_USAGE_INPUT_TOKENS

Schema metadata: aggregate input tokens across all states.

META_USAGE_OUTPUT_TOKENS

Schema metadata: aggregate output tokens across all states.

Functions

answers_from_batch

Reconstruct Jev answers from a version-1 batch produced by this module.

arrow_batch

Handler for the unofficial POST /v1/arrow bulk endpoint.