Typed decision boundaries

bun:yolo adapts application-supplied judgments into Noul booleans, named Choice keys and finite Score values. Bun validates the request, provider response and primitive conversion natively. A judgment is a proposal; application permission rules still authorize any subsequent operation.

import { decide, noul, choice, score, type Provider } from "bun:yolo";

export async function selectSource(provider: Provider) {
  return await decide(
    {
      state: { query: "How do Bun.Video frames become images?", passage: "A curated source excerpt." },
      questions: {
        relevant: noul("Does `passage` help answer `query`?"),
        route: choice("Which source fits?", { docs: "API documentation", graph: "Source relationships" }),
        support: score("How directly does `passage` support `query`?", ["None", "Partial", "Direct"]),
      },
    },
    { provider, timeout: 10000, maxRetries: 0 },
  );
}
// relevant: boolean; route: "docs" | "graph"; support: number in 0..2

One named batch shares one provider request. inspect, also exported as systemOne, keeps the validated probabilities, model and usage. decide returns primitives. A Noul becomes true only when its probability is greater than threshold, which defaults to 0.5; equality returns false. Score can be fractional. Unknown answers, choice keys, distributions or legends are rejected.

Confidence and abstention

Choice abstention is a separate operation. Validate the minimum with confidenceThreshold(minimum) before calling the provider, then call selections(request, result, minimum) on an inspected response. It returns only Choice entries: the winning key when its confidence is at or above the minimum, otherwise null. Answers, distributions, model and usage stay unchanged. This confidence minimum is distinct from the Noul probability threshold.

Providers and limits

Supply your own Provider, or use the default remote() provider configured with the server-side TYPESAFE_API_KEY environment variable. code adapts deterministic or asynchronous callbacks through the same validation; local borrows a caller-owned bun-llama context without downloading weights. Local outputs are raw model judgments and are not calibrated. The full type definitions are in packages/bun-types/yolo.d.ts.

Batches contain 1–64 questions; Choice has 2–255 options and Score has 2–10 criteria. Request and response JSON are each limited to 1 MiB. timeout bounds the complete operation, including retries, to 1–120000 ms. maxRetries is 0–3, default 0. A caller AbortSignal cancels pending work. Typed judgments do not generate an explanatory answer: an application may generate text separately and then check its grounding against cited evidence.

Python SDK

The runtime SDK in packages/bun-runtime-sdk/python/ctypes provides bun_yolo.Yolo, noul, choice and score. It has no Python HTTP client or model engine. Each call sends a JSON envelope over stdin to a Bun worker, which calls inspect, decide or value from bun:yolo. Converted values return as Python bool, str or float. client.inspect(..., minimum_confidence=0.8) (alias system_one) returns the raw model, answers and usage, plus the computed selections. inspect_async and decide_async are the asynchronous variants.

import os
from pathlib import Path
from bun_yolo import Yolo, noul
from yolo_runtime import Runtime

with Runtime() as runtime:
    client = Yolo(runtime, Path(os.environ["BUN_EXECUTABLE"]))
    result = client.value({"type": "noul", "noul": 0.8}, noul("Fixture answer"))
    assert result is True

This example validates a supplied answer without model inference. Provider credentials come from the caller's configuration; no key is embedded in source. Yolo borrows the Runtime, accepts one active call per instance and never closes the borrowed handle. Each child process has at most 1 MiB of input and captured output. transport_timeout_ms bounds the wait for the worker (1–130000 ms, default 130000); options.timeout still bounds inference. cancel() cancels the pending operation, stops the child process and releases its handles. When the Python task running await client.decide_async(...) is cancelled, the call waits for native cleanup.

The runtime library must support the process.stdin and process.wait capabilities (C ABI 1.6 or later); older installations are refused before a process is created. State, tokens and provider bodies are never passed in argv, temporary files or diagnostics. Native errors return bounded names and codes without raw messages.