Skip to content

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

chore: clean up empty code change sections in the changes log

yifanfeng9715a958bfa467
diff --git a/.gitignore b/.gitignore
index 96564fe..7818c1c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
temp/
logs/
.trae/
+.github/
# Byte-compiled / optimized / DLL files
__pycache__/
diff --git a/README.md b/README.md
index fe1539a..be6df86 100644
--- a/README.md
+++ b/README.md
@@ -6,108 +6,100 @@
Transform documents into **knowledge abstracts** — with just one command.
-![Hero](docs/assets/hero-v2.jpg)
+<p align="center">
+ <img alt="Python Version" src="https://img.shields.io/badge/python-3.9%2B-blue">
+ <img alt="License" src="https://img.shields.io/badge/license-Apache%202.0-blue">
+ <img alt="Status" src="https://img.shields.io/badge/status-active-success">
+</p>
[📖 English Version](./README.md) · [中文版](./README_ZH.md)
---
-## ✨ Features
+## 🚀 What is Hyper-Extract?
-- 🔷 **Knowledge Structures** — Model, List, Set, Graph, Hypergraph, TemporalGraph, SpatialGraph, SpatioTemporalGraph
-- 💻 **Interactive CLI** — Extract, build, and interact with knowledge abstracts
-- ⚡ **Incremental Updates** — Continuously update knowledge abstracts with new questions
+Hyper-Extract is an intelligent, LLM-powered knowledge extraction and evolution framework. It radically simplifies transforming highly unstructured texts into persistent, predictable, and strongly-typed knowledge summaries. It effortlessly extracts information into a wide spectrum of formats—ranging from simple **Collections** (Lists/Sets) and **Pydantic Models**, to complex **Knowledge Graphs**, **Hypergraphs**, and even **Spatio-Temporal Graphs**.
+
+![Hero & Workflow](docs/assets/hero-v2.jpg)
+
+*A seamless pipeline from messy documents to neat structured nodes.*
+
+---
+
+## ✨ Core Features
+
+- 🔷 **8 Auto-Types:** From basic `AutoModel`/`AutoList` to advanced `AutoGraph`, `AutoHypergraph`, and `AutoSpatioTemporalGraph`.
+- 🧠 **10+ Extraction Engines:** Out-of-the-box support for cutting-edge retrieval paradigms like `graph_rag`, `light_rag`, and `cog_rag`.
+- 📝 **Declarative YAML Templates:** Zero-code extraction definition. Includes 80+ presets across 6 domains.
+- 🔄 **Incremental Evolution:** Feed new documents on the fly to continuously map out and expand the extracted knowledge.
---
## ⚡ Quick Start
-### Install with uv
+### 1. Installation
```bash
uv pip install hyper-extract
```
-### CLI Usage
+### 2. The Command Line Way
+
+Extract, search, and manage directly from CLI.
+*(Note: By default, the CLI relies on `gpt-4o-mini` as the foundation model and `text-embedding-3-small` for embeddings to balance performance and speed.)*
```bash
he config init -k YOUR_API_KEY
he parse document.md -o ./output/ -l zh
he search ./output/ "What are the key events?"
he feed ./output/ new_document.md
-he show ./output/
```
-<details>
-<summary>🐍 Python API</summary>
+### 3. The Python API Way
```python
from hyperextract import Template
+# Load a preset YAML template
ka = Template.create("finance/event_timeline")
+
+# Extract and auto-parse the document
result = ka.parse(annual_report_text)
-# result.timeline = [Event("Q1 revenue", "2024-01"), ...]
+# result.timeline yields beautifully parsed list of Event objects!
```
-</details>
-
> 🔗 For detailed CLI usage, see [CLI Guide](./hyperextract/cli/README.md)
---
-## 📖 Knowledge Abstraction
-
-> From simple structured data to complex spatio-temporal graphs — **10+ extraction methods**, covering **6 domains**, with **80+ templates**.
-
-<details>
-<summary>🔧 8 Knowledge Structures</summary>
+## 🧩 Deep Dive: The 8 Auto-Types
-| Type | Best For | Example |
-|------|----------|---------|
-| AutoModel | Structured reports | Financial summaries |
-| AutoList | Ordered lists | Meeting notes |
-| AutoSet | Deduplicated collections | Product catalogs |
-| AutoGraph | Binary relations | Social networks |
-| AutoHypergraph | Multi-party events | Contract disputes |
-| AutoTemporalGraph | Temporal relations | News timelines |
-| AutoSpatialGraph | Spatial relations | Delivery routes |
-| AutoSpatioTemporalGraph | Events in time & space | Historical battles |
+Our framework embraces complexity without making you write boilerplate code.
+4
+![Knowledge Structures Matrix](docs/assets/8-types-v2.jpg)
-</details>
+| Auto-Type | Best For | Real-World Example |
+|-----------|----------|--------------------|
+| **Model** | Structured reports | Financial summaries |
+| **List** | Ordered items | Meeting actions |
+| **Set** | Deduplicated queries | Product catalogs |
+| **Graph** | Binary relationships | Social networks |
+| **Hypergraph** | Multi-party events | Contract disputes |
+| **TemporalGraph** | Time sequencing | News timelines |
+| **SpatialGraph** | Geolocation | Delivery routes |
+| **SpatioTemporalGraph**| Time & Space hybrid | Historical battles |
-<details>
-<summary>🔍 Extraction Methods (10+)</summary>
+---
-| Method | Type | Description |
-|--------|------|-------------|
-| graph_rag | graph | Graph-RAG + community detection |
-| light_rag | graph | Lightweight entity-relation extraction |
-| hyper_rag | hypergraph | Hypergraph for multi-entity relations |
-| cog_rag | graph | Cognitive retrieval augmentation |
-| itext2kg | graph | High-quality triple extraction |
-| kg_gen | graph | Structured knowledge generation |
-| atom | graph | Temporal graph + evidence attribution |
+## 🛠️ Architecture Overview
-</details>
+The system is built on a robust triad: **Auto-Types** (Multi-typed knowledge structures definition), **Templates** (Declarative extraction schema), and **Methods** (The LLM Execution strategy).
-<details>
-<summary>🌍 Domain Templates (6 Domains / 38+ Templates)</summary>
+![Architecture](docs/assets/architecture-v4.png)
-Templates are written in YAML to define extraction targets and output structure.
- **Design Guide**: [Template Design Guide](./hyperextract/templates/DESIGN_GUIDE.md)
- **Preset Templates**: [presets directory](./hyperextract/templates/presets/)
-| Domain | Templates | Typical Scenarios |
-|--------|-----------|-------------------|
-| General | 13 | Workflow, Biography, Concept maps |
-| Finance | 5 | Earnings reports, Risk factors |
-| Medicine | 5 | Clinical records, Drug interactions |
-| TCM | 5 | Formula composition, Meridian flow |
-| Industry | 5 | Equipment topology, Failure analysis |
-| Legal | 5 | Contract clauses, Case citations |
-
-</details>
-
---
## 📈 Comparison with Other Libraries
diff --git a/README_ZH.md b/README_ZH.md
index e1442e0..97fe8f8 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -6,141 +6,132 @@
将文档转化为**知识摘要** —— 一行命令即可。
-![Hero](docs/assets/hero-v2.jpg)
+<p align="center">
+ <img alt="Python版本" src="https://img.shields.io/badge/python-3.9%2B-blue">
+ <img alt="开源协议" src="https://img.shields.io/badge/license-Apache%202.0-blue">
+ <img alt="状态" src="https://img.shields.io/badge/status-active-success">
+</p>
[📖 English Version](./README.md) · [中文版](./README_ZH.md)
---
-## ✨ 核心特性
+## 🚀 什么是 Hyper-Extract?
-- 🔷 **知识结构** — Model, List, Set, Graph, Hypergraph, TemporalGraph, SpatialGraph, SpatioTemporalGraph
-- 💻 **交互式CLI** — 提取、构建、与知识摘要交互
-- ⚡ **增量更新** — 持续使用新问题更新知识摘要
+Hyper-Extract 是一个智能的、由大语言模型(LLM)驱动的知识提取与演进框架。它极大地简化了将杂乱不堪的文本转化为持久化、强类型的知识摘要的过程。无论从基础的**集合(Collection/List)**和**结构化模型(Model)**,还是到高阶复杂的**知识图谱(Knowledge Graph)**、**超图(Hypergraph)**,甚至是**时空图谱(Spatio-Temporal Graph)**,它都能轻松拿捏。
+
+![Hero & Workflow](docs/assets/hero-v2.jpg)
+
+*从混沌杂乱的文档到清晰条理结构化知识节点的无缝管线。*
---
-## ⚡ 快速开始
+## ✨ 核心亮点
-### 使用 uv 安装
+- 🔷 **8大自动数据结构(Auto-Types):** 从基础的 `AutoModel`/`AutoList` 到高阶的 `AutoGraph`, `AutoHypergraph`, 以及 `AutoSpatioTemporalGraph`(时空图)。
+- 🧠 **10+ 前沿提取引擎:** 开箱即用整合了业界顶尖的检索范式,例如 `graph_rag`, `light_rag`, 和 `cog_rag`。
+- 📝 **声明式 YAML 模板:** 零代码定义提取策略。内置覆盖 6 大领域的 80+ 预设模板。
+- 🔄 **知识增量演进:** 支持动态喂入新文档(Feed),让提取的知识图谱自动补全和扩展。
+
+---
+
+## ⚡ 快速上手
+
+### 1. 极速安装
```bash
uv pip install hyper-extract
```
-### CLI 使用
+### 2. CLI 命令行玩法
+
+仅仅几行命令即可完整体验提取、搜索和管理知识库:
+*(注:默认使用 `gpt-4o-mini` 作为基础大模型,`text-embedding-3-small` 作为向量模型,兼顾高性价比与速度)*
```bash
he config init -k YOUR_API_KEY
he parse document.md -o ./output/ -l zh
he search ./output/ "有哪些关键事件?"
he feed ./output/ new_document.md
-he show ./output/
```
-<details>
-<summary>🐍 Python API</summary>
+### 3. Python API 深度集成
```python
from hyperextract import Template
+# 加载内置的 YAML 模板
ka = Template.create("finance/event_timeline")
+
+# 一键解析文档
result = ka.parse(annual_report_text)
-# result.timeline = [Event("Q1营收", "2024-01"), ...]
+# result.timeline 将优雅地输出提取后的 Event 对象列表!
```
-</details>
-
-> 🔗 详细 CLI 使用请查看 [CLI 指南](./hyperextract/cli/README.md)
+> 🔗 想了解完整的命令流,请查阅 [CLI 指南](./hyperextract/cli/README.md)
---
-## 📖 知识摘要
-
-> 从简单结构化到复杂时空图谱 —— **10+ 提取方法**,覆盖 **6 大领域**,共 **38+ 模板**。
-
-<details>
-<summary>🔧 8 种知识结构</summary>
+## 🧩 深入探究:8 种核心知识结构
-| 类型 | 适用场景 | 示例 |
-|------|----------|------|
-| AutoModel | 结构化报告 | 财报摘要 |
-| AutoList | 有序列表 | 会议要点 |
-| AutoSet | 去重集合 | 产品目录 |
-| AutoGraph | 二元关系 | 社交网络 |
-| AutoHypergraph | 多元事件 | 合同纠纷 |
-| AutoTemporalGraph | 时序关系 | 新闻时间线 |
-| AutoSpatialGraph | 空间关系 | 配送路线 |
-| AutoSpatioTemporalGraph | 时空事件 | 历史战役 |
+不需要写繁琐的清洗代码,你的架构需求框架都能支持。
-</details>
+![Knowledge Structures Matrix](docs/assets/8-types-v2.jpg)
+| 自动类型 (Auto-Type) | 最佳应用场景 | 典型案例 |
+|-----------|----------|--------------------|
+| **Model** | 结构化报告提取 | 财务报表摘要 |
+| **List** | 顺序化列表 | 会议待办事项 |
+| **Set** | 去重的集合 | 产品目录梳理 |
+| **Graph** | 二元关系网络 | 社交媒体网络实体 |
+| **Hypergraph** | 多方复杂关系 | 合同纠纷事件提取 |
+| **TemporalGraph** | 时间序列图谱 | 新闻历史时间线 |
+| **SpatialGraph** | 空间地理位置 | 物理设备拓扑图 |
+| **SpatioTemporalGraph**| 时空双维度图谱 | 包含时间地理的战役记录 |
-<details>
-<summary>🔍 提取方法 (10+)</summary>
-
-| 方法 | 类型 | 描述 |
-|------|------|------|
-| graph_rag | graph | Graph-RAG + 社区检测 |
-| light_rag | graph | 轻量级实体关系提取 |
-| hyper_rag | hypergraph | 超图多实体关系 |
-| cog_rag | graph | 认知检索增强 |
-| itext2kg | graph | 高质量三元组提取 |
-| kg_gen | graph | 结构化知识生成 |
-| atom | graph | 时序图谱 + 证据归因 |
-
-</details>
+---
-<details>
-<summary>🌍 领域模板 (6领域 / 80+模板)</summary>
+## 🛠️ 系统架构揭秘
-模板使用 YAML 编写,定义提取目标和输出结构。
-- **编写指南**: [模板设计指南](./hyperextract/templates/DESIGN_GUIDE.md)
-- **预设模板**: [presets 目录](./hyperextract/templates/presets/)
+系统底座基于稳固的铁三角架构:**Auto-Types** (多类型知识结构定义)、**Templates** (声明式提取 Schema)、以及 **Methods** (基于 LLM 的灵活执行策略)。
-| 领域 | 模板数 | 典型场景 |
-|------|--------|----------|
-| General | 13 | 工作流、传记、概念图 |
-| Finance | 5 | 财报分析、风险因子 |
-| Medicine | 5 | 临床记录、药物相互作用 |
-| TCM | 5 | 方剂配伍、经络走向 |
-| Industry | 5 | 设备拓扑、事故分析 |
-| Legal | 5 | 合同条款、判例引用 |
+![Architecture](docs/assets/architecture-v4.png)
-</details>
+- **设计指南**: [模板设计指南](./hyperextract/templates/DESIGN_GUIDE.md)
+- **内置模板**: [预设模板目录](./hyperextract/templates/presets/)
---
-## 📈 与同类项目对比
+## 📈 与其他流行库的对比
| 特性 | GraphRAG | LightRAG | KG-Gen | ATOM | **Hyper-Extract** |
|------|:---:|:---:|:---:|:---:|:---:|
-| 知识图谱 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 知识图谱支持 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 时序图谱 | ✅ | ❌ | ❌ | ✅ | ✅ |
| 空间图谱 | ❌ | ❌ | ❌ | ❌ | ✅ |
-| 超图 | ❌ | ❌ | ❌ | ❌ | ✅ |
-| 领域模板 | ❌ | ❌ | ❌ | ❌ | ✅ |
-| CLI工具 | ❌ | ❌ | ❌ | ❌ | ✅ |
-| 多语言 | 部分 | ❌ | ❌ | ❌ | ✅ |
-| 可视化 | 部分 | ❌ | ❌ | ❌ | ✅ |
+| 超图提取 | ❌ | ❌ | ❌ | ❌ | ✅ |
+| 领域模板驱动 | ❌ | ❌ | ❌ | ❌ | ✅ |
+| 交互式 CLI | ❌ | ❌ | ❌ | ❌ | ✅ |
+| 多语言完美支持 | 部分支持 | ❌ | ❌ | ❌ | ✅ |
+| 命令行可视化 | 部分支持 | ❌ | ❌ | ❌ | ✅ |
---
-## 📚 相关文档
+## 📚 项目参考文档
-| 文档 | 说明 |
+| 文档名称 | 功能说明 |
|------|------|
-| [CLI 指南](./hyperextract/cli/README.md) | 命令行工具完整参考 |
-| [模板库](./hyperextract/templates/) | 38+ 领域模板 |
-| [示例代码](./examples/) | Python API 使用示例 |
-| [完整文档](./docs/) | 架构设计与实现细节 |
+| [CLI 命令行指南](./hyperextract/cli/README.md) | 所有 he 命令的完整参考 |
+| [模板画廊](./hyperextract/templates/) | 38+ 内置垂直领域模板大全 |
+| [示例代码示例](./examples/) | Python API 对接的 demo 实例 |
+| [完整架构文档](./docs/) | 项目完整原理与架构解读 |
---
-## 🤝 贡献
+## 🤝 欢迎贡献参与
-欢迎提交 Issue 和 PR!
+热情欢迎社区成员提交 Issues 和 PRs。让项目变得更好!
-## 📄 许可证
+## 📄 开源协议
Apache-2.0
diff --git a/docs/assets/architecture-v4.jpeg b/docs/assets/architecture-v4.jpeg
new file mode 100644
index 0000000..0f4f650
Binary files /dev/null and b/docs/assets/architecture-v4.jpeg differ
diff --git a/docs/assets/architecture-v4.png b/docs/assets/architecture-v4.png
new file mode 100644
index 0000000..d0a4f18
Binary files /dev/null and b/docs/assets/architecture-v4.png differ
diff --git a/docs/assets/workflow-v3.jpeg b/docs/assets/workflow-v3.jpeg
new file mode 100644
index 0000000..967bbfc
Binary files /dev/null and b/docs/assets/workflow-v3.jpeg differ