# Extraction methods reference

> Registered methods (`graph_rag`, `light_rag`, `hyper_rag`, `hypergraph_rag`, `cog_rag`, `itext2kg`, `itext2kg_star`, `kg_gen`, `atom`): autotype output, descriptions, registry API, and constructor kwargs.

- Repository: yifanfeng97/Hyper-Extract
- GitHub: https://github.com/yifanfeng97/Hyper-Extract
- Human docs: https://grok-wiki.com/public/docs/yifanfeng97-hyper-extract-7891c7254cdf
- Complete Markdown: https://grok-wiki.com/public/docs/yifanfeng97-hyper-extract-7891c7254cdf/llms-full.txt

## Source Files

- `hyperextract/methods/registry.py`
- `hyperextract/methods/rag/graph_rag.py`
- `hyperextract/methods/rag/light_rag.py`
- `hyperextract/methods/rag/hyper_rag.py`
- `hyperextract/methods/typical/kg_gen.py`
- `hyperextract/methods/typical/atom.py`
- `hyperextract/utils/template_engine/factory.py`

---

---
title: "Extraction methods reference"
description: "Registered methods (`graph_rag`, `light_rag`, `hyper_rag`, `hypergraph_rag`, `cog_rag`, `itext2kg`, `itext2kg_star`, `kg_gen`, `atom`): autotype output, descriptions, registry API, and constructor kwargs."
---

Nine extraction algorithms are registered in `hyperextract/methods/registry.py` at import time. Each entry maps a short name (for example `light_rag`) to a Python class, an autotype label (`graph` or `hypergraph`), and a description. `TemplateFactory.create_method` and `Template.create("method/<name>")` resolve names through this registry, instantiate the class with `llm_client` and `embedder`, and stamp instance metadata (`template`, `lang="en"`, `type`).

<Info>
Method templates always use English prompts. The `language` argument to `Template.create` is ignored for `method/` sources.
</Info>

## Method catalog

| Registry name | Python class | Autotype | Base engine | Description |
|---|---|---|---|---|
| `graph_rag` | `Graph_RAG` | `graph` | `AutoGraph` | Graph-RAG with community detection and global search |
| `light_rag` | `Light_RAG` | `graph` | `AutoGraph` | Lightweight graph RAG with binary entity–relation edges |
| `hyper_rag` | `Hyper_RAG` | `hypergraph` | `AutoHypergraph` | Hypergraph RAG with n-ary hyperedges |
| `hypergraph_rag` | `HyperGraph_RAG` | `hypergraph` | `AutoHypergraph` | Knowledge-segment hyperedges with nested entities |
| `cog_rag` | `Cog_RAG` | `hypergraph` | Dual `AutoHypergraph` layers | Theme layer + detail layer cognitive RAG |
| `itext2kg` | `iText2KG` | `graph` | `AutoGraph` | High-quality triple-based knowledge graph extraction |
| `itext2kg_star` | `iText2KG_Star` | `graph` | `AutoGraph` | Edge-first extraction with semantic node deduplication |
| `kg_gen` | `KG_Gen` | `graph` | `AutoGraph` | Subject–predicate–object triple generator |
| `atom` | `Atom` | `graph` | `AutoGraph` | Temporal triple extraction with evidence attribution |

Template IDs use the `method/<registry_name>` prefix (for example `method/atom`). List registered methods from the CLI with `he list method` or `he list method -q rag`.

```mermaid
classDiagram
    class MethodRegistry {
        +register_method(name, class, autotype, description)
        +get_method(name)
        +list_methods()
        +get_method_cfg(name)
        +list_method_cfgs()
    }
    class TemplateFactory {
        +create_method(name, llm, embedder, **kwargs)
        +create(source, language, llm, embedder, **kwargs)
    }
    class AutoGraph
    class AutoHypergraph
    class Cog_RAG

    MethodRegistry --> TemplateFactory : get_method()
    TemplateFactory --> AutoGraph : graph methods
    TemplateFactory --> AutoHypergraph : hypergraph methods
    TemplateFactory --> Cog_RAG : cog_rag
    Cog_RAG --> AutoHypergraph : theme_layer + detail_layer
```

## Registry API

Import from `hyperextract.methods`:

```python
from hyperextract.methods import (
    register_method,
    get_method,
    list_methods,
    get_method_cfg,
    list_method_cfgs,
    MethodCfg,
)
```

### `register_method`

<ParamField body="name" type="string" required>
Short registry key used by CLI `-m` and `method/<name>` template paths.
</ParamField>

<ParamField body="method_class" type="Type" required>
Callable class. Must accept `llm_client` and `embedder` as constructor arguments.
</ParamField>

<ParamField body="autotype" type="string" required>
Output category written to instance metadata `type`. Built-in values: `graph`, `hypergraph`.
</ParamField>

<ParamField body="description" type="string">
Human-readable summary shown by `he list method` and `Template.list()`.
</ParamField>

