Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
refactor(template_engine): 重构模板引擎API,优化接口设计和实现
yifanfeng9796065b7f7fce
diff --git a/examples/template_api_demo.py b/examples/template_api_demo.pynew file mode 100644index 0000000..4d124e8--- /dev/null+++ b/examples/template_api_demo.py@@ -0,0 +1,78 @@+"""Template API 测试演示++这个文件用于测试 hyperextract 的统一 Template API。++使用方法:+ python examples/template_api_demo.py+"""++import os+import sys++sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))++from pathlib import Path+from dotenv import load_dotenv++load_dotenv()++from hyperextract.utils.template_engine import Template++from langchain_openai import ChatOpenAI, OpenAIEmbeddings+++def main():+ llm = ChatOpenAI(model="gpt-4o-mini")+ embedder = OpenAIEmbeddings(model="text-embedding-3-small")++ print("=" * 60)+ print("Template API 测试")+ print("=" * 60)++ print("\n[1] Template.list() - 列出所有模板")+ names = Template.list()+ print(f"共 {len(names)} 个模板")+ print(f"前10个: {names[:10]}")++ print("\n[2] Template.list_domains() - 列出所有领域")+ domains = Template.list_domains()+ print(f"共 {len(domains)} 个领域: {domains}")++ print("\n[3] Template.get() - 通过路径获取配置")+ config = Template.get("general/knowledge_graph")+ if config:+ print(f"找到: {config.name}, type: {config.type}")+ else:+ print("未找到")++ print("\n[4] Template.search(type='graph') - 按类型搜索")+ results = Template.search(type="graph")+ print(f"找到 {len(results)} 个 graph 类型模板")+ if results:+ print(f"前5个: {[r.name for r in results[:5]]}")++ print("\n[5] Template.search(query='知识图谱') - 模糊搜索")+ results = Template.search(query="知识图谱")+ print(f"找到 {len(results)} 个匹配模板")+ if results:+ print(f"前5个: {[r.name for r in results[:5]]}")++ print("\n[6] Template.create() - 创建实例(通过路径)")+ template = Template.create("general/knowledge_graph", llm, embedder)+ print(f"创建成功: {type(template).__name__}")++ print("\n[7] 测试 parse")+ test_text = "苹果公司成立于1976年,总部位于加利福尼亚州库比蒂诺。"+ try:+ result = template.parse(test_text)+ print(f"解析结果: {result}")+ except Exception as e:+ print(f"解析出错(正常,API调用): {e}")++ print("\n" + "=" * 60)+ print("测试完成!")+ print("=" * 60)+++if __name__ == "__main__":+ main()diff --git a/hyperextract/utils/template_engine/factory.py b/hyperextract/utils/template_engine/factory.pyindex 0fcd040..8d2ef57 100644--- a/hyperextract/utils/template_engine/factory.py+++ b/hyperextract/utils/template_engine/factory.py@@ -3,7 +3,8 @@Supports all 8 AutoType dynamic generation."""-from typing import TYPE_CHECKING+from typing import TYPE_CHECKING, Union+from pathlib import Pathfrom langchain_core.language_models import BaseChatModelfrom langchain_core.embeddings import Embeddings@@ -45,11 +46,8 @@ class TemplateFactory:from hyperextract.types import AutoModeldata_schema = parse_output(config.output, config.type)-prompt = parse_guideline(config.guideline, config.type)-options = parse_option(config.options, config.type, override=kwargs)-label_extractor = parse_display(config.display, config.type)return AutoModel(@@ -73,11 +71,8 @@ class TemplateFactory:from hyperextract.types import AutoListdata_schema = parse_output(config.output, config.type)-prompt = parse_guideline(config.guideline, config.type)-options = parse_option(config.options, config.type, override=kwargs)-item_label_extractor = parse_display(config.display, config.type)return AutoList(@@ -101,13 +96,9 @@ class TemplateFactory:from hyperextract.types import AutoSetdata_schema = parse_output(config.output, config.type)-item_id_extractor = parse_identifiers(config.identifiers, config.type)-prompt = parse_guideline(config.guideline, config.type)-options = parse_option(config.options, config.type, override=kwargs)-item_label_extractor = parse_display(config.display, config.type)return AutoSet(@@ -132,20 +123,16 @@ class TemplateFactory:from hyperextract.types import AutoGraphentity_schema, relation_schema = parse_output(config.output, config.type)-identifiers = parse_identifiers(config.identifiers, config.type)entity_key_extractor, relation_key_extractor, entities_in_relation_extractor = (identifiers)-prompt, prompt_for_entity_extraction, prompt_for_relation_extraction = (parse_guideline(config.guideline, config.type))-node_label_extractor, edge_label_extractor = parse_display(config.display, config.type)-options = parse_option(config.options, config.type, override=kwargs)return AutoGraph(@@ -176,20 +163,16 @@ class TemplateFactory:from hyperextract.types import AutoHypergraphentity_schema, relation_schema = parse_output(config.output, config.type)-identifiers = parse_identifiers(config.identifiers, config.type)entity_key_extractor, relation_key_extractor, entities_in_relation_extractor = (identifiers)-prompt, prompt_for_entity_extraction, prompt_for_relation_extraction = (parse_guideline(config.guideline, config.type))-node_label_extractor, edge_label_extractor = parse_display(config.display, config.type)-options = parse_option(config.options, config.type, override=kwargs)return AutoHypergraph(@@ -229,11 +212,9 @@ class TemplateFactory:prompt, prompt_for_entity_extraction, prompt_for_relation_extraction = (parse_guideline(config.guideline, config.type))-node_label_extractor, edge_label_extractor = parse_display(config.display, config.type)-options = parse_option(config.options, config.type, override=kwargs)return AutoTemporalGraph(@@ -265,7 +246,6 @@ class TemplateFactory:from hyperextract.types import AutoSpatialGraphentity_schema, relation_schema = parse_output(config.output, config.type)-identifiers = parse_identifiers(config.identifiers, config.type)(entity_key_extractor,@@ -273,15 +253,12 @@ class TemplateFactory:entities_in_relation_extractor,location_in_edge_extractor,) = identifiers-prompt, prompt_for_entity_extraction, prompt_for_relation_extraction = (parse_guideline(config.guideline, config.type))-node_label_extractor, edge_label_extractor = parse_display(config.display, config.type)-options = parse_option(config.options, config.type, override=kwargs)return AutoSpatialGraph(@@ -313,7 +290,6 @@ class TemplateFactory:from hyperextract.types import AutoSpatioTemporalGraphentity_schema, relation_schema = parse_output(config.output, config.type)-identifiers = parse_identifiers(config.identifiers, config.type)(entity_key_extractor,@@ -322,15 +298,12 @@ class TemplateFactory:time_in_edge_extractor,location_in_edge_extractor,) = identifiers-prompt, prompt_for_entity_extraction, prompt_for_relation_extraction = (parse_guideline(config.guideline, config.type))-node_label_extractor, edge_label_extractor = parse_display(config.display, config.type)-options = parse_option(config.options, config.type, override=kwargs)return AutoSpatioTemporalGraph(@@ -354,7 +327,7 @@ class TemplateFactory:@classmethoddef create(cls,- config: TemplateCfg,+ source: Union[str, Path, TemplateCfg],llm_client: BaseChatModel,embedder: Embeddings,language: str = "zh",@@ -363,7 +336,10 @@ class TemplateFactory:"""Create template instance based on configuration.Args:- config: Template configuration+ source: Template source - can be:+ - str: Template name (e.g., "knowledge_graph") or file path+ - Path: YAML file path+ - TemplateCfg: Template configuration instancellm_client: LLM clientembedder: Embedding modellanguage: Language code for localization (e.g., 'zh', 'en')@@ -371,18 +347,24 @@ class TemplateFactory:e.g., observation_time="2024-06-15", observation_location="Beijing"Returns:- TemplateWrapper: Wrapped template instance+ AutoType instanceExamples:- # Basic usage+ # By name (search via Gallery)+ template = TemplateFactory.create("knowledge_graph", llm, embedder)++ # By file path+ template = TemplateFactory.create("/path/to/template.yaml", llm, embedder)++ # By TemplateCfg instancetemplate = TemplateFactory.create(config, llm, embedder)# For specific language- template = TemplateFactory.create(config, llm, embedder, language="en")+ template = TemplateFactory.create("knowledge_graph", llm, embedder, language="en")# For spatio-temporal templates, pass observation_time etc.template = TemplateFactory.create(- config,+ "FinancialTemporalGraph",llm,embedder,language="zh",@@ -392,7 +374,7 @@ class TemplateFactory:# Can also override other parameterstemplate = TemplateFactory.create(- config,+ "knowledge_graph",llm,embedder,language="zh",@@ -400,71 +382,50 @@ class TemplateFactory:max_workers=20)"""- template = localize_template(config, language)-- autotype_map = {- "model": cls.create_model,- "list": cls.create_list,- "set": cls.create_set,- "graph": cls.create_graph,- "hypergraph": cls.create_hypergraph,- "temporal_graph": cls.create_temporal_graph,- "spatial_graph": cls.create_spatial_graph,- "spatio_temporal_graph": cls.create_spatio_temporal_graph,- }-- creator = autotype_map.get(template.type)- template = creator(template, llm_client, embedder, **kwargs)- return template-- @classmethod- def create_from_name(- cls,- name: str,- lang: str = "zh",- llm_client=None,- embedder=None,- **kwargs,- ):- """Create template instance by template name.-- Args:- name: Template name (e.g., "knowledge_graph", "zh/finance/risk_assessment")- lang: Language, default "zh"- llm_client: LLM client, optional, reads from global config if not provided- embedder: Embedder client, optional, reads from global config if not provided- **kwargs: Additional parameters (e.g., observation_time, observation_location)-- Returns:- AutoType instance-- Examples:- # Use global config (recommended)- template = TemplateFactory.create_from_name("knowledge_graph")-- # Custom client- template = TemplateFactory.create_from_name("knowledge_graph", llm_client=llm, embedder=emb)-- # With additional parameters- template = TemplateFactory.create_from_name("FinancialTemporalGraph", observation_time="2024-06-15")- """from .gallery import Gallery+ from .parsers import load_template++ match source:+ case str() as s if Path(s).exists():+ config = load_template(s)+ case str() as s:+ config = Gallery.get(s)+ if config is None:+ config = Gallery.get(f"{language}/{s}")+ if config is None:+ raise ValueError(f"Template '{s}' not found")+ case Path() as p if p.exists():+ config = load_template(p)+ case TemplateCfg() as cfg:+ config = cfg+ case _:+ raise ValueError(f"Invalid source type: {type(source)}")- config = Gallery.get(name)- if config is None:- config = Gallery.get(f"{lang}/{name}")-- if config is None:- available = Gallery.list_all()- raise ValueError(- f"Template '{name}' not found. Available: {available[:10]}..."- )-- if llm_client is None or embedder is None:- from hyperextract.utils import get_client-- default_llm, default_emb = get_client()- llm_client = llm_client or default_llm- embedder = embedder or default_emb+ template = localize_template(config, language)- return cls.create(config, llm_client, embedder, language=lang, **kwargs)+ match template.type:+ case "model":+ template = cls.create_model(template, llm_client, embedder, **kwargs)+ case "list":+ template = cls.create_list(template, llm_client, embedder, **kwargs)+ case "set":+ template = cls.create_set(template, llm_client, embedder, **kwargs)+ case "graph":+ template = cls.create_graph(template, llm_client, embedder, **kwargs)+ case "hypergraph":+ template = cls.create_hypergraph(+ template, llm_client, embedder, **kwargs+ )+ case "temporal_graph":+ template = cls.create_temporal_graph(+ template, llm_client, embedder, **kwargs+ )+ case "spatial_graph":+ template = cls.create_spatial_graph(+ template, llm_client, embedder, **kwargs+ )+ case "spatio_temporal_graph":+ template = cls.create_spatio_temporal_graph(+ template, llm_client, embedder, **kwargs+ )+ return templatediff --git a/hyperextract/utils/template_engine/gallery.py b/hyperextract/utils/template_engine/gallery.pyindex 8513517..5207b97 100644--- a/hyperextract/utils/template_engine/gallery.py+++ b/hyperextract/utils/template_engine/gallery.py@@ -17,10 +17,16 @@ class Gallery:from hyperextract.utils.template_engine import Gallery# Get template (auto-loaded)- config = Gallery.get("KnowledgeGraph")+ config = Gallery.get("general/knowledge_graph")# List all templates- print(Gallery.list_all())+ print(Gallery.list())++ # List domains+ print(Gallery.list_domains())++ # Search templates+ results = Gallery.search(type="graph")# Add custom template directory (auto-loaded)Gallery.add_path("/path/to/my/templates")@@ -37,15 +43,33 @@ class Gallery:self._configs_by_tag: Dict[str, List[str]] = {}@classmethod- def get(cls, name: str) -> Optional[TemplateCfg]:- return cls._instance._configs.get(name) if cls._instance else None+ def get(cls, path: str) -> Optional[TemplateCfg]:+ """Get template configuration by path.++ Args:+ path: Template path (e.g., "general/knowledge_graph")++ Returns:+ TemplateCfg or None if not found+ """+ return cls._instance._configs.get(path) if cls._instance else None@classmethod- def list_all(cls) -> List[str]:+ 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 []@classmethoddef add_path(cls, path: str) -> None:+ """Add a directory of template files.++ Args:+ path: Directory path containing YAML template files+ """if not cls._instance:returndir_path = Path(path)@@ -58,6 +82,11 @@ class Gallery:@classmethoddef add(cls, file_path: str) -> None:+ """Add a single template file.++ Args:+ file_path: Path to YAML template file+ """if not cls._instance:returnpath = Path(file_path)@@ -65,52 +94,46 @@ class Gallery:cls._instance._load_config(path)@classmethod- def get_by_type(cls, type_value: str) -> List[TemplateCfg]:- if not cls._instance:- return []- names = cls._instance._configs_by_type.get(type_value, [])- return [cls._instance._configs[name] for name in names if name in cls._instance._configs]-- @classmethod- def get_by_tag(cls, tag: str) -> List[TemplateCfg]:- if not cls._instance:- return []- names = cls._instance._configs_by_tag.get(tag, [])- return [cls._instance._configs[name] for name in names if name in cls._instance._configs]-- @classmethod- def search(cls, query: str = None, type_value: str = None, tag: str = None, language: str = None) -> List[TemplateCfg]:+ def search(+ cls,+ query: str = None,+ type: str = None,+ tag: str = None,+ language: str = None,+ ) -> List[TemplateCfg]:"""Search templates by query, type, tag, or language.-+Args:query: Search in template name/description- type_value: Filter by type (e.g., "graph", "list")+ type: Filter by autotype (e.g., "graph", "list", "model")tag: Filter by taglanguage: Filter by language (e.g., "zh", "en")-+Returns:List of matching TemplateCfg"""if not cls._instance:return []-+results = []-+for config in cls._instance._configs.values():if query:query_lower = query.lower()name_match = config.name.lower()- desc_match = getattr(config, 'description', None)- desc_value = desc_match.zh if hasattr(desc_match, 'zh') else desc_match- if query_lower not in name_match and (desc_value and query_lower not in str(desc_value).lower()):+ desc_match = getattr(config, "description", None)+ desc_value = desc_match.zh if hasattr(desc_match, "zh") else desc_match+ if query_lower not in name_match and (+ desc_value and query_lower not in str(desc_value).lower()+ ):continue-- if type_value and config.type != type_value:++ if type and config.type != type:continue-+if tag and (not config.tags or tag not in config.tags):continue-+if language:config_lang = config.languageif isinstance(config_lang, list):@@ -118,68 +141,25 @@ class Gallery:continueelif config_lang != language:continue-- results.append(config)-- return results-- @classmethod- def list_languages(cls) -> List[str]:- """List all available languages."""- if not cls._instance:- return []- languages = set()- for config in cls._instance._configs.values():- lang = config.language- if isinstance(lang, list):- languages.update(lang)- elif lang:- languages.add(lang)- return sorted(languages)- @classmethod- def list_types(cls) -> List[str]:- """List all available types."""- if not cls._instance:- return []- return list(cls._instance._configs_by_type.keys())+ results.append(config)- @classmethod- def list_tags(cls) -> List[str]:- """List all available tags."""- if not cls._instance:- return []- return list(cls._instance._configs_by_tag.keys())+ return results@classmethod- def list_autotypes(cls) -> List[str]:- """List all available autotypes."""- return [- "model", "list", "set", "graph", "hypergraph",- "temporal_graph", "spatial_graph", "spatio_temporal_graph"- ]+ def list_domains(cls) -> List[str]:+ """List all available domains (folder names in presets).- @classmethod- def list_domains(cls) -> List[tuple]:- """List all available domains with template count.-Returns:- List of (domain_name, template_count) tuples+ 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('_'):- count = len(list(item.glob("*.yaml")))- domains.append((item.name, count))- return domains-- @classmethod- def create(cls, name: str, lang: str = "zh", llm_client=None, embedder=None, **kwargs):- """Create template instance (delegate to TemplateFactory)."""- from .factory import TemplateFactory- return TemplateFactory.create_from_name(name, lang, llm_client, embedder, **kwargs)+ if item.is_dir() and not item.name.startswith("_"):+ domains.append(item.name)+ return sorted(domains)def _load_config(self, file_path: Path) -> None:try:diff --git a/hyperextract/utils/template_engine/template.py b/hyperextract/utils/template_engine/template.pyindex df7888f..872e345 100644--- a/hyperextract/utils/template_engine/template.py+++ b/hyperextract/utils/template_engine/template.py@@ -3,7 +3,8 @@Provides a clean API for searching and creating knowledge extraction templates."""-from typing import List, Optional+from typing import List, Optional, Union+from pathlib import Pathfrom langchain_core.language_models import BaseChatModelfrom langchain_core.embeddings import Embeddings@@ -18,147 +19,129 @@ class Template:Usage Examples:from hyperextract.utils.template_engine import Template- # List all templates- print(Template.list())+ # Create template instance (3 ways)+ template = Template.create("general/knowledge_graph", llm, emb)+ template = Template.create("/path/to/template.yaml", llm, emb)+ template = Template.create(config, llm, emb)- # Search templates- results = Template.search(query="财报", type_value="model")+ # Get template config by path+ config = Template.get("general/knowledge_graph")- # Get template config- config = Template.get("EarningsCallSummary")+ # Search templates+ results = Template.search(type="graph")+ results = Template.search(tag="finance")+ results = Template.search(query="知识图谱")- # Create template instance- template = Template.create("KnowledgeGraph", llm_client=llm, embedder=emb)- result = template.parse("your text here")+ # List all templates+ names = Template.list()- # List available domains- print(Template.domains())+ # List domains+ domains = Template.list_domains()"""- @staticmethod- def list() -> List[str]:- """List all available template names.-- Returns:- List of template names- """- return Gallery.list_all()-- @staticmethod- def search(- query: Optional[str] = None,- type_value: Optional[str] = None,- tag: Optional[str] = None,- language: Optional[str] = None,- ) -> List[TemplateCfg]:- """Search templates by various criteria.-- Args:- query: Search in template name/description- type_value: Filter by type (e.g., "graph", "list", "model")- tag: Filter by tag (e.g., "finance", "medicine")- language: Filter by language (e.g., "zh", "en")-- Returns:- List of matching TemplateCfg objects- """- return Gallery.search(- query=query,- type_value=type_value,- tag=tag,- language=language,- )-- @staticmethod- def get(name: str, lang: str = "zh") -> Optional[TemplateCfg]:- """Get template configuration by name.-- Args:- name: Template name (e.g., "KnowledgeGraph")- lang: Language, default "zh"-- Returns:- TemplateCfg or None if not found- """- return Gallery.get(name)-@staticmethoddef create(- name: str,- lang: str = "zh",+ source: Union[str, Path, TemplateCfg],llm_client: Optional[BaseChatModel] = None,embedder: Optional[Embeddings] = None,+ language: str = "zh",**kwargs,):"""Create template instance.Args:- name: Template name (e.g., "KnowledgeGraph")- lang: Language, default "zh"+ source: Template source - can be:+ - str: Template path (e.g., "general/knowledge_graph") or file path+ - Path: YAML file path+ - TemplateCfg: Template configuration instancellm_client: LLM client (reads from global config if not provided)embedder: Embedder client (reads from global config if not provided)- **kwargs: Additional parameters (e.g., observation_time, observation_location)+ language: Language code (e.g., "zh", "en")+ **kwargs: Additional parametersReturns:- TemplateWrapper instance+ AutoType instanceExamples:- # Basic usage (uses global config)- template = Template.create("KnowledgeGraph")+ # By path+ template = Template.create("general/knowledge_graph", llm, emb)- # With custom clients- template = Template.create(- "KnowledgeGraph",- llm_client=my_llm,- embedder=my_embedder- )+ # By file path+ template = Template.create("/path/to/template.yaml", llm, emb)++ # By config instance+ template = Template.create(config, llm, emb)# For temporal/spatial templatestemplate = Template.create(- "FinancialTemporalGraph",+ "finance/financial_data_temporal_graph",+ llm,+ emb,observation_time="2024-06-15")"""- return Gallery.create(- name=name,- lang=lang,- llm_client=llm_client,- embedder=embedder,- **kwargs,- )+ from .factory import TemplateFactory++ if llm_client is None or embedder is None:+ from hyperextract.utils import get_client++ default_llm, default_emb = get_client()+ llm_client = llm_client or default_llm+ embedder = embedder or default_emb++ return TemplateFactory.create(source, llm_client, embedder, language=language, **kwargs)@staticmethod- def domains() -> List[tuple]:- """List all available domains with template count.+ def get(path: str) -> Optional[TemplateCfg]:+ """Get template configuration by path.++ Args:+ path: Template path (e.g., "general/knowledge_graph")Returns:- List of (domain_name, template_count) tuples+ TemplateCfg or None if not found"""- return Gallery.list_domains()+ return Gallery.get(path)@staticmethod- def types() -> List[str]:- """List all available template types.+ 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.++ 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")Returns:- List of type names (e.g., ["model", "list", "graph", ...])+ List of matching TemplateCfg objects"""- return Gallery.list_types()+ return Gallery.search(+ query=query,+ type=type,+ tag=tag,+ language=language,+ )@staticmethod- def tags() -> List[str]:- """List all available tags.+ def list() -> List[str]:+ """List all available template names.Returns:- List of tag names+ List of template names"""- return Gallery.list_tags()+ return Gallery.list()@staticmethod- def languages() -> List[str]:- """List all available languages.+ def list_domains() -> List[str]:+ """List all available domains (folder names in presets).Returns:- List of language codes (e.g., ["zh", "en"])+ List of domain names"""- return Gallery.list_languages()+ return Gallery.list_domains()