Skip to content

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

feat(方法注册): 实现方法注册中心并集成到模板系统

yifanfeng9790cafaefff37
diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.py
index b8124ac..5ff5fcd 100644
--- a/hyperextract/cli/cli.py
+++ b/hyperextract/cli/cli.py
@@ -1,7 +1,6 @@
"""CLI entry point for Hyper-Extract."""
from pathlib import Path
-from datetime import datetime
from typing import Optional
import typer
@@ -155,19 +154,32 @@ def parse(
input: str = typer.Argument(..., help="Input file path, directory, or '-' for stdin"),
output: str = typer.Option(..., "--output", "-o", help="Output directory"),
template: Optional[str] = typer.Option(None, "--template", "-t", help="Template (omit for interactive selection)"),
- lang: str = typer.Option("zh", "--lang", "-l", help="Language (zh/en)"),
+ method: Optional[str] = typer.Option(None, "--method", "-m", help="Method template (e.g., light_rag, hyper_rag)"),
+ lang: Optional[str] = typer.Option(None, "--lang", "-l", help="Language (zh/en). Required for knowledge templates, optional for methods (default: en)"),
force: bool = typer.Option(False, "--force", "-f", help="Force overwrite"),
no_index: bool = typer.Option(False, "--no-index", help="Skip building search index"),
):
"""Extract knowledge from text to a new directory."""
validate_config()
- if template is None:
+ if method:
+ template = f"method/{method}"
+ elif template is None:
template = select_template_interactive()
if template is None:
console.print("[red]No template selected. Exiting.[/red]")
raise typer.Exit(1)
+ is_method_template = template.startswith("method/")
+
+ if is_method_template:
+ if lang is not None:
+ console.print("[dim]Note: Method templates use English prompts. --lang parameter is ignored.[/dim]")
+ lang = "en"
+ elif lang is None:
+ console.print("[red]Error:[/red] --lang is required for knowledge templates. Use --lang en or --lang zh.")
+ raise typer.Exit(1)
+
output_path = Path(output)
if output_path.exists() and not force:
diff --git a/hyperextract/cli/commands/list.py b/hyperextract/cli/commands/list.py
index 67dc6bd..fec888b 100644
--- a/hyperextract/cli/commands/list.py
+++ b/hyperextract/cli/commands/list.py
@@ -14,23 +14,13 @@ app = typer.Typer(
help="List available resources",
)
-METHODS = [
- ("kg_gen", "Knowledge Graph Generation"),
- ("atom", "Atomic Information Extraction"),
- ("itext2kg", "iText2KG - Iterative Knowledge Graph Construction"),
- ("itext2kg_star", "iText2KG-Star - Star-shaped Knowledge Graph"),
- ("light_rag", "LightRAG - Lightweight Graph RAG"),
- ("hyper_rag", "HyperRAG - Hypergraph RAG"),
- ("cog_rag", "CogRAG - Cognitive RAG"),
- ("hypergraph_rag", "Hypergraph RAG"),
-]
-
@app.command(name="template")
def template(
query: Optional[str] = typer.Option(None, "--query", "-q", help="Query to search templates"),
autotype: Optional[str] = typer.Option(None, "--autotype", "-a", help="Filter by autotype"),
language: Optional[str] = typer.Option(None, "--lang", "-l", help="Filter by language"),
+ include_methods: bool = typer.Option(True, "--include-methods/--no-methods", help="Include method templates"),
):
"""List all available templates."""
results = Gallery.list(
@@ -49,12 +39,18 @@ def template(
for lang in languages:
templates.append((path, full_name, lang))
+ if include_methods:
+ from hyperextract.methods import list_method_cfgs
+ method_templates = list_method_cfgs()
+ for name, cfg in method_templates.items():
+ templates.append((name, cfg.name, "en"))
+
if not templates:
console.print("[yellow]No templates found.[/yellow]")
return
table = Table(title="Available Templates", show_header=True, header_style="bold magenta")
- table.add_column("Template ID", style="cyan", width=30)
+ table.add_column("Template ID", style="cyan", width=35)
table.add_column("Name", style="green", width=30)
table.add_column("Language", style="yellow", width=10)
@@ -63,7 +59,7 @@ def template(
console.print(table)
console.print(f"\n[dim]Total: {len(templates)} templates[/dim]")
- console.print("\n[dim]Tip: Use -t/--template to specify a template.[/dim]")
+ console.print("\n[dim]Tip: Use -t/--template to specify a template, or -m/--method for methods.[/dim]")
@app.command(name="method")
@@ -71,14 +67,16 @@ def method(
query: Optional[str] = typer.Option(None, "--query", "-q", help="Query to search methods"),
):
"""List all available extraction methods."""
- items = METHODS
+ from hyperextract.methods import list_methods
+
+ items = list_methods()
if query:
query_lower = query.lower()
- items = [
- item for item in items
- if query_lower in item[0].lower() or query_lower in item[1].lower()
- ]
+ items = {
+ k: v for k, v in items.items()
+ if query_lower in k.lower() or query_lower in v.get("description", "").lower()
+ }
if not items:
console.print("[yellow]No methods found.[/yellow]")
@@ -86,10 +84,12 @@ def method(
table = Table(title="Available Methods", show_header=True, header_style="bold magenta")
table.add_column("Method", style="cyan", width=20)
+ table.add_column("Type", style="yellow", width=15)
table.add_column("Description", style="green")
- for name, desc in items:
- table.add_row(name, desc)
+ for name, info in items.items():
+ table.add_row(f"method/{name}", info["type"], info["description"])
console.print(table)
console.print(f"\n[dim]Total: {len(items)} methods[/dim]")
+ console.print("\n[dim]Tip: Use -m/--method to specify a method template.[/dim]")
diff --git a/hyperextract/methods/__init__.py b/hyperextract/methods/__init__.py
index 50689b3..2b25c7f 100644
--- a/hyperextract/methods/__init__.py
+++ b/hyperextract/methods/__init__.py
@@ -8,6 +8,23 @@ the AutoTypes primitives. It's divided into:
from . import rag
from . import typical
+from .registry import (
+ register_method,
+ get_method,
+ list_methods,
+ get_method_cfg,
+ list_method_cfgs,
+ MethodCfg,
+)
-__all__ = ["rag", "typical"]
+__all__ = [
+ "rag",
+ "typical",
+ "register_method",
+ "get_method",
+ "list_methods",
+ "get_method_cfg",
+ "list_method_cfgs",
+ "MethodCfg",
+]
diff --git a/hyperextract/methods/rag/hyper_rag.py b/hyperextract/methods/rag/hyper_rag.py
index 92e9839..ce5b157 100644
--- a/hyperextract/methods/rag/hyper_rag.py
+++ b/hyperextract/methods/rag/hyper_rag.py
@@ -197,6 +197,9 @@ class Hyper_RAG(AutoHypergraph[NodeSchema, EdgeSchema]):
# Optimize indexing
node_fields_for_index=["name", "type", "description"],
edge_fields_for_index=["keywords", "description"],
+ # Display labels
+ node_label_extractor=lambda x: x.name,
+ edge_label_extractor=lambda x: f"{x.description[:5]}...",
# Other parameters
chunk_size=chunk_size,
chunk_overlap=chunk_overlap,
diff --git a/hyperextract/methods/rag/hypergraph_rag.py b/hyperextract/methods/rag/hypergraph_rag.py
index ebe14da..3056d67 100644
--- a/hyperextract/methods/rag/hypergraph_rag.py
+++ b/hyperextract/methods/rag/hypergraph_rag.py
@@ -223,6 +223,9 @@ class HyperGraph_RAG(AutoHypergraph[NodeSchema, EdgeSchema]):
# Optimize indexing
node_fields_for_index=["name", "type", "description"],
edge_fields_for_index=["knowledge_segment"],
+ # Display labels
+ node_label_extractor=lambda x: x.name,
+ edge_label_extractor=lambda x: f"{x.knowledge_segment[:5]}...",
# Other parameters
chunk_size=chunk_size,
chunk_overlap=chunk_overlap,
diff --git a/hyperextract/methods/rag/light_rag.py b/hyperextract/methods/rag/light_rag.py
index b33f2a4..69c850a 100644
--- a/hyperextract/methods/rag/light_rag.py
+++ b/hyperextract/methods/rag/light_rag.py
@@ -197,10 +197,12 @@ class Light_RAG(AutoGraph[NodeSchema, EdgeSchema]):
# Optimize indexing
node_fields_for_index=["name", "type", "description"],
edge_fields_for_index=["keywords", "description"],
+ # Display labels
+ node_label_extractor=lambda x: x.name,
+ edge_label_extractor=lambda x: f"{x.description[:5]}...",
# Other parameters
chunk_size=chunk_size,
chunk_overlap=chunk_overlap,
max_workers=max_workers,
verbose=verbose,
)
-
diff --git a/hyperextract/methods/registry.py b/hyperextract/methods/registry.py
new file mode 100644
index 0000000..d1b2784
--- /dev/null
+++ b/hyperextract/methods/registry.py
@@ -0,0 +1,161 @@
+"""Method Registry - Central registry for all extraction methods.
+
+This module provides a unified registry for method templates, enabling
+consistent creation and management of method-based knowledge extraction.
+"""
+
+from typing import Dict, Any, Type, Optional
+from pydantic import BaseModel
+
+
+_METHOD_REGISTRY: Dict[str, Dict[str, Any]] = {}
+
+
+def register_method(
+ name: str,
+ method_class: Type,
+ autotype: str,
+ description: str = "",
+) -> None:
+ """Register a method in the registry.
+
+ Args:
+ name: Method name (e.g., "light_rag")
+ method_class: The method class
+ autotype: AutoType category (e.g., "graph", "hypergraph")
+ description: Method description
+ """
+ _METHOD_REGISTRY[name] = {
+ "class": method_class,
+ "type": autotype,
+ "description": description,
+ }
+
+
+def get_method(name: str) -> Optional[Dict[str, Any]]:
+ """Get method info by name.
+
+ Args:
+ name: Method name
+
+ Returns:
+ Method info dict or None if not found
+ """
+ return _METHOD_REGISTRY.get(name)
+
+
+def list_methods() -> Dict[str, Dict[str, Any]]:
+ """List all registered methods.
+
+ Returns:
+ Dict mapping method names to their info
+ """
+ return _METHOD_REGISTRY.copy()
+
+
+class MethodCfg(BaseModel):
+ """Configuration model for method templates."""
+
+ name: str
+ type: str
+ description: str = ""
+
+
+def get_method_cfg(name: str) -> Optional[MethodCfg]:
+ """Get method configuration as MethodCfg.
+
+ Args:
+ name: Method name
+
+ Returns:
+ MethodCfg or None if not found
+ """
+ info = get_method(name)
+ if info is None:
+ return None
+ return MethodCfg(
+ name=name,
+ type=info["type"],
+ description=info["description"],
+ )
+
+
+def list_method_cfgs() -> Dict[str, MethodCfg]:
+ """List all method configurations.
+
+ Returns:
+ Dict mapping "method/{name}" to MethodCfg
+ """
+ return {
+ f"method/{name}": MethodCfg(
+ name=name,
+ type=info["type"],
+ description=info["description"],
+ )
+ for name, info in _METHOD_REGISTRY.items()
+ }
+
+
+def _init_registry():
+ """Initialize the registry with built-in methods."""
+ from hyperextract.methods.rag import Light_RAG, Hyper_RAG, HyperGraph_RAG, Cog_RAG
+ from hyperextract.methods.typical import iText2KG, iText2KG_Star, KG_Gen, Atom
+
+ register_method(
+ name="light_rag",
+ method_class=Light_RAG,
+ autotype="graph",
+ description="Lightweight Graph-based RAG with binary edges for entity-relationship extraction",
+ )
+
+ register_method(
+ name="hyper_rag",
+ method_class=Hyper_RAG,
+ autotype="hypergraph",
+ description="Hypergraph-based RAG with n-ary hyperedges for complex multi-entity relationships",
+ )
+
+ register_method(
+ name="hypergraph_rag",
+ method_class=HyperGraph_RAG,
+ autotype="hypergraph",
+ description="HyperGraph RAG implementation for advanced knowledge graph construction",
+ )
+
+ register_method(
+ name="cog_rag",
+ method_class=Cog_RAG,
+ autotype="graph",
+ description="Cognitive RAG implementation for intelligent knowledge retrieval",
+ )
+
+ register_method(
+ name="itext2kg",
+ method_class=iText2KG,
+ autotype="graph",
+ description="iText2KG: High-quality triple-based knowledge graph extraction",
+ )
+
+ register_method(
+ name="itext2kg_star",
+ method_class=iText2KG_Star,
+ autotype="graph",
+ description="iText2KG Star: Enhanced version with improved extraction quality",
+ )
+
+ register_method(
+ name="kg_gen",
+ method_class=KG_Gen,
+ autotype="graph",
+ description="KG_Gen: Knowledge Graph Generator for structured knowledge extraction",
+ )
+
+ register_method(
+ name="atom",
+ method_class=Atom,
+ autotype="graph",
+ description="Atom: Temporal knowledge graph extraction with evidence attribution",
+ )
+
+
+_init_registry()
diff --git a/hyperextract/methods/typical/atom.py b/hyperextract/methods/typical/atom.py
index 578fb1b..20bb609 100644
--- a/hyperextract/methods/typical/atom.py
+++ b/hyperextract/methods/typical/atom.py
@@ -388,6 +388,9 @@ class Atom(AutoGraph[NodeSchema, EdgeSchema]):
# Optimize indexing: only index name field
node_fields_for_index=["name", "label"],
edge_fields_for_index=["startNode", "name", "endNode"],
+ # Display labels
+ node_label_extractor=lambda x: x.name,
+ edge_label_extractor=lambda x: x.name,
# Other parameters
chunk_size=chunk_size,
chunk_overlap=chunk_overlap,
diff --git a/hyperextract/methods/typical/itext2kg.py b/hyperextract/methods/typical/itext2kg.py
index 0c43653..365c296 100644
--- a/hyperextract/methods/typical/itext2kg.py
+++ b/hyperextract/methods/typical/itext2kg.py
@@ -173,6 +173,9 @@ class iText2KG(AutoGraph[NodeSchema, EdgeSchema]):
# Optimize indexing: only index name field
node_fields_for_index=["name", "label"],
edge_fields_for_index=["startNode", "name", "endNode"],
+ # Display labels
+ node_label_extractor=lambda x: x.name,
+ edge_label_extractor=lambda x: x.name,
# Other parameters
chunk_size=chunk_size,
chunk_overlap=chunk_overlap,
diff --git a/hyperextract/methods/typical/itext2kg_star.py b/hyperextract/methods/typical/itext2kg_star.py
index 4d7937a..8113677 100644
--- a/hyperextract/methods/typical/itext2kg_star.py
+++ b/hyperextract/methods/typical/itext2kg_star.py
@@ -12,7 +12,6 @@ from datetime import datetime
from pydantic import BaseModel, Field
from semhash import SemHash
from langchain_core.language_models import BaseChatModel
-from langchain_core.prompts import ChatPromptTemplate
from langchain_core.embeddings import Embeddings
from ontomem.merger import MergeStrategy
@@ -185,6 +184,9 @@ class iText2KG_Star(AutoGraph[NodeSchema, EdgeSchema]):
# Optimize indexing: only index name field
node_fields_for_index=["name", "label"],
edge_fields_for_index=["startNode", "name", "endNode"],
+ # Display labels
+ node_label_extractor=lambda x: x.name,
+ edge_label_extractor=lambda x: x.name,
# Other parameters
chunk_size=chunk_size,
chunk_overlap=chunk_overlap,
diff --git a/hyperextract/methods/typical/kg_gen.py b/hyperextract/methods/typical/kg_gen.py
index f5f1d21..94fa748 100644
--- a/hyperextract/methods/typical/kg_gen.py
+++ b/hyperextract/methods/typical/kg_gen.py
@@ -153,6 +153,9 @@ class KG_Gen(AutoGraph[NodeSchema, EdgeSchema]):
# Optimize indexing: only index name field
node_fields_for_index=["name"],
edge_fields_for_index=["subject", "predicate", "object"],
+ # Display labels
+ node_label_extractor=lambda x: x.name,
+ edge_label_extractor=lambda x: x.predicate,
# Other parameters
chunk_size=chunk_size,
chunk_overlap=chunk_overlap,
diff --git a/hyperextract/utils/template_engine/factory.py b/hyperextract/utils/template_engine/factory.py
index d988894..0d12c3b 100644
--- a/hyperextract/utils/template_engine/factory.py
+++ b/hyperextract/utils/template_engine/factory.py
@@ -3,7 +3,7 @@
Supports all 8 AutoType dynamic generation.
"""
-from typing import TYPE_CHECKING, Union
+from typing import TYPE_CHECKING, Union, Optional
from pathlib import Path
from langchain_core.language_models import BaseChatModel
@@ -34,6 +34,58 @@ if TYPE_CHECKING:
class TemplateFactory:
+ @classmethod
+ def create_method(
+ cls,
+ method_name: str,
+ llm_client: BaseChatModel,
+ embedder: Embeddings,
+ **kwargs,
+ ):
+ """Create method template instance.
+
+ Note: Method templates use English prompts only.
+ Language is hardcoded to "en" in metadata.
+
+ Args:
+ method_name: Method name (e.g., "light_rag", "hyper_rag")
+ llm_client: LLM client
+ embedder: Embedding model
+ **kwargs: Additional parameters passed to the method constructor
+
+ Returns:
+ AutoType instance
+
+ Examples:
+ # Create Light_RAG method
+ template = TemplateFactory.create_method("light_rag", llm, embedder)
+
+ # Create Atom method with observation_time
+ template = TemplateFactory.create_method(
+ "atom", llm, embedder, observation_time="2024-06-15"
+ )
+ """
+ from hyperextract.methods.registry import get_method
+
+ method_info = get_method(method_name)
+ if method_info is None:
+ raise ValueError(f"Unknown method: {method_name}")
+
+ method_class = method_info["class"]
+ autotype = method_info["type"]
+
+ instance = method_class(
+ llm_client=llm_client,
+ embedder=embedder,
+ **kwargs,
+ )
+
+ instance.metadata["template"] = f"method/{method_name}"
+ instance.metadata["lang"] = "en"
+ instance.metadata["type"] = autotype
+
+ return instance
+
@classmethod
def create_model(
cls,
@@ -328,18 +380,24 @@ class TemplateFactory:
def create(
cls,
source: Union[str, TemplateCfg],
- language: str,
- llm_client: BaseChatModel,
- embedder: Embeddings,
+ language: Optional[str] = None,
+ llm_client: BaseChatModel = None,
+ embedder: Embeddings = None,
**kwargs,
):
"""Create template instance based on configuration.
+ Supports both knowledge templates and method templates:
+ - Knowledge templates: "general/knowledge_graph", "/path/to/template.yaml"
+ - Method templates: "method/light_rag", "method/hyper_rag"
+
Args:
source: Template source - can be:
- - str: Template name (e.g., "knowledge_graph") or file path
+ - str: Template name (e.g., "knowledge_graph", "method/light_rag") or file path
- TemplateCfg: Template configuration instance
- language: Language code for localization (e.g., 'zh', 'en') - required
+ language: Language code for localization (e.g., 'zh', 'en')
+ - Required for knowledge templates
+ - Ignored for method templates (always uses "en")
llm_client: LLM client
embedder: Embedding model
**kwargs: Additional parameters to override config parameters
@@ -349,18 +407,18 @@ class TemplateFactory:
AutoType instance
Examples:
- # By name (search via Gallery)
+ # Knowledge template by name (language required)
template = TemplateFactory.create("knowledge_graph", "zh", llm, embedder)
- # By file path
+ # Method template (language ignored, always "en")
+ template = TemplateFactory.create("method/light_rag", llm=llm, embedder=embedder)
+
+ # By file path (language required)
template = TemplateFactory.create("/path/to/template.yaml", "zh", llm, embedder)
- # By TemplateCfg instance
+ # By TemplateCfg instance (language required)
template = TemplateFactory.create(config, "zh", llm, embedder)
- # For specific language
- template = TemplateFactory.create("knowledge_graph", "en", llm, embedder)
-
# For spatio-temporal templates, pass observation_time etc.
template = TemplateFactory.create(
"FinancialTemporalGraph",
@@ -371,16 +429,24 @@ class TemplateFactory:
observation_location="Beijing"
)
- # Can also override other parameters
+ # For method templates with specific parameters
template = TemplateFactory.create(
- "knowledge_graph",
- llm,
- embedder,
- language="zh",
- chunk_size=4096,
- max_workers=20
+ "method/atom",
+ llm=llm,
+ embedder=embedder,
+ observation_time="2024-06-15"
)
"""
+ if isinstance(source, str) and source.startswith("method/"):
+ method_name = source[7:]
+ return cls.create_method(method_name, llm_client, embedder, **kwargs)
+
+ if language is None:
+ raise ValueError(
+ "language is required for knowledge templates. "
+ "Provide a language code (e.g., 'zh', 'en')."
+ )
+
from .gallery import Gallery
from .parsers import load_template
diff --git a/hyperextract/utils/template_engine/template.py b/hyperextract/utils/template_engine/template.py
index c832cf7..92dd0e4 100644
--- a/hyperextract/utils/template_engine/template.py
+++ b/hyperextract/utils/template_engine/template.py
@@ -8,6 +8,8 @@ from typing import Dict, Optional
from langchain_core.language_models import BaseChatModel
from langchain_core.embeddings import Embeddings
+from hyperextract.methods import get_method_cfg
+
from .gallery import Gallery
from .parsers import TemplateCfg
@@ -36,7 +38,7 @@ class Template:
@staticmethod
def create(
source: str,
- language: str,
+ language: Optional[str] = None,
llm_client: Optional[BaseChatModel] = None,
embedder: Optional[Embeddings] = None,
**kwargs,
@@ -44,8 +46,10 @@ class Template:
"""Create template instance.
Args:
- source: Template path (e.g., "general/knowledge_graph") or file path
- language: Language code (e.g., "zh", "en") - required
+ source: Template path (e.g., "general/knowledge_graph", "method/light_rag") or file path
+ language: Language code (e.g., "zh", "en")
+ - Required for knowledge templates
+ - Ignored for method templates (always uses "en")
llm_client: LLM client (reads from global config if not provided)
embedder: Embedder client (reads from global config if not provided)
**kwargs: Additional parameters
@@ -54,10 +58,13 @@ class Template:
AutoType instance
Examples:
- # By path
+ # Knowledge template (language required)
template = Template.create("general/knowledge_graph", "zh", llm, emb)
- # By file path
+ # Method template (language ignored, always "en")
+ template = Template.create("method/light_rag", llm_client=llm, embedder=embedder)
+
+ # By file path (language required)
template = Template.create("/path/to/template.yaml", "zh", llm, emb)
# For temporal/spatial templates
@@ -85,11 +92,14 @@ class Template:
"""Get template configuration by path.
Args:
- path: Template path (e.g., "general/knowledge_graph")
+ path: Template path (e.g., "general/knowledge_graph" or "method/light_rag")
Returns:
TemplateCfg or None if not found
"""
+ if path.startswith("method/"):
+ method_name = path[7:]
+ return get_method_cfg(method_name)
return Gallery.get(path)
@staticmethod
@@ -98,6 +108,7 @@ class Template:
filter_by_type: Optional[str] = None,
filter_by_tag: Optional[str] = None,
filter_by_language: Optional[str] = None,
+ include_methods: bool = True,
) -> Dict[str, TemplateCfg]:
"""List templates with optional filters.
@@ -106,15 +117,23 @@ class Template:
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")
+ include_methods: Whether to include method templates (default: True)
Returns:
Dict mapping template name to TemplateCfg
"""
- return Gallery.list(
+ templates = 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,
)
+ if include_methods:
+ from hyperextract.methods import list_method_cfgs
+ method_templates = list_method_cfgs()
+ templates.update(method_templates)
+
+ return templates
+