iomgaa
6bdb802f01
- Add all claude skills (brainstorming, commit, debugging, TDD, etc.) - Add claude hooks (pre-commit-guard, post-edit-quality) - Add research templates (experiment plan, research brief, etc.) - Add claude tools (arxiv/semantic_scholar/openalex fetch, wiki, exa) - Add TRM4 reference implementation as algorithm fidelity baseline - Add research-wiki content (plans, index, graph, query_pack) - Update .gitignore to exclude .graphify_version runtime state
104 lines
5.0 KiB
Markdown
104 lines
5.0 KiB
Markdown
# graphify reference: query, path, explain
|
|
|
|
Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow.
|
|
|
|
Two traversal modes - choose based on the question:
|
|
|
|
| Mode | Flag | Best for |
|
|
|------|------|----------|
|
|
| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
|
|
| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
|
|
|
|
### Step 0 — Constrained query expansion (REQUIRED before traversal)
|
|
|
|
graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
|
|
|
|
Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
|
|
|
|
1. Extract the token vocabulary from node labels:
|
|
```bash
|
|
$(cat graphify-out/.graphify_python) -c "
|
|
import json, re
|
|
from pathlib import Path
|
|
data = json.loads(Path('graphify-out/graph.json').read_text())
|
|
vocab = set()
|
|
for n in data['nodes']:
|
|
for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
|
|
parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
|
|
for p in parts:
|
|
t = p.lower()
|
|
if 3 <= len(t) <= 30:
|
|
vocab.add(t)
|
|
Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)))
|
|
print(f'vocab: {len(vocab)} tokens')
|
|
"
|
|
```
|
|
|
|
2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
|
|
- You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
|
|
- If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
|
|
- If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
|
|
- Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
|
|
- Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
|
|
|
|
3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
|
|
```
|
|
Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
|
|
```
|
|
If the list is empty, say so plainly and stop — do not proceed to traversal.
|
|
|
|
### Step 1 — Traversal
|
|
|
|
Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
|
|
|
|
```bash
|
|
graphify query "QUESTION"
|
|
# or: graphify query "QUESTION" --dfs --budget 3000
|
|
```
|
|
|
|
Answer using **only** what the graph output contains. Quote `source_location` when citing a specific fact. If the graph lacks enough information, say so - do not hallucinate edges.
|
|
|
|
After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
|
|
|
|
```bash
|
|
$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
|
|
```
|
|
|
|
Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
|
|
|
|
---
|
|
|
|
## For /graphify path
|
|
|
|
Find the shortest path between two named concepts in the graph.
|
|
|
|
```bash
|
|
graphify path "NODE_A" "NODE_B"
|
|
```
|
|
|
|
Replace `NODE_A` and `NODE_B` with the actual concept names. Then explain the path in plain language - what each hop means, why it's significant.
|
|
|
|
After writing the explanation, save it back:
|
|
|
|
```bash
|
|
$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
|
|
```
|
|
|
|
---
|
|
|
|
## For /graphify explain
|
|
|
|
Give a plain-language explanation of a single node - everything connected to it.
|
|
|
|
```bash
|
|
graphify explain "NODE_NAME"
|
|
```
|
|
|
|
Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
|
|
|
|
After writing the explanation, save it back:
|
|
|
|
```bash
|
|
$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
|
|
```
|