# Method demos

> Runnable scripts under `examples/en/methods/` for each extraction engine: instantiate method classes, `feed_text`, `chat`, and `show` with LangChain clients and dotenv configuration.

- 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

- `examples/en/methods/light_rag_demo.py`
- `examples/en/methods/graph_rag_demo.py`
- `examples/en/methods/hyper_rag_demo.py`
- `examples/en/methods/atom_demo.py`
- `examples/en/methods/kg_gen_demo.py`
- `examples/en/tesla.md`

---

---
title: "Method demos"
description: "Runnable scripts under `examples/en/methods/` for each extraction engine: instantiate method classes, `feed_text`, `chat`, and `show` with LangChain clients and dotenv configuration."
---

Nine runnable Python scripts under `examples/en/methods/` exercise every registered extraction method against the shared Tesla biography corpus. Each script follows the same lifecycle: load credentials with `dotenv`, construct LangChain LLM and embedder clients, instantiate a method class, call `feed_text`, run batch Q&A via `chat`, and open an OntoSight visualization with `show`.

## Demo inventory

All nine demos share input files and control flow; they differ only in the method class imported and the extraction statistics printed after `feed_text`.

| Script | Method class | Import path | Registry ID | AutoType | Post-extraction stats |
|--------|-------------|-------------|-------------|----------|----------------------|
| `light_rag_demo.py` | `Light_RAG` | `hyperextract.methods.rag` | `light_rag` | `graph` | `nodes`, `edges` |
| `graph_rag_demo.py` | `Graph_RAG` | `hyperextract.methods.rag` | `graph_rag` | `graph` | `nodes`, `edges` |
| `hyper_rag_demo.py` | `Hyper_RAG` | `hyperextract.methods.rag` | `hyper_rag` | `hypergraph` | `nodes`, `edges` (hyperedges) |
| `hypergraph_rag_demo.py` | `HyperGraph_RAG` | `hyperextract.methods.rag` | `hypergraph_rag` | `hypergraph` | `nodes`, `edges` (hyperedges) |
| `cog_rag_demo.py` | `Cog_RAG` | `hyperextract.methods.rag` | `cog_rag` | `hypergraph` | `nodes`, `edges` (dual-layer aggregate) |
| `itext2kg_demo.py` | `iText2KG` | `hyperextract.methods.typical` | `itext2kg` | `graph` | `nodes`, `edges` |
| `itext2kg_star_demo.py` | `iText2KG_Star` | `hyperextract.methods.typical` | `itext2kg_star` | `graph` | `nodes`, `edges` |
| `kg_gen_demo.py` | `KG_Gen` | `hyperextract.methods.typical` | `kg_gen` | `graph` | `nodes`, `edges` |
| `atom_demo.py` | `Atom` | `hyperextract.methods.typical` | `atom` | `graph` | `nodes`, `edges` (derived from atomic facts) |

<Note>
Method prompts are authored in English. The `examples/zh/methods/` directory mirrors every script with Chinese corpus files (`sushi.md`, `sushi_question.md`); entity names preserve the input language during extraction.
</Note>

## File layout

:::files
examples/
├── en/
│   ├── tesla.md              # Shared biography input (English)
│   ├── tesla_question.md     # Three evaluation questions
│   └── methods/
│       ├── light_rag_demo.py
│       ├── graph_rag_demo.py
│       ├── hyper_rag_demo.py
│       ├── hypergraph_rag_demo.py
│       ├── cog_rag_demo.py
│       ├── itext2kg_demo.py
│       ├── itext2kg_star_demo.py
│       ├── kg_gen_demo.py
│       └── atom_demo.py
└── zh/
    └── methods/              # Same nine scripts, Chinese corpus
:::

## Prerequisites

<Steps>
<Step title="Install Hyper-Extract">

```bash
uv pip install hyperextract
```

Python 3.11+ is required. Optional provider extras (`anthropic`, `google`, `all`) apply only when using non-OpenAI LangChain clients.

</Step>
<Step title="Configure credentials">

Copy `.env.example` to `.env` at the repository root and set provider variables:

```bash
cp .env.example .env
```

<ParamField body="OPENAI_API_KEY" type="string" required>
API key for the LLM and embedder endpoints.
</ParamField>

<ParamField body="OPENAI_BASE_URL" type="string">
Optional proxy or compatible endpoint base URL. Defaults to `https://api.openai.com/v1`.
</ParamField>

Each demo calls `load_dotenv()` at startup, so a root-level `.env` file is picked up automatically.

</Step>
<Step title="Verify LangChain clients">

Demos instantiate clients directly:

```python
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

llm = ChatOpenAI(model="gpt-4o-mini")
embedder = OpenAIEmbeddings(model="text-embedding-3-small")
```

For BYOC/BYOK deployments, swap in `create_client()` from `hyperextract` instead — see [Configure providers](/configure-providers).

</Step>
</Steps>

## Shared demo pattern

Every script under `examples/en/methods/` implements the same five-phase pipeline:

