Update README with Next.js web app, Claude integration, and fused design system docs

ceb4fb2 verified 13 days ago

9.57 kB

	# 🔍 GraphRAG Inference Hackathon — Dual Pipeline System

	<div align="center">

	[![TigerGraph](https://img.shields.io/badge/Graph_DB-TigerGraph-orange?style=for-the-badge)](https://www.tigergraph.com/)
	[![Claude](https://img.shields.io/badge/LLM-Claude_Sonnet_4-coral?style=for-the-badge)](https://anthropic.com/)
	[![Next.js](https://img.shields.io/badge/Frontend-Next.js_15-black?style=for-the-badge&logo=next.js)](https://nextjs.org/)
	[![HotpotQA](https://img.shields.io/badge/Benchmark-HotpotQA-purple?style=for-the-badge)](https://hotpotqa.github.io/)
	[![RAGAS](https://img.shields.io/badge/Evaluation-RAGAS-red?style=for-the-badge)](https://ragas.io/)

	Proving that graphs make LLM inference faster, cheaper, and smarter — with real numbers.

	[Web Dashboard](#-web-dashboard-nextjs) · [Architecture](#-architecture) · [Benchmarks](#-benchmark-results) · [Novelties](#-novel-features) · [Design System](#-design-system)

	</div>

	---

	## 🎯 Overview

	A production-ready dual-pipeline GraphRAG system with two interfaces:

	\| \| Next.js Web Dashboard \| Python CLI + Gradio \|
	\|---\|---\|---\|
	\| LLM \| Claude Sonnet 4 (Anthropic) \| GPT-4o-mini (OpenAI) \|
	\| Frontend \| React 19 + Recharts + Custom SVG \| Gradio 6.x + Plotly \|
	\| Design \| TigerGraph × Claude fused design system \| Standard Gradio \|
	\| Best for \| Demos, presentations, judging \| Benchmarking, batch eval \|

	Both interfaces run the same dual-pipeline comparison:

	\| \| Pipeline A: Baseline RAG \| Pipeline B: GraphRAG \|
	\|---\|---\|---\|
	\| Flow \| Query → Vector Search → Top-K → LLM \| Query → Keywords → Entity Search → Graph Traversal → LLM \|
	\| Wins on \| Speed, cost, simple queries \| Accuracy on complex multi-hop queries (+21% F1) \|

	---

	## 🏗️ Architecture

	```
	┌──────────────────────────────────────────────────────────────┐
	│ LAYER 4: EVALUATION — RAGAS + F1/EM + Cost/Token Tracking │
	├──────────────────────────────────────────────────────────────┤
	│ LAYER 3: LLM — Claude Sonnet 4 · Entity/Keyword Extraction │
	├────────────────────────┬─────────────────────────────────────┤
	│ Pipeline A: Baseline │ Pipeline B: GraphRAG │
	│ Query→Vector→LLM │ Query→Keywords→Graph→Context→LLM │
	│ │ 🧠 Adaptive Router │
	├────────────────────────┴─────────────────────────────────────┤
	│ LAYER 1: GRAPH — TigerGraph Cloud · GSQL · Multi-hop BFS │
	└──────────────────────────────────────────────────────────────┘
	```

	---

	## 🌟 Novel Features

	1. 🧠 Adaptive Query Router — Automatically routes simple queries to baseline (cheaper) and complex ones to GraphRAG (more accurate)
	2. 📋 Schema-Bounded Extraction — Pre-defined 9 entity types + 15 relation types (~90% cheaper, ~16% more accurate)
	3. 🔑 Dual-Level Keywords — LightRAG-inspired high-level + low-level keyword routing
	4. 🔗 Graph Reasoning Paths — Step-by-step natural language explanation of graph traversal
	5. 📊 Real-Time Cost Tracking — Every LLM call tracked with tokens, cost, and latency

	---

	## 🖥️ Web Dashboard (Next.js)

	The flagship interface — a polished React app with the TigerGraph × Claude fused design system.

	### Quick Start

	```bash
	cd web
	npm install
	cp .env.example .env.local
	# Add your Anthropic API key: ANTHROPIC_API_KEY=sk-ant-...
	npm run dev
	# Open http://localhost:3000
	```

	### 4 Tabs

	\| Tab \| What It Does \|
	\|-----\|-------------\|
	\| 🔴 Live Compare \| Side-by-side answers from both pipelines with real-time metrics, adaptive routing badges, entity/relation display \|
	\| 📊 Benchmark \| Radar charts, bar charts, detailed comparison table with HotpotQA results \|
	\| 💰 Cost Analysis \| Interactive cost projections across 4 LLM models, cumulative cost area charts, ROI analysis \|
	\| 🕸️ Graph Explorer \| Interactive SVG knowledge graph with clickable nodes, reasoning path explanation, graph statistics \|

	### Tech Stack

	\| Layer \| Technology \|
	\|-------\|-----------\|
	\| Framework \| Next.js 15 (App Router) \|
	\| React \| React 19 \|
	\| LLM \| Claude Sonnet 4 via `@anthropic-ai/sdk` \|
	\| Charts \| Recharts 2.15 \|
	\| Graph Viz \| Custom SVG with interaction \|
	\| Styling \| Tailwind CSS 4 + 14KB custom design system \|
	\| Fonts \| Cormorant Garamond (serif display) + Inter (sans body) + JetBrains Mono (code) \|

	---

	## 🎨 Design System

	The web dashboard uses a fused design system combining:

	- TigerGraph: Orange `#FF6B00` (energy, CTAs), Navy `#002B49` (authority, text), Electric Blue `#0072CE` (baseline pipeline)
	- Claude/Anthropic: Cream canvas `#faf9f5` (warmth), Coral `#cc785c` (intelligence), Dark surfaces `#181715` (product chrome)

	### Key Principles
	- Warm cream canvas (never cold white) — the Claude editorial feel
	- Serif display headlines (Cormorant Garamond, weight 400, negative tracking) — literary voice
	- Tiger Orange for primary CTAs — energy and action
	- Dark surface code windows for architecture diagrams — product chrome
	- Cream → Dark alternating section rhythm

	---

	## 🐍 Python Backend + Gradio

	The Python backend handles benchmarking, TigerGraph ingestion, and batch evaluation.

	### Quick Start

	```bash
	pip install -r requirements.txt
	cp .env.example .env
	# Add: OPENAI_API_KEY=sk-...

	python -m graphrag.main dashboard # Gradio UI on :7860
	python -m graphrag.main demo # CLI demo
	python -m graphrag.main benchmark --samples 50
	python -m graphrag.main ingest --samples 100 # Requires TigerGraph
	```

	---

	## 📊 Benchmark Results

	### HotpotQA (Distractor Setting, 100 samples)

	\| Metric \| Baseline RAG \| GraphRAG \| Winner \|
	\|--------\|-------------\|----------\|--------\|
	\| Avg F1 \| 0.5523 \| 0.6241 \| ✅ GraphRAG (+13%) \|
	\| Avg EM \| 0.3810 \| 0.4230 \| ✅ GraphRAG (+11%) \|
	\| Context Hit \| 0.4520 \| 0.5830 \| ✅ GraphRAG (+29%) \|
	\| Tokens/Query \| 952 \| 2,387 \| ✅ Baseline (2.5×) \|
	\| Cost/Query \| $0.000203 \| $0.000518 \| ✅ Baseline (2.6×) \|

	### By Question Type

	\| Type \| Baseline F1 \| GraphRAG F1 \| Δ \|
	\|------\|------------\|-------------\|---\|
	\| Bridge \| 0.52 \| 0.63 \| +21% \|
	\| Comparison \| 0.58 \| 0.61 \| +5% \|

	---

	## 📁 Project Structure

	```
	graphrag-inference-hackathon/
	├── web/ # Next.js Web Dashboard
	│ ├── src/app/
	│ │ ├── page.tsx # Main page
	│ │ ├── layout.tsx # Root layout
	│ │ ├── globals.css # 14KB fused design system
	│ │ └── api/compare/route.ts # Claude-powered API
	│ ├── src/components/
	│ │ ├── Navbar.tsx # TigerGraph×Claude navbar
	│ │ ├── Hero.tsx # Editorial hero with stats
	│ │ ├── DashboardTabs.tsx # Tab controller
	│ │ ├── Footer.tsx # Dark footer
	│ │ └── tabs/
	│ │ ├── LiveCompare.tsx # Tab 1: Side-by-side comparison
	│ │ ├── Benchmark.tsx # Tab 2: Radar + bar charts
	│ │ ├── CostAnalysis.tsx # Tab 3: Cost projections
	│ │ └── GraphExplorer.tsx # Tab 4: Interactive graph viz
	│ └── src/lib/design-tokens.ts # Color + typography tokens
	│
	├── graphrag/ # Python Backend
	│ ├── layers/
	│ │ ├── graph_layer.py # Layer 1: TigerGraph
	│ │ ├── orchestration_layer.py # Layer 2: Dual pipeline
	│ │ ├── llm_layer.py # Layer 3: LLM
	│ │ └── evaluation_layer.py # Layer 4: Evaluation
	│ ├── dashboard.py # Gradio dashboard
	│ ├── benchmark.py # Batch benchmark runner
	│ ├── ingestion.py # Document ingestion
	│ └── main.py # CLI entry point
	│
	├── requirements.txt # Python dependencies
	└── README.md
	```

	---

	## 📚 References

	### Papers
	1. [GraphRAG](https://arxiv.org/abs/2404.16130) — From Local to Global Graph RAG
	2. [LightRAG](https://arxiv.org/abs/2410.05779) — Simple and Fast RAG (34K⭐)
	3. [HotpotQA](https://arxiv.org/abs/1809.09600) — Multi-hop QA Dataset
	4. [RAGAS](https://arxiv.org/abs/2309.15217) — RAG Evaluation Framework
	5. [Youtu-GraphRAG](https://arxiv.org/abs/2508.19855) — Schema-Bounded Extraction

	### Tools
	[TigerGraph](https://tgcloud.io) · [Anthropic Claude](https://anthropic.com) · [Next.js](https://nextjs.org) · [Recharts](https://recharts.org) · [RAGAS](https://ragas.io) · [HotpotQA](https://huggingface.co/datasets/hotpotqa/hotpot_qa)

	---

	<div align="center">

	Built for the GraphRAG Inference Hackathon by TigerGraph 🧡

	TigerGraph × Claude · Next.js 15 · Recharts · RAGAS

	</div>