aggregate_api 1.0.0__py3-none-any.whl

aggregate_api/resources.py

@@ -0,0 +1,257 @@
+"""What the process costs, from ``psutil`` when it is installed and stdlib when not.
+
+``psutil`` is an optional extra (``uv sync --extra status``), so this module has
+two implementations of the same small block of numbers and says which one it
+used. Everything here is a read of counters the operating system already
+maintains; nothing walks a Python object or touches the cache.
+
+**A field that cannot be filled renders "unavailable" with the reason, never
+zero.** A resource panel reporting 0 bytes resident is worse than one reporting
+nothing, because the first is a number an operator will act on. So every
+absence carries why it is absent, and the page prints the reason beside the
+blank.
+
+The extra is worth declaring even though ``psutil`` is usually already there.
+It arrives transitively through ``ipython``, which ``aggregate`` pulls, so the
+import succeeds today on any box with the dev environment: by accident rather
+than by intent, and one unrelated dependency change away from not. Declaring it
+also means the stdlib path is never exercised by accident, which is why the
+tests force it.
+
+CPU percent must not block
+--------------------------
+
+``psutil.Process.cpu_percent(interval=...)`` sleeps for the interval and then
+reports. The ``interval=None`` form reports the share since the previous call on
+the same object instead, costing nothing, and :func:`seed` makes the first such
+call at startup so the first page load has a denominator. The stdlib path does
+the same arithmetic by hand off :func:`time.process_time`. A status page that
+blocks a worker for a second is a status page that lies about latency.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import threading
+import time
+from pathlib import Path
+
+try:  # pragma: no cover (the branch taken depends on the environment)
+    import psutil
+except ImportError:  # pragma: no cover
+    psutil = None
+
+#: Set by :func:`seed`. Held rather than created per call because
+#: ``cpu_percent(interval=None)`` measures against the previous call on **this
+#: object**, so a fresh Process each time would report zero forever.
+_process = None
+
+#: The stdlib path's previous sample, ``(monotonic, process_time)``.
+_cpu_mark: tuple[float, float] | None = None
+
+_lock = threading.Lock()
+
+#: Reason strings, spelled once so the tests can assert on them.
+NO_PSUTIL = "psutil not installed; install the status extra"
+NO_PROC = "no /proc on this platform"
+NO_LOADAVG = "no system load average on this platform"
+
+
+def available() -> bool:
+    """True when ``psutil`` imported, which decides which path :func:`snapshot` takes."""
+    return psutil is not None
+
+
+def seed() -> None:
+    """Prime the CPU measurement so the first page load has a denominator.
+
+    Notes
+    -----
+    Called from :func:`aggregate_api.app.create_app`. Both paths need a previous
+    sample to measure against, and without one the first reading is either zero
+    (``psutil``) or a division by a zero interval (stdlib). Seeding at startup
+    means the first reading is the share since boot, which is a fair number
+    rather than a placeholder.
+    """
+    global _process, _cpu_mark
+    with _lock:
+        _cpu_mark = (time.monotonic(), time.process_time())
+        if psutil is None:
+            return
+        try:
+            _process = psutil.Process()
+            _process.cpu_percent(interval=None)
+        except Exception:  # noqa: BLE001 (a resource panel must never break boot)
+            _process = None
+
+
+def _cpu_percent_stdlib() -> float | None:
+    """CPU share since the previous call, from :func:`time.process_time`.
+
+    Notes
+    -----
+    ``time.process_time`` is stdlib and cross-platform, unlike
+    ``resource.getrusage``, and it counts system plus user CPU for the process,
+    which is what ``psutil`` reports too. The result exceeds 100 on a
+    multi-core box running several threads hot, which is the same convention
+    ``psutil`` uses and is left uncapped for that reason.
+    """
+    global _cpu_mark
+    now, cpu = time.monotonic(), time.process_time()
+    with _lock:
+        previous = _cpu_mark
+        _cpu_mark = (now, cpu)
+    if previous is None:
+        return None
+    elapsed = now - previous[0]
+    if elapsed <= 0:
+        return None
+    return round(100.0 * (cpu - previous[1]) / elapsed, 1)
+
+
+def _load_average(unavailable: dict) -> list[float] | None:
+    """System load average, or ``None`` with a reason recorded.
+
+    Notes
+    -----
+    ``os.getloadavg`` rather than ``psutil.getloadavg``, on both paths and
+    deliberately. psutil emulates the figure on Windows by sampling in a
+    background thread, and an emulated load average on a page whose whole
+    argument is that it reports honestly is worse than a blank. On the Linux VPS
+    the two agree because psutil reads the same source.
+    """
+    try:
+        return [round(value, 2) for value in os.getloadavg()]
+    except (OSError, AttributeError):
+        unavailable["load_average"] = NO_LOADAVG
+        return None
+
+
+def _disk(path: str, unavailable: dict) -> tuple[int | None, int | None]:
+    """Free and total bytes on the volume holding ``path``.
+
+    Notes
+    -----
+    Walks up to the first parent that exists. The audit database is created
+    lazily, so on a fresh install the configured path and often its directory
+    are both absent, and reporting the volume they *would* land on is the useful
+    answer rather than a blank.
+    """
+    candidate = Path(path).expanduser()
+    for parent in [candidate, *candidate.parents]:
+        if parent.exists():
+            try:
+                usage = shutil.disk_usage(parent)
+            except OSError as exc:
+                unavailable["disk"] = str(exc)
+                return None, None
+            return usage.free, usage.total
+    unavailable["disk"] = f"no existing parent of {path}"
+    return None, None
+
+
+def _proc_memory(unavailable: dict) -> tuple[int | None, int | None]:
+    """Resident and virtual bytes from ``/proc/self/statm``, the stdlib path.
+
+    Notes
+    -----
+    ``statm`` reports pages, first field virtual and second resident, so both
+    are multiplied by the page size. Linux only, which covers the VPS; the
+    Windows development box gets the reason instead, which is the case the extra
+    exists to fix.
+    """
+    try:
+        fields = Path("/proc/self/statm").read_text().split()
+    except OSError:
+        unavailable["memory"] = NO_PROC if sys.platform != "linux" else NO_PSUTIL
+        return None, None
+    try:
+        page = os.sysconf("SC_PAGE_SIZE")
+        return int(fields[1]) * page, int(fields[0]) * page
+    except (ValueError, IndexError, OSError, AttributeError) as exc:
+        unavailable["memory"] = str(exc)
+        return None, None
+
+
+def _proc_open_files(unavailable: dict) -> int | None:
+    """Open file descriptors from ``/proc/self/fd``, the stdlib path."""
+    try:
+        return len(os.listdir("/proc/self/fd"))
+    except OSError:
+        unavailable["open_files"] = NO_PROC if sys.platform != "linux" else NO_PSUTIL
+        return None
+
+
+def snapshot(audit_db: str) -> dict:
+    """The resource block.
+
+    Parameters
+    ----------
+    audit_db : str
+        Configured path of the audit database, used to pick the volume whose
+        free space is reported. It is the one file this process grows without
+        bound, so it is the one worth watching.
+
+    Returns
+    -------
+    dict
+        ``source`` names which implementation answered. Every metric is present
+        as a key with ``None`` where it could not be read, and ``unavailable``
+        maps the missing ones to why. Callers render the reason; nothing here
+        substitutes a zero.
+    """
+    unavailable: dict[str, str] = {}
+    free, total = _disk(audit_db, unavailable)
+    block = {
+        "source": "psutil" if _process is not None else "stdlib",
+        "platform": sys.platform,
+        "rss_bytes": None,
+        "vms_bytes": None,
+        "cpu_percent": None,
+        "threads": None,
+        "open_files": None,
+        "load_average": _load_average(unavailable),
+        "disk_free_bytes": free,
+        "disk_total_bytes": total,
+        "unavailable": unavailable,
+    }
+
+    if _process is not None:
+        try:
+            memory = _process.memory_info()
+            block["rss_bytes"] = int(memory.rss)
+            block["vms_bytes"] = int(memory.vms)
+            block["cpu_percent"] = round(float(_process.cpu_percent(interval=None)), 1)
+            block["threads"] = int(_process.num_threads())
+        except Exception as exc:  # noqa: BLE001 (the process can vanish under us)
+            unavailable.setdefault("process", str(exc))
+        # Descriptors are ``num_fds`` on Unix and ``num_handles`` on Windows, and
+        # the two count different things, so the label travels with the number.
+        counter = getattr(_process, "num_fds", None) or getattr(_process, "num_handles", None)
+        if counter is None:
+            unavailable["open_files"] = "no descriptor count on this platform"
+        else:
+            try:
+                block["open_files"] = int(counter())
+                block["open_files_kind"] = ("handles" if sys.platform == "win32"
+                                            else "descriptors")
+            except Exception as exc:  # noqa: BLE001
+                unavailable["open_files"] = str(exc)
+        return block
+
+    if psutil is None:
+        unavailable["source"] = NO_PSUTIL
+    rss, vms = _proc_memory(unavailable)
+    block["rss_bytes"] = rss
+    block["vms_bytes"] = vms
+    block["cpu_percent"] = _cpu_percent_stdlib()
+    # ``threading.active_count`` counts Python threads only, so it misses the
+    # ones uvicorn's C extensions own. Named so the page can say which it is.
+    block["threads"] = threading.active_count()
+    block["threads_kind"] = "python"
+    block["open_files"] = _proc_open_files(unavailable)
+    if block["open_files"] is not None:
+        block["open_files_kind"] = "descriptors"
+    return block

aggregate_api/routes/__init__.py

@@ -0,0 +1,8 @@
+"""Route modules for the api.
+
+Each submodule defines a single :class:`fastapi.APIRouter` named
+``router`` that the app factory mounts under ``/v1``.
+
+Flask users: an ``APIRouter`` is FastAPI's analogue of a
+:class:`flask.Blueprint`.
+"""

aggregate_api/routes/decl.py

@@ -0,0 +1,327 @@
+"""DecL-helpers routes: the family that asks the grammar about text.
+
+None of these builds anything. They cost a parse, not a convolution, and
+they create no object and no cache entry.
+
+Routes
+------
+
+* ``POST /v1/decl/complete``: accepts ``(decl, cursor)`` and returns
+  terminal-level completion candidates for the editor.
+* ``POST /v1/decl/lex``: accepts ``decl`` and returns the token stream,
+  for client-side syntax highlighting that prefers authoritative tokens
+  over a TextMate or language-server clone.
+* ``POST /v1/decl/parse``: accepts ``decl`` and returns the
+  ``(kind, name, spec)`` triple the parser understood, one entry per
+  statement. Added at a192 for an external client that needs the
+  structure of a program and must not read it back out of text.
+* ``POST /v1/decl/format``: accepts ``decl`` and returns the program
+  re-rendered canonically, echoing the input on any failure.
+* ``GET  /v1/decl/grammar``: serves ``decl.lark`` verbatim as
+  ``text/plain``. Lets a future docs page embed the live grammar without a
+  build-time include step.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import PlainTextResponse
+
+from aggregate.parser_errors import format_error
+
+from .. import models
+from ..completion import complete, lex
+from ..serializers import spec_to_payload
+
+
+router = APIRouter()
+
+
+class _StatementParseError(Exception):
+    """A statement the parser refused, carrying its index in the program.
+
+    Parameters
+    ----------
+    index : int
+        Zero-based position of the failing statement in the preprocessed
+        program. A program that will not even split reports 0.
+    statement : str
+        The text actually handed to the parser, which is the preprocessed
+        statement, or the whole program when the split itself failed. This is
+        the right ``source`` for a report, because it is what the column and
+        caret are measured against.
+    cause : BaseException
+        What the parser raised. ``aggregate.parser_errors.format_error`` turns
+        it into the rich report.
+    """
+
+    def __init__(self, index: int, statement: str, cause: BaseException) -> None:
+        super().__init__(f"statement {index} did not parse")
+        self.index = index
+        self.statement = statement
+        self.cause = cause
+
+
+def _parse_statements(decl: str) -> list[tuple[str, str, dict]]:
+    """Split ``decl`` into statements and parse each one, in source order.
+
+    Parameters
+    ----------
+    decl : str
+        A DecL program, one statement or several.
+
+    Returns
+    -------
+    list of tuple
+        One ``(kind, name, spec)`` triple per statement, the parser's own
+        return value, untouched.
+
+    Raises
+    ------
+    _StatementParseError
+        On the first statement that will not parse, or when the program will
+        not split at all.
+
+    Notes
+    -----
+    The two library names are both public and both the ones the writer itself
+    uses, so this predicts the writer's behavior rather than guessing at it.
+    ``UnderwritingLexer.preprocess`` splits on **blank** lines, not on every
+    newline: a single newline plus indentation is a continuation and folds into
+    one space, which is how a program spread over five lines stays one
+    statement.
+
+    Each statement is parsed against ``aggregate.build`` alone, so a name a
+    statement declares is not in scope for the statements after it. See
+    :func:`_every_statement_parses`, which is where that costs something.
+    """
+    try:
+        from aggregate import build
+        from aggregate.parser import UnderwritingLexer
+        statements = UnderwritingLexer.preprocess(decl)
+    except Exception as exc:  # noqa: BLE001 (a program that will not even split)
+        raise _StatementParseError(0, decl, exc) from exc
+    parsed: list[tuple[str, str, dict]] = []
+    for index, statement in enumerate(statements):
+        try:
+            parsed.append(build.parser.parse(statement))
+        except Exception as exc:  # noqa: BLE001 (parse error, or unresolved name)
+            raise _StatementParseError(index, statement, exc) from exc
+    return parsed
+
+
+def _every_statement_parses(decl: str) -> bool:
+    """Whether every statement in ``decl`` parses, which is what Reformat needs.
+
+    Parameters
+    ----------
+    decl : str
+        A DecL program, one statement or several.
+
+    Returns
+    -------
+    bool
+        True when the writer will canonicalize the whole program, False when
+        at least one statement will come back as source text instead.
+
+    Notes
+    -----
+    **This exists because ``format_program``'s fallback is not the no-op it
+    reads as, and a137 is where that cost the author a program.** The writer
+    renders statement by statement through ``_render_statement``, which catches
+    every exception and returns the statement instead of a render node. The
+    statement it returns is not the source, though: it is the source after
+    ``UnderwritingLexer.preprocess``, which is what splits the program at all,
+    and preprocessing folds every newline and every run of indentation into one
+    space. So a program the writer cannot read comes back **collapsed onto one
+    line**, the SPA sees text that differs from what it sent, writes it into the
+    editor, and the reader's carefully spread program is gone. Pressing the
+    button that formats a program is how you lose its formatting.
+
+    Three ways in, all reachable from an ordinary session: a statement using a
+    spelling a grammar change retired, a statement naming something the default
+    underwriter cannot resolve, and, the one that surprises, a second statement
+    referring to a name the **first** statement defines. The writer parses each
+    statement against ``aggregate.build`` alone, so ``sev MySev ...`` followed by
+    ``agg A ... sev.MySev ...`` renders the first and collapses the second.
+
+    Asking the same parser the same question first is what makes the route's
+    standing promise ("a malformed program reformats to itself") true. It parses
+    the program twice on the way to a canonical answer, which is the right
+    trade for a button a reader presses by hand: correctness for a few
+    milliseconds nobody can perceive.
+
+    ``UnderwritingLexer.preprocess`` and ``Underwriter.parser`` are both public
+    names, and they are the two the writer itself uses, so this predicts the
+    fallback rather than guessing at it. The remaining gap is a statement that
+    parses and then fails while rendering; that is a library defect when it
+    happens rather than a program the reader can fix, and it is raised upstream
+    rather than guarded here.
+    """
+    try:
+        _parse_statements(decl)
+    except _StatementParseError:
+        return False
+    return True
+
+
+def _format_decl(decl: str) -> str:
+    """Canonicalize a DecL program, echoing the original on any failure.
+
+    ``format_program`` lives in ``aggregate.decl_writer`` and parses and builds
+    the program internally, so it can raise on malformed input. That must never
+    500 the format helper, so a failure falls back to the input and a malformed
+    program reformats to itself.
+
+    Notes
+    -----
+    **The gate in front of it, which is what a137 added.** The echo has to be
+    the text that came in, and until a137 it was not: the writer answers an
+    unreadable statement with its own preprocessed copy, which is the statement
+    with every line break folded into a space, and the SPA wrote that into the
+    editor. See :func:`_every_statement_parses` for the three ways a program
+    reaches that path and why the answer is to ask the parser first.
+
+    **``trailer=True``, which is the whole of what a126 changed here.** The
+    writer's signature is
+    ``(spec_or_text, *, fmt='text', layout='spread', trailer=False)`` and it
+    emits the trailer as a unit, so at the default every ``note{}``, ``hints{}``
+    and ``tags{}`` in the program is silently dropped. That made Reformat delete
+    the clause Sharpen had just written: press one to pin a grid, press the
+    other to tidy the layout, and the pinning is gone. A grid a program does not
+    state is a grid the next build is free to choose differently, so this was
+    losing meaning rather than formatting.
+
+    A reader who types their own ``tags{}`` now keeps it through a Reformat too,
+    on the same rule as the note (author ruling, 2026-08-24). This does not fight
+    the Examples library: a loaded entry arrives with note and tags already
+    stripped, so there is nothing on that path for Reformat to restore.
+
+    ``format_program`` still round trips through the spec, so Reformat continues
+    to rewrite ``ph 2/3`` as a float and ``dsev [1:6]`` as six values. That is
+    the writer working as designed and is tracked upstream as
+    ``[Unparser-Reference-Gaps]``; it is why the Examples menu serves
+    ``Recipe.as_read`` instead of coming through here.
+    """
+    if not _every_statement_parses(decl):
+        return decl
+    try:
+        from aggregate.decl_writer import format_program
+        out = format_program(decl, fmt="text", trailer=True)
+        return out or decl
+    except Exception:  # noqa: BLE001 (formatting is best-effort)
+        return decl
+
+
+@router.post("/decl/complete", response_model=models.CompletionsResponse)
+def decl_complete(req: models.DeclCompleteRequest) -> dict:
+    """Return completion candidates for ``decl[:cursor]``.
+
+    FastAPI deserializes the JSON body into ``req`` automatically;
+    we just unpack and call into the completion module.
+    """
+    return {"completions": complete(req.decl, req.cursor)}
+
+
+@router.post("/decl/lex", response_model=models.LexResponse)
+def decl_lex(req: models.DeclLexRequest) -> dict:
+    """Return the token stream for ``req.decl``.
+
+    On a tokenization error returns an empty list. Callers should hit
+    ``POST /v1/objects`` to see the structured :class:`ErrorReport`.
+    """
+    return {"tokens": lex(req.decl)}
+
+
+@router.post("/decl/format", response_model=models.DeclFormatResponse)
+def decl_format(req: models.DeclFormatRequest) -> dict:
+    """Return ``req.decl`` re-rendered in canonical form.
+
+    Notes
+    -----
+    Two callers, and neither is the one this docstring used to name. It said
+    the SPA standardizes a program loaded from the Examples library, which
+    stopped being true at a122: a library entry now arrives as its own file's
+    text and needs no round trip, and putting it through one would undo the
+    spellings the entry exists to teach. What is left is the **Reformat**
+    button and the ``grossceded`` prefix path, which reformats on the way
+    through because it is rewriting the program anyway.
+
+    Best-effort: malformed input echoes back unchanged.
+    """
+    return {"decl": _format_decl(req.decl)}
+
+
+@router.post("/decl/parse", response_model=models.DeclParseResponse)
+def decl_parse(req: models.DeclParseRequest) -> dict:
+    """Return what the parser understood about ``req.decl``, as data.
+
+    One ``(kind, name, spec)`` entry per statement, in source order. Nothing is
+    built, nothing is cached, nothing is audited as a build: this is the
+    grammar answering a question about text, like its three siblings above, and
+    it costs a parse rather than a convolution.
+
+    Notes
+    -----
+    **The spec is the library's vocabulary**, served as an open object rather
+    than a mirrored schema, for the reason
+    :class:`~aggregate_api.models.ParsedStatement` gives. Two coercions a
+    client has to expect, both from
+    :func:`~aggregate_api.serializers.spec_to_payload`: a tuple arrives as an
+    array, so a reinsurance layer reads as ``[share, limit, attach]``; and a
+    non-finite float arrives as the string ``"inf"``, ``"-inf"`` or ``"nan"``,
+    which is the spelling the grammar accepts for an unlimited layer and the
+    only form that keeps an unlimited limit apart from an absent one. ``inf``
+    is not exotic: ``sev_ub`` carries it on the plainest one-line ``agg``.
+
+    **Statements are split on blank lines**, the rule
+    ``UnderwritingLexer.preprocess`` has always applied, so a program spread
+    over several indented lines is one statement and two programs separated by
+    an empty line are two.
+
+    **Each statement resolves against the default underwriter**, as
+    :func:`_every_statement_parses` and ``format_program`` both do, so a
+    ``sev.X`` or ``agg.X`` reference into the recipe base resolves and a
+    builtin reference resolves inline. The consequence worth stating: a program
+    whose second statement refers to a name its **first** statement declares
+    does not parse, because nothing here feeds the first statement's result
+    back into scope for the second.
+
+    **A parse failure is the structured error path**, not a 200 with an empty
+    list: HTTP 422 whose ``detail`` is the ``aggregate.parser_errors``
+    ``ErrorReport`` dict that ``POST /v1/objects`` already returns, with
+    ``line``, ``column``, ``source``, ``caret`` and ``suggestions``, plus one
+    added key, ``statement_index``, naming which statement failed. ``source``
+    is that statement rather than the whole program, because the column and the
+    caret are measured against what the parser was handed.
+    """
+    try:
+        parsed = _parse_statements(req.decl)
+    except _StatementParseError as exc:
+        detail = format_error(exc.statement, exc.cause).to_dict()
+        detail["statement_index"] = exc.index
+        raise HTTPException(status_code=422, detail=detail) from None
+    return {
+        "statements": [
+            {"kind": kind, "name": name, "spec": spec_to_payload(spec)}
+            for kind, name, spec in parsed
+        ]
+    }
+
+
+@router.get(
+    "/decl/grammar",
+    response_class=PlainTextResponse,
+    responses={200: {"content": {"text/plain": {}}}},
+)
+def decl_grammar() -> PlainTextResponse:
+    """Return the bundled ``decl.lark`` as plain text.
+
+    Reads via ``importlib.resources`` so the result is the installed
+    package's grammar, which works whether the package is installed as a
+    regular site-package, a zip, or an editable install.
+    """
+    text = files("aggregate").joinpath("decl.lark").read_text(encoding="utf-8")
+    return PlainTextResponse(text)

