trading-system-docs/tolaria/c4b-search-service

C4B — TOLARIA SEARCH SERVICE (Keyword & Metadata Search)

Phase: C4B Typ: Agentenunabhängiger, abgeleiteter Retrieval-Dienst (Weg A). Indexquelle: Forgejo-SoT (Source of Truth). Der Index ist DERIVED und jederzeit aus index_source.json rebuildbar. Kein pgvector, kein Vector-Store, keine Embeddings (C4C). Stdlib-only Python.

Zweck

Der Such-Dienst macht die Tolaria-Knowledge-Objects durchsuchbar (exact / keyword / metadata). Er ist read-only gegen den Index und schreibt NIE nach Forgejo oder Tolaria. Semantic/Vector/Hybrid sind NICHT implementiert (Honest Mode → mode_not_implemented), sie werden in C4C adressiert.

Komponenten

Datei	Zweck
search_engine.py	Kern-Engine: Tokenisierung, Index, Ranking, Collapse, Secret-Scan
search_api.py	TolariaSearch-API, Result-Contract, SUPPORTED_MODES, Honest Mode, Pagination
server.py	HTTP-Server (/api/search, /api/search/health, kontrollierter Rebuild)
rebuild.py	Rebuild-CLI aus index_source.json
run_tests.py	C4B-Test-Suite: 22er-Ground-Truth v1.1, Acceptance, Quality, Latency, Failure. Validiert Ground-Truth zuerst (GROUND_TRUTH_IDS_VALID); bei ungültigen IDs → TEST SUITE BLOCKED.
fresh_checker.py	Unabhängiger Fresh Checker (gegen Live-API)
erratum_build.py	Erzeugt test_corpus_v1.1.json aus v1.0 (Ground-Truth-Erratum, verifiziert gegen SoT)
test_corpus_v1.0.json	C4A-Evidence (eingefroren, unverändert — Original mit korrupten IDs, Doku nur)
test_corpus_v1.1.json	Korrigierter, versionierter Ground-Truth-Corpus (kanonisch)
C4A_GROUND_TRUTH_ERRATUM.md	Erratum-Report (ROOT_CAUSE, OLD→CORRECT SOT ID, Verifikation)
index_source.json	Abgeleitete Indexquelle aus SoT-Frontmatter (84 Objekte, rebuildbar)

Rebuild & Test (lokal)

python3 rebuild.py --source index_source.json     # baut data/search_index.json
python3 run_tests.py                              # 22er Corpus + Quality + Latency + Failure
python3 fresh_checker.py                          # Freshness gegen Live-API (Port 8325)
python3 erratum_build.py                          # (re-)erzeugt test_corpus_v1.1.json

Betrieb

TOLARIA_SEARCH_PORT=8325 python3 server.py         # HTTP auf 0.0.0.0:8325
curl http://localhost:8325/api/search/health
curl -X POST http://localhost:8325/api/search -H 'Content-Type: application/json' \
     -d '{"query":"Modul-09","mode":"exact"}'

Honest Mode

• exact = echt, keyword = echt, metadata = echt.
• semantic/vector/hybrid → mode_not_implemented (kein Silent-Fallback). Kein Fake-Semantic.

Security

• Secret-Scan läuft fail-closed vor dem Index; keine Secret-Werte im Index/Report.
• Rebuild-Admin-Endpoint nur mit ephemerem Token (TOLARIA_SEARCH_REBUILD_TOKEN).
• Keine Credentials in diesem Repo.

Status (C4B)

• IMPLEMENTATION_STATUS: COMPLETE (lokal, test-runtime-verifiziert)
• TEST_RUNTIME_STATUS: PASS (22/22 Corpus v1.1; Quality/Latency/Failure gemessen)
• PRODUCTION_DEPLOYMENT_STATUS: NICHT deployed — läuft als eigenständiger lokaler/optionaler Dienst; produktiver VPS-Deploy nicht Gegenstand von C4B.