Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

refactor(templates): 简化字段类型定义并优化模板指南

yifanfeng97f8411dbb414e
diff --git a/README.md b/README.md
index 737301b..8b2b908 100644
--- a/README.md
+++ b/README.md
@@ -1,159 +1,110 @@
-# Hyper-Extract 🖥️
+# 🔍 Hyper-Extract
-[中文版](./README_ZH.md) · [English Version](#)
+> **"Stop reading. Start understanding."**
+>
+> *"告别文档焦虑,让信息一目了然"*
----
-
-## The CLI-First Knowledge Extraction Engine
-
-> Transform any document into **searchable, queryable, reasoning-enabled** structured knowledge — with just one command.
-
-**8 Knowledge Types** · **5 Extraction Methods** · **200+ Domain Templates** · **Bilingual**
-
-
-<!-- Architecture Diagram -->
-![Architecture](docs/assets/fw.png)
-
----
-
-## ⚡ One-Line Knowledge Extraction
+Transform unstructured documents into **searchable, visual, structured knowledge** — with just one command.
-![CLI Welcome Screen](./docs/assets/cli.png)
-
-```bash
-# Install
-uv pip install hyperextract
-
-# Extract → Build → Query (one line at a time)
-he parse report.md -o kb -t graph -l zh # Extract knowledge
-he talk kb -i # Interactive Q&A
-he search kb "revenue growth reasons" # Semantic search
-he show kb # Visualize
-```
-
-### 💻 CLI Commands
+[📖 English Version](#) · [中文版](./README_ZH.md)
---
-## "Chat solved. What's next is Structured Knowledge."
+## ✨ Features
-Transform LLM output from scattered text into **searchable, queryable, and reasoning-enabled** structured knowledge.
+| Feature | Description |
+|---------|-------------|
+| ⚡ **CLI-First** | One command to extract knowledge from any document |
+| 🎯 **8 Structures** | Knowledge Graph, Timeline, Spatial, Hypergraph... |
+| 👁️ **Visual** | Interactive visualization with OntoSight |
+| 🔍 **Searchable** | Semantic search across all your knowledge |
+| 🌐 **Bilingual** | Full support for English and Chinese |
+| 📦 **200+ Templates** | Ready-to-use domain-specific templates |
---
## ❌ Before | ✅ After
-<!-- Concept Diagram -->
-![Concept](./docs/assets/concept.png)
-
| Before | After |
-| :--- | :--- |
-| LLM outputs a wall of text | Structured knowledge (8 types) |
-| ❌ Need Python to use | ✅ CLI-first (`he` command) |
-| ❌ Only simple graph | ✅ Graph/Temporal/Spatial/Hypergraph... |
-| ❌ Answer disappears | ✅ Persistent storage |
-| ❌ Can't search precisely | ✅ Semantic search |
-| ❌ Can't trace source | ✅ Traceable provenance |
-| ❌ One language only | ✅ Bilingual (zh/en) |
-| ❌ Fragmented, can't reuse | ✅ Knowledge accumulates |
-
----
-
-## 🧩 8 Knowledge Structures (Not Just Simple Graphs)
-
-> Unlike other tools that only support basic graphs, Hyper-Extract handles **complex, multi-dimensional knowledge structures**.
+|--------|-------|
+| Walls of text | **Clear visual structure** |
+| ❌ Hours of reading | ✅ **Instant clarity** |
+| ❌ Hard to find key info | ✅ **Semantic search** |
+| ❌ Can't compare docs | ✅ **Structured comparison** |
+| ❌ Scattered insights | ✅ **Knowledge accumulation** |
-<!-- AutoTypes Diagram -->
-![AutoTypes](./docs/assets/autotypes.png)
-
-| Type | Icon | What it does |
-| :--- | :---: | :--- |
-| **AutoModel** | 📋 | Extract into a complete data model |
-| **AutoList** | 📝 | Extract as a list (keywords, items) |
-| **AutoSet** | 📦 | Extract and deduplicate (entity registry) |
-| **AutoGraph** | 🔗 | Extract as a knowledge graph (relations) |
-| **AutoTemporalGraph** | ⏱️ | Extract as timeline (events over time) |
-| **AutoSpatialGraph** | 📍 | Extract as spatial graph (locations) |
-| **AutoSpatioTemporalGraph** | 🌏 | Extract as spatiotemporal graph (time + space) |
-| **AutoHypergraph** | 🌐 | Extract as hypergraph (multi-party relations) |
+![Before/After Demo](docs/assets/before-after-demo.jpeg)
---
-## 🔬 Extraction Methods Comparison
+## ⚡ Quick Start
-> Hyper-Extract implements **multiple** extraction methods, not just one.
+### Installation
-| Method | Type | Graph | Temporal | Spatial | Spatiotemporal | Hypergraph |
-| :--- | :--- | :---: | :---: | :---: | :---: | :---: |
-| **KG-Gen** | Graph | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **ATOM** | Atomic | ✅ | ✅ | ❌ | ❌ | ❌ |
-| **Graphiti** | Temporal | ❌ | ✅ | ❌ | ❌ | ❌ |
-| **LightRAG** | Graph | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **Hyper-RAG** | Hypergraph | ❌ | ❌ | ❌ | ❌ | ✅ |
-| **Hyper-Extract** | **All-in-One** | ✅ | ✅ | ✅ | ✅ | ✅ |
+```bash
+pip install hyper-extract
+```
-**Choose the method that fits your need, or let AutoTypes auto-select.**
+### Usage
----
+```bash
+# Extract structure from document
+he parse document.pdf -o kb
-## 🌍 6 Domains, 40+ Ready-to-Use Templates
+# Visualize the knowledge
+he show kb
-> Pre-built templates for **different industries** — extract knowledge **right away** without designing schemas.
+# Semantic search
+he search kb "key insights"
-| Domain | Templates | Domain | Templates |
-| :--- | :---: | :--- | :---: |
-| 📚 General | 16 | 💰 Finance | 21 |
-| 🏥 Medicine | 15 | 🌿 TCM | 10 |
-| ⚖️ Legal | 11 | 🔧 Industry | 15 |
+# Interactive Q&A
+he talk kb -i
+```
-**✅ Bilingual** — Templates available in both English and Chinese
+![CLI Welcome Screen](docs/assets/cli.png)
---
-## 🚀 Quick Start
-
-### Option 1: CLI (Recommended) ⚡
-
-```bash
-# Extract knowledge from document
-he parse document.pdf -o my_kb -t knowledge_graph -l zh
-
-# Chat with your knowledge
-he talk my_kb -i
+## 🧩 8 Knowledge Structures
-# Search semantically
-he search my_kb "公司营收增长原因"
+**8 different structures** for different needs:
-# Visualize knowledge graph
-he show my_kb
-```
+| Type | Icon | Best For | Example |
+|------|------|----------|---------|
+| **AutoModel** | 📋 | Structured reports | Financial statements |
+| **AutoList** | 📝 | Key points | Meeting notes |
+| **AutoSet** | 📦 | Entity registry | Product catalog |
+| **AutoGraph** | 🔗 | Relations | Social networks |
+| **AutoTemporalGraph** | ⏱️ | Event sequences | News timeline |
+| **AutoSpatialGraph** | 📍 | Locations | Delivery routes |
+| **AutoSpatioTemporalGraph** | 🌏 | Time + Space | Historical events |
+| **AutoHypergraph** | 🌐 | Complex relations | Legal cases |
-### Option 2: Python API
+![AutoTypes Demo](docs/assets/autotypes-demo.jpeg)
-```python
-from hyperextract.utils.template_engine import Gallery, TemplateFactory
-from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+---
-llm = ChatOpenAI(model="gpt-4o-mini")
-embedder = OpenAIEmbeddings()
+## 🎯 Use Cases
-config = Gallery.get("ResearchNoteSummary")
-template = TemplateFactory.create(config, llm, embedder)
-result = template.parse("Apple Q3 revenue reached $94.9 billion...")
+| Domain | What You Get | Example |
+|--------|--------------|---------|
+| 📊 **Finance** | Extract insights from earnings reports | `he parse report.pdf -o kb -l en` |
+| ⚖️ **Legal** | Structure contracts, case laws | `he parse contract.pdf -o kb -t hypergraph` |
+| 🏥 **Medical** | Organize patient histories | `he parse records.pdf -o kb` |
+| 📚 **Research** | Extract key findings from papers | `he parse paper.pdf -o kb` |
+| 📋 **Meetings** | Transform notes into timelines | `he parse notes.md -o kb` |
-answer = template.chat("What drove the revenue growth?")
-print(answer.content)
-```
+![Use Cases Demo](docs/assets/use-cases-demo.jpeg)
---
## 🔧 Architecture
<details>
-<summary><strong>Technical Details</strong></summary>
+<summary><strong>Technical Details (Click to Expand)</strong></summary>
```
-hyperextract/
+hyper-extract/
├── cli/ # 💻 CLI Interface (he command)
│ ├── commands/ # parse, talk, search, show...
│ └── __main__.py # Entry point
@@ -166,17 +117,28 @@ hyperextract/
│ ├── hypergraph.py # AutoHypergraph
│ ├── temporal_graph.py # AutoTemporalGraph
│ ├── spatial_graph.py # AutoSpatialGraph
-│ └── spatio_temporal_graph.py # AutoSpatioTemporalGraph
+│ └── spatio_temporal_graph.py
│
├── methods/ # 🔬 Extraction Engines
│ ├── rag/ # LightRAG, HyperRAG, CogRAG
-│ └── typical/ # KG-Gen, ATOM (reproduced)
+│ └── typical/ # KG-Gen, ATOM
│
└── templates/ # 🌍 200+ Domain Templates
- ├── zh/ # Chinese templates (25+ domains)
+ ├── zh/ # Chinese templates
└── en/ # English templates
```
+### Supported Methods
+
+| Method | Graph | Temporal | Spatial | Hypergraph |
+|--------|-------|----------|---------|------------|
+| KG-Gen | ✅ | ❌ | ❌ | ❌ |
+| ATOM | ✅ | ✅ | ❌ | ❌ |
+| Graphiti | ❌ | ✅ | ❌ | ❌ |
+| LightRAG | ✅ | ❌ | ❌ | ❌ |
+| Hyper-RAG | ❌ | ❌ | ❌ | ✅ |
+| **Hyper-Extract** | ✅ | ✅ | ✅ | ✅ |
+
</details>
---
@@ -189,14 +151,10 @@ hyperextract/
---
-## 🤝 Contributing
+## 🤝 Contributing & Support
Welcome! Please feel free to submit issues and pull requests.
----
-
-## ⭐ Support
-
If you find this project helpful, please give us a ⭐ to show your support!
---
diff --git a/README_ZH.md b/README_ZH.md
index d7648dd..137326f 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -1,162 +1,113 @@
-# Hyper-Extract 🖥️
+# 🔍 Hyper-Extract
-[English Version](./README.md) · [中文版](#)
-
----
-
-## 首个 CLI 优先的知识提取引擎
-
-> 只需一行命令,将任何文档转化为**可搜索、可查询、可推理**的结构化知识。
-
-**8 种知识结构** · **5 种提取方法** · **200+ 领域模板** · **中英文支持**
+> **"告别文档焦虑,让信息一目了然"**
+>
+> *"Stop reading. Start understanding."*
+将非结构化文档转化为**可搜索、可视化、结构化**的知识 —— 一行命令即可。
-<!-- 架构图 -->
-![架构图](docs/assets/fw.png)
+[📖 English Version](./README.md) · [中文版](#)
---
-## ⚡ 一行命令提取知识
+## ✨ 核心特性
-![CLI 欢迎界面](./docs/assets/cli.png)
-
-```bash
-# 安装
-uv pip install hyperextract
-
-# 提取 → 构建 → 问答 (逐行执行)
-he parse report.md -o kb -t graph -l zh # 提取知识
-he talk kb -i # 交互式问答
-he search kb "营收增长原因" # 语义搜索
-he show kb # 可视化
-```
-
-### 💻 CLI 命令
-
----
-
-## "Chat 已解决,下一步是 结构化知识"
-
-将 LLM 输出的文本转化为**可搜索、可查询、可推理**的结构化知识。
+| 特性 | 说明 |
+|------|------|
+| ⚡ **CLI 优先** | 一条命令提取任何文档的知识 |
+| 🎯 **8 种结构** | 知识图谱、时间线、空间图、超图... |
+| 👁️ **可视化** | 使用 OntoSight 进行交互式可视化 |
+| 🔍 **可搜索** | 语义搜索所有知识 |
+| 🌐 **双语支持** | 完整支持中文和英文 |
+| 📦 **200+ 模板** | 开箱即用的领域模板 |
---
## ❌ 以前 | ✅ 现在
-<!-- 概念图 -->
-![概念图](./docs/assets/concept.png)
-
| 以前 | 现在 |
-| :--- | :--- |
-| LLM 输出一堆文本 | 结构化知识(8种类型) |
-| ❌ 需要写 Python 代码 | ✅ CLI 优先(`he` 命令) |
-| ❌ 只支持简单图谱 | ✅ 图谱/时序/空间/超图... |
-| ❌ 回答完就消失 | ✅ 可持久化存储 |
-| ❌ 无法精准检索 | ✅ 语义搜索 |
-| ❌ 难以追溯源头 | ✅ 可追溯来源 |
-| ❌ 只有一种语言 | ✅ 中英文双语支持 |
-| ❌ 碎片化无法复用 | ✅ 知识沉淀复用 |
-
----
-
-## 🧩 8 种知识结构(不只是简单图谱)
-
-> 与其他只支持基础图谱的工具不同,Hyper-Extract 支持**复杂、多维的知识结构**。
-
-<!-- AutoTypes 图 -->
-![AutoTypes](./docs/assets/autotypes.png)
+|------|------|
+| 密密麻麻的文字 | **清晰的结构** |
+| ❌ 花几小时阅读 | ✅ **即时清晰** |
+| ❌ 找不到关键信息 | ✅ **语义搜索** |
+| ❌ 无法对比文档 | ✅ **结构化对比** |
+| ❌ 洞察碎片化 | ✅ **知识沉淀** |
-| 类型 | 图标 | 功能 |
-| :--- | :---: | :--- |
-| **AutoModel** | 📋 | 提取为完整的数据模型 |
-| **AutoList** | 📝 | 提取为列表 |
-| **AutoSet** | 📦 | 提取并去重 |
-| **AutoGraph** | 🔗 | 提取为知识图谱 |
-| **AutoTemporalGraph** | ⏱️ | 提取为时序图(时间线) |
-| **AutoSpatialGraph** | 📍 | 提取为空间图(地理位置) |
-| **AutoSpatioTemporalGraph** | 🌏 | 提取为时空图(时间+空间) |
-| **AutoHypergraph** | 🌐 | 提取为超图(多方关系) |
+![Before/After 演示](docs/assets/before-after-demo.jpeg)
---
-## 🔬 提取方法对比
+## ⚡ 快速开始
-> Hyper-Extract 实现了**多种**提取方法,而非只有一种。
+### 安装
-| 方法 | 类型 | 图谱 | 时序 | 空间 | 时空 | 超图 |
-| :--- | :--- | :---: | :---: | :---: | :---: | :---: |
-| **KG-Gen** | 图谱 | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **ATOM** | 原子 | ✅ | ✅ | ❌ | ❌ | ❌ |
-| **Graphiti** | 时序 | ❌ | ✅ | ❌ | ❌ | ❌ |
-| **LightRAG** | 图谱 | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **Hyper-RAG** | 超图 | ❌ | ❌ | ❌ | ❌ | ✅ |
-| **Hyper-Extract** | **全能型** | ✅ | ✅ | ✅ | ✅ | ✅ |
+```bash
+pip install hyper-extract
+```
-**选择适合你需求的方法,或让 AutoTypes 自动选择。**
+### 使用
----
+```bash
+# 从文档提取结构
+he parse document.pdf -o kb
-## 🌍 6 个领域,40+ 开箱即用模板
+# 可视化知识
+he show kb
-> 针对**不同行业**预置的模板 —— 无需设计schema,直接提取知识。
+# 语义搜索
+he search kb "关键信息"
-| 领域 | 模板数 | 领域 | 模板数 |
-| :--- | :---: | :--- | :---: |
-| � 通用 | 16 | � 金融 | 21 |
-| 🏥 医疗 | 15 | 🌿 中医 | 10 |
-| ⚖️ 法律 | 11 | 🔧 工业 | 15 |
+# 交互式问答
+he talk kb -i
+```
-**✅ 双语支持** — 模板同时支持中文和英文
+![CLI 界面](docs/assets/cli.png)
---
-## 🚀 快速开始
+## 🧩 8 种知识结构
-### 方式一:CLI(推荐)⚡
+**8 种不同结构**,满足不同需求:
-```bash
-# 从文档提取知识
-he parse document.pdf -o my_kb -t knowledge_graph -l zh
+| 类型 | 图标 | 适用场景 | 示例 |
+|------|------|----------|------|
+| **AutoModel** | 📋 | 结构化报告 | 财务报表 |
+| **AutoList** | 📝 | 要点提取 | 会议记录 |
+| **AutoSet** | 📦 | 实体注册 | 产品目录 |
+| **AutoGraph** | 🔗 | 关系分析 | 社交网络 |
+| **AutoTemporalGraph** | ⏱️ | 事件序列 | 新闻时间线 |
+| **AutoSpatialGraph** | 📍 | 地理位置 | 配送路线 |
+| **AutoSpatioTemporalGraph** | 🌏 | 时间+空间 | 历史事件 |
+| **AutoHypergraph** | 🌐 | 复杂关系 | 法律案件 |
-# 与知识库问答
-he talk my_kb -i
+![AutoTypes 演示](docs/assets/autotypes-demo.jpeg)
-# 语义搜索
-he search my_kb "公司营收增长原因"
-
-# 可视化知识图谱
-he show my_kb
-```
-
-### 方式二:Python API
+---
-```python
-from hyperextract.utils.template_engine import Gallery, TemplateFactory
-from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+## 🎯 使用场景
-llm = ChatOpenAI(model="gpt-4o-mini")
-embedder = OpenAIEmbeddings()
+| 领域 | 你将获得 | 示例 |
+|------|----------|------|
+| 📊 **财务** | 从财报中提取洞察 | `he parse report.pdf -o kb -l en` |
+| ⚖️ **法律** | 结构化合同、法条 | `he parse contract.pdf -o kb -t hypergraph` |
+| 🏥 **医疗** | 整理病历、治疗方案 | `he parse records.pdf -o kb` |
+| 📚 **研究** | 从论文中提取关键发现 | `he parse paper.pdf -o kb` |
+| 📋 **会议** | 转化为可操作的洞察 | `he parse notes.md -o kb` |
-config = Gallery.get("ResearchNoteSummary")
-template = TemplateFactory.create(config, llm, embedder)
-result = template.parse("苹果Q3营收达到949亿美元...")
-
-answer = template.chat("营收增长的原因是什么?")
-print(answer.content)
-```
+![使用场景演示](docs/assets/use-cases-demo.jpeg)
---
-## 🔧 技术架构
+## 🔧 架构
<details>
-<summary><strong>技术细节</strong></summary>
+<summary><strong>技术细节(点击展开)</strong></summary>
```
-hyperextract/
-├── cli/ # 💻 CLI 接口(he 命令)
+hyper-extract/
+├── cli/ # 💻 CLI 接口 (he 命令)
│ ├── commands/ # parse, talk, search, show...
-│ └── __main__.py # 入口
+│ └── __main__.py # 入口点
│
├── types/ # 🧩 8 种知识结构
│ ├── model.py # AutoModel
@@ -166,17 +117,28 @@ hyperextract/
│ ├── hypergraph.py # AutoHypergraph
│ ├── temporal_graph.py # AutoTemporalGraph
│ ├── spatial_graph.py # AutoSpatialGraph
-│ └── spatio_temporal_graph.py # AutoSpatioTemporalGraph
+│ └── spatio_temporal_graph.py
│
├── methods/ # 🔬 提取引擎
│ ├── rag/ # LightRAG, HyperRAG, CogRAG
-│ └── typical/ # KG-Gen, ATOM(复现)
+│ └── typical/ # KG-Gen, ATOM
│
└── templates/ # 🌍 200+ 领域模板
- ├── zh/ # 中文模板(25+ 领域)
+ ├── zh/ # 中文模板
└── en/ # 英文模板
```
+### 支持的方法
+
+| 方法 | 图谱 | 时序 | 空间 | 超图 |
+|------|------|------|------|------|
+| KG-Gen | ✅ | ❌ | ❌ | ❌ |
+| ATOM | ✅ | ✅ | ❌ | ❌ |
+| Graphiti | ❌ | ✅ | ❌ | ❌ |
+| LightRAG | ✅ | ❌ | ❌ | ❌ |
+| Hyper-RAG | ❌ | ❌ | ❌ | ✅ |
+| **Hyper-Extract** | ✅ | ✅ | ✅ | ✅ |
+
</details>
---
@@ -185,20 +147,16 @@ hyperextract/
- [📖 完整文档](docs/)
- [💻 示例代码](examples/)
-- [🏷️ 模板 Gallery](hyperextract/templates/)
+- [🏷️ 模板库](hyperextract/templates/)
---
-## 🤝 贡献
+## 🤝 贡献与支持
欢迎提交 Issue 和 Pull Request!
----
-
-## ⭐ 支持
-
-如果你觉得这个项目有帮助,请给我们一个 ⭐ 表示支持!
+如果这个项目对你有帮助,请给我们一个 ⭐!
---
-*用 ❤️ 为 AI 社区构建*
+*为 AI 社区而构建 ❤️*
diff --git a/docs/assets/autotypes-demo.jpeg b/docs/assets/autotypes-demo.jpeg
new file mode 100644
index 0000000..6bc3cb1
Binary files /dev/null and b/docs/assets/autotypes-demo.jpeg differ
diff --git a/docs/assets/before-after-demo.jpeg b/docs/assets/before-after-demo.jpeg
new file mode 100644
index 0000000..b0f43c7
Binary files /dev/null and b/docs/assets/before-after-demo.jpeg differ
diff --git a/docs/assets/fw.jpeg b/docs/assets/fw.jpeg
new file mode 100644
index 0000000..80a844d
Binary files /dev/null and b/docs/assets/fw.jpeg differ
diff --git a/docs/assets/use-cases-demo.jpeg b/docs/assets/use-cases-demo.jpeg
new file mode 100644
index 0000000..c58a4f2
Binary files /dev/null and b/docs/assets/use-cases-demo.jpeg differ
diff --git a/examples/method_graph_rag_demo.py b/examples/method_graph_rag_demo.py
index 0527c5f..efa7591 100644
--- a/examples/method_graph_rag_demo.py
+++ b/examples/method_graph_rag_demo.py
@@ -126,7 +126,6 @@ if __name__ == "__main__":
for i, edge in enumerate(rag.edges, 1):
print(f"\n{i}. {edge.source} -> {edge.target}")
print(f" Description: {edge.description}")
- print(f" Keywords: {edge.keywords}")
print(f" Strength: {edge.strength}/10")
print(f"\n✓ Total edges extracted: {len(rag.edges)}\n")
@@ -208,56 +207,98 @@ if __name__ == "__main__":
"Leona目前的状况如何?",
]
- # 1. Global Search Example (Community-Enhanced Search)
+ # 1. Standard Edge Search
print("\n" + "-" * 60)
- print("[1. Community-Enhanced Search] (use_community=True)")
+ print("[1. Standard Node & Edge Search] (use_community=False)")
print("-" * 60)
- for q in queries:
- print(f"\nQuery: {q}")
- print("Response:")
+
+ for i, query in enumerate(queries, 1):
+ print(f"\n【问题 {i}】{query}")
+ print("-" * 60)
+
try:
- nodes, edges, community_context = rag.search(q, use_community=True)
+ # 基础检索模式:按语义向量直接搜索相关的Edges
+ results = rag.search_edges(query, top_k=3)
+
+ if results:
+ for j, result in enumerate(results, 1):
+ # Graph_RAG 从底层直接继承支持了带有 score 评分的结果也可以直接遍历 Edge 对象
+ edge = result[0] if isinstance(result, tuple) else result
+ score = result[1] if isinstance(result, tuple) else 1.0
+
+ print(f"\n {j}. [Score: {score:.3f}]")
+ print(f" Relation: {edge.source} -> {edge.target}")
+ print(f" Description: {edge.description}")
+ print(f" Strength: {edge.strength}/10")
+ else:
+ print(" (No relevant relationships found)")
+ except Exception as e:
+ print(f" Search error: {str(e)}")
+
+
+ # 2. Global Search Example (Community-Enhanced Search)
+ print("\n" + "-" * 60)
+ print("[2. Community-Enhanced Search] (use_community=True)")
+ print("-" * 60)
+ for i, q in enumerate(queries, 1):
+ print(f"\n【问题 {i}】{q}")
+ print("-" * 60)
+ try:
+ # 社区增强检索模式,返回 nodes, edges 和 community_context (返回长度为 3 的 tuple)
+ nodes, edges, community_context = rag.search(q, top_k=3, use_community=True)
if community_context:
- print("Community Summaries:")
+ print(" Community Summaries:")
for summary in community_context.get("summaries", []):
- print(f" - [{summary['title']}] (rating: {summary['rating']})")
- print(f" {summary['summary'][:100]}...")
+ print(f" - [{summary['title']}] (rating: {summary['rating']})")
+ print(f" {summary['summary'][:100]}...")
if nodes:
- print(f"Top nodes: {[n.name for n in nodes[:3]]}")
+ print(f" Top nodes: {[n.name for n in nodes[:3]]}")
if edges:
- print(f"Top edges: {[e.description[:50] for e in edges[:3]]}")
+ print(f" Top edges: {[e.description[:50] for e in edges[:3]]}")
except Exception as e:
- print(f"Error: {e}")
+ print(f" Error: {e}")
- # 2. Local Search Example (Not implemented yet)
- print("\n" + "-" * 60)
- print("[2. Local Search] (Targeted Subgraph + Community Context) - Not Implemented")
- print("-" * 60)
- print("Local search is not yet available. Use chat() for conversational queries.")
+ # ============================================================================
+ # Chat with GraphRAG
+ # ============================================================================
+ print("\n" + "=" * 80)
+ print("💬 Interactive Chat with GraphRAG")
+ print("=" * 80)
+ print("Engaging in multi-turn dialogue based on extracted knowledge...\n")
- # 3. Standard Edge Search
- print("\n" + "-" * 60)
- print("[3. Standard Edge Search] (Vector similarity only)")
- print("-" * 60)
-
- for i, query in enumerate(queries, 1):
- print(f"\nQuery: {query}")
+ for q in queries:
+ print(f"❓ User: {q}")
try:
- results = rag.search_edges(query, top_k=3)
-
- if results:
- for j, result in enumerate(results, 1):
- print(f" [{j}] {result.source} -> {result.target}: {result.description[:100]}...")
- else:
- print(" No relevant edges found.")
+ response = rag.chat(q)
+ print(f"🤖 GraphRAG: {response.content}\n")
except Exception as e:
- print(f" Search failed: {e}")
+ print(f"⚠️ Chat error: {e}\n")
# ============================================================================
# Save Results
# ============================================================================
print("\n" + "=" * 80)
- print("SAVING RESULTS")
+ print("Saving Results...")
print("=" * 80)
-
- rag.dump("temp/graph_rag_demo")
+
+ try:
+ output_dir = "temp/graph_rag_demo"
+ rag.dump(output_dir)
+ print(f"✓ Results saved to {output_dir}/")
+
+ # List saved files
+ saved_files = []
+ if os.path.exists(output_dir):
+ for root, dirs, files in os.walk(output_dir):
+ for file in files:
+ rel_path = os.path.relpath(os.path.join(root, file), output_dir)
+ saved_files.append(rel_path)
+
+ if saved_files:
+ print("\n Saved files:")
+ for f in saved_files:
+ print(f" - {f}")
+ except Exception as e:
+ print(f"⚠️ Warning: Could not save results: {str(e)}")
+
+ print("\n" + "=" * 80 + "\n")
diff --git a/hyperextract-skills/README.md b/hyperextract-skills/README.md
index 9cd5b1d..97b6f23 100644
--- a/hyperextract-skills/README.md
+++ b/hyperextract-skills/README.md
@@ -115,6 +115,11 @@ hyperextract-skills/
└── SKILL.md # Multi-language conversion
```
+## Design Principles
+
+When designing templates, remember: **Schema defines WHAT, Guideline defines HOW TO DO WELL**.
+See `graph-designer/SKILL.md` or `record-designer/SKILL.md` for details.
+
## License
Apache 2.0
diff --git a/hyperextract-skills/graph-designer/SKILL.md b/hyperextract-skills/graph-designer/SKILL.md
index ee4184c..8a382c9 100644
--- a/hyperextract-skills/graph-designer/SKILL.md
+++ b/hyperextract-skills/graph-designer/SKILL.md
@@ -27,6 +27,17 @@ Receive design specs from brainstorm:
6. **Write guideline** (guideline)
7. **Review and output YAML**
+## Critical: Output vs Guideline
+
+**Key Principle**: Schema defines "WHAT", Guideline defines "HOW TO DO WELL". DO NOT repeat schema definitions in guideline.
+
+| Guideline Should Have | Guideline Should NOT Have |
+|-----------------------|-------------------------|
+| Extraction strategy ("extract valuable entities") | Field definitions ("name should be...") |
+| Quality requirements ("maintain naming consistency") | Type descriptions ("type field is...") |
+| Creation conditions ("only when text explicitly states") | Reference requirements ("must reference name field") |
+| Common mistakes to avoid | Schema field descriptions |
+
## Type Confirmation
| Type | relation_members | Additional Config |
@@ -151,6 +162,13 @@ identifiers:
- [ ] source/target reference entities?
- [ ] No ambiguous relations?
+### Guideline (Must Check)
+- [ ] No field definitions repeated from schema?
+- [ ] Extraction strategy defined?
+- [ ] Quality requirements specified (naming consistency)?
+- [ ] Creation conditions clear ("only when text explicitly states")?
+- [ ] Common mistakes warned?
+
### Hypergraph
- [ ] Participant count reasonable?
- [ ] Grouping strategy clear?
diff --git a/hyperextract-skills/record-designer/SKILL.md b/hyperextract-skills/record-designer/SKILL.md
index db6d456..054cb09 100644
--- a/hyperextract-skills/record-designer/SKILL.md
+++ b/hyperextract-skills/record-designer/SKILL.md
@@ -25,6 +25,17 @@ Receive design specs from brainstorm:
5. **Write guideline** (guideline)
6. **Review and output YAML**
+## Critical: Output vs Guideline
+
+**Key Principle**: Schema defines "WHAT", Guideline defines "HOW TO DO WELL". DO NOT repeat schema definitions in guideline.
+
+| Guideline Should Have | Guideline Should NOT Have |
+|-----------------------|-------------------------|
+| Extraction strategy ("extract key information for...") | Field definitions ("field_a is for...") |
+| Quality requirements ("maintain format consistency") | Type descriptions ("type field should be...") |
+| Deduplication rules (for set type) | Required/optional clarifications |
+| Common mistakes to avoid | Default value explanations |
+
## Type Confirmation
| Type | Identifiers | Use Case |
@@ -113,3 +124,10 @@ identifiers:
- [ ] Default values are safe/meaningful?
- [ ] For set: item_id can uniquely identify records?
- [ ] Display label references correct fields?
+
+### Guideline (Must Check)
+- [ ] No field definitions repeated from schema?
+- [ ] Extraction strategy defined?
+- [ ] Quality requirements specified?
+- [ ] Common mistakes warned?
+- [ ] For set: deduplication rules clear?
diff --git a/hyperextract-skills/yaml-validator/references/rules-types.md b/hyperextract-skills/yaml-validator/references/rules-types.md
index 3987978..f1f30ec 100644
--- a/hyperextract-skills/yaml-validator/references/rules-types.md
+++ b/hyperextract-skills/yaml-validator/references/rules-types.md
@@ -34,42 +34,93 @@ output:
## Graph Types
+**Important**: All graph types (graph, hypergraph, temporal_graph, spatial_graph, spatio_temporal_graph) **must** use `entities` and `relations` as keys.
+
```yaml
output:
- entities: # ✓ Exists
+ entities: # ✓ Required for ALL graph types (not nodes)
description: '...'
fields:
- name: name
- - name: category
- relations: # ✓ Exists
+ - name: type
+ relations: # ✓ Required for ALL graph types (not hyperedges)
description: '...'
fields:
- - name: source # ✓ Binary relations
- - name: target # ✓ OR
- - name: participants # ✓ Hypergraph
+ - name: source # ✓ graph: binary relation
+ - name: target # ✓ graph
+ # --- OR ---
+ - name: participants # ✓ hypergraph: multi-entity relation
```
### graph
- Binary relations (source/target)
- identifiers with {source, target}
+- identifiers.relation_members: source, target
### hypergraph
-- Multi-entity relations
-- identifiers.relation_members: string OR list
+- Multi-entity relations (participants)
+- identifiers.relation_members: participants
+- **NOT** `nodes`/`hyperedges`, but `entities`/`relations`
### temporal_graph
- identifiers.time_field required
+- Must also satisfy graph requirements
### spatial_graph
- identifiers.location_field required
+- Must also satisfy graph requirements
### spatio_temporal_graph
- Both time_field and location_field required
+- Must also satisfy graph requirements
+
+---
+
+## Common Validation Errors
+
+### Hypergraph Common Errors
+
+❌ **Wrong Example**:
+```yaml
+output:
+ nodes: # ✗ Wrong: not nodes
+ ...
+ hyperedges: # ✗ Wrong: not hyperedges
+ ...
+guideline:
+ rules_for_nodes: # ✗ Wrong
+ rules_for_hyperedges: # ✗ Wrong
+identifiers:
+ node_id: # ✗ Wrong
+ hyperedge_id: # ✗ Wrong
+display:
+ node_label: # ✗ Wrong
+ hyperedge_label: # ✗ Wrong
+```
+
+✅ **Correct Example**:
+```yaml
+output:
+ entities: # ✓ Correct
+ ...
+ relations: # ✓ Correct
+ ...
+guideline:
+ rules_for_entities: # ✓ Correct
+ rules_for_relations: # ✓ Correct
+identifiers:
+ entity_id: # ✓ Correct
+ relation_id: # ✓ Correct
+ relation_members: participants
+display:
+ entity_label: # ✓ Correct
+ relation_label: # ✓ Correct
+```
---
@@ -77,6 +128,8 @@ output:
| Field | Valid Values | Common Errors |
|-------|-------------|---------------|
-| type | 8 valid types | Typo: "graphh" |
+| output.fields[].type | str, int, float, bool, list | Typo: "bol" |
| language | zh/en or [zh, en] | Non-standard: "chinese" |
| extraction_mode | one_stage, two_stage | Typo: "two-stage" |
+
+**Note**: The top-level `type` field must be one of the 8 AutoTypes: model, list, set, graph, hypergraph, temporal_graph, spatial_graph, spatio_temporal_graph.
diff --git a/hyperextract/methods/rag/graph_rag.py b/hyperextract/methods/rag/graph_rag.py
index 718ad8a..c945ee2 100644
--- a/hyperextract/methods/rag/graph_rag.py
+++ b/hyperextract/methods/rag/graph_rag.py
@@ -10,7 +10,6 @@ from pydantic import BaseModel, Field
from langchain_core.embeddings import Embeddings
from langchain_core.language_models import BaseChatModel
from langchain_core.prompts import ChatPromptTemplate
-from langchain_core.output_parsers import StrOutputParser
from hyperextract.types import AutoGraph
from ontomem.merger import CustomRuleMerger
@@ -62,9 +61,6 @@ class EdgeSchema(BaseModel):
description: str = Field(
description="Detailed explanation of the relationship or event connection"
)
- keywords: str = Field(
- description="Keywords summarizing the relationship (e.g., 'conflict, trade')",
- )
strength: int = Field(
ge=1,
le=10,
@@ -182,8 +178,7 @@ Your task is to merge them into a SINGLE object exactly matching the schema.
Merge strategy:
1. **source/target**: Keep them identical to the inputs.
2. **description**: Synthesize a single, comprehensive description covering the relationship dynamics from all inputs. Write it in the third person.
-3. **keywords**: Combine keyword lists from all inputs, removing duplicates.
-4. **strength**: Calculate the average of the input strengths (round to nearest integer).
+3. **strength**: Calculate the average of the input strengths (round to nearest integer).
"""
# ============================================================================
@@ -269,7 +264,7 @@ class Graph_RAG(AutoGraph[NodeSchema, EdgeSchema]):
edge_strategy_or_merger=edge_merger,
# Optimize indexing
node_fields_for_index=["name", "type", "description"],
- edge_fields_for_index=["keywords", "description"],
+ edge_fields_for_index=["description"],
# Display labels
node_label_extractor=lambda x: x.name,
edge_label_extractor=lambda x: f"{x.description[:5]}...",
@@ -563,8 +558,3 @@ class Graph_RAG(AutoGraph[NodeSchema, EdgeSchema]):
for r in sorted_reports
]
}
-
- # ============================================================================
- # Deprecated: Global Search functionality is now integrated into search(use_community=True)
- # Use kb.search(query, use_community=True) instead
- # ============================================================================
diff --git a/hyperextract/templates/presets/general/base_graph.yaml b/hyperextract/templates/presets/general/base_graph.yaml
index c372ddc..2f3469b 100644
--- a/hyperextract/templates/presets/general/base_graph.yaml
+++ b/hyperextract/templates/presets/general/base_graph.yaml
@@ -67,27 +67,21 @@ guideline:
rules_for_entities:
zh:
- '提取对理解文本事实、结构或逻辑有价值的实体。'
- - 'name 使用原文中最明确、最稳定的称呼;同一实体在全文中保持命名一致。'
- - 'type 需概括实体类别,可使用通用类型标签。'
- - 'description 用 1 句话概括实体的身份或作用;若信息不足可留空。'
+ - '同一实体在全文中保持命名一致。'
+ - '不要提取纯代词、泛称或无独立指代意义的词语。'
en:
- 'Extract entities that are valuable for understanding text facts, structure, or logic.'
- - 'Use the most explicit and stable designation in the source text for names; maintain consistent naming for the same entity.'
- - 'Use type to summarize the entity category using general type labels.'
- - 'Describe the entity in 1 sentence; leave empty if information is insufficient.'
+ - 'Maintain consistent naming for the same entity throughout the text.'
+ - 'Do not extract pure pronouns, generic terms, or phrases without independent referential meaning.'
rules_for_relations:
zh:
- '仅在文本明确表达两个实体之间存在语义联系时创建关系,不要凭常识补充隐含关系。'
- - 'source 和 target 必须直接引用已提取实体的 name,不能新造实体名称。'
- - 'type 使用简洁、方向清晰的关系词。'
- - 'description 简要说明关系依据或上下文;若文本没有额外信息可留空。'
- '避免重复关系;若同一对实体存在多种不同关系,可分别记录。'
+ - '优先使用文本中明确出现的关系词,不要过度抽象化。'
en:
- 'Create relation edges only when the text explicitly expresses a semantic connection between two entities.'
- - 'Source and target must directly reference the name of an extracted entity; do not create new entity names.'
- - 'Use concise relation words with clear direction.'
- - 'Briefly describe the relation basis or context; leave empty if no additional information is available.'
- 'Avoid duplicate relations; if the same pair of entities has multiple different relations, record them separately.'
+ - 'Prefer relation words that explicitly appear in the text; avoid over-abstraction.'
identifiers:
entity_id: name
diff --git a/hyperextract/templates/presets/general/base_hypergraph.yaml b/hyperextract/templates/presets/general/base_hypergraph.yaml
index 3e69db2..02becf9 100644
--- a/hyperextract/templates/presets/general/base_hypergraph.yaml
+++ b/hyperextract/templates/presets/general/base_hypergraph.yaml
@@ -2,7 +2,7 @@ language: [zh, en]
name: base_hypergraph
type: hypergraph
-tags: [general]
+tags: [general, hypergraph]
description:
zh: '通用超图结构知识模板 - 从任意文本中提取超图结构,包含节点(实体、概念、地点等)以及连接多个节点的多元关系超边(事件、会议、合作、冲突等)。'
@@ -12,10 +12,10 @@ output:
description:
zh: '提取出来的超图结构,包含节点和超边。'
en: 'Extracted hypergraph structure containing nodes and hyperedges.'
- nodes:
+ entities:
description:
zh: '文本中可独立识别的节点,如实体、概念、地点等基本语义单元。'
- en: 'Nodes that can be independently identified in the text, such as entities, concepts, locations, or other basic semantic units.'
+ en: 'Entity nodes that can be independently identified in the text, such as entities, concepts, locations, or other basic semantic units.'
fields:
- name: name
type: str
@@ -33,7 +33,7 @@ output:
zh: '对节点身份或作用的简要说明。'
en: 'Brief description of the node identity or role.'
required: false
- hyperedges:
+ relations:
description:
zh: '连接多个节点的多元关系超边,如事件、会议、合作、冲突、交易等。'
en: 'Multi-node relation hyperedges connecting multiple nodes, such as events, meetings, cooperation, conflicts, transactions, etc.'
@@ -64,39 +64,33 @@ guideline:
target:
zh: '你是一位关系抽取专家。请从文本中提取超图结构,包括:1)可独立识别的节点(实体、概念、地点等);2)连接多个节点的多元关系超边(事件、会议、合作等)。'
en: 'You are an expert in relation extraction. Extract hypergraph structure from the text, including: 1) independently identifiable nodes (entities, concepts, locations, etc.); 2) multi-node relation hyperedges (events, meetings, cooperation, etc.).'
- rules_for_nodes:
+ rules_for_entities:
zh:
- '提取文本中可识别的节点,如实体、概念、地点、组织、物品等基本语义单元。'
- - 'name 使用原文中最稳定、最清晰的称呼。'
- - 'type 概括节点的类别,如实体、概念、地点、组织、物品等。'
- - 'description 用 1 句话概括节点身份或作用;若信息不足可留空。'
+ - '同一节点在全文中保持命名一致。'
+ - '不要提取纯代词、泛称或无独立指代意义的词语。'
en:
- 'Extract identifiable nodes from the text, such as entities, concepts, locations, organizations, objects, or other basic semantic units.'
- - 'Use the most stable and clear designation in the source text for names.'
- - 'Use type to summarize the node category, such as entity, concept, location, organization, object, etc.'
- - 'Describe the node in 1 sentence; leave empty if information is insufficient.'
- rules_for_hyperedges:
+ - 'Maintain consistent naming for the same node throughout the text.'
+ - 'Do not extract pure pronouns, generic terms, or phrases without independent referential meaning.'
+ rules_for_relations:
zh:
- '仅在文本明确表达多个节点共同参与某个事件或关系时创建超边。'
- - 'participants 必须全部引用已提取节点的 name。'
- - 'name 用简洁的词语概括该超边的核心内容。'
- - 'type 概括该超边的类型,如事件、会议、合作、冲突、交易、协议等。'
- - 'description 简要说明超边内容或结果;无额外信息时可留空。'
+ - '避免重复超边;若多个节点多次以相同方式共同参与同一事件,应合并为一条记录。'
+ - '优先使用文本中明确出现的词语描述超边内容。'
en:
- 'Create hyperedges only when the text explicitly expresses that multiple nodes jointly participate in an event or relation.'
- - 'All participants must reference the names of extracted nodes.'
- - 'Use concise words for name to summarize the core content of this hyperedge.'
- - 'Use type to characterize the hyperedge type, such as event, meeting, cooperation, conflict, transaction, agreement, etc.'
- - 'Briefly describe the hyperedge content or result; leave empty if no additional information is available.'
+ - 'Avoid duplicate hyperedges; if multiple nodes repeatedly participate in the same event in the same way, merge them into one record.'
+ - 'Prefer words that explicitly appear in the text to describe hyperedge content.'
identifiers:
- node_id: name
- hyperedge_id: '{name}|{type}'
- hyperedge_members: participants
+ entity_id: name
+ relation_id: '{name}|{type}'
+ relation_members: participants
options:
extraction_mode: two_stage
display:
- node_label: '{name} ({type})'
- hyperedge_label: '{name}'
+ entity_label: '{name} ({type})'
+ relation_label: '{name}'
diff --git a/hyperextract/templates/presets/general/base_list.yaml b/hyperextract/templates/presets/general/base_list.yaml
index d2ba068..148914a 100644
--- a/hyperextract/templates/presets/general/base_list.yaml
+++ b/hyperextract/templates/presets/general/base_list.yaml
@@ -32,13 +32,9 @@ guideline:
rules:
zh:
- '提取所有符合要求的列表项,不遗漏。'
- - 'item 直接引用原文或用简洁语言概括。'
- - 'type 用于区分不同类型的项;如无需区分可留空。'
- '去除无意义或重复的列表项。'
en:
- 'Extract all qualifying list items without omission.'
- - 'Quote directly or summarize items concisely.'
- - 'Use type to distinguish different types; leave empty if unnecessary.'
- 'Remove meaningless or duplicate items.'
display:
diff --git a/hyperextract/templates/presets/general/base_model.yaml b/hyperextract/templates/presets/general/base_model.yaml
index d32d500..31d4654 100644
--- a/hyperextract/templates/presets/general/base_model.yaml
+++ b/hyperextract/templates/presets/general/base_model.yaml
@@ -38,14 +38,10 @@ guideline:
rules:
zh:
- '提取文本中核心的、结构化的对象。'
- - 'name 使用原文中最稳定、最清晰的称呼。'
- - 'description 用 1-2 句话概括对象的身份或作用。'
- - 'type 概括对象的类型,如无法确定可留空。'
+ - '优先使用原文中的稳定叫法,避免使用临时描述或简称。'
en:
- 'Extract the core, structured object from the text.'
- - 'Use the most stable and clear designation for name.'
- - 'Describe the object in 1-2 sentences.'
- - 'Categorize the object; leave empty if unclassifiable.'
+ - 'Prefer stable designations from the source text; avoid temporary descriptions or abbreviations.'
display:
label: '{name}'
diff --git a/hyperextract/templates/presets/general/base_set.yaml b/hyperextract/templates/presets/general/base_set.yaml
index 72e8e17..f5a37f8 100644
--- a/hyperextract/templates/presets/general/base_set.yaml
+++ b/hyperextract/templates/presets/general/base_set.yaml
@@ -37,16 +37,12 @@ guideline:
rules:
zh:
- '提取对理解文本内容有意义的实体。'
- - 'name 使用文本中最清晰、最稳定的称呼;同一实体若有简称或别称,应统一为一个名称。'
- - 'type 用于概括实体类型,尽量准确且可复用。'
- - 'description 用 1 句话说明实体是谁、是什么或在文本中的作用;信息不足时可留空。'
+ - '同一实体若有简称或别称,应统一为一个名称。'
- '对同一实体进行去重,不要因表述差异重复输出多条。'
- '不要把纯代词、泛称、临时描述短语或无独立指代意义的词语当作实体。'
en:
- 'Extract entities that are meaningful for understanding the text content.'
- - 'Use the clearest and most stable designation for names; unify names with aliases or nicknames.'
- - 'Use type to summarize the entity category.'
- - 'Describe the entity in 1 sentence; leave empty if information is insufficient.'
+ - 'Unify names with aliases or nicknames for the same entity.'
- 'Deduplicate entities; do not output multiple records for the same entity.'
- 'Do not treat pure pronouns, generic terms, or non-referential phrases as entities.'
diff --git a/hyperextract/templates/presets/general/base_spatial_graph.yaml b/hyperextract/templates/presets/general/base_spatial_graph.yaml
index eb62150..775314c 100644
--- a/hyperextract/templates/presets/general/base_spatial_graph.yaml
+++ b/hyperextract/templates/presets/general/base_spatial_graph.yaml
@@ -73,39 +73,25 @@ guideline:
rules_for_entities:
zh:
- '提取对理解文本事实有价值,且能够参与关系连接的实体。'
- - 'name 使用原文中最稳定、最清晰的称呼;同一实体在全文中保持命名一致。'
- - 'type 需概括实体类别。'
- - 'description 用 1 句话概括实体身份或作用;若信息不足可留空。'
+ - '同一实体在全文中保持命名一致。'
en:
- 'Extract entities that are valuable for understanding text facts, and that can participate in relation connections.'
- - 'Use the most stable and clear designation in the source text for names; maintain consistent naming for the same entity.'
- - 'Use type to summarize the entity category.'
- - 'Describe the entity in 1 sentence; leave empty if information is insufficient.'
+ - 'Maintain consistent naming for the same entity throughout the text.'
rules_for_relations:
zh:
- '仅在文本明确表达两个实体之间存在关系时创建关系边。'
- - 'source 和 target 必须直接引用已提取实体的 name。'
- - 'relation_type 使用简洁关系词概括。'
- - 'location 是可选字段;没有明确位置时也要保留关系边,并将 location 留空。'
- - 'description 简要说明关系依据或上下文;无额外信息时可留空。'
en:
- 'Create relation edges only when the text explicitly expresses a relationship between two entities.'
- - 'Source and target must directly reference the name of an extracted entity.'
- - 'Use concise relational words for relation_type.'
- - 'location is optional; retain the relation edge even without explicit location, and leave location empty.'
- - 'Briefly describe the relation basis or context; leave empty if no additional information is available.'
rules_for_location:
zh:
- '当前观察位置:{observation_location}'
- 'location 是可选字段;仅在文本明确提供位置,或可依据相对位置可靠确定时填写。'
- - '没有明确位置时,仍应保留关系边,并将 location 留空。'
- '优先使用文本中的原始位置表达;可接受地名、地址、区域等。'
- '若关系涉及空间转移或分布,可在 location 中标注起点和终点。'
- '无法可靠确定位置时留空,不要根据常识补写。'
en:
- 'Current observation location: {observation_location}'
- 'location is optional; fill in only when the text explicitly provides location or when relative location can be reliably determined.'
- - 'Retain the relation edge even without explicit location, and leave location empty.'
- 'Prefer to use the original location expression from the text; place names, addresses, and regions are acceptable.'
- 'If the relation involves spatial transfer or distribution, indicate the start and end points in location.'
- 'Leave empty when location cannot be reliably determined.'
diff --git a/hyperextract/templates/presets/general/base_spatio_temporal_graph.yaml b/hyperextract/templates/presets/general/base_spatio_temporal_graph.yaml
index c0de810..7b960b8 100644
--- a/hyperextract/templates/presets/general/base_spatio_temporal_graph.yaml
+++ b/hyperextract/templates/presets/general/base_spatio_temporal_graph.yaml
@@ -79,29 +79,15 @@ guideline:
rules_for_entities:
zh:
- '提取对理解文本事实有价值,且能够参与关系连接的实体。'
- - 'name 使用原文中最稳定、最清晰的称呼;同一实体在全文中保持命名一致。'
- - 'type 需概括实体类别。'
- - 'description 用 1 句话概括实体身份或作用;若信息不足可留空。'
+ - '同一实体在全文中保持命名一致。'
en:
- 'Extract entities that are valuable for understanding text facts, and that can participate in relation connections.'
- - 'Use the most stable and clear designation in the source text for names; maintain consistent naming for the same entity.'
- - 'Use type to summarize the entity category.'
- - 'Describe the entity in 1 sentence; leave empty if information is insufficient.'
+ - 'Maintain consistent naming for the same entity throughout the text.'
rules_for_relations:
zh:
- '仅在文本明确表达两个实体之间存在关系时创建关系边。'
- - 'source 和 target 必须直接引用已提取实体的 name。'
- - 'event_type 使用简洁关系词概括。'
- - 'event_date 是可选字段;没有明确时间时也要保留关系边,并将 event_date 留空。'
- - 'location 是可选字段;没有明确位置时也要保留关系边,并将 location 留空。'
- - 'description 简要说明关系依据或上下文;无额外信息时可留空。'
en:
- 'Create relation edges only when the text explicitly expresses a relationship between two entities.'
- - 'Source and target must directly reference the name of an extracted entity.'
- - 'Use concise relational words for event_type.'
- - 'event_date is optional; retain the relation edge even without explicit time, and leave event_date empty.'
- - 'location is optional; retain the relation edge even without explicit location, and leave location empty.'
- - 'Briefly describe the relation basis or context; leave empty if no additional information is available.'
rules_for_time:
zh:
- '当前观察日期:{observation_time}'
diff --git a/hyperextract/templates/presets/general/base_temporal_graph.yaml b/hyperextract/templates/presets/general/base_temporal_graph.yaml
index 3c066db..b47dbd2 100644
--- a/hyperextract/templates/presets/general/base_temporal_graph.yaml
+++ b/hyperextract/templates/presets/general/base_temporal_graph.yaml
@@ -73,32 +73,19 @@ guideline:
rules_for_entities:
zh:
- '提取对理解文本事实、事件过程有价值,且能够参与关系连接的实体。'
- - 'name 使用原文中最稳定、最清晰的称呼;同一实体在全文中保持命名一致。'
- - 'type 需概括实体类别。'
- - 'description 用 1 句话概括实体身份或作用;若信息不足可留空。'
+ - '同一实体在全文中保持命名一致。'
en:
- 'Extract entities that are valuable for understanding text facts and event processes, and that can participate in relation connections.'
- - 'Use the most stable and clear designation in the source text for names; maintain consistent naming for the same entity.'
- - 'Use type to summarize the entity category.'
- - 'Describe the entity in 1 sentence; leave empty if information is insufficient.'
+ - 'Maintain consistent naming for the same entity throughout the text.'
rules_for_relations:
zh:
- '仅在文本明确表达两个实体之间存在关系时创建关系边。'
- - 'source 和 target 必须直接引用已提取实体的 name。'
- - 'event_type 使用简洁关系词概括。'
- - 'event_date 是可选字段;没有明确时间时也要保留关系边,并将 event_date 留空。'
- - 'description 简要说明关系依据或上下文;无额外信息时可留空。'
en:
- 'Create relation edges only when the text explicitly expresses a relationship between two entities.'
- - 'Source and target must directly reference the name of an extracted entity.'
- - 'Use concise relational words for event_type.'
- - 'event_date is optional; retain the relation edge even without explicit time, and leave event_date empty.'
- - 'Briefly describe the relation basis or context; leave empty if no additional information is available.'
rules_for_time:
zh:
- '当前观察日期:{observation_time}'
- 'event_date 是可选字段;仅在文本明确提供时间,或可依据相对时间可靠换算时填写。'
- - '没有明确时间时,仍应保留关系边,并将 event_date 留空。'
- '相对时间以 observation_time 为基准解析,如"去年/今年/明年""昨天/今天/明天""十年前/五年后"。'
- '若文本给出明确年份,则写为 YYYY;若给出完整日期,则写为 YYYY-MM-DD;保留文本可确定的最细粒度。'
- '若时间只对应关系成立、变化或终止中的某一时点,则记录最直接相关的那个时间。'
@@ -106,7 +93,6 @@ guideline:
en:
- 'Current observation date: {observation_time}'
- 'event_date is optional; fill in only when the text explicitly provides time or when relative time can be reliably converted.'
- - 'Retain the relation edge even without explicit time, and leave event_date empty.'
- 'Parse relative time based on observation_time.'
- 'Write years as YYYY; write full dates as YYYY-MM-DD; preserve the finest granularity determinable from the text.'
- 'If time corresponds to only one point among establishment, change, or termination, record the most directly relevant time.'
diff --git a/hyperextract/templates/presets/general/compliance_logic.yaml b/hyperextract/templates/presets/general/compliance_logic.yaml
index 047c6f2..eb66250 100644
--- a/hyperextract/templates/presets/general/compliance_logic.yaml
+++ b/hyperextract/templates/presets/general/compliance_logic.yaml
@@ -35,7 +35,7 @@ output:
description:
zh: '规定类型,用于概括该条规定在规定什么。优先使用:职责分工、行为要求、流程程序、其他。'
- name: participants
- type: list[str]
+ type: list
description:
zh: '构成该条规定基本内容的实体名称列表,必须直接使用已提取节点的 name。只放实体,不要把动作短语放进 participants。'
- name: action
diff --git a/hyperextract/templates/presets/general/concept_hierarchy.yaml b/hyperextract/templates/presets/general/concept_hierarchy.yaml
index 3892f07..5d6e194 100644
--- a/hyperextract/templates/presets/general/concept_hierarchy.yaml
+++ b/hyperextract/templates/presets/general/concept_hierarchy.yaml
@@ -54,17 +54,14 @@ guideline:
zh: '你是一位概念层级抽取专家。请只提取能够组成层级结构的概念,并同时给出这些概念之间明确成立的层次结构组成或实例关系。'
rules_for_entities:
zh:
- - 'name 必须使用原文中的完整稳定名称;不要把“推理/预测”缩写成“推理”这类更短名字。'
- - 'category 表明专业所属类别,需要通过文中内容归纳并结合你的常识进行判断;如果无法归类太过于泛化或不重要可留空。'
- - 'description 用 1 句话简述该概念在当前层级中的含义;若无必要可留空。'
+ - '必须使用原文中的完整稳定名称;不要把"推理/预测"缩写成"推理"这类更短名字。'
+ - '同一概念在全文中保持命名一致。'
+ - '如果某个概念在全文中找不到任何可靠关系,不要为了保留它而强行构造边。'
rules_for_relations:
zh:
- '只在文本明确表达层级结构时建立边。'
- - 'source 和 target 必须逐字对应已提取节点的 name,不能改写、缩写或新造名称。'
- - '组成用于“X 包含 Y 作为部分/模块/组成项”;实例用于“Y 是 X 的具体实例/代表;你还可以使用一些其他的表示层次关系的词语”。'
- - '如果某个节点在全文中找不到任何可靠关系,不要为了保留它而强行构造边。'
- '优先保证图谱连通性和关系准确性,而不是追求节点数量。'
- - '若关系依赖特定限定语、范围或角度,可写入 details;没有则留空。'
+ - '关系词应使用文本中明确出现的层次关系词语(如"包含"、"组成"、"是...的实例"等)。'
identifiers:
entity_id: name
diff --git a/hyperextract/templates/presets/general/entity_registry.yaml b/hyperextract/templates/presets/general/entity_registry.yaml
index 2abb4e4..bbca877 100644
--- a/hyperextract/templates/presets/general/entity_registry.yaml
+++ b/hyperextract/templates/presets/general/entity_registry.yaml
@@ -30,9 +30,7 @@ guideline:
rules:
zh:
- '提取对理解文本内容有意义的实体,如人物、机构、地点、产品、概念、事件、制度等。'
- - 'name 使用文本中最清晰、最稳定的称呼;同一实体若有简称或别称,应统一为一个名称。'
- - 'category 用于概括实体类型,尽量准确且可复用。'
- - 'description 用 1 句话说明实体是谁、是什么或在文本中的作用;信息不足时可留空。'
+ - '同一实体若有简称或别称,应统一为一个名称。'
- '对同一实体进行去重,不要因表述差异重复输出多条。'
- '不要把纯代词、泛称、临时描述短语或无独立指代意义的词语当作实体。'
diff --git a/hyperextract/templates/presets/legal/adjudication_logic.yaml b/hyperextract/templates/presets/legal/adjudication_logic.yaml
index abf010d..684bbdf 100644
--- a/hyperextract/templates/presets/legal/adjudication_logic.yaml
+++ b/hyperextract/templates/presets/legal/adjudication_logic.yaml
@@ -41,7 +41,7 @@ output:
required: true
default: ''
- name: participants
- type: list[str]
+ type: list
description:
zh: '参与要素名称列表,必须使用已提取节点的 name'
required: true
diff --git a/hyperextract/utils/template_engine/parsers/output.py b/hyperextract/utils/template_engine/parsers/output.py
index 677612b..87139fe 100644
--- a/hyperextract/utils/template_engine/parsers/output.py
+++ b/hyperextract/utils/template_engine/parsers/output.py
@@ -14,7 +14,7 @@ TYPE_MAPPING = {
"int": int,
"float": float,
"bool": bool,
- "list[str]": List[str],
+ "list": List[str],
}
diff --git a/hyperextract/utils/template_engine/parsers/schemas/base.py b/hyperextract/utils/template_engine/parsers/schemas/base.py
index c2c04e4..535e670 100644
--- a/hyperextract/utils/template_engine/parsers/schemas/base.py
+++ b/hyperextract/utils/template_engine/parsers/schemas/base.py
@@ -21,7 +21,7 @@ VALID_AUTOTYPES = Literal[
"spatio_temporal_graph",
]
-VALID_FIELD_TYPES = Literal["str", "int", "float", "bool", "list[str]"]
+VALID_FIELD_TYPES = Literal["str", "int", "float", "bool", "list"]
class FieldSchema(BaseModel):