Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
"""Template Factory - Dynamically creates template instances from configuration.
Supports AutoType generation for model, list, set, document, graph,
hypergraph, temporal_graph, spatial_graph, and spatio_temporal_graph.
Unknown `type` values raise ValueError listing the allowed types.
"""
from pathlib import Path
from typing import TYPE_CHECKING, get_args
from langchain_core.embeddings import Embeddings
from langchain_core.language_models import BaseChatModel
from .parsers import (
TemplateCfg,
localize_template,
parse_display,
parse_guideline,
parse_identifiers,
parse_option,
parse_output,
)
from .parsers.identifiers import validate_identifiers_fields
from .parsers.schemas.base import VALID_AUTOTYPES
if TYPE_CHECKING:
from hyperextract.types import (
AutoDocument,
AutoGraph,
AutoHypergraph,
AutoList,
AutoModel,
AutoSet,
AutoSpatialGraph,
AutoSpatioTemporalGraph,
AutoTemporalGraph,
)
def _unknown_autotype_error(type_name: str) -> ValueError:
allowed = ", ".join(get_args(VALID_AUTOTYPES))
return ValueError(f"Unknown template type {type_name!r}. Allowed types: {allowed}")
def _declared_output_fields(config) -> dict[str, set[str]]:
"""Declared field names per output section (entities/relations)."""
declared: dict[str, set[str]] = {}
output = config.output
for section in ("entities", "relations"):
fields = getattr(output, section, None)
if fields is not None and getattr(fields, "fields", None) is not None:
declared[section] = {f.name for f in fields.fields}
return declared
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,
config: TemplateCfg,
llm_client: BaseChatModel,
embedder: Embeddings,
**kwargs,
) -> "AutoModel":
"""Create AutoModel template."""
from hyperextract.types import AutoModel
data_schema = parse_output(config.output, config.type)
prompt = parse_guideline(config.guideline, config.type, config.language)
options = parse_option(config.options, config.type, override=kwargs)
label_extractor = parse_display(config.display, config.type)
return AutoModel(
data_schema=data_schema,
llm_client=llm_client,
embedder=embedder,
prompt=prompt,
label_extractor=label_extractor,
**options,
)
@classmethod
def create_list(
cls,
config: TemplateCfg,
llm_client: BaseChatModel,
embedder: Embeddings,
**kwargs,
) -> "AutoList":
"""Create AutoList template."""
from hyperextract.types import AutoList
data_schema = parse_output(config.output, config.type)
prompt = parse_guideline(config.guideline, config.type, config.language)
options = parse_option(config.options, config.type, override=kwargs)
item_label_extractor = parse_display(config.display, config.type)
return AutoList(
item_schema=data_schema,
llm_client=llm_client,
embedder=embedder,
prompt=prompt,
item_label_extractor=item_label_extractor,
**options,
)
@classmethod
def create_set(
cls,
config: TemplateCfg,
llm_client: BaseChatModel,
embedder: Embeddings,
**kwargs,
) -> "AutoSet":
"""Create AutoSet template."""
from hyperextract.types import AutoSet
data_schema = parse_output(config.output, config.type)
item_id_extractor = parse_identifiers(config.identifiers, config.type)
prompt = parse_guideline(config.guideline, config.type, config.language)
options = parse_option(config.options, config.type, override=kwargs)
item_label_extractor = parse_display(config.display, config.type)
return AutoSet(
item_schema=data_schema,
llm_client=llm_client,
embedder=embedder,
key_extractor=item_id_extractor,
item_label_extractor=item_label_extractor,
prompt=prompt,
**options,
)
@classmethod
def create_graph(
cls,
config: TemplateCfg,
llm_client: BaseChatModel,
embedder: Embeddings,
**kwargs,
) -> "AutoGraph":
"""Create AutoGraph template."""
from hyperextract.types import AutoGraph
entity_schema, relation_schema = parse_output(config.output, config.type)
validate_identifiers_fields(
config.identifiers,
config.type,
_declared_output_fields(config),
)
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, config.language)
)
node_label_extractor, edge_label_extractor = parse_display(
config.display, config.type
)
options = parse_option(config.options, config.type, override=kwargs)
return AutoGraph(
node_schema=entity_schema,
edge_schema=relation_schema,
node_key_extractor=entity_key_extractor,
edge_key_extractor=relation_key_extractor,
nodes_in_edge_extractor=entities_in_relation_extractor,
llm_client=llm_client,
embedder=embedder,
prompt=prompt,
prompt_for_node_extraction=prompt_for_entity_extraction,
prompt_for_edge_extraction=prompt_for_relation_extraction,
node_label_extractor=node_label_extractor,
edge_label_extractor=edge_label_extractor,
**options,
)
@classmethod
def create_hypergraph(
cls,
config: TemplateCfg,
llm_client: BaseChatModel,
embedder: Embeddings,
**kwargs,
) -> "AutoHypergraph":
"""Create AutoHypergraph template."""
from hyperextract.types import AutoHypergraph
entity_schema, relation_schema = parse_output(config.output, config.type)
validate_identifiers_fields(
config.identifiers,
config.type,
_declared_output_fields(config),
)
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, config.language)
)
node_label_extractor, edge_label_extractor = parse_display(
config.display, config.type
)
options = parse_option(config.options, config.type, override=kwargs)
return AutoHypergraph(
node_schema=entity_schema,
edge_schema=relation_schema,
node_key_extractor=entity_key_extractor,
edge_key_extractor=relation_key_extractor,
nodes_in_edge_extractor=entities_in_relation_extractor,
llm_client=llm_client,
embedder=embedder,
prompt=prompt,
prompt_for_node_extraction=prompt_for_entity_extraction,
prompt_for_edge_extraction=prompt_for_relation_extraction,
node_label_extractor=node_label_extractor,
edge_label_extractor=edge_label_extractor,
**options,
)
@classmethod
def create_temporal_graph(
cls,
config: TemplateCfg,
llm_client: BaseChatModel,
embedder: Embeddings,
**kwargs,
) -> "AutoTemporalGraph":
from hyperextract.types import AutoTemporalGraph
entity_schema, relation_schema = parse_output(config.output, config.type)
validate_identifiers_fields(
config.identifiers,
config.type,
_declared_output_fields(config),
)
(
entity_key_extractor,
relation_key_extractor,
entities_in_relation_extractor,
time_in_edge_extractor,
) = parse_identifiers(config.identifiers, config.type)
prompt, prompt_for_entity_extraction, prompt_for_relation_extraction = (
parse_guideline(config.guideline, config.type, config.language)
)
node_label_extractor, edge_label_extractor = parse_display(
config.display, config.type
)
options = parse_option(config.options, config.type, override=kwargs)
return AutoTemporalGraph(
node_schema=entity_schema,
edge_schema=relation_schema,
llm_client=llm_client,
embedder=embedder,
node_key_extractor=entity_key_extractor,
edge_key_extractor=relation_key_extractor,
nodes_in_edge_extractor=entities_in_relation_extractor,
time_in_edge_extractor=time_in_edge_extractor,
prompt=prompt,
prompt_for_node_extraction=prompt_for_entity_extraction,
prompt_for_edge_extraction=prompt_for_relation_extraction,
node_label_extractor=node_label_extractor,
edge_label_extractor=edge_label_extractor,
**options,
)
@classmethod
def create_spatial_graph(
cls,
config: TemplateCfg,
llm_client: BaseChatModel,
embedder: Embeddings,
**kwargs,
) -> "AutoSpatialGraph":
"""Create AutoSpatialGraph template."""
from hyperextract.types import AutoSpatialGraph
entity_schema, relation_schema = parse_output(config.output, config.type)
validate_identifiers_fields(
config.identifiers,
config.type,
_declared_output_fields(config),
)
identifiers = parse_identifiers(config.identifiers, config.type)
(
entity_key_extractor,
relation_key_extractor,
entities_in_relation_extractor,
location_in_edge_extractor,
) = identifiers
prompt, prompt_for_entity_extraction, prompt_for_relation_extraction = (
parse_guideline(config.guideline, config.type, config.language)
)
node_label_extractor, edge_label_extractor = parse_display(
config.display, config.type
)
options = parse_option(config.options, config.type, override=kwargs)
return AutoSpatialGraph(
node_schema=entity_schema,
edge_schema=relation_schema,
node_key_extractor=entity_key_extractor,
edge_key_extractor=relation_key_extractor,
location_in_edge_extractor=location_in_edge_extractor,
nodes_in_edge_extractor=entities_in_relation_extractor,
llm_client=llm_client,
embedder=embedder,
prompt=prompt,
prompt_for_node_extraction=prompt_for_entity_extraction,
prompt_for_edge_extraction=prompt_for_relation_extraction,
node_label_extractor=node_label_extractor,
edge_label_extractor=edge_label_extractor,
**options,
)
@classmethod
def create_spatio_temporal_graph(
cls,
config: TemplateCfg,
llm_client: BaseChatModel,
embedder: Embeddings,
**kwargs,
) -> "AutoSpatioTemporalGraph":
"""Create AutoSpatioTemporalGraph template."""
from hyperextract.types import AutoSpatioTemporalGraph
entity_schema, relation_schema = parse_output(config.output, config.type)
validate_identifiers_fields(
config.identifiers,
config.type,
_declared_output_fields(config),
)
identifiers = parse_identifiers(config.identifiers, config.type)
(
entity_key_extractor,
relation_key_extractor,
entities_in_relation_extractor,
time_in_edge_extractor,
location_in_edge_extractor,
) = identifiers
prompt, prompt_for_entity_extraction, prompt_for_relation_extraction = (
parse_guideline(config.guideline, config.type, config.language)
)
node_label_extractor, edge_label_extractor = parse_display(
config.display, config.type
)
options = parse_option(config.options, config.type, override=kwargs)
return AutoSpatioTemporalGraph(
node_schema=entity_schema,
edge_schema=relation_schema,
node_key_extractor=entity_key_extractor,
edge_key_extractor=relation_key_extractor,
nodes_in_edge_extractor=entities_in_relation_extractor,
time_in_edge_extractor=time_in_edge_extractor,
location_in_edge_extractor=location_in_edge_extractor,
llm_client=llm_client,
embedder=embedder,
prompt=prompt,
prompt_for_node_extraction=prompt_for_entity_extraction,
prompt_for_edge_extraction=prompt_for_relation_extraction,
node_label_extractor=node_label_extractor,
edge_label_extractor=edge_label_extractor,
**options,
)
@classmethod
def create_document(
cls,
config: TemplateCfg,
llm_client: BaseChatModel,
embedder: Embeddings,
**kwargs,
) -> "AutoDocument":
"""Create AutoDocument template (chunk corpus, no LLM extraction)."""
from hyperextract.types import AutoDocument
options = parse_option(config.options, config.type, override=kwargs)
return AutoDocument(
llm_client=llm_client,
embedder=embedder,
**options,
)
@classmethod
def create(
cls,
source: str | TemplateCfg,
language: str | None = 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/graph", "/path/to/template.yaml"
- Method templates: "method/light_rag", "method/hyper_rag"
Args:
source: Template source - can be:
- str: Template name (e.g., "graph", "method/light_rag") or file path
- TemplateCfg: Template configuration instance
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
e.g., observation_time="2024-06-15", observation_location="Beijing"
Returns:
AutoType instance
Examples:
# Knowledge template by name (language required)
template = TemplateFactory.create("general/graph", "zh", llm, embedder)
# 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 (language required)
template = TemplateFactory.create(config, "zh", llm, embedder)
# For spatio-temporal templates, pass observation_time etc.
template = TemplateFactory.create(
"FinancialTemporalGraph",
"zh",
llm,
embedder,
observation_time="2024-06-15",
observation_location="Beijing"
)
# For method templates with specific parameters
template = TemplateFactory.create(
"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
match source:
case str() as s if s.endswith(".yaml") or Path(s).exists():
template_cfg = load_template(s)
case str() as s:
template_cfg = Gallery.get(s)
case TemplateCfg() as cfg:
template_cfg = cfg
case _:
raise ValueError("Invalid source: must be a template path or file path")
if template_cfg is None:
raise ValueError(f"Template not found: {source}")
if template_cfg.type not in get_args(VALID_AUTOTYPES):
raise _unknown_autotype_error(template_cfg.type)
template_cfg = localize_template(template_cfg, language)
match template_cfg.type:
case "model":
template = cls.create_model(
template_cfg, llm_client, embedder, **kwargs
)
case "list":
template = cls.create_list(template_cfg, llm_client, embedder, **kwargs)
case "set":
template = cls.create_set(template_cfg, llm_client, embedder, **kwargs)
case "document":
template = cls.create_document(
template_cfg, llm_client, embedder, **kwargs
)
case "graph":
template = cls.create_graph(
template_cfg, llm_client, embedder, **kwargs
)
case "hypergraph":
template = cls.create_hypergraph(
template_cfg, llm_client, embedder, **kwargs
)
case "temporal_graph":
template = cls.create_temporal_graph(
template_cfg, llm_client, embedder, **kwargs
)
case "spatial_graph":
template = cls.create_spatial_graph(
template_cfg, llm_client, embedder, **kwargs
)
case "spatio_temporal_graph":
template = cls.create_spatio_temporal_graph(
template_cfg, llm_client, embedder, **kwargs
)
case _:
raise _unknown_autotype_error(template_cfg.type)
if isinstance(source, str):
template.metadata["template"] = (
Path(source).stem if source.endswith(".yaml") else source
)
else:
template.metadata["template"] = source.name
template.metadata["lang"] = language
template.metadata["type"] = template_cfg.type
return template