TCGRuler

Generic TCG knowledge graph generator. Input any trading card game's rulebook (PDF/TXT/HTML), get a structured bilingual (EN+CN) concept graph with complexity metrics and interactive visualization.

Features

• Any TCG — LLM automatically analyzes rulebook structure, discovers game-specific concept types, generates extraction config
• Bilingual — English + Chinese definitions aligned by rule reference
• Knowledge Graph — concepts, relations (9 canonical types), and rule text linkage stored in SQLite + FTS5
• Complexity Metrics — intrinsic complexity (1-5) + understanding complexity (recursive dependency sum)
• Multi-game — single server/UI serves multiple games simultaneously
• 5 Visualization Views — force-directed graph, complexity heatmap, dependency explorer, chapter overview, keyword interaction matrix
• Full-text Search — bilingual FTS5 search with CJK tokenization support

How It Works

Rulebook (PDF/TXT/HTML) + Game Name
        │
  ┌─────▼──────┐
  │  0. Ingest  │  Unified file reader → plain text
  ├─────▼──────┤
  │  1. Analyze │  LLM infers structure → game_profile.yaml
  ├─────▼──────┤
  │  2. Parse   │  Split chapters/rules by profile patterns, align EN/CN
  ├─────▼──────┤
  │  3. Extract │  LLM extracts concepts + relations (batch + cache + retry)
  ├─────▼──────┤
  │  4. Build   │  SQLite + FTS5 database
  ├─────▼──────┤
  │  5. Normalize│ Canonicalize 100+ relation types → 9 standard types
  └─────▼──────┘
        │
  Express API (:3001) → React + Cytoscape.js UI (:5173)

Quick Start

Prerequisites

• Python 3.10+
• Node.js 20+
• An Anthropic API key

1. Clone and install

git clone https://github.com/silvery5d/TCGRuler.git
cd TCGRuler

# Set up API key
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

# Python dependencies
cd parser && pip install -r requirements.txt && cd ..

# Server
cd server && npm install && cd ..

# Client
cd client && npm install && cd ..

2. Run the pipeline

cd parser

# First run: provide game name and rulebook file(s)
python run_pipeline.py --game "Yu-Gi-Oh!" --en path/to/rules_en.pdf --cn path/to/rules_cn.pdf

# The pipeline will pause after Stage 1 (Analyze) — review data/{slug}/game_profile.yaml
# Then re-run to continue:
python run_pipeline.py --slug yu_gi_oh

3. Start the app

# Terminal 1: API server
cd server && npm run dev

# Terminal 2: UI
cd client && npm run dev

Open http://localhost:5173 — select your game from the list and explore!

CLI Reference

# Full pipeline with new game
python run_pipeline.py --game "Game Name" --en rules.pdf --cn rules_cn.pdf

# Re-run with existing profile (skips analyze)
python run_pipeline.py --slug game_name

# Regenerate the game profile
python run_pipeline.py --slug game_name --re-analyze

# Force re-extract all concepts
python run_pipeline.py --slug game_name --force

Game Profile

Stage 1 (Analyze) generates a game_profile.yaml that drives the rest of the pipeline:

game:
  name: "Yu-Gi-Oh!"
  slug: yu_gi_oh

structure:
  chapter_pattern: "^Section (\\d+):"
  rule_pattern: "^(\\d+-\\d+[A-Z]?)\\.\\s+(.+)"
  stop_markers: ["Appendix", "Index"]

concept_types:
  base: [Chapter, Concept, Zone, CardType, Phase, Step, Keyword, Action]
  custom: [SummonMethod, ChainMechanic]    # game-specific, discovered by LLM

extraction_hints:
  domain_context: "Yu-Gi-Oh! is a TCG where players summon monsters..."
  key_mechanics: [Chain Links, Tribute Summon, Synchro Summon]

You can edit this file to tune extraction before running Stages 2-5.

Tech Stack

Layer	Technology
Parser	Python 3.10+, Anthropic Claude API, pymupdf, BeautifulSoup
Database	SQLite 3.35+ with FTS5 full-text search
API Server	Node.js, Express, TypeScript, better-sqlite3
UI	React 19, Vite 8, Cytoscape.js (fcose layout), Tailwind CSS v4

Project Structure

TCGRuler/
├── parser/                  # Python ETL pipeline
│   ├── ingest.py           # Stage 0: PDF/TXT/HTML → text
│   ├── analyze.py          # Stage 1: LLM → game_profile.yaml
│   ├── parse_rules.py      # Stage 2: profile-driven parsing
│   ├── extract.py          # Stage 3: LLM concept extraction
│   ├── build_db.py         # Stage 4: SQLite + FTS5
│   ├── normalize_relations.py  # Stage 5: relation canonicalization
│   ├── run_pipeline.py     # CLI orchestrator
│   ├── game_profile.py     # Profile loading/validation
│   └── data/{slug}/        # Per-game data directory
├── server/                  # Multi-game Express API
│   └── src/
│       ├── db.ts           # Auto-discovers games from data/
│       └── routes/         # concepts, relations, search, graph, stats, path, games
├── client/                  # React + Cytoscape.js UI
│   └── src/
│       ├── pages/          # GameList, GameView
│       └── components/     # GraphView, SearchBar, DetailPanel, DesignerViews
└── docs/                    # Design spec and implementation plan

Related

• MTGRuler — The original Magic: The Gathering specific version that inspired this project

License

MIT