```mermaid
sequenceDiagram
    participant Script as Demo script
    participant Env as dotenv / .env
    participant LC as LangChain clients
    participant Method as Method class
    participant OS as OntoSight (show)

    Script->>Env: load_dotenv()
    Script->>Script: read tesla.md + tesla_question.md
    Script->>LC: ChatOpenAI + OpenAIEmbeddings
    Script->>Method: __init__(llm_client, embedder)
    Script->>Method: feed_text(text)
    Method-->>Script: nodes / edges populated
    loop Each question
        Script->>Method: chat(question)
        Method-->>Script: AIMessage.content
    end
    Script->>OS: show()
```

### Path resolution

Scripts resolve the repository root four levels above the demo file:

```python
project_root = Path(__file__).resolve().parent.parent.parent.parent
INPUT_FILE = project_root / "examples" / "en" / "tesla.md"
QUESTION_FILE = project_root / "examples" / "en" / "tesla_question.md"
```

Run demos from any working directory; paths are anchored to the script location, not the current shell cwd.

### Core lifecycle calls

<ParamField body="llm_client" type="BaseChatModel" required>
LangChain chat model passed to the method constructor.
</ParamField>

<ParamField body="embedder" type="Embeddings" required>
LangChain embedding model for vector indexing inside `feed_text`.
</ParamField>

<ParamField body="feed_text(text)" type="str → self">
Ingests document text, runs the method's extraction pipeline, and merges results into the in-memory Knowledge Abstract. Supports chaining: `method.feed_text(t1).feed_text(t2)`.
</ParamField>

<ParamField body="chat(query)" type="str → AIMessage">
Retrieves relevant graph or hypergraph context, then generates an answer. Demos print `result.content`.
</ParamField>

<ParamField body="show()" type="None">
Opens an OntoSight interactive visualization with embedded search and chat callbacks when vector indices exist.
</ParamField>

### Representative script

`light_rag_demo.py` is the canonical template; other demos differ only in the import, class name, and stat line:

```python
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from hyperextract.methods.rag import Light_RAG

load_dotenv()

llm = ChatOpenAI(model="gpt-4o-mini")
embedder = OpenAIEmbeddings(model="text-embedding-3-small")

rag = Light_RAG(llm_client=llm, embedder=embedder)
rag.feed_text(text)

for q in questions:
    result = rag.chat(q)
    print(result.content)

rag.show()
```

## Input corpus and questions

### `examples/en/tesla.md`

Nikola Tesla biography (1856–1943) covering early life, work with Edison, the War of Currents, Colorado Springs experiments, and Wardenclyffe Tower. All nine English method demos feed this single document.

### `examples/en/tesla_question.md`

Three evaluation questions, one per line:

- What are Tesla's major inventions and their significance?
- What was the "War of Currents" and who were the main participants?
- How did Tesla's relationship with Edison evolve over time?

Demos read non-empty lines into a list and iterate `chat` over each question inside a try/except block.

## Run a demo

<Steps>
<Step title="Pick a method">

```bash
python examples/en/methods/light_rag_demo.py
```

Replace `light_rag_demo.py` with any script from the inventory table.

</Step>
<Step title="Observe extraction output">

After `feed_text`, the script prints entity and relation counts. Graph methods report `len(rag.nodes)` and `len(rag.edges)`. Hypergraph methods (`Hyper_RAG`, `HyperGraph_RAG`) store hyperedges in the `edges` property on `AutoHypergraph`.

</Step>
<Step title="Review Q&A results">

Each question prints as `Q: …` followed by `A: …` from `result.content`. Errors are caught and printed without stopping the loop.

</Step>
<Step title="Visualize">

`show()` launches OntoSight. For graph and hypergraph AutoTypes, search and chat callbacks are wired when vector indices are present.

</Step>
</Steps>

<RequestExample>

```bash
python examples/en/methods/graph_rag_demo.py
```

</RequestExample>

<ResponseExample>

```text
============================================================
Graph RAG Demo
============================================================
Extracting entities and relations from Tesla's biography...

✓ Extracted 42 entities, 38 relations

------------------------------------------------------------
Q&A
------------------------------------------------------------

Q: What are Tesla's major inventions and their significance?
A: Tesla's major inventions include the AC induction motor, the Tesla coil, ...
```

</ResponseExample>

## Method-specific behavior

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

Five graph- and hypergraph-based RAG engines share constructor kwargs:

<ParamField body="chunk_size" type="int" default="2048">
Characters per text chunk during extraction.
</ParamField>

<ParamField body="chunk_overlap" type="int" default="256">
Overlap between consecutive chunks.
</ParamField>

<ParamField body="max_workers" type="int" default="10">
Concurrency limit for batch LLM calls.
</ParamField>

<ParamField body="verbose" type="bool" default="false">
Emit detailed extraction logs when `True`.
</ParamField>

