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.mdindex d059b55..7a13e03 100644--- a/README.md+++ b/README.md@@ -8,7 +8,7 @@**Transform documents into knowledge abstracts — with just one command.**-[](https://python.org)+[](https://python.org)[](LICENSE)[]()@@ -55,22 +55,53 @@ he feed ./output/ new_document.mdZero-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.-+## 🛠️ Architecture OverviewThe system is built on a robust triad: **Auto-Types** (Multi-typed structures), **Methods** (The Execution strategy), and **Templates** (Declarative schema).-+* **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.mdindex cca386a..d7b4301 100644--- a/README_ZH.md+++ b/README_ZH.md@@ -8,7 +8,7 @@**将文档转化为知识摘要 —— 一行命令即可。**-[](https://python.org)+[](https://python.org)[](LICENSE)[]()@@ -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)拒绝样板代码,纯干货聚焦数据本身。-+## 🛠️ 系统架构揭秘系统底座基于坚实的铁三角架构:**Auto-Types** (提取结构)、**Methods** (执行策略)、以及 **Templates** (声明式配置)。-+* **设计指南**: [模板设计指南](./hyperextract/templates/DESIGN_GUIDE.md)* **内置模板**: [预设模板目录](./hyperextract/templates/presets/)diff --git a/docs/assets/8-types-v2.jpg b/docs/assets/8-types-v2.jpgdeleted file mode 100644index 7149049..0000000Binary files a/docs/assets/8-types-v2.jpg and /dev/null differdiff --git a/docs/assets/8-types-v2.png b/docs/assets/8-types-v2.pngnew file mode 100644index 0000000..4fc6d7eBinary files /dev/null and b/docs/assets/8-types-v2.png differdiff --git a/docs/assets/8-types-v5.jpg b/docs/assets/8-types-v5.jpgdeleted file mode 100644index 41ceac3..0000000Binary files a/docs/assets/8-types-v5.jpg and /dev/null differdiff --git a/docs/assets/architecture-v10.jpg b/docs/assets/architecture-v10.jpgdeleted file mode 100644index c82c60a..0000000Binary files a/docs/assets/architecture-v10.jpg and /dev/null differdiff --git a/docs/assets/architecture-v2.png b/docs/assets/architecture-v2.pngnew file mode 100644index 0000000..944c628Binary files /dev/null and b/docs/assets/architecture-v2.png differdiff --git a/docs/assets/architecture-v9.jpg b/docs/assets/architecture.jpgsimilarity index 100%rename from docs/assets/architecture-v9.jpgrename to docs/assets/architecture.jpgdiff --git a/docs/assets/hero-v1.jpg b/docs/assets/hero.jpgsimilarity index 100%rename from docs/assets/hero-v1.jpgrename to docs/assets/hero.jpgdiff --git a/docs/en/concepts/auto-types.md b/docs/en/concepts/auto-types.mdindex 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.mdindex 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.mdindex 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:+-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 TemplatesHyper-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```pythonfrom 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.mdindex 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 configurationhe 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.mdindex 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)```bashuv 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 settingsdiff --git a/docs/en/getting-started/quickstart.md b/docs/en/getting-started/quickstart.mdindex 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)++```bashhe parse document.txt -o output/ -t template.yaml```@@ -55,14 +81,14 @@ he parse document.txt -o output/ -t template.yamlfrom hyperextract import Template# Create template from YAML-ka = Template.from_yaml("template.yaml")+ka = Template.create("template.yaml", "en")# Parse documentresult = 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 Resultsdiff --git a/docs/en/guides/domain-templates/finance.md b/docs/en/guides/domain-templates/finance.mdindex 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 documentresult = 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 Typesdiff --git a/docs/en/guides/domain-templates/legal.md b/docs/en/guides/domain-templates/legal.mdindex 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 documentresult = 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 Typesdiff --git a/docs/en/guides/domain-templates/medicine.md b/docs/en/guides/domain-templates/medicine.mdindex 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 documentresult = 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 Typesdiff --git a/docs/en/guides/domain-templates/tcm.md b/docs/en/guides/domain-templates/tcm.mdindex 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 (TExtract 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 compositionhe 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 documentresult = 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 Typesdiff --git a/docs/en/guides/python-api.md b/docs/en/guides/python-api.mdindex 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```pythonfrom 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 documentresult = 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```pythonfrom 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```pythonfrom 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.mdindex 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.**-[](https://python.org)+++[](https://python.org)[](LICENSE)[]()@@ -70,6 +72,8 @@ result = ka.parse(annual_report_text)## Architecture++The system is built on a robust triad: **Auto-Types** (Multi-typed structures), **Methods** (The Execution strategy), and **Templates** (Declarative schema).## Licensediff --git a/docs/en/resources/contributing.md b/docs/en/resources/contributing.mdindex 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 Guidelinesdiff --git a/docs/en/resources/index.md b/docs/en/resources/index.mdnew file mode 100644index 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.cssdeleted file mode 100644index 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.mdindex 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.mdindex 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.mdindex 4c385e9..62102e3 100644--- a/docs/zh/concepts/templates.md+++ b/docs/zh/concepts/templates.md@@ -1,156 +1,571 @@# 模板-模板使用声明式 YAML 定义要提取的内容。它们提供了一种强大的方式来指定提取模式,无需编写代码。+模板使用声明式 YAML 定义要提取的内容,提供了一种强大的方式来指定提取模式,无需编写代码。-## 模板结构+## 类型选择-模板由以下部分组成:+-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```pythonfrom 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.mdindex 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.mdindex 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(推荐)```bashuv 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.mdindex 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)++```bashhe parse document.txt -o output/ -t template.yaml```@@ -55,14 +81,14 @@ he parse document.txt -o output/ -t template.yamlfrom 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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```-## 基本用法+## 基础用法-### 导入和初始化+### 加载预设模板```pythonfrom 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"])```-## 高级用法--### 自定义解析器+### 设置模型```pythonfrom 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")```-### 批量处理+## 错误处理```pythonfrom 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.mdindex b97b5b6..d2aa6b8 100644--- a/docs/zh/index.md+++ b/docs/zh/index.md@@ -4,7 +4,9 @@**一行命令,将文档转化为结构化知识摘要。**-[](https://python.org)+++[](https://python.org)[](LICENSE)[]()@@ -70,6 +72,8 @@ result = ka.parse(annual_report_text)## 架构++系统构建在稳固的三元组上:**自动类型**(多类型结构)、**方法**(执行策略)和**模板**(声明式模式)。## 许可证diff --git a/docs/zh/resources/contributing.md b/docs/zh/resources/contributing.mdindex 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.ymlindex 898d8f6..470e08e 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -13,56 +13,65 @@ theme:name: materiallanguage: enfeatures:- - 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.annotatepalette:- - 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 purpleplugins:- - search:- separator: '[\s\-,:!=\[\]()"/]+|(?<!:)(?://|(?<!--))'+ - search- i18n:docs_structure: folderfallback_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.mdextra: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-extractnav:- 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