aggregate_api/routes/examples.py

@@ -0,0 +1,82 @@
+"""Example-library routes.
+
+Two endpoints over ``aggregate``'s recipe base (``library.agg``):
+
+* ``GET /v1/examples``: the whole library, one flat list in file order.
+* ``GET /v1/examples/heroes``: just the ``role:hero`` entries, for the
+  landing gallery.
+
+Both loaders are ``lru_cache``d in :mod:`aggregate_api.examples`, so the recipe
+base is walked once per process. The routes are thin wrappers.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Query
+
+from .. import models
+from ..examples import (
+    filter_examples, load_examples, load_hero_sparklines, load_heroes,
+)
+
+
+router = APIRouter()
+
+
+@router.get("/examples", response_model=models.ExamplesResponse)
+def list_examples(
+    kind: list[str] | None = Query(
+        None, description="Keep only these recipe kinds (agg, port, sev, ...)."
+    ),
+    topic: list[str] | None = Query(
+        None, description="Keep only these topic: values, unprefixed."
+    ),
+    role: list[str] | None = Query(
+        None, description="Keep only these role: values, unprefixed."
+    ),
+) -> dict:
+    """Return the example library, one flat list in the library's own order.
+
+    See :class:`ExamplesResponse` for the payload shape. Every entry appears
+    exactly once, in the order ``library.agg`` declares it.
+
+    Notes
+    -----
+    The three filters are repeatable and compose as OR within a namespace and
+    AND across them, so ``?role=intro&role=intermediate&topic=severity`` is the
+    easy half of the severity entries.
+
+    **The SPA does not pass them.** The whole payload is 151 entries fetched
+    once and filtered in the browser, where the pills and the list stay in step
+    with no round trip. These exist for a notebook reading the api directly.
+
+    ``?group=topic|kind|role`` stood here through a121 and is gone rather than
+    deprecated: the api is private and pre-release, so a clean break costs
+    nothing and leaving a grouped view behind would have kept the ordering
+    tables it needed.
+    """
+    return filter_examples(load_examples(), kind=kind, topic=topic, role=role)
+
+
+@router.get("/examples/heroes", response_model=models.HeroesResponse)
+def list_heroes() -> dict:
+    """Return the entries tagged ``role:hero``, the landing-page gallery.
+
+    Nothing is built here: ``discover``'s directory path filters the recipe
+    frame, so this is as cheap as the full listing.
+    """
+    return load_heroes()
+
+
+@router.get("/examples/heroes/sparklines", response_model=models.SparklinesResponse)
+def hero_sparklines() -> dict:
+    """Density silhouettes for the hero cards, keyed by entry name.
+
+    **Slow on the first call**, which is the whole reason it is a separate
+    endpoint: it builds every hero, and one of them carries ``hints{log2=16}``.
+    Cached for the process afterwards.
+
+    The SPA calls this *after* first paint and leaves the cards on their
+    placeholder art until it resolves, so the landing page never waits on it.
+    """
+    return load_hero_sparklines()