| Class | Distinction |
|-------|-------------|
| `Light_RAG` | Lightweight binary-edge graph RAG |
| `Graph_RAG` | Community-detection graph RAG |
| `Hyper_RAG` | N-ary hyperedge extraction via `AutoHypergraph` |
| `HyperGraph_RAG` | Advanced multi-entity hypergraph construction |
| `Cog_RAG` | Dual-layer system: theme layer (macro narratives) + detail layer (micro entities) |

`Cog_RAG` is structurally different: it does not subclass `AutoGraph` or `AutoHypergraph`. It owns `theme_layer` and `detail_layer` sub-instances, aggregates `nodes` and `edges` across both, and its `show()` prompts interactively for layer selection (Detail Layer default, Theme Layer optional).

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

Four canonical graph-building pipelines subclass `AutoGraph`:

| Class | Role |
|-------|------|
| `iText2KG` | Triple-based knowledge graph extraction |
| `iText2KG_Star` | iText2KG with semantic deduplication |
| `KG_Gen` | Structured knowledge graph generation |
| `Atom` | Two-stage atomic-fact extraction with temporal fields (`t_start`, `t_end`, `t_obs`) and evidence attribution |

`Atom` accepts an additional constructor argument:

<ParamField body="observation_time" type="string">
Date baseline for resolving relative temporal expressions (for example `1997-10-10`). Defaults to the current date when omitted.
</ParamField>

<ParamField body="facts_per_chunk" type="int" default="10">
Maximum atomic facts batched into a single edge-extraction call.
</ParamField>

## Alternative client setup

Demos use explicit LangChain constructors for clarity. For provider-preset deployments, replace the client block with `create_client()`:

<CodeGroup>
```python title="OpenAI preset"
from hyperextract import create_client
from hyperextract.methods.rag import Light_RAG

llm, embedder = create_client("openai")
rag = Light_RAG(llm_client=llm, embedder=embedder)
```

```python title="Bailian preset"
llm, embedder = create_client("bailian", api_key="sk-xxx")
```

```python title="Mixed vLLM + cloud"
llm, embedder = create_client(
    llm="bailian:qwen-plus",
    embedder="vllm:bge-m3@localhost:8001/v1",
    api_key="sk-xxx",
)
```
</CodeGroup>

See [Provider system](/provider-system) for preset identifiers and compatibility requirements.

## CLI equivalent

Each demo method maps to a registered template ID usable from the CLI:

```bash
he parse examples/en/tesla.md -m light_rag -o ./output/light_rag
he talk ./output/light_rag -q "What was the War of Currents?"
he show ./output/light_rag
```

List all registered methods:

```bash
he list method
```

Demos exercise the direct Python class API; the CLI path persists a on-disk Knowledge Abstract under `-o`.

## Troubleshooting

<AccordionGroup>
<Accordion title="Missing API key or authentication error">

Confirm `OPENAI_API_KEY` is set in `.env` or exported in the shell before `load_dotenv()` runs. For non-OpenAI endpoints, set `OPENAI_BASE_URL` or switch to `create_client()` with the correct provider preset.

</Accordion>

<Accordion title="AttributeError on stat properties">

Hypergraph demos reference `hyper_edges` in print statements, but `AutoHypergraph` exposes hyperedges via the `edges` property. Use `len(method.edges)` when adapting demo output. `Atom` derives a graph from internal atomic facts; report `len(atom.nodes)` and `len(atom.edges)` rather than a `facts` attribute.

</Accordion>

<Accordion title="chat returns empty or generic answers">

Extraction quality depends on model structured-output support. Use models verified for `json_schema` or function calling. Enable debug logging:

```bash
export HYPER_EXTRACT_LOG_LEVEL=DEBUG
```

</Accordion>

<Accordion title="show() does not open or errors">

OntoSight requires a display environment. In headless environments, use `dump()` to persist the Knowledge Abstract and inspect `data.json` instead.

</Accordion>

<Accordion title="Cog_RAG show() blocks on input">

`Cog_RAG.show()` prompts for layer `1` (Detail) or `2` (Theme). In non-interactive runs it defaults to Detail Layer on `EOFError`.

</Accordion>
</AccordionGroup>

## Related pages

<CardGroup>
<Card title="Use extraction methods" href="/use-extraction-methods">
Invoke methods via `he parse -m` or `Template.create("method/…")`, including method-specific kwargs.
</Card>
<Card title="Extraction methods reference" href="/extraction-methods-reference">
Registry IDs, AutoType outputs, descriptions, and constructor parameters for all nine methods.
</Card>
<Card title="Tesla biography recipe" href="/tesla-biography-recipe">
End-to-end CLI and template workflow on the same `tesla.md` corpus with `general/biography_graph`.
</Card>
<Card title="Configure providers" href="/configure-providers">
Set up LLM and embedder clients via `he config`, environment variables, or `create_client()`.
</Card>
<Card title="Search, chat, and visualize" href="/search-chat-visualize">
CLI equivalents for `chat`, `search`, and `show` on persisted Knowledge Abstracts.
</Card>
</CardGroup>