Getting Started

Getting Started

This demo needs Python 3.12 and about 90 MB of disk space for the embedding model, which the first index run downloads once. After that everything runs offline, and no API key is required, because the default provider is a deterministic mock. It was tested on Windows, and the commands below follow that platform. A clean copy went through these steps on 2026-11-06 with Python 3.12.10, and the output shown came from that run.

Install

git clone https://github.com/dboles99/tm-rag-copilot.git
cd tm-rag-copilot
python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt

First run

Build the index. This step took about 14 seconds on the test machine, and search, translate, and eval also build it automatically if ./.qdrant is missing.

.venv\Scripts\python -m tm_rag index

Indexed 133 units into .qdrant (collection 'tm', model sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2)

Search by meaning. The query below shares no words with the unit it finds, which is the point of using embeddings.

.venv\Scripts\python -m tm_rag search "start a brand new playthrough" --k 5 --target-lang zh-CN

0.6391	ui-new-game	en->zh-CN	New Game -> 新游戏
0.5211	dlg-017	en->zh-CN	New Game+ unlocked -> 解锁新周目
0.4282	ui-save-game	en->zh-CN	Save Game -> 保存游戏
0.4073	ui-load-game	en->zh-CN	Load Game -> 读取游戏
0.3274	ui-quit	en->zh-CN	Quit Game -> 退出游戏

The memory also answers a query in Chinese against its English sources:

.venv\Scripts\python -m tm_rag search "保存我的游戏进度" --k 3

0.7326	ui-save-game	en->zh-CN	Save Game -> 保存游戏
0.7326	ui-save-game@th	en->th	Save Game -> บันทึกเกม
0.7326	ui-save-game@zh-TW	en->zh-TW	Save Game -> 儲存遊戲

Those three identical scores show the crowding problem that the zh-CN filter solves: one English source, three variants, and one embedding.

Translate one segment, and see QA fail

The default provider copies the closest match, and it says so. That makes this command a useful first look at QA, because the mock returns a template with a placeholder and the rule catches it:

.venv\Scripts\python -m tm_rag translate "Costs 50 mana"

The output is JSON, and the parts that matter are these:

"translation": "消耗 %d 点法力",
"notes": ["mock provider copied the closest TM match 'combat-mana-cost'; it is not a model"]
...
"check": "number_preservation", "passed": false, "detail": "missing numbers: ['50']"
...
"qa_passed": false

The failure is correct. The mock does not translate, so the number 50 never reached the output, and the check reports that.

Measure it

Writing results to a new folder leaves the committed files unchanged.

mkdir out
.venv\Scripts\python -m tm_rag eval --k 1 3 5 10 --target-lang zh-CN --results out\zhcn.json

The figures should match results/eval_zhcn.json, with an MRR of 0.6755 and a mock QA pass rate of 0.8293.

Run the tests:

.venv\Scripts\python -m pytest -q

57 passed

Optional: a real model

The model evaluation needs a local Ollama server with qwen2.5-coder:14b pulled, and it took about nine minutes for 41 items in the recorded run.

.venv\Scripts\python -m tm_rag eval --k 1 3 5 10 --provider ollama --results out\qwen.json

The --base-url, --model, and --timeout options point it at another OpenAI-compatible server. The translate command does not offer ollama, so a single segment through a real model needs --provider openai-compatible and the variables TM_RAG_LLM_BASE_URL and TM_RAG_LLM_MODEL.

Rebuild the results page

.venv\Scripts\python -m tm_rag report

This command rewrites docs/index.html and docs/recall.svg from results/*.json. The published copy is at dboles99.github.io/tm-rag-copilot.

Next, How It Works follows one query through three configurations, and Evidence sets out every measured result.