decisionnode-edge 0.9.2__py3-none-any.whl

decisionnode_edge/request.py

@@ -0,0 +1,337 @@
+"""The request of the hosted `/v1/decide` endpoint, read into the questions the model answers.
+
+    {"state": ..., "questions": {"<id>": {"type": "choice" | "score" | "truth" | "number", ...}}, "images": [...]}
+
+What a request becomes (the same rules as the hosted API):
+
+    state         a string is used as it is; an object or array becomes compact JSON with its key order
+                  kept; a missing state, null and "" are the empty state.
+    instructions  a string, or the compact JSON of an object or array; missing or null is the empty text.
+    choice        criteria {option: description}, 1 to 255 options. A description is a string, the compact
+                  JSON of an object or array, or "" for null.
+    score         criteria [level, ...], 1 to 10 levels. One level is answered without the model.
+    truth         optional criteria {"true": ..., "false": ...}; needs instructions or criteria.
+    number        min, max and step (default 0, 255, 1): the answer is a value of that grid. Up to 256 values
+                  are one internal choice over the values; up to 4,096 are answered as pages of 256 (one choice
+                  over the pages, one per page) and composed. A grid of one value is answered without the model.
+    point, box    instructions (required), image (the id of a picture; optional with one picture), units ("pixels"
+                  or "normalized"), max (2 to 16: a list of places): answered in a few readings (places.py). Their
+                  faults come first, every one in one 422 (RequestError.errors).
+    images        [{"id", "data" (base64) and "media_type"}] or, on Edge, [{"id", "path"}] for a local file.
+                  Every question sees every picture, in request order.
+
+Edge has no videos, boosters, uploads or image URLs: a request that names them is refused.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import math
+from dataclasses import dataclass, field
+from decimal import Decimal, localcontext
+from typing import Any
+
+from . import places
+
+MAX_OPTIONS = 255
+MAX_LEVELS = 10
+MAX_IMAGES = 16
+MAX_IMAGE_ID = 64
+IMAGE_MEDIA_TYPES = ("image/jpeg", "image/png", "image/webp")
+ONE_ROW_VALUES = 256  # the answer codes: a grid up to this size is one internal choice
+MAX_GRID_VALUES = 4096
+MAX_DECIMALS = 6
+NUMBER_DEFAULTS = {"min": 0, "max": 255, "step": 1}
+NOT_ON_EDGE = ("videos", "boosters")
+MAX_ERRORS = 1000  # the entries a 422 lists at most
+
+
+class RequestError(ValueError):
+    """A request the model cannot answer. `status` is the HTTP status the hosted API gives the same fault, `error_type`
+    the kind of fault its error body names (the local server's, server.py), `errors` a 422's field errors when it lists
+    them ({"type", "loc", "msg", "input"}, as the hosted API's body), `detail` the error body's detail when it is not the
+    server's own shape (the hosted API's plain-text details on /v1/systemone)."""
+
+    def __init__(self, message: str, status: int = 400, error_type: str = "api_usage_error", errors: list[dict] | None = None, detail: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.error_type = error_type
+        self.errors = errors
+        self.detail = detail
+
+
+def text_of(value: Any) -> str:
+    """A state, instruction, description or level as the prompt carries it."""
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def _content(value: Any, where: str, nullable: bool = True) -> None:
+    if not (isinstance(value, (str, dict, list)) or (value is None and nullable)):
+        raise RequestError(f"{where} must be a string, an object or an array", 422)
+
+
+# ---------------------------------------------------------------------------
+# Number grids
+# ---------------------------------------------------------------------------
+
+
+def _decimal(value: Any) -> Decimal:
+    return Decimal(repr(value)) if isinstance(value, float) else Decimal(int(value))
+
+
+def _places(value: Decimal) -> int:
+    """Digits after the point once trailing zeros are dropped: 0.5 has 1, 7 has 0."""
+    text = format(value.normalize(), "f")
+    return len(text.split(".")[1]) if "." in text else 0
+
+
+def _value_text(scaled: int, d: int) -> str:
+    """The grid value scaled / 10^d in its shortest plain decimal form."""
+    digits = str(abs(scaled)).rjust(d + 1, "0")
+    whole, frac = (digits[:-d], digits[-d:].rstrip("0")) if d else (digits, "")
+    text = whole + ("." + frac if frac else "")
+    return "-" + text if scaled < 0 else text
+
+
+@dataclass(frozen=True)
+class Grid:
+    """Value i is (m + i * s) / 10^d, for i in 0 .. n - 1."""
+
+    d: int
+    m: int
+    s: int
+    n: int
+
+    def text(self, i: int) -> str:
+        return _value_text(self.m + i * self.s, self.d)
+
+    def texts(self, start: int = 0, end: int | None = None) -> list[str]:
+        return [self.text(i) for i in range(start, self.n if end is None else end)]
+
+    @property
+    def pages(self) -> int:
+        return 1 if self.n <= ONE_ROW_VALUES else -(-self.n // ONE_ROW_VALUES)
+
+    def page_bounds(self) -> list[tuple[int, int]]:
+        """(first, end) of each page; the first n mod pages pages hold one value more."""
+        q, r = divmod(self.n, self.pages)
+        out, start = [], 0
+        for j in range(self.pages):
+            size = q + 1 if j < r else q
+            out.append((start, start + size))
+            start += size
+        return out
+
+
+def number_grid(question: dict, qid: str) -> Grid:
+    values = {}
+    for name in ("min", "max", "step"):
+        value = question.get(name)
+        if value is None:
+            value = NUMBER_DEFAULTS[name]
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or (isinstance(value, float) and not math.isfinite(value)):
+            raise RequestError(f"question {qid!r}: {name} must be a finite number", 422)
+        values[name] = _decimal(value)
+        if abs(values[name]) > 2**53:
+            raise RequestError(f"question {qid!r}: {name} must be within plus or minus 2^53", 422)
+        if name != "max" and _places(values[name]) > MAX_DECIMALS:
+            raise RequestError(f"question {qid!r}: {name} has more than {MAX_DECIMALS} decimals", 422)
+    if values["step"] <= 0:
+        raise RequestError(f"question {qid!r}: step must be above 0", 422)
+    if values["min"] > values["max"]:
+        raise RequestError(f"question {qid!r}: min is above max", 422)
+    d = max(_places(values["min"]), _places(values["step"]))
+    with localcontext() as ctx:
+        ctx.prec = 200
+        if d:
+            bound = Decimal(10) ** (15 - d) - Decimal(10) ** -d
+            if abs(values["min"]) > bound or abs(values["max"]) > bound:
+                raise RequestError(f"question {qid!r}: on a grid with {d} decimals, min and max must stay within plus or minus {bound}", 422)
+        scale = Decimal(10) ** d
+        m, s = int(values["min"] * scale), int(values["step"] * scale)
+        top = int((values["max"] * scale).to_integral_value(rounding="ROUND_FLOOR"))
+    n = (top - m) // s + 1
+    if n > MAX_GRID_VALUES:
+        raise RequestError(f"question {qid!r}: the grid holds {n} values, the limit is {MAX_GRID_VALUES}", 422)
+    return Grid(d=d, m=m, s=s, n=n)
+
+
+def number_rows(instructions: str, grid: Grid) -> list[dict]:
+    """The internal choice questions of a number question: one over the values, or one over the pages and one per page."""
+    if grid.pages == 1:
+        keys = grid.texts()
+        return [{"type": "choice", "instructions": instructions, "keys": keys, "descs": [""] * len(keys)}]
+    bounds = grid.page_bounds()
+    rows = [{"type": "choice", "instructions": instructions, "keys": [f"{grid.text(a)} to {grid.text(b - 1)}" for a, b in bounds], "descs": [""] * len(bounds)}]
+    for a, b in bounds:
+        keys = grid.texts(a, b)
+        rows.append({"type": "choice", "instructions": instructions, "keys": keys, "descs": [""] * len(keys)})
+    return rows
+
+
+def compose(grid: Grid, answered: list[list[float]]) -> list[float]:
+    """The probability of every grid value: p(page) * p(value | page) on a paged grid."""
+    if grid.pages == 1:
+        return list(answered[0])
+    out: list[float] = []
+    for j, page in enumerate(answered[1:]):
+        out.extend(answered[0][j] * p for p in page)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# The request
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Question:
+    id: str
+    type: str  # choice, score, truth or number (as answered)
+    rows: list[dict]  # what the model runs: one prompt per row (none for a question answered without the model)
+    levels: list | None = None  # score: the levels as sent, for `legend`
+    keys: list[str] | None = None  # choice: the options in request order
+    grid: Grid | None = None  # number
+    place: places.PlaceSpec | None = None  # point and box (answered by places.Plan, not by rows of its own)
+
+
+@dataclass
+class Request:
+    state: str
+    questions: list[Question]
+    images: list[dict] = field(default_factory=list)
+
+
+def parse(body: Any) -> Request:
+    """Validate a `/v1/decide` request body (a dict) and read it into questions. Raises RequestError."""
+    if not isinstance(body, dict):
+        raise RequestError("the request must be a JSON object", 422)
+    for name in NOT_ON_EDGE:
+        if body.get(name):
+            raise RequestError(f"`{name}` is not available on DecisionNode Edge")
+    specs = _place_specs(body)
+    state = body.get("state")
+    _content(state, "state")
+    questions = body.get("questions")
+    if not isinstance(questions, dict) or not questions:
+        raise RequestError("questions must be an object with at least one question", 422)
+    state_text = text_of(state)
+    out = [Question(qid, specs[qid].shape, [], place=specs[qid]) if qid in specs else _question(qid, q) for qid, q in questions.items()]
+    return Request(state=state_text, questions=out, images=_images(body.get("images")))
+
+
+def _place_specs(body: dict) -> dict[str, places.PlaceSpec]:
+    """The point and box questions by id, read before the rest of the request: their 422 (every faulty field), then
+    the 400 of one without instructions."""
+    questions = body.get("questions")
+    if not isinstance(questions, dict):
+        return {}
+    found = [(qid, q) for qid, q in questions.items() if places.is_place_question(q)]
+    if not found:
+        return {}
+    images = body.get("images")
+    image_ids = [image.get("id") for image in images if isinstance(image, dict) and isinstance(image.get("id"), str)] if isinstance(images, list) else []
+    # pictures the image check refuses (not a list, an id that is not a string, an id used twice) are its fault to name
+    faulty = images is not None and (not isinstance(images, list) or len(image_ids) != len(images) or len(set(image_ids)) != len(image_ids))
+    entries = (entry for qid, q in found for entry in places.question_errors(q, ("body", "questions", qid), None if faulty else image_ids))
+    errors = list(itertools.islice(entries, MAX_ERRORS))
+    if errors:
+        raise RequestError(places.reason(errors), 422, errors=errors)
+    missing = places.missing_instructions(found)
+    if missing:
+        raise RequestError(missing)
+    out = {}
+    for qid, q in found:
+        image = q.get("image") if q.get("image") is not None else (image_ids[0] if image_ids else "")
+        number = image_ids.index(image) + 1 if image in image_ids else 0
+        out[qid] = places.PlaceSpec(str(qid), q["type"], text_of(q.get("instructions")), image, number, q.get("units") or "pixels", q.get("max"))
+    return out
+
+
+def _question(qid: str, q: Any) -> Question:
+    if not isinstance(q, dict) or "type" not in q:
+        raise RequestError(f"question {qid!r} must be an object with a type", 422)
+    kind = q["type"]
+    if kind == "noul":  # the older name of the yes-or-no type, answered as truth
+        kind = "truth"
+    if kind not in ("choice", "score", "truth", "number"):
+        raise RequestError(f"question {qid!r}: unknown question type {kind!r}")
+    instructions, criteria = q.get("instructions"), q.get("criteria")
+    _content(instructions, f"question {qid!r}: instructions")
+    text = text_of(instructions)
+
+    if kind == "number":
+        if instructions is None or instructions == "":
+            raise RequestError(f"Number question must have instructions: {qid}")
+        grid = number_grid(q, qid)
+        rows = [] if grid.n == 1 else number_rows(text, grid)
+        return Question(qid, "number", rows, grid=grid)
+
+    if kind == "choice":
+        if not isinstance(criteria, dict):
+            raise RequestError(f"question {qid!r}: a choice needs criteria, an object of options", 422)
+        if not criteria:
+            raise RequestError(f"Choice question must have at least one choice: {qid}")
+        if len(criteria) > MAX_OPTIONS:
+            raise RequestError(f"Too many choices: question {qid!r} has {len(criteria)} options, the limit is {MAX_OPTIONS} options per choice.")
+        for key, desc in criteria.items():
+            _content(desc, f"question {qid!r}: the description of {key!r}")
+        keys = list(criteria)
+        row = {"type": "choice", "instructions": text, "keys": keys, "descs": [text_of(d) for d in criteria.values()]}
+        return Question(qid, "choice", [] if len(keys) == 1 else [row], keys=keys)
+
+    if kind == "score":
+        if not isinstance(criteria, list) or not criteria:
+            raise RequestError(f"question {qid!r}: a score needs criteria, a list of 1 to {MAX_LEVELS} levels", 422)
+        if len(criteria) > MAX_LEVELS:
+            raise RequestError(f"Too many score levels. Must have at most {MAX_LEVELS} levels.")
+        for i, level in enumerate(criteria):
+            _content(level, f"question {qid!r}: level {i}", nullable=False)
+        row = {"type": "score", "instructions": text, "levels": [text_of(level) for level in criteria]}
+        return Question(qid, "score", [] if len(criteria) == 1 else [row], levels=list(criteria))
+
+    # truth
+    if criteria is not None and not isinstance(criteria, dict):
+        raise RequestError(f"question {qid!r}: truth criteria must be an object with `true` and `false`", 422)
+    if instructions is None and criteria is None:
+        raise RequestError(f"Truth question must have criteria or instructions: {qid}")
+    row: dict = {"type": "truth", "instructions": text}
+    if criteria:
+        for side in ("true", "false"):
+            _content(criteria.get(side), f"question {qid!r}: criteria.{side}")
+        sides = {side: text_of(criteria.get(side)) for side in ("true", "false") if text_of(criteria.get(side))}
+        if sides:
+            row["criteria"] = sides
+    return Question(qid, "truth", [row])
+
+
+def _images(images: Any) -> list[dict]:
+    if images is None:
+        return []
+    if not isinstance(images, list):
+        raise RequestError("images must be a list", 422)
+    if len(images) > MAX_IMAGES:
+        raise RequestError(f"Too many images: {len(images)}, the limit is {MAX_IMAGES}.")
+    seen = set()
+    for i, image in enumerate(images):
+        if not isinstance(image, dict) or not isinstance(image.get("id"), str) or not image["id"]:
+            raise RequestError(f"Image {i} needs an id.")
+        image_id = image["id"]
+        if len(image_id) > MAX_IMAGE_ID:
+            raise RequestError(f"Image {i}: its id is longer than {MAX_IMAGE_ID} characters.")
+        if image_id in seen:
+            raise RequestError(f"Image id {image_id!r} is used twice.")
+        seen.add(image_id)
+        if image.get("url") is not None or image.get("upload_id") is not None:
+            raise RequestError(f"Image {image_id!r}: DecisionNode Edge reads pictures from `data` or a local `path`, not from a URL or an upload.")
+        forms = [name for name in ("data", "path") if image.get(name) is not None]
+        if len(forms) != 1:
+            raise RequestError(f"Image {image_id!r} needs exactly one of data and path.")
+        if forms == ["data"] and image.get("media_type") not in IMAGE_MEDIA_TYPES:
+            raise RequestError(f"Image {image_id!r}: media_type must be one of {', '.join(IMAGE_MEDIA_TYPES)}.")
+    return images

decisionnode_edge/server.py

@@ -0,0 +1,282 @@
+"""A local HTTP server for a DecisionNode Edge model, on the standard library only.
+
+    python -m decisionnode_edge serve path/to/model [--host 127.0.0.1] [--port 8000] [--api-key FILE] [--backend ...]
+
+    POST /v1/systemone   the /v1/systemone format used by public decision-model leaderboards:
+                         {"model", "state", "questions", "assets"}; noul, choice, score and box questions; a noul is
+                         answered {"type": "noul", "noul": p}, a choice and a score as on /v1/decide but with lists
+                         that sum to exactly 1.00, a box as {"type": "box", "box": {"top", "bottom", "left", "right"},
+                         "confidence"} (systemone.py)
+    POST /v1/decide      the DecisionNode API's call: the runtime's own request and answers (EdgeModel.decide)
+    GET  /v1/models      {"models": [{"name", "description", "release_date"}]}
+    GET  /healthz        {"status": "ok", "model", "backend"} (no key needed)
+
+Pictures: `images` as the runtime takes them, base64 `data` only (a local `path` is refused over HTTP: a caller must
+never make the server read its files), and on /v1/systemone the format's own: the `assets` map, {"<ref>": {"type":
+"image", "format": "png" | "jpg" | "jpeg", "data_base64": ...}}, whose references in the text become `Picture <n>`,
+`image_url` content parts and `images` as data URLs (systemone.translate).
+
+Point and box questions are taken on /v1/decide. On /v1/systemone a box is taken (in the format's shape, its
+`confidence` the model folder's box calibration where there is one, box_calibration.json, else `present`), and point
+and number questions are refused.
+
+Errors carry a `detail` body: {"detail": {"error_type", "message"}} (a 422 as a list of field errors). A
+request over the model's length limit says "maximum context length", a choice over 255 options "options per choice",
+and on /v1/systemone a score over 10 levels "a score takes 2 to 10 levels": the words leaderboard harnesses look for to
+count a request as beyond the model rather than as a failure. On /v1/systemone these three come in the hosted route's
+bodies (systemone.mark_capacity).
+
+The model answers one request at a time (a lock); the server listens on the loopback address unless told otherwise.
+`model` is required on /v1/systemone, as on the hosted API, and any name is accepted: the answer names the model that
+answered.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hmac
+import json
+import logging
+import os
+import sys
+import threading
+import time
+import traceback
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+from . import request as requests, systemone
+from .request import RequestError
+
+MAX_BODY_BYTES = 64 << 20  # 16 pictures as base64 with room to spare
+SYSTEMONE_TYPES = ("noul", "choice", "score", "box")
+AUTH_MESSAGE = "Cannot authenticate with the server. Please check your API key and try again."
+ROUTES = {"/v1/systemone": "POST", "/v1/decide": "POST", "/v1/models": "GET", "/healthz": "GET"}
+
+log = logging.getLogger("decisionnode_edge.server")
+
+
+class HTTPError(Exception):
+    def __init__(self, status: int, error_type: str, message: str, headers: dict | None = None):
+        super().__init__(message)
+        self.status, self.error_type, self.message, self.headers = status, error_type, message, headers or {}
+
+
+def error_body(status: int, error_type: str, message: str, errors: list[dict] | None = None) -> dict:
+    if status == 422:
+        return {"detail": errors or [{"type": "value_error", "loc": ["body"], "msg": message, "input": None}]}
+    return {"detail": {"error_type": error_type, "message": message}}
+
+
+def _images_over_http(images: Any) -> list:
+    if images is None:
+        return []
+    if not isinstance(images, list):
+        raise RequestError("images must be a list", 422)
+    for image in images:
+        if isinstance(image, dict) and image.get("path") is not None:
+            raise RequestError("Over HTTP a picture is sent as base64 `data` (or an asset), never as a local `path`.")
+    return list(images)
+
+
+def box_calibration(model: Any, path: str | None = None, sha256: str | None = None) -> systemone.BoxCalibration | None:
+    """The box calibration /v1/systemone reads: `path` (or "none" for none), else the model folder's
+    box_calibration.json when there is one. `sha256` (else `box_calibration_sha256` in decisionnode_edge.json), when
+    set, must be the file's. A file that does not check is a BoxCalibrationError: the server does not start on it."""
+    if path == "none":
+        return None
+    sha256 = sha256 if sha256 is not None else model.config.get("box_calibration_sha256") or ""
+    if path is None:
+        path = os.path.join(model.path, systemone.BOX_CALIBRATION_FILE)
+        if not os.path.isfile(path):
+            if sha256:
+                raise systemone.BoxCalibrationError(f"{path}: the model names a box calibration that is not there")
+            return None
+    return systemone.BoxCalibration.load(path, sha256)
+
+
+class Service:
+    """The routes, without the socket: handle(method, path, headers, body) gives (status, JSON body, extra headers).
+    `calibration`: the box calibration of /v1/systemone (default: box_calibration(model))."""
+
+    def __init__(self, model: Any, api_key: str | None = None, description: str | None = None, release_date: str | None = None, calibration: Any = "model"):
+        self.model = model
+        self.api_key = api_key
+        self.name = model.config["name"]
+        self.description = description or model.config.get("description") or f"{self.name}: typed, calibrated decisions, run locally"
+        self.release_date = release_date or model.config.get("release_date")
+        self.calibration = box_calibration(model) if calibration == "model" else calibration
+        self.lock = threading.Lock()
+
+    def handle(self, method: str, path: str, headers: dict[str, str], body: bytes) -> tuple[int, dict, dict]:
+        try:
+            return 200, self._route(method, path.split("?", 1)[0], headers, body), {}
+        except HTTPError as error:
+            return error.status, error_body(error.status, error.error_type, error.message), error.headers
+        except RequestError as error:
+            if path.split("?", 1)[0] == "/v1/systemone":
+                error = systemone.mark_capacity(error)
+            if error.detail is not None:
+                return error.status, {"detail": error.detail}, {}
+            return error.status, error_body(error.status, error.error_type, str(error), error.errors), {}
+        except Exception:  # a fault of the model or the backend, never the caller's
+            log.error("the model could not answer:\n%s", traceback.format_exc())
+            return 500, error_body(500, "internal_error", "The model could not answer this request."), {}
+
+    def _route(self, method: str, path: str, headers: dict[str, str], body: bytes) -> dict:
+        if path not in ROUTES:
+            raise HTTPError(404, "not_found_error", "Not found.")
+        if method != ROUTES[path]:
+            raise HTTPError(405, "api_usage_error", "Method not allowed.", {"Allow": ROUTES[path]})
+        if path == "/healthz":
+            return {"status": "ok", "model": self.name, "backend": self.model.backend}
+        self._authenticate(headers)
+        if path == "/v1/models":
+            return {"models": [{"name": self.name, "description": self.description, "release_date": self.release_date}]}
+        try:
+            request = json.loads(body)
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise RequestError(f"the body is not JSON: {error}", 422) from None
+        if path == "/v1/decide":
+            if isinstance(request, dict) and request.get("images") is not None:
+                request = {**request, "images": _images_over_http(request["images"])}
+            with self.lock:
+                return self.model.decide(request)
+        return self._systemone(request)
+
+    def _authenticate(self, headers: dict[str, str]) -> None:
+        if self.api_key is None:
+            return
+        given = headers.get("authorization", "")
+        scheme, _, token = given.partition(" ")
+        if scheme.lower() != "bearer" or not hmac.compare_digest(token.strip().encode(), self.api_key.encode()):
+            raise HTTPError(401, "authentication_error", AUTH_MESSAGE, {"WWW-Authenticate": "Bearer"})
+
+    def _systemone(self, request: Any) -> dict:
+        if not isinstance(request, dict):
+            raise RequestError("the request must be a JSON object", 422)
+        if not isinstance(request.get("model"), str):
+            raise RequestError("model: Field required, a string", 422)
+        questions = request.get("questions")
+        if isinstance(questions, dict):
+            for qid, question in questions.items():
+                kind = question.get("type") if isinstance(question, dict) else None
+                if kind in ("number", "point"):
+                    raise RequestError(f"question {qid!r}: the {kind} type is not available on /v1/systemone; send it to /v1/decide")
+                if isinstance(question, dict) and "type" in question and kind not in SYSTEMONE_TYPES:
+                    raise RequestError(f"question {qid!r}: unknown question type {kind!r}")
+        _images_over_http(request.get("images"))
+        body = {name: request[name] for name in ("state", "questions", "images", "assets") if name in request}
+        body, done = systemone.translate(body, max_images=requests.MAX_IMAGES)
+        parsed = requests.parse(body)
+        systemone.normalised_boxes(q.place for q in parsed.questions if q.place is not None)  # the format's edges are fractions
+        with self.lock:
+            response = self.model._decide(parsed, exact_sum=True)
+        answers = {}
+        for qid, answer in response["answers"].items():  # a noul is answered under its own name, as the format has it
+            if answer["type"] == "truth":
+                answer = {"type": "noul", "noul": answer["truth"]}
+            elif answer["type"] == "score" and qid in done.legends and len(done.legends[qid]) == len(answer["legend"]):
+                answer = {**answer, "legend": {str(i): level for i, level in enumerate(done.legends[qid])}}  # the levels as sent
+            answers[qid] = answer
+        return systemone.box_answers({"model": response["model"], "answers": answers, "usage": response["usage"]}, self.calibration)
+
+
+class Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"  # keep-alive: every response carries Content-Length
+    disable_nagle_algorithm = True  # headers and body are two writes: without it a kept-alive client waits for a delayed ACK
+    server_version = "decisionnode-edge"
+    service: Service = None  # set by make_server
+
+    def _answer(self, method: str) -> None:
+        started = time.perf_counter()
+        body = b""
+        if method == "POST":
+            length = self.headers.get("Content-Length")
+            if length is None or not length.isdigit():
+                return self._send(411, error_body(411, "api_usage_error", "Content-Length is required."), {"Connection": "close"}, started)
+            if int(length) > MAX_BODY_BYTES:
+                return self._send(413, error_body(413, "api_usage_error", "Request body too large."), {"Connection": "close"}, started)
+            body = self.rfile.read(int(length))
+        headers = {k.lower(): v for k, v in self.headers.items()}
+        status, payload, extra = self.service.handle(method, self.path, headers, body)
+        self._send(status, payload, extra, started)
+
+    def _send(self, status: int, payload: dict, extra: dict, started: float) -> None:
+        data = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.send_header("X-Latency-Ms", f"{(time.perf_counter() - started) * 1000:.2f}")
+        for name, value in extra.items():
+            self.send_header(name, value)
+        self.end_headers()
+        self.wfile.write(data)
+        if extra.get("Connection") == "close":
+            self.close_connection = True
+
+    def do_GET(self) -> None:  # noqa: N802 (the standard library's names)
+        self._answer("GET")
+
+    def do_POST(self) -> None:  # noqa: N802
+        self._answer("POST")
+
+    def do_PUT(self) -> None:  # noqa: N802
+        self._answer("PUT")
+
+    def do_DELETE(self) -> None:  # noqa: N802
+        self._answer("DELETE")
+
+    def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
+        log.info("%s %s", self.address_string(), format % args)
+
+
+def make_server(model: Any, host: str = "127.0.0.1", port: int = 8000, api_key: str | None = None, **service: Any) -> ThreadingHTTPServer:
+    handler = type("EdgeHandler", (Handler,), {"service": Service(model, api_key=api_key, **service)})
+    server = ThreadingHTTPServer((host, port), handler)
+    server.daemon_threads = True
+    return server
+
+
+def main(argv: list[str] | None = None) -> int:
+    from . import EdgeModel
+
+    parser = argparse.ArgumentParser(prog="python -m decisionnode_edge serve", description="Serve a DecisionNode Edge model over HTTP: /v1/systemone, /v1/decide, /v1/models.")
+    parser.add_argument("model", help="the model directory")
+    parser.add_argument("--host", default="127.0.0.1", help="the address to listen on (default 127.0.0.1, this machine only)")
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument("--api-key", default=None, help="a file holding the key callers must send as `Authorization: Bearer <key>`")
+    parser.add_argument("--device", default=None)
+    parser.add_argument("--dtype", default=None)
+    parser.add_argument("--backend", default=None, help="auto, torch, vllm, openvino, mlx or llamacpp (default: auto)")
+    parser.add_argument("--artifacts", default=None, help="the directory python -m decisionnode_edge.build wrote")
+    parser.add_argument("--description", default=None, help="the description GET /v1/models gives")
+    parser.add_argument("--release-date", default=None, help="the release date GET /v1/models gives (YYYY-MM-DD)")
+    parser.add_argument("--box-calibration", default=None, help="the box calibration of /v1/systemone (default: the model folder's box_calibration.json when there is one; none for none)")
+    parser.add_argument("--box-calibration-sha256", default=None, help="the sha256 the box calibration file must have")
+    args = parser.parse_args(argv)
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(message)s")
+    api_key = None
+    if args.api_key:
+        with open(args.api_key, encoding="utf-8") as f:
+            api_key = f.read().strip()
+        if not api_key:
+            raise SystemExit(f"{args.api_key} is empty")
+    model = EdgeModel.load(args.model, device=args.device, dtype=args.dtype, backend=args.backend, artifacts=args.artifacts)
+    calibration = box_calibration(model, args.box_calibration, args.box_calibration_sha256)
+    model.decide({"state": "The color is red.", "questions": {"warmup": {"type": "choice", "instructions": "Which color is named?", "criteria": {"red": "red", "blue": "blue"}}}})
+    server = make_server(model, args.host, args.port, api_key, description=args.description, release_date=args.release_date, calibration=calibration)
+    log.info("serving %s (%s backend) on http://%s:%d%s", model.config["name"], model.backend, args.host, server.server_address[1], ", key required" if api_key else "")
+    if calibration is not None:
+        log.info("/v1/systemone box confidence: the box calibration %s (sha256 %s)", calibration.model or "of this model", calibration.sha256)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())