ContextQMD
Back to Openviking

Example: Knowledge Graph

docs/en/context-compilation/03-knowledge-graph.md

0.4.164.1 KB
Original Source

Example: Knowledge Graph

Compile a set of sources into an evidence-grounded, visualization-ready knowledge graph: semantically typed entity nodes, statement-level provenance, and typed directed relationship edges. The output is this artifact tree:

text
entities/
  <entity-id>.md      # one file per node; frontmatter carries type/id/title/entity_type/description/sources
relations.jsonl       # one directed edge per line

Each edge is a compact JSON line, readable as the statement <from> <relation> <to>:

json
{"from":"sun-wukong","relation":"member_of","label":"belongs to","to":"pilgrimage-team","evidence":["viking://resources/source.md"]}

relation is a stable, language-independent machine predicate (member_of, leads, located_in…), label is its localized display name, and entity_type drives node color, shape, and filtering in the visualization. The graph refreshes incrementally: existing nodes and edges are preserved, evidence is merged, and new knowledge is appended.

Skill source: examples/compile/ov-compile-skills/knowledge-graph · Visualization script: examples/compile/graph-show/knowledge-graph

Step 1: Prepare the sources

bash
ov add-resource ./journal-to-the-west --to viking://resources/journal --wait
ov ls -r viking://resources/journal

Step 2: Add the Skill

bash
ov add-skill examples/compile/ov-compile-skills/knowledge-graph --wait
ov skills list
# → viking://agent/skills/knowledge-graph

Step 3: Run compile

bash
ov compile \
  --from viking://resources/journal \
  --to viking://resources/journal-kg \
  --skill viking://agent/skills/knowledge-graph \
  --reason "Extract characters, places, artifacts and their relationships into a traversable graph" \
  --wait

Drop --wait to get a task_id back immediately, then:

bash
ov task status cmp_01abc      # progress and final result
ov task cancel cmp_01abc      # cooperative cancel

Step 4: Inspect the output

bash
ov tree viking://resources/journal-kg
ov read viking://resources/journal-kg/relations.jsonl
ov read viking://resources/journal-kg/entities/sun-wukong.md

Step 5: Visualize it as an interactive graph

Unlike the LLM Wiki script, knowledge_graph.py reads from a local directory (it needs both entities/ and relations.jsonl on disk). So download the output first, then generate the HTML.

Download the whole artifact tree. ov get downloads one file at a time; combine it with ov ls -r -s to pull every path:

bash
SRC="viking://resources/journal-kg"
DST="./journal-kg"
mkdir -p "$DST"
ov ls -r -s "$SRC" | while read -r uri; do
  # only download files (entities/*.md and relations.jsonl), skip directories
  case "$uri" in
    */entities|"$SRC") continue ;;
  esac
  rel="${uri#$SRC/}"
  mkdir -p "$DST/$(dirname "$rel")"
  ov get "$uri" "$DST/$rel"
done

ov get requires the local target path to not exist yet, so clear the old directory (rm -rf ./journal-kg) before re-downloading.

Confirm the local layout is correct:

bash
find ./journal-kg          # should show entities/*.md and relations.jsonl

Generate the interactive HTML:

bash
python examples/compile/graph-show/knowledge-graph/knowledge_graph.py \
  ./journal-kg \
  -o journal-kg.html \
  --title "Journey to the West Knowledge Graph"

Open journal-kg.html in a browser. The script validates first — relations.jsonl must be valid JSON, every entity file must have a stable id and title, and both ends of every edge must resolve to an entity node — and fails with the offending line if not, so it doubles as a quality check on the output. Nodes are colored and shaped by entity_type, edges show their localized label, and clicking a node reveals that entity's body, aliases, and sources.