Admin panel: catalog, quality, usage, settings

How the local panel at 127.0.0.1:8777 works: four blocks, the REST API, the mutation token gate, security, and the interactive emulator.

What it is and why #

ragraf admin raises a local panel (127.0.0.1:8777, loopback only, zero external dependencies — pure Python stdlib + one HTML/CSS/JS bundle). It is the operational console of a corpus: what is in the index, how good it is, how the agent uses it, and which thresholds govern reindexing. The panel is read-only over index data; mutations (settings, cache clear) require a token.

An interactive replica of the panel with real measured data — the site emulator. Everything described below can be "touched" there without installing the product.

Four blocks #

Catalog (corpus) #

Corpus revisions: rev-NNNN, state (ready/degraded), corpus_hash, file counts by parse status, sizes of the three stores, hash_matches (how many files matched the previous revision — the reuse metric). This is where the rebuild economy shows: on the pilot, 123 files → 487 nodes → 7,292 edges → 27.5 MB of stores.

Quality #

Vector norms: distribution of embedding norms (pilot: min 0.0576, max 0.6627) — zero outliers mean broken chunks.
Chunks vs budget: the largest chunk's token size against chunk_budget: 8000 (pilot: max 5,543, over-budget 0).
Truncated signatures: how many symbol signatures were cut (defect U3: 33 → 0 after the fix) — an extractor health indicator.

Usage #

usage_call telemetry: calls by operation, facts, spans, characters and token estimate, runtime errors. A real pilot session profile: 46 calls, write_check — 14, errors 0, estimated savings ~5,200 tokens. Mean latencies: schema 0.5 ms · symbol 0.7 ms · table_usage 0.9 ms · write_check 3.3 ms · search up to ~1 s (dominated by the query embedding).

Settings #

Global thresholds and project values: full_reindex_threshold / fast_reindex_threshold (full > fast validated server-side, not only in the form), joern_enabled, retain_revs. Project-config writes are validated and .bak-copied. The state-cache clear button is token-gated.

REST API #

Method and path	Purpose	Token
`GET /api/state`	catalog and quality summary	—
`GET /api/usage`	telemetry	—
`GET /api/settings`	current thresholds (global + project)	—
`GET /api/health`	liveness and capability	—
`POST /api/settings/global`	change global thresholds	✓
`POST /api/settings/project`	change the project config (with .bak)	✓
`POST /api/cache/clear`	reset the state cache	✓
`GET /api/token`	hand the token to a local client	— (see security)

The token is compared with secrets.compare_digest (timing-safe). The token prints to the console at startup or comes from RAGRAF_ADMIN_TOKEN.

The security model — honestly #

The panel is designed for one machine, one user:

Loopback binding: unreachable from outside (no firewall needed, but none is replaced either).
Mutations — token only; reads — open (index data is no more secret than the code on disk).
Known gap (documented in SECURITY.md and the defect register, C-01): GET /api/token hands the token to any local process. The threat model accepts this consciously: a local process with loopback access can already read the corpus files directly. Hardening (token only from console/env) — on the roadmap, R-SEC.
The panel serves no CSP/headers (a single-user local tool); the website you are reading is a separate application with strict headers.

When the panel helps, and when not #

Helps: tuning reindex thresholds on a live corpus; auditing "what the index knows" after a big edit; reviewing agent telemetry (is the call profile healthy?); product demos. Not needed: CI pipelines (use --json + jq there), headless servers (the panel is interactive), multiple corpora at once (the panel is per-corpus; multi-corpus is in future directions).