Skip to content

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

17.7 KB
Raw Blame

Hyper-Extract Knowledge Templates

A curated library of YAML-based templates for structured knowledge extraction from domain-specific documents.

Read this in 中文


Table of Contents


Quick Start

Installation & Setup

from hyperextract.utils.template_engine import Gallery, TemplateFactory
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

llm = ChatOpenAI(model="gpt-4o-mini")
embedder = OpenAIEmbeddings()

Load & Use a Template

config = Gallery.get("general/workflow_graph")

template = TemplateFactory.create(config, llm, embedder)

result = template.parse("Your document text here...")

Browse Available Templates

all_templates = Gallery.list()
print(f"Total templates: {len(all_templates)}")

graph_templates = Gallery.list(filter_by_type="graph")
print(f"Graph templates: {list(graph_templates.keys())}")

finance_templates = Gallery.list(filter_by_tag="finance")
print(f"Finance templates: {list(finance_templates.keys())}")

Core Concepts

What is a Knowledge Template?

A knowledge template is a YAML configuration that defines:

  • What to extract from your documents (entities, relations, fields)
  • How to structure the output (schema definition)
  • Extraction guidelines for the LLM (instructions and rules)

Template Structure

language: [zh, en]

name: template_name
type: graph | hypergraph | model | list | set | temporal_graph | spatial_graph | spatio_temporal_graph
tags: [domain, category]

description:
  zh: '中文描述'
  en: 'English description'

output:
  description:
    zh: '输出描述'
    en: 'Output description'
  entities:          # For graph types
    fields: [...]
  fields:           # For model types
    - name: field_name
      type: str | int | float | list
      description: {...}
  relations:
    fields: [...]

guideline:
  target: {...}
  rules_for_entities: [...]
  rules_for_relations: [...]

identifiers:
  entity_id: name
  relation_id: '{source}|{type}|{target}'

AutoType Reference

Hyper-Extract provides 8 extraction types, forming two families:

Record Types (Extracting Data)

Type Description Output Structure
model Single structured object Flat fields with values
list Ordered array Array of items
set Deduplicated collection Unique items only

Graph Types (Extracting Relationships)

Type Description Output Structure
graph Binary relations Nodes + Edges (source→target)
hypergraph Multi-entity relations Nodes + Hyperedges (multiple participants)
temporal_graph Relations + time Nodes + Edges with timestamps
spatial_graph Relations + location Nodes + Edges with coordinates
spatio_temporal_graph Relations + time + location Nodes + Edges with both
                    ┌─────────────┐
                    │   Record    │
                    │   Types     │
                    └──────┬──────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
         ▼                 ▼                 ▼
    ┌─────────┐     ┌───────────┐     ┌─────────┐
    │  model  │     │   list    │     │   set   │
    └─────────┘     └───────────┘     └─────────┘

                    ┌─────────────┐
                    │    Graph    │
                    │    Types    │
                    └──────┬──────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
         ▼                 ▼                 ▼
    ┌─────────┐     ┌───────────┐     ┌─────────────┐
    │  graph  │     │ hypergraph│     │ temporal_*  │
    └─────────┘     └───────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │ spatial_*   │
                    └─────────────┘

When to Use Which Type

Decision Tree

Does your document contain relationships between entities?
│
├─ No
│   └─ Is the data a single structured object?
│       ├─ Yes → model
│       └─ No
│           └─ Is order important?
│               ├─ Yes → list
│               └─ No → set
│
└─ Yes
    └─ Are relations binary (A→B)?
        ├─ Yes
        │   └─ Need time or location?
        │       ├─ Time only → temporal_graph
        │       ├─ Location only → spatial_graph
        │       ├─ Both → spatio_temporal_graph
        │       └─ Neither → graph
        └─ No (multi-party)
            └─ Need time or location?
                ├─ Time only → temporal_graph
                ├─ Location only → spatial_graph
                ├─ Both → spatio_temporal_graph
                └─ Neither → hypergraph

