Skip to content

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

Refactor hyperextract imports and templates for improved structure and clarity

yifanfeng97d7f305ecf016
diff --git a/examples/auto_spatio_temporal_graph_demo.py b/examples/auto_spatio_temporal_graph_demo.py
index fcddfa7..d89bb4e 100644
--- a/examples/auto_spatio_temporal_graph_demo.py
+++ b/examples/auto_spatio_temporal_graph_demo.py
@@ -26,7 +26,6 @@ from pydantic import BaseModel, Field
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from hyperextract.types import AutoSpatioTemporalGraph
-from ontomem import MergeStrategy
import dotenv
diff --git a/examples/cog_rag_demo.py b/examples/cog_rag_demo.py
index ce0abdb..a3fac67 100644
--- a/examples/cog_rag_demo.py
+++ b/examples/cog_rag_demo.py
@@ -22,7 +22,7 @@ from dotenv import load_dotenv
load_dotenv()
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-from hyperextract.types.cog_rag import Cog_RAG
+from hyperextract.methods.rag import Cog_RAG
# ============================================================================
# Sample Story for Extraction
diff --git a/examples/hyper_rag_demo.py b/examples/hyper_rag_demo.py
index 5b3dd5f..ee08090 100644
--- a/examples/hyper_rag_demo.py
+++ b/examples/hyper_rag_demo.py
@@ -16,7 +16,7 @@ sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-from hyperextract.types import Hyper_RAG
+from hyperextract.methods.rag import Hyper_RAG
load_dotenv()
diff --git a/examples/hypergraph_rag_demo.py b/examples/hypergraph_rag_demo.py
index 15c5c81..dbb45b1 100644
--- a/examples/hypergraph_rag_demo.py
+++ b/examples/hypergraph_rag_demo.py
@@ -13,7 +13,7 @@ sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-from hyperextract.types import HyperGraph_RAG
+from hyperextract.methods.rag import HyperGraph_RAG
load_dotenv()
diff --git a/examples/itext2kg_demo.py b/examples/itext2kg_demo.py
index 206ecb1..853b67c 100644
--- a/examples/itext2kg_demo.py
+++ b/examples/itext2kg_demo.py
@@ -14,7 +14,7 @@ sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-from hyperextract.types import iText2KG
+from hyperextract.methods.typical import iText2KG
load_dotenv()
diff --git a/examples/itext2kg_star_demo.py b/examples/itext2kg_star_demo.py
index 0e4e5f3..f2c82ec 100644
--- a/examples/itext2kg_star_demo.py
+++ b/examples/itext2kg_star_demo.py
@@ -16,7 +16,7 @@ sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-from hyperextract.types.itext2kg_star import iText2KG_Star
+from hyperextract.methods.typical import iText2KG_Star
load_dotenv()
diff --git a/examples/kg_gen_demo.py b/examples/kg_gen_demo.py
index 79c4702..9b7b031 100644
--- a/examples/kg_gen_demo.py
+++ b/examples/kg_gen_demo.py
@@ -14,7 +14,7 @@ sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-from hyperextract.types import KG_Gen
+from hyperextract.methods.typical import KG_Gen
load_dotenv()
diff --git a/hyperextract/methods/rag/__init__.py b/hyperextract/methods/rag/__init__.py
index 5268c87..d55f995 100644
--- a/hyperextract/methods/rag/__init__.py
+++ b/hyperextract/methods/rag/__init__.py
@@ -6,15 +6,13 @@ This module contains various RAG implementations that leverage graph structures
from .hyper_rag import Hyper_RAG
from .hypergraph_rag import HyperGraph_RAG
-from .cog_rag import Cog_RAG, Cog_RAG_ThemeLayer, Cog_RAG_DetailLayer
+from .cog_rag import Cog_RAG
from .light_rag import Light_RAG
__all__ = [
"Hyper_RAG",
"HyperGraph_RAG",
"Cog_RAG",
- "Cog_RAG_ThemeLayer",
- "Cog_RAG_DetailLayer",
"Light_RAG",
]
diff --git a/hyperextract/methods/rag/cog_rag.py b/hyperextract/methods/rag/cog_rag.py
index 360740f..3a81272 100644
--- a/hyperextract/methods/rag/cog_rag.py
+++ b/hyperextract/methods/rag/cog_rag.py
@@ -6,7 +6,7 @@ Extracts and manages Theme-Entity relationships where Themes act as Hyperedges c
from typing import List
from hashlib import md5
from pydantic import BaseModel, Field
-from hyperextract.types import AutoHypergraph, AutoHypergraphSchema
+from hyperextract.types.hypergraph import AutoHypergraph, AutoHypergraphSchema
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.embeddings import Embeddings
from langchain_core.language_models import BaseChatModel
@@ -482,4 +482,3 @@ class Cog_RAG:
def edges(self):
"""Return all edges (Themes + Relations)."""
return self.theme_layer.edges + self.detail_layer.edges
-
diff --git a/hyperextract/methods/rag/hypergraph_rag.py b/hyperextract/methods/rag/hypergraph_rag.py
index 70e9318..800d4a4 100644
--- a/hyperextract/methods/rag/hypergraph_rag.py
+++ b/hyperextract/methods/rag/hypergraph_rag.py
@@ -18,7 +18,7 @@ from langchain_core.language_models import BaseChatModel
from langchain_core.prompts.chat import ChatPromptTemplate
from ontomem.merger import MergeStrategy
-from hyperextract.types import AutoHypergraph, AutoHypergraphSchema
+from hyperextract.types.hypergraph import AutoHypergraph, AutoHypergraphSchema
# ============================================================================
# Node Schema
@@ -315,4 +315,3 @@ class HyperGraph_RAG(AutoHypergraph[NodeSchema, EdgeSchema]):
raw_hypergraph = self.merge_batch_data(partial_hypergraphs)
return self._prune_dangling_edges(raw_hypergraph)
-
diff --git a/hyperextract/methods/typical/atom.py b/hyperextract/methods/typical/atom.py
index 2618f97..7f5b407 100644
--- a/hyperextract/methods/typical/atom.py
+++ b/hyperextract/methods/typical/atom.py
@@ -17,7 +17,7 @@ from langchain_core.embeddings import Embeddings
from ontomem.merger import MergeStrategy, CustomRuleMerger
from hyperextract.utils.logging import logger
-from hyperextract.types import AutoGraph, AutoGraphSchema
+from hyperextract.types.graph import AutoGraph, AutoGraphSchema
# ==============================================================================
# 1. Schema Definition - Consistent with original Atom implementation
diff --git a/hyperextract/methods/typical/itext2kg_star.py b/hyperextract/methods/typical/itext2kg_star.py
index 70f0921..71f1bc0 100644
--- a/hyperextract/methods/typical/itext2kg_star.py
+++ b/hyperextract/methods/typical/itext2kg_star.py
@@ -16,7 +16,7 @@ from langchain_core.prompts import ChatPromptTemplate
from langchain_core.embeddings import Embeddings
from ontomem.merger import MergeStrategy
-from hyperextract.types import AutoGraph, AutoGraphSchema
+from hyperextract.types.graph import AutoGraph, AutoGraphSchema
from hyperextract.utils.logging import logger
# ==============================================================================
diff --git a/hyperextract/methods/typical/kg_gen.py b/hyperextract/methods/typical/kg_gen.py
index 2f0016a..56da4b1 100644
--- a/hyperextract/methods/typical/kg_gen.py
+++ b/hyperextract/methods/typical/kg_gen.py
@@ -13,7 +13,7 @@ from langchain_core.language_models import BaseChatModel
from langchain_core.embeddings import Embeddings
from ontomem.merger import MergeStrategy
-from hyperextract.types import AutoGraph, AutoGraphSchema
+from hyperextract.types.graph import AutoGraph, AutoGraphSchema
from hyperextract.utils.logging import logger
# ==============================================================================
diff --git a/hyperextract/templates/INSTRUCTION.md b/hyperextract/templates/INSTRUCTION.md
new file mode 100644
index 0000000..950b9a4
--- /dev/null
+++ b/hyperextract/templates/INSTRUCTION.md
@@ -0,0 +1,103 @@
+# Hyper-Extract Template Development & Master Prompt Protocol
+
+This document defines the standard workflow for implementing domain-specific knowledge extraction templates in the `Hyper-Extract` framework.
+
+## 0. Core Protocol: Source-First
+
+Before writing any code, you MUST:
+1. **Identify the Base Class**: Choose the appropriate base class from the mapping table below.
+2. **Read the Source**: Use tools to read the Python source code of the chosen base class (located in `hyperextract/types/`).
+ * *Reason*: Source code is the source of truth for `__init__` parameters, `show` method signatures, and generic constraints.
+
+## 1. Design Phase: Feasibility & Selection
+
+### The Extractability Rule
+Before designing a Schema, ask yourself:
+* **Evidence Availability**: Does the input text explicitly contain evidence for this field? (Do not design fields for dynamic data typically found in external databases).
+* **Structural Fit**: What is the most natural form for this data? (e.g., Unordered repeating patterns, unique set, or complex N-ary relations?)
+
+### Mapping Table for Base Class Selection
+
+| Data Nature | Recommended Base Class | Source Code Location | Key Constraints |
+| :--- | :--- | :--- | :--- |
+| **Single Object** (Summary/Meta) | `AutoModel` | `hyperextract/types/model.py` | One object per document |
+| **Pattern Collection** (Repeating) | `AutoList` | `hyperextract/types/list.py` | No deduplication. Extracts all instances found. |
+| **Unique Collection** (Glossary) | `AutoSet` | `hyperextract/types/set.py` | Auto-deduplication; requires `key_extractor` |
+| **Binary Graph** (Entity-Relation) | `AutoGraph` | `hyperextract/types/graph.py` | Standard binary relationships |
+| **Temporal Graph** (Timestamps) | `AutoTemporalGraph` | `hyperextract/types/temporal_graph.py` | Edges MUST have time fields |
+| **Spatial Graph** (Locations) | `AutoSpatialGraph` | `hyperextract/types/spatial_graph.py` | Nodes/Edges MUST have location/coords |
+| **Spatio-Temporal Graph** | `AutoSpatioTemporalGraph` | `hyperextract/types/spatio_temporal_graph.py` | Tracks movement and evolution in space/time |
+| **N-ary/Complex Events** | `AutoHypergraph` | `hyperextract/types/hypergraph.py` | Hyperedge connects N nodes |
+
+---
+
+## 2. Implementation Rules
+
+### A. Prompt Definition
+* **Mandatory Constant**: Define `_TEMPLATE_PROMPT` (a multi-line string) outside the class.
+* **Content**: Clearly define the expert persona and extraction logic. Mention specific formatting rules if necessary.
+
+### B. Class Structure
+* **Schemas**: All Pydantic fields MUST include a `description` attribute. This is vital for the LLM to understand the target.
+* **Initialization**: Explicitly list parameters (`llm_client`, `embedder`, etc.) and pass the prompt to `super().__init__(..., prompt=_TEMPLATE_PROMPT, ...)`.
+* **Visualization (`show`)**: YOU MUST override the `show` method.
+ * **Parameter Constraint**: **DO NOT** include `label_extractor` parameters (e.g., `node_label_extractor`) in the template's `show` method signature.
+ * **Implementation**: You should define the best **frontend visualization labels** and their extraction logic for your specific Schema internally within `show` and pass them to `super().show(...)`. This ensures users get the best visualization out-of-the-box by simply calling `template.show()`.
+
+---
+
+## 3. Standard Skeleton
+
+```python
+from typing import Any, Callable
+from langchain_core.language_models import BaseChatModel
+from langchain_core.embeddings import Embeddings
+from pydantic import BaseModel, Field
+from hyperextract.types import ... # Import relevant base class
+
+# 1. Define Schemas
+class ItemSchema(BaseModel):
+ name: str = Field(..., description="Name of the entity")
+ ...
+
+# 2. Define Prompt
+_TEMPLATE_PROMPT = """
+You are an expert in [Domain]. Your task is to extract [Structure] from text...
+"""
+
+# 3. Define Class
+class MyTemplate(AutoType[ItemSchema]): # Replace with actual base class (AutoList, AutoSet, etc.)
+ """Google Style Docstring."""
+
+ def __init__(
+ self,
+ llm_client: BaseChatModel,
+ embedder: Embeddings,
+ chunk_size: int = 2048,
+ **kwargs: Any
+ ):
+ super().__init__(
+ item_schema=ItemSchema,
+ llm_client=llm_client,
+ embedder=embedder,
+ prompt=_TEMPLATE_PROMPT,
+ chunk_size=chunk_size,
+ **kwargs
+ )
+
+ def show(
+ self,
+ *,
+ top_k_for_search: int = 3,
+ top_k_for_chat: int = 3,
+ ):
+ # Define frontend visualization labels internally
+ def my_label_extractor(item: ItemSchema) -> str:
+ return item.name
+
+ super().show(
+ item_label_extractor=my_label_extractor,
+ top_k_for_search=top_k_for_search,
+ top_k_for_chat=top_k_for_chat,
+ )
+```
diff --git a/hyperextract/templates/INSTRUCTION_ZH.md b/hyperextract/templates/INSTRUCTION_ZH.md
new file mode 100644
index 0000000..45c445b
--- /dev/null
+++ b/hyperextract/templates/INSTRUCTION_ZH.md
@@ -0,0 +1,103 @@
+# Hyper-Extract 模板开发与 Master Prompt 协议
+
+本文档定义了在 `Hyper-Extract` 框架中实现特定领域知识抽取模板的标准工作流。
+
+## 0. 核心协议:阅读源码 (Source-First Protocol)
+
+在编写任何代码之前,你**必须**:
+1. **明确基类**:根据需求从下表中选择合适的基类。
+2. **强制读码**:使用工具读取 `hyperextract/types/` 目录中对应基类的 Python 源码文件。
+ * *原因*:具体的 `__init__` 参数、`show` 方法签名和泛型约束以源码为准。
+
+## 1. 设计阶段:可行性与选型
+
+### 可提取性原则 (Extractability)
+在设计 Schema 前自问:
+* **证据可用性**:输入文本是否显式包含该字段的证据?(拒绝为外部数据库才有的动态数据设计字段)。
+* **结构适配**:数据最自然的存在形式是什么?是无序重复、唯一集合还是复杂的多元关系?
+
+### 选型映射表 (Mapping Table)
+
+| 数据特性 | 推荐基类 | 核心源码位置 | 关键约束 |
+| :--- | :--- | :--- | :--- |
+| **单对象** (摘要/元数据) | `AutoModel` | `hyperextract/types/model.py` | 每个文档只提一个对象 |
+| **模式集合** (重复提取) | `AutoList` | `hyperextract/types/list.py` | 不去重。提取文本中出现的所有模式实例 |
+| **唯一集合** (术语/清单) | `AutoSet` | `hyperextract/types/set.py` | 自动去重,需定义 `key_extractor` |
+| **标准图谱** (实体-关系) | `AutoGraph` | `hyperextract/types/graph.py` | 标准二元关系 |
+| **时序图谱** (含时间戳) | `AutoTemporalGraph` | `hyperextract/types/temporal_graph.py` | 边必须包含时间字段 |
+| **空间关系图谱** | `AutoSpatialGraph` | `hyperextract/types/spatial_graph.py` | 节点/边需包含位置坐标信息 |
+| **时空演变图谱** | `AutoSpatioTemporalGraph` | `hyperextract/types/spatio_temporal_graph.py` | 同时描述空间移动与时间演变 |
+| **多元/复杂事件** | `AutoHypergraph` | `hyperextract/types/hypergraph.py` | 超边连接 N 个节点 |
+
+---
+
+## 2. 实现规范 (Implementation Rules)
+
+### A. Prompt 定义
+* **强制常数**:必须在类外部定义 `_TEMPLATE_PROMPT`(多行字符串)。
+* **内容要求**:明确定义专家角色、提取逻辑。如果某些字段有特定的提取格式要求,请在 Prompt 中强调。
+
+### B. 类结构
+* **Schema**:所有 Pydantic 字段必须包含 `description` 属性,这是 LLM 理解抽取目标的关键。
+* **初始化 (`__init__`)**:显式列参数(`llm_client`, `embedder` 等),并正确调用 `super().__init__(..., prompt=_TEMPLATE_PROMPT, ...)`。
+* **可视化 (`show`)**:必须覆盖 `show` 方法。
+ * **参数约束**:**禁止**在模板类的 `show` 方法签名中包含 `label_extractor` 参数。
+ * **实现要求**:你应该在 `show` 内部定义最适合该 Schema 的 **前端展示标签** 的提取函数,然后传给 `super().show(...)`。这样用户只需调用 `template.show()` 即可获得最佳效果。
+
+---
+
+## 3. 标准示例骨架 (Example Skeleton)
+
+```python
+from typing import Any, Callable
+from langchain_core.language_models import BaseChatModel
+from langchain_core.embeddings import Embeddings
+from pydantic import BaseModel, Field
+from hyperextract.types import ... # 导入对应基类
+
+# 1. 定义 Schema
+class ItemSchema(BaseModel):
+ name: str = Field(..., description="实体的名称")
+ ...
+
+# 2. 定义 Prompt
+_TEMPLATE_PROMPT = """
+你是一位[领域]专家。你的任务是从文本中提取[结构化知识]...
+"""
+
+# 3. 定义模板类
+class MyTemplate(AutoType[ItemSchema]): # 替换为 AutoList, AutoSet 等
+ """Google Style 类文档字符串。"""
+
+ def __init__(
+ self,
+ llm_client: BaseChatModel,
+ embedder: Embeddings,
+ chunk_size: int = 2048,
+ **kwargs: Any
+ ):
+ super().__init__(
+ item_schema=ItemSchema,
+ llm_client=llm_client,
+ embedder=embedder,
+ prompt=_TEMPLATE_PROMPT,
+ chunk_size=chunk_size,
+ **kwargs
+ )
+
+ def show(
+ self,
+ *,
+ top_k_for_search: int = 3,
+ top_k_for_chat: int = 3,
+ ):
+ # 在内部定义展示逻辑
+ def my_label_extractor(item: ItemSchema) -> str:
+ return item.name
+
+ super().show(
+ item_label_extractor=my_label_extractor, # 传给基类
+ top_k_for_search=top_k_for_search,
+ top_k_for_chat=top_k_for_chat,
+ )
+```
diff --git a/hyperextract/templates/en/__init__.py b/hyperextract/templates/en/__init__.py
index db5ed8b..f45d0ea 100644
--- a/hyperextract/templates/en/__init__.py
+++ b/hyperextract/templates/en/__init__.py
@@ -1,21 +1,15 @@
-from .general.knowledge_graph import KnowledgeGraph
-from .general.concept_map import ConceptMap
-from .general.logic_graph import LogicGraph
-from .agriculture.crop import CropStatusGraph
-from .agriculture.soil import SoilNutritionGraph
-from .biology.taxonomy import TaxonomyGraph
-from .biology.network import BiologicalNetwork
-from .biology.metabolic import MetabolicHypergraph
-from .chemistry.molecular import MolecularStructureGraph
-from .chemistry.reaction import ChemicalReactionHyper
-from .chemistry.protocol import LabProtocolTemporal
+from .general import KnowledgeGraph, ConceptMap, LogicGraph
+from .agriculture import CropCycleGraph, LivestockGraph, AgriPestControl
+from .biology import TaxonomyGraph, BiologicalNetwork, MetabolicHypergraph
+from .chemistry import MolecularStructureGraph, ChemicalReactionHyper, LabProtocolTemporal
__all__ = [
"KnowledgeGraph",
"ConceptMap",
"LogicGraph",
- "CropStatusGraph",
- "SoilNutritionGraph",
+ "CropCycleGraph",
+ "LivestockGraph",
+ "AgriPestControl",
"TaxonomyGraph",
"BiologicalNetwork",
"MetabolicHypergraph",
diff --git a/hyperextract/templates/en/agriculture/__init__.py b/hyperextract/templates/en/agriculture/__init__.py
index 34c0d82..556a0eb 100644
--- a/hyperextract/templates/en/agriculture/__init__.py
+++ b/hyperextract/templates/en/agriculture/__init__.py
@@ -1,6 +1,6 @@
-from .crop_cycle import CropCycleGraph, AgriEntity, AgriRelation
+from .crop_cycle import CropCycleGraph, AgriEntity, AgriRelation
from .livestock import LivestockGraph, AnimalNode, BreedingRelation
-from .supply_chain import AgriSupplyChain, SupplyEntity, SupplyFlow
+from .pest_control import AgriPestControl, AgriPestEntity, AgriPestRelation
__all__ = [
"CropCycleGraph",
@@ -9,7 +9,7 @@ __all__ = [
"LivestockGraph",
"AnimalNode",
"BreedingRelation",
- "AgriSupplyChain",
- "SupplyEntity",
- "SupplyFlow"
+ "AgriPestControl",
+ "AgriPestEntity",
+ "AgriPestRelation"
]
diff --git a/hyperextract/templates/en/agriculture/pest_control.py b/hyperextract/templates/en/agriculture/pest_control.py
new file mode 100644
index 0000000..0aea89b
--- /dev/null
+++ b/hyperextract/templates/en/agriculture/pest_control.py
@@ -0,0 +1,117 @@
+from typing import Optional, Any, Callable
+from pydantic import BaseModel, Field
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.embeddings import Embeddings
+from hyperextract.types.graph import AutoGraph
+
+# ==============================================================================
+# 1. Schema Definitions
+# ==============================================================================
+
+
+class AgriPestEntity(BaseModel):
+ """An entity in the pest control domain (Pest, Disease, Crop, Symptom, Treatment)."""
+
+ name: str = Field(description="Name of the pest, crop, disease, or chemical agent.")
+ category: str = Field(
+ description="Category: 'Pest', 'Disease', 'Host Crop', 'Symptom', 'Prevention Method', 'Chemical Treatment'."
+ )
+ description: Optional[str] = Field(
+ None, description="Detailed description, biological traits, or characteristics."
+ )
+
+
+class AgriPestRelation(BaseModel):
+ """The relationship between agricultural entities (e.g., 'infests', 'causes', 'treated_by')."""
+
+ source: str = Field(description="The source entity name.")
+ target: str = Field(description="The target entity name.")
+ relation_type: str = Field(
+ description="Type: 'infests', 'parasitizes', 'damages', 'causes symptom', 'prevented by', 'sensitive to'."
+ )
+ detail: Optional[str] = Field(
+ None, description="Specific conditions, dosage, or damage severity."
+ )
+
+
+# ==============================================================================
+# 2. Prompts
+# ==============================================================================
+
+_TEMPLATE_PROMPT = """
+You are an expert agronomist and pest management specialist.
+Your task is to extract a comprehensive knowledge graph of crop pests, diseases, and their control methods.
+
+Guidelines:
+1. Identify biological threats: Pests, insects, fungi, bacteria, or viruses.
+2. Link threats to their host crops and the specific symptoms they cause (e.g., leaf spot, stem rot).
+3. Map out integrated pest management (IPM) strategies, including biological, physical, and chemical control methods.
+4. Extract specific chemical agents, dosages, and application timings mentioned in the text.
+"""
+
+# ==============================================================================
+# 3. Template Class
+# ==============================================================================
+
+
+class AgriPestControl(AutoGraph[AgriPestEntity, AgriPestRelation]):
+ """
+ Knowledge graph template for agricultural pest and disease management.
+
+ Transforms technical manuals and guidelines into structured control strategies.
+ """
+
+ def __init__(
+ self,
+ llm_client: BaseChatModel,
+ embedder: Embeddings,
+ *,
+ extraction_mode: str = "one_stage",
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
+ max_workers: int = 10,
+ verbose: bool = False,
+ **kwargs: Any,
+ ):
+ """Initialize the AgriPestControl template."""
+ super().__init__(
+ node_schema=AgriPestEntity,
+ edge_schema=AgriPestRelation,
+ node_key_extractor=lambda x: x.name.strip(),
+ edge_key_extractor=lambda x: f"{x.source.strip()}--({x.relation_type.lower()})-->{x.target.strip()}",
+ nodes_in_edge_extractor=lambda x: (x.source.strip(), x.target.strip()),
+ llm_client=llm_client,
+ embedder=embedder,
+ extraction_mode=extraction_mode,
+ chunk_size=chunk_size,
+ chunk_overlap=chunk_overlap,
+ max_workers=max_workers,
+ verbose=verbose,
+ prompt=_TEMPLATE_PROMPT,
+ **kwargs,
+ )
+
+ def show(
+ self,
+ *,
+ top_k_nodes_for_search: int = 3,
+ top_k_edges_for_search: int = 3,
+ top_k_nodes_for_chat: int = 3,
+ top_k_edges_for_chat: int = 3,
+ ) -> None:
+ """Visualize the pest control knowledge graph."""
+
+ def node_label_extractor(node: AgriPestEntity) -> str:
+ return f"{node.name} ({node.category})"
+
+ def edge_label_extractor(edge: AgriPestRelation) -> str:
+ return f"{edge.relation_type}"
+
+ super().show(
+ node_label_extractor=node_label_extractor,
+ edge_label_extractor=edge_label_extractor,
+ top_k_nodes_for_search=top_k_nodes_for_search,
+ top_k_edges_for_search=top_k_edges_for_search,
+ top_k_nodes_for_chat=top_k_nodes_for_chat,
+ top_k_edges_for_chat=top_k_edges_for_chat,
+ )
diff --git a/hyperextract/templates/en/agriculture/supply_chain.py b/hyperextract/templates/en/agriculture/supply_chain.py
deleted file mode 100644
index 70e5989..0000000
--- a/hyperextract/templates/en/agriculture/supply_chain.py
+++ /dev/null
@@ -1,158 +0,0 @@
-from typing import Optional, Any
-from pydantic import BaseModel, Field
-from langchain_core.language_models.chat_models import BaseChatModel
-from langchain_core.embeddings import Embeddings
-from hyperextract.types import AutoGraph
-
-# ==============================================================================
-# 1. Schema Definitions
-# ==============================================================================
-
-
-class SupplyEntity(BaseModel):
- """An actor or asset in the agri-supply chain (e.g., Farm, Warehouse, Processor, Logistics, Retailer)."""
-
- name: str = Field(description="Name of the organization, facility, or batch ID.")
- category: str = Field(
- description="Category: 'Producer/Farm', 'Processor', 'Distributor', 'Logistics Provider', 'Retailer', 'Batch/Product'."
- )
- location_or_cert: Optional[str] = Field(
- description="Geographic location or quality certification (e.g., Organic, ISO)."
- )
-
-
-class SupplyFlow(BaseModel):
- """The flow of products or information between supply chain actors."""
-
- source: str = Field(description="The starting entity (sender/producer).")
- target: str = Field(description="The receiving entity (buyer/processor).")
- flow_type: str = Field(
- description="Type: 'Ships to', 'Processes', 'Sells to', 'Tests', 'Certifies'."
- )
- specification: Optional[str] = Field(
- description="Quantity, transportation mode, or quality check result."
- )
-
-
-# ==============================================================================
-# 2. Prompts
-# ==============================================================================
-
-AGRI_SUPPLY_CHAIN_PROMPT = (
- "You are a supply chain analyst specializing in agriculture. Extract a traceability and logistics graph.\n\n"
- "Guidelines:\n"
- "- Identify all actors involved from the farm to the fork (Producer, Processor, Distributor).\n"
- "- Map the flow of specific batches or products through various stages.\n"
- "- Capture quality checks, certifications, and transportation modes mentioned in the text."
-)
-
-AGRI_SUPPLY_CHAIN_NODE_PROMPT = (
- "Extract supply chain entities: identify specific farms, factories, logistics hubs, and retailers. "
- "Note their roles, locations, and any quality certifications mentioned."
-)
-
-AGRI_SUPPLY_CHAIN_EDGE_PROMPT = (
- "Establish the movement of goods and information. Connect producers to processors, and processors to retailers. "
- "Use specific relation types like 'Ships to' or 'Processes', and include details like transport methods or quantities."
-)
-
-# ==============================================================================
-# 3. Template Class
-# ==============================================================================
-
-
-class AgriSupplyChain(AutoGraph[SupplyEntity, SupplyFlow]):
- """
- Template for agricultural traceability, logistics mapping, and supply chain transparency.
-
- Ideal for food safety tracking, logistics optimization, and trade analysis.
-
- Example:
- >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
- >>> llm = ChatOpenAI(model="gpt-4o")
- >>> embedder = OpenAIEmbeddings()
- >>> graph = AgriSupplyChain(llm_client=llm, embedder=embedder)
- >>> text = "Batch #A102 was shipped from GreenFarm (Organic) to CentralProcessor via cold-chain truck."
- >>> graph.feed_text(text)
- >>> print(graph.edges) # Extracted logistics flow
- """
-
- def __init__(
- self,
- llm_client: BaseChatModel,
- embedder: Embeddings,
- *,
- extraction_mode: str = "one_stage",
- chunk_size: int = 2048,
- chunk_overlap: int = 256,
- max_workers: int = 10,
- verbose: bool = False,
- **kwargs: Any,
- ):
- """
- Initialize the AgriSupplyChain template.
-
- Args:
- llm_client: The language model client for extraction.
- embedder: The embedding model for deduplication.
- extraction_mode: "one_stage" or "two_stage".
- chunk_size: Max characters per chunk.
- chunk_overlap: Overlap between chunks.
- max_workers: Parallel processing workers.
- verbose: Enable progress logging.
- **kwargs: Extra arguments for AutoGraph.
- """
- super().__init__(
- node_schema=SupplyEntity,
- edge_schema=SupplyFlow,
- node_key_extractor=lambda x: x.name.strip(),
- edge_key_extractor=lambda x: (
- f"{x.source.strip()}--({x.flow_type.lower()})-->{x.target.strip()}"
- ),
- nodes_in_edge_extractor=lambda x: (x.source.strip(), x.target.strip()),
- llm_client=llm_client,
- embedder=embedder,
- extraction_mode=extraction_mode,
- chunk_size=chunk_size,
- chunk_overlap=chunk_overlap,
- max_workers=max_workers,
- verbose=verbose,
- prompt=AGRI_SUPPLY_CHAIN_PROMPT,
- prompt_for_node_extraction=AGRI_SUPPLY_CHAIN_NODE_PROMPT,
- prompt_for_edge_extraction=AGRI_SUPPLY_CHAIN_EDGE_PROMPT,
- **kwargs,
- )
-
- def show(
- self,
- *,
- top_k_nodes_for_search: int = 3,
- top_k_edges_for_search: int = 3,
- top_k_nodes_for_chat: int = 3,
- top_k_edges_for_chat: int = 3,
- ) -> None:
- """
- Visualize the graph using OntoSight.
-
- Args:
- top_k_nodes_for_search (int): Number of nodes to retrieve for search context. Default 3.
- top_k_edges_for_search (int): Number of edges to retrieve for search context. Default 3.
- top_k_nodes_for_chat (int): Number of nodes to retrieve for chat context. Default 3.
- top_k_edges_for_chat (int): Number of edges to retrieve for chat context. Default 3.
- """
-
- def node_label_extractor(node: SupplyEntity) -> str:
- info = f" ({node.category})" if getattr(node, "category", None) else ""
- return f"{node.name}{info}"
-
- def edge_label_extractor(edge: SupplyFlow) -> str:
- return f"{edge.flow_type}"
-
- super().show(
- node_label_extractor=node_label_extractor,
- edge_label_extractor=edge_label_extractor,
- top_k_nodes_for_search=top_k_nodes_for_search,
- top_k_edges_for_search=top_k_edges_for_search,
- top_k_nodes_for_chat=top_k_nodes_for_chat,
- top_k_edges_for_chat=top_k_edges_for_chat,
- )
diff --git a/hyperextract/templates/zh/__init__.py b/hyperextract/templates/zh/__init__.py
index db5ed8b..f45d0ea 100644
--- a/hyperextract/templates/zh/__init__.py
+++ b/hyperextract/templates/zh/__init__.py
@@ -1,21 +1,15 @@
-from .general.knowledge_graph import KnowledgeGraph
-from .general.concept_map import ConceptMap
-from .general.logic_graph import LogicGraph
-from .agriculture.crop import CropStatusGraph
-from .agriculture.soil import SoilNutritionGraph
-from .biology.taxonomy import TaxonomyGraph
-from .biology.network import BiologicalNetwork
-from .biology.metabolic import MetabolicHypergraph
-from .chemistry.molecular import MolecularStructureGraph
-from .chemistry.reaction import ChemicalReactionHyper
-from .chemistry.protocol import LabProtocolTemporal
+from .general import KnowledgeGraph, ConceptMap, LogicGraph
+from .agriculture import CropCycleGraph, LivestockGraph, AgriPestControl
+from .biology import TaxonomyGraph, BiologicalNetwork, MetabolicHypergraph
+from .chemistry import MolecularStructureGraph, ChemicalReactionHyper, LabProtocolTemporal
__all__ = [
"KnowledgeGraph",
"ConceptMap",
"LogicGraph",
- "CropStatusGraph",
- "SoilNutritionGraph",
+ "CropCycleGraph",
+ "LivestockGraph",
+ "AgriPestControl",
"TaxonomyGraph",
"BiologicalNetwork",
"MetabolicHypergraph",
diff --git a/hyperextract/templates/zh/agriculture/__init__.py b/hyperextract/templates/zh/agriculture/__init__.py
index 34c0d82..556a0eb 100644
--- a/hyperextract/templates/zh/agriculture/__init__.py
+++ b/hyperextract/templates/zh/agriculture/__init__.py
@@ -1,6 +1,6 @@
-from .crop_cycle import CropCycleGraph, AgriEntity, AgriRelation
+from .crop_cycle import CropCycleGraph, AgriEntity, AgriRelation
from .livestock import LivestockGraph, AnimalNode, BreedingRelation
-from .supply_chain import AgriSupplyChain, SupplyEntity, SupplyFlow
+from .pest_control import AgriPestControl, AgriPestEntity, AgriPestRelation
__all__ = [
"CropCycleGraph",
@@ -9,7 +9,7 @@ __all__ = [
"LivestockGraph",
"AnimalNode",
"BreedingRelation",
- "AgriSupplyChain",
- "SupplyEntity",
- "SupplyFlow"
+ "AgriPestControl",
+ "AgriPestEntity",
+ "AgriPestRelation"
]
diff --git a/hyperextract/templates/zh/agriculture/pest_control.py b/hyperextract/templates/zh/agriculture/pest_control.py
new file mode 100644
index 0000000..ddb6b8d
--- /dev/null
+++ b/hyperextract/templates/zh/agriculture/pest_control.py
@@ -0,0 +1,117 @@
+from typing import Optional, Any, Callable
+from pydantic import BaseModel, Field
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.embeddings import Embeddings
+from hyperextract.types.graph import AutoGraph
+
+# ==============================================================================
+# 1. Schema 定义
+# ==============================================================================
+
+
+class AgriPestEntity(BaseModel):
+ """农业病虫害防治领域的实体(如害虫、病害、作物、症状、防治方法)。"""
+
+ name: str = Field(description="病虫害、作物、病原体或药剂的名称。")
+ category: str = Field(
+ description="类别:'害虫', '病害', '寄主作物', '受害症状', '防治方法', '化学药剂'。"
+ )
+ description: Optional[str] = Field(
+ None, description="详细描述、生物学特征或发生规律。"
+ )
+
+
+class AgriPestRelation(BaseModel):
+ """农业实体之间的关系(如'危害'、'导致'、'防治手段')。"""
+
+ source: str = Field(description="源实体名称。")
+ target: str = Field(description="目标实体名称。")
+ relation_type: str = Field(
+ description="类型:'危害', '寄生', '导致症状', '防治手段', '对...敏感', '发生于'。"
+ )
+ detail: Optional[str] = Field(
+ None, description="具体的发生环境、用药剂量或危害程度。"
+ )
+
+
+# ==============================================================================
+# 2. 提示词 (Prompt)
+# ==============================================================================
+
+_TEMPLATE_PROMPT = """
+你是一位资深农艺师和植物保护专家。
+你的任务是从文本中提取详尽的农作物病虫害及其防治知识图谱。
+
+指南:
+1. 识别生物威胁:包括害虫、真菌、细菌、病毒或杂草。
+2. 建立威胁与寄主作物、具体受害症状(如:叶斑、秆腐、卷叶)之间的链接。
+3. 映射病虫害综合防治 (IPM) 策略,包括生物防治、物理防治和化学防治方法。
+4. 提取文本中提到的具体农药名称、施用剂量及最佳施药时期。
+"""
+
+# ==============================================================================
+# 3. 模板类
+# ==============================================================================
+
+
+class AgriPestControl(AutoGraph[AgriPestEntity, AgriPestRelation]):
+ """
+ 农业病虫害防治知识图谱模板。
+
+ 将技术手册和防治指南转化为结构化的防治策略。
+ """
+
+ def __init__(
+ self,
+ llm_client: BaseChatModel,
+ embedder: Embeddings,
+ *,
+ extraction_mode: str = "one_stage",
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
+ max_workers: int = 10,
+ verbose: bool = False,
+ **kwargs: Any,
+ ):
+ """初始化 AgriPestControl 模板。"""
+ super().__init__(
+ node_schema=AgriPestEntity,
+ edge_schema=AgriPestRelation,
+ node_key_extractor=lambda x: x.name.strip(),
+ edge_key_extractor=lambda x: f"{x.source.strip()}--({x.relation_type.lower()})-->{x.target.strip()}",
+ nodes_in_edge_extractor=lambda x: (x.source.strip(), x.target.strip()),
+ llm_client=llm_client,
+ embedder=embedder,
+ extraction_mode=extraction_mode,
+ chunk_size=chunk_size,
+ chunk_overlap=chunk_overlap,
+ max_workers=max_workers,
+ verbose=verbose,
+ prompt=_TEMPLATE_PROMPT,
+ **kwargs,
+ )
+
+ def show(
+ self,
+ *,
+ top_k_nodes_for_search: int = 3,
+ top_k_edges_for_search: int = 3,
+ top_k_nodes_for_chat: int = 3,
+ top_k_edges_for_chat: int = 3,
+ ) -> None:
+ """可视化病虫害防治知识图谱。"""
+
+ def node_label_extractor(node: AgriPestEntity) -> str:
+ return f"{node.name} ({node.category})"
+
+ def edge_label_extractor(edge: AgriPestRelation) -> str:
+ return f"{edge.relation_type}"
+
+ super().show(
+ node_label_extractor=node_label_extractor,
+ edge_label_extractor=edge_label_extractor,
+ top_k_nodes_for_search=top_k_nodes_for_search,
+ top_k_edges_for_search=top_k_edges_for_search,
+ top_k_nodes_for_chat=top_k_nodes_for_chat,
+ top_k_edges_for_chat=top_k_edges_for_chat,
+ )
diff --git a/hyperextract/templates/zh/agriculture/supply_chain.py b/hyperextract/templates/zh/agriculture/supply_chain.py
deleted file mode 100644
index 0590415..0000000
--- a/hyperextract/templates/zh/agriculture/supply_chain.py
+++ /dev/null
@@ -1,150 +0,0 @@
-from typing import Optional, Any
-from pydantic import BaseModel, Field
-from langchain_core.language_models.chat_models import BaseChatModel
-from langchain_core.embeddings import Embeddings
-from hyperextract.types import AutoGraph
-
-# ==============================================================================
-# 1. Schema 定义 (Schema Definitions)
-# ==============================================================================
-
-
-class SupplyEntity(BaseModel):
- """农产品供应链中的参与者或资产(如农场、仓库、加工商、物流商、零售商)。"""
-
- name: str = Field(description="机构、设施的名称或批次ID。")
- category: str = Field(
- description="类别:'生产者/农场', '加工商', '分销商', '物流商', '零售商', '批次/产品'。"
- )
- location_or_cert: Optional[str] = Field(
- description="地理位置或质量认证(如:有机认证、ISO)。"
- )
-
-
-class SupplyFlow(BaseModel):
- """供应链参与者之间的产品或信息流。"""
-
- source: str = Field(description="起始实体(发送方/生产者)。")
- target: str = Field(description="接收实体(购买方/加工商)。")
- flow_type: str = Field(
- description="类型:'发货至', '加工', '销售给', '检测', '认证'。"
- )
- specification: Optional[str] = Field(description="数量、运输方式或质量检测结果。")
-
-
-# ==============================================================================
-# 2. 提示词 (Prompts)
-# ==============================================================================
-
-AGRI_SUPPLY_CHAIN_PROMPT = (
- "你是一位专注于农业的供应链分析师。请从文本中提取溯源与物流图谱。\n\n"
- "提取指南:\n"
- "- 识别从农田到餐桌(生产者、加工商、分销商)涉及的所有参与者。\n"
- "- 映射特定批次或产品经过各个阶段的流动情况。\n"
- "- 捕获文本中提到的质量检测、认证和运输方式。"
-)
-
-AGRI_SUPPLY_CHAIN_NODE_PROMPT = "请提取供应链实体:识别特定的农场、工厂、物流枢纽和零售商。记录它们的角色、位置以及提及的任何质量认证。"
-
-AGRI_SUPPLY_CHAIN_EDGE_PROMPT = "建立货物与信息的流动。连接生产者到加工商,以及加工商到零售商。使用'发货至'或'加工'等具体的关系类型,并包含运输方式或数量等细节。"
-
-# ==============================================================================
-# 3. 模板类 (Template Class)
-# ==============================================================================
-
-
-class AgriSupplyChain(AutoGraph[SupplyEntity, SupplyFlow]):
- """
- 用于农产品溯源、物流映射和供应链透明化的模板。
-
- 适用于食品安全追踪、物流优化和贸易分析。
-
- 示例:
- >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
- >>> llm = ChatOpenAI(model="gpt-4o")
- >>> embedder = OpenAIEmbeddings()
- >>> graph = AgriSupplyChain(llm_client=llm, embedder=embedder)
- >>> text = "批次#A102通过冷链卡车从绿色农场(有机认证)运往中央处理厂。"
- >>> graph.feed_text(text)
- >>> print(graph.edges) # 提取物流流向
- """
-
- def __init__(
- self,
- llm_client: BaseChatModel,
- embedder: Embeddings,
- *,
- extraction_mode: str = "one_stage",
- chunk_size: int = 2048,
- chunk_overlap: int = 256,
- max_workers: int = 10,
- verbose: bool = False,
- **kwargs: Any,
- ):
- """
- 初始化 AgriSupplyChain 模板。
-
- Args:
- llm_client: 用于提取的语言模型客户端。
- embedder: 用于去重的嵌入模型。
- extraction_mode: "one_stage" 或 "two_stage"。
- chunk_size: 每个分块的最大字符数。
- chunk_overlap: 分块间的重叠字符数。
- max_workers: 并行处理的最大 worker 数量。
- verbose: 是否开启进度日志。
- **kwargs: 传递给 AutoGraph 的其他参数。
- """
- super().__init__(
- node_schema=SupplyEntity,
- edge_schema=SupplyFlow,
- node_key_extractor=lambda x: x.name.strip(),
- edge_key_extractor=lambda x: (
- f"{x.source.strip()}--({x.flow_type.lower()})-->{x.target.strip()}"
- ),
- nodes_in_edge_extractor=lambda x: (x.source.strip(), x.target.strip()),
- llm_client=llm_client,
- embedder=embedder,
- extraction_mode=extraction_mode,
- chunk_size=chunk_size,
- chunk_overlap=chunk_overlap,
- max_workers=max_workers,
- verbose=verbose,
- prompt=AGRI_SUPPLY_CHAIN_PROMPT,
- prompt_for_node_extraction=AGRI_SUPPLY_CHAIN_NODE_PROMPT,
- prompt_for_edge_extraction=AGRI_SUPPLY_CHAIN_EDGE_PROMPT,
- **kwargs,
- )
-
- def show(
- self,
- *,
- top_k_nodes_for_search: int = 3,
- top_k_edges_for_search: int = 3,
- top_k_nodes_for_chat: int = 3,
- top_k_edges_for_chat: int = 3,
- ) -> None:
- """
- Visualize the graph using OntoSight.
-
- Args:
- top_k_nodes_for_search (int): Number of nodes to retrieve for search context. Default 3.
- top_k_edges_for_search (int): Number of edges to retrieve for search context. Default 3.
- top_k_nodes_for_chat (int): Number of nodes to retrieve for chat context. Default 3.
- top_k_edges_for_chat (int): Number of edges to retrieve for chat context. Default 3.
- """
-
- def node_label_extractor(node: SupplyEntity) -> str:
- info = f" ({node.category})" if getattr(node, "category", None) else ""
- return f"{node.name}{info}"
-
- def edge_label_extractor(edge: SupplyFlow) -> str:
- return f"{edge.flow_type}"
-
- super().show(
- node_label_extractor=node_label_extractor,
- edge_label_extractor=edge_label_extractor,
- top_k_nodes_for_search=top_k_nodes_for_search,
- top_k_edges_for_search=top_k_edges_for_search,
- top_k_nodes_for_chat=top_k_nodes_for_chat,
- top_k_edges_for_chat=top_k_edges_for_chat,
- )
diff --git a/hyperextract/types/__init__.py b/hyperextract/types/__init__.py
index d985fc0..d81883d 100644
--- a/hyperextract/types/__init__.py
+++ b/hyperextract/types/__init__.py
@@ -1,16 +1,16 @@
"""Types - Core data structures for automatic knowledge extraction.
-This module contains the fundamental, reusable data structure primitives that can
-automatically extract knowledge from text. These are the "building blocks" of the
+This module contains the fundamental, reusable data structure primitives that can
+automatically extract knowledge from text. These are the "building blocks" of the
Hyper-Extract framework.
"""
from .base import BaseAutoType
from .model import AutoModel
-from .list import AutoList, AutoListSchema
-from .set import AutoSet, AutoSetSchema
-from .graph import AutoGraph, AutoGraphSchema
-from .hypergraph import AutoHypergraph, AutoHypergraphSchema
+from .list import AutoList
+from .set import AutoSet
+from .graph import AutoGraph
+from .hypergraph import AutoHypergraph
from .temporal_graph import AutoTemporalGraph
from .spatial_graph import AutoSpatialGraph
from .spatio_temporal_graph import AutoSpatioTemporalGraph
@@ -20,16 +20,14 @@ __all__ = [
"BaseAutoType",
# Scalar types
"AutoModel",
+ # Collection types
"AutoList",
- "AutoListSchema",
"AutoSet",
- "AutoSetSchema",
# Graph types
"AutoGraph",
- "AutoGraphSchema",
- "AutoHypergraph",
- "AutoHypergraphSchema",
"AutoTemporalGraph",
"AutoSpatialGraph",
"AutoSpatioTemporalGraph",
+ # Hypergraph type
+ "AutoHypergraph",
]