Skip to content

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

docs: 更新文档结构和内容,优化模板格式

yifanfeng976e6d990b73a0
diff --git a/README.md b/README.md
index d059b55..7a13e03 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
**Transform documents into knowledge abstracts — with just one command.**
-[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Status](https://img.shields.io/badge/status-active-success)]()
@@ -55,22 +55,53 @@ he feed ./output/ new_document.md
Zero-code approach to define what to extract from incoming texts:
```yaml
-name: Event Timeline
-description: Extract financial events and their temporal relations.
-type: TemporalGraph
-schema:
- nodes:
- - type: Event
- properties:
- - name: description
- type: string
- edges:
- - type: Timeline
- source: Event
- target: Event
- properties:
- - name: relation
- type: string
+language: en
+
+name: Knowledge Graph
+type: graph
+tags: [general]
+
+description: 'Extract entities and their relationships to construct a knowledge graph.'
+
+output:
+ entities:
+ fields:
+ - name: name
+ type: str
+ description: 'Entity name'
+ - name: type
+ type: str
+ description: 'Entity type'
+ 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 their relationships from the text.'
+ rules_for_entities:
+ - 'Extract meaningful entities'
+ - 'Maintain consistent naming'
+ rules_for_relations:
+ - 'Create relations only when explicitly expressed in the text'
+
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{type}|{target}'
+ relation_members:
+ source: source
+ target: target
+
+display:
+ entity_label: '{name} ({type})'
+ relation_label: '{type}'
```
</details>
@@ -92,13 +123,13 @@ result = ka.parse(annual_report_text)
Our framework embraces complexity without making you write boilerplate code.
-![Knowledge Structures Matrix](docs/assets/8-types.jpg)
+![Knowledge Structures Matrix](docs/assets/8-types-v2.png)
## 🛠️ Architecture Overview
The system is built on a robust triad: **Auto-Types** (Multi-typed structures), **Methods** (The Execution strategy), and **Templates** (Declarative schema).
-![Architecture](docs/assets/architecture-v10.jpg)
+![Architecture](docs/assets/architecture-v2.png)
* **Design Guide**: [Template Design Guide](./hyperextract/templates/DESIGN_GUIDE.md)
* **Preset Templates**: [presets directory](./hyperextract/templates/presets/)
diff --git a/README_ZH.md b/README_ZH.md
index cca386a..d7b4301 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -8,7 +8,7 @@
**将文档转化为知识摘要 —— 一行命令即可。**
-[![Python版本](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
+[![Python版本](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)
[![开源协议](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![状态](https://img.shields.io/badge/status-active-success)]()
@@ -54,22 +54,53 @@ he feed ./output/ new_document.md
无需编写长篇代码,只需使用优雅的 YAML 结构直接声明你想要的信息形态:
```yaml
-name: Event Timeline
-description: 提取金融动态及其时间依赖关系。
-type: TemporalGraph
-schema:
- nodes:
- - type: Event
- properties:
- - name: description
- type: string
- edges:
- - type: Timeline
- source: Event
- target: Event
- properties:
- - name: relation
- type: string
+language: zh
+
+name: 知识图谱
+type: graph
+tags: [general]
+
+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}'
```
</details>
@@ -91,13 +122,13 @@ result = ka.parse(annual_report_text)
拒绝样板代码,纯干货聚焦数据本身。
-![Knowledge Structures Matrix](docs/assets/8-types.jpg)
+![Knowledge Structures Matrix](docs/assets/8-types-v2.png)
## 🛠️ 系统架构揭秘
系统底座基于坚实的铁三角架构:**Auto-Types** (提取结构)、**Methods** (执行策略)、以及 **Templates** (声明式配置)。
-![Architecture](docs/assets/architecture-v10.jpg)
+![Architecture](docs/assets/architecture-v2.png)
* **设计指南**: [模板设计指南](./hyperextract/templates/DESIGN_GUIDE.md)
* **内置模板**: [预设模板目录](./hyperextract/templates/presets/)
diff --git a/docs/assets/8-types-v2.jpg b/docs/assets/8-types-v2.jpg
deleted file mode 100644
index 7149049..0000000
Binary files a/docs/assets/8-types-v2.jpg and /dev/null differ
diff --git a/docs/assets/8-types-v2.png b/docs/assets/8-types-v2.png
new file mode 100644
index 0000000..4fc6d7e
Binary files /dev/null and b/docs/assets/8-types-v2.png differ
diff --git a/docs/assets/8-types-v5.jpg b/docs/assets/8-types-v5.jpg
deleted file mode 100644
index 41ceac3..0000000
Binary files a/docs/assets/8-types-v5.jpg and /dev/null differ
diff --git a/docs/assets/architecture-v10.jpg b/docs/assets/architecture-v10.jpg
deleted file mode 100644
index c82c60a..0000000
Binary files a/docs/assets/architecture-v10.jpg and /dev/null differ
diff --git a/docs/assets/architecture-v2.png b/docs/assets/architecture-v2.png
new file mode 100644
index 0000000..944c628
Binary files /dev/null and b/docs/assets/architecture-v2.png differ
diff --git a/docs/assets/architecture-v9.jpg b/docs/assets/architecture.jpg
similarity index 100%
rename from docs/assets/architecture-v9.jpg
rename to docs/assets/architecture.jpg
diff --git a/docs/assets/hero-v1.jpg b/docs/assets/hero.jpg
similarity index 100%
rename from docs/assets/hero-v1.jpg
rename to docs/assets/hero.jpg
diff --git a/docs/en/concepts/auto-types.md b/docs/en/concepts/auto-types.md
index 89dfc57..4332a38 100644
--- a/docs/en/concepts/auto-types.md
+++ b/docs/en/concepts/auto-types.md
@@ -1,118 +1,129 @@
-# Auto-Types
+# AutoTypes
-Hyper-Extract provides 8 auto-types for representing knowledge. Each type is optimized for specific extraction scenarios.
+Hyper-Extract uses auto types to determine extraction patterns, supporting 8 types in total.
-## Overview
+## Type Overview
-| Type | Module | Description |
-|------|--------|-------------|
-| AutoModel | `hyperextract.types.model` | Pydantic model extraction |
-| AutoList | `hyperextract.types.list` | List/collection extraction |
-| AutoSet | `hyperextract.types.set` | Unique set extraction |
-| AutoGraph | `hyperextract.types.graph` | Knowledge graph extraction |
-| AutoHypergraph | `hyperextract.types.hypergraph` | Hypergraph extraction |
-| AutoTemporalGraph | `hyperextract.types.temporal_graph` | Temporal knowledge graph |
-| AutoSpatialGraph | `hyperextract.types.spatial_graph` | Spatial knowledge graph |
-| AutoSpatioTemporalGraph | `hyperextract.types.spatio_temporal_graph` | Spatio-temporal graph |
+| 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 |
-## Usage Examples
+## Selection Decision Tree
-### AutoModel
+```
+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
+```
+
+## Detailed Usage
+
+### Model
-Extract structured data into Pydantic models:
+Used for extracting a single structured object.
```python
-from hyperextract import AutoModel
-from pydantic import BaseModel
+from hyperextract import Template
-class Person(BaseModel):
- name: str
- age: int
- occupation: str
+ka = Template.create("finance/earnings_summary", "en")
+result = ka.parse(text)
-extractor = AutoModel(schema=Person)
-result = extractor.parse("John Smith is a 35-year-old software engineer.")
+print(result.fields["company_name"])
+print(result.fields["revenue"])
```
-### AutoList
+### List
-Extract lists of items:
+Used for extracting an ordered list.
```python
-from hyperextract import AutoList
+from hyperextract import Template
-extractor = AutoList(item_type="string")
-result = extractor.parse("The ingredients are flour, sugar, eggs, and milk.")
-# result: ["flour", "sugar", "eggs", "milk"]
+ka = Template.create("finance/risk_factor_set", "en")
+result = ka.parse(text)
+
+for item in result.fields:
+ print(item)
```
-### AutoGraph
+### Set
-Extract knowledge graphs:
+Used for extracting a deduplicated set.
```python
-from hyperextract import AutoGraph
+from hyperextract import Template
+
+ka = Template.create("general/entity_registry", "en")
+result = ka.parse(text)
-extractor = AutoGraph(node_types=["Person", "Company"], edge_types=["WORKS_AT"])
-result = extractor.parse("Alice works at Google.")
-# result: Graph with nodes and edges
+for entity in result.fields:
+ print(entity)
```
-### AutoHypergraph
+### Graph
-Extract hypergraphs (edges connecting multiple nodes):
+Used for extracting binary relations.
```python
-from hyperextract import AutoHypergraph
+from hyperextract import Template
+
+ka = Template.create("finance/ownership_graph", "en")
+result = ka.parse(text)
-extractor = AutoHypergraph()
-result = extractor.parse("Alice, Bob, and Carol collaborated on Project X.")
+for entity in result.entities:
+ print(f"{entity['name']} ({entity['type']})")
+
+for relation in result.relations:
+ print(f"{relation['source']} --[{relation['type']}]--> {relation['target']}")
```
-### AutoTemporalGraph
+### Hypergraph
-Extract graphs with temporal information:
+Used for extracting multi-entity relations.
```python
-from hyperextract import AutoTemporalGraph
-
-extractor = AutoTemporalGraph()
-result = extractor.parse("On Monday, Alice joined Google. On Tuesday, she started working.")
-```
+from hyperextract import Template
-## Choosing the Right Type
+ka = Template.create("tcm/formula_composition", "en")
+result = ka.parse(text)
-### When to Use AutoModel
-- Need structured, validated output
-- Working with well-defined schemas
-- Want Pydantic validation
+for relation in result.relations:
+ print(f"Formula: {relation['formula_name']}")
+ print(f"Herbs: {relation['herbs']}")
+```
-### When to Use AutoList
-- Extracting collections of items
-- Order matters
-- Simple item extraction
+### Temporal Graph
-### When to Use AutoSet
-- Need unique items only
-- Don't care about order
-- Deduplication required
+Used for extracting temporal relations.
-### When to Use AutoGraph
-- Complex relationships between entities
-- Knowledge graphs
-- Network analysis
+```python
+from hyperextract import Template
-### When to Use AutoHypergraph
-- Many-to-many relationships
-- Group entities together
-- Complex network structures
+ka = Template.create("finance/event_timeline", "en")
+result = ka.parse(text)
-### When to Use Temporal/Spatial Variants
-- Time-aware: Use `AutoTemporalGraph`
-- Location-aware: Use `AutoSpatialGraph`
-- Both: Use `AutoSpatioTemporalGraph`
+for relation in result.relations:
+ print(f"{relation['source']} --[{relation['type']}]--> {relation['target']} @ {relation['time']}")
+```
## Next Steps
-- Learn about [Extraction Methods](methods.md)
-- Explore [Templates](templates.md)
+- Learn about [Templates](./templates.md)
+- Browse [Preset Templates](./templates.md)
+- Explore [Domain Templates](../guides/domain-templates/index.md)
diff --git a/docs/en/concepts/index.md b/docs/en/concepts/index.md
index f19b19c..86d80fe 100644
--- a/docs/en/concepts/index.md
+++ b/docs/en/concepts/index.md
@@ -1,52 +1,52 @@
-# Concepts
+# Core Concepts
-This section explains the core concepts behind Hyper-Extract.
+## Overview
-## What's in This Section
-
-- [Auto-Types](auto-types.md) - The 8 data structures for knowledge representation
-- [Extraction Methods](methods.md) - The 10+ engines for knowledge extraction
-- [Templates](templates.md) - Declarative YAML schemas for extraction
+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.
## Core Concepts
-### Auto-Types
+### Template
+
+Templates use YAML to define what to extract, providing a declarative way to specify extraction schemas without writing code.
+
+Learn more: [Templates](./templates.md)
+
+### AutoType
+
+Hyper-Extract supports 8 auto types, each designed for different extraction scenarios:
-Hyper-Extract provides 8 auto-types, ranging from simple collections to complex graphs:
+| 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 |
-| Type | Use Case |
-|------|----------|
-| AutoModel | Structured data extraction |
-| AutoList | List/collection extraction |
-| AutoSet | Unique item extraction |
-| AutoGraph | Knowledge graph extraction |
-| AutoHypergraph | Complex relationship extraction |
-| AutoTemporalGraph | Time-aware knowledge graphs |
-| AutoSpatialGraph | Location-aware knowledge graphs |
-| AutoSpatioTemporalGraph | Time and location aware graphs |
+Learn more: [AutoTypes](./auto-types.md)
-### Extraction Methods
+### Methods
-Choose the right method for your extraction task:
+Hyper-Extract supports multiple extraction methods:
-| Method | Best For |
-|--------|----------|
-| atom | Simple, direct extraction |
-| graph_rag | Graph-based retrieval |
-| light_rag | Lightweight retrieval |
-| hyper_rag | Hypergraph extraction |
-| cog_rag | Cognitive retrieval |
+- **Local Models**: Use locally deployed models
+- **API Models**: Use cloud APIs (e.g., OpenAI, Claude)
+- **Hybrid Mode**: Combine multiple methods
-### Templates
+Learn more: [Methods](./methods.md)
-Templates define WHAT to extract using declarative YAML. They provide:
+## Quick Start
-- Type-safe schemas
-- Validation rules
-- Custom extraction logic
+1. [Installation](../getting-started/installation.md)
+2. [Quick Start Tutorial](../getting-started/quickstart.md)
+3. [Template Design](./templates.md)
-## Learn More
+## Next Steps
-- [Auto-Types](auto-types.md) - Deep dive into each type
-- [Methods](methods.md) - Compare extraction methods
-- [Templates](templates.md) - Create custom templates
+- Browse the [Template Gallery](../reference/template-gallery.md)
+- Explore [Domain Templates](../guides/domain-templates/index.md)
+- Learn the [Python API](../guides/python-api.md)
diff --git a/docs/en/concepts/templates.md b/docs/en/concepts/templates.md
index 795b80f..a62c8d3 100644
--- a/docs/en/concepts/templates.md
+++ b/docs/en/concepts/templates.md
@@ -2,155 +2,570 @@
Templates define WHAT to extract using declarative YAML. They provide a powerful way to specify extraction schemas without writing code.
-## Template Structure
+## Type Selection
-A template consists of:
+![Knowledge Structures Matrix](../assets/8-types-v2.png)
-1. **Metadata**: name, description, author
-2. **Type**: The extraction type (Graph, List, Model, etc.)
-3. **Schema**: Definition of nodes, edges, and fields
+Before designing a template, determine which type fits your needs:
-## Basic Example
+```
+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
-name: Event Timeline
-description: Extract financial events and their temporal relations
-type: TemporalGraph
-schema:
- nodes:
- - type: Event
- properties:
- - name: description
- type: string
- - name: date
- type: string
- edges:
- - type: TIMELINE
- source: Event
- target: Event
- properties:
- - name: relation
- type: string
+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}'
```
-## Template Types
+### model - Single Object
-### Graph Templates
+Extract a single structured record.
```yaml
-type: Graph
-schema:
- nodes:
- - type: Person
- - type: Organization
- edges:
- - type: WORKS_AT
- source: Person
- target: Organization
+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 Templates
+### list - Ordered Array
+
+Extract ordered items (rankings, sequences, bullet points).
```yaml
-type: List
-schema:
- item:
- - name: ingredient
- type: string
- - name: quantity
- type: string
+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}'
```
-### Model Templates
+### set - Deduplicated Collection
+
+Extract unique entities with automatic deduplication.
```yaml
-type: Model
-schema:
- - name: product_name
- type: string
- required: true
- - name: price
- type: float
- required: true
+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}'
```
-## Property Types
+**Note**: Set type requires `identifiers.item_id` to define the deduplication key.
-| Type | Description | Example |
-|------|-------------|---------|
-| string | Text value | "Hello World" |
-| integer | Whole number | 42 |
-| float | Decimal number | 3.14 |
-| boolean | True/False | true |
-| date | Date value | 2024-01-15 |
-| array | List of values | ["a", "b", "c"] |
+---
+
+## Graph Types
-## Advanced Features
+Graph types extract entities and their relationships. They use `output.entities` and `output.relations`.
-### Validation Rules
+### Common Structure
```yaml
-- name: email
- type: string
- pattern: "^[a-zA-Z0-9._%+-]+@[a-z]+.[a-z]{2,}$"
+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}'
```
-### Enumerations
+### graph - Binary Relations
+
+Extract relationships between two entities (A→B).
```yaml
-- name: status
- type: string
- enum: [pending, active, completed]
+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}'
```
-### Conditional Fields
+### 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
-- name: end_date
- type: date
- required_if: type == "event"
+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`
-- `finance/risk_factors`
-- `finance/ownership_graph`
+- `finance/earnings_summary` (model)
+- `finance/risk_factor_set` (set)
+- `finance/ownership_graph` (graph)
+- `finance/event_timeline` (temporal_graph)
### Legal
-- `legal/case_facts`
-- `legal/contract_terms`
-- `legal/compliance_requirements`
+- `legal/case_fact_timeline` (temporal_graph)
+- `legal/case_citation` (graph)
+- `legal/contract_obligation` (list)
### Medicine
-- `medicine/drug_interactions`
-- `medicine/treatment_plan`
-- `medicine/patient_history`
+- `medicine/drug_interaction` (graph)
+- `medicine/treatment_map` (temporal_graph)
+- `medicine/discharge_instruction` (list)
-### TCM (Traditional Chinese Medicine)
-- `tcm/herb_properties`
-- `tcm/formula_composition`
-- `tcm/syndrome_reasoning`
+### TCM
+- `tcm/herb_property` (model)
+- `tcm/formula_composition` (list)
+- `tcm/meridian_graph` (graph)
### Industry
-- `industry/safety_controls`
-- `industry/equipment_topology`
-- `industry/operation_flow`
+- `industry/safety_control` (list)
+- `industry/equipment_topology` (graph)
+- `industry/failure_case` (temporal_graph)
### General
-- `general/biography`
-- `general/concepts`
-- `general/workflow`
+- `general/graph` (graph)
+- `general/list` (list)
+- `general/model` (model)
+- `general/set` (set)
+- `general/biography_graph` (spatio_temporal_graph)
+
+---
## Using Templates
### CLI
```bash
-he parse document.txt -t finance/earnings_summary
+# 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
@@ -158,15 +573,21 @@ he parse document.txt -t finance/earnings_summary
```python
from hyperextract import Template
-# Load preset
-ka = Template.create("finance/earnings_summary")
+# Load preset template
+ka = Template.create("finance/ownership_graph", "en")
+
+# Load from YAML
+ka = Template.create("template.yaml", "en")
-# Load custom template
-ka = Template.from_yaml("my_template.yaml")
+# Parse document
+result = ka.parse(document_text)
```
+---
+
## Next Steps
-- Browse the [Template Gallery](../reference/template-gallery.md)
+- 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.md
index 49cf194..5ca4ae1 100644
--- a/docs/en/getting-started/configuration.md
+++ b/docs/en/getting-started/configuration.md
@@ -1,76 +1,60 @@
# Configuration
-This guide covers advanced configuration options for Hyper-Extract.
+Hyper-Extract uses a TOML configuration file. Default location: `~/.he/config.toml`
-## Configuration File
+## Quick Setup
-Hyper-Extract uses a YAML configuration file. Default location: `~/.hyper-extract/config.yaml`
+```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
-```yaml
-llm:
- provider: openai # openai, anthropic, azure, etc.
- model: gpt-4o
- api_key: ${OPENAI_API_KEY} # Or use environment variable
- temperature: 0.0
- max_tokens: 4096
-```
-
-### Embedding Settings
-
-```yaml
-embedding:
- provider: openai # openai, huggingface, etc.
- model: text-embedding-3-small
- api_key: ${OPENAI_API_KEY}
+```bash
+he config llm --api-key YOUR_KEY --model gpt-4o-mini
```
-### Extraction Settings
-
-```yaml
-extraction:
- default_type: AutoGraph
- max_retries: 3
- timeout: 60
- batch_size: 10
-```
+| 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) |
-### Storage Settings
+### Embedder Settings
-```yaml
-storage:
- type: local # local, s3, etc.
- path: ./output
- format: json # json, yaml, parquet
+```bash
+he config embedder --api-key YOUR_KEY --model text-embedding-3-small
```
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `OPENAI_API_KEY` | OpenAI API key |
-| `ANTHROPIC_API_KEY` | Anthropic API key |
-| `HYPER_EXTRACT_CONFIG` | Path to config file |
-
-## CLI Configuration
+| 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) |
-Initialize configuration via CLI:
+## View Configuration
```bash
-# Initialize with OpenAI
-he config init -k your-api-key
-
-# Show current configuration
he config show
-
-# Update specific option
-he config set llm.model gpt-4o-mini
```
+## 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
-- Explore [Concepts](../concepts/index.md) to understand extraction types
-- Check [CLI Reference](../reference/cli-reference.md) for all commands
+- Learn about [Templates](../concepts/templates.md)
+- Browse [Preset Templates](../concepts/templates.md#preset-templates)
diff --git a/docs/en/getting-started/installation.md b/docs/en/getting-started/installation.md
index 969e61b..92e6628 100644
--- a/docs/en/getting-started/installation.md
+++ b/docs/en/getting-started/installation.md
@@ -1,69 +1,24 @@
# Installation
-This guide covers how to install Hyper-Extract and its dependencies.
-
## Requirements
-- Python 3.9+
-- pip or uv package manager
-- OpenAI API key (or compatible LLM API)
-
-## Installation Methods
-
-### Using pip
+- Python 3.11+
-```bash
-pip install hyper-extract
-```
+## Install
-### Using uv
+### Using uv (Recommended)
```bash
uv pip install hyper-extract
```
-## Install with Extras
-
-For specific use cases, you can install with extras:
-
-```bash
-# With all integrations
-pip install hyper-extract[all]
-
-# With OpenAI support
-pip install hyper-extract[openai]
-
-# With development tools
-pip install hyper-extract[dev]
-```
-
-## Verify Installation
-
-After installation, verify it works:
-
-```bash
-he --version
-```
-
-You should see the version number printed.
-
-## Setting Up API Keys
-
-Hyper-Extract requires an API key for LLM services. Set it up:
-
-### Using Environment Variable
-
-```bash
-export OPENAI_API_KEY=your-api-key-here
-```
-
-### Using CLI
+### Using pip
```bash
-he config init -k your-api-key-here
+pip install hyper-extract
```
## Next Steps
-- Continue to [Quick Start](quickstart.md) to run your first extraction
-- Or configure advanced settings in [Configuration](configuration.md)
+- [Quick Start](getting-started/quickstart.md) - Extract your first document
+- [Configuration](getting-started/configuration.md) - Configure API settings
diff --git a/docs/en/getting-started/quickstart.md b/docs/en/getting-started/quickstart.md
index e68f287..e34b783 100644
--- a/docs/en/getting-started/quickstart.md
+++ b/docs/en/getting-started/quickstart.md
@@ -18,33 +18,59 @@ Services revenue reached an all-time high of $22.3 billion.
Hyper-Extract uses YAML templates to define what to extract. Create `template.yaml`:
```yaml
+language: en
+
name: Company News Summary
-description: Extract key financial events from news articles
-type: TemporalGraph
-schema:
- nodes:
- - type: Company
- properties:
- - name: name
- type: string
- - name: ticker
- type: string
- - type: FinancialEvent
- properties:
- - name: description
- type: string
- - name: amount
- type: number
- - name: category
- type: string
- edges:
- - type: ANNOUNCED
- source: Company
- target: FinancialEvent
+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)
+![CLI](../assets/cli.png)
+
```bash
he parse document.txt -o output/ -t template.yaml
```
@@ -55,14 +81,14 @@ he parse document.txt -o output/ -t template.yaml
from hyperextract import Template
# Create template from YAML
-ka = Template.from_yaml("template.yaml")
+ka = Template.create("template.yaml", "en")
# Parse document
result = ka.parse("Apple Inc. reported record quarterly revenue...")
# Access results
-print(result.nodes)
-print(result.edges)
+print(result.entities)
+print(result.relations)
```
## Step 5: View Results
diff --git a/docs/en/guides/domain-templates/finance.md b/docs/en/guides/domain-templates/finance.md
index 4dbecdf..e0580fb 100644
--- a/docs/en/guides/domain-templates/finance.md
+++ b/docs/en/guides/domain-templates/finance.md
@@ -9,14 +9,34 @@ Hyper-Extract provides specialized templates for financial document extraction.
Extract key financial metrics from earnings reports:
```yaml
-name: earnings_summary
-type: TemporalGraph
-schema:
- nodes:
- - type: FinancialMetric
- - type: Company
- edges:
- - type: REPORTED
+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}'
```
### Risk Factors
@@ -24,14 +44,31 @@ schema:
Extract risk factors from financial documents:
```yaml
-name: risk_factors
-type: List
-schema:
- item:
- - name: category
- type: string
- - name: description
- type: string
+language: en
+
+name: Risk Factor List
+type: list
+tags: [finance]
+
+description: 'Extract risk factor list.'
+
+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'
+ - 'Each risk factor includes category and description'
+
+display:
+ label: '{category}'
```
### Ownership Graph
@@ -39,14 +76,111 @@ schema:
Extract ownership relationships:
```yaml
-name: ownership_graph
-type: Graph
-schema:
- nodes:
- - type: Entity
- - type: Company
- edges:
- - type: OWNS
+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/organization)'
+ 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 expressed'
+
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{type}|{target}'
+ relation_members:
+ source: source
+ target: target
+
+display:
+ entity_label: '{name} ({type})'
+ relation_label: '{type}'
+```
+
+### Event Timeline
+
+Extract financial events and their temporal relationships:
+
+```yaml
+language: en
+
+name: Event Timeline
+type: temporal_graph
+tags: [finance]
+
+description: 'Extract financial events and their temporal relationships.'
+
+output:
+ entities:
+ fields:
+ - name: name
+ type: str
+ description: 'Event name'
+ - name: type
+ type: str
+ description: 'Event type'
+ relations:
+ fields:
+ - name: source
+ type: str
+ description: 'Source event'
+ - name: target
+ type: str
+ description: 'Target event'
+ - name: type
+ type: str
+ description: 'Relation type'
+ - name: time
+ type: str
+ description: 'Time'
+ required: false
+
+guideline:
+ target: 'Extract financial events and temporal relationships.'
+ rules_for_entities:
+ - 'Extract key financial events'
+ rules_for_relations:
+ - 'Extract temporal relationships between events'
+
+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}'
```
## Usage Examples
@@ -58,7 +192,10 @@ schema:
he parse earnings_report.pdf -t finance/earnings_summary -o output/
# Extract risk factors
-he parse 10k_filing.txt -t finance/risk_factors -o output/
+he parse 10k_filing.txt -t finance/risk_factor_set -o output/
+
+# Extract ownership relationships
+he parse ownership.txt -t finance/ownership_graph -o output/
```
### Python API
@@ -67,14 +204,13 @@ he parse 10k_filing.txt -t finance/risk_factors -o output/
from hyperextract import Template
# Load finance template
-ka = Template.create("finance/earnings_summary")
+ka = Template.create("finance/earnings_summary", "en")
# Extract from document
result = ka.parse(earnings_text)
-# Access financial metrics
-for metric in result.get_nodes("FinancialMetric"):
- print(f"{metric.name}: {metric.value}")
+# Access results
+print(result.fields)
```
## Supported Document Types
diff --git a/docs/en/guides/domain-templates/legal.md b/docs/en/guides/domain-templates/legal.md
index 3b1be44..789165a 100644
--- a/docs/en/guides/domain-templates/legal.md
+++ b/docs/en/guides/domain-templates/legal.md
@@ -9,16 +9,57 @@ Hyper-Extract provides specialized templates for legal document extraction.
Extract facts from court judgments:
```yaml
-name: case_facts
-type: TemporalGraph
-schema:
- nodes:
- - type: Party
- - type: Event
- - type: LegalFact
- edges:
- - type: PARTICIPATED_IN
- - type: OCCURRED_ON
+language: en
+
+name: Case Fact Timeline
+type: temporal_graph
+tags: [legal]
+
+description: 'Extract case facts from court judgments.'
+
+output:
+ entities:
+ fields:
+ - name: name
+ type: str
+ description: 'Entity name'
+ - name: type
+ type: str
+ description: 'Entity type (party/event/fact)'
+ relations:
+ fields:
+ - name: source
+ type: str
+ description: 'Source entity'
+ - name: target
+ type: str
+ description: 'Target entity'
+ - name: type
+ type: str
+ description: 'Relation type'
+ - name: time
+ type: str
+ description: 'Time'
+ required: false
+
+guideline:
+ target: 'Extract case facts.'
+ rules_for_entities:
+ - 'Extract parties and events'
+ rules_for_relations:
+ - 'Extract fact relationships'
+
+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}'
```
### Contract Terms
@@ -26,16 +67,34 @@ schema:
Extract contract obligations:
```yaml
-name: contract_terms
-type: List
-schema:
- item:
- - name: clause_type
- type: string
- - name: parties
- type: array
- - name: obligations
- type: string
+language: en
+
+name: Contract Terms List
+type: list
+tags: [legal]
+
+description: 'Extract contract terms.'
+
+output:
+ fields:
+ - name: clause_type
+ type: str
+ description: 'Clause type'
+ - name: parties
+ type: str
+ description: 'Parties involved'
+ - name: obligations
+ type: str
+ description: 'Obligation content'
+
+guideline:
+ target: 'Extract contract terms.'
+ rules:
+ - 'Extract all contract terms'
+ - 'Each term includes type, parties, and obligations'
+
+display:
+ label: '{clause_type}'
```
### Compliance Requirements
@@ -43,16 +102,87 @@ schema:
Extract compliance requirements:
```yaml
-name: compliance_requirements
-type: List
-schema:
- item:
- - name: regulation
- type: string
- - name: requirement
- type: string
- - name: deadline
- type: date
+language: en
+
+name: Compliance Requirements List
+type: list
+tags: [legal]
+
+description: 'Extract compliance requirements.'
+
+output:
+ fields:
+ - name: regulation
+ type: str
+ description: 'Regulation name'
+ - name: requirement
+ type: str
+ description: 'Compliance requirement'
+ - name: deadline
+ type: str
+ description: 'Deadline'
+ required: false
+
+guideline:
+ target: 'Extract compliance requirements.'
+ rules:
+ - 'Extract all compliance requirements'
+
+display:
+ label: '{regulation}'
+```
+
+### Case Citation
+
+Extract case citation relationships:
+
+```yaml
+language: en
+
+name: Case Citation Graph
+type: graph
+tags: [legal]
+
+description: 'Extract case citation relationships.'
+
+output:
+ entities:
+ fields:
+ - name: name
+ type: str
+ description: 'Case name'
+ - name: type
+ type: str
+ description: 'Case type'
+ relations:
+ fields:
+ - name: source
+ type: str
+ description: 'Citing case'
+ - name: target
+ type: str
+ description: 'Cited case'
+ - name: type
+ type: str
+ description: 'Citation type'
+
+guideline:
+ target: 'Extract case citation relationships.'
+ rules_for_entities:
+ - 'Extract case names'
+ rules_for_relations:
+ - 'Extract citation relationships between cases'
+
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{type}|{target}'
+ relation_members:
+ source: source
+ target: target
+
+display:
+ entity_label: '{name}'
+ relation_label: '{type}'
```
## Usage Examples
@@ -61,10 +191,13 @@ schema:
```bash
# Extract case facts
-he parse judgment.txt -t legal/case_facts -o output/
+he parse judgment.txt -t legal/case_fact_timeline -o output/
# Extract contract terms
-he parse contract.pdf -t legal/contract_terms -o output/
+he parse contract.pdf -t legal/contract_obligation -o output/
+
+# Extract compliance requirements
+he parse compliance.txt -t legal/compliance_list -o output/
```
### Python API
@@ -73,14 +206,13 @@ he parse contract.pdf -t legal/contract_terms -o output/
from hyperextract import Template
# Load legal template
-ka = Template.create("legal/case_facts")
+ka = Template.create("legal/case_fact_timeline", "en")
# Extract from document
result = ka.parse(judgment_text)
-# Access parties
-for party in result.get_nodes("Party"):
- print(f"Party: {party.name}")
+# Access results
+print(result.entities)
```
## Supported Document Types
diff --git a/docs/en/guides/domain-templates/medicine.md b/docs/en/guides/domain-templates/medicine.md
index 680d325..dfb9794 100644
--- a/docs/en/guides/domain-templates/medicine.md
+++ b/docs/en/guides/domain-templates/medicine.md
@@ -9,15 +9,52 @@ Hyper-Extract provides specialized templates for medical document extraction.
Extract drug interaction information:
```yaml
-name: drug_interactions
-type: Graph
-schema:
- nodes:
- - type: Drug
- - type: Interaction
- edges:
- - type: INTERACTS_WITH
- - type: CAUSES
+language: en
+
+name: Drug Interaction Graph
+type: graph
+tags: [medicine]
+
+description: 'Extract drug interaction information.'
+
+output:
+ entities:
+ fields:
+ - name: name
+ type: str
+ description: 'Drug name'
+ - name: type
+ type: str
+ description: 'Drug type'
+ relations:
+ fields:
+ - name: source
+ type: str
+ description: 'Source drug'
+ - name: target
+ type: str
+ description: 'Target drug'
+ - name: type
+ type: str
+ description: 'Interaction type'
+
+guideline:
+ target: 'Extract drug interactions.'
+ rules_for_entities:
+ - 'Extract drug names'
+ rules_for_relations:
+ - 'Extract interactions between drugs'
+
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{type}|{target}'
+ relation_members:
+ source: source
+ target: target
+
+display:
+ entity_label: '{name}'
+ relation_label: '{type}'
```
### Treatment Plan
@@ -25,33 +62,110 @@ schema:
Extract treatment plan details:
```yaml
-name: treatment_plan
-type: TemporalGraph
-schema:
- nodes:
- - type: Treatment
- - type: Medication
- - type: Procedure
- edges:
- - type: INCLUDES
- - type: SCHEDULED_FOR
+language: en
+
+name: Treatment Plan Timeline
+type: temporal_graph
+tags: [medicine]
+
+description: 'Extract treatment plan details.'
+
+output:
+ entities:
+ fields:
+ - name: name
+ type: str
+ description: 'Entity name'
+ - name: type
+ type: str
+ description: 'Type (treatment/medication/procedure)'
+ relations:
+ fields:
+ - name: source
+ type: str
+ description: 'Source entity'
+ - name: target
+ type: str
+ description: 'Target entity'
+ - name: type
+ type: str
+ description: 'Relation type'
+ - name: time
+ type: str
+ description: 'Time'
+ required: false
+
+guideline:
+ target: 'Extract treatment plan.'
+ rules_for_entities:
+ - 'Extract treatment plans and medications'
+ rules_for_relations:
+ - 'Extract treatment steps'
+
+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}'
```
-### Patient History
+### Anatomy Graph
-Extract patient medical history:
+Extract anatomy structure relationships:
```yaml
-name: patient_history
-type: TemporalGraph
-schema:
- nodes:
- - type: Condition
- - type: Treatment
- - type: Medication
- edges:
- - type: DIAGNOSED_ON
- - type: TREATED_WITH
+language: en
+
+name: Anatomy Structure Graph
+type: graph
+tags: [medicine]
+
+description: 'Extract anatomy structure relationships.'
+
+output:
+ entities:
+ fields:
+ - name: name
+ type: str
+ description: 'Anatomy structure name'
+ - name: type
+ type: str
+ description: 'Structure type'
+ relations:
+ fields:
+ - name: source
+ type: str
+ description: 'Source structure'
+ - name: target
+ type: str
+ description: 'Target structure'
+ - name: type
+ type: str
+ description: 'Relation type'
+
+guideline:
+ target: 'Extract anatomy structure relationships.'
+ rules_for_entities:
+ - 'Extract anatomy structures'
+ rules_for_relations:
+ - 'Extract relationships between structures'
+
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{type}|{target}'
+ relation_members:
+ source: source
+ target: target
+
+display:
+ entity_label: '{name}'
+ relation_label: '{type}'
```
## Usage Examples
@@ -60,10 +174,10 @@ schema:
```bash
# Extract drug interactions
-he parse clinical_note.txt -t medicine/drug_interactions -o output/
+he parse clinical_note.txt -t medicine/drug_interaction -o output/
# Extract treatment plan
-he parse discharge_summary.pdf -t medicine/treatment_plan -o output/
+he parse discharge_summary.pdf -t medicine/treatment_map -o output/
```
### Python API
@@ -72,14 +186,13 @@ he parse discharge_summary.pdf -t medicine/treatment_plan -o output/
from hyperextract import Template
# Load medicine template
-ka = Template.create("medicine/drug_interactions")
+ka = Template.create("medicine/drug_interaction", "en")
# Extract from document
result = ka.parse(clinical_text)
-# Access drug information
-for drug in result.get_nodes("Drug"):
- print(f"Drug: {drug.name}")
+# Access results
+print(result.entities)
```
## Supported Document Types
diff --git a/docs/en/guides/domain-templates/tcm.md b/docs/en/guides/domain-templates/tcm.md
index a6be952..5e04a51 100644
--- a/docs/en/guides/domain-templates/tcm.md
+++ b/docs/en/guides/domain-templates/tcm.md
@@ -9,17 +9,37 @@ Hyper-Extract provides specialized templates for Traditional Chinese Medicine (T
Extract properties of medicinal herbs:
```yaml
-name: herb_properties
-type: Model
-schema:
+language: en
+
+name: Herb Properties
+type: model
+tags: [tcm]
+
+description: 'Extract herb property information.'
+
+output:
+ fields:
- name: herb_name
- type: string
+ type: str
+ description: 'Herb name'
- name: properties
- type: array
+ type: str
+ description: 'Properties'
- name: channels
- type: array
+ type: str
+ description: 'Meridian channels'
- name: indications
- type: array
+ type: str
+ description: 'Indications'
+
+guideline:
+ target: 'Extract herb properties.'
+ rules:
+ - 'Extract herb name and properties'
+ - 'Keep original expressions'
+
+display:
+ label: '{herb_name}'
```
### Formula Composition
@@ -27,16 +47,35 @@ schema:
Extract herbal formula composition:
```yaml
-name: formula_composition
-type: List
-schema:
- item:
- - name: herb_name
- type: string
- - name: dosage
- type: string
- - name: role
- type: string
+language: en
+
+name: Formula Composition List
+type: list
+tags: [tcm]
+
+description: 'Extract formula composition.'
+
+output:
+ fields:
+ - name: herb_name
+ type: str
+ description: 'Herb name'
+ - name: dosage
+ type: str
+ description: 'Dosage'
+ - name: role
+ type: str
+ description: 'Role (jun/chen/zuo/shi)'
+ required: false
+
+guideline:
+ target: 'Extract formula composition.'
+ rules:
+ - 'Extract all herbs in the formula'
+ - 'Record dosage and role'
+
+display:
+ label: '{herb_name}'
```
### Meridian Graph
@@ -44,14 +83,52 @@ schema:
Extract meridian relationships:
```yaml
-name: meridian_graph
-type: Graph
-schema:
- nodes:
- - type: Herb
- - type: Meridian
- edges:
- - type: ENTERS
+language: en
+
+name: Meridian Relationship Graph
+type: graph
+tags: [tcm]
+
+description: 'Extract meridian relationships.'
+
+output:
+ entities:
+ fields:
+ - name: name
+ type: str
+ description: 'Entity name (herb/meridian)'
+ - name: type
+ type: str
+ description: 'Type'
+ 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 meridian relationships.'
+ rules_for_entities:
+ - 'Extract herbs and meridians'
+ rules_for_relations:
+ - 'Extract relationships of herbs entering meridians'
+
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{type}|{target}'
+ relation_members:
+ source: source
+ target: target
+
+display:
+ entity_label: '{name}'
+ relation_label: '{type}'
```
### Syndrome Reasoning
@@ -59,13 +136,51 @@ schema:
Extract syndrome diagnosis and reasoning:
```yaml
-name: syndrome_reasoning
-type: TemporalGraph
-schema:
- nodes:
- - type: Syndrome
- - type: Pattern
- - type: Treatment
+language: en
+
+name: Syndrome Reasoning Hypergraph
+type: hypergraph
+tags: [tcm]
+
+description: 'Extract syndrome diagnosis and reasoning.'
+
+output:
+ entities:
+ fields:
+ - name: name
+ type: str
+ description: 'Entity name'
+ - name: type
+ type: str
+ description: 'Type (syndrome/symptom/treatment)'
+ relations:
+ fields:
+ - name: syndrome
+ type: str
+ description: 'Syndrome name'
+ - name: symptoms
+ type: list
+ description: 'Related symptoms'
+ - name: treatment
+ type: str
+ description: 'Treatment method'
+ required: false
+
+guideline:
+ target: 'Extract syndrome diagnosis and reasoning.'
+ rules_for_entities:
+ - 'Extract syndromes and symptoms'
+ rules_for_relations:
+ - 'Extract relationships between syndrome and symptoms/treatment'
+
+identifiers:
+ entity_id: name
+ relation_id: '{syndrome}'
+ relation_members: symptoms
+
+display:
+ entity_label: '{name}'
+ relation_label: '{syndrome}'
```
## Usage Examples
@@ -74,10 +189,13 @@ schema:
```bash
# Extract herb properties
-he parse herbal_compendium.txt -t tcm/herb_properties -o output/
+he parse herbal_compendium.txt -t tcm/herb_property -o output/
# Extract formula composition
he parse prescription.txt -t tcm/formula_composition -o output/
+
+# Extract meridian relationships
+he parse meridian.txt -t tcm/meridian_graph -o output/
```
### Python API
@@ -86,15 +204,13 @@ he parse prescription.txt -t tcm/formula_composition -o output/
from hyperextract import Template
# Load TCM template
-ka = Template.create("tcm/herb_properties")
+ka = Template.create("tcm/herb_property", "en")
# Extract from document
result = ka.parse(herbal_text)
-# Access herb information
-for herb in result.get_nodes("Herb"):
- print(f"Herb: {herb.name}")
- print(f"Properties: {herb.properties}")
+# Access results
+print(result.fields)
```
## Supported Document Types
diff --git a/docs/en/guides/python-api.md b/docs/en/guides/python-api.md
index 2426540..6dcdc7c 100644
--- a/docs/en/guides/python-api.md
+++ b/docs/en/guides/python-api.md
@@ -1,209 +1,167 @@
# Python API
-This guide covers using Hyper-Extract in your Python applications.
+Hyper-Extract provides a Python API for programmatic extraction.
## Installation
```bash
-pip install hyper-extract
+pip install hyperextract
```
## Basic Usage
-### Import and Initialize
+### Load Preset Template
```python
from hyperextract import Template
-# Load a preset template
-ka = Template.create("general/biography")
-
-# Parse document
-result = ka.parse(text)
-```
-
-### Using Custom Templates
-
-```python
-from hyperextract import Template
-
-# Load from YAML
-ka = Template.from_yaml("template.yaml")
+# Load preset template
+ka = Template.create("general/graph", "en")
# Parse document
result = ka.parse(document_text)
# Access results
-print(result.nodes)
-print(result.edges)
+print(result.entities)
+print(result.relations)
```
-## Auto-Types
-
-### AutoModel
+### Load Custom Template
```python
-from hyperextract import AutoModel
-from pydantic import BaseModel
-
-class Person(BaseModel):
- name: str
- age: int
- occupation: str
-
-extractor = AutoModel(schema=Person)
-result = extractor.parse("John is a 30-year-old engineer.")
-```
-
-### AutoList
-
-```python
-from hyperextract import AutoList
-
-extractor = AutoList(item_type="string")
-result = extractor.parse("The ingredients are flour, sugar, and eggs.")
-print(result.items) # ["flour", "sugar", "eggs"]
-```
-
-### AutoGraph
-
-```python
-from hyperextract import AutoGraph
+from hyperextract import Template
-extractor = AutoGraph(
- node_types=["Person", "Organization"],
- edge_types=["WORKS_AT"]
-)
-result = extractor.parse("Alice works at Google.")
+# 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")
```
-### AutoHypergraph
+### Batch Processing
```python
-from hyperextract import AutoHypergraph
-
-extractor = AutoHypergraph()
-result = extractor.parse("Alice, Bob, and Carol collaborated.")
-```
-
-## Extraction Methods
+from hyperextract import Template
-### Using atom
+ka = Template.create("general/graph", "en")
-```python
-from hyperextract.methods import atom
+documents = ["Document 1 content...", "Document 2 content...", "Document 3 content..."]
-result = atom.extract(text, schema=MySchema)
+results = []
+for doc in documents:
+ result = ka.parse(doc)
+ results.append(result)
```
-### Using graph_rag
+### Export Results
```python
-from hyperextract.methods import graph_rag
+from hyperextract import Template
-result = graph_rag.extract(
- text,
- node_types=["Person", "Company"],
- edge_types=["WORKS_AT"]
-)
-```
+ka = Template.create("general/graph", "en")
+result = ka.parse(document_text)
-### Using cog_rag
+# Export to JSON
+json_output = result.to_json()
-```python
-from hyperextract.methods import cog_rag
+# Export to Dict
+dict_output = result.to_dict()
-result = cog_rag.extract(
- text,
- task="Extract causal relationships"
-)
+# Export to triples
+triples = result.to_triples()
```
-## Configuration
+## Template Creation
-### LLM Configuration
+### Create New Template
```python
-from hyperextract import Config
-
-config = Config(
- llm_provider="openai",
- llm_model="gpt-4o",
- api_key="your-api-key"
-)
-
-ka = Template.create("general/biography", config=config)
-```
-
-### Embedding Configuration
+from hyperextract import Template
-```python
-config = Config(
- embedding_provider="openai",
- embedding_model="text-embedding-3-small"
-)
+template = Template.create("template.yaml", "en")
```
-## Working with Results
-
-### Accessing Nodes
+### Save Template
```python
-result = ka.parse(text)
+from hyperextract import Template
-for node in result.nodes:
- print(f"{node.type}: {node.properties}")
+ka = Template.create("general/graph", "en")
+ka.save("my_template.yaml")
```
-### Accessing Edges
+## Configuration Options
-```python
-for edge in result.edges:
- print(f"{edge.source} --[{edge.type}]--> {edge.target}")
-```
-
-### Serialization
+### Set Language
```python
-# Save to JSON
-result.to_json("output.json")
+from hyperextract import Template
-# Save to YAML
-result.to_yaml("output.yaml")
+# Single language
+ka = Template.create("general/graph", "en")
-# Load from file
-loaded = Result.from_json("output.json")
+# Multiple languages
+ka = Template.create("general/graph", ["zh", "en"])
```
-## Advanced Usage
-
-### Custom Parsers
+### Set Model
```python
from hyperextract import Template
-from hyperextract.parsers import CustomParser
-class MyParser(CustomParser):
- def parse(self, text):
- # Custom parsing logic
- return processed_result
+# Use specified model
+ka = Template.create("general/graph", "en", model="gpt-4")
-ka = Template(parser=MyParser())
+# Use local model
+ka = Template.create("general/graph", "en", model="local-model")
```
-### Batch Processing
+## Error Handling
```python
from hyperextract import Template
-ka = Template.create("general/biography")
-
-documents = ["doc1.txt", "doc2.txt", "doc3.txt"]
-results = ka.batch_parse(documents)
+try:
+ ka = Template.create("template.yaml", "en")
+ result = ka.parse(document_text)
+except Exception as e:
+ print(f"Extraction failed: {e}")
```
## Next Steps
-- Explore [CLI](cli.md)
-- Browse [Domain Templates](domain-templates/index.md)
-- Check [Reference](../reference/index.md)
+- Browse [Preset Templates](../concepts/templates.md)
+- Explore [Domain Templates](./domain-templates/index.md)
diff --git a/docs/en/index.md b/docs/en/index.md
index 21e4dcd..07bf7ab 100644
--- a/docs/en/index.md
+++ b/docs/en/index.md
@@ -4,7 +4,9 @@
**Transform documents into knowledge abstracts — with just one command.**
-[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
+![Hero & Workflow](assets/hero-v2.jpg)
+
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Status](https://img.shields.io/badge/status-active-success)]()
@@ -70,6 +72,8 @@ result = ka.parse(annual_report_text)
## Architecture
+![Architecture](assets/architecture-v2.png)
+
The system is built on a robust triad: **Auto-Types** (Multi-typed structures), **Methods** (The Execution strategy), and **Templates** (Declarative schema).
## License
diff --git a/docs/en/resources/contributing.md b/docs/en/resources/contributing.md
index 193b97f..42cc39d 100644
--- a/docs/en/resources/contributing.md
+++ b/docs/en/resources/contributing.md
@@ -90,8 +90,7 @@ Documentation improvements are always welcome:
We welcome translation contributions:
1. Check the existing translations
-2. Follow the [Translation Guide](./translation-guide.md)
-3. Submit translations via PR
+2. Submit translations via PR
## Pull Request Guidelines
diff --git a/docs/en/resources/index.md b/docs/en/resources/index.md
new file mode 100644
index 0000000..1f9a9c8
--- /dev/null
+++ b/docs/en/resources/index.md
@@ -0,0 +1,15 @@
+# Resources
+
+Additional resources and information.
+
+## FAQ
+
+Frequently asked questions about Hyper-Extract.
+
+## Troubleshooting
+
+Solutions to common issues.
+
+## Contributing
+
+Guidelines for contributing to the project.
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
deleted file mode 100644
index 94fd02a..0000000
--- a/docs/stylesheets/extra.css
+++ /dev/null
@@ -1,75 +0,0 @@
-/* Hyper-Extract Documentation Custom Styles */
-
-:root {
- --hyper-extract-primary: #6366f1;
- --hyper-extract-accent: #818cf8;
- --hyper-extract-light: #e0e7ff;
-}
-
-.md-typeset h1 {
- color: var(--hyper-extract-primary);
- font-weight: 700;
-}
-
-.md-typeset h2 {
- color: var(--hyper-extract-primary);
- font-weight: 600;
-}
-
-.md-typeset h3 {
- color: var(--hyper-extract-accent);
- font-weight: 600;
-}
-
-.md-typeset .highlight {
- border-radius: 8px;
- border: 1px solid rgba(99, 102, 241, 0.2);
-}
-
-.md-typeset :is(.admonition):is(.tip) {
- border-left-color: var(--hyper-extract-primary);
-}
-
-.md-typeset :is(.admonition):is(.note) {
- border-left-color: var(--hyper-extract-accent);
-}
-
-.md-typeset :is(.admonition):is(.warning) {
- border-left-color: #f59e0b;
-}
-
-.md-typeset :is(.admonition):is(.danger) {
- border-left-color: #ef4444;
-}
-
-.md-nav__link--active {
- color: var(--hyper-extract-primary);
- font-weight: 600;
-}
-
-.md-search__input:focus {
- border-color: var(--hyper-extract-primary);
-}
-
-.md-header {
- background: linear-gradient(135deg, var(--hyper-extract-primary) 0%, var(--hyper-extract-accent) 100%);
-}
-
-.md-typeset code {
- border-radius: 4px;
- padding: 2px 6px;
- background-color: var(--hyper-extract-light);
- color: var(--hyper-extract-primary);
-}
-
-@media print {
- .md-header,
- .md-nav,
- .md-sidebar {
- display: none;
- }
-
- .md-main__inner {
- margin-left: 0;
- }
-}
diff --git a/docs/zh/concepts/auto-types.md b/docs/zh/concepts/auto-types.md
index 10a09b4..a34d227 100644
--- a/docs/zh/concepts/auto-types.md
+++ b/docs/zh/concepts/auto-types.md
@@ -1,113 +1,129 @@
-# 自动类型
+# 自动类型 (AutoTypes)
-Hyper-Extract 提供 8 种自动类型用于表示知识。每种类型都针对特定的提取场景进行了优化。
+Hyper-Extract 使用自动类型来确定提取模式,共支持 8 种类型。
-## 概览
+## 类型概览
-| 类型 | 模块 | 描述 |
-|------|------|------|
-| AutoModel | `hyperextract.types.model` | Pydantic 模型提取 |
-| AutoList | `hyperextract.types.list` | 列表/集合提取 |
-| AutoSet | `hyperextract.types.set` | 唯一集合提取 |
-| AutoGraph | `hyperextract.types.graph` | 知识图谱提取 |
-| AutoHypergraph | `hyperextract.types.hypergraph` | 超图提取 |
-| AutoTemporalGraph | `hyperextract.types.temporal_graph` | 时序知识图谱 |
-| AutoSpatialGraph | `hyperextract.types.spatial_graph` | 空间知识图谱 |
-| AutoSpatioTemporalGraph | `hyperextract.types.spatio_temporal_graph` | 时空图 |
+| 类型 | 说明 | 使用场景 |
+|------|------|---------|
+| `model` | 单个结构化对象 | 提取单一记录 |
+| `list` | 有序列表 | 提取排序项目 |
+| `set` | 去重集合 | 提取唯一实体 |
+| `graph` | 二元关系图 | 提取实体关系 |
+| `hypergraph` | 多元关系图 | 提取多方关系 |
+| `temporal_graph` | 时序图 | 添加时间维度 |
+| `spatial_graph` | 空间图 | 添加空间维度 |
+| `spatio_temporal_graph` | 时空图 | 添加时间和空间 |
-## 使用示例
+## 选择决策树
-### AutoModel
+```
+需要关系?
+├─ 否 → 记录类型
+│ ├─ 单个对象 → model
+│ ├─ 有序列表 → list
+│ └─ 去重集合 → set
+└─ 是 → 图类型
+ ├─ 二元关系 (A→B) → graph
+ └─ 多元关系 (A+B+C→D) → hypergraph
+
++ 时间维度 → temporal_graph
++ 空间维度 → spatial_graph
++ 两者都有 → spatio_temporal_graph
+```
+
+## 详细说明
-提取到 Pydantic 模型的结构化数据:
+### Model
+
+用于提取单个结构化对象。
```python
-from hyperextract import AutoModel
-from pydantic import BaseModel
+from hyperextract import Template
-class Person(BaseModel):
- name: str
- age: int
- occupation: str
+ka = Template.create("finance/earnings_summary", "zh")
+result = ka.parse(text)
-extractor = AutoModel(schema=Person)
-result = extractor.parse("John Smith 是一位 35 岁的软件工程师。")
+print(result.fields["company_name"])
+print(result.fields["revenue"])
```
-### AutoList
+### List
-提取项目列表:
+用于提取有序列表。
```python
-from hyperextract import AutoList
+from hyperextract import Template
+
+ka = Template.create("finance/risk_factor_set", "zh")
+result = ka.parse(text)
-extractor = AutoList(item_type="string")
-result = extractor.parse("配料包括面粉、糖、鸡蛋和牛奶。")
-# result: ["面粉", "糖", "鸡蛋", "牛奶"]
+for item in result.fields:
+ print(item)
```
-### AutoGraph
+### Set
-提取知识图谱:
+用于提取去重集合。
```python
-from hyperextract import AutoGraph
+from hyperextract import Template
+
+ka = Template.create("general/entity_registry", "zh")
+result = ka.parse(text)
-extractor = AutoGraph(node_types=["Person", "Organization"], edge_types=["WORKS_AT"])
-result = extractor.parse("Alice 在 Google 工作。")
-# result: 包含节点和边的图
+for entity in result.fields:
+ print(entity)
```
-### AutoHypergraph
+### Graph
-提取超图(连接多个节点的边):
+用于提取二元关系。
```python
-from hyperextract import AutoHypergraph
+from hyperextract import Template
-extractor = AutoHypergraph()
-result = extractor.parse("Alice、Bob 和 Carol 合作完成了 X 项目。")
+ka = Template.create("finance/ownership_graph", "zh")
+result = ka.parse(text)
+
+for entity in result.entities:
+ print(f"{entity['name']} ({entity['type']})")
+
+for relation in result.relations:
+ print(f"{relation['source']} --[{relation['type']}]--> {relation['target']}")
```
-### AutoTemporalGraph
+### Hypergraph
-提取带有时间信息的图谱:
+用于提取多元关系。
```python
-from hyperextract import AutoTemporalGraph
+from hyperextract import Template
-extractor = AutoTemporalGraph()
-result = extractor.parse("周一,Alice 加入 Google。周二,她开始工作。")
-```
+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']}")
+```
-### 何时使用 AutoModel
-- 需要结构化、经验证的输出
-- 使用定义良好的模式
-- 想要 Pydantic 验证
+### Temporal Graph
-### 何时使用 AutoList
-- 提取项目集合
-- 顺序重要
-- 简单项目提取
+用于提取带时间的关系。
-### 何时使用 AutoSet
-- 只需要唯一项
-- 不关心顺序
-- 需要去重
+```python
+from hyperextract import Template
-### 何时使用 AutoGraph
-- 实体之间的复杂关系
-- 知识图谱
-- 网络分析
+ka = Template.create("finance/event_timeline", "zh")
+result = ka.parse(text)
-### 何时使用 Temporal/Spatial 变体
-- 时间感知:使用 `AutoTemporalGraph`
-- 位置感知:使用 `AutoSpatialGraph`
-- 两者都需要:使用 `AutoSpatioTemporalGraph`
+for relation in result.relations:
+ print(f"{relation['source']} --[{relation['type']}]--> {relation['target']} @ {relation['time']}")
+```
## 下一步
-- 了解 [提取方法](methods.md)
-- 探索 [模板](templates.md)
+- 了解 [模板](./templates.md)
+- 查看 [预设模板](./templates.md)
+- 浏览 [领域模板](../guides/domain-templates/index.md)
diff --git a/docs/zh/concepts/index.md b/docs/zh/concepts/index.md
index b27326b..64a079a 100644
--- a/docs/zh/concepts/index.md
+++ b/docs/zh/concepts/index.md
@@ -1,52 +1,52 @@
# 核心概念
-本节解释 Hyper-Extract 的核心概念。
+## 概述
-## 本节内容
-
-- [自动类型](auto-types.md) - 用于知识表示的 8 种数据结构
-- [提取方法](methods.md) - 10+ 种知识提取引擎
-- [模板](templates.md) - 用于提取的声明式 YAML 模式
+Hyper-Extract 是一个知识提取框架,可从各种文档中提取结构化知识。本文档介绍核心概念,帮助您理解系统的工作原理。
## 核心概念
-### 自动类型
+### 模板 (Template)
+
+模板使用 YAML 定义要提取的内容,提供声明式的方式来指定提取模式,无需编写代码。
+
+详细了解:[模板](./templates.md)
+
+### 自动类型 (AutoType)
+
+Hyper-Extract 支持 8 种自动类型,每种类型针对不同的提取场景:
-Hyper-Extract 提供 8 种自动类型,从简单的集合到复杂的图:
+| 类型 | 说明 | 使用场景 |
+|------|------|---------|
+| `model` | 单个结构化对象 | 提取单一记录 |
+| `list` | 有序列表 | 提取排序项目 |
+| `set` | 去重集合 | 提取唯一实体 |
+| `graph` | 二元关系图 | 提取实体关系 |
+| `hypergraph` | 多元关系图 | 提取多方关系 |
+| `temporal_graph` | 时序图 | 添加时间维度 |
+| `spatial_graph` | 空间图 | 添加空间维度 |
+| `spatio_temporal_graph` | 时空图 | 添加时间和空间 |
-| 类型 | 用例 |
-|------|------|
-| AutoModel | 结构化数据提取 |
-| AutoList | 列表/集合提取 |
-| AutoSet | 唯一项提取 |
-| AutoGraph | 知识图谱提取 |
-| AutoHypergraph | 复杂关系提取 |
-| AutoTemporalGraph | 时序知识图谱 |
-| AutoSpatialGraph | 空间知识图谱 |
-| AutoSpatioTemporalGraph | 时空知识图谱 |
+详细了解:[自动类型](./auto-types.md)
-### 提取方法
+### 提取方法 (Methods)
-选择适合您提取任务的方法:
+Hyper-Extract 支持多种提取方法:
-| 方法 | 最佳用途 |
-|------|----------|
-| atom | 简单、直接的提取 |
-| graph_rag | 基于图的检索 |
-| light_rag | 轻量级检索 |
-| hyper_rag | 超图提取 |
-| cog_rag | 认知检索 |
+- **本地模型**:使用本地部署的模型
+- **API 模型**:使用云端 API(如 OpenAI、Claude)
+- **混合模式**:结合多种方法
-### 模板
+详细了解:[提取方法](./methods.md)
-模板使用声明式 YAML 定义要提取的内容。它们提供:
+## 快速开始
-- 类型安全的模式
-- 验证规则
-- 自定义提取逻辑
+1. [安装](../getting-started/installation.md)
+2. [快速教程](../getting-started/quickstart.md)
+3. [模板设计](./templates.md)
-## 了解更多
+## 下一步
-- [自动类型](auto-types.md) - 深入了解每种类型
-- [方法](methods.md) - 比较提取方法
-- [模板](templates.md) - 创建自定义模板
+- 浏览 [模板库](../reference/template-gallery.md)
+- 查看 [领域模板](../guides/domain-templates/index.md)
+- 了解 [Python API](../guides/python-api.md)
diff --git a/docs/zh/concepts/templates.md b/docs/zh/concepts/templates.md
index 4c385e9..62102e3 100644
--- a/docs/zh/concepts/templates.md
+++ b/docs/zh/concepts/templates.md
@@ -1,156 +1,571 @@
# 模板
-模板使用声明式 YAML 定义要提取的内容。它们提供了一种强大的方式来指定提取模式,无需编写代码。
+模板使用声明式 YAML 定义要提取的内容,提供了一种强大的方式来指定提取模式,无需编写代码。
-## 模板结构
+## 类型选择
-模板由以下部分组成:
+![Knowledge Structures Matrix](../assets/8-types-v2.png)
-1. **元数据**: name、description、author
-2. **类型**: 提取类型(Graph、List、Model 等)
-3. **模式**: 节点、边和字段的定义
+在设计模板之前,先确定哪种类型适合您的需求:
-## 基本示例
+```
+需要关系?
+├─ 否 → 记录类型 (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
-name: 事件时间线
-description: 提取财务事件及其时间关系
-type: TemporalGraph
-schema:
- nodes:
- - type: Event
- properties:
- - name: description
- type: string
- - name: date
- type: string
- edges:
- - type: TIMELINE
- source: Event
- target: Event
- properties:
- - name: relation
- type: string
+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
-type: Graph
-schema:
- nodes:
- - type: Person
- - type: Organization
- edges:
- - type: WORKS_AT
- source: Person
- target: Organization
+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
-type: List
-schema:
- item:
- - name: ingredient
- type: string
- - name: quantity
- type: string
+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
-type: Model
-schema:
- - name: product_name
- type: string
- required: true
- - name: price
- type: float
- required: true
+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` 来定义去重键。
-| 类型 | 描述 | 示例 |
-|------|------|------|
-| string | 文本值 | "你好世界" |
-| integer | 整数 | 42 |
-| float | 小数 | 3.14 |
-| boolean | 布尔值 | true |
-| date | 日期值 | 2024-01-15 |
-| array | 值列表 | ["a", "b", "c"] |
+---
+
+## 图类型
+
+图类型提取实体及其关系。使用 `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
-- name: email
- type: string
- pattern: "^[a-zA-Z0-9._%+-]+@[a-z]+.[a-z]{2,}$"
+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
-- name: status
- type: string
- enum: [pending, active, completed]
+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
-- name: end_date
- type: date
- required_if: type == "event"
+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`
-- `finance/risk_factors`
-- `finance/ownership_graph`
+- `finance/earnings_summary` (model)
+- `finance/risk_factor_set` (set)
+- `finance/ownership_graph` (graph)
+- `finance/event_timeline` (temporal_graph)
### 法律
-- `legal/case_facts`
-- `legal/contract_terms`
-- `legal/compliance_requirements`
+- `legal/case_fact_timeline` (temporal_graph)
+- `legal/case_citation` (graph)
+- `legal/contract_obligation` (list)
### 医学
-- `medicine/drug_interactions`
-- `medicine/treatment_plan`
-- `medicine/patient_history`
+- `medicine/drug_interaction` (graph)
+- `medicine/treatment_map` (temporal_graph)
+- `medicine/discharge_instruction` (list)
### 中医
-- `tcm/herb_properties`
-- `tcm/formula_composition`
-- `tcm/syndrome_reasoning`
+- `tcm/herb_property` (model)
+- `tcm/formula_composition` (list)
+- `tcm/meridian_graph` (graph)
### 工业
-- `industry/safety_controls`
-- `industry/equipment_topology`
-- `industry/operation_flow`
+- `industry/safety_control` (list)
+- `industry/equipment_topology` (graph)
+- `industry/failure_case` (temporal_graph)
### 通用
-- `general/biography`
-- `general/concepts`
-- `general/workflow`
+- `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/earnings_summary
+# 使用预设模板
+he parse document.txt -t finance/ownership_graph -o output/
+
+# 使用自定义模板
+he parse document.txt -t template.yaml -o output/
```
### Python API
@@ -158,15 +573,21 @@ he parse document.txt -t finance/earnings_summary
```python
from hyperextract import Template
-# 加载预设
-ka = Template.create("finance/earnings_summary")
+# 加载预设模板
+ka = Template.create("finance/ownership_graph", "zh")
+
+# 从 YAML 加载
+ka = Template.create("template.yaml", "zh")
-# 加载自定义模板
-ka = Template.from_yaml("my_template.yaml")
+# 解析文档
+result = ka.parse(document_text)
```
+---
+
## 下一步
-- 浏览[模板库](../reference/template-gallery.md)
+- 浏览[模板库](../../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.md
index 14c3831..bb4bc31 100644
--- a/docs/zh/getting-started/configuration.md
+++ b/docs/zh/getting-started/configuration.md
@@ -1,76 +1,60 @@
# 配置
-本指南介绍 Hyper-Extract 的高级配置选项。
+Hyper-Extract 使用 TOML 配置文件。默认位置:`~/.he/config.toml`
-## 配置文件
+## 快速配置
-Hyper-Extract 使用 YAML 配置文件。默认位置:`~/.hyper-extract/config.yaml`
+```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 设置
-```yaml
-llm:
- provider: openai # openai, anthropic, azure 等
- model: gpt-4o
- api_key: ${OPENAI_API_KEY} # 或使用环境变量
- temperature: 0.0
- max_tokens: 4096
-```
-
-### Embedding 设置
-
-```yaml
-embedding:
- provider: openai # openai, huggingface 等
- model: text-embedding-3-small
- api_key: ${OPENAI_API_KEY}
+```bash
+he config llm --api-key YOUR_KEY --model gpt-4o-mini
```
-### 提取设置
-
-```yaml
-extraction:
- default_type: AutoGraph
- max_retries: 3
- timeout: 60
- batch_size: 10
-```
+| 选项 | 说明 | 默认值 |
+|------|------|---------|
+| `--api-key`, `-k` | LLM API 密钥 | 必需 |
+| `--model`, `-m` | 模型名称 | gpt-4o-mini |
+| `--base-url`, `-u` | 自定义 API 基础 URL | (默认) |
-### 存储设置
+### Embedder 设置
-```yaml
-storage:
- type: local # local, s3 等
- path: ./output
- format: json # json, yaml, parquet
+```bash
+he config embedder --api-key YOUR_KEY --model text-embedding-3-small
```
-## 环境变量
-
-| 变量 | 描述 |
-|------|------|
-| `OPENAI_API_KEY` | OpenAI API 密钥 |
-| `ANTHROPIC_API_KEY` | Anthropic API 密钥 |
-| `HYPER_EXTRACT_CONFIG` | 配置文件路径 |
+| 选项 | 说明 | 默认值 |
+|------|------|---------|
+| `--api-key`, `-k` | Embedder API 密钥 | 必需 |
+| `--model`, `-m` | 模型名称 | text-embedding-3-small |
+| `--base-url`, `-u` | 自定义 API 基础 URL | (默认) |
-## CLI 配置
-
-通过 CLI 初始化配置:
+## 查看配置
```bash
-# 使用 OpenAI 初始化
-he config init -k your-api-key
-
-# 显示当前配置
he config show
-
-# 更新特定选项
-he config set llm.model gpt-4o-mini
```
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `he config init -k KEY` | 使用 API 密钥初始化 LLM 和 Embedder |
+| `he config llm` | 配置 LLM 设置 |
+| `he config embedder` | 配置 Embedder 设置 |
+| `he config show` | 显示当前配置 |
+
## 下一步
-- 探索[核心概念](../concepts/index.md) 了解提取类型
-- 查看 [CLI 参考](../reference/cli-reference.md) 了解所有命令
+- 了解[模板](../concepts/templates.md)
+- 浏览[预设模板](../concepts/templates.md#preset-templates)
diff --git a/docs/zh/getting-started/installation.md b/docs/zh/getting-started/installation.md
index 99539c2..d61a91b 100644
--- a/docs/zh/getting-started/installation.md
+++ b/docs/zh/getting-started/installation.md
@@ -1,69 +1,24 @@
# 安装
-本指南介绍如何安装 Hyper-Extract 及其依赖项。
-
## 系统要求
-- Python 3.9+
-- pip 或 uv 包管理器
-- OpenAI API 密钥(或兼容的 LLM API)
+- Python 3.11+
## 安装方法
-### 使用 pip
-
-```bash
-pip install hyper-extract
-```
-
-### 使用 uv
+### 使用 uv(推荐)
```bash
uv pip install hyper-extract
```
-## 额外依赖安装
-
-针对特定用例安装额外依赖:
-
-```bash
-# 安装所有集成
-pip install hyper-extract[all]
-
-# 安装 OpenAI 支持
-pip install hyper-extract[openai]
-
-# 安装开发工具
-pip install hyper-extract[dev]
-```
-
-## 验证安装
-
-安装后,验证是否正常工作:
-
-```bash
-he --version
-```
-
-您应该看到版本号。
-
-## 设置 API 密钥
-
-Hyper-Extract 需要 LLM 服务的 API 密钥。设置方法:
-
-### 使用环境变量
-
-```bash
-export OPENAI_API_KEY=your-api-key-here
-```
-
-### 使用 CLI
+### 使用 pip
```bash
-he config init -k your-api-key-here
+pip install hyper-extract
```
## 下一步
-- 继续学习[快速教程](quickstart.md) 运行您的第一次提取
-- 或在[配置](configuration.md)中配置高级选项
+- [快速教程](getting-started/quickstart.md) - 运行您的第一次提取
+- [配置](getting-started/configuration.md) - 配置 API 设置
diff --git a/docs/zh/getting-started/quickstart.md b/docs/zh/getting-started/quickstart.md
index a9add0c..3e0f16f 100644
--- a/docs/zh/getting-started/quickstart.md
+++ b/docs/zh/getting-started/quickstart.md
@@ -18,33 +18,59 @@ CEO Tim Cook 宣布公司实现了史上最强的 iPhone 销量。
Hyper-Extract 使用 YAML 模板来定义要提取的内容。创建 `template.yaml`:
```yaml
+language: zh
+
name: 公司新闻摘要
-description: 从新闻文章中提取关键财务事件
-type: TemporalGraph
-schema:
- nodes:
- - type: Company
- properties:
- - name: name
- type: string
- - name: ticker
- type: string
- - type: FinancialEvent
- properties:
- - name: description
- type: string
- - name: amount
- type: number
- - name: category
- type: string
- edges:
- - type: ANNOUNCED
- source: Company
- target: FinancialEvent
+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)
+![CLI](../assets/cli.png)
+
```bash
he parse document.txt -o output/ -t template.yaml
```
@@ -55,14 +81,14 @@ he parse document.txt -o output/ -t template.yaml
from hyperextract import Template
# 从 YAML 创建模板
-ka = Template.from_yaml("template.yaml")
+ka = Template.create("template.yaml", "zh")
# 解析文档
result = ka.parse("Apple Inc. 报告创纪录的季度收入...")
# 访问结果
-print(result.nodes)
-print(result.edges)
+print(result.entities)
+print(result.relations)
```
## 第五步:查看结果
diff --git a/docs/zh/guides/domain-templates/finance.md b/docs/zh/guides/domain-templates/finance.md
index 36f59a4..d70d5ec 100644
--- a/docs/zh/guides/domain-templates/finance.md
+++ b/docs/zh/guides/domain-templates/finance.md
@@ -9,14 +9,34 @@ Hyper-Extract 提供专门的金融文档提取模板。
从财报中提取关键财务指标:
```yaml
-name: earnings_summary
-type: TemporalGraph
-schema:
- nodes:
- - type: FinancialMetric
- - type: Company
- edges:
- - type: REPORTED
+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}'
```
### 风险因素
@@ -24,14 +44,31 @@ schema:
从金融文档中提取风险因素:
```yaml
-name: risk_factors
-type: List
-schema:
- item:
- - name: category
- type: string
- - name: description
- type: string
+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}'
```
### 所有权图
@@ -39,14 +76,111 @@ schema:
提取所有权关系:
```yaml
-name: ownership_graph
-type: Graph
-schema:
- nodes:
- - type: Entity
- - type: Company
- edges:
- - type: OWNS
+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}'
+```
+
+### 事件时序图
+
+提取财务事件及其时间关系:
+
+```yaml
+language: zh
+
+name: 事件时序图
+type: temporal_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: '关系类型'
+ - name: time
+ type: str
+ description: '时间'
+ required: false
+
+guideline:
+ target: '提取财务事件和时间关系。'
+ rules_for_entities:
+ - '提取关键财务事件'
+ rules_for_relations:
+ - '提取事件之间的时间关系'
+
+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}'
```
## 使用示例
@@ -58,7 +192,10 @@ schema:
he parse earnings_report.pdf -t finance/earnings_summary -o output/
# 提取风险因素
-he parse 10k_filing.txt -t finance/risk_factors -o output/
+he parse 10k_filing.txt -t finance/risk_factor_set -o output/
+
+# 提取所有权关系
+he parse ownership.txt -t finance/ownership_graph -o output/
```
### Python API
@@ -67,14 +204,13 @@ he parse 10k_filing.txt -t finance/risk_factors -o output/
from hyperextract import Template
# 加载金融模板
-ka = Template.create("finance/earnings_summary")
+ka = Template.create("finance/earnings_summary", "zh")
# 从文档提取
result = ka.parse(earnings_text)
-# 访问财务指标
-for metric in result.get_nodes("FinancialMetric"):
- print(f"{metric.name}: {metric.value}")
+# 访问结果
+print(result.fields)
```
## 支持的文档类型
diff --git a/docs/zh/guides/domain-templates/legal.md b/docs/zh/guides/domain-templates/legal.md
index cba57d5..a4c8ce1 100644
--- a/docs/zh/guides/domain-templates/legal.md
+++ b/docs/zh/guides/domain-templates/legal.md
@@ -9,16 +9,57 @@ Hyper-Extract 提供专门的法律文档提取模板。
从判决书中提取事实:
```yaml
-name: case_facts
-type: TemporalGraph
-schema:
- nodes:
- - type: Party
- - type: Event
- - type: LegalFact
- edges:
- - type: PARTICIPATED_IN
- - type: OCCURRED_ON
+language: zh
+
+name: 案件事实时序图
+type: temporal_graph
+tags: [legal]
+
+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: '关系类型'
+ - name: time
+ type: str
+ description: '时间'
+ required: false
+
+guideline:
+ target: '提取案件事实。'
+ rules_for_entities:
+ - '提取当事人和事件'
+ rules_for_relations:
+ - '提取事实关系'
+
+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}'
```
### 合同条款
@@ -26,16 +67,34 @@ schema:
提取合同义务:
```yaml
-name: contract_terms
-type: List
-schema:
- item:
- - name: clause_type
- type: string
- - name: parties
- type: array
- - name: obligations
- type: string
+language: zh
+
+name: 合同条款列表
+type: list
+tags: [legal]
+
+description: '提取合同条款。'
+
+output:
+ fields:
+ - name: clause_type
+ type: str
+ description: '条款类型'
+ - name: parties
+ type: str
+ description: '涉及方'
+ - name: obligations
+ type: str
+ description: '义务内容'
+
+guideline:
+ target: '提取合同条款。'
+ rules:
+ - '提取所有合同条款'
+ - '每个条款包含类型、涉及方和义务'
+
+display:
+ label: '{clause_type}'
```
### 合规要求
@@ -43,16 +102,87 @@ schema:
提取合规要求:
```yaml
-name: compliance_requirements
-type: List
-schema:
- item:
- - name: regulation
- type: string
- - name: requirement
- type: string
- - name: deadline
- type: date
+language: zh
+
+name: 合规要求列表
+type: list
+tags: [legal]
+
+description: '提取合规要求。'
+
+output:
+ fields:
+ - name: regulation
+ type: str
+ description: '法规名称'
+ - name: requirement
+ type: str
+ description: '合规要求'
+ - name: deadline
+ type: str
+ description: '截止日期'
+ required: false
+
+guideline:
+ target: '提取合规要求。'
+ rules:
+ - '提取所有合规要求'
+
+display:
+ label: '{regulation}'
+```
+
+### 案件引用
+
+提取案件引用关系:
+
+```yaml
+language: zh
+
+name: 案件引用图谱
+type: graph
+tags: [legal]
+
+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}'
+ relation_label: '{type}'
```
## 使用示例
@@ -61,10 +191,13 @@ schema:
```bash
# 提取案件事实
-he parse judgment.txt -t legal/case_facts -o output/
+he parse judgment.txt -t legal/case_fact_timeline -o output/
# 提取合同条款
-he parse contract.pdf -t legal/contract_terms -o output/
+he parse contract.pdf -t legal/contract_obligation -o output/
+
+# 提取合规要求
+he parse compliance.txt -t legal/compliance_list -o output/
```
### Python API
@@ -73,14 +206,13 @@ he parse contract.pdf -t legal/contract_terms -o output/
from hyperextract import Template
# 加载法律模板
-ka = Template.create("legal/case_facts")
+ka = Template.create("legal/case_fact_timeline", "zh")
# 从文档提取
result = ka.parse(judgment_text)
-# 访问当事人
-for party in result.get_nodes("Party"):
- print(f"Party: {party.name}")
+# 访问结果
+print(result.entities)
```
## 支持的文档类型
diff --git a/docs/zh/guides/domain-templates/medicine.md b/docs/zh/guides/domain-templates/medicine.md
index 9a3563a..e541e6c 100644
--- a/docs/zh/guides/domain-templates/medicine.md
+++ b/docs/zh/guides/domain-templates/medicine.md
@@ -9,15 +9,52 @@ Hyper-Extract 提供专门的医疗文档提取模板。
提取药物相互作用信息:
```yaml
-name: drug_interactions
-type: Graph
-schema:
- nodes:
- - type: Drug
- - type: Interaction
- edges:
- - type: INTERACTS_WITH
- - type: CAUSES
+language: zh
+
+name: 药物相互作用图谱
+type: graph
+tags: [medicine]
+
+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}'
+ relation_label: '{type}'
```
### 治疗计划
@@ -25,33 +62,110 @@ schema:
提取治疗计划详情:
```yaml
-name: treatment_plan
-type: TemporalGraph
-schema:
- nodes:
- - type: Treatment
- - type: Medication
- - type: Procedure
- edges:
- - type: INCLUDES
- - type: SCHEDULED_FOR
+language: zh
+
+name: 治疗计划时序图
+type: temporal_graph
+tags: [medicine]
+
+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: '关系类型'
+ - name: time
+ type: str
+ description: '时间'
+ required: false
+
+guideline:
+ target: '提取治疗计划。'
+ rules_for_entities:
+ - '提取治疗方案和药物'
+ rules_for_relations:
+ - '提取治疗步骤'
+
+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}'
```
-### 患者病史
+### 解剖图
-提取患者病史:
+提取解剖结构关系:
```yaml
-name: patient_history
-type: TemporalGraph
-schema:
- nodes:
- - type: Condition
- - type: Treatment
- - type: Medication
- edges:
- - type: DIAGNOSED_ON
- - type: TREATED_WITH
+language: zh
+
+name: 解剖结构图谱
+type: graph
+tags: [medicine]
+
+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}'
+ relation_label: '{type}'
```
## 使用示例
@@ -60,10 +174,10 @@ schema:
```bash
# 提取药物相互作用
-he parse clinical_note.txt -t medicine/drug_interactions -o output/
+he parse clinical_note.txt -t medicine/drug_interaction -o output/
# 提取治疗计划
-he parse discharge_summary.pdf -t medicine/treatment_plan -o output/
+he parse discharge_summary.pdf -t medicine/treatment_map -o output/
```
### Python API
@@ -72,14 +186,13 @@ he parse discharge_summary.pdf -t medicine/treatment_plan -o output/
from hyperextract import Template
# 加载医学模板
-ka = Template.create("medicine/drug_interactions")
+ka = Template.create("medicine/drug_interaction", "zh")
# 从文档提取
result = ka.parse(clinical_text)
-# 访问药物信息
-for drug in result.get_nodes("Drug"):
- print(f"Drug: {drug.name}")
+# 访问结果
+print(result.entities)
```
## 支持的文档类型
diff --git a/docs/zh/guides/domain-templates/tcm.md b/docs/zh/guides/domain-templates/tcm.md
index 80f2929..55de6bb 100644
--- a/docs/zh/guides/domain-templates/tcm.md
+++ b/docs/zh/guides/domain-templates/tcm.md
@@ -9,17 +9,37 @@ Hyper-Extract 提供专门的中医(Traditional Chinese Medicine)文档提
提取中药属性:
```yaml
-name: herb_properties
-type: Model
-schema:
+language: zh
+
+name: 中药属性
+type: model
+tags: [tcm]
+
+description: '提取中药属性信息。'
+
+output:
+ fields:
- name: herb_name
- type: string
+ type: str
+ description: '中药名称'
- name: properties
- type: array
+ type: str
+ description: '药性'
- name: channels
- type: array
+ type: str
+ description: '归经'
- name: indications
- type: array
+ type: str
+ description: '功效主治'
+
+guideline:
+ target: '提取中药属性。'
+ rules:
+ - '提取中药名称和属性'
+ - '保持原文表述'
+
+display:
+ label: '{herb_name}'
```
### 方剂组成
@@ -27,16 +47,35 @@ schema:
提取方剂组成:
```yaml
-name: formula_composition
-type: List
-schema:
- item:
- - name: herb_name
- type: string
- - name: dosage
- type: string
- - name: role
- type: string
+language: zh
+
+name: 方剂组成列表
+type: list
+tags: [tcm]
+
+description: '提取方剂组成。'
+
+output:
+ fields:
+ - name: herb_name
+ type: str
+ description: '药材名称'
+ - name: dosage
+ type: str
+ description: '剂量'
+ - name: role
+ type: str
+ description: '角色(君/臣/佐/使)'
+ required: false
+
+guideline:
+ target: '提取方剂组成。'
+ rules:
+ - '提取方剂中的所有药材'
+ - '记录剂量和角色'
+
+display:
+ label: '{herb_name}'
```
### 经络图
@@ -44,14 +83,52 @@ schema:
提取经络关系:
```yaml
-name: meridian_graph
-type: Graph
-schema:
- nodes:
- - type: Herb
- - type: Meridian
- edges:
- - type: ENTERS
+language: zh
+
+name: 经络关系图谱
+type: graph
+tags: [tcm]
+
+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}'
+ relation_label: '{type}'
```
### 证候推理
@@ -59,13 +136,51 @@ schema:
提取证候诊断和推理:
```yaml
-name: syndrome_reasoning
-type: TemporalGraph
-schema:
- nodes:
- - type: Syndrome
- - type: Pattern
- - type: Treatment
+language: zh
+
+name: 证候推理超图
+type: hypergraph
+tags: [tcm]
+
+description: '提取证候诊断和推理。'
+
+output:
+ entities:
+ fields:
+ - name: name
+ type: str
+ description: '实体名称'
+ - name: type
+ type: str
+ description: '类型(证候/症状/治法)'
+ relations:
+ fields:
+ - name: syndrome
+ type: str
+ description: '证候名称'
+ - name: symptoms
+ type: list
+ description: '相关症状'
+ - name: treatment
+ type: str
+ description: '治疗方法'
+ required: false
+
+guideline:
+ target: '提取证候诊断和推理。'
+ rules_for_entities:
+ - '提取证候和症状'
+ rules_for_relations:
+ - '提取证候与症状、治法的关系'
+
+identifiers:
+ entity_id: name
+ relation_id: '{syndrome}'
+ relation_members: symptoms
+
+display:
+ entity_label: '{name}'
+ relation_label: '{syndrome}'
```
## 使用示例
@@ -74,10 +189,13 @@ schema:
```bash
# 提取中药属性
-he parse herbal_compendium.txt -t tcm/herb_properties -o output/
+he parse herbal_compendium.txt -t tcm/herb_property -o output/
# 提取方剂组成
he parse prescription.txt -t tcm/formula_composition -o output/
+
+# 提取经络关系
+he parse meridian.txt -t tcm/meridian_graph -o output/
```
### Python API
@@ -86,15 +204,13 @@ he parse prescription.txt -t tcm/formula_composition -o output/
from hyperextract import Template
# 加载中医模板
-ka = Template.create("tcm/herb_properties")
+ka = Template.create("tcm/herb_property", "zh")
# 从文档提取
result = ka.parse(herbal_text)
-# 访问中药信息
-for herb in result.get_nodes("Herb"):
- print(f"Herb: {herb.name}")
- print(f"Properties: {herb.properties}")
+# 访问结果
+print(result.fields)
```
## 支持的文档类型
diff --git a/docs/zh/guides/python-api.md b/docs/zh/guides/python-api.md
index 5101c36..4cf54d6 100644
--- a/docs/zh/guides/python-api.md
+++ b/docs/zh/guides/python-api.md
@@ -1,209 +1,167 @@
# Python API
-本指南介绍如何在 Python 应用程序中使用 Hyper-Extract。
+Hyper-Extract 提供 Python API 用于程序化提取。
## 安装
```bash
-pip install hyper-extract
+pip install hyperextract
```
-## 基本用法
+## 基础用法
-### 导入和初始化
+### 加载预设模板
```python
from hyperextract import Template
# 加载预设模板
-ka = Template.create("general/biography")
-
-# 解析文档
-result = ka.parse(text)
-```
-
-### 使用自定义模板
-
-```python
-from hyperextract import Template
-
-# 从 YAML 加载
-ka = Template.from_yaml("template.yaml")
+ka = Template.create("general/graph", "zh")
# 解析文档
result = ka.parse(document_text)
# 访问结果
-print(result.nodes)
-print(result.edges)
+print(result.entities)
+print(result.relations)
```
-## 自动类型
-
-### AutoModel
+### 加载自定义模板
```python
-from hyperextract import AutoModel
-from pydantic import BaseModel
-
-class Person(BaseModel):
- name: str
- age: int
- occupation: str
-
-extractor = AutoModel(schema=Person)
-result = extractor.parse("John 是一位 30 岁的工程师。")
-```
-
-### AutoList
-
-```python
-from hyperextract import AutoList
-
-extractor = AutoList(item_type="string")
-result = extractor.parse("配料包括面粉、糖和鸡蛋。")
-print(result.items) # ["面粉", "糖", "鸡蛋"]
-```
-
-### AutoGraph
-
-```python
-from hyperextract import AutoGraph
+from hyperextract import Template
-extractor = AutoGraph(
- node_types=["Person", "Organization"],
- edge_types=["WORKS_AT"]
-)
-result = extractor.parse("Alice 在 Google 工作。")
+# 从 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")
```
-### AutoHypergraph
+### 批量处理
```python
-from hyperextract import AutoHypergraph
-
-extractor = AutoHypergraph()
-result = extractor.parse("Alice、Bob 和 Carol 合作了。")
-```
-
-## 提取方法
+from hyperextract import Template
-### 使用 atom
+ka = Template.create("general/graph", "zh")
-```python
-from hyperextract.methods import atom
+documents = ["文档1内容...", "文档2内容...", "文档3内容..."]
-result = atom.extract(text, schema=MySchema)
+results = []
+for doc in documents:
+ result = ka.parse(doc)
+ results.append(result)
```
-### 使用 graph_rag
+### 结果导出
```python
-from hyperextract.methods import graph_rag
+from hyperextract import Template
-result = graph_rag.extract(
- text,
- node_types=["Person", "Company"],
- edge_types=["WORKS_AT"]
-)
-```
+ka = Template.create("general/graph", "zh")
+result = ka.parse(document_text)
-### 使用 cog_rag
+# 导出为 JSON
+json_output = result.to_json()
-```python
-from hyperextract.methods import cog_rag
+# 导出为 Dict
+dict_output = result.to_dict()
-result = cog_rag.extract(
- text,
- task="提取因果关系"
-)
+# 导出为三元组
+triples = result.to_triples()
```
-## 配置
+## 模板创建
-### LLM 配置
+### 创建新模板
```python
-from hyperextract import Config
-
-config = Config(
- llm_provider="openai",
- llm_model="gpt-4o",
- api_key="your-api-key"
-)
-
-ka = Template.create("general/biography", config=config)
-```
-
-### Embedding 配置
+from hyperextract import Template
-```python
-config = Config(
- embedding_provider="openai",
- embedding_model="text-embedding-3-small"
-)
+template = Template.create("template.yaml", "zh")
```
-## 处理结果
-
-### 访问节点
+### 保存模板
```python
-result = ka.parse(text)
+from hyperextract import Template
-for node in result.nodes:
- print(f"{node.type}: {node.properties}")
+ka = Template.create("general/graph", "zh")
+ka.save("my_template.yaml")
```
-### 访问边
+## 配置选项
-```python
-for edge in result.edges:
- print(f"{edge.source} --[{edge.type}]--> {edge.target}")
-```
-
-### 序列化
+### 设置语言
```python
-# 保存为 JSON
-result.to_json("output.json")
+from hyperextract import Template
-# 保存为 YAML
-result.to_yaml("output.yaml")
+# 单语言
+ka = Template.create("general/graph", "zh")
-# 从文件加载
-loaded = Result.from_json("output.json")
+# 多语言
+ka = Template.create("general/graph", ["zh", "en"])
```
-## 高级用法
-
-### 自定义解析器
+### 设置模型
```python
from hyperextract import Template
-from hyperextract.parsers import CustomParser
-class MyParser(CustomParser):
- def parse(self, text):
- # 自定义解析逻辑
- return processed_result
+# 使用指定模型
+ka = Template.create("general/graph", "zh", model="gpt-4")
-ka = Template(parser=MyParser())
+# 使用本地模型
+ka = Template.create("general/graph", "zh", model="local-model")
```
-### 批量处理
+## 错误处理
```python
from hyperextract import Template
-ka = Template.create("general/biography")
-
-documents = ["doc1.txt", "doc2.txt", "doc3.txt"]
-results = ka.batch_parse(documents)
+try:
+ ka = Template.create("template.yaml", "zh")
+ result = ka.parse(document_text)
+except Exception as e:
+ print(f"提取失败: {e}")
```
## 下一步
-- 探索 [CLI](cli.md)
-- 浏览 [领域模板](domain-templates/index.md)
-- 查看 [参考](../reference/index.md)
+- 浏览 [预设模板](../concepts/templates.md)
+- 查看 [领域模板](./domain-templates/index.md)
diff --git a/docs/zh/index.md b/docs/zh/index.md
index b97b5b6..d2aa6b8 100644
--- a/docs/zh/index.md
+++ b/docs/zh/index.md
@@ -4,7 +4,9 @@
**一行命令,将文档转化为结构化知识摘要。**
-[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
+![Hero & Workflow](assets/hero-v2.jpg)
+
+[![Python版本](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Status](https://img.shields.io/badge/status-active-success)]()
@@ -70,6 +72,8 @@ result = ka.parse(annual_report_text)
## 架构
+![Architecture](assets/architecture-v2.png)
+
系统构建在稳固的三元组上:**自动类型**(多类型结构)、**方法**(执行策略)和**模板**(声明式模式)。
## 许可证
diff --git a/docs/zh/resources/contributing.md b/docs/zh/resources/contributing.md
index f4a1b15..09a9870 100644
--- a/docs/zh/resources/contributing.md
+++ b/docs/zh/resources/contributing.md
@@ -90,8 +90,7 @@
我们欢迎翻译贡献:
1. 检查现有翻译
-2. 遵循[翻译指南](./translation-guide.md)
-3. 通过 PR 提交翻译
+2. 通过 PR 提交翻译
## Pull Request 指南
diff --git a/mkdocs.yml b/mkdocs.yml
index 898d8f6..470e08e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -13,56 +13,65 @@ theme:
name: material
language: en
features:
- - navigation.instant
+ - navigation.tracking
- navigation.tabs
- - navigation.sections
+ - navigation.tabs.sticky
- navigation.indexes
- - toc.integrate
- - toc.follow
- search.suggest
- search.highlight
- content.code.copy
- - content.code.annotate
palette:
- - media: "(prefers-color-scheme: light)"
- scheme: default
- primary: indigo
- accent: indigo
- toggle:
- icon: material/brightness-7
- name: Switch to dark mode
- - media: "(prefers-color-scheme: dark)"
- scheme: slate
- primary: indigo
- accent: indigo
- toggle:
- icon: material/brightness-4
- name: Switch to light mode
- font:
- text: Roboto
- code: Roboto Mono
+ primary: purple
+ accent: deep purple
plugins:
- - search:
- separator: '[\s\-,:!=\[\]()"/]+|(?<!:)(?://|(?<!--))'
+ - search
- i18n:
docs_structure: folder
fallback_to_default: true
- reconfigure_material: true
- reconfigure_search: true
+ languages:
+ - locale: en
+ name: English
+ default: true
+ build: true
+ - locale: zh
+ name: 中文
+ build: true
+ nav:
+ - 首页: zh/index.md
+ - 开始使用:
+ - zh/getting-started/index.md
+ - zh/getting-started/installation.md
+ - zh/getting-started/quickstart.md
+ - zh/getting-started/configuration.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/resources/faq.md
+ - zh/resources/troubleshooting.md
+ - zh/resources/contributing.md
extra:
social:
- icon: fontawesome/brands/github
- link: https://github.com/hyper-extract/hyper-extract
- generator: false
- alternate:
- - name: English
- link: /en/
- lang: en
- - name: 中文
- link: /zh/
- lang: zh
+ link: https://github.com/yifanfeng97/hyper-extract
nav:
- Home: en/index.md
@@ -96,22 +105,11 @@ nav:
markdown_extensions:
- pymdownx.highlight:
- anchor_linenums: true
+ use_pygments: true
- pymdownx.inlinehilite
- - pymdownx.snippets
- pymdownx.superfences
- admonition
- - pymdownx.details
- tables
- toc:
permalink: true
- attr_list
- - md_in_html
- - pymdownx.emoji:
- emoji_index: !!python/name:materialx.emoji.material
- emoji_generator: !!python/name:materialx.emoji.material
- - pymdownx.mark
- - attr_list
-
-extra_css:
- - stylesheets/extra.css