Quick Reference

Scenario Recommended Type
Extract a person profile model
List all meeting attendees set
Rank companies by revenue list
Extract who works at where graph
Analyze multi-party contract obligations hypergraph
Build a company history timeline temporal_graph
Map store locations and territories spatial_graph
Track delivery routes with timestamps spatio_temporal_graph

Document-to-Template Guide

Match your document type to the right template:

Document Type Recommended Templates Type
Earnings Call Transcript earnings_summary model
Financial News Article sentiment_model, event_timeline model, temporal_graph
IPO Prospectus ownership_graph, event_timeline graph, temporal_graph
Clinical Practice Guideline treatment_map hypergraph
Drug Interaction Reference drug_interaction graph
Patient Discharge Summary hospital_timeline, discharge_instruction temporal_graph, model
Medical Textbook anatomy_graph graph
Service Contract (MSA) contract_obligation hypergraph
Court Judgment case_fact_timeline, case_citation temporal_graph, graph
Legal Compliance Document compliance_list, defined_term_set list, set
SOP / Operation Manual workflow_graph, operation_flow temporal_graph, graph
Equipment Manual equipment_topology graph
Safety Handbook safety_control, emergency_response graph, graph
Failure Analysis Report failure_case graph
TCM Medical Record syndrome_reasoning hypergraph
Classical Formula Text formula_composition hypergraph
Acupuncture Text meridian_graph graph
Herbal Compendium herb_property model
Biography / Memoir biography_graph temporal_graph
Technical Documentation doc_structure graph
Skill Definition (Agent) workflow_graph temporal_graph
Conceptual Text concept_graph graph
Course textbook / lecture notes course_concept_graph graph
Syllabus / curriculum outline curriculum_structure hypergraph

Template Catalog

General Domain

General-purpose templates applicable to any document type.

Base Templates (8)

Template Type Description
base_model model General structured data extraction
base_list list General ordered list extraction
base_set set General deduplicated set extraction
base_graph graph General knowledge graph (entities + binary relations)
base_hypergraph hypergraph General hypergraph (multi-entity relations)
base_temporal_graph temporal_graph General temporal graph (relations + time)
base_spatial_graph spatial_graph General spatial graph (relations + location)
base_spatio_temporal_graph spatio_temporal_graph General spatio-temporal graph (relations + time + location)

Domain-Specific Templates (5)

Template Type Purpose Documents
workflow_graph temporal_graph Extract workflow steps and execution order Skill definitions, Agent workflows, SOPs
doc_structure graph Extract document hierarchy and cross-references Technical docs, papers, reports
biography_graph temporal_graph Extract life events with timestamps Biographies, memoirs, year timelines
concept_graph graph Extract conceptual hierarchies and relations Textbooks, encyclopedias, academic papers

Finance Domain

Templates optimized for financial documents and investor relations.

Template Type Purpose Documents
earnings_summary model Extract earnings call key metrics Earnings call transcripts
sentiment_model model Quantify market sentiment and themes Financial news, research reports
event_timeline temporal_graph Build company event timelines 8-K filings, news releases
ownership_graph graph Extract shareholder structures IPO prospectuses, annual reports
risk_factor_set set Catalog risk factors by category 10-K risk sections

Medicine Domain

Templates for clinical and medical documentation.

Template Type Purpose Documents
treatment_map hypergraph Extract diagnosis-treatment-outcome mappings Clinical guidelines
drug_interaction graph Map drug interaction networks Drug references, interaction databases
anatomy_graph graph Extract anatomical hierarchies Anatomy textbooks, surgical records
hospital_timeline temporal_graph Build patient admission timelines Discharge summaries, progress notes
discharge_instruction model Structured patient discharge information Discharge summaries, patient education

TCM Domain

Templates for Traditional Chinese Medicine literature.

