Oleksandr Kozachuk
60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
# SPEC-014 — Codex Mechanicus search
|
|
|
|
Luma is an Adeptus Mechanicus tech-priest; his lore has a real home —
|
|
the priest's own Codex Mechanicus at `binaric.tech` (an Astro/MDX
|
|
archive, five tongues). A `codex_search` function tool lets him consult
|
|
that archive and answer from sourced inscriptions instead of inventing
|
|
lore. The index is public but still untrusted by the time it reaches a
|
|
prompt: the fetch is SSRF-guarded (SPEC-011 shares `guard_url`),
|
|
size-bounded, and every returned field is sanitized (SAF-03). Luma-only;
|
|
active only when `enable-codex = true`.
|
|
|
|
### CDX-01 — codex_search is offered as a tool (coverage: test)
|
|
|
|
When `enable-codex` is true, the chat call's `tools` list includes a
|
|
`codex_search` function (`query` string, optional `lang`) next to any
|
|
IGDB / fetch_url tools. When false, it is absent.
|
|
|
|
### CDX-02 — The index is fetched safely and cached (coverage: test)
|
|
|
|
The index URL (`codex-index-url`, default
|
|
`https://binaric.tech/search-index.json`) passes the SSRF guard before
|
|
any network call, is read under a byte cap (`codex-max-bytes`, default
|
|
4 MB) with a download timeout, and is cached in memory for
|
|
`codex-cache-ttl` (default 3600 s) so repeated searches do not re-fetch.
|
|
|
|
### CDX-03 — Ranking weights title over summary over body (coverage: test)
|
|
|
|
The query is tokenized (stopwords dropped); each inscription is scored
|
|
by term hits weighted title (8) > summary (3) > body (1). Results are
|
|
returned highest-score first, each as `{title, summary, collection,
|
|
url}`, with `url` absolute against the site origin.
|
|
|
|
### CDX-04 — Language is preferred, with fallback (coverage: test)
|
|
|
|
Results are filtered to the requested `lang` (en, de, eo, no, uk;
|
|
default en; unknown codes fall back to en) by the language segment in
|
|
each inscription URL. If no inscription in that tongue matches, the
|
|
search falls back to all tongues rather than returning nothing.
|
|
|
|
### CDX-05 — Results are sanitized and failure is reported (coverage: test)
|
|
|
|
Each `title` and `summary` is passed through `sanitize_external_text`
|
|
and length-capped (`codex-summary-chars`, default 500). An index that
|
|
cannot be fetched or parsed returns an `{error: ...}` dict the model can
|
|
relay — `search` never raises.
|
|
|
|
### CDX-06 — Searches are metered per user (coverage: test)
|
|
|
|
Each `codex_search` increments a per-user daily counter; over
|
|
`codex-daily-per-user` (default 50) the tool refuses with an error
|
|
result without touching the index. The budget gate (SAF-04) still
|
|
applies to the surrounding model calls.
|
|
|
|
### CDX-07 — Luma cites the codex, not invention (coverage: manual)
|
|
|
|
With the persona grounding line, when a pilgrim asks Cult Mechanicus
|
|
lore Luma consults `codex_search` and answers from it, offering the
|
|
`binaric.tech` link to read the full inscription rather than
|
|
hallucinating. Verified live on ggg.
|