### `get_method`

<ResponseField name="class" type="Type">
Instantiable method class.
</ResponseField>

<ResponseField name="type" type="string">
Autotype label (`graph` or `hypergraph`).
</ResponseField>

<ResponseField name="description" type="string">
Registered description string.
</ResponseField>

Returns `None` when the name is unknown. `TemplateFactory.create_method` raises `ValueError` in that case.

### `list_methods`

Returns a shallow copy of the full registry: `Dict[str, Dict[str, Any]]` keyed by method name.

### `get_method_cfg` / `list_method_cfgs`

`get_method_cfg(name)` returns a `MethodCfg` Pydantic model or `None`.

<ResponseField name="name" type="string">
Registry key.
</ResponseField>

<ResponseField name="type" type="string">
Autotype label.
</ResponseField>

<ResponseField name="description" type="string">
Description string.
</ResponseField>

`list_method_cfgs()` returns `Dict[str, MethodCfg]` keyed by `method/<name>`, suitable for merging into `Template.list(include_methods=True)`.

### Register a custom method

```python
from hyperextract.methods import register_method
from hyperextract import Template

class MyMethod(AutoGraph):
    def __init__(self, llm_client, embedder, **kwargs):
        ...

register_method("my_method", MyMethod, "graph", "Custom graph extractor")

ka = Template.create("method/my_method", llm_client=llm, embedder=embedder)
```

Built-in methods are registered in `_init_registry()` inside `registry.py`; add new built-ins there and export the class from `hyperextract/methods/rag` or `hyperextract/methods/typical`.

## Autotype output

Registry `autotype` values map to Hyper-Extract primitives, not full class names:

| Registry `type` | Runtime instance | On-disk KA shape |
|---|---|---|
| `graph` | `AutoGraph` subclass | `data.json` with `nodes` and `edges` (binary or triple schemas) |
| `hypergraph` | `AutoHypergraph` subclass | `data.json` with `nodes` and hyperedge records |
| `hypergraph` (`cog_rag` only) | `Cog_RAG` wrapper | Root `data.json` (aggregated) plus `theme_layer/` and `detail_layer/` subdirectories |

After `TemplateFactory.create_method`, every instance carries:

```python
instance.metadata["template"]  # "method/<name>"
instance.metadata["lang"]      # "en"
instance.metadata["type"]      # registry autotype
```

## Constructor kwargs

All methods require a LangChain-compatible LLM and embedder. Additional kwargs pass through `Template.create(..., **kwargs)` and `TemplateFactory.create_method(..., **kwargs)` unchanged.

### Shared parameters

| Parameter | Type | Default | Applies to |
|---|---|---|---|
| `llm_client` | `BaseChatModel` | — (required) | All |
| `embedder` | `Embeddings` | — (required) | All |
| `chunk_size` | `int` | `2048` | All |
| `chunk_overlap` | `int` | `256` | All |
| `max_workers` | `int` | `10` | All |
| `verbose` | `bool` | `False` | All |

### Method-specific parameters

| Method | Extra kwargs | Default | Purpose |
|---|---|---|---|
| `atom` | `observation_time` | current date if omitted | Anchor for resolving relative temporal expressions in factoid and edge prompts |
| `atom` | `facts_per_chunk` | `10` | Max atomic facts per edge-extraction batch |
| `itext2kg_star` | `observation_date` | current datetime if omitted | Written to `edge.properties.observation_date` post-extraction |

<CodeGroup>
```python Python API
from hyperextract import Template

atom = Template.create(
    "method/atom",
    llm_client=llm,
    embedder=embedder,
    observation_time="2024-06-15",
    facts_per_chunk=8,
    chunk_size=1024,
    verbose=True,
)

star = Template.create(
    "method/itext2kg_star",
    llm_client=llm,
    embedder=embedder,
    observation_date="2024-06-15",
)
```

```bash CLI
he parse examples/en/tesla.md -m atom -o ./out/atom
he list method -q temporal
```
</CodeGroup>

## Per-method reference

### RAG methods (`hyperextract/methods/rag`)

#### `graph_rag` — `Graph_RAG`

Binary directed edges (`source`, `target`, `description`, `strength`). Two-stage extraction with `CustomRuleMerger` deduplication. Extends `AutoGraph` with community features:

- `build_communities(level=0)` — Leiden clustering via `graspologic` (optional; requires `networkx` and `graspologic`)
- `search(query, use_community=True)` — optional community-enhanced retrieval
- `dump` / `load` — persists `community_data.json` alongside standard KA files

#### `light_rag` — `Light_RAG`

Binary edges with `keywords` and `strength`. Edge keys use `f"{source}->{target}"`. Indexed fields: node `name/type/description`, edge `keywords/description`.

#### `hyper_rag` — `Hyper_RAG`

N-ary hyperedges via `participants: List[str]`. Edge keys are sorted participant tuples. Two-stage node-then-hyperedge extraction.

