Skip to content

Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦

C

brio: many questions on one state, and a JSON object filled one field at a time

JustVugg07b8d0653a2a
diff --git a/c/openai_server.py b/c/openai_server.py
index 252c453b..42fe3635 100644
--- a/c/openai_server.py
+++ b/c/openai_server.py
@@ -3905,22 +3905,81 @@ class APIHandler(BaseHTTPRequestHandler):
# COSA TORNA. Non solo il vincitore: la probabilita di OGNI opzione e
# l'entropia. E' la differenza con la generazione, che una risposta la da
# sempre e con la stessa faccia: qui "non lo so" e' un numero.
- def brio(self, body, request_id):
- options = body.get("options")
+ # TRE FORME, UN ENDPOINT. `options` e' la domanda singola. `questions` e'
+ # un elenco di domande sullo stesso stato, ognuna con le sue opzioni: lo
+ # stato viene fotografato una volta e ogni domanda paga solo se stessa,
+ # che e' dove sta il 5,7x misurato. `schema` e' un oggetto campo -> valori
+ # ammessi: il server scrive lo scheletro JSON, casella per casella, e per
+ # ognuna legge il logprob di ciascun valore. Il JSON non puo' uscire
+ # malformato perche' non lo scrive il modello. Prima queste due forme
+ # esistevano solo come script di misura: chi integrava doveva riscriverle.
+ @staticmethod
+ def _brio_options(options, where):
if not isinstance(options, list) or not options:
- raise APIError(400, "`options` must be a non-empty array of strings.", "options")
+ raise APIError(400, f"`{where}` must be a non-empty array of strings.", where)
if len(options) > 64:
- raise APIError(400, "`options` accepts at most 64 entries.", "options")
+ raise APIError(400, f"`{where}` accepts at most 64 entries.", where)
seen = set()
for option in options:
if not isinstance(option, str) or not option.strip():
- raise APIError(400, "Every option must be a non-empty string.", "options")
+ raise APIError(400, f"Every entry of `{where}` must be a non-empty string.", where)
if option in seen:
- raise APIError(400, f"Duplicate option: {option!r}.", "options")
+ raise APIError(400, f"Duplicate option in `{where}`: {option!r}.", where)
seen.add(option)
+ if len(options) < 2:
+ raise APIError(400, f"`{where}` needs at least two options to choose between.", where)
+ return options
+
+ def brio(self, body, request_id):
+ forms = [k for k in ("options", "questions", "schema") if body.get(k) is not None]
+ if len(forms) != 1:
+ raise APIError(400, "Provide exactly one of `options`, `questions` or `schema`.",
+ forms[0] if forms else "options")
+ form = forms[0]
question = body.get("question")
if question is not None and not isinstance(question, str):
raise APIError(400, "`question` must be a string.", "question")
+ options = questions = schema = None
+ if form == "options":
+ options = self._brio_options(body["options"], "options")
+ elif form == "questions":
+ raw = body["questions"]
+ if not isinstance(raw, list) or not raw:
+ raise APIError(400, "`questions` must be a non-empty array.", "questions")
+ if len(raw) > 64:
+ raise APIError(400, "`questions` accepts at most 64 entries.", "questions")
+ questions = []
+ for i, entry in enumerate(raw):
+ if not isinstance(entry, dict):
+ raise APIError(400, f"`questions[{i}]` must be an object.", "questions")
+ text = entry.get("question")
+ if not isinstance(text, str) or not text.strip():
+ raise APIError(400, f"`questions[{i}].question` must be a non-empty string.",
+ "questions")
+ per = entry.get("normalize", body.get("normalize", "mean"))
+ if per not in ("mean", "sum"):
+ raise APIError(400, "`normalize` must be \"mean\" or \"sum\".", "normalize")
+ questions.append((text, self._brio_options(entry.get("options"),
+ f"questions[{i}].options"), per))
+ else:
+ raw = body["schema"]
+ if not isinstance(raw, dict) or not raw:
+ raise APIError(400, "`schema` must be a non-empty object of field: [values].",
+ "schema")
+ if len(raw) > 64:
+ raise APIError(400, "`schema` accepts at most 64 fields.", "schema")
+ schema = []
+ for field, values in raw.items():
+ if not isinstance(field, str) or not field.strip():
+ raise APIError(400, "Every `schema` field name must be a non-empty string.",
+ "schema")
+ if any(ch in field for ch in '"\\\n'):
+ raise APIError(400, f"`schema` field {field!r} cannot contain quotes, "
+ "backslashes or newlines.", "schema")
+ schema.append((field, self._brio_options(values, f"schema.{field}")))
+ task = body.get("task")
+ if task is not None and not isinstance(task, str):
+ raise APIError(400, "`task` must be a string.", "task")
state = body.get("state")
messages = body.get("messages")
if state is not None and not isinstance(state, str):
@@ -3939,8 +3998,10 @@ class APIHandler(BaseHTTPRequestHandler):
if content:
parts.append(f"{message.get('role', 'user')}: {content}")
state = "\n".join(parts)
- if not state and not question:
+ if not state and not question and form == "options":
raise APIError(400, "Provide `state`, `messages` or `question`.", "state")
+ if not state and form != "options":
+ raise APIError(400, f"`{form}` needs a `state` (or `messages`) to decide on.", "state")
normalize = body.get("normalize", "mean")
if normalize not in ("mean", "sum"):
raise APIError(400, "`normalize` must be \"mean\" or \"sum\".", "normalize")
@@ -3957,14 +4018,10 @@ class APIHandler(BaseHTTPRequestHandler):
or not 0 <= cache_slot < self.server.kv_slots:
raise APIError(400, "Invalid cache slot.", "cache_slot")
- prefix = ""
- if state:
- prefix += f"Context:\n{state}\n\n"
- if question:
- prefix += f"Question: {question}\n"
- prefix += "Answer:"
-
+ state_prefix = f"Context:\n{state}\n\n" if state else ""
started = time.time()
+ read_total = 0
+ prompt_max = 0
with self.server.scheduler.admit(self.client_disconnected, cache_slot) as admission:
queue_wait, cache_slot = admission
@@ -3984,56 +4041,103 @@ class APIHandler(BaseHTTPRequestHandler):
text, 0, 0.0, 1.0, lambda _chunk: None, cache_slot,
self.client_disconnected, logprobs=1, pin=pin,
on_echo=echoes.append, on_accept=on_accept)
- return accepted.get("prompt_tokens"), echoes
-
- # 1) il prefisso condiviso, fotografato una volta
- n_prefix, echoes = score(prefix, True)
- if n_prefix is None: # motore senza ACCEPT (olmoe)
- n_prefix = max((e["pos"] for e in echoes), default=-1) + 1
-
- # 2) un giro per opzione: paga solo i propri token
- scored = []
- for option in options:
- # Il cliente se n'e andato: smettere subito invece di macinare
- # le opzioni restanti per nessuno. Con una sola slot KV un menu
- # lungo abbandonato la terrebbe occupata per minuti, e le
- # richieste dietro andrebbero in coda fino al timeout -- e'
- # cosi che sono usciti i primi 429.
- if self.client_disconnected():
- raise ClientCancelled()
- _, tail = score(prefix + " " + option, False)
- rows = [e for e in tail if e["pos"] >= n_prefix and e["logprob"] is not None]
- total = sum(e["logprob"] for e in rows)
- count = max(len(rows), 1)
- scored.append({"option": option, "logprob": total, "tokens": len(rows),
- "mean_logprob": total / count})
-
- if not any(entry["tokens"] for entry in scored):
- raise APIError(502, "The engine returned no log probabilities for the options.",
- None, "engine_error", "server_error")
- key = "mean_logprob" if normalize == "mean" else "logprob"
- top = max(entry[key] for entry in scored)
- weights = [math.exp(entry[key] - top) for entry in scored]
- total_weight = sum(weights) or 1.0
- for entry, weight in zip(scored, weights):
- entry["p"] = weight / total_weight
- scored.sort(key=lambda entry: -entry["p"])
- entropy = -sum(e["p"] * math.log(max(e["p"], 1e-12)) for e in scored)
- entropy /= math.log(max(len(scored), 2))
-
- self.send_json(200, {
+ n = accepted.get("prompt_tokens")
+ if n is None: # motore senza ACCEPT (olmoe)
+ n = max((e["pos"] for e in echoes), default=-1) + 1
+ return n, echoes
+
+ def choose(prefix, choices, norm):
+ """Fotografa `prefix`, poi un giro per opzione: ognuna paga solo
+ i propri token. Torna (scored, entropia, token del prefisso)."""
+ nonlocal read_total, prompt_max
+ n_prefix, _ = score(prefix, True)
+ prompt_max = max(prompt_max, n_prefix)
+ scored = []
+ for option in choices:
+ # Il cliente se n'e andato: smettere subito invece di
+ # macinare le opzioni restanti per nessuno. Con una sola
+ # slot KV un menu lungo abbandonato la terrebbe occupata
+ # per minuti, e le richieste dietro andrebbero in coda fino
+ # al timeout -- e' cosi che sono usciti i primi 429.
+ if self.client_disconnected():
+ raise ClientCancelled()
+ _, tail = score(prefix + " " + option, False)
+ rows = [e for e in tail if e["pos"] >= n_prefix and e["logprob"] is not None]
+ total = sum(e["logprob"] for e in rows)
+ count = max(len(rows), 1)
+ scored.append({"option": option, "logprob": total, "tokens": len(rows),
+ "mean_logprob": total / count})
+ if not any(entry["tokens"] for entry in scored):
+ raise APIError(502, "The engine returned no log probabilities for the "
+ "options.", None, "engine_error", "server_error")
+ key = "mean_logprob" if norm == "mean" else "logprob"
+ top = max(entry[key] for entry in scored)
+ weights = [math.exp(entry[key] - top) for entry in scored]
+ total_weight = sum(weights) or 1.0
+ for entry, weight in zip(scored, weights):
+ entry["p"] = weight / total_weight
+ scored.sort(key=lambda entry: -entry["p"])
+ entropy = -sum(e["p"] * math.log(max(e["p"], 1e-12)) for e in scored)
+ entropy /= math.log(max(len(scored), 2))
+ read_total += sum(e["tokens"] for e in scored)
+ return scored, round(entropy, 6), n_prefix
+
+ # Lo stato da solo, fotografato per primo: e' il livello che tutte
+ # le domande (o tutte le caselle) condividono. Con un livello solo
+ # la domanda si rilegge una volta per opzione; con due, 176 token
+ # invece di 496 su quattro item (misurato).
+ if state_prefix and form != "options":
+ n_state, _ = score(state_prefix, True)
+ prompt_max = max(prompt_max, n_state)
+
+ if form == "options":
+ prefix = state_prefix
+ if question:
+ prefix += f"Question: {question}\n"
+ prefix += "Answer:"
+ scored, entropy, _ = choose(prefix, options, normalize)
+ result = {"object": "brio.choice", "answer": scored[0]["option"],
+ "entropy": entropy, "normalize": normalize, "choices": scored}
+
+ elif form == "questions":
+ answers = []
+ for text, choices, norm in questions:
+ prefix = state_prefix + f"Question: {text}\nAnswer:"
+ scored, entropy, _ = choose(prefix, choices, norm)
+ answers.append({"question": text, "answer": scored[0]["option"],
+ "entropy": entropy, "normalize": norm,
+ "choices": scored})
+ result = {"object": "brio.answers", "answers": answers}
+
+ else:
+ # Lo scheletro JSON e' DATO: parentesi, virgolette e nomi dei
+ # campi li scriviamo noi, il modello sceglie solo il valore. Ogni
+ # casella si fotografa con dentro le scelte gia fatte, cosi il
+ # campo dopo vede quelli prima, come nella generazione.
+ head = state_prefix + (f"Task: {task}\n" if task else "")
+ filled, fields = {}, []
+ for field, values in schema:
+ skeleton = "{" + "".join(
+ f'"{k}": {json.dumps(v)}, ' for k, v in filled.items())
+ prefix = head + skeleton + f'"{field}": "'
+ scored, entropy, _ = choose(prefix, values, normalize)
+ filled[field] = scored[0]["option"]
+ fields.append({"field": field, "value": scored[0]["option"],
+ "p": scored[0]["p"], "entropy": entropy,
+ "choices": scored})
+ result = {"object": "brio.schema", "json": filled, "fields": fields,
+ "normalize": normalize}
+
+ result.update({
"id": "brio-" + uuid.uuid4().hex,
- "object": "brio.choice",
"created": int(time.time()),
"model": self.server.model_id,
- "answer": scored[0]["option"],
- "entropy": round(entropy, 6),
- "normalize": normalize,
- "choices": scored,
- "usage": {"prompt_tokens": n_prefix, "completion_tokens": 0,
- "read_tokens": sum(e["tokens"] for e in scored),
- "total_tokens": n_prefix + sum(e["tokens"] for e in scored)},
- }, request_id, {"x-colibri-queue-wait-ms": str(round(queue_wait * 1000)),
+ "usage": {"prompt_tokens": prompt_max, "completion_tokens": 0,
+ "read_tokens": read_total,
+ "total_tokens": prompt_max + read_total},
+ })
+ self.send_json(200, result, request_id,
+ {"x-colibri-queue-wait-ms": str(round(queue_wait * 1000)),
"x-colibri-elapsed-ms": str(round((time.time() - started) * 1000))})
def _fail(self, error, request_id):
diff --git a/c/tests/test_brio_api.py b/c/tests/test_brio_api.py
new file mode 100644
index 00000000..e95c4cb3
--- /dev/null
+++ b/c/tests/test_brio_api.py
@@ -0,0 +1,210 @@
+"""The three forms of POST /v1/brio, driven through the gateway with a scoring
+engine we control.
+
+`options` is one closed question. `questions` is many questions on one state,
+each with its own options, and the state must be photographed ONCE: that is
+where the measured 5.7x lives, and a handler that re-reads the state per
+question would still answer correctly while throwing the saving away, so the
+pin order is asserted, not just the answers. `schema` fills a JSON object one
+field at a time; the skeleton is data the server writes, so the field after
+must see the value chosen for the field before, and nothing is ever generated.
+
+The fake engine tokenises on whitespace and scores an option by a table, so
+every answer here is chosen by the test, not by chance. It records every
+call: prompt, max_tokens and pin, which is what the assertions read.
+"""
+import json
+import math
+import unittest
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+import openai_server
+from openai_server import APIServer
+
+STATE = "340 lines across 8 files, no tests. CI is green but nothing covers that path."
+
+
+class ScoringEngine:
+ """Scores like the real channel, deterministically.
+
+ `table` maps an option string to the mean log-probability its tokens get;
+ anything not in the table scores -5.0. A pinned call answers with ACCEPT
+ (prompt_tokens) and one ECHO per position, like an engine with the channel."""
+
+ def __init__(self, table):
+ self.table = table
+ self.calls = []
+ self.kv_slots = 1
+
+ def generate(self, prompt, max_tokens, temperature, top_p, on_text, cache_slot=0,
+ cancelled=None, grammar=None, stopped=None, on_accept=None, audio=None,
+ on_tool=None, image=None, logprobs=0, pin=False, on_echo=None):
+ self.calls.append({"prompt": prompt, "max_tokens": max_tokens, "pin": bool(pin),
+ "logprobs": logprobs})
+ words = prompt.split()
+ if on_accept:
+ on_accept({"prompt_tokens": len(words)})
+ if on_echo and logprobs:
+ # The option is whatever follows the last "Answer:" or the last
+ # opening quote of a skeleton cell; score its words from the table.
+ option = None
+ for key in self.table:
+ if prompt.endswith(" " + key):
+ option = key
+ per_token = self.table.get(option, -5.0)
+ for pos, _word in enumerate(words):
+ on_echo({"pos": pos, "logprob": per_token if option and pos >= len(words) - len(option.split()) else -1.0})
+
+ def close(self):
+ pass
+
+
+class BrioApi(unittest.TestCase):
+ def serve(self, table):
+ self.engine = ScoringEngine(table)
+ self.server = APIServer(("127.0.0.1", 0), self.engine, "test-model")
+ self.addCleanup(self.server.shutdown)
+ self.addCleanup(self.server.server_close)
+ import threading
+ threading.Thread(target=self.server.serve_forever, daemon=True).start()
+ self.base = f"http://127.0.0.1:{self.server.server_port}"
+
+ def post(self, body):
+ request = Request(self.base + "/v1/brio", data=json.dumps(body).encode(),
+ headers={"Content-Type": "application/json"})
+ with urlopen(request, timeout=10) as response:
+ return json.loads(response.read())
+
+ def post_error(self, body):
+ try:
+ self.post(body)
+ except HTTPError as error:
+ return error.code, json.loads(error.read())
+ self.fail("expected an error")
+
+ def pins(self):
+ return [c["prompt"] for c in self.engine.calls if c["pin"]]
+
+ # ---- options: the single form is unchanged ------------------------------
+ def test_single_form_still_answers_and_never_generates(self):
+ self.serve({"merge": -3.0, "request changes": -0.2, "close": -4.0})
+ out = self.post({"model": "test-model", "state": STATE,
+ "question": "What should the reviewer do?",
+ "options": ["merge", "request changes", "close"]})
+ self.assertEqual(out["object"], "brio.choice")
+ self.assertEqual(out["answer"], "request changes")
+ self.assertEqual(out["usage"]["completion_tokens"], 0)
+ self.assertTrue(all(c["max_tokens"] == 0 for c in self.engine.calls))
+ # one photograph, of the whole prefix; the options are never pinned
+ self.assertEqual(len(self.pins()), 1)
+ self.assertTrue(self.pins()[0].endswith("Answer:"))
+
+ # ---- questions: many on one state ----------------------------------------
+ def test_questions_share_one_state_photograph(self):
+ self.serve({"merge": -3.0, "request changes": -0.2, "close": -4.0,
+ "yes": -0.1, "no": -2.0, "high": -0.3, "low": -1.5})
+ out = self.post({"model": "test-model", "state": STATE, "questions": [
+ {"question": "What should the reviewer do?",
+ "options": ["merge", "request changes", "close"]},
+ {"question": "Does it need tests?", "options": ["yes", "no"]},
+ {"question": "How risky is it?", "options": ["high", "low"], "normalize": "sum"},
+ ]})
+ self.assertEqual(out["object"], "brio.answers")
+ self.assertEqual([a["answer"] for a in out["answers"]],
+ ["request changes", "yes", "high"])
+ self.assertEqual([a["normalize"] for a in out["answers"]], ["mean", "mean", "sum"])
+ for answer in out["answers"]:
+ self.assertAlmostEqual(sum(c["p"] for c in answer["choices"]), 1.0, places=6)
+ self.assertGreaterEqual(answer["entropy"], 0.0)
+ self.assertLessEqual(answer["entropy"], 1.0)
+ # The state is photographed exactly once, first, on its own; then each
+ # question once. Options are never pinned. This is the two-level order
+ # that makes the second question cost only its own words.
+ pins = self.pins()
+ self.assertEqual(len(pins), 4, pins)
+ self.assertEqual(pins[0], f"Context:\n{STATE}\n\n")
+ for pin, entry in zip(pins[1:], out["answers"]):
+ self.assertTrue(pin.startswith(pins[0]), "a question prefix must extend the state")
+ self.assertTrue(pin.endswith(f"Question: {entry['question']}\nAnswer:"))
+ self.assertEqual(out["usage"]["completion_tokens"], 0)
+ self.assertEqual(out["usage"]["read_tokens"],
+ sum(c["tokens"] for a in out["answers"] for c in a["choices"]))
+
+ # ---- schema: a JSON object filled one cell at a time --------------------
+ def test_schema_fills_cells_in_order_and_each_cell_sees_the_ones_before(self):
+ self.serve({"merge": -3.0, "request changes": -0.2, "close": -4.0,
+ "yes": -0.1, "no": -2.0, "engine": -0.05, "docs": -3.0})
+ out = self.post({"model": "test-model", "state": STATE,
+ "task": "Review this pull request.",
+ "schema": {"decision": ["merge", "request changes", "close"],
+ "needs_tests": ["yes", "no"],
+ "area": ["engine", "docs"]}})
+ self.assertEqual(out["object"], "brio.schema")
+ self.assertEqual(out["json"], {"decision": "request changes",
+ "needs_tests": "yes", "area": "engine"})
+ self.assertEqual([f["field"] for f in out["fields"]],
+ ["decision", "needs_tests", "area"])
+ # the JSON is valid by construction and round-trips
+ self.assertEqual(json.loads(json.dumps(out["json"])), out["json"])
+ pins = self.pins()
+ self.assertEqual(len(pins), 4, pins) # state, then one per cell
+ self.assertTrue(pins[1].endswith('Task: Review this pull request.\n{"decision": "'))
+ # the second cell's skeleton carries the first cell's chosen value
+ self.assertTrue(pins[2].endswith('{"decision": "request changes", "needs_tests": "'))
+ self.assertTrue(pins[3].endswith(
+ '{"decision": "request changes", "needs_tests": "yes", "area": "'))
+ self.assertEqual(out["usage"]["completion_tokens"], 0)
+ self.assertTrue(all(c["max_tokens"] == 0 for c in self.engine.calls))
+ for field in out["fields"]:
+ self.assertIn("p", field)
+ self.assertIn("entropy", field)
+
+ def test_schema_value_with_a_quote_is_written_as_valid_json(self):
+ self.serve({'say "hi"': -0.1, "stay quiet": -3.0})
+ out = self.post({"model": "test-model", "state": STATE,
+ "schema": {"reply": ['say "hi"', "stay quiet"],
+ "again": ['say "hi"', "stay quiet"]}})
+ self.assertEqual(out["json"]["reply"], 'say "hi"')
+ # the skeleton for the second cell must escape the first cell's value,
+ # or the JSON the server claims to build would not parse
+ self.assertIn('"reply": "say \\"hi\\"", "again": "', self.pins()[2])
+
+ # ---- validation ----------------------------------------------------------
+ def test_exactly_one_form(self):
+ self.serve({})
+ code, body = self.post_error({"model": "test-model", "state": STATE,
+ "options": ["a", "b"], "questions": []})
+ self.assertEqual(code, 400)
+ self.assertIn("exactly one", body["error"]["message"])
+ code, _ = self.post_error({"model": "test-model", "state": STATE})
+ self.assertEqual(code, 400)
+
+ def test_every_option_set_needs_two_entries(self):
+ self.serve({})
+ code, body = self.post_error({"model": "test-model", "state": STATE,
+ "schema": {"decision": ["merge"]}})
+ self.assertEqual(code, 400)
+ self.assertIn("schema.decision", body["error"]["message"])
+ code, body = self.post_error({"model": "test-model", "state": STATE,
+ "questions": [{"question": "q?", "options": ["only"]}]})
+ self.assertEqual(code, 400)
+ self.assertIn("questions[0].options", body["error"]["message"])
+
+ def test_questions_and_schema_need_a_state(self):
+ self.serve({})
+ code, body = self.post_error({"model": "test-model",
+ "questions": [{"question": "q?", "options": ["a", "b"]}]})
+ self.assertEqual(code, 400)
+ self.assertIn("state", body["error"]["message"])
+
+ def test_schema_field_names_that_would_break_the_skeleton_are_refused(self):
+ self.serve({})
+ code, body = self.post_error({"model": "test-model", "state": STATE,
+ "schema": {'bad"name': ["a", "b"]}})
+ self.assertEqual(code, 400)
+ self.assertIn("quotes", body["error"]["message"])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/docs/brio.md b/docs/brio.md
index 267e647b..0cc134fc 100644
--- a/docs/brio.md
+++ b/docs/brio.md
@@ -70,7 +70,10 @@ POST /v1/brio
| field | required | meaning |
|---|---|---|
| `model` | yes | as in every other endpoint |
-| `options` | yes | 2 to 64 distinct non-empty strings |
+| `options` | one of | 2 to 64 distinct non-empty strings: one closed question |
+| `questions` | one of | an array of `{question, options}`: many questions on one state, see below |
+| `schema` | one of | an object `field: [values]`: a JSON object filled one field at a time, see below |
+| `task` | optional | with `schema`, what the object is for |
| `state` | one of | the text to decide on |
| `messages` | one of | a chat history used as the context instead of `state` |
| `question` | optional | what to ask about the state |
@@ -97,6 +100,87 @@ The reply:
`completion_tokens` is always **0**: nothing is generated. `read_tokens` counts the
option tokens the engine read to score them.
+### Many questions on one text: `questions`
+
+The document is photographed once and every question pays only for its own
+words. This is the case where brio mode saves the most (5.7x against the chat,
+measured below), and the server keeps the order of the snapshots itself.
+
+```json
+{
+ "model": "qwen36",
+ "state": "340 lines, 8 files, no tests. CI is green but no coverage on that path.",
+ "questions": [
+ {"question": "What should the reviewer do?", "options": ["merge", "request changes", "close"]},
+ {"question": "Does it need tests?", "options": ["yes", "no"]},
+ {"question": "How risky is it?", "options": ["high", "medium", "low"], "normalize": "sum"}
+ ]
+}
+```
+
+The reply is `brio.answers`: an `answers` array in the same order, each entry
+shaped like a single `brio.choice` (`question`, `answer`, `entropy`, `choices`),
+and one `usage` for the whole request. Up to 64 questions, each with 2 to 64
+options; `normalize` can be set per question or once for all of them.
+
+### Fill a JSON object: `schema`
+
+The braces, the quotes and the field names are data the server writes. For
+each field, in the order you give them, the model only picks one of the values
+you allow, with the fields already filled visible to it. The JSON cannot come
+out malformed and no value can be outside your list, because nothing is
+generated.
+
+```json
+{
+ "model": "qwen36",
+ "state": "340 lines, 8 files, no tests. CI is green but no coverage on that path.",
+ "task": "Review this pull request.",
+ "schema": {
+ "decision": ["merge", "request changes", "close"],
+ "needs_tests": ["yes", "no"],
+ "risk": ["high", "medium", "low"],
+ "area": ["engine", "gateway", "docs"]
+ }
+}
+```
+
+The reply is `brio.schema`: `json` is the filled object, ready to use, and
+`fields` carries, per field, the chosen `value`, its `p`, the `entropy` of that
+cell and the full `choices`. The entropy per field is the point: the measured
+run below was sure about `area` (0.17) and not about `needs_tests` and `risk`
+(0.95 and 0.99), and said so, where the chat wrote `"risk": "high"` with the
+same face. `task` is optional. Field names cannot contain quotes, backslashes
+or newlines; values can, they are escaped.
+
+### From your own code
+
+No SDK is needed: it is one JSON request on the same server, with the same
+API key header as the rest.
+
+```python
+import requests
+r = requests.post("http://127.0.0.1:8000/v1/brio", json={
+ "model": "qwen36",
+ "state": open("ticket.txt").read(),
+ "questions": [
+ {"question": "Which queue?", "options": ["billing", "bugs", "sales"]},
+ {"question": "Urgent?", "options": ["yes", "no"]},
+ ]})
+for a in r.json()["answers"]:
+ print(a["question"], "->", a["answer"], f"(entropy {a['entropy']:.2f})")
+```
+
+```js
+const r = await fetch("http://127.0.0.1:8000/v1/brio", {
+ method: "POST", headers: {"Content-Type": "application/json"},
+ body: JSON.stringify({ model: "qwen36", state: ticket,
+ schema: { queue: ["billing", "bugs", "sales"], urgent: ["yes", "no"] } })
+});
+const { json, fields } = await r.json();
+// json.queue, json.urgent are guaranteed to be values from your lists
+```
+
### Do not put the options in the prompt
Write the state and the question; leave the option list to the `options` field. On a