Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
refactor(template): 重构模板加载和搜索接口
yifanfeng97b59b2c50bce8
diff --git a/examples/template_api_demo.py b/examples/template_api_demo.pyindex c705711..d90d326 100644--- a/examples/template_api_demo.py+++ b/examples/template_api_demo.py@@ -23,6 +23,8 @@ from langchain_openai import ChatOpenAI, OpenAIEmbeddingsINPUT_FILE = Path(__file__).parent.parent / "tests" / "test_data" / "templates" / "biography_scientist.md"+name = "life_event_timeline"+# name = "knowledge_graph"def main():print("=" * 60)@@ -34,53 +36,49 @@ def main():returnprint(f"\n📄 输入文件: {INPUT_FILE.name}")- print(f"🎯 使用模板: general/life_event_timeline")+ print(f"🎯 使用模板: general/{name}")llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)embedder = OpenAIEmbeddings(model="text-embedding-3-small")print("\n[1] Template.list() - 列出所有模板")- names = Template.list()- print(f"共 {len(names)} 个模板")+ templates = Template.list()+ print(f"共 {len(templates)} 个模板")- print("\n[2] Template.list_domains() - 列出所有领域")- domains = Template.list_domains()- print(f"共 {len(domains)} 个领域: {domains}")-- print("\n[3] Template.get() - 获取配置")- config = Template.get("general/life_event_timeline")+ print("\n[2] Template.get() - 获取配置")+ config = Template.get(f"general/{name}")if config:print(f"找到: {config.name}, type: {config.type}")else:print("未找到")- print("\n[4] Template.search(type='list') - 按类型搜索")- results = Template.search(type="list")+ print("\n[3] Template.list(filter_by_type='list') - 按类型搜索")+ results = Template.list(filter_by_type="list")print(f"找到 {len(results)} 个 list 类型模板")- print("\n[5] Template.create() - 通过文件路径创建实例")+ print("\n[4] Template.create() - 通过文件路径创建实例")template = Template.create(- 'life_event_timeline',+ name,+ language="zh",llm_client=llm,embedder=embedder,- language="zh",)print(f"创建成功: {type(template).__name__}")- print("\n[6] 读取输入文件")+ print("\n[5] 读取输入文件")with open(INPUT_FILE, "r", encoding="utf-8") as f:content = f.read()print(f"读取成功,共 {len(content)} 字符")- print("\n[7] template.feed_text() - 喂入文本")+ print("\n[6] template.feed_text() - 喂入文本")template.feed_text(content)print("✅ 知识提取完成")- print("\n[8] template.build_index() - 构建索引")+ print("\n[7] template.build_index() - 构建索引")template.build_index()print("✅ 索引构建完成")- print("\n[9] template.show() - 展示结果")+ print("\n[8] template.show() - 展示结果")template.show()print("\n" + "=" * 60)diff --git a/hyperextract/templates/presets/general/graph.yaml b/hyperextract/templates/presets/general/graph.yamlnew file mode 100644index 0000000..c2c712e--- /dev/null+++ b/hyperextract/templates/presets/general/graph.yaml@@ -0,0 +1,62 @@+language: zh+name: knowledge_graph+type: graph+tags: [general]+description: '通用知识图谱 - 提取实体和它们之间的关系'++output:+ description: '通用知识图谱结构'+ entities:+ description: '提取的实体'+ fields:+ - name: name+ type: str+ description: '实体名称'+ - name: type+ type: str+ description: '实体类型'+ - name: description+ type: str+ description: '实体描述'+ required: false+ relations:+ description: '实体之间的关系'+ fields:+ - name: source+ type: str+ description: '源实体'+ - name: target+ type: str+ description: '目标实体'+ - name: description+ type: str+ description: '关系描述'+ required: false++guideline:+ target:+ zh: '你是一位知识图谱专家,请从文本中提取实体和它们之间的关系。'+ rules_for_entities:+ zh:+ - '提取所有相关实体'+ - '为每个实体指定类型'+ - '实体类型包括:人物、地点、组织、物品、概念、事件等'+ rules_for_relations:+ zh:+ - '仅从提取的实体中创建关系边'+ - '关系类型包括:包含、属于、相关、影响、合作、竞争等'+ - 'source 和 target 都必须是已提取的实体'++identifiers:+ entity_id: name+ relation_id: '{source}|{target}'+ relation_members:+ source: source+ target: target++options:+ extraction_mode: two_stage++display:+ entity_label: '{name} ({type})'+ relation_label: '{description}'diff --git a/hyperextract/types/graph.py b/hyperextract/types/graph.pyindex 5fe0189..1dd6c7e 100644--- a/hyperextract/types/graph.py+++ b/hyperextract/types/graph.py@@ -291,8 +291,8 @@ class AutoGraph()# Store label extractors for visualization- self.node_label_extractor = node_label_extractor- self.edge_label_extractor = edge_label_extractor+ self._node_label_extractor = node_label_extractor+ self._edge_label_extractor = edge_label_extractor# Call parent initsuper().__init__(diff --git a/hyperextract/types/hypergraph.py b/hyperextract/types/hypergraph.pyindex 3f9ee00..d5c6987 100644--- a/hyperextract/types/hypergraph.py+++ b/hyperextract/types/hypergraph.py@@ -296,8 +296,8 @@ class AutoHypergraph()# Store label extractors for visualization- self.node_label_extractor = node_label_extractor- self.edge_label_extractor = edge_label_extractor+ self._node_label_extractor = node_label_extractor+ self._edge_label_extractor = edge_label_extractor# Initialize Base Classsuper().__init__(diff --git a/hyperextract/utils/template_engine/factory.py b/hyperextract/utils/template_engine/factory.pyindex c0e0f6b..de3da5d 100644--- a/hyperextract/utils/template_engine/factory.py+++ b/hyperextract/utils/template_engine/factory.py@@ -328,9 +328,9 @@ class TemplateFactory:def create(cls,source: Union[str, Path, TemplateCfg],+ language: str,llm_client: BaseChatModel,embedder: Embeddings,- language: str = "zh",**kwargs,):"""Create template instance based on configuration.@@ -340,9 +340,9 @@ class TemplateFactory:- str: Template name (e.g., "knowledge_graph") or file path- Path: YAML file path- TemplateCfg: Template configuration instance+ language: Language code for localization (e.g., 'zh', 'en') - requiredllm_client: LLM clientembedder: Embedding model- language: Language code for localization (e.g., 'zh', 'en')**kwargs: Additional parameters to override config parameterse.g., observation_time="2024-06-15", observation_location="Beijing"@@ -351,23 +351,23 @@ class TemplateFactory:Examples:# By name (search via Gallery)- template = TemplateFactory.create("knowledge_graph", llm, embedder)+ template = TemplateFactory.create("knowledge_graph", "zh", llm, embedder)# By file path- template = TemplateFactory.create("/path/to/template.yaml", llm, embedder)+ template = TemplateFactory.create("/path/to/template.yaml", "zh", llm, embedder)# By TemplateCfg instance- template = TemplateFactory.create(config, llm, embedder)+ template = TemplateFactory.create(config, "zh", llm, embedder)# For specific language- template = TemplateFactory.create("knowledge_graph", llm, embedder, language="en")+ template = TemplateFactory.create("knowledge_graph", "en", llm, embedder)# For spatio-temporal templates, pass observation_time etc.template = TemplateFactory.create("FinancialTemporalGraph",+ "zh",llm,embedder,- language="zh",observation_time="2024-06-15",observation_location="Beijing")diff --git a/hyperextract/utils/template_engine/gallery.py b/hyperextract/utils/template_engine/gallery.pyindex e0aa47d..4d827e7 100644--- a/hyperextract/utils/template_engine/gallery.py+++ b/hyperextract/utils/template_engine/gallery.py@@ -4,7 +4,7 @@ Auto-loads templates from presets directory."""from pathlib import Path-from typing import Dict, List, Optional+from typing import Dict, Optionalfrom .parsers import TemplateCfg, load_template@@ -18,14 +18,12 @@ class Gallery:# Get template by pathconfig = Gallery.get("general/knowledge_graph")- # List all templates- print(Gallery.list())+ # List all templates (returns Dict[str, TemplateCfg])+ all_templates = Gallery.list()- # List domains- print(Gallery.list_domains())-- # Search templates- results = Gallery.search(type="graph")+ # List templates with filters+ graph_templates = Gallery.list(filter_by_type="graph")+ zh_templates = Gallery.list(filter_by_language="zh")"""_instance: Optional["Gallery"] = None@@ -53,39 +51,30 @@ class Gallery:return cls._instance._configs.get(f"general/{path}")@classmethod- def list(cls) -> List[str]:- """List all available template names.-- Returns:- List of template names- """- return list(cls._instance._configs.keys()) if cls._instance else []-- @classmethod- def search(+ def list(cls,- query: str = None,- type: str = None,- tag: str = None,- language: str = None,- ) -> List[TemplateCfg]:- """Search templates by query, type, tag, or language.+ filter_by_query: str = None,+ filter_by_type: str = None,+ filter_by_tag: str = None,+ filter_by_language: str = None,+ ) -> Dict[str, "TemplateCfg"]:+ """List templates with optional filters.Args:- query: Search in template name/description- type: Filter by autotype (e.g., "graph", "list", "model")- tag: Filter by tag- language: Filter by language (e.g., "zh", "en")+ filter_by_query: Search in template name/description+ filter_by_type: Filter by autotype (e.g., "graph", "list", "model")+ filter_by_tag: Filter by tag+ filter_by_language: Filter by language (e.g., "zh", "en")Returns:- List of matching TemplateCfg+ Dict mapping template name to TemplateCfg"""if not cls._instance:- return []+ return {}- results = []- for config in cls._instance._configs.values():- q = query.lower() if query else None+ results = {}+ for key, config in cls._instance._configs.items():+ q = filter_by_query.lower() if filter_by_query else Noneif q and q not in config.name.lower():desc = config.description@@ -96,36 +85,21 @@ class Gallery:):continue- if type and config.type != type:+ if filter_by_type and config.type != filter_by_type:continue- if tag and (not config.tags or tag not in config.tags):+ if filter_by_tag and (not config.tags or filter_by_tag not in config.tags):continue- if language:+ if filter_by_language:config_lang = config.languageif isinstance(config_lang, list):- if language not in config_lang:+ if filter_by_language not in config_lang:continue- elif config_lang != language:+ elif config_lang != filter_by_language:continue- results.append(config)+ results[key] = configreturn results- @classmethod- def list_domains(cls) -> List[str]:- """List all available domains (folder names in presets).-- Returns:- List of domain names- """- base_dir = Path(__file__).parent.parent.parent / "templates" / "presets"- domains = []- if base_dir.exists():- for item in base_dir.iterdir():- if item.is_dir() and not item.name.startswith("_"):- domains.append(item.name)- return sorted(domains)-def _load_config(self, file_path: Path, presets_dir: Path) -> None:try:config = load_template(file_path)diff --git a/hyperextract/utils/template_engine/parsers/identifiers.py b/hyperextract/utils/template_engine/parsers/identifiers.pyindex e732f03..ea4f9a1 100644--- a/hyperextract/utils/template_engine/parsers/identifiers.py+++ b/hyperextract/utils/template_engine/parsers/identifiers.py@@ -43,9 +43,9 @@ def _extractor(field_or_template: str) -> Callable[[Any], str]:def _members_extractor(members: dict[str, str] | str | list[str],) -> Callable[[Any], Tuple[str, ...]]:- """Relation members extractor:+ """Relation members extractor:Graph: {source: 's', target: 't'} -> lambda x: (x.s, x.t)- Hypergraph: 'members' -> lambda x: tuple(sorted(x.members)) or+ Hypergraph: 'members' -> lambda x: tuple(sorted(x.members)) or'members' -> lambda x: tuple(sorted(x.m) for m in x.members)"""# Handle Graph@@ -54,8 +54,10 @@ def _members_extractor(def extractor(item: Any) -> Tuple[str, str]:return tuple(sorted(- str(getattr(item, "source")),- str(getattr(item, "target")),+ [+ str(getattr(item, "source")),+ str(getattr(item, "target")),+ ]))@@ -120,7 +122,7 @@ def parse_identifiers(if autotype in ("spatial_graph", "spatio_temporal_graph"):location_extractor = _extractor(identifiers.location_field)rets.append(location_extractor)-+return tuple(rets)return Nonediff --git a/hyperextract/utils/template_engine/parsers/loader.py b/hyperextract/utils/template_engine/parsers/loader.pyindex 1b76dd8..66df71e 100644--- a/hyperextract/utils/template_engine/parsers/loader.py+++ b/hyperextract/utils/template_engine/parsers/loader.py@@ -38,7 +38,7 @@ class TemplateCfg(BaseModel):def _localize_data(- value: str | List[str] | Dict[str, str | List[str]] | None,+ value: str | List[str] | Dict[str, str | List[str]],language: str,) -> str:"""Get multilingual text value, supports list formatdiff --git a/hyperextract/utils/template_engine/parsers/output.py b/hyperextract/utils/template_engine/parsers/output.pyindex f2c5730..677612b 100644--- a/hyperextract/utils/template_engine/parsers/output.py+++ b/hyperextract/utils/template_engine/parsers/output.py@@ -29,11 +29,14 @@ def build_naive_schema(kwargs = {"description": field.description,}- if field.required is not None:- kwargs["required"] = field.requiredif field.default is not None:kwargs["default"] = field.default- schema_fields[field.name] = (TYPE_MAPPING[field.type], Field(**kwargs))+ elif field.required is False: # 非必填且无默认值时,设 default=None+ kwargs["default"] = None+ schema_fields[field.name] = (+ TYPE_MAPPING[field.type],+ Field(**kwargs),+ )return create_model(name, __doc__=description, **schema_fields)diff --git a/hyperextract/utils/template_engine/template.py b/hyperextract/utils/template_engine/template.pyindex 6ad692f..317228e 100644--- a/hyperextract/utils/template_engine/template.py+++ b/hyperextract/utils/template_engine/template.py@@ -3,7 +3,7 @@Provides a clean API for searching and creating knowledge extraction templates."""-from typing import List, Optional+from typing import Dict, Optionalfrom pathlib import Pathfrom langchain_core.language_models import BaseChatModel@@ -26,33 +26,29 @@ class Template:# Get template config by pathconfig = Template.get("general/knowledge_graph")- # Search templates- results = Template.search(type="graph")- results = Template.search(tag="finance")- results = Template.search(query="知识图谱")+ # List all templates (returns Dict[str, TemplateCfg])+ all_templates = Template.list()- # List all templates- names = Template.list()-- # List domains- domains = Template.list_domains()+ # List templates with filters+ graph_templates = Template.list(filter_by_type="graph")+ zh_templates = Template.list(filter_by_language="zh")"""@staticmethoddef create(source: str | Path,+ language: str,llm_client: Optional[BaseChatModel] = None,embedder: Optional[Embeddings] = None,- language: str = "en",**kwargs,):"""Create template instance.Args:source: Template path (e.g., "general/knowledge_graph") or file path+ language: Language code (e.g., "zh", "en") - requiredllm_client: LLM client (reads from global config if not provided)embedder: Embedder client (reads from global config if not provided)- language: Language code (e.g., "zh", "en")**kwargs: Additional parametersReturns:@@ -60,14 +56,15 @@ class Template:Examples:# By path- template = Template.create("general/knowledge_graph", llm, emb)+ template = Template.create("general/knowledge_graph", "zh", llm, emb)# By file path- template = Template.create("/path/to/template.yaml", llm, emb)+ template = Template.create("/path/to/template.yaml", "zh", llm, emb)# For temporal/spatial templatestemplate = Template.create("finance/financial_data_temporal_graph",+ "zh",llm,emb,observation_time="2024-06-15"@@ -82,7 +79,7 @@ class Template:llm_client = llm_client or default_llmembedder = embedder or default_emb- return TemplateFactory.create(source, llm_client, embedder, language=language, **kwargs)+ return TemplateFactory.create(source, language, llm_client, embedder, **kwargs)@staticmethoddef get(path: str) -> Optional[TemplateCfg]:@@ -97,44 +94,28 @@ class Template:return Gallery.get(path)@staticmethod- def search(- query: Optional[str] = None,- type: Optional[str] = None,- tag: Optional[str] = None,- language: Optional[str] = None,- ) -> List[TemplateCfg]:- """Search templates by various criteria.+ def list(+ filter_by_query: Optional[str] = None,+ filter_by_type: Optional[str] = None,+ filter_by_tag: Optional[str] = None,+ filter_by_language: Optional[str] = None,+ ) -> Dict[str, TemplateCfg]:+ """List templates with optional filters.Args:- query: Search in template name/description- type: Filter by autotype (e.g., "graph", "list", "model")- tag: Filter by tag (e.g., "finance", "medicine")- language: Filter by language (e.g., "zh", "en")+ filter_by_query: Search in template name/description+ filter_by_type: Filter by autotype (e.g., "graph", "list", "model")+ filter_by_tag: Filter by tag+ filter_by_language: Filter by language (e.g., "zh", "en")Returns:- List of matching TemplateCfg objects+ Dict mapping template name to TemplateCfg"""- return Gallery.search(- query=query,- type=type,- tag=tag,- language=language,+ return Gallery.list(+ filter_by_query=filter_by_query,+ filter_by_type=filter_by_type,+ filter_by_tag=filter_by_tag,+ filter_by_language=filter_by_language,)- @staticmethod- def list() -> List[str]:- """List all available template names.-- Returns:- List of template names- """- return Gallery.list()- @staticmethod- def list_domains() -> List[str]:- """List all available domains (folder names in presets).-- Returns:- List of domain names- """- return Gallery.list_domains()