Korean Herbal Formula Knowledge Graph

Korean herbal formulas are often stored as flat lists, which makes names retrievable but leaves a harder question unanswered: which relationship came from which source, and what did the source actually state? I began this project as a Korean medicine student to represent formula composition as a queryable graph without detaching each fact from its provenance. The repository currently implements a deliberately small vertical slice—one formula and four herbs—before any embedding, agent, or interface layer.

Architecture

flowchart LR
    A["Formula and herb YAML<br/>identity, composition, source_refs"] --> B["PyYAML safe_load<br/>loader.py"]
    B --> C["Pydantic validation<br/>models.py"]
    C --> D["Validated records<br/>with source YAML paths"]
    D --> E["NetworkX DiGraph<br/>graph.py"]
    E --> F["Exact-name CLI query<br/>query.py"]
    F --> G["Ordered herbs, roles,<br/>YAML paths, and source refs"]
    C -.->|invalid field| H["DataValidationError<br/>file and field path"]
    E -.->|inconsistent reference| I["GraphBuildError<br/>missing herb or name mismatch"]

Loading

Demo

Quick Start

The commands below were verified with Python 3.9.6.

git clone https://github.com/jjasminum02-debug/tcm-formula-knowledge-graph.git
cd tcm-formula-knowledge-graph

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

python query.py 사군자탕

The same record can be queried by its Hanja name:

python query.py 四君子湯

Tech Stack

• Pydantic — strict record validation and cross-field constraints
• PyYAML — UTF-8 YAML parsing with safe_load
• NetworkX — directed formula-to-herb graph construction

Roadmap

Built

• Strict formula, herb, ingredient, and source-reference models
• File-aware validation errors with JSON-style field paths
• Duplicate entity, composition sequence, and source-reference consistency checks
• Formula and herb nodes connected by ordered contains edges
• Node- and edge-level YAML provenance and document/page/segment references
• Exact Korean, Hanja, and alias lookup from the command line
• Explicit preservation of unknown roles as null, printed as not stated in source
• One source-linked sample formula, 사군자탕 (四君子湯), with four herb records

Planned

• Expand the dataset through reviewable, source-linked YAML records
• Add an automated test suite for schema, graph, and CLI boundary cases
• Add graph queries beyond exact formula-name composition lookup
• Evaluate embedding and vector retrieval only after deterministic provenance tests are in place
• Design MCP, agent, and UI interfaces after retrieval quality and source tracing can be measured