Template Type Purpose Documents
formula_composition hypergraph Extract formula composition (君臣佐使) Classical formula texts
syndrome_reasoning hypergraph Extract syndrome-treatment reasoning Medical case records
meridian_graph graph Map acupoint-meridian relationships Acupuncture texts
herb_property model Extract herb properties (四气五味) Herbal compendiums
herb_relation graph Map herb compatibility (七情) Formula texts, compatibility guides

Industry Domain

Templates for industrial operations and maintenance.

Template Type Purpose Documents
operation_flow graph Extract operation steps and outcomes SOPs, operation manuals
safety_control graph Map hazard-risk-control relationships Safety handbooks
failure_case graph Extract failure phenomenon-causes-solutions Failure analysis reports
equipment_topology graph Map equipment hierarchies and connections Equipment manuals
emergency_response graph Map emergency scenarios and responses Emergency plans

Legal Domain

Templates for legal documents and compliance.

Template Type Purpose Documents
contract_obligation hypergraph Extract party-obligation relationships Service contracts, procurement contracts
case_fact_timeline temporal_graph Build case fact timelines Court judgments
case_citation graph Extract case citation relationships Legal opinions, case law
compliance_list list Structured compliance requirements Compliance manuals, audit reports
defined_term_set set Catalog defined terms Contracts, legal opinions

Education Domain

Templates for course materials, syllabi, and curriculum documents.

Template Type Purpose Documents
course_concept_graph graph Extract knowledge points and pedagogical dependencies Textbooks, lecture notes, course readers
curriculum_structure hypergraph Extract course–module–concept–assessment structure Syllabi, program plans, course outlines

Base Templates Reference

Base templates provide foundation patterns for extraction. Use them directly or extend them for custom needs.

Record Type Patterns

Pattern Schema Use Case
Key-Value Pairs model Information cards, profiles
Sequential Items list Rankings, sequences
Unique Items set Entity registries

Graph Type Patterns

Pattern Schema Use Case
Binary Relations graph Simple entity relationships
Multi-Entity Relations hypergraph Complex events, group relations
Time-Anchored Relations temporal_graph Histories, timelines
Location-Anchored Relations spatial_graph Maps, territories
Time + Location Relations spatio_temporal_graph Routes, events

Custom Templates

Create Your Own Template

A custom template is a standalone YAML file that can be placed anywhere.

YAML Template Structure

language: [zh, en]

name: my_custom_template
type: graph
tags: [custom]

description:
  zh: '我的自定义模板'
  en: 'My custom template'

output:
  description:
    zh: '输出描述'
    en: 'Output description'
  entities:
    fields:
      - name: name
        type: str
        description:
          zh: '实体名称'
          en: 'Entity name'
  relations:
    fields:
      - name: source
        type: str
      - name: target
        type: str
      - name: type
        type: str

guideline:
  target:
    zh: '你是一位...'
    en: 'You are an...'
  rules_for_entities:
    - '...'
  rules_for_relations:
    - '...'

identifiers:
  entity_id: name
  relation_id: '{source}|{type}|{target}'

Use Custom Template

from hyperextract.utils.template_engine import Template
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

llm = ChatOpenAI(model="gpt-4o-mini")
embedder = OpenAIEmbeddings()

# Load custom template by file path
template = Template.create(
    "/path/to/my_template.yaml",  # Template file path
    "zh",  # Language
    llm,
    embedder,
)

result = template.parse("Your document text here...")

Statistics

Domain Templates Base Domain-Specific
general 13 8 5
finance 5 0 5
medicine 5 0 5
tcm 5 0 5
industry 5 0 5
legal 5 0 5
education 2 0 2
Total 40 8 32

Contributing

To add a new template:

  1. Create a YAML file in the appropriate domain directory
  2. Follow the template structure conventions
  3. Include both Chinese and English descriptions
  4. Test with sample documents

License

Part of the Hyper-Extract project. See root LICENSE.