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.pyindex 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, Fieldfrom langchain_openai import ChatOpenAI, OpenAIEmbeddingsfrom hyperextract.types import AutoSpatioTemporalGraph-from ontomem import MergeStrategyimport dotenvdiff --git a/examples/cog_rag_demo.py b/examples/cog_rag_demo.pyindex ce0abdb..a3fac67 100644--- a/examples/cog_rag_demo.py+++ b/examples/cog_rag_demo.py@@ -22,7 +22,7 @@ from dotenv import load_dotenvload_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 Extractiondiff --git a/examples/hyper_rag_demo.py b/examples/hyper_rag_demo.pyindex 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_dotenvfrom langchain_openai import ChatOpenAI, OpenAIEmbeddings-from hyperextract.types import Hyper_RAG+from hyperextract.methods.rag import Hyper_RAGload_dotenv()diff --git a/examples/hypergraph_rag_demo.py b/examples/hypergraph_rag_demo.pyindex 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_dotenvfrom langchain_openai import ChatOpenAI, OpenAIEmbeddings-from hyperextract.types import HyperGraph_RAG+from hyperextract.methods.rag import HyperGraph_RAGload_dotenv()diff --git a/examples/itext2kg_demo.py b/examples/itext2kg_demo.pyindex 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_dotenvfrom langchain_openai import ChatOpenAI, OpenAIEmbeddings-from hyperextract.types import iText2KG+from hyperextract.methods.typical import iText2KGload_dotenv()diff --git a/examples/itext2kg_star_demo.py b/examples/itext2kg_star_demo.pyindex 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_dotenvfrom langchain_openai import ChatOpenAI, OpenAIEmbeddings-from hyperextract.types.itext2kg_star import iText2KG_Star+from hyperextract.methods.typical import iText2KG_Starload_dotenv()diff --git a/examples/kg_gen_demo.py b/examples/kg_gen_demo.pyindex 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_dotenvfrom langchain_openai import ChatOpenAI, OpenAIEmbeddings-from hyperextract.types import KG_Gen+from hyperextract.methods.typical import KG_Genload_dotenv()diff --git a/hyperextract/methods/rag/__init__.py b/hyperextract/methods/rag/__init__.pyindex 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 structuresfrom .hyper_rag import Hyper_RAGfrom .hypergraph_rag import HyperGraph_RAG-from .cog_rag import Cog_RAG, Cog_RAG_ThemeLayer, Cog_RAG_DetailLayer+from .cog_rag import Cog_RAGfrom .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.pyindex 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 cfrom typing import Listfrom hashlib import md5from pydantic import BaseModel, Field-from hyperextract.types import AutoHypergraph, AutoHypergraphSchema+from hyperextract.types.hypergraph import AutoHypergraph, AutoHypergraphSchemafrom langchain_core.prompts import ChatPromptTemplatefrom langchain_core.embeddings import Embeddingsfrom 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.pyindex 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 BaseChatModelfrom langchain_core.prompts.chat import ChatPromptTemplatefrom 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.pyindex 2618f97..7f5b407 100644--- a/hyperextract/methods/typical/atom.py+++ b/hyperextract/methods/typical/atom.py@@ -17,7 +17,7 @@ from langchain_core.embeddings import Embeddingsfrom ontomem.merger import MergeStrategy, CustomRuleMergerfrom 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 implementationdiff --git a/hyperextract/methods/typical/itext2kg_star.py b/hyperextract/methods/typical/itext2kg_star.pyindex 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 ChatPromptTemplatefrom langchain_core.embeddings import Embeddingsfrom ontomem.merger import MergeStrategy-from hyperextract.types import AutoGraph, AutoGraphSchema+from hyperextract.types.graph import AutoGraph, AutoGraphSchemafrom hyperextract.utils.logging import logger# ==============================================================================diff --git a/hyperextract/methods/typical/kg_gen.py b/hyperextract/methods/typical/kg_gen.pyindex 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 BaseChatModelfrom langchain_core.embeddings import Embeddingsfrom ontomem.merger import MergeStrategy-from hyperextract.types import AutoGraph, AutoGraphSchema+from hyperextract.types.graph import AutoGraph, AutoGraphSchemafrom hyperextract.utils.logging import logger# ==============================================================================diff --git a/hyperextract/templates/INSTRUCTION.md b/hyperextract/templates/INSTRUCTION.mdnew file mode 100644index 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.mdnew file mode 100644index 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__.pyindex 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__.pyindex 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, AgriRelationfrom .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.pynew file mode 100644index 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.pydeleted file mode 100644index 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__.pyindex 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__.pyindex 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, AgriRelationfrom .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.pynew file mode 100644index 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.pydeleted file mode 100644index 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__.pyindex 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 theHyper-Extract framework."""from .base import BaseAutoTypefrom .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 AutoHypergraphfrom .temporal_graph import AutoTemporalGraphfrom .spatial_graph import AutoSpatialGraphfrom .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",]