An auditable retrieval system that maps Victoria 3 player slang to official game mechanics through a reviewed concept layer, then returns both community and official evidence. The public snapshot focuses on retrieval/runtime engineering; private raw corpora, crawler credentials, generated indexes, and copyrighted source text are not distributed.
面向《Victoria 3》玩家黑话与官方机制对齐的可审计 GraphRAG：玩家怎么说 → 标准概念 → 官方机制与玩家证据。
flowchart LR
Q[Player query] --> N[Normalization]
N --> L[Lexical / exact retrieval]
N --> S[Optional BGE-M3 semantic channel]
L --> C[Reviewed concept graph]
S --> C
C --> F[Late fusion + safety guards]
F --> W[Official wiki evidence]
F --> P[Player-source evidence]
W --> T[Read-only MCP tools]
P --> T
Player language is often not a paraphrase of official terminology. A direct vector search can retrieve topically similar text without proving the intended game mechanic. This project keeps five auditable assets separate:
- standard concepts;
- player aliases;
- player evidence spans;
- concept-to-wiki links;
- rejected candidates and review decisions.
Retrieval combines exact/lexical signals with an optional dual-view semantic channel. Text and metadata embeddings are fused late, while exact matches, evidence references, fallback behavior, and read-only boundaries remain guarded.
These are measurements from the private research corpus and generated index; they are not claims that the public snapshot bundles the data.
| Asset | Scale |
|---|---|
| Official wiki blocks | 5,519 |
| Player sources / chunks | 434 / 7,280 |
| Standard concepts / aliases | 423 / 1,434 |
| Player evidence / concept-to-wiki links | 1,364 / 613 |
| Reviewed BGE-M3 alignment seeds / hard negatives | 642 / 508 |
| Dual-view semantic index | 13,222 items, 6 vector groups/item, 5.2 GiB |
| Streaming build memory | 13.48 → 5.85 GiB (about 57% lower) |
On a 320-query AI-reviewed pilot benchmark, the metadata view changed player-source hit@5 from 0.1625 to 0.1688 (+0.63pp). The bootstrap 95% interval was [0.0, 0.025], so this is a directional result rather than a statistically established improvement. The pilot recorded zero exact/reference/fallback regressions.
The current semantic preview uses exact vector scanning. It does not implement HNSW or another ANN index yet, and semantic retrieval is default-off behind explicit health/fallback checks. This repository is an engineering/research prototype, not a production search service.
rag_runtime/scripts/: concept retrieval, fusion, semantic channel, evaluation, MCP/JSON-RPC tools.rag_runtime/interfaces/: tool schemas and example MCP configuration.player_corpus/scripts/: deterministic source/index builders required by the runtime tests.wiki_collector/scripts/rag_index.py: read-only official-index adapter.rag_runtime/tests/: synthetic fixtures covering retrieval, fusion, variants, semantic guards, MCP, and ablations.
Not included: Firecrawl integration, API keys, raw Reddit/community exports, copied wiki text, production JSONL/SQLite data, BGE-M3 model artifacts, semantic indexes, logs, internal research workspaces, or third-party PDFs.
The tests create synthetic temporary corpora and do not require the private dataset or paid APIs.
python -m pip install -r requirements-dev.txt
python -m pytest -q rag_runtime/tests \
--ignore=rag_runtime/tests/test_eval_dataset.py \
-p no:cacheproviderOptional semantic-index building dependencies are isolated in requirements-semantic.txt; Torch and FlagEmbedding are lazy imports and are not required for the default lexical/runtime tests.
The runtime exposes read-only tools for concept lookup, source search, evidence expansion, and health inspection. Every result keeps source identifiers and evidence references so an agent can cite where a mapping came from rather than treating retrieval as an opaque answer generator.
This project is consumed by the separate vic3-agent-harness benchmark through an MCP client boundary.