Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
feat(docs): 重构文档结构并更新内容
yifanfeng978d4e2818d8a5
diff --git a/examples/.env.example b/.env.examplesimilarity index 100%rename from examples/.env.examplerename to .env.examplediff --git a/README.md b/README.mdindex effea95..3af4e93 100644--- a/README.md+++ b/README.md@@ -17,7 +17,7 @@<br/>-<img src="docs/assets/hero.jpg" alt="Hero & Workflow" width="100%">+<img src="docs/assets/hero.png" alt="Hero & Workflow" width="100%"><br/></div>@@ -51,25 +51,77 @@ Extract, search, and manage directly from CLI.# Configure OpenAI API Keyhe config init -k YOUR_OPENAI_API_KEY-# Extract knowledge (using examples/en/tesla.md as sample input)+# Extract knowledgehe parse examples/en/tesla.md -t general/biography_graph -o ./output/ -l en# Query the knowledge basehe search ./output/ "What are Tesla's major achievements?"+# Visualize the knowledge graph+he show ./output/+# Incrementally supplement knowledge-he feed ./output/ another_tesla_document.md+he feed ./output/ examples/en/tesla_question.md++# Show the updated knowledge graph+he show ./output/```<details>-<summary><b> The Python API Way</b></summary>+<summary><b>🐍 The Python API Way</b></summary><br>+### Installation++```bash+# Clone the repository+git clone https://github.com/yifanfeng97/hyper-extract.git+cd hyper-extract++# Install dependencies+uv sync+```++### Configuration++```bash+# Copy the example env file+cp .env.example .env++# Edit .env with your API key and base URL+# OPENAI_API_KEY=your-api-key+# OPENAI_BASE_URL=https://api.openai.com/v1+```++### Usage+```python+import os+from dotenv import load_dotenv++# Load environment variables from .env file+load_dotenv()+from hyperextract import Template+# Create a templateka = Template.create("general/biography_graph")++# Parse a document+with open("examples/en/tesla.md", "r") as f:+ text = f.read()result = ka.parse(text)++# Visualize the knowledge graph+ka.show(result)++# Incrementally supplement knowledge+with open("examples/en/tesla_question.md", "r") as f:+ new_text = f.read()+ka.feed(result, new_text)++# Show the updated knowledge graph+ka.show(result)```> 🔗 For complete examples, see [examples/en](./examples/en/)@@ -80,7 +132,7 @@ result = ka.parse(text)Our framework embraces complexity without making you write boilerplate code.-!\[Knowledge Structures Matrix]\(docs/assets/autotypes.png null)+### Example: AutoGraph Visualization@@ -90,13 +142,27 @@ Here is the knowledge graph visualization after `AutoGraph` extraction:## 🛠️ Architecture Overview-The system is built on a robust triad: **Auto-Types** (Multi-typed structures), **Methods** (The Execution strategy), and **Templates** (Declarative schema).+Hyper-Extract follows a **three-layer architecture**:++- **Auto-Types** define the data structures for knowledge extraction. With 8 strong-typed structures (AutoModel, AutoList, AutoSet, AutoGraph, AutoHypergraph, AutoTemporalGraph, AutoSpatialGraph, AutoSpatioTemporalGraph), they serve as the output format for all extractions.++- **Methods** provide extraction algorithms built on Auto-Types. This includes Typical methods (KG-Gen, iText2KG, iText2KG*) and RAG-based methods (GraphRAG, LightRAG, Hyper-RAG, HypergraphRAG, Cog-RAG).++- **Templates** offer domain-specific configurations with ready-to-use prompts and data structures. Covering 6 domains (Finance, Legal, Medical, TCM, Industry, General) with 80+ preset templates, users can extract knowledge without dealing with Auto-Types or Methods directly.++Use via **CLI** (`he parse`, `he search`, `he show`...) or **Python API** (`Template.create()`).-### 📋 Template Structure Example+### 📚 Related Documentation++- **Preset Templates**: Browse [80+ ready-to-use templates](./hyperextract/templates/presets/) across 6 domains+- **Design Guide**: Learn how to [create custom templates](./hyperextract/templates/DESIGN_GUIDE.md)++<details>+<summary><b>📋 Template Structure Example (Graph Type)</b></summary>-Here's a complete YAML template example that defines a Knowledge Graph extraction:+Here's a complete YAML template example for **Graph** type extraction (entity-relationship extraction):```yamllanguage: en@@ -115,7 +181,10 @@ output:description: 'Entity name'- name: typetype: str- description: 'Entity type'+ description: 'Entity type: e.g., person, organization, event'+ - name: description+ type: str+ description: 'Entity description'relations:fields:- name: source@@ -126,7 +195,10 @@ output:description: 'Target entity'- name: typetype: str- description: 'Relation type'+ description: 'Relation type: e.g., invention, collaboration, competition'+ - name: description+ type: str+ description: 'Relation description'guideline:target: 'Extract entities and their relationships from the text.'@@ -148,10 +220,7 @@ display:relation_label: '{type}'```-### 📚 Related Documentation--- **Preset Templates**: Browse [80+ ready-to-use templates](./hyperextract/templates/presets/) across 6 domains-- **Design Guide**: Learn how to [create custom templates](./hyperextract/templates/DESIGN_GUIDE.md)+</details>## 📈 Comparison with Other Libraries@@ -162,8 +231,8 @@ display:| Spatial Graph | ❌ | ❌ | ❌ | ❌ | ✅ || Hypergraph | ❌ | ❌ | ❌ | ❌ | ✅ || Domain Templates | ❌ | ❌ | ❌ | ❌ | ✅ |-| CLI Tool | ❌ | ❌ | ❌ | ❌ | ✅ |-| Multi-language | Partial | ❌ | ❌ | ❌ | ✅ |+| CLI Tool | ✅ | ❌ | ❌ | ❌ | ✅ |+| Multi-language | ✅ | ❌ | ❌ | ❌ | ✅ |## 📚 Related Documentationdiff --git a/README_ZH.md b/README_ZH.mdindex 95ba072..2687d14 100644--- a/README_ZH.md+++ b/README_ZH.md@@ -17,7 +17,7 @@<br/>-<img src="docs/assets/hero.jpg" alt="Hero & Workflow" width="100%">+<img src="docs/assets/hero.png" alt="Hero & Workflow" width="100%"><br/></div>@@ -51,25 +51,77 @@ uv pip install hyper-extract# 配置 OpenAI API Keyhe config init -k YOUR_OPENAI_API_KEY-# 提取知识(使用 examples/zh/sushi.md 作为示例输入)+# 提取知识he parse examples/zh/sushi.md -t general/biography_graph -o ./output/ -l zh# 查询知识库he search ./output/ "苏轼有哪些重要的作品?"+# 可视化知识图谱+he show ./output/+# 增量补充知识-he feed ./output/ another_sushi_document.md+he feed ./output/ examples/zh/sushi_question.md++# 展示更新后的知识图谱+he show ./output/```<details><summary><b>🐍 Python API 深度集成</b></summary><br>+### 安装++```bash+# 克隆仓库+git clone https://github.com/yifanfeng97/hyper-extract.git+cd hyper-extract++# 安装依赖+uv sync+```++### 配置++```bash+# 复制示例配置文件+cp .env.example .env++# 编辑 .env 文件,填入你的 API Key 和 Base URL+# OPENAI_API_KEY=your-api-key+# OPENAI_BASE_URL=https://api.openai.com/v1+```++### 使用+```python+import os+from dotenv import load_dotenv++# 从 .env 文件加载环境变量+load_dotenv()+from hyperextract import Template+# 创建模板ka = Template.create("general/biography_graph")++# 解析文档+with open("examples/zh/sushi.md", "r", encoding="utf-8") as f:+ text = f.read()result = ka.parse(text)++# 可视化知识图谱+ka.show(result)++# 增量补充知识+with open("examples/zh/sushi_question.md", "r", encoding="utf-8") as f:+ new_text = f.read()+ka.feed(result, new_text)++# 展示更新后的知识图谱+ka.show(result)```> 🔗 完整示例代码,请参阅 [examples/zh](./examples/zh/)@@ -90,13 +142,27 @@ result = ka.parse(text)## 🛠️ 系统架构-系统底座基于坚实的铁三角架构:**Auto-Types** (提取结构)、**Methods** (执行策略)、以及 **Templates** (声明式配置)。+Hyper-Extract 采用**三层架构**:++- **Auto-Types** 定义了知识提取的数据结构。8 种强类型结构(AutoModel、AutoList、AutoSet、AutoGraph、AutoHypergraph、AutoTemporalGraph、AutoSpatialGraph、AutoSpatioTemporalGraph)作为所有提取的输出格式。++- **Methods** 基于 Auto-Types 提供提取算法。包括典型方法(KG-Gen、iText2KG、iText2KG*)和 RAG 增强方法(GraphRAG、LightRAG、Hyper-RAG、HypergraphRAG、Cog-RAG)。++- **Templates** 提供领域特定的配置,包含开箱即用的 prompt 和数据结构。覆盖 6 大领域(金融、法律、医疗、中医、工业、通用),提供 80+ 预设模板,用户无需了解底层 Auto-Types 和 Methods 即可直接使用。++可通过 **CLI**(`he parse`、`he search`、`he show`...)或 **Python API**(`Template.create()`)使用。-### 📋 模板结构示例+### 📝 相关文档++- **预设模板**: 浏览覆盖 6 大领域的 [80+ 即用型模板](./hyperextract/templates/presets/)+- **设计指南**: 学习如何[创建自定义模板](./hyperextract/templates/DESIGN_GUIDE_ZH.md)++<details>+<summary><b>📋 模板结构示例 (Graph 类型)</b></summary>-以下是一个完整的 YAML 模板示例,定义了知识图谱提取:+以下是一个完整的 YAML 模板示例,用于 **Graph** 类型(实体关系)提取:```yamllanguage: zh@@ -115,7 +181,10 @@ output:description: '实体名称'- name: typetype: str- description: '实体类型'+ description: '实体类型:如人物、组织、事件等'+ - name: description+ type: str+ description: '实体的详细介绍'relations:fields:- name: source@@ -126,7 +195,10 @@ output:description: '目标实体'- name: typetype: str- description: '关系类型'+ description: '关系类型:如发明、合作、竞争等'+ - name: description+ type: str+ description: '关系的详细介绍'guideline:target: '从文本中提取实体及其关系。'@@ -148,12 +220,9 @@ display:relation_label: '{type}'```-### 📚 相关文档--- **预设模板**: 浏览覆盖 6 大领域的 [80+ 即用型模板](./hyperextract/templates/presets/)-- **设计指南**: 学习如何[创建自定义模板](./hyperextract/templates/DESIGN_GUIDE_ZH.md)+</details>-## 📈 与其他流行库的对比+## 📈 与其他相关库的对比| 特性 | GraphRAG | LightRAG | KG-Gen | ATOM | **Hyper-Extract** || ------- | :------: | :------: | :----: | :--: | :---------------: |@@ -162,8 +231,9 @@ display:| 空间图谱 | ❌ | ❌ | ❌ | ❌ | ✅ || 超图提取 | ❌ | ❌ | ❌ | ❌ | ✅ || 领域模板驱动 | ❌ | ❌ | ❌ | ❌ | ✅ |-| 交互式 CLI | ❌ | ❌ | ❌ | ❌ | ✅ |-| 多语言支持 | 部分支持 | ❌ | ❌ | ❌ | ✅ |+| 交互式 CLI | ✅ | ❌ | ❌ | ❌ | ✅ |+| 多语言支持 | ✅ | ❌ | ❌ | ❌ | ✅ |+## 📚 项目参考文档diff --git a/docs/assets/arch.png b/docs/assets/arch.pngindex 754e866..a80cc67 100644Binary files a/docs/assets/arch.png and b/docs/assets/arch.png differdiff --git a/docs/assets/hero.jpg b/docs/assets/hero.jpgdeleted file mode 100644index 80d1f1e..0000000Binary files a/docs/assets/hero.jpg and /dev/null differdiff --git a/docs/assets/hero.png b/docs/assets/hero.pngnew file mode 100644index 0000000..bcdb76fBinary files /dev/null and b/docs/assets/hero.png differdiff --git a/docs/en/guides/cli.md b/docs/en/cli/cli.mdsimilarity index 93%rename from docs/en/guides/cli.mdrename to docs/en/cli/cli.mdindex 6d3af70..5af0cc1 100644--- a/docs/en/guides/cli.md+++ b/docs/en/cli/cli.md@@ -7,7 +7,7 @@ The Hyper-Extract CLI provides a powerful command-line interface for knowledge eThe CLI is included with the main package:```bash-pip install hyper-extract+uv pip install hyper-extract```## Basic Usage@@ -158,6 +158,5 @@ he parse chinese_doc.txt -l zh -o ./output/## Next Steps-- Explore [Python API](python-api.md)-- Browse [Domain Templates](domain-templates/index.md)-- Check [CLI Reference](../reference/cli-reference.md)+- Explore [Python API](../python/python-api.md)+- Browse [Domain Templates](../templates/index.md)diff --git a/docs/en/cli/config.md b/docs/en/cli/config.mdnew file mode 100644index 0000000..092162e--- /dev/null+++ b/docs/en/cli/config.md@@ -0,0 +1,83 @@+# CLI Configuration++## Configuration File++The CLI configuration is stored in `~/.he/config.toml`.++## Initialize Configuration++```bash+# Initialize with API Key (recommended for first-time users)+he config init -k YOUR_OPENAI_API_KEY++# Interactive setup (will prompt for LLM and Embedder settings)+he config init+```++## View Configuration++```bash+# Show current configuration+he config show+```++## Configure LLM++```bash+# Set LLM API key and model+he config llm --api-key YOUR_KEY --model gpt-4o-mini++# Show current LLM configuration+he config llm --show++# Set custom base URL+he config llm --api-key YOUR_KEY --base-url https://api.openai.com/v1++# Clear LLM configuration+he config llm --unset+```++## Configure Embedder++```bash+# Set Embedder API key and model+he config embedder --api-key YOUR_KEY --model text-embedding-3-small++# Show current Embedder configuration+he config embedder --show++# Set custom base URL+he config embedder --api-key YOUR_KEY --base-url https://api.openai.com/v1++# Clear Embedder configuration+he config embedder --unset+```++## Configuration Options++### LLM Options++| Option | Flag | Description | Default |+|--------|------|-------------|---------|+| API Key | `--api-key`, `-k` | LLM API key | Required |+| Model | `--model`, `-m` | LLM model name | `gpt-4o-mini` |+| Base URL | `--base-url`, `-u` | Custom API base URL | OpenAI default |++### Embedder Options++| Option | Flag | Description | Default |+|--------|------|-------------|---------|+| API Key | `--api-key`, `-k` | Embedder API key | Required |+| Model | `--model`, `-m` | Embedder model name | `text-embedding-3-small` |+| Base URL | `--base-url`, `-u` | Custom API base URL | OpenAI default |++## Environment Variables++You can also use environment variables as an alternative:++```bash+export OPENAI_API_KEY=your-api-key+export OPENAI_BASE_URL=https://api.openai.com/v1+```++Environment variables are used when not set in the configuration file.diff --git a/docs/en/cli/index.md b/docs/en/cli/index.mdnew file mode 100644index 0000000..0adf21e--- /dev/null+++ b/docs/en/cli/index.md@@ -0,0 +1,50 @@+# CLI++Command-line interface for Hyper-Extract.++## Installation++```bash+uv pip install hyper-extract+```++## Quick Start++```bash+# Configure API Key+he config init -k YOUR_OPENAI_API_KEY++# Extract knowledge+he parse document.txt -t general/biography_graph -o ./output/++# Query the knowledge base+he search ./output/ "What are the key events?"++# Visualize the knowledge graph+he show ./output/+```++## Core Commands++| Command | Purpose |+|---------|---------|+| `he config init` | Configure API Key |+| `he parse` | Extract knowledge |+| `he search` | Query knowledge base |+| `he show` | Visualize graph |+| `he feed` | Incrementally supplement |+| `he list` | List templates |++## Configuration++[→ CLI Configuration Guide](./config.md)++## Detailed Guide++[→ CLI Command Details](./cli.md)++## Usage Examples++- [Finance Domain Templates](../templates/finance.md)+- [Legal Domain Templates](../templates/legal.md)+- [Medical Domain Templates](../templates/medicine.md)diff --git a/docs/en/concepts/auto-types.md b/docs/en/concepts/auto-types.mdindex 4332a38..a5882d7 100644--- a/docs/en/concepts/auto-types.md+++ b/docs/en/concepts/auto-types.md@@ -1,129 +1,91 @@# AutoTypes-Hyper-Extract uses auto types to determine extraction patterns, supporting 8 types in total.+AutoTypes define the **output data structure** for knowledge extraction. There are 8 types:-## Type Overview+## Record Types-| Type | Description | Use Case |-|------|-------------|----------|-| `model` | Single structured object | Extract single record |-| `list` | Ordered list | Extract ranked items |-| `set` | Deduplicated set | Extract unique entities |-| `graph` | Binary relation graph | Extract entity relations |-| `hypergraph` | Multi-entity relation | Extract multi-party relations |-| `temporal_graph` | Temporal graph | Add time dimension |-| `spatial_graph` | Spatial graph | Add space dimension |-| `spatio_temporal_graph` | Spatio-temporal graph | Add both time and space |+### AutoModel-## Selection Decision Tree+Structured data extraction with Pydantic models.-```-Need relationships?-├─ No → Record types-│ ├─ Single object → model-│ ├─ Ordered list → list-│ └─ Deduplicated set → set-└─ Yes → Graph types- ├─ Binary relations (A→B) → graph- └─ Multi-entity relations (A+B+C→D) → hypergraph--+ time dimension → temporal_graph-+ space dimension → spatial_graph-+ both → spatio_temporal_graph-```+```python+from pydantic import BaseModel, Field+from hyperextract import AutoModel++class Summary(BaseModel):+ title: str = Field(description="Title")+ summary: str = Field(description="Summary")-## Detailed Usage+model = AutoModel(data_schema=Summary, llm_client=llm)+```-### Model+### AutoList-Used for extracting a single structured object.+Extract lists of items.```python-from hyperextract import Template--ka = Template.create("finance/earnings_summary", "en")-result = ka.parse(text)+from hyperextract.types import AutoList-print(result.fields["company_name"])-print(result.fields["revenue"])+lst = AutoList[str](item_schema=str, llm_client=llm)+lst.feed_text(text)```-### List+### AutoSet-Used for extracting an ordered list.+Extract unique items (deduplicated).```python-from hyperextract import Template+from hyperextract.types import AutoSet-ka = Template.create("finance/risk_factor_set", "en")-result = ka.parse(text)--for item in result.fields:- print(item)+s = AutoSet[str](item_schema=str, llm_client=llm)+s.feed_text(text)```-### Set+## Graph Types-Used for extracting a deduplicated set.+### AutoGraph-```python-from hyperextract import Template+Entity-relationship extraction.-ka = Template.create("general/entity_registry", "en")-result = ka.parse(text)+```python+from hyperextract.types import AutoGraph-for entity in result.fields:- print(entity)+graph = AutoGraph(node_schema=Entity, edge_schema=Relation, llm_client=llm)+graph.feed_text(text)```-### Graph+### AutoHypergraph-Used for extracting binary relations.+Multi-entity relationships (n-ary relations).```python-from hyperextract import Template+from hyperextract.types import AutoHypergraph+```-ka = Template.create("finance/ownership_graph", "en")-result = ka.parse(text)+### AutoTemporalGraph-for entity in result.entities:- print(f"{entity['name']} ({entity['type']})")+Time-based relationships.-for relation in result.relations:- print(f"{relation['source']} --[{relation['type']}]--> {relation['target']}")+```python+from hyperextract.types import AutoTemporalGraph```-### Hypergraph+### AutoSpatialGraph-Used for extracting multi-entity relations.+Location-based relationships.```python-from hyperextract import Template--ka = Template.create("tcm/formula_composition", "en")-result = ka.parse(text)--for relation in result.relations:- print(f"Formula: {relation['formula_name']}")- print(f"Herbs: {relation['herbs']}")+from hyperextract.types import AutoSpatialGraph```-### Temporal Graph+### AutoSpatioTemporalGraph-Used for extracting temporal relations.+Both time and location.```python-from hyperextract import Template--ka = Template.create("finance/event_timeline", "en")-result = ka.parse(text)--for relation in result.relations:- print(f"{relation['source']} --[{relation['type']}]--> {relation['target']} @ {relation['time']}")+from hyperextract.types import AutoSpatioTemporalGraph```-## Next Steps+## Quick Links-- Learn about [Templates](./templates.md)-- Browse [Preset Templates](./templates.md)-- Explore [Domain Templates](../guides/domain-templates/index.md)+- [Domain Templates](../templates/index.md) - Ready-to-use templatesdiff --git a/docs/en/concepts/index.md b/docs/en/concepts/index.mdindex 86d80fe..d11c261 100644--- a/docs/en/concepts/index.md+++ b/docs/en/concepts/index.md@@ -1,52 +1,18 @@-# Core Concepts+# Concepts-## Overview+Hyper-Extract is built on a **three-layer architecture**:-Hyper-Extract is a knowledge extraction framework that extracts structured knowledge from various documents. This section introduces core concepts to help you understand how the system works.+- **Auto-Types** define the data structures for knowledge extraction+- **Methods** provide extraction algorithms built on Auto-Types+- **Templates** offer domain-specific configurations with ready-to-use prompts-## Core Concepts+## Auto-Types-### Template+Auto-Types are the foundation - they define the output data structure for knowledge extraction.-Templates use YAML to define what to extract, providing a declarative way to specify extraction schemas without writing code.+[→ Learn more about Auto-Types](./auto-types.md)-Learn more: [Templates](./templates.md)+## Quick Links-### AutoType--Hyper-Extract supports 8 auto types, each designed for different extraction scenarios:--| Type | Description | Use Case |-|------|-------------|----------|-| `model` | Single structured object | Extract single record |-| `list` | Ordered list | Extract ranked items |-| `set` | Deduplicated set | Extract unique entities |-| `graph` | Binary relation graph | Extract entity relations |-| `hypergraph` | Multi-entity relation | Extract multi-party relations |-| `temporal_graph` | Temporal graph | Add time dimension |-| `spatial_graph` | Spatial graph | Add space dimension |-| `spatio_temporal_graph` | Spatio-temporal graph | Add both time and space |--Learn more: [AutoTypes](./auto-types.md)--### Methods--Hyper-Extract supports multiple extraction methods:--- **Local Models**: Use locally deployed models-- **API Models**: Use cloud APIs (e.g., OpenAI, Claude)-- **Hybrid Mode**: Combine multiple methods--Learn more: [Methods](./methods.md)--## Quick Start--1. [Installation](../getting-started/installation.md)-2. [Quick Start Tutorial](../getting-started/quickstart.md)-3. [Template Design](./templates.md)--## Next Steps--- Browse the [Template Gallery](../reference/template-gallery.md)-- Explore [Domain Templates](../guides/domain-templates/index.md)-- Learn the [Python API](../guides/python-api.md)+- [Auto-Types](./auto-types.md) - 8 strong-typed knowledge structures+- [Templates](../templates/index.md) - Ready-to-use templatesdiff --git a/docs/en/concepts/methods.md b/docs/en/concepts/methods.mddeleted file mode 100644index 4aa64c3..0000000--- a/docs/en/concepts/methods.md+++ /dev/null@@ -1,123 +0,0 @@-# Extraction Methods--Hyper-Extract provides multiple extraction methods, each optimized for different use cases.--## Available Methods--### Basic Methods--| Method | Description | Use Case |-|--------|-------------|----------|-| atom | Direct extraction | Simple, straightforward extraction |-| kg_gen | Knowledge graph generation | Structured knowledge extraction |--### RAG-Based Methods--| Method | Description | Use Case |-|--------|-------------|----------|-| graph_rag | Graph-based RAG | Complex relationship extraction |-| light_rag | Lightweight RAG | Fast, efficient extraction |-| hyper_rag | Hypergraph RAG | Multi-entity relationships |-| hypergraph_rag | Advanced hypergraph | Complex network analysis |-| cog_rag | Cognitive RAG | Reasoning-based extraction |--### Specialized Methods--| Method | Description | Use Case |-|--------|-------------|----------|-| itext2kg | Text to knowledge graph | Document conversion |-| itext2kg_star | Enhanced text-to-kg | Advanced document processing |--## Method Comparison--### Speed--```-fast: atom > light_rag > kg_gen > graph_rag-slow: hyper_rag > cog_rag > hypergraph_rag-```--### Accuracy--```-high: cog_rag > graph_rag > hypergraph_rag > hyper_rag-medium: kg_gen > itext2kg > light_rag > atom-```--### Use Case Matrix--| Task | Recommended Method |-|------|-------------------|-| Simple extraction | atom |-| Fast prototyping | light_rag |-| Knowledge graphs | graph_rag |-| Complex relationships | hyper_rag |-| Reasoning tasks | cog_rag |-| Document conversion | itext2kg |--## Usage Examples--### Using atom Method--```python-from hyperextract.methods import atom--result = atom.extract(text, schema=MySchema)-```--### Using graph_rag Method--```python-from hyperextract.methods import graph_rag--result = graph_rag.extract(- text,- node_types=["Person", "Organization"],- edge_types=["WORKS_AT", "KNOWS"]-)-```--### Using cog_rag Method--```python-from hyperextract.methods import cog_rag--result = cog_rag.extract(- text,- task="Extract causal relationships"-)-```--## Method Selection Guide--### Quick Decision Tree--```-Is your task simple?-├── Yes → Use atom-└── No → Does it require reasoning?- ├── Yes → Use cog_rag- └── No → Do you need graphs?- ├── Yes → graph_rag or hyper_rag- └── No → Use light_rag-```--## Advanced Configuration--Each method supports custom configuration:--```python-result = graph_rag.extract(- text,- max_nodes=100,- max_edges=200,- temperature=0.0,- confidence_threshold=0.8-)-```--## Next Steps--- Explore [Templates](templates.md)-- See [CLI Reference](../reference/cli-reference.md)-- Browse [Examples](../guides/index.md)diff --git a/docs/en/concepts/templates.md b/docs/en/concepts/templates.mddeleted file mode 100644index db56100..0000000--- a/docs/en/concepts/templates.md+++ /dev/null@@ -1,593 +0,0 @@-# Templates--Templates define WHAT to extract using declarative YAML. They provide a powerful way to specify extraction schemas without writing code.--## Type Selection----Before designing a template, determine which type fits your needs:--```-Need relationships?-├─ No → Record types (model, list, set)-└─ Yes → Graph types (graph, hypergraph, temporal_graph, spatial_graph)--Record types: Direct field extraction, no entity or relation concepts-Graph types: Extract entities and their relationships-```--| Type | Description | Use Case |-|------|-------------|----------|-| `model` | Single structured object | Extract one record |-| `list` | Ordered array | Extract ranked items |-| `set` | Deduplicated collection | Extract unique entities |-| `graph` | Binary relations (A→B) | Extract entity relationships |-| `hypergraph` | Multi-entity relations | Extract multi-party events |-| `temporal_graph` | + time dimension | Extract events over time |-| `spatial_graph` | + space dimension | Extract events at locations |-| `spatio_temporal_graph` | + time + space | Extract events at locations over time |-------## Record Types--Record types use `output.fields` to define the data structure directly. No entities or relations.--### Common Structure--```yaml-language: en--name: TemplateName-type: [model/list/set]-tags: [domain]--description: 'Template description.'--output:- fields:- - name: field_name- type: str- description: 'Field description.'- required: false- default: 'value'--guideline:- target: 'Extraction target description.'- rules:- - 'Rule 1'- - 'Rule 2'--display:- label: '{field_name}'-```--### model - Single Object--Extract a single structured record.--```yaml-language: en--name: Earnings Summary-type: model-tags: [finance]--description: 'Extract key financial metrics from earnings reports.'--output:- fields:- - name: company_name- type: str- description: 'Company name.'- - name: revenue- type: str- description: 'Revenue amount.'- - name: quarter- type: str- description: 'Quarter.'--guideline:- target: 'Extract key financial information.'- rules:- - 'Extract company name and financial data'- - 'Use numbers from the source text'--display:- label: '{company_name}'-```--### list - Ordered Array--Extract ordered items (rankings, sequences, bullet points).--```yaml-language: en--name: Risk Factor List-type: list-tags: [finance]--description: 'Extract risk factors in order.'--output:- fields:- - name: category- type: str- description: 'Risk category.'- - name: description- type: str- description: 'Risk description.'--guideline:- target: 'Extract risk factors.'- rules:- - 'Extract all risk factors'- - 'Maintain order as they appear'--display:- label: '{category}'-```--### set - Deduplicated Collection--Extract unique entities with automatic deduplication.--```yaml-language: en--name: Person Set-type: set-tags: [general]--description: 'Extract unique person entities.'--output:- fields:- - name: name- type: str- description: 'Person name.'- - name: role- type: str- description: 'Role or position.'- required: false--guideline:- target: 'Extract person entities.'- rules:- - 'Extract all unique persons'- - 'Apply deduplication by name'--identifiers:- item_id: name--display:- label: '{name}'-```--**Note**: Set type requires `identifiers.item_id` to define the deduplication key.-------## Graph Types--Graph types extract entities and their relationships. They use `output.entities` and `output.relations`.--### Common Structure--```yaml-language: en--name: TemplateName-type: [graph/hypergraph/temporal_graph/spatial_graph]-tags: [domain]--description: 'Template description.'--output:- entities:- description: 'Entity description.'- fields:- - name: name- type: str- description: 'Entity name.'- - name: type- type: str- description: 'Entity type.'- relations:- description: 'Relation description.'- fields:- - name: source- type: str- - name: target- type: str- - name: type- type: str--guideline:- target: 'Extraction target description.'- rules_for_entities:- - 'Rule 1'- rules_for_relations:- - 'Rule 2'--identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}'- relation_members:- source: source- target: target--display:- entity_label: '{name} ({type})'- relation_label: '{type}'-```--### graph - Binary Relations--Extract relationships between two entities (A→B).--```yaml-language: en--name: Ownership Graph-type: graph-tags: [finance]--description: 'Extract ownership relationships.'--output:- entities:- fields:- - name: name- type: str- description: 'Entity name.'- - name: type- type: str- description: 'Entity type (company/person).'- relations:- fields:- - name: source- type: str- description: 'Owner.'- - name: target- type: str- description: 'Owned entity.'- - name: type- type: str- description: 'Relation type.'--guideline:- target: 'Extract ownership relationships.'- rules_for_entities:- - 'Extract companies and individuals'- - 'Maintain consistent naming'- rules_for_relations:- - 'Create relations only when explicitly stated'--identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}'- relation_members:- source: source- target: target--display:- entity_label: '{name} ({type})'- relation_label: '{type}'-```--### hypergraph - Multi-Entity Relations--Extract relationships involving multiple participants.--#### Simple Hypergraph (Flat List)--All participants have equal roles.--```yaml-language: en--name: Meeting Hypergraph-type: hypergraph-tags: [general]--output:- entities:- fields:- - name: name- type: str- relations:- fields:- - name: topic- type: str- description: 'Meeting topic.'- - name: participants- type: list- description: 'List of participants.'- - name: outcome- type: str- description: 'Meeting outcome.'- required: false--identifiers:- entity_id: name- relation_id: '{topic}'- relation_members: participants # STRING--display:- entity_label: '{name}'- relation_label: '{topic}'-```--#### Nested Hypergraph (Semantic Groups)--Participants have distinct semantic roles.--```yaml-language: en--name: Battle Analysis-type: hypergraph-tags: [history]--output:- entities:- fields:- - name: name- type: str- relations:- fields:- - name: battle_name- type: str- - name: attackers- type: list- description: 'Attacking parties.'- - name: defenders- type: list- description: 'Defending parties.'- - name: outcome- type: str--identifiers:- entity_id: name- relation_id: '{battle_name}'- relation_members: [attackers, defenders] # LIST--display:- entity_label: '{name}'- relation_label: '{battle_name}'-```--### temporal_graph - With Time Dimension--Add time dimension to graph relationships.--```yaml-language: en--name: Event Timeline-type: temporal_graph-tags: [general]--output:- entities:- fields:- - name: name- type: str- description: 'Event name.'- - name: type- type: str- description: 'Event type.'- relations:- fields:- - name: source- type: str- - name: target- type: str- - name: type- type: str- - name: time- type: str- description: 'When the relation occurred.'- required: false--guideline:- target: 'Extract events and temporal relationships.'- rules_for_entities:- - 'Extract key events'- rules_for_relations:- - 'Extract temporal relationships'- rules_for_time:- - 'Record when events occurred'--identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}|{time}'- relation_members:- source: source- target: target- time_field: time--display:- entity_label: '{name} ({type})'- relation_label: '{type}@{time}'-```--### spatial_graph - With Space Dimension--Add location dimension to graph relationships.--```yaml-language: en--name: Spatial Graph-type: spatial_graph-tags: [general]--output:- entities:- fields:- - name: name- type: str- - name: type- type: str- relations:- fields:- - name: source- type: str- - name: target- type: str- - name: type- type: str- - name: location- type: str- description: 'Where the relation occurred.'- required: false--identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}|{location}'- relation_members:- source: source- target: target- location_field: location--display:- entity_label: '{name} ({type})'- relation_label: '{type}@{location}'-```--### spatio_temporal_graph - Time + Space--Combine time and location dimensions.--```yaml-identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}|{location}|{time}'- relation_members:- source: source- target: target- time_field: time- location_field: location--display:- entity_label: '{name} ({type})'- relation_label: '{type}@{location}({time})'-```-------## Field Types--| Type | Description | Example |-|------|-------------|---------|-| `str` | String | "Hello World" |-| `int` | Integer | 42 |-| `float` | Float | 3.14 |-| `bool` | Boolean | true |-| `list` | List | ["a", "b", "c"] |-------## Display Configuration--| Type | entity_label | relation_label |-|------|--------------|----------------|-| graph | `{name} ({type})` | `{type}` |-| hypergraph | `{name}` | `{event_name}` |-| temporal_graph | `{name} ({type})` | `{type}@{time}` |-| spatial_graph | `{name} ({type})` | `{type}@{location}` |-| spatio_temporal_graph | `{name} ({type})` | `{type}@{location}({time})` |-------## Schema vs Guideline--| Schema Defines (WHAT) | Guideline Defines (HOW TO DO WELL) |-|----------------------|----------------------------------|-| Field names | Extraction strategy |-| Field types | Quality requirements |-| Field descriptions | Creation conditions |-| Required/optional | Common mistakes to avoid |--**Important**: Guideline should NOT repeat schema definitions.-------## Preset Templates--Hyper-Extract includes 80+ preset templates across 6 domains:--### Finance-- `finance/earnings_summary` (model)-- `finance/risk_factor_set` (set)-- `finance/ownership_graph` (graph)-- `finance/event_timeline` (temporal_graph)--### Legal-- `legal/case_fact_timeline` (temporal_graph)-- `legal/case_citation` (graph)-- `legal/contract_obligation` (list)--### Medicine-- `medicine/drug_interaction` (graph)-- `medicine/treatment_map` (temporal_graph)-- `medicine/discharge_instruction` (list)--### TCM-- `tcm/herb_property` (model)-- `tcm/formula_composition` (list)-- `tcm/meridian_graph` (graph)--### Industry-- `industry/safety_control` (list)-- `industry/equipment_topology` (graph)-- `industry/failure_case` (temporal_graph)--### General-- `general/graph` (graph)-- `general/list` (list)-- `general/model` (model)-- `general/set` (set)-- `general/biography_graph` (spatio_temporal_graph)-------## Using Templates--### CLI--```bash-# Use preset template-he parse document.txt -t finance/ownership_graph -o output/--# Use custom template-he parse document.txt -t template.yaml -o output/-```--### Python API--```python-from hyperextract import Template--# Load preset template-ka = Template.create("finance/ownership_graph", "en")--# Load from YAML-ka = Template.create("template.yaml", "en")--# Parse document-result = ka.parse(document_text)-```-------## Next Steps--- Browse the [Template Gallery](../../reference/template-gallery.md)-- Learn about [Domain Templates](../guides/domain-templates/index.md)-- Create your own templates-- Read the [Design Guide](https://github.com/hyper-extract/hyper-extract/blob/main/hyperextract/templates/DESIGN_GUIDE.md)diff --git a/docs/en/getting-started/configuration.md b/docs/en/getting-started/configuration.mddeleted file mode 100644index 23fcc95..0000000--- a/docs/en/getting-started/configuration.md+++ /dev/null@@ -1,60 +0,0 @@-# Configuration--Hyper-Extract uses a TOML configuration file. Default location: `~/.he/config.toml`--## Quick Setup--```bash-# Initialize with API key (recommended)-he config init -k <your-api-key>--# Or configure LLM and Embedder separately-he config llm --api-key <your-api-key>-he config embedder --api-key <your-api-key>-```--## Configuration Options--### LLM Settings--```bash-he config llm --api-key <your-api-key> --model gpt-4o-mini-```--| Option | Description | Default |-|--------|-------------|---------|-| `--api-key`, `-k` | LLM API key | Required |-| `--model`, `-m` | Model name | gpt-4o-mini |-| `--base-url`, `-u` | Custom API base URL | (default) |--### Embedder Settings--```bash-he config embedder --api-key <your-api-key> --model text-embedding-3-small-```--| Option | Description | Default |-|--------|-------------|---------|-| `--api-key`, `-k` | Embedder API key | Required |-| `--model`, `-m` | Model name | text-embedding-3-small |-| `--base-url`, `-u` | Custom API base URL | (default) |--## View Configuration--```bash-he config show-```--## Commands--| Command | Description |-|---------|-------------|-| `he config init -k KEY` | Initialize with API key for both LLM and Embedder |-| `he config llm` | Configure LLM settings |-| `he config embedder` | Configure Embedder settings |-| `he config show` | Show current configuration |--## Next Steps--- Learn about [Templates](../concepts/templates.md)-- Browse [Preset Templates](../concepts/templates.md#preset-templates)diff --git a/docs/en/getting-started/index.md b/docs/en/getting-started/index.mddeleted file mode 100644index 8d976ba..0000000--- a/docs/en/getting-started/index.md+++ /dev/null@@ -1,37 +0,0 @@-# Getting Started--Welcome to Hyper-Extract! This section will help you get up and running quickly.--## What's in This Section--- [Installation](installation.md) - How to install Hyper-Extract-- [Quick Start](quickstart.md) - Get started with your first extraction-- [Configuration](configuration.md) - Configure API keys and settings--## Prerequisites--Before using Hyper-Extract, you should have:--- Python 3.9 or higher installed-- An OpenAI API key (or compatible LLM API)-- Basic understanding of Python--## Choose Your Path--### For CLI Users--If you prefer command-line tools, see our [CLI Guide](../guides/cli.md) for detailed command documentation.--### For Python Developers--If you're building applications with Python, check out our [Python API Guide](../guides/python-api.md).--### For Template Designers--If you want to create custom extraction templates, see our [Template Design Guide](../concepts/templates.md).--## Next Steps--1. [Install Hyper-Extract](installation.md)-2. Try the [Quick Start](quickstart.md) tutorial-3. Explore the [Concepts](../concepts/index.md) sectiondiff --git a/docs/en/getting-started/installation.md b/docs/en/getting-started/installation.mddeleted file mode 100644index 92e6628..0000000--- a/docs/en/getting-started/installation.md+++ /dev/null@@ -1,24 +0,0 @@-# Installation--## Requirements--- Python 3.11+--## Install--### Using uv (Recommended)--```bash-uv pip install hyper-extract-```--### Using pip--```bash-pip install hyper-extract-```--## Next Steps--- [Quick Start](getting-started/quickstart.md) - Extract your first document-- [Configuration](getting-started/configuration.md) - Configure API settingsdiff --git a/docs/en/getting-started/quickstart.md b/docs/en/getting-started/quickstart.mddeleted file mode 100644index 5c4b608..0000000--- a/docs/en/getting-started/quickstart.md+++ /dev/null@@ -1,110 +0,0 @@-# Quick Start--This tutorial will walk you through extracting knowledge from a document in under 5 minutes.--## Step 1: Prepare Your Document--Let's start with a simple text document. Create a file called `document.txt`:--```text-Apple Inc. reported record quarterly revenue of $123.9 billion in Q1 2024.-CEO Tim Cook announced the company's strongest-ever iPhone sales.-The board declared a cash dividend of $0.24 per share.-Services revenue reached an all-time high of $22.3 billion.-```--## Step 2: Create an Extraction Template--Hyper-Extract uses YAML templates to define what to extract. Create `template.yaml`:--```yaml-language: en--name: Company News Summary-type: graph-tags: [finance]--description: 'Extract key financial events and entity relationships from news articles.'--output:- entities:- fields:- - name: name- type: str- description: 'Entity name'- - name: type- type: str- description: 'Entity type (company/person/event/amount)'- relations:- fields:- - name: source- type: str- description: 'Source entity'- - name: target- type: str- description: 'Target entity'- - name: type- type: str- description: 'Relation type'--guideline:- target: 'Extract entities and relationships from news articles.'- rules_for_entities:- - 'Extract companies, persons, amounts, etc.'- - 'Maintain consistent naming'- rules_for_relations:- - 'Create relations only when explicitly expressed'--identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}'- relation_members:- source: source- target: target--display:- entity_label: '{name} ({type})'- relation_label: '{type}'-```--## Step 3: Extract Knowledge (CLI)----```bash-he parse document.txt -o output/ -t template.yaml-```--## Step 4: Extract Knowledge (Python API)--```python-from hyperextract import Template--# Create template from YAML-ka = Template.create("template.yaml", "en")--# Parse document-result = ka.parse("Apple Inc. reported record quarterly revenue...")--# Access results-print(result.entities)-print(result.relations)-```--## Step 5: View Results--The extracted knowledge will be saved in your output directory. You can use the search command:--```bash-he search output/ "What financial events were mentioned?"-```--**AutoGraph Visualization Example:**----## Next Steps--- Learn about the [8 Auto-Types](../concepts/auto-types.md)-- Explore [Extraction Methods](../concepts/methods.md)-- Browse [Preset Templates](../concepts/templates.md)diff --git a/docs/en/guides/index.md b/docs/en/guides/index.mddeleted file mode 100644index 9b11adc..0000000--- a/docs/en/guides/index.md+++ /dev/null@@ -1,34 +0,0 @@-# Guides--This section provides step-by-step tutorials and how-to guides for using Hyper-Extract.--## What's in This Section--- [CLI Guide](cli.md) - Command-line interface documentation-- [Python API](python-api.md) - Python API usage guide-- [Domain Templates](domain-templates/index.md) - Templates for specific domains--## Popular Guides--### Getting Started with CLI--Learn how to use the command-line interface for quick extraction tasks.--### Python API Tutorial--Build applications using the Python API with detailed examples.--### Domain-Specific Templates--Use pre-built templates for finance, legal, medicine, and more.--## Quick Links--- [Finance Templates](domain-templates/finance.md) - Financial document extraction-- [Legal Templates](domain-templates/legal.md) - Legal document extraction-- [Medicine Templates](domain-templates/medicine.md) - Medical document extraction-- [TCM Templates](domain-templates/tcm.md) - Traditional Chinese Medicine templates--## Learn by Example--Check out our [Examples Repository](https://github.com/hyper-extract/hyper-extract/tree/main/examples) for complete working examples.diff --git a/docs/en/guides/python-api.md b/docs/en/guides/python-api.mddeleted file mode 100644index 6dcdc7c..0000000--- a/docs/en/guides/python-api.md+++ /dev/null@@ -1,167 +0,0 @@-# Python API--Hyper-Extract provides a Python API for programmatic extraction.--## Installation--```bash-pip install hyperextract-```--## Basic Usage--### Load Preset Template--```python-from hyperextract import Template--# Load preset template-ka = Template.create("general/graph", "en")--# Parse document-result = ka.parse(document_text)--# Access results-print(result.entities)-print(result.relations)-```--### Load Custom Template--```python-from hyperextract import Template--# Load from YAML file-ka = Template.create("template.yaml", "en")--# Load from string-yaml_content = """-language: en-name: Custom Template-type: graph-tags: [custom]-description: '...'-output:- entities:- fields:- - name: name- type: str- description: 'Name'- relations:- fields:- - name: source- type: str- description: 'Source'- - name: target- type: str- description: 'Target'- - name: type- type: str- description: 'Type'-guideline:- target: '...'-identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}'- relation_members:- source: source- target: target-"""--ka = Template.create(yaml_content, "en")-```--### Batch Processing--```python-from hyperextract import Template--ka = Template.create("general/graph", "en")--documents = ["Document 1 content...", "Document 2 content...", "Document 3 content..."]--results = []-for doc in documents:- result = ka.parse(doc)- results.append(result)-```--### Export Results--```python-from hyperextract import Template--ka = Template.create("general/graph", "en")-result = ka.parse(document_text)--# Export to JSON-json_output = result.to_json()--# Export to Dict-dict_output = result.to_dict()--# Export to triples-triples = result.to_triples()-```--## Template Creation--### Create New Template--```python-from hyperextract import Template--template = Template.create("template.yaml", "en")-```--### Save Template--```python-from hyperextract import Template--ka = Template.create("general/graph", "en")-ka.save("my_template.yaml")-```--## Configuration Options--### Set Language--```python-from hyperextract import Template--# Single language-ka = Template.create("general/graph", "en")--# Multiple languages-ka = Template.create("general/graph", ["zh", "en"])-```--### Set Model--```python-from hyperextract import Template--# Use specified model-ka = Template.create("general/graph", "en", model="gpt-4")--# Use local model-ka = Template.create("general/graph", "en", model="local-model")-```--## Error Handling--```python-from hyperextract import Template--try:- ka = Template.create("template.yaml", "en")- result = ka.parse(document_text)-except Exception as e:- print(f"Extraction failed: {e}")-```--## Next Steps--- Browse [Preset Templates](../concepts/templates.md)-- Explore [Domain Templates](./domain-templates/index.md)diff --git a/docs/en/index.md b/docs/en/index.mdindex 9656352..e943856 100644--- a/docs/en/index.md+++ b/docs/en/index.md@@ -1,10 +1,11 @@-# Hyper-Extract+# 🚀 Hyper-Extract> **"Stop reading. Start understanding."**+> *"告别文档焦虑,让信息一目了然"*-**Transform documents into knowledge abstracts — with just one command.**+**Smart Knowledge Extraction CLI — Transform documents into structured knowledge with one command.**-+[](https://python.org)[](LICENSE)@@ -14,14 +15,14 @@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**.-## Core Features+## ✨ 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 `GraphRAG`, `LightRAG`, `Hyper-RAG`, and `KG-Gen`.- 📝 **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+## ⚡ Quick Start### Installation@@ -32,29 +33,85 @@ uv pip install hyper-extract### The Command Line Way```bash-he config init -k <your-api-key>-he parse sample.md -t general/biography_graph -o ./output/ -l en-he search ./output/ "What are the key events?"-he feed ./output/ another_sample.md+# Configure OpenAI API Key+he config init -k YOUR_OPENAI_API_KEY++# Extract knowledge+he parse examples/en/tesla.md -t general/biography_graph -o ./output/ -l en++# Query the knowledge base+he search ./output/ "What are Tesla's major achievements?"++# Visualize the knowledge graph+he show ./output/++# Incrementally supplement knowledge+he feed ./output/ examples/en/tesla_question.md++# Show the updated knowledge graph+he show ./output/```### The Python API Way+#### Installation++```bash+# Clone the repository+git clone https://github.com/yifanfeng97/hyper-extract.git+cd hyper-extract++# Install dependencies+uv sync+```++#### Configuration++```bash+# Copy the example env file+cp .env.example .env++# Edit .env with your API key and base URL+# OPENAI_API_KEY=your-api-key+# OPENAI_BASE_URL=https://api.openai.com/v1+```++#### Usage+```python+import os+from dotenv import load_dotenv++# Load environment variables from .env file+load_dotenv()+from hyperextract import Template+# Create a templateka = Template.create("general/biography_graph")++# Parse a document+with open("examples/en/tesla.md", "r") as f:+ text = f.read()result = ka.parse(text)++# Visualize the knowledge graph+ka.show(result)++# Incrementally supplement knowledge+with open("examples/en/tesla_question.md", "r") as f:+ new_text = f.read()+ka.feed(result, new_text)++# Show the updated knowledge graph+ka.show(result)```-## Documentation+## 🧩 The 8 Auto-Types-- [Getting Started](getting-started/index.md) - Get up and running quickly-- [Concepts](concepts/index.md) - Understand the core concepts-- [Guides](guides/index.md) - Step-by-step tutorials-- [Reference](reference/index.md) - API and configuration reference+Our framework embraces complexity without making you write boilerplate code.-## The 8 Auto-Types+| Type | Description ||------|-------------|@@ -69,16 +126,42 @@ result = ka.parse(text)### Example: AutoGraph Visualization-After extraction with `AutoGraph`, you can visualize your knowledge graph:+Here is the knowledge graph visualization after `AutoGraph` extraction:-## Architecture+## 🛠️ Architecture++Hyper-Extract follows a **three-layer architecture**:++- **Auto-Types** define the data structures for knowledge extraction. With 8 strong-typed structures (AutoModel, AutoList, AutoSet, AutoGraph, AutoHypergraph, AutoTemporalGraph, AutoSpatialGraph, AutoSpatioTemporalGraph), they serve as the output format for all extractions.++- **Methods** provide extraction algorithms built on Auto-Types. This includes Typical methods (KG-Gen, iText2KG, iText2KG*) and RAG-based methods (GraphRAG, LightRAG, Hyper-RAG, HypergraphRAG, Cog-RAG).++- **Templates** offer domain-specific configurations with ready-to-use prompts and data structures. Covering 6 domains (Finance, Legal, Medical, TCM, Industry, General) with 80+ preset templates, users can extract knowledge without dealing with Auto-Types or Methods directly.++Use via **CLI** (`he parse`, `he search`, `he show`...) or **Python API** (`Template.create()`).-The system is built on a robust triad: **Auto-Types** (Multi-typed structures), **Methods** (The Execution strategy), and **Templates** (Declarative schema).+## 📈 Comparison with Other Libraries++| Feature | GraphRAG | LightRAG | KG-Gen | ATOM | **Hyper-Extract** |+| ---------------- | :------: | :------: | :----: | :--: | :---------------: |+| Knowledge Graph | ✅ | ✅ | ✅ | ✅ | ✅ |+| Temporal Graph | ✅ | ❌ | ❌ | ✅ | ✅ |+| Spatial Graph | ❌ | ❌ | ❌ | ❌ | ✅ |+| Hypergraph | ❌ | ❌ | ❌ | ❌ | ✅ |+| Domain Templates | ❌ | ❌ | ❌ | ❌ | ✅ |+| CLI Tool | ✅ | ❌ | ❌ | ❌ | ✅ |+| Multi-language | ✅ | ❌ | ❌ | ❌ | ✅ |++## 📚 Documentation++- [Getting Started](cli/index.md) - Get up and running quickly+- [Domain Templates](templates/index.md) - Ready-to-use templates-## License+## 🤝 Contributing & License+Contributions are welcome! Please submit Issues and PRs.Licensed under **Apache-2.0**.diff --git a/docs/en/python/config.md b/docs/en/python/config.mdnew file mode 100644index 0000000..3f3b8ee--- /dev/null+++ b/docs/en/python/config.md@@ -0,0 +1,74 @@+# Python SDK Configuration++## Environment Variables++Create a `.env` file in your project root:++```bash+# Copy the example env file+cp .env.example .env+```++Edit `.env` with your configuration:++```bash+OPENAI_API_KEY=your-api-key+OPENAI_BASE_URL=https://api.openai.com/v1+```++## Loading Environment Variables++Use `python-dotenv` to load environment variables:++```bash+pip install python-dotenv+```++```python+from dotenv import load_dotenv++# Load environment variables from .env file+load_dotenv()+```++## Programmatic Configuration++You can also set environment variables programmatically:++```python+import os++os.environ["OPENAI_API_KEY"] = "your-api-key"+os.environ["OPENAI_BASE_URL"] = "https://api.openai.com/v1"+```++## Configuration Options++### LLM Options++| Option | Environment Variable | Default |+|--------|---------------------|---------|+| API Key | `OPENAI_API_KEY` | Required |+| Base URL | `OPENAI_BASE_URL` | OpenAI default |+| Model | `LLM_MODEL` | `gpt-4o-mini` |+| Temperature | `LLM_TEMPERATURE` | `0.0` |++### Embedder Options++| Option | Environment Variable | Default |+|--------|---------------------|---------|+| Model | `EMBEDDER_MODEL` | `text-embedding-3-small` |+| Batch Size | `EMBEDDER_BATCH_SIZE` | `100` |++## Example .env File++```bash+# Required+OPENAI_API_KEY=sk-your-api-key++# Optional+OPENAI_BASE_URL=https://api.openai.com/v1+LLM_MODEL=gpt-4o-mini+LLM_TEMPERATURE=0.0+EMBEDDER_MODEL=text-embedding-3-small+```diff --git a/docs/en/python/index.md b/docs/en/python/index.mdnew file mode 100644index 0000000..8ae8ce7--- /dev/null+++ b/docs/en/python/index.md@@ -0,0 +1,55 @@+# Python SDK++Python API for Hyper-Extract.++## Installation++```bash+pip install hyper-extract+```++## Quick Start++```python+from dotenv import load_dotenv++# Load environment variables from .env file+load_dotenv()++from hyperextract import Template++# Create a template+ka = Template.create("general/biography_graph", "en")++# Parse a document+with open("examples/en/tesla.md", "r") as f:+ text = f.read()+result = ka.parse(text)++# Access results+print(result.entities)+print(result.relations)+```++## Core APIs++| API | Purpose |+|-----|---------|+| `Template.create()` | Create template instance |+| `ka.parse()` | Parse document |+| `ka.feed()` | Incrementally supplement |+| `ka.search()` | Query knowledge base |++## Configuration++[→ Python SDK Configuration Guide](./config.md)++## Detailed Guide++[→ Python API Details](./python-api.md)++## Usage Examples++- [Finance Domain Templates](../templates/finance.md)+- [Legal Domain Templates](../templates/legal.md)+- [Medical Domain Templates](../templates/medicine.md)diff --git a/docs/en/python/python-api.md b/docs/en/python/python-api.mdnew file mode 100644index 0000000..ba351ee--- /dev/null+++ b/docs/en/python/python-api.md@@ -0,0 +1,280 @@+# Python API++## Installation++```bash+pip install hyperextract+```++## Configuration++Set up your API key using dotenv:++```python+from dotenv import load_dotenv+load_dotenv()+```++Create a `.env` file:+```bash+OPENAI_API_KEY=your-api-key+```++## Quick Start++```python+from hyperextract import Template++ka = Template.create("general/biography_graph", "en")+result = ka.parse(document_text)+```++---++## AutoTypes++AutoTypes define the **output data structure** for knowledge extraction. There are 8 types:++### AutoModel - Structured Data++Extract structured summaries with AutoModel:++```python+from pydantic import BaseModel, Field+from hyperextract import AutoModel+from langchain_openai import ChatOpenAI++class BiographySummary(BaseModel):+ title: str = Field(description="Title of the biography")+ subject: str = Field(description="Main subject name")+ summary: str = Field(description="Brief summary")++llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)++model = AutoModel(+ data_schema=BiographySummary,+ llm_client=llm,+)+model.feed_text(text)+print(model.data.title)+```++### AutoList - List Data++Extract lists of items:++```python+from hyperextract.types import AutoList++llm = ChatOpenAI(model="gpt-4o-mini")+embedder = OpenAIEmbeddings(model="text-embedding-3-small")++lst = AutoList[str](+ item_schema=str,+ llm_client=llm,+ embedder=embedder,+)+lst.feed_text(text)+print(lst.items) # List of extracted items+```++### AutoSet - Deduplicated List++Extract unique items (deduplicated):++```python+from hyperextract.types import AutoSet++s = AutoSet[str](+ item_schema=str,+ llm_client=llm,+ embedder=embedder,+)+s.feed_text(text)+print(s.items) # Deduplicated list+```++### AutoGraph - Knowledge Graph++Extract entities and relationships:++```python+from pydantic import BaseModel, Field+from hyperextract.types import AutoGraph++class Entity(BaseModel):+ name: str = Field(description="Entity name")+ type: str = Field(description="Entity type")++class Relation(BaseModel):+ source: str = Field(description="Source entity")+ target: str = Field(description="Target entity")+ type: str = Field(description="Relation type")++graph = AutoGraph[Entity, Relation](+ node_schema=Entity,+ edge_schema=Relation,+ node_key_extractor=lambda x: x.name,+ edge_key_extractor=lambda x: f"{x.source}-{x.type}-{x.target}",+ llm_client=llm,+ embedder=embedder,+)+graph.feed_text(text)+print(f"Nodes: {len(graph.nodes)}, Edges: {len(graph.edges)}")+```++### AutoHypergraph - Hypergraph++For multi-entity relationships (n-ary relations):++```python+from hyperextract.types import AutoHypergraph+# See examples/en/autotypes/hypergraph_demo.py+```++### AutoTemporalGraph - Temporal Graph++For time-based relationships:++```python+from hyperextract.types import AutoTemporalGraph+# See examples/en/autotypes/temporal_graph_demo.py+```++### AutoSpatialGraph - Spatial Graph++For location-based relationships:++```python+from hyperextract.types import AutoSpatialGraph+# See examples/en/autotypes/spatial_graph_demo.py+```++### AutoSpatioTemporalGraph - Spatio-Temporal Graph++For both time and location:++```python+from hyperextract.types import AutoSpatioTemporalGraph+# See examples/en/autotypes/spatio_temporal_graph_demo.py+```++---++## Methods vs Templates++Hyper-Extract provides two ways to extract knowledge:++### Methods (Low-level)++Methods give you **full control** over the extraction process. Use them when you need:+- Custom extraction logic+- Specific algorithm tuning+- Advanced use cases++```python+from hyperextract.methods.typical import KG_Gen++ka = KG_Gen(llm_client=llm, embedder=embedder)+ka.feed_text(text)+result = ka.chat("What are the main achievements?")+```++Available Methods:+- **Typical**: KG_Gen, iText2KG, iText2KG*+- **RAG-Based**: GraphRAG, LightRAG, HyperRAG, HypergraphRAG, CogRAG++### Templates (High-level)++Templates are **pre-configured** schemas for common use cases. Use them when you want:+- Quick results+- Domain-specific extraction+- Zero-code setup++```python+from hyperextract import Template++ka = Template.create("finance/earnings_summary", "en")+result = ka.parse(text)+```++### When to Use Which?++| Scenario | Recommendation |+|----------|----------------|+| Quick prototyping | Templates |+| Domain-specific extraction | Templates |+| Custom extraction logic | Methods |+| Real-time interaction | Methods |+| Batch processing | Both work |++---++## Advanced Usage++### Batch Processing++```python+from hyperextract import Template++ka = Template.create("general/biography_graph", "en")+documents = ["doc1.txt", "doc2.txt", "doc3.txt"]++results = []+for doc in documents:+ with open(doc) as f:+ result = ka.parse(f.read())+ results.append(result)+```++### Incremental Supplement (feed)++```python+ka = Template.create("general/biography_graph", "en")+result = ka.parse(text1)++# Add more knowledge+ka.feed(result, text2)+```++### Knowledge Q&A (chat)++```python+ka.build_index()+answer = ka.chat("What are the key events?")+print(answer.content)+```++### Error Handling++```python+from hyperextract import Template++try:+ ka = Template.create("template_name", "en")+ result = ka.parse(text)+except Exception as e:+ print(f"Error: {e}")+ # Handle error+```++### Result Export++```python+# Export to JSON+json_output = result.to_json()++# Export to Dict+dict_output = result.to_dict()++# Export to Triples+triples = result.to_triples()+```++---++## Next Steps++- [Preset Templates](../templates/index.md)+- [Domain Templates](../templates/index.md)+- [Explore Examples](https://github.com/yifanfeng97/hyper-extract/tree/main/examples/en)diff --git a/docs/en/reference/cli-reference.md b/docs/en/reference/cli-reference.mddeleted file mode 100644index 924f269..0000000--- a/docs/en/reference/cli-reference.md+++ /dev/null@@ -1,192 +0,0 @@-# CLI Reference--Complete reference for all Hyper-Extract CLI commands.--## Command Overview--| Command | Description |-|---------|-------------|-| `he config` | Manage configuration |-| `he parse` | Extract knowledge from documents |-| `he search` | Query extracted knowledge |-| `he feed` | Add new documents to knowledge base |-| `he list` | List available templates |--## config--Manage Hyper-Extract configuration.--### Syntax--```bash-he config <action> [options]-```--### Actions--#### init--Initialize configuration:--```bash-he config init -k API_KEY [--provider PROVIDER]-```--#### show--Show current configuration:--```bash-he config show [--format json|yaml]-```--#### set--Update configuration option:--```bash-he config set KEY VALUE-```--#### list-templates--List available templates:--```bash-he config list-templates [--category CATEGORY]-```--## parse--Extract knowledge from documents.--### Syntax--```bash-he parse <input> [options]-```--### Options--| Option | Description | Default |-|--------|-------------|---------|-| `-o, --output` | Output directory | Required |-| `-t, --template` | Template name | Auto-detect |-| `-l, --language` | Document language | Auto-detect |-| `--method` | Extraction method | Default |-| `--batch` | Batch processing | False |-| `--format` | Output format | json |--### Examples--```bash-# Basic usage-he parse document.txt -o output/--# With template-he parse document.txt -t finance/earnings_summary -o output/--# Batch processing-he parse ./documents/ -o output/ --batch--# Specify language-he parse chinese.txt -l zh -o output/-```--## search--Query extracted knowledge.--### Syntax--```bash-he search <knowledge_base> <query> [options]-```--### Options--| Option | Description | Default |-|--------|-------------|---------|-| `--filter` | Filter by node/edge type | None |-| `--limit` | Maximum results | 10 |-| `--format` | Output format | json |--### Examples--```bash-# Basic search-he search output/ "What happened?"--# With filters-he search output/ "financial events" --filter type=FinancialEvent--# Limited results-he search output/ "companies" --limit 5-```--## feed--Add new documents to existing knowledge base.--### Syntax--```bash-he feed <knowledge_base> <documents...> [options]-```--### Options--| Option | Description | Default |-|--------|-------------|---------|-| `-t, --template` | Template name | Inherited |-| `--merge` | Merge strategy | smart |--### Examples--```bash-# Add single document-he feed output/ new_doc.txt--# Add multiple documents-he feed output/ doc1.txt doc2.txt doc3.txt--# Add directory-he feed output/ ./new_documents/-```--## list--List available templates.--### Syntax--```bash-he list [options]-```--### Options--| Option | Description | Default |-|--------|-------------|---------|-| `--category` | Filter by category | All |-| `--domain` | Filter by domain | All |-| `--format` | Output format | table |--### Categories--- `finance`-- `legal`-- `medicine`-- `tcm`-- `industry`-- `general`--## Global Options--| Option | Description |-|--------|-------------|-| `--help` | Show help message |-| `--version` | Show version number |-| `--verbose` | Enable verbose output |-| `--debug` | Enable debug mode |-| `--config PATH` | Custom config file |diff --git a/docs/en/reference/index.md b/docs/en/reference/index.mddeleted file mode 100644index 9efee88..0000000--- a/docs/en/reference/index.md+++ /dev/null@@ -1,21 +0,0 @@-# Reference--This section provides detailed API and configuration reference documentation.--## What's in This Section--- [CLI Reference](cli-reference.md) - Complete CLI command reference-- [Template Gallery](template-gallery.md) - All available templates--## API Reference--For detailed Python API documentation, see the [API Documentation](https://hyper-extract.readthedocs.io/).--## Configuration Reference--See [Configuration Guide](../getting-started/configuration.md) for configuration options.--## Next Steps--- [CLI Reference](cli-reference.md)-- [Template Gallery](template-gallery.md)diff --git a/docs/en/reference/template-gallery.md b/docs/en/reference/template-gallery.mddeleted file mode 100644index f299c05..0000000--- a/docs/en/reference/template-gallery.md+++ /dev/null@@ -1,99 +0,0 @@-# Template Gallery--Complete list of all available preset templates in Hyper-Extract.--## Finance Templates--### Core Templates--| Template | Description |-|----------|-------------|-| `finance/earnings_summary` | Extract earnings report highlights |-| `finance/risk_factor_set` | Extract risk factors |-| `finance/ownership_graph` | Extract ownership relationships |-| `finance/event_timeline` | Extract financial events timeline |-| `finance/sentiment_model` | Extract sentiment analysis |--## Legal Templates--### Core Templates--| Template | Description |-|----------|-------------|-| `legal/case_facts` | Extract case facts from judgments |-| `legal/case_citation` | Extract legal citations |-| `legal/contract_obligation` | Extract contract obligations |-| `legal/compliance_list` | Extract compliance requirements |-| `legal/defined_term_set` | Extract defined terms |-| `legal/case_fact_timeline` | Extract case fact timeline |--## Medicine Templates--### Core Templates--| Template | Description |-|----------|-------------|-| `medicine/drug_interaction` | Extract drug interactions |-| `medicine/treatment_map` | Extract treatment plans |-| `medicine/anatomy_graph` | Extract anatomical relationships |-| `medicine/hospital_timeline` | Extract patient hospital timeline |-| `medicine/discharge_instruction` | Extract discharge instructions |--## TCM Templates--### Core Templates--| Template | Description |-|----------|-------------|-| `tcm/herb_property` | Extract herb properties |-| `tcm/formula_composition` | Extract formula composition |-| `tcm/herb_relation` | Extract herb relationships |-| `tcm/meridian_graph` | Extract meridian relationships |-| `tcm/syndrome_reasoning` | Extract syndrome reasoning |--## Industry Templates--### Core Templates--| Template | Description |-|----------|-------------|-| `industry/safety_control` | Extract safety controls |-| `industry/equipment_topology` | Extract equipment relationships |-| `industry/operation_flow` | Extract operation flows |-| `industry/failure_case` | Extract failure case analysis |-| `industry/emergency_response` | Extract emergency procedures |--## General Templates--### Core Templates--| Template | Description |-|----------|-------------|-| `general/biography` | Extract biographical information |-| `general/concepts` | Extract conceptual relationships |-| `general/workflow` | Extract workflow steps |-| `general/doc_structure` | Extract document structure |-| `general/base_model` | Basic model extraction |-| `general/base_list` | Basic list extraction |-| `general/base_set` | Basic set extraction |-| `general/base_graph` | Basic graph extraction |-| `general/base_hypergraph` | Basic hypergraph extraction |--## Using Templates--### CLI--```bash-he parse document.txt -t <template_name>-```--### Python API--```python-ka = Template.create("<template_name>")-result = ka.parse(document_text)-```--## Creating Custom Templates--See the [Template Design Guide](../concepts/templates.md) for creating your own templates.diff --git a/docs/en/resources/contributing.md b/docs/en/resources/contributing.mdindex de17703..60793bc 100644--- a/docs/en/resources/contributing.md+++ b/docs/en/resources/contributing.md@@ -102,9 +102,9 @@ We welcome translation contributions:## Development Resources-- [GitHub Repository](https://github.com/hyper-extract/hyper-extract)-- [Issue Tracker](https://github.com/hyper-extract/hyper-extract/issues)-- [Discussions](https://github.com/hyper-extract/hyper-extract/discussions)+- [GitHub Repository](https://github.com/yifanfeng97/hyper-extract)+- [Issue Tracker](https://github.com/yifanfeng97/hyper-extract/issues)+- [Discussions](https://github.com/yifanfeng97/hyper-extract/discussions)## Code of Conductdiff --git a/docs/en/resources/faq.md b/docs/en/resources/faq.mdindex afb813d..683d32e 100644--- a/docs/en/resources/faq.md+++ b/docs/en/resources/faq.md@@ -59,7 +59,7 @@ Choose a template based on:### How do I create a custom template?-See the [Template Design Guide](../concepts/templates.md) for creating custom templates.+See the [Domain Templates](../templates/index.md) for creating custom templates.## Troubleshootingdiff --git a/docs/en/resources/troubleshooting.md b/docs/en/resources/troubleshooting.mdindex 10dbfaf..f6199a9 100644--- a/docs/en/resources/troubleshooting.md+++ b/docs/en/resources/troubleshooting.md@@ -145,5 +145,5 @@ he config init -k <your-api-key>If you're still experiencing issues:1. Check the [FAQ](faq.md)-2. Search existing [GitHub Issues](https://github.com/hyper-extract/hyper-extract/issues)+2. Search existing [GitHub Issues](https://github.com/yifanfeng97/hyper-extract/issues)3. Create a new issue with detailed informationdiff --git a/docs/en/guides/domain-templates/finance.md b/docs/en/templates/finance.mdsimilarity index 98%rename from docs/en/guides/domain-templates/finance.mdrename to docs/en/templates/finance.mdindex e0580fb..caf8be4 100644--- a/docs/en/guides/domain-templates/finance.md+++ b/docs/en/templates/finance.md@@ -227,4 +227,4 @@ print(result.fields)- [Legal Templates](legal.md)- [Medicine Templates](medicine.md)-- [Template Gallery](../../reference/template-gallery.md)+diff --git a/docs/en/guides/domain-templates/index.md b/docs/en/templates/index.mdsimilarity index 71%rename from docs/en/guides/domain-templates/index.mdrename to docs/en/templates/index.mdindex 9538290..a2f3fd4 100644--- a/docs/en/guides/domain-templates/index.md+++ b/docs/en/templates/index.md@@ -1,13 +1,13 @@-# Domain Templates+# TemplatesHyper-Extract includes specialized templates for various industries and use cases.## Available Domains-- [Finance](finance.md) - Financial document extraction-- [Legal](legal.md) - Legal document extraction-- [Medicine](medicine.md) - Medical document extraction-- [TCM](tcm.md) - Traditional Chinese Medicine templates+- [Finance](domain/finance.md) - Financial document extraction+- [Legal](domain/legal.md) - Legal document extraction+- [Medicine](domain/medicine.md) - Medical document extraction+- [TCM](domain/tcm.md) - Traditional Chinese Medicine templates## Quick Start@@ -62,6 +62,6 @@ Traditional Chinese Medicine specific templates:- Meridian graphs- Syndrome reasoning-## Creating Custom Domain Templates+## Quick Links-See [Template Design Guide](../../concepts/templates.md) for creating your own domain-specific templates.+- [Concepts](../concepts/index.md) - Understand AutoTypes and Methodsdiff --git a/docs/en/guides/domain-templates/legal.md b/docs/en/templates/legal.mdsimilarity index 98%rename from docs/en/guides/domain-templates/legal.mdrename to docs/en/templates/legal.mdindex 789165a..95bd9f9 100644--- a/docs/en/guides/domain-templates/legal.md+++ b/docs/en/templates/legal.md@@ -227,4 +227,4 @@ print(result.entities)- [Finance Templates](finance.md)- [Medicine Templates](medicine.md)-- [Template Gallery](../../reference/template-gallery.md)+diff --git a/docs/en/guides/domain-templates/medicine.md b/docs/en/templates/medicine.mdsimilarity index 98%rename from docs/en/guides/domain-templates/medicine.mdrename to docs/en/templates/medicine.mdindex dfb9794..c9643f8 100644--- a/docs/en/guides/domain-templates/medicine.md+++ b/docs/en/templates/medicine.md@@ -208,4 +208,4 @@ print(result.entities)- [TCM Templates](tcm.md)- [Finance Templates](finance.md)-- [Template Gallery](../../reference/template-gallery.md)+diff --git a/docs/en/guides/domain-templates/tcm.md b/docs/en/templates/tcm.mdsimilarity index 98%rename from docs/en/guides/domain-templates/tcm.mdrename to docs/en/templates/tcm.mdindex 5e04a51..b9167da 100644--- a/docs/en/guides/domain-templates/tcm.md+++ b/docs/en/templates/tcm.md@@ -225,4 +225,4 @@ print(result.fields)- [Medicine Templates](medicine.md)- [Finance Templates](finance.md)-- [Template Gallery](../../reference/template-gallery.md)+diff --git a/docs/zh/guides/cli.md b/docs/zh/cli/cli.mdsimilarity index 93%rename from docs/zh/guides/cli.mdrename to docs/zh/cli/cli.mdindex 036361b..84c6ea8 100644--- a/docs/zh/guides/cli.md+++ b/docs/zh/cli/cli.md@@ -7,7 +7,7 @@ Hyper-Extract CLI 提供了强大的命令行界面用于知识提取。CLI 已包含在主包中:```bash-pip install hyper-extract+uv pip install hyper-extract```## 基本用法@@ -158,6 +158,5 @@ he parse chinese_doc.txt -l zh -o ./output/## 下一步-- 探索 [Python API](python-api.md)-- 浏览 [领域模板](domain-templates/index.md)-- 查看 [CLI 参考](../reference/cli-reference.md)+- 探索 [Python API](../python/python-api.md)+- 浏览 [领域模板](../templates/index.md)diff --git a/docs/zh/cli/config.md b/docs/zh/cli/config.mdnew file mode 100644index 0000000..6520c48--- /dev/null+++ b/docs/zh/cli/config.md@@ -0,0 +1,83 @@+# CLI 配置++## 配置文件++CLI 配置文件位于 `~/.he/config.toml`。++## 初始化配置++```bash+# 使用 API Key 初始化(推荐首次用户)+he config init -k YOUR_OPENAI_API_KEY++# 交互式设置(会提示输入 LLM 和 Embedder 配置)+he config init+```++## 查看配置++```bash+# 显示当前配置+he config show+```++## 配置 LLM++```bash+# 设置 LLM API key 和模型+he config llm --api-key YOUR_KEY --model gpt-4o-mini++# 显示当前 LLM 配置+he config llm --show++# 设置自定义 base URL+he config llm --api-key YOUR_KEY --base-url https://api.openai.com/v1++# 清除 LLM 配置+he config llm --unset+```++## 配置 Embedder++```bash+# 设置 Embedder API key 和模型+he config embedder --api-key YOUR_KEY --model text-embedding-3-small++# 显示当前 Embedder 配置+he config embedder --show++# 设置自定义 base URL+he config embedder --api-key YOUR_KEY --base-url https://api.openai.com/v1++# 清除 Embedder 配置+he config embedder --unset+```++## 配置选项++### LLM 选项++| 选项 | 标志 | 描述 | 默认值 |+|------|------|------|--------|+| API Key | `--api-key`, `-k` | LLM API key | 必填 |+| Model | `--model`, `-m` | LLM 模型名称 | `gpt-4o-mini` |+| Base URL | `--base-url`, `-u` | 自定义 API base URL | OpenAI 默认 |++### Embedder 选项++| 选项 | 标志 | 描述 | 默认值 |+|------|------|------|--------|+| API Key | `--api-key`, `-k` | Embedder API key | 必填 |+| Model | `--model`, `-m` | Embedder 模型名称 | `text-embedding-3-small` |+| Base URL | `--base-url`, `-u` | 自定义 API base URL | OpenAI 默认 |++## 环境变量++你也可以使用环境变量作为替代方案:++```bash+export OPENAI_API_KEY=your-api-key+export OPENAI_BASE_URL=https://api.openai.com/v1+```++当配置文件中未设置时,将使用环境变量。diff --git a/docs/zh/cli/index.md b/docs/zh/cli/index.mdnew file mode 100644index 0000000..7814796--- /dev/null+++ b/docs/zh/cli/index.md@@ -0,0 +1,50 @@+# CLI++Hyper-Extract 命令行界面。++## 安装++```bash+uv pip install hyper-extract+```++## 快速开始++```bash+# 配置 API Key+he config init -k YOUR_OPENAI_API_KEY++# 提取知识+he parse document.txt -t general/biography_graph -o ./output/++# 查询知识库+he search ./output/ "有哪些关键事件?"++# 可视化知识图谱+he show ./output/+```++## 核心命令++| 命令 | 用途 |+|------|------|+| `he config init` | 配置 API Key |+| `he parse` | 提取知识 |+| `he search` | 查询知识库 |+| `he show` | 可视化图谱 |+| `he feed` | 增量补充 |+| `he list` | 列出模板 |++## 配置++[→ CLI 配置指南](./config.md)++## 详细指南++[→ CLI 命令详解](./cli.md)++## 使用示例++- [金融领域模板](../templates/finance.md)+- [法律领域模板](../templates/legal.md)+- [医学领域模板](../templates/medicine.md)diff --git a/docs/zh/concepts/auto-types.md b/docs/zh/concepts/auto-types.mdindex a34d227..0386196 100644--- a/docs/zh/concepts/auto-types.md+++ b/docs/zh/concepts/auto-types.md@@ -1,129 +1,91 @@-# 自动类型 (AutoTypes)+# AutoTypes-Hyper-Extract 使用自动类型来确定提取模式,共支持 8 种类型。+AutoTypes 定义了知识提取的**输出数据结构**。共有 8 种类型:-## 类型概览+## 记录型-| 类型 | 说明 | 使用场景 |-|------|------|---------|-| `model` | 单个结构化对象 | 提取单一记录 |-| `list` | 有序列表 | 提取排序项目 |-| `set` | 去重集合 | 提取唯一实体 |-| `graph` | 二元关系图 | 提取实体关系 |-| `hypergraph` | 多元关系图 | 提取多方关系 |-| `temporal_graph` | 时序图 | 添加时间维度 |-| `spatial_graph` | 空间图 | 添加空间维度 |-| `spatio_temporal_graph` | 时空图 | 添加时间和空间 |+### AutoModel-## 选择决策树+使用 Pydantic 模型提取结构化数据。-```-需要关系?-├─ 否 → 记录类型-│ ├─ 单个对象 → model-│ ├─ 有序列表 → list-│ └─ 去重集合 → set-└─ 是 → 图类型- ├─ 二元关系 (A→B) → graph- └─ 多元关系 (A+B+C→D) → hypergraph--+ 时间维度 → temporal_graph-+ 空间维度 → spatial_graph-+ 两者都有 → spatio_temporal_graph-```+```python+from pydantic import BaseModel, Field+from hyperextract import AutoModel++class Summary(BaseModel):+ title: str = Field(description="标题")+ summary: str = Field(description="摘要")-## 详细说明+model = AutoModel(data_schema=Summary, llm_client=llm)+```-### Model+### AutoList-用于提取单个结构化对象。+提取列表项。```python-from hyperextract import Template--ka = Template.create("finance/earnings_summary", "zh")-result = ka.parse(text)+from hyperextract.types import AutoList-print(result.fields["company_name"])-print(result.fields["revenue"])+lst = AutoList[str](item_schema=str, llm_client=llm)+lst.feed_text(text)```-### List+### AutoSet-用于提取有序列表。+提取唯一项(去重)。```python-from hyperextract import Template+from hyperextract.types import AutoSet-ka = Template.create("finance/risk_factor_set", "zh")-result = ka.parse(text)--for item in result.fields:- print(item)+s = AutoSet[str](item_schema=str, llm_client=llm)+s.feed_text(text)```-### Set+## 图谱型-用于提取去重集合。+### AutoGraph-```python-from hyperextract import Template+实体-关系提取。-ka = Template.create("general/entity_registry", "zh")-result = ka.parse(text)+```python+from hyperextract.types import AutoGraph-for entity in result.fields:- print(entity)+graph = AutoGraph(node_schema=Entity, edge_schema=Relation, llm_client=llm)+graph.feed_text(text)```-### Graph+### AutoHypergraph-用于提取二元关系。+多元关系(n 元关系)。```python-from hyperextract import Template+from hyperextract.types import AutoHypergraph+```-ka = Template.create("finance/ownership_graph", "zh")-result = ka.parse(text)+### AutoTemporalGraph-for entity in result.entities:- print(f"{entity['name']} ({entity['type']})")+时间相关的关嗧。-for relation in result.relations:- print(f"{relation['source']} --[{relation['type']}]--> {relation['target']}")+```python+from hyperextract.types import AutoTemporalGraph```-### Hypergraph+### AutoSpatialGraph-用于提取多元关系。+位置相关的关嗧。```python-from hyperextract import Template--ka = Template.create("tcm/formula_composition", "zh")-result = ka.parse(text)--for relation in result.relations:- print(f"Formula: {relation['formula_name']}")- print(f"Herbs: {relation['herbs']}")+from hyperextract.types import AutoSpatialGraph```-### Temporal Graph+### AutoSpatioTemporalGraph-用于提取带时间的关系。+时间和位置同时相关的关嗧。```python-from hyperextract import Template--ka = Template.create("finance/event_timeline", "zh")-result = ka.parse(text)--for relation in result.relations:- print(f"{relation['source']} --[{relation['type']}]--> {relation['target']} @ {relation['time']}")+from hyperextract.types import AutoSpatioTemporalGraph```-## 下一步+## 快速链接-- 了解 [模板](./templates.md)-- 查看 [预设模板](./templates.md)-- 浏览 [领域模板](../guides/domain-templates/index.md)+- [领域模板](../templates/index.md) - 开箱即用的模板diff --git a/docs/zh/concepts/index.md b/docs/zh/concepts/index.mdindex 64a079a..bf4b6b7 100644--- a/docs/zh/concepts/index.md+++ b/docs/zh/concepts/index.md@@ -1,52 +1,18 @@-# 核心概念+# Concepts-## 概述+Hyper-Extract 采用**三层架构**:-Hyper-Extract 是一个知识提取框架,可从各种文档中提取结构化知识。本文档介绍核心概念,帮助您理解系统的工作原理。+- **Auto-Types** 定义了知识提取的数据结构+- **Methods** 基于 Auto-Types 提供提取算法+- **Templates** 提供领域特定的配置,包含开箱即用的 prompt-## 核心概念+## Auto-Types-### 模板 (Template)+Auto-Types 是基础层 - 它们定义了知识提取的输出数据结构。-模板使用 YAML 定义要提取的内容,提供声明式的方式来指定提取模式,无需编写代码。+[→ 了解更多 Auto-Types](./auto-types.md)-详细了解:[模板](./templates.md)+## 快速链接-### 自动类型 (AutoType)--Hyper-Extract 支持 8 种自动类型,每种类型针对不同的提取场景:--| 类型 | 说明 | 使用场景 |-|------|------|---------|-| `model` | 单个结构化对象 | 提取单一记录 |-| `list` | 有序列表 | 提取排序项目 |-| `set` | 去重集合 | 提取唯一实体 |-| `graph` | 二元关系图 | 提取实体关系 |-| `hypergraph` | 多元关系图 | 提取多方关系 |-| `temporal_graph` | 时序图 | 添加时间维度 |-| `spatial_graph` | 空间图 | 添加空间维度 |-| `spatio_temporal_graph` | 时空图 | 添加时间和空间 |--详细了解:[自动类型](./auto-types.md)--### 提取方法 (Methods)--Hyper-Extract 支持多种提取方法:--- **本地模型**:使用本地部署的模型-- **API 模型**:使用云端 API(如 OpenAI、Claude)-- **混合模式**:结合多种方法--详细了解:[提取方法](./methods.md)--## 快速开始--1. [安装](../getting-started/installation.md)-2. [快速教程](../getting-started/quickstart.md)-3. [模板设计](./templates.md)--## 下一步--- 浏览 [模板库](../reference/template-gallery.md)-- 查看 [领域模板](../guides/domain-templates/index.md)-- 了解 [Python API](../guides/python-api.md)+- [Auto-Types](./auto-types.md) - 8 种强类型的知识结构+- [Templates](../templates/index.md) - 开箱即用的模板diff --git a/docs/zh/concepts/methods.md b/docs/zh/concepts/methods.mddeleted file mode 100644index 4720082..0000000--- a/docs/zh/concepts/methods.md+++ /dev/null@@ -1,123 +0,0 @@-# 提取方法--Hyper-Extract 提供多种提取方法,每种都针对不同的用例进行了优化。--## 可用方法--### 基本方法--| 方法 | 描述 | 用例 |-|------|------|------|-| atom | 直接提取 | 简单、直接的提取 |-| kg_gen | 知识图谱生成 | 结构化知识提取 |--### 基于 RAG 的方法--| 方法 | 描述 | 用例 |-|------|------|------|-| graph_rag | 基于图的 RAG | 复杂关系提取 |-| light_rag | 轻量级 RAG | 快速、高效提取 |-| hyper_rag | 超图 RAG | 多实体关系 |-| hypergraph_rag | 高级超图 | 复杂网络分析 |-| cog_rag | 认知 RAG | 基于推理的提取 |--### 专业化方法--| 方法 | 描述 | 用例 |-|------|------|------|-| itext2kg | 文本转知识图谱 | 文档转换 |-| itext2kg_star | 增强文本转知识图谱 | 高级文档处理 |--## 方法比较--### 速度--```-快速: atom > light_rag > kg_gen > graph_rag-慢速: hyper_rag > cog_rag > hypergraph_rag-```--### 准确性--```-高: cog_rag > graph_rag > hypergraph_rag > hyper_rag-中等: kg_gen > itext2kg > light_rag > atom-```--### 用例矩阵--| 任务 | 推荐方法 |-|------|----------|-| 简单提取 | atom |-| 快速原型 | light_rag |-| 知识图谱 | graph_rag |-| 复杂关系 | hyper_rag |-| 推理任务 | cog_rag |-| 文档转换 | itext2kg |--## 使用示例--### 使用 atom 方法--```python-from hyperextract.methods import atom--result = atom.extract(text, schema=MySchema)-```--### 使用 graph_rag 方法--```python-from hyperextract.methods import graph_rag--result = graph_rag.extract(- text,- node_types=["Person", "Organization"],- edge_types=["WORKS_AT", "KNOWS"]-)-```--### 使用 cog_rag 方法--```python-from hyperextract.methods import cog_rag--result = cog_rag.extract(- text,- task="提取因果关系"-)-```--## 方法选择指南--### 快速决策树--```-任务是否简单?-├── 是 → 使用 atom-└── 否 → 是否需要推理?- ├── 是 → 使用 cog_rag- └── 否 → 是否需要图?- ├── 是 → graph_rag 或 hyper_rag- └── 否 → 使用 light_rag-```--## 高级配置--每种方法都支持自定义配置:--```python-result = graph_rag.extract(- text,- max_nodes=100,- max_edges=200,- temperature=0.0,- confidence_threshold=0.8-)-```--## 下一步--- 探索 [模板](templates.md)-- 查看 [CLI 参考](../reference/cli-reference.md)-- 浏览 [示例](../guides/index.md)diff --git a/docs/zh/concepts/templates.md b/docs/zh/concepts/templates.mddeleted file mode 100644index 5eeed5e..0000000--- a/docs/zh/concepts/templates.md+++ /dev/null@@ -1,593 +0,0 @@-# 模板--模板使用声明式 YAML 定义要提取的内容,提供了一种强大的方式来指定提取模式,无需编写代码。--## 类型选择----在设计模板之前,先确定哪种类型适合您的需求:--```-需要关系?-├─ 否 → 记录类型 (model, list, set)-└─ 是 → 图类型 (graph, hypergraph, temporal_graph, spatial_graph)--记录类型:直接字段提取,没有实体和关系的概念-图类型:提取实体及其关系-```--| 类型 | 说明 | 使用场景 |-|------|------|---------|-| `model` | 单个结构化对象 | 提取一条记录 |-| `list` | 有序数组 | 提取排序项目 |-| `set` | 去重集合 | 提取唯一实体 |-| `graph` | 二元关系 (A→B) | 提取实体关系 |-| `hypergraph` | 多元关系 | 提取多方事件 |-| `temporal_graph` | + 时间维度 | 提取随时间变化的事件 |-| `spatial_graph` | + 空间维度 | 提取特定地点的事件 |-| `spatio_temporal_graph` | + 时间 + 空间 | 提取特定地点随时间变化的事件 |-------## 记录类型--记录类型使用 `output.fields` 直接定义数据结构,没有实体和关系。--### 通用结构--```yaml-language: zh--name: 模板名称-type: [model/list/set]-tags: [领域]--description: '模板描述。'--output:- fields:- - name: 字段名- type: str- description: '字段描述。'- required: false- default: '默认值'--guideline:- target: '提取目标描述。'- rules:- - '规则 1'- - '规则 2'--display:- label: '{字段名}'-```--### model - 单个对象--提取单个结构化记录。--```yaml-language: zh--name: 财报摘要-type: model-tags: [finance]--description: '从财报中提取关键财务指标。'--output:- fields:- - name: company_name- type: str- description: '公司名称。'- - name: revenue- type: str- description: '收入金额。'- - name: quarter- type: str- description: '季度。'--guideline:- target: '提取关键财务信息。'- rules:- - '提取公司名称和财务数据'- - '使用原文中的数字'--display:- label: '{company_name}'-```--### list - 有序数组--提取有序项目(排名、序列、要点列表)。--```yaml-language: zh--name: 风险因素列表-type: list-tags: [finance]--description: '按顺序提取风险因素。'--output:- fields:- - name: category- type: str- description: '风险类别。'- - name: description- type: str- description: '风险描述。'--guideline:- target: '提取风险因素。'- rules:- - '提取所有风险因素'- - '保持出现顺序'--display:- label: '{category}'-```--### set - 去重集合--提取具有自动去重的唯一实体。--```yaml-language: zh--name: 人物集合-type: set-tags: [general]--description: '提取唯一的人物实体。'--output:- fields:- - name: name- type: str- description: '人物姓名。'- - name: role- type: str- description: '角色或职位。'- required: false--guideline:- target: '提取人物实体。'- rules:- - '提取所有唯一的人物'- - '按姓名去重'--identifiers:- item_id: name--display:- label: '{name}'-```--**注意**:Set 类型需要 `identifiers.item_id` 来定义去重键。-------## 图类型--图类型提取实体及其关系。使用 `output.entities` 和 `output.relations`。--### 通用结构--```yaml-language: zh--name: 模板名称-type: [graph/hypergraph/temporal_graph/spatial_graph]-tags: [领域]--description: '模板描述。'--output:- entities:- description: '实体描述。'- fields:- - name: name- type: str- description: '实体名称。'- - name: type- type: str- description: '实体类型。'- relations:- description: '关系描述。'- fields:- - name: source- type: str- - name: target- type: str- - name: type- type: str--guideline:- target: '提取目标描述。'- rules_for_entities:- - '规则 1'- rules_for_relations:- - '规则 2'--identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}'- relation_members:- source: source- target: target--display:- entity_label: '{name} ({type})'- relation_label: '{type}'-```--### graph - 二元关系--提取两个实体之间的关系 (A→B)。--```yaml-language: zh--name: 所有权图谱-type: graph-tags: [finance]--description: '提取所有权关系。'--output:- entities:- fields:- - name: name- type: str- description: '实体名称。'- - name: type- type: str- description: '实体类型(公司/个人)。'- relations:- fields:- - name: source- type: str- description: '所有者。'- - name: target- type: str- description: '被拥有的实体。'- - name: type- type: str- description: '关系类型。'--guideline:- target: '提取所有权关系。'- rules_for_entities:- - '提取公司和个人'- - '保持命名一致'- rules_for_relations:- - '仅在文本明确表达时创建关系'--identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}'- relation_members:- source: source- target: target--display:- entity_label: '{name} ({type})'- relation_label: '{type}'-```--### hypergraph - 多元关系--提取涉及多个参与者的关系。--#### 简单超图(扁平列表)--所有参与者角色相同。--```yaml-language: zh--name: 会议超图-type: hypergraph-tags: [general]--output:- entities:- fields:- - name: name- type: str- relations:- fields:- - name: topic- type: str- description: '会议主题。'- - name: participants- type: list- description: '参与者列表。'- - name: outcome- type: str- description: '会议结论。'- required: false--identifiers:- entity_id: name- relation_id: '{topic}'- relation_members: participants # 字符串--display:- entity_label: '{name}'- relation_label: '{topic}'-```--#### 嵌套超图(语义分组)--参与者具有不同的语义角色。--```yaml-language: zh--name: 战役分析-type: hypergraph-tags: [history]--output:- entities:- fields:- - name: name- type: str- relations:- fields:- - name: battle_name- type: str- - name: attackers- type: list- description: '攻击方。'- - name: defenders- type: list- description: '防守方。'- - name: outcome- type: str--identifiers:- entity_id: name- relation_id: '{battle_name}'- relation_members: [attackers, defenders] # 列表--display:- entity_label: '{name}'- relation_label: '{battle_name}'-```--### temporal_graph - 时间维度--为图关系添加时间维度。--```yaml-language: zh--name: 事件时序图-type: temporal_graph-tags: [general]--output:- entities:- fields:- - name: name- type: str- description: '事件名称。'- - name: type- type: str- description: '事件类型。'- relations:- fields:- - name: source- type: str- - name: target- type: str- - name: type- type: str- - name: time- type: str- description: '关系发生的时间。'- required: false--guideline:- target: '提取事件和时间关系。'- rules_for_entities:- - '提取关键事件'- rules_for_relations:- - '提取时间关系'- rules_for_time:- - '记录事件发生的时间'--identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}|{time}'- relation_members:- source: source- target: target- time_field: time--display:- entity_label: '{name} ({type})'- relation_label: '{type}@{time}'-```--### spatial_graph - 空间维度--为图关系添加位置维度。--```yaml-language: zh--name: 空间图谱-type: spatial_graph-tags: [general]--output:- entities:- fields:- - name: name- type: str- - name: type- type: str- relations:- fields:- - name: source- type: str- - name: target- type: str- - name: type- type: str- - name: location- type: str- description: '关系发生的地点。'- required: false--identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}|{location}'- relation_members:- source: source- target: target- location_field: location--display:- entity_label: '{name} ({type})'- relation_label: '{type}@{location}'-```--### spatio_temporal_graph - 时间和空间--结合时间和空间维度。--```yaml-identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}|{location}|{time}'- relation_members:- source: source- target: target- time_field: time- location_field: location--display:- entity_label: '{name} ({type})'- relation_label: '{type}@{location}({time})'-```-------## 字段类型--| 类型 | 说明 | 示例 |-|------|------|------|-| `str` | 字符串 | "你好世界" |-| `int` | 整数 | 42 |-| `float` | 浮点数 | 3.14 |-| `bool` | 布尔值 | true |-| `list` | 列表 | ["a", "b", "c"] |-------## 显示配置--| 类型 | entity_label | relation_label |-|------|--------------|----------------|-| graph | `{name} ({type})` | `{type}` |-| hypergraph | `{name}` | `{event_name}` |-| temporal_graph | `{name} ({type})` | `{type}@{time}` |-| spatial_graph | `{name} ({type})` | `{type}@{location}` |-| spatio_temporal_graph | `{name} ({type})` | `{type}@{location}({time})` |-------## Schema 与 Guideline 的区别--| Schema 定义(WHAT) | Guideline 定义(HOW TO DO WELL) |-|---------------------|--------------------------------|-| 字段名 | 提取策略 |-| 字段类型 | 质量要求 |-| 字段描述 | 创建条件 |-| 必需/可选 | 避免常见错误 |--**重要**:Guideline 不应重复 schema 定义。-------## 预设模板--Hyper-Extract 包含 6 个领域 80+ 预设模板:--### 金融-- `finance/earnings_summary` (model)-- `finance/risk_factor_set` (set)-- `finance/ownership_graph` (graph)-- `finance/event_timeline` (temporal_graph)--### 法律-- `legal/case_fact_timeline` (temporal_graph)-- `legal/case_citation` (graph)-- `legal/contract_obligation` (list)--### 医学-- `medicine/drug_interaction` (graph)-- `medicine/treatment_map` (temporal_graph)-- `medicine/discharge_instruction` (list)--### 中医-- `tcm/herb_property` (model)-- `tcm/formula_composition` (list)-- `tcm/meridian_graph` (graph)--### 工业-- `industry/safety_control` (list)-- `industry/equipment_topology` (graph)-- `industry/failure_case` (temporal_graph)--### 通用-- `general/graph` (graph)-- `general/list` (list)-- `general/model` (model)-- `general/set` (set)-- `general/biography_graph` (spatio_temporal_graph)-------## 使用模板--### CLI--```bash-# 使用预设模板-he parse document.txt -t finance/ownership_graph -o output/--# 使用自定义模板-he parse document.txt -t template.yaml -o output/-```--### Python API--```python-from hyperextract import Template--# 加载预设模板-ka = Template.create("finance/ownership_graph", "zh")--# 从 YAML 加载-ka = Template.create("template.yaml", "zh")--# 解析文档-result = ka.parse(document_text)-```-------## 下一步--- 浏览[模板库](../../reference/template-gallery.md)-- 了解[领域模板](../guides/domain-templates/index.md)-- 创建您自己的模板-- 查看[设计指南](https://github.com/hyper-extract/hyper-extract/blob/main/hyperextract/templates/DESIGN_GUIDE_zh.md)diff --git a/docs/zh/getting-started/configuration.md b/docs/zh/getting-started/configuration.mddeleted file mode 100644index bdcc0d8..0000000--- a/docs/zh/getting-started/configuration.md+++ /dev/null@@ -1,60 +0,0 @@-# 配置--Hyper-Extract 使用 TOML 配置文件。默认位置:`~/.he/config.toml`--## 快速配置--```bash-# 使用 API 密钥初始化(推荐)-he config init -k YOUR_API_KEY--# 或者分别配置 LLM 和 Embedder-he config llm --api-key YOUR_API_KEY-he config embedder --api-key YOUR_API_KEY-```--## 配置选项--### LLM 设置--```bash-he config llm --api-key YOUR_KEY --model gpt-4o-mini-```--| 选项 | 说明 | 默认值 |-|------|------|---------|-| `--api-key`, `-k` | LLM API 密钥 | 必需 |-| `--model`, `-m` | 模型名称 | gpt-4o-mini |-| `--base-url`, `-u` | 自定义 API 基础 URL | (默认) |--### Embedder 设置--```bash-he config embedder --api-key <your-api-key> --model text-embedding-3-small-```--| 选项 | 说明 | 默认值 |-|------|------|---------|-| `--api-key`, `-k` | Embedder API 密钥 | 必需 |-| `--model`, `-m` | 模型名称 | text-embedding-3-small |-| `--base-url`, `-u` | 自定义 API 基础 URL | (默认) |--## 查看配置--```bash-he config show-```--## 命令--| 命令 | 说明 |-|------|------|-| `he config init -k KEY` | 使用 API 密钥初始化 LLM 和 Embedder |-| `he config llm` | 配置 LLM 设置 |-| `he config embedder` | 配置 Embedder 设置 |-| `he config show` | 显示当前配置 |--## 下一步--- 了解[模板](../concepts/templates.md)-- 浏览[预设模板](../concepts/templates.md#preset-templates)diff --git a/docs/zh/getting-started/index.md b/docs/zh/getting-started/index.mddeleted file mode 100644index d8cd8d3..0000000--- a/docs/zh/getting-started/index.md+++ /dev/null@@ -1,37 +0,0 @@-# 快速开始--欢迎使用 Hyper-Extract!本节将帮助您快速上手。--## 本节内容--- [安装](installation.md) - 如何安装 Hyper-Extract-- [快速教程](quickstart.md) - 运行您的第一次提取-- [配置](configuration.md) - 配置 API 密钥和设置--## 前置要求--使用 Hyper-Extract 之前,您需要:--- Python 3.9 或更高版本-- OpenAI API 密钥(或兼容的 LLM API)-- 基本的 Python 知识--## 选择您的路径--### CLI 用户--如果您更喜欢命令行工具,请查看我们的 [CLI 指南](../guides/cli.md) 获取详细的命令文档。--### Python 开发者--如果您正在使用 Python 构建应用程序,请查看我们的 [Python API 指南](../guides/python-api.md)。--### 模板设计师--如果您想创建自定义提取模板,请查看我们的 [模板设计指南](../concepts/templates.md)。--## 下一步--1. [安装 Hyper-Extract](installation.md)-2. 尝试[快速教程](quickstart.md)-3. 探索[核心概念](../concepts/index.md)diff --git a/docs/zh/getting-started/installation.md b/docs/zh/getting-started/installation.mddeleted file mode 100644index d61a91b..0000000--- a/docs/zh/getting-started/installation.md+++ /dev/null@@ -1,24 +0,0 @@-# 安装--## 系统要求--- Python 3.11+--## 安装方法--### 使用 uv(推荐)--```bash-uv pip install hyper-extract-```--### 使用 pip--```bash-pip install hyper-extract-```--## 下一步--- [快速教程](getting-started/quickstart.md) - 运行您的第一次提取-- [配置](getting-started/configuration.md) - 配置 API 设置diff --git a/docs/zh/getting-started/quickstart.md b/docs/zh/getting-started/quickstart.mddeleted file mode 100644index 338dfa7..0000000--- a/docs/zh/getting-started/quickstart.md+++ /dev/null@@ -1,110 +0,0 @@-# 快速教程--本教程将引导您在 5 分钟内完成从文档中提取知识。--## 第一步:准备文档--从一个简单的文本文档开始。创建名为 `document.txt` 的文件:--```text-Apple Inc. 报告 2024 年第一季度创纪录的季度收入 1239 亿美元。-CEO Tim Cook 宣布公司实现了史上最强的 iPhone 销量。-董事会宣布每股 0.24 美元的现金股息。-服务业务收入达到历史新高的 223 亿美元。-```--## 第二步:创建提取模板--Hyper-Extract 使用 YAML 模板来定义要提取的内容。创建 `template.yaml`:--```yaml-language: zh--name: 公司新闻摘要-type: graph-tags: [finance]--description: '从新闻文章中提取关键财务事件和实体关系。'--output:- entities:- fields:- - name: name- type: str- description: '实体名称'- - name: type- type: str- description: '实体类型(公司/人物/事件/金额)'- relations:- fields:- - name: source- type: str- description: '源实体'- - name: target- type: str- description: '目标实体'- - name: type- type: str- description: '关系类型'--guideline:- target: '从新闻中提取实体和关系。'- rules_for_entities:- - '提取公司、人物、金额等实体'- - '保持命名一致'- rules_for_relations:- - '仅在文本明确表达时创建关系'--identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}'- relation_members:- source: source- target: target--display:- entity_label: '{name} ({type})'- relation_label: '{type}'-```--## 第三步:提取知识(CLI)----```bash-he parse document.txt -o output/ -t template.yaml-```--## 第四步:提取知识(Python API)--```python-from hyperextract import Template--# 从 YAML 创建模板-ka = Template.create("template.yaml", "zh")--# 解析文档-result = ka.parse("Apple Inc. 报告创纪录的季度收入...")--# 访问结果-print(result.entities)-print(result.relations)-```--## 第五步:查看结果--提取的知识将保存在您的输出目录中。您可以使用搜索命令:--```bash-he search output/ "有哪些财务事件?"-```--**AutoGraph 可视化示例:**----## 下一步--- 了解 [8 种自动类型](../concepts/auto-types.md)-- 探索 [提取方法](../concepts/methods.md)-- 浏览 [预设模板](../concepts/templates.md)diff --git a/docs/zh/guides/domain-templates/index.md b/docs/zh/guides/domain-templates/index.mddeleted file mode 100644index d9a7f18..0000000--- a/docs/zh/guides/domain-templates/index.md+++ /dev/null@@ -1,27 +0,0 @@-# 领域模板--Hyper-Extract 为各行业和用例提供专用模板。--## 可用领域--- [金融](finance.md) - 金融文档提取-- [法律](legal.md) - 法律文档提取-- [医学](medicine.md) - 医疗文档提取-- [中医](tcm.md) - 中医模板--## 快速开始--### 使用领域模板--```bash-# CLI-he parse document.txt -t finance/earnings_summary--# Python API-ka = Template.create("finance/earnings_summary")-result = ka.parse(document_text)-```--## 创建自定义领域模板--请参阅[模板设计指南](../../concepts/templates.md)了解如何创建您自己的领域特定模板。diff --git a/docs/zh/guides/index.md b/docs/zh/guides/index.mddeleted file mode 100644index e798c43..0000000--- a/docs/zh/guides/index.md+++ /dev/null@@ -1,34 +0,0 @@-# 使用指南--本节提供 Hyper-Extract 的逐步教程和操作指南。--## 本节内容--- [CLI 指南](cli.md) - 命令行界面文档-- [Python API](python-api.md) - Python API 使用指南-- [领域模板](domain-templates/index.md) - 特定领域的模板--## 热门指南--### CLI 入门--学习如何使用命令行界面进行快速提取任务。--### Python API 教程--通过详细示例使用 Python API 构建应用程序。--### 领域特定模板--使用金融、法律、医学等的预构建模板。--## 快速链接--- [金融模板](domain-templates/finance.md) - 金融文档提取-- [法律模板](domain-templates/legal.md) - 法律文档提取-- [医学模板](domain-templates/medicine.md) - 医疗文档提取-- [中医模板](domain-templates/tcm.md) - 中医模板--## 示例学习--查看我们的[示例代码库](https://github.com/hyper-extract/hyper-extract/tree/main/examples)获取完整的工作示例。diff --git a/docs/zh/guides/python-api.md b/docs/zh/guides/python-api.mddeleted file mode 100644index 4cf54d6..0000000--- a/docs/zh/guides/python-api.md+++ /dev/null@@ -1,167 +0,0 @@-# Python API--Hyper-Extract 提供 Python API 用于程序化提取。--## 安装--```bash-pip install hyperextract-```--## 基础用法--### 加载预设模板--```python-from hyperextract import Template--# 加载预设模板-ka = Template.create("general/graph", "zh")--# 解析文档-result = ka.parse(document_text)--# 访问结果-print(result.entities)-print(result.relations)-```--### 加载自定义模板--```python-from hyperextract import Template--# 从 YAML 文件加载-ka = Template.create("template.yaml", "zh")--# 从字符串加载-yaml_content = """-language: zh-name: 自定义模板-type: graph-tags: [custom]-description: '...'-output:- entities:- fields:- - name: name- type: str- description: '名称'- relations:- fields:- - name: source- type: str- description: '源'- - name: target- type: str- description: '目标'- - name: type- type: str- description: '类型'-guideline:- target: '...'-identifiers:- entity_id: name- relation_id: '{source}|{type}|{target}'- relation_members:- source: source- target: target-"""--ka = Template.create(yaml_content, "zh")-```--### 批量处理--```python-from hyperextract import Template--ka = Template.create("general/graph", "zh")--documents = ["文档1内容...", "文档2内容...", "文档3内容..."]--results = []-for doc in documents:- result = ka.parse(doc)- results.append(result)-```--### 结果导出--```python-from hyperextract import Template--ka = Template.create("general/graph", "zh")-result = ka.parse(document_text)--# 导出为 JSON-json_output = result.to_json()--# 导出为 Dict-dict_output = result.to_dict()--# 导出为三元组-triples = result.to_triples()-```--## 模板创建--### 创建新模板--```python-from hyperextract import Template--template = Template.create("template.yaml", "zh")-```--### 保存模板--```python-from hyperextract import Template--ka = Template.create("general/graph", "zh")-ka.save("my_template.yaml")-```--## 配置选项--### 设置语言--```python-from hyperextract import Template--# 单语言-ka = Template.create("general/graph", "zh")--# 多语言-ka = Template.create("general/graph", ["zh", "en"])-```--### 设置模型--```python-from hyperextract import Template--# 使用指定模型-ka = Template.create("general/graph", "zh", model="gpt-4")--# 使用本地模型-ka = Template.create("general/graph", "zh", model="local-model")-```--## 错误处理--```python-from hyperextract import Template--try:- ka = Template.create("template.yaml", "zh")- result = ka.parse(document_text)-except Exception as e:- print(f"提取失败: {e}")-```--## 下一步--- 浏览 [预设模板](../concepts/templates.md)-- 查看 [领域模板](./domain-templates/index.md)diff --git a/docs/zh/index.md b/docs/zh/index.mdindex 8cdaaaa..c2f71e7 100644--- a/docs/zh/index.md+++ b/docs/zh/index.md@@ -1,10 +1,11 @@-# Hyper-Extract+# 🚀 Hyper-Extract-> **"告别文档焦虑,让信息一目了然"**+> *"告别文档焦虑,让信息一目了然"*+> **"Stop reading. Start understanding."**-**一行命令,将文档转化为结构化知识摘要。**+**智能知识提取 CLI — 一条命令,将文档转化为结构化知识。**-+[](https://python.org)[](LICENSE)@@ -14,14 +15,14 @@Hyper-Extract 是一个智能的、基于 LLM 的知识提取与演化框架。它极大地简化了将高度非结构化文本转换为持久化、可预测、强类型知识摘要的过程。它能够轻松地将信息提取为多种格式——从简单的**集合**(列表/集合)和 **Pydantic 模型**,到复杂的**知识图谱**、**超图**,甚至**时空图**。-## 核心特性+## ✨ 核心特性- 🔷 **8 种自动类型:** 从基础的 `AutoModel`/`AutoList` 到高级的 `AutoGraph`、`AutoHypergraph` 和 `AutoSpatioTemporalGraph`。- 🧠 **10+ 提取引擎:** 开箱即用的前沿检索范式支持,如 `GraphRAG`、`LightRAG`、`Hyper-RAG` 和 `KG-Gen`。- 📝 **声明式 YAML 模板:** 零代码提取定义。包含 6 个领域 80+ 预设模板。- 🔄 **增量演化:** 动态输入新文档,持续扩展和更新提取的知识。-## 快速开始+## ⚡ 快速开始### 安装@@ -32,29 +33,85 @@ uv pip install hyper-extract### 命令行方式```bash-he config init -k <your-api-key>-he parse sample.md -t general/biography_graph -o ./output/ -l zh-he search ./output/ "关键事件有哪些?"-he feed ./output/ another_sample.md+# 配置 OpenAI API Key+he config init -k YOUR_OPENAI_API_KEY++# 提取知识+he parse examples/en/tesla.md -t general/biography_graph -o ./output/ -l en++# 查询知识库+he search ./output/ "Tesla 的主要成就有哪些?"++# 可视化知识图谱+he show ./output/++# 增量补充知识+he feed ./output/ examples/en/tesla_question.md++# 查看更新后的知识图谱+he show ./output/```### Python API 方式+#### 安装++```bash+# 克隆仓库+git clone https://github.com/yifanfeng97/hyper-extract.git+cd hyper-extract++# 安装依赖+uv sync+```++#### 配置++```bash+# 复制环境变量示例文件+cp .env.example .env++# 编辑 .env 文件配置 API Key 和 Base URL+# OPENAI_API_KEY=your-api-key+# OPENAI_BASE_URL=https://api.openai.com/v1+```++#### 使用+```python+import os+from dotenv import load_dotenv++# 从 .env 文件加载环境变量+load_dotenv()+from hyperextract import Template+# 创建模板ka = Template.create("general/biography_graph")++# 解析文档+with open("examples/en/tesla.md", "r") as f:+ text = f.read()result = ka.parse(text)++# 可视化知识图谱+ka.show(result)++# 增量补充知识+with open("examples/en/tesla_question.md", "r") as f:+ new_text = f.read()+ka.feed(result, new_text)++# 查看更新后的知识图谱+ka.show(result)```-## 文档+## 🧩 8 种自动类型-- [快速开始](getting-started/index.md) - 快速上手-- [核心概念](concepts/index.md) - 理解核心概念-- [使用指南](guides/index.md) - 逐步教程-- [参考文档](reference/index.md) - API 和配置参考+我们的框架化繁为简,让您无需编写样板代码。-## 8 种自动类型+| 类型 | 描述 ||------|------|@@ -69,16 +126,42 @@ result = ka.parse(text)### 示例:AutoGraph 可视化-使用 `AutoGraph` 提取后,您可以可视化知识图谱:+使用 `AutoGraph` 提取后的知识图谱可视化:-## 架构+## 🛠️ 系统架构++Hyper-Extract 采用**三层架构**:++- **Auto-Types** 定义了知识提取的数据结构。8 种强类型结构(AutoModel、AutoList、AutoSet、AutoGraph、AutoHypergraph、AutoTemporalGraph、AutoSpatialGraph、AutoSpatioTemporalGraph)作为所有提取的输出格式。++- **Methods** 基于 Auto-Types 提供提取算法。包括典型方法(KG-Gen、iText2KG、iText2KG*)和 RAG 增强方法(GraphRAG、LightRAG、Hyper-RAG、HypergraphRAG、Cog-RAG)。++- **Templates** 提供领域特定的配置,包含开箱即用的 prompt 和数据结构。覆盖 6 大领域(金融、法律、医疗、中医、工业、通用),提供 80+ 预设模板,用户无需了解底层 Auto-Types 和 Methods 即可直接使用。++可通过 **CLI**(`he parse`、`he search`、`he show`...)或 **Python API**(`Template.create()`)使用。++++## 📈 与其他库对比++| 特性 | GraphRAG | LightRAG | KG-Gen | ATOM | **Hyper-Extract** |+|------|:--------:|:--------:|:------:|:----:|:-----------------:|+| 知识图谱 | ✅ | ✅ | ✅ | ✅ | ✅ |+| 时序图谱 | ✅ | ❌ | ❌ | ✅ | ✅ |+| 空间图谱 | ❌ | ❌ | ❌ | ❌ | ✅ |+| 超图 | ❌ | ❌ | ❌ | ❌ | ✅ |+| 领域模板 | ❌ | ❌ | ❌ | ❌ | ✅ |+| CLI 工具 | ✅ | ❌ | ❌ | ❌ | ✅ |+| 多语言 | ✅ | ❌ | ❌ | ❌ | ✅ |-+## 📚 文档-系统构建在稳固的三元组上:**自动类型**(多类型结构)、**方法**(执行策略)和**模板**(声明式模式)。+- [快速开始](cli/index.md) - 快速上手+- [领域模板](templates/index.md) - 开箱即用的模板-## 许可证+## 🤝 贡献与许可+欢迎贡献!请提交 Issues 和 PRs。基于 **Apache-2.0** 许可证。diff --git a/docs/zh/python/config.md b/docs/zh/python/config.mdnew file mode 100644index 0000000..61a792b--- /dev/null+++ b/docs/zh/python/config.md@@ -0,0 +1,74 @@+# Python SDK 配置++## 环境变量++在项目根目录创建 `.env` 文件:++```bash+# 复制示例 env 文件+cp .env.example .env+```++编辑 `.env` 文件:++```bash+OPENAI_API_KEY=your-api-key+OPENAI_BASE_URL=https://api.openai.com/v1+```++## 加载环境变量++使用 `python-dotenv` 加载环境变量:++```bash+pip install python-dotenv+```++```python+from dotenv import load_dotenv++# 从 .env 文件加载环境变量+load_dotenv()+```++## 程序化配置++你也可以通过代码设置环境变量:++```python+import os++os.environ["OPENAI_API_KEY"] = "your-api-key"+os.environ["OPENAI_BASE_URL"] = "https://api.openai.com/v1"+```++## 配置选项++### LLM 选项++| 选项 | 环境变量 | 默认值 |+|------|---------|--------|+| API Key | `OPENAI_API_KEY` | 必填 |+| Base URL | `OPENAI_BASE_URL` | OpenAI 默认 |+| Model | `LLM_MODEL` | `gpt-4o-mini` |+| Temperature | `LLM_TEMPERATURE` | `0.0` |++### Embedder 选项++| 选项 | 环境变量 | 默认值 |+|------|---------|--------|+| Model | `EMBEDDER_MODEL` | `text-embedding-3-small` |+| Batch Size | `EMBEDDER_BATCH_SIZE` | `100` |++## 示例 .env 文件++```bash+# 必填+OPENAI_API_KEY=sk-your-api-key++# 可选+OPENAI_BASE_URL=https://api.openai.com/v1+LLM_MODEL=gpt-4o-mini+LLM_TEMPERATURE=0.0+EMBEDDER_MODEL=text-embedding-3-small+```diff --git a/docs/zh/python/index.md b/docs/zh/python/index.mdnew file mode 100644index 0000000..9bcab12--- /dev/null+++ b/docs/zh/python/index.md@@ -0,0 +1,55 @@+# Python SDK++Hyper-Extract Python API。++## 安装++```bash+pip install hyper-extract+```++## 快速开始++```python+from dotenv import load_dotenv++# 从 .env 文件加载环境变量+load_dotenv()++from hyperextract import Template++# 创建模板+ka = Template.create("general/biography_graph", "zh")++# 解析文档+with open("examples/zh/sushi.md", "r", encoding="utf-8") as f:+ text = f.read()+result = ka.parse(text)++# 访问结果+print(result.entities)+print(result.relations)+```++## 核心 API++| API | 用途 |+|-----|------|+| `Template.create()` | 创建模板实例 |+| `ka.parse()` | 解析文档 |+| `ka.feed()` | 增量补充 |+| `ka.search()` | 查询知识库 |++## 配置++[→ Python SDK 配置指南](./config.md)++## 详细指南++[→ Python API 详解](./python-api.md)++## 使用示例++- [金融领域模板](../templates/finance.md)+- [法律领域模板](../templates/legal.md)+- [医学领域模板](../templates/medicine.md)diff --git a/docs/zh/python/python-api.md b/docs/zh/python/python-api.mdnew file mode 100644index 0000000..a020491--- /dev/null+++ b/docs/zh/python/python-api.md@@ -0,0 +1,280 @@+# Python API++## 安装++```bash+pip install hyper-extract+```++## 配置++使用 dotenv 设置 API key:++```python+from dotenv import load_dotenv+load_dotenv()+```++创建 `.env` 文件:+```bash+OPENAI_API_KEY=your-api-key+```++## 快速开始++```python+from hyperextract import Template++ka = Template.create("general/biography_graph", "zh")+result = ka.parse(document_text)+```++---++## AutoTypes++AutoTypes 定义了知识提取的**输出数据结构**。共有 8 种类型:++### AutoModel - 结构化数据++使用 AutoModel 提取结构化摘要:++```python+from pydantic import BaseModel, Field+from hyperextract import AutoModel+from langchain_openai import ChatOpenAI++class BiographySummary(BaseModel):+ title: str = Field(description="传记标题")+ subject: str = Field(description="主题名称")+ summary: str = Field(description="简要摘要")++llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)++model = AutoModel(+ data_schema=BiographySummary,+ llm_client=llm,+)+model.feed_text(text)+print(model.data.title)+```++### AutoList - 列表数据++提取列表项:++```python+from hyperextract.types import AutoList++llm = ChatOpenAI(model="gpt-4o-mini")+embedder = OpenAIEmbeddings(model="text-embedding-3-small")++lst = AutoList[str](+ item_schema=str,+ llm_client=llm,+ embedder=embedder,+)+lst.feed_text(text)+print(lst.items) # 提取的列表项+```++### AutoSet - 去重集合++提取唯一项(去重):++```python+from hyperextract.types import AutoSet++s = AutoSet[str](+ item_schema=str,+ llm_client=llm,+ embedder=embedder,+)+s.feed_text(text)+print(s.items) # 去重后的列表+```++### AutoGraph - 知识图谱++提取实体和关系:++```python+from pydantic import BaseModel, Field+from hyperextract.types import AutoGraph++class Entity(BaseModel):+ name: str = Field(description="实体名称")+ type: str = Field(description="实体类型")++class Relation(BaseModel):+ source: str = Field(description="源实体")+ target: str = Field(description="目标实体")+ type: str = Field(description="关系类型")++graph = AutoGraph[Entity, Relation](+ node_schema=Entity,+ edge_schema=Relation,+ node_key_extractor=lambda x: x.name,+ edge_key_extractor=lambda x: f"{x.source}-{x.type}-{x.target}",+ llm_client=llm,+ embedder=embedder,+)+graph.feed_text(text)+print(f"节点: {len(graph.nodes)}, 边: {len(graph.edges)}")+```++### AutoHypergraph - 超图++用于多元关系(n元关系):++```python+from hyperextract.types import AutoHypergraph+# 参考 examples/zh/autotypes/hypergraph_demo.py+```++### AutoTemporalGraph - 时序图++用于时间相关的关嗧:++```python+from hyperextract.types import AutoTemporalGraph+# 参考 examples/zh/autotypes/temporal_graph_demo.py+```++### AutoSpatialGraph - 空间图++用于位置相关的关嗧:++```python+from hyperextract.types import AutoSpatialGraph+# 参考 examples/zh/autotypes/spatial_graph_demo.py+```++### AutoSpatioTemporalGraph - 时空图++用于时间和位置同时相关的关嗧:++```python+from hyperextract.types import AutoSpatioTemporalGraph+# 参考 examples/zh/autotypes/spatio_temporal_graph_demo.py+```++---++## Methods vs Templates++Hyper-Extract 提供了两种提取知识的方式:++### Methods(底层方法)++Methods 提供对提取过程的**完全控制**。在以下情况下使用:+- 需要自定义提取逻辑+- 需要特定的算法调优+- 高级用例++```python+from hyperextract.methods.typical import KG_Gen++ka = KG_Gen(llm_client=llm, embedder=embedder)+ka.feed_text(text)+result = ka.chat("主要成就有哪些?")+```++可用的 Methods:+- **典型方法**:KG_Gen、iText2KG、iText2KG*+- **RAG增强方法**:GraphRAG、LightRAG、HyperRAG、HypergraphRAG、CogRAG++### Templates(高层配置)++Templates 是常见用例的**预配置 schema**。在以下情况下使用:+- 快速得到结果+- 领域特定的提取+- 零代码设置++```python+from hyperextract import Template++ka = Template.create("finance/earnings_summary", "zh")+result = ka.parse(text)+```++### 何时使用哪个?++| 场景 | 推荐 |+|------|------|+| 快速原型 | Templates |+| 领域特定提取 | Templates |+| 自定义提取逻辑 | Methods |+| 实时交互 | Methods |+| 批量处理 | 两者皆可 |++---++## 高级用法++### 批量处理++```python+from hyperextract import Template++ka = Template.create("general/biography_graph", "zh")+documents = ["doc1.txt", "doc2.txt", "doc3.txt"]++results = []+for doc in documents:+ with open(doc, encoding="utf-8") as f:+ result = ka.parse(f.read())+ results.append(result)+```++### 增量补充(feed)++```python+ka = Template.create("general/biography_graph", "zh")+result = ka.parse(text1)++# 添加更多知识+ka.feed(result, text2)+```++### 知识问答(chat)++```python+ka.build_index()+answer = ka.chat("有哪些关键事件?")+print(answer.content)+```++### 错误处理++```python+from hyperextract import Template++try:+ ka = Template.create("template_name", "zh")+ result = ka.parse(text)+except Exception as e:+ print(f"错误: {e}")+ # 处理错误+```++### 结果导出++```python+# 导出为 JSON+json_output = result.to_json()++# 导出为 Dict+dict_output = result.to_dict()++# 导出为三元组+triples = result.to_triples()+```++---++## 下一步++- [预设模板](../templates/index.md)+- [领域模板](../templates/index.md)+- [探索示例](https://github.com/yifanfeng97/hyper-extract/tree/main/examples/zh)diff --git a/docs/zh/reference/cli-reference.md b/docs/zh/reference/cli-reference.mddeleted file mode 100644index 1ed6fbd..0000000--- a/docs/zh/reference/cli-reference.md+++ /dev/null@@ -1,134 +0,0 @@-# CLI 参考--Hyper-Extract 所有 CLI 命令的完整参考。--## 命令概览--| 命令 | 描述 |-|------|------|-| `he config` | 管理配置 |-| `he parse` | 从文档提取知识 |-| `he search` | 查询提取的知识 |-| `he feed` | 向知识库添加新文档 |-| `he list` | 列出可用模板 |--## config--管理 Hyper-Extract 配置。--### 语法--```bash-he config <action> [options]-```--### 操作--#### init--初始化配置:--```bash-he config init -k API_KEY [--provider PROVIDER]-```--#### show--显示当前配置:--```bash-he config show [--format json|yaml]-```--#### set--更新配置选项:--```bash-he config set KEY VALUE-```--#### list-templates--列出可用模板:--```bash-he config list-templates [--category CATEGORY]-```--## parse--从文档中提取知识。--### 语法--```bash-he parse <input> [options]-```--### 选项--| 选项 | 描述 | 默认值 |-|------|------|--------|-| `-o, --output` | 输出目录 | 必需 |-| `-t, --template` | 模板名称 | 自动检测 |-| `-l, --language` | 文档语言 | 自动检测 |-| `--method` | 提取方法 | 默认 |-| `--batch` | 批量处理 | False |-| `--format` | 输出格式 | json |--## search--查询提取的知识。--### 语法--```bash-he search <knowledge_base> <query> [options]-```--### 选项--| 选项 | 描述 | 默认值 |-|------|------|--------|-| `--filter` | 按节点/边类型过滤 | 无 |-| `--limit` | 最大结果数 | 10 |-| `--format` | 输出格式 | json |--## feed--向现有知识库添加新文档。--### 语法--```bash-he feed <knowledge_base> <documents...> [options]-```--## list--列出可用模板。--### 语法--```bash-he list [options]-```--### 选项--| 选项 | 描述 | 默认值 |-|------|------|--------|-| `--category` | 按类别过滤 | 全部 |-| `--domain` | 按领域过滤 | 全部 |-| `--format` | 输出格式 | table |--## 全局选项--| 选项 | 描述 |-|------|------|-| `--help` | 显示帮助信息 |-| `--version` | 显示版本号 |-| `--verbose` | 启用详细输出 |-| `--debug` | 启用调试模式 |-| `--config PATH` | 自定义配置文件 |diff --git a/docs/zh/reference/index.md b/docs/zh/reference/index.mddeleted file mode 100644index f9eb73b..0000000--- a/docs/zh/reference/index.md+++ /dev/null@@ -1,21 +0,0 @@-# 参考文档--本节提供详细的 API 和配置参考文档。--## 本节内容--- [CLI 参考](cli-reference.md) - 完整的 CLI 命令参考-- [模板库](template-gallery.md) - 所有可用模板--## API 参考--详细的 Python API 文档,请参阅 [API 文档](https://hyper-extract.readthedocs.io/)。--## 配置参考--请参阅[配置指南](../getting-started/configuration.md)了解配置选项。--## 下一步--- [CLI 参考](cli-reference.md)-- [模板库](template-gallery.md)diff --git a/docs/zh/reference/template-gallery.md b/docs/zh/reference/template-gallery.mddeleted file mode 100644index ee0e550..0000000--- a/docs/zh/reference/template-gallery.md+++ /dev/null@@ -1,99 +0,0 @@-# 模板库--Hyper-Extract 中所有可用预设模板的完整列表。--## 金融模板--### 核心模板--| 模板 | 描述 |-|------|------|-| `finance/earnings_summary` | 提取财报亮点 |-| `finance/risk_factor_set` | 提取风险因素 |-| `finance/ownership_graph` | 提取所有权关系 |-| `finance/event_timeline` | 提取财务事件时间线 |-| `finance/sentiment_model` | 提取情感分析 |--## 法律模板--### 核心模板--| 模板 | 描述 |-|------|------|-| `legal/case_facts` | 从判决书中提取案件事实 |-| `legal/case_citation` | 提取法律引用 |-| `legal/contract_obligation` | 提取合同义务 |-| `legal/compliance_list` | 提取合规要求 |-| `legal/defined_term_set` | 提取定义术语 |-| `legal/case_fact_timeline` | 提取案件事实时间线 |--## 医学模板--### 核心模板--| 模板 | 描述 |-|------|------|-| `medicine/drug_interaction` | 提取药物相互作用 |-| `medicine/treatment_map` | 提取治疗计划 |-| `medicine/anatomy_graph` | 提取解剖学关系 |-| `medicine/hospital_timeline` | 提取患者住院时间线 |-| `medicine/discharge_instruction` | 提取出院指导 |--## 中医模板--### 核心模板--| 模板 | 描述 |-|------|------|-| `tcm/herb_property` | 提取中药属性 |-| `tcm/formula_composition` | 提取方剂组成 |-| `tcm/herb_relation` | 提取中药关系 |-| `tcm/meridian_graph` | 提取经络关系 |-| `tcm/syndrome_reasoning` | 提取证候推理 |--## 工业模板--### 核心模板--| 模板 | 描述 |-|------|------|-| `industry/safety_control` | 提取安全控制 |-| `industry/equipment_topology` | 提取设备关系 |-| `industry/operation_flow` | 提取操作流程 |-| `industry/failure_case` | 提取故障案例分析 |-| `industry/emergency_response` | 提取应急程序 |--## 通用模板--### 核心模板--| 模板 | 描述 |-|------|------|-| `general/biography` | 提取传记信息 |-| `general/concepts` | 提取概念关系 |-| `general/workflow` | 提取工作流程步骤 |-| `general/doc_structure` | 提取文档结构 |-| `general/base_model` | 基本模型提取 |-| `general/base_list` | 基本列表提取 |-| `general/base_set` | 基本集合提取 |-| `general/base_graph` | 基本图提取 |-| `general/base_hypergraph` | 基本超图提取 |--## 使用模板--### CLI--```bash-he parse document.txt -t <template_name>-```--### Python API--```python-ka = Template.create("<template_name>")-result = ka.parse(document_text)-```--## 创建自定义模板--请参阅[模板设计指南](../concepts/templates.md)了解如何创建您自己的模板。diff --git a/docs/zh/resources/contributing.md b/docs/zh/resources/contributing.mdindex 139e515..dc58d82 100644--- a/docs/zh/resources/contributing.md+++ b/docs/zh/resources/contributing.md@@ -102,9 +102,9 @@## 开发资源-- [GitHub 仓库](https://github.com/hyper-extract/hyper-extract)-- [Issue 追踪器](https://github.com/hyper-extract/hyper-extract/issues)-- [讨论区](https://github.com/hyper-extract/hyper-extract/discussions)+- [GitHub 仓库](https://github.com/yifanfeng97/hyper-extract)+- [Issue 追踪器](https://github.com/yifanfeng97/hyper-extract/issues)+- [讨论区](https://github.com/yifanfeng97/hyper-extract/discussions)## 行为准则diff --git a/docs/zh/resources/faq.md b/docs/zh/resources/faq.mdindex 553887e..5bec915 100644--- a/docs/zh/resources/faq.md+++ b/docs/zh/resources/faq.md@@ -59,7 +59,7 @@ result = ka.parse(document_text)### 如何创建自定义模板?-请参阅[模板设计指南](../concepts/templates.md)了解如何创建自定义模板。+请参阅[领域模板](../templates/index.md)了解如何创建自定义模板。## 故障排除diff --git a/docs/zh/resources/index.md b/docs/zh/resources/index.mdindex 7e5802d..b09e622 100644--- a/docs/zh/resources/index.md+++ b/docs/zh/resources/index.md@@ -12,7 +12,7 @@- 查看 [常见问题](faq.md)- 阅读 [故障排除](troubleshooting.md)-- 访问 [GitHub Issues](https://github.com/hyper-extract/hyper-extract/issues)+- 访问 [GitHub Issues](https://github.com/yifanfeng97/hyper-extract/issues)## 贡献diff --git a/docs/zh/resources/troubleshooting.md b/docs/zh/resources/troubleshooting.mdindex d519272..f46551a 100644--- a/docs/zh/resources/troubleshooting.md+++ b/docs/zh/resources/troubleshooting.md@@ -145,5 +145,5 @@ he config init -k <your-api-key>如果您仍然遇到问题:1. 查看[常见问题](faq.md)-2. 搜索现有的 [GitHub Issues](https://github.com/hyper-extract/hyper-extract/issues)+2. 搜索现有的 [GitHub Issues](https://github.com/yifanfeng97/hyper-extract/issues)3. 创建包含详细信息的新问题diff --git a/docs/zh/guides/domain-templates/finance.md b/docs/zh/templates/finance.mdsimilarity index 98%rename from docs/zh/guides/domain-templates/finance.mdrename to docs/zh/templates/finance.mdindex d70d5ec..39cebd8 100644--- a/docs/zh/guides/domain-templates/finance.md+++ b/docs/zh/templates/finance.md@@ -227,4 +227,4 @@ print(result.fields)- [法律模板](legal.md)- [医学模板](medicine.md)-- [模板库](../../reference/template-gallery.md)+diff --git a/docs/zh/templates/index.md b/docs/zh/templates/index.mdnew file mode 100644index 0000000..041c58e--- /dev/null+++ b/docs/zh/templates/index.md@@ -0,0 +1,67 @@+# Templates++Hyper-Extract 为各行业和用例提供专用模板。++## 可用领域++- [金融](domain/finance.md) - 金融文档提取+- [法律](domain/legal.md) - 法律文档提取+- [医学](domain/medicine.md) - 医疗文档提取+- [中医](domain/tcm.md) - 中医模板++## 快速开始++### 使用领域模板++```bash+# CLI+he parse document.txt -t finance/earnings_summary++# Python API+ka = Template.create("finance/earnings_summary")+result = ka.parse(document_text)+```++## 模板类别++### 金融模板++从各种文档类型中提取财务信息:++- 财报+- 财经新闻+- IPO 招股书+- 券商研报+- 供应链分析++### 法律模板++提取法律信息:++- 判决书+- 合同+- 合规文件+- 法律专著++### 医学模板++提取医学信息:++- 临床指南+- 出院小结+- 药品说明书+- 病理报告+- 医学教材++### 中医模板++中医专用模板:++- 中药属性+- 方剂组成+- 经络图谱+- 证候推理++## 快速链接++- [Concepts](../concepts/index.md) - 了解 AutoTypes 和 Methodsdiff --git a/docs/zh/guides/domain-templates/legal.md b/docs/zh/templates/legal.mdsimilarity index 98%rename from docs/zh/guides/domain-templates/legal.mdrename to docs/zh/templates/legal.mdindex a4c8ce1..e5228d7 100644--- a/docs/zh/guides/domain-templates/legal.md+++ b/docs/zh/templates/legal.md@@ -227,4 +227,4 @@ print(result.entities)- [金融模板](finance.md)- [医学模板](medicine.md)-- [模板库](../../reference/template-gallery.md)+diff --git a/docs/zh/guides/domain-templates/medicine.md b/docs/zh/templates/medicine.mdsimilarity index 98%rename from docs/zh/guides/domain-templates/medicine.mdrename to docs/zh/templates/medicine.mdindex e541e6c..269aa05 100644--- a/docs/zh/guides/domain-templates/medicine.md+++ b/docs/zh/templates/medicine.md@@ -208,4 +208,4 @@ print(result.entities)- [中医模板](tcm.md)- [金融模板](finance.md)-- [模板库](../../reference/template-gallery.md)+diff --git a/docs/zh/guides/domain-templates/tcm.md b/docs/zh/templates/tcm.mdsimilarity index 98%rename from docs/zh/guides/domain-templates/tcm.mdrename to docs/zh/templates/tcm.mdindex 55de6bb..b959f4f 100644--- a/docs/zh/guides/domain-templates/tcm.md+++ b/docs/zh/templates/tcm.md@@ -225,4 +225,4 @@ print(result.fields)- [医学模板](medicine.md)- [金融模板](finance.md)-- [模板库](../../reference/template-gallery.md)+diff --git a/examples/README.md b/examples/README.mdindex fb1f135..1e8492f 100644--- a/examples/README.md+++ b/examples/README.md@@ -31,19 +31,59 @@ examples/│ │ ├── list_demo.py # List extraction│ │ ├── set_demo.py # Set extraction│ │ ├── model_demo.py # Model extraction-│ │ ├── temporal_demo.py # Temporal graph-│ │ ├── spatial_demo.py # Spatial graph-│ │ ├── spatio_temporal_demo.py # Spatio-temporal+│ │ ├── temporal_graph_demo.py # Temporal graph+│ │ ├── spatial_graph_demo.py # Spatial graph+│ │ ├── spatio_temporal_graph_demo.py # Spatio-temporal│ │ └── hypergraph_demo.py # Hypergraph│ ├── methods/ # RAG method demos+│ │ ├── atom_demo.py+│ │ ├── cog_rag_demo.py+│ │ ├── graph_rag_demo.py+│ │ ├── hyper_rag_demo.py+│ │ ├── hypergraph_rag_demo.py+│ │ ├── itext2kg_demo.py+│ │ ├── itext2kg_star_demo.py+│ │ ├── kg_gen_demo.py+│ │ └── light_rag_demo.py│ └── templates/ # Template demos+│ ├── finance_template.py+│ ├── general_template.py+│ ├── industry_template.py+│ ├── legal_template.py+│ ├── list_templates.py+│ ├── medicine_template.py+│ └── tcm_template.py│└── zh/ # Chinese demos├── sushi.md # Su Shi biography data├── sushi_question.md # Query questions├── autotypes/ # AutoType demos+ │ ├── graph_demo.py+ │ ├── list_demo.py+ │ ├── set_demo.py+ │ ├── model_demo.py+ │ ├── temporal_graph_demo.py+ │ ├── spatial_graph_demo.py+ │ ├── spatio_temporal_graph_demo.py+ │ └── hypergraph_demo.py├── methods/ # RAG method demos+ │ ├── atom_demo.py+ │ ├── cog_rag_demo.py+ │ ├── graph_rag_demo.py+ │ ├── hyper_rag_demo.py+ │ ├── hypergraph_rag_demo.py+ │ ├── itext2kg_demo.py+ │ ├── itext2kg_star_demo.py+ │ ├── kg_gen_demo.py+ │ └── light_rag_demo.py└── templates/ # Template demos+ ├── finance_template.py+ ├── general_template.py+ ├── industry_template.py+ ├── legal_template.py+ ├── list_templates.py+ ├── medicine_template.py+ └── tcm_template.py```## AutoType Demos@@ -56,9 +96,9 @@ Each demo showcases a specific extraction type:| `list_demo.py` | Extract list of items || `set_demo.py` | Extract deduplicated set || `model_demo.py` | Extract structured summary |-| `temporal_demo.py` | Extract temporal relationships |-| `spatial_demo.py` | Extract spatial relationships |-| `spatio_temporal_demo.py` | Extract both time & space |+| `temporal_graph_demo.py` | Extract temporal relationships |+| `spatial_graph_demo.py` | Extract spatial relationships |+| `spatio_temporal_graph_demo.py` | Extract both time & space || `hypergraph_demo.py` | Extract multi-entity relationships |## Data Files@@ -83,6 +123,14 @@ Nikola Tesla biography (1856-1943):## Requirements```bash-pip install hyperextract langchain-openai python-dotenv+# Install hyper-extract (dependencies are automatically installed)+uv pip install hyper-extract++# Configure API key+# Option 1: Use .env file (recommended)+cp .env.example .env+# Then edit .env with your OPENAI_API_KEY and OPENAI_BASE_URL++# Option 2: Set environment variableexport OPENAI_API_KEY=your-key```diff --git a/mkdocs.yml b/mkdocs.ymlindex 470e08e..af0ce30 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -2,11 +2,11 @@site_name: Hyper-Extractsite_description: LLM-powered knowledge extraction framework-site_author: Hyper-Extract Team+site_author: Yifan Fengsite_url: https://hyper-extract.github.io/-repo_name: hyper-extract/hyper-extract-repo_url: https://github.com/hyper-extract/hyper-extract+repo_name: yifanfeng97/hyper-extract+repo_url: https://github.com/yifanfeng97/hyper-extractedit_uri: edit/main/docs/theme:@@ -39,31 +39,25 @@ plugins:build: truenav:- 首页: zh/index.md- - 开始使用:- - zh/getting-started/index.md- - zh/getting-started/installation.md- - zh/getting-started/quickstart.md- - zh/getting-started/configuration.md+ - CLI 使用指南:+ - zh/cli/index.md+ - zh/cli/cli.md+ - zh/cli/config.md+ - Python 开发者指南:+ - zh/python/index.md+ - zh/python/python-api.md+ - zh/python/config.md- 核心概念:- zh/concepts/index.md- zh/concepts/auto-types.md- - zh/concepts/methods.md- - zh/concepts/templates.md- - 使用指南:- - zh/guides/index.md- - zh/guides/cli.md- - zh/guides/python-api.md- - zh/guides/domain-templates/index.md- - zh/guides/domain-templates/finance.md- - zh/guides/domain-templates/legal.md- - zh/guides/domain-templates/medicine.md- - zh/guides/domain-templates/tcm.md- - 参考资料:- - zh/reference/index.md- - zh/reference/cli-reference.md- - zh/reference/template-gallery.md- - 资源:- - zh/resources/index.md+ - 知识摘要模板:+ - zh/templates/index.md+ - zh/templates/domain/index.md+ - zh/templates/domain/finance.md+ - zh/templates/domain/legal.md+ - zh/templates/domain/medicine.md+ - zh/templates/domain/tcm.md+ - 帮助指南:- zh/resources/faq.md- zh/resources/troubleshooting.md- zh/resources/contributing.md@@ -75,30 +69,25 @@ extra:nav:- Home: en/index.md- - Getting Started:- - en/getting-started/index.md- - en/getting-started/installation.md- - en/getting-started/quickstart.md- - en/getting-started/configuration.md+ - CLI:+ - en/cli/index.md+ - en/cli/cli.md+ - en/cli/config.md+ - Python SDK:+ - en/python/index.md+ - en/python/python-api.md+ - en/python/config.md- Concepts:- en/concepts/index.md- en/concepts/auto-types.md- - en/concepts/methods.md- - en/concepts/templates.md- - Guides:- - en/guides/index.md- - en/guides/cli.md- - en/guides/python-api.md- - en/guides/domain-templates/index.md- - en/guides/domain-templates/finance.md- - en/guides/domain-templates/legal.md- - en/guides/domain-templates/medicine.md- - en/guides/domain-templates/tcm.md- - Reference:- - en/reference/index.md- - en/reference/cli-reference.md- - en/reference/template-gallery.md- - Resources:+ - Templates:+ - en/templates/index.md+ - en/templates/domain/index.md+ - en/templates/domain/finance.md+ - en/templates/domain/legal.md+ - en/templates/domain/medicine.md+ - en/templates/domain/tcm.md+ - Help:- en/resources/faq.md- en/resources/troubleshooting.md- en/resources/contributing.md