#### `hypergraph_rag` — `HyperGraph_RAG`

Edge-first extraction: each hyperedge is a `knowledge_segment` with embedded `related_entities` (`NodeSchema` list including `key_score`). Edge key is MD5 of segment text. Uses `MergeStrategy.LLM.BALANCED` for both nodes and edges. No separate node-extraction stage.

#### `cog_rag` — `Cog_RAG`

Dual-layer system, not a direct `AutoHypergraph` subclass:

| Layer | Class | Pattern | Output |
|---|---|---|---|
| Theme (macro) | `Cog_RAG_ThemeLayer` | Edge-first themes | `ThemeSchema` hyperedges with nested participant nodes |
| Detail (micro) | `Cog_RAG_DetailLayer` | Two-stage entities + hyperedges | `EdgeSchema` with `participants`, `keywords`, `strength` |

Public API: `feed_text`, `build_index`, `search(top_k_themes=3, top_k_entities=3)`, `chat`, `dump`, `load`, `show` (interactive layer picker). `nodes` and `edges` properties aggregate both layers.

### Typical methods (`hyperextract/methods/typical`)

#### `itext2kg` — `iText2KG`

Nested `NodeSchema` (`label`, `name`) and `EdgeSchema` (`startNode`, `endNode`, `name`). Two-stage extraction. Merge strategy: `MergeStrategy.LLM.BALANCED`.

#### `itext2kg_star` — `iText2KG_Star`

Edge-first extraction; nodes derived from edge endpoints. Sets `properties.observation_date` after extraction. Includes `match_nodes_and_update_edges(threshold=0.8)` for SemHash-based semantic deduplication. Merge strategy: `MergeStrategy.KEEP_EXISTING`.

#### `kg_gen` — `KG_Gen`

Minimal triple schema: nodes have `name` only; edges use `subject`, `predicate`, `object`. Two-stage extraction with `MergeStrategy.KEEP_EXISTING`. Post-extraction helpers:

- `deduplicate(threshold=0.9)` — returns new `KG_Gen` instance
- `self_deduplicate(threshold=0.9)` — in-place SemHash deduplication

#### `atom` — `Atom`

Temporal triple extraction pipeline:

1. Extract atomic factoids (`AtomicFactSchema`) per text chunk
2. Batch-extract edges from grouped facts
3. Derive nodes from edge `startNode` / `endNode`; set `t_obs` to observation timestamp

Edge fields: `t_start`, `t_end`, `t_obs`, `atomic_facts` (verbatim evidence). Custom `EDGE_MERGE_RULE` via `CustomRuleMerger`. Includes `match_nodes_and_update_edges(threshold=0.8)` for semantic node merging.

<Warning>
`graph_rag.build_communities()` requires optional packages `networkx` and `graspologic`. Community detection is skipped with a verbose message when `graspologic` is not installed.
</Warning>

## Extraction patterns

| Pattern | Methods | Behavior |
|---|---|---|
| Two-stage (nodes → edges) | `light_rag`, `graph_rag`, `hyper_rag`, `itext2kg`, `kg_gen`, `cog_rag` detail layer | `extraction_mode="two_stage"` |
| Edge-first (nodes derived) | `hypergraph_rag`, `itext2kg_star`, `cog_rag` theme layer | Custom `_extract_data` overrides |
| Facts → edges → nodes | `atom` | Atomic factoid pass, then edge extraction from fact batches |

## Direct class instantiation

Bypass the registry when tuning algorithm parameters directly:

```python
from hyperextract.methods.rag import Light_RAG
from hyperextract.methods.typical import Atom

rag = Light_RAG(llm_client=llm, embedder=embedder, chunk_size=1024, max_workers=5)
rag.feed_text(text)
rag.build_index()

atom = Atom(llm_client=llm, embedder=embedder, observation_time="2024-06-15")
atom.feed_text(text)
atom.match_nodes_and_update_edges(threshold=0.85)
```

Equivalent template path: `Template.create("method/light_rag", llm_client=llm, embedder=embedder, chunk_size=1024)`.

## Related pages

<CardGroup>
<Card title="Use extraction methods" href="/use-extraction-methods">
CLI `he parse -m` and Python `Template.create("method/...")` workflows with method-specific kwargs.
</Card>
<Card title="Templates vs methods" href="/templates-vs-methods">
When to pick domain YAML templates versus algorithm method templates.
</Card>
<Card title="Auto-Types" href="/auto-types">
`AutoGraph` and `AutoHypergraph` lifecycle, merge behavior, and indexing.
</Card>
<Card title="Method demos" href="/method-demos">
Runnable scripts under `examples/en/methods/` for each registered engine.
</Card>
<Card title="Python API reference" href="/python-api-reference">
`Template.create`, `BaseAutoType` lifecycle, and `create_client` helpers.
</Card>
<Card title="Contributing" href="/contributing">
Development setup and how to add templates or register new extraction methods.
</Card>
</CardGroup>