53 lines
3.1 KiB
Markdown
53 lines
3.1 KiB
Markdown
# 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)
|
|
```bash
|
|
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
|
|
```bash
|
|
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.
|