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/.gitignoreindex 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.mdindex fe1539a..be6df86 100644--- a/README.md+++ b/README.md@@ -6,108 +6,100 @@Transform documents into **knowledge abstracts** — with just one command.-+<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**.++++*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```bashuv 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.)*```bashhe config init -k YOUR_API_KEYhe parse document.md -o ./output/ -l zhhe 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```pythonfrom hyperextract import Template+# Load a preset YAML templateka = Template.create("finance/event_timeline")++# Extract and auto-parse the documentresult = 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+-</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>+-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 Librariesdiff --git a/README_ZH.md b/README_ZH.mdindex e1442e0..97fe8f8 100644--- a/README_ZH.md+++ b/README_ZH.md@@ -6,141 +6,132 @@将文档转化为**知识摘要** —— 一行命令即可。-+<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)**,它都能轻松拿捏。++++*从混沌杂乱的文档到清晰条理结构化知识节点的无缝管线。*----## ⚡ 快速开始+## ✨ 核心亮点-### 使用 uv 安装+- 🔷 **8大自动数据结构(Auto-Types):** 从基础的 `AutoModel`/`AutoList` 到高阶的 `AutoGraph`, `AutoHypergraph`, 以及 `AutoSpatioTemporalGraph`(时空图)。+- 🧠 **10+ 前沿提取引擎:** 开箱即用整合了业界顶尖的检索范式,例如 `graph_rag`, `light_rag`, 和 `cog_rag`。+- 📝 **声明式 YAML 模板:** 零代码定义提取策略。内置覆盖 6 大领域的 80+ 预设模板。+- 🔄 **知识增量演进:** 支持动态喂入新文档(Feed),让提取的知识图谱自动补全和扩展。++---++## ⚡ 快速上手++### 1. 极速安装```bashuv pip install hyper-extract```-### CLI 使用+### 2. CLI 命令行玩法++仅仅几行命令即可完整体验提取、搜索和管理知识库:+*(注:默认使用 `gpt-4o-mini` 作为基础大模型,`text-embedding-3-small` 作为向量模型,兼顾高性价比与速度)*```bashhe config init -k YOUR_API_KEYhe parse document.md -o ./output/ -l zhhe search ./output/ "有哪些关键事件?"he feed ./output/ new_document.md-he show ./output/```-<details>-<summary>🐍 Python API</summary>+### 3. Python API 深度集成```pythonfrom 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>++| 自动类型 (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 | 合同条款、判例引用 |+-</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.0diff --git a/docs/assets/architecture-v4.jpeg b/docs/assets/architecture-v4.jpegnew file mode 100644index 0000000..0f4f650Binary files /dev/null and b/docs/assets/architecture-v4.jpeg differdiff --git a/docs/assets/architecture-v4.png b/docs/assets/architecture-v4.pngnew file mode 100644index 0000000..d0a4f18Binary files /dev/null and b/docs/assets/architecture-v4.png differdiff --git a/docs/assets/workflow-v3.jpeg b/docs/assets/workflow-v3.jpegnew file mode 100644index 0000000..967bbfcBinary files /dev/null and b/docs/assets/workflow-v3.jpeg differ