Skip to content

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

docs: 更新文档中的知识库(knowledge base)为知识摘要(knowledge abstract)

yifanfeng97027753764acd
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..6d8ede4
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,45 @@
+version: 2
+updates:
+ # Python dependencies
+ - package-ecosystem: "pip"
+ directory: "/"
+ schedule:
+ interval: "weekly"
+ day: "monday"
+ time: "09:00"
+ open-pull-requests-limit: 10
+ reviewers:
+ - "yifanfeng97"
+ assignees:
+ - "yifanfeng97"
+ commit-message:
+ prefix: "chore(deps)"
+ include: "scope"
+ labels:
+ - "dependencies"
+ groups:
+ # Group patch updates together
+ patch-updates:
+ patterns:
+ - "*"
+ update-types:
+ - "patch"
+
+ # GitHub Actions
+ - package-ecosystem: "github-actions"
+ directory: "/"
+ schedule:
+ interval: "weekly"
+ day: "monday"
+ time: "09:00"
+ open-pull-requests-limit: 5
+ reviewers:
+ - "yifanfeng97"
+ assignees:
+ - "yifanfeng97"
+ commit-message:
+ prefix: "chore(ci)"
+ include: "scope"
+ labels:
+ - "dependencies"
+ - "ci"
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..01d4d96
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,83 @@
+name: Deploy Documentation
+
+on:
+ push:
+ branches:
+ - main
+ paths:
+ - "docs/**"
+ - "mkdocs.yml"
+ - "pyproject.toml"
+ - ".github/workflows/docs.yml"
+ workflow_dispatch:
+ inputs:
+ version:
+ description: "Version to deploy (e.g., 0.1.0 or latest)"
+ required: false
+ default: "latest"
+ alias:
+ description: "Alias to set (e.g., dev, stable)"
+ required: false
+ default: ""
+
+permissions:
+ contents: write
+ pages: write
+ id-token: write
+
+concurrency:
+ group: pages
+ cancel-in-progress: false
+
+jobs:
+ deploy-docs:
+ runs-on: ubuntu-latest
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v5
+ with:
+ enable-cache: true
+
+ - name: Install dependencies
+ run: |
+ uv pip install --system mkdocs-material mkdocs-static-i18n mkdocstrings[python] pymdown-extensions mike
+
+ - name: Configure Git
+ run: |
+ git config user.name "github-actions[bot]"
+ git config user.email "github-actions[bot]@users.noreply.github.com"
+
+ - name: Deploy with mike
+ run: |
+ VERSION="${{ github.event.inputs.version || 'latest' }}"
+ ALIAS="${{ github.event.inputs.alias }}"
+
+ # Build and deploy the version
+ if [ -n "$ALIAS" ]; then
+ echo "Deploying version $VERSION with alias $ALIAS"
+ mike deploy --push --update-aliases "$VERSION" "$ALIAS"
+ else
+ echo "Deploying version $VERSION"
+ mike deploy --push "$VERSION"
+ fi
+
+ # Set default version to latest
+ mike set-default --push latest
+
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
new file mode 100644
index 0000000..48e2d26
--- /dev/null
+++ b/.github/workflows/lint.yml
@@ -0,0 +1,67 @@
+name: Lint
+
+on:
+ push:
+ branches: [main, develop]
+ paths:
+ - "hyperextract/**/*.py"
+ - "pyproject.toml"
+ - ".github/workflows/lint.yml"
+ pull_request:
+ branches: [main, develop]
+ paths:
+ - "hyperextract/**/*.py"
+ - "pyproject.toml"
+ - ".github/workflows/lint.yml"
+
+permissions:
+ contents: read
+
+jobs:
+ ruff:
+ name: Ruff
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v5
+ with:
+ enable-cache: true
+
+ - name: Install ruff
+ run: uv pip install --system ruff
+
+ - name: Run ruff linter
+ run: ruff check hyperextract
+
+ - name: Run ruff formatter check
+ run: ruff format --check hyperextract
+
+ mypy:
+ name: Type Check (mypy)
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v5
+ with:
+ enable-cache: true
+
+ - name: Install dependencies
+ run: |
+ uv pip install --system -e ".[all]"
+ uv pip install --system mypy
+
+ - name: Run mypy
+ run: mypy hyperextract --ignore-missing-imports
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
new file mode 100644
index 0000000..098589a
--- /dev/null
+++ b/.github/workflows/publish.yml
@@ -0,0 +1,105 @@
+name: Publish to PyPI
+
+on:
+ release:
+ types: [published]
+ workflow_dispatch:
+ inputs:
+ test_pypi:
+ description: "Publish to Test PyPI instead of production"
+ required: false
+ default: false
+ type: boolean
+
+permissions:
+ contents: read
+
+jobs:
+ build:
+ name: Build distribution packages
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v5
+ with:
+ enable-cache: true
+
+ - name: Install build dependencies
+ run: uv pip install --system build hatchling
+
+ - name: Build package
+ run: python -m build
+
+ - name: Check distribution
+ run: |
+ uv pip install --system twine
+ twine check dist/*
+
+ - name: Upload distribution packages
+ uses: actions/upload-artifact@v4
+ with:
+ name: python-package-distributions
+ path: dist/
+ retention-days: 5
+
+ publish-pypi:
+ name: Publish to PyPI
+ needs: build
+ runs-on: ubuntu-latest
+ if: github.event_name == 'release' && !inputs.test_pypi
+
+ environment:
+ name: pypi
+ url: https://pypi.org/p/hyperextract
+
+ permissions:
+ id-token: write
+
+ steps:
+ - name: Download distribution packages
+ uses: actions/download-artifact@v4
+ with:
+ name: python-package-distributions
+ path: dist/
+
+ - name: Publish to PyPI
+ uses: pypa/gh-action-pypi-publish@release/v1
+ with:
+ attestations: true
+
+ publish-test-pypi:
+ name: Publish to Test PyPI
+ needs: build
+ runs-on: ubuntu-latest
+ if: inputs.test_pypi
+
+ environment:
+ name: test-pypi
+ url: https://test.pypi.org/p/hyperextract
+
+ permissions:
+ id-token: write
+
+ steps:
+ - name: Download distribution packages
+ uses: actions/download-artifact@v4
+ with:
+ name: python-package-distributions
+ path: dist/
+
+ - name: Publish to Test PyPI
+ uses: pypa/gh-action-pypi-publish@release/v1
+ with:
+ repository-url: https://test.pypi.org/legacy/
+ attestations: true
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 0000000..0417cbe
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,67 @@
+name: Tests
+
+on:
+ push:
+ branches: [main, develop]
+ paths:
+ - "hyperextract/**/*.py"
+ - "tests/**/*.py"
+ - "pyproject.toml"
+ - ".github/workflows/test.yml"
+ pull_request:
+ branches: [main, develop]
+ paths:
+ - "hyperextract/**/*.py"
+ - "tests/**/*.py"
+ - "pyproject.toml"
+ - ".github/workflows/test.yml"
+
+permissions:
+ contents: read
+
+jobs:
+ test:
+ name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
+ runs-on: ${{ matrix.os }}
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [ubuntu-latest, macos-latest]
+ python-version: ["3.11", "3.12"]
+ exclude:
+ # Reduce CI time by excluding some combinations
+ - os: macos-latest
+ python-version: "3.11"
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Set up Python ${{ matrix.python-version }}
+ uses: actions/setup-python@v5
+ with:
+ python-version: ${{ matrix.python-version }}
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v5
+ with:
+ enable-cache: true
+
+ - name: Install dependencies
+ run: |
+ uv pip install --system -e ".[all]"
+ uv pip install --system pytest pytest-cov
+
+ - name: Run tests
+ run: |
+ pytest --cov=hyperextract --cov-report=xml --cov-report=term -v
+ env:
+ PYTHONPATH: ${{ github.workspace }}
+
+ - name: Upload coverage to Codecov
+ if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+ uses: codecov/codecov-action@v5
+ with:
+ files: ./coverage.xml
+ fail_ci_if_error: false
+ verbose: true
diff --git a/.gitignore b/.gitignore
index 3e68017..21cb0f3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,7 @@
temp/
logs/
.trae/
-.github/
+.github/agents/
.claude/
# Byte-compiled / optimized / DLL files
diff --git a/README.md b/README.md
index 9258f92..04fc8ea 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@
<br/>
</div>
-Hyper-Extract is an intelligent, LLM-powered knowledge extraction and evolution framework. It radically simplifies transforming highly unstructured texts into persistent, predictable, and strongly-typed knowledge summaries. It effortlessly extracts information into a wide spectrum of formats—ranging from simple **Collections** (Lists/Sets) and **Pydantic Models**, to complex **Knowledge Graphs**, **Hypergraphs**, and even **Spatio-Temporal Graphs**.
+Hyper-Extract is an intelligent, LLM-powered knowledge extraction and evolution framework. It radically simplifies transforming highly unstructured texts into persistent, predictable, and strongly-typed **Knowledge Abstracts**. It effortlessly extracts information into a wide spectrum of formats—ranging from simple **Collections** (Lists/Sets) and **Pydantic Models**, to complex **Knowledge Graphs**, **Hypergraphs**, and even **Spatio-Temporal Graphs**.
## ✨ Core Features
@@ -63,7 +63,7 @@ he config init -k YOUR_OPENAI_API_KEY
# Extract knowledge
he parse examples/en/tesla.md -t general/biography_graph -o ./output/ -l en
-# Query the knowledge base
+# Query the knowledge abstract
he search ./output/ "What are Tesla's major achievements?"
# Visualize the knowledge graph
diff --git a/README_ZH.md b/README_ZH.md
index 567b636..aa0945b 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -31,7 +31,7 @@
<br/>
</div>
-Hyper-Extract 是一个智能的、由大语言模型(LLM)驱动的知识提取与演进框架。它极大地简化了将杂乱不堪的文本转化为持久化、强类型的知识摘要的过程。无论从基础的**集合(Collection/List)和**结构化模型(Model),还是到高阶复杂的**知识图谱(Knowledge Graph)**、**超图(Hypergraph)**,甚至是**时空图谱(Spatio-Temporal Graph)**,它都能轻松拿捏。
+Hyper-Extract 是一个智能的、由大语言模型(LLM)驱动的知识提取与演进框架。它极大地简化了将杂乱不堪的文本转化为持久化、强类型的**知识摘要(Knowledge Abstracts)**的过程。无论从基础的**集合(Collection/List)和**结构化模型(Model),还是到高阶复杂的**知识图谱(Knowledge Graph)**、**超图(Hypergraph)**,甚至是**时空图谱(Spatio-Temporal Graph)**,它都能轻松拿捏。
## ✨ 核心亮点
@@ -63,7 +63,7 @@ he config init -k YOUR_OPENAI_API_KEY
# 提取知识
he parse examples/zh/sushi.md -t general/biography_graph -o ./output/ -l zh
-# 查询知识库
+# 查询知识摘要
he search ./output/ "苏轼有哪些重要的作品?"
# 可视化知识图谱
diff --git a/docs/assets/examples/en/transformer_paper.txt b/docs/assets/examples/en/transformer_paper.txt
new file mode 100644
index 0000000..68d7be0
--- /dev/null
+++ b/docs/assets/examples/en/transformer_paper.txt
@@ -0,0 +1,40 @@
+# Attention Is All You Need
+
+## Abstract
+
+The dominant sequence transduction models are based on complex recurrent or convolutional neural networks that include an encoder and a decoder. The best performing models also connect the encoder and decoder through an attention mechanism. We propose a new simple network architecture, the Transformer, based solely on attention mechanisms, dispensing with recurrence and convolutions entirely. Experiments on two machine translation tasks show these models to be superior in quality while being more parallelizable and requiring significantly less time to train.
+
+## Authors
+
+- Ashish Vaswani
+- Noam Shazeer
+- Niki Parmar
+- Jakob Uszkoreit
+- Llion Jones
+- Aidan N. Gomez
+- Lukasz Kaiser
+- Illia Polosukhin
+
+## Introduction
+
+Recurrent neural networks, long short-term memory and gated recurrent neural networks in particular, have been firmly established as state of the art approaches in sequence modeling and transduction problems such as language modeling and machine translation. Numerous efforts have since continued to push the boundaries of recurrent language models and encoder-decoder architectures.
+
+## Key Innovation
+
+The Transformer eschews recurrence and instead relies entirely on an attention mechanism to draw global dependencies between input and output sequences. This allows for significantly more parallelization and can reach a new state of the art in translation quality after being trained for as little as twelve hours on eight P100 GPUs.
+
+## Model Architecture
+
+Most competitive neural sequence transduction models have an encoder-decoder structure. Here, the encoder maps an input sequence of symbol representations to a sequence of continuous representations. Given the continuous representation, the decoder generates an output sequence of symbols one element at a time.
+
+## Attention Mechanism
+
+An attention function can be described as mapping a query and a set of key-value pairs to an output, where the query, keys, values, and output are all vectors. The output is computed as a weighted sum of the values, where the weight assigned to each value is computed by a compatibility function of the query with the corresponding key.
+
+## Performance
+
+On the WMT 2014 English-to-German translation task, our model achieves a BLEU score of 28.4, outperforming all existing models, including ensembles, by over 2.0 BLEU. On the WMT 2014 English-to-French translation task, our model establishes a new single-model state-of-the-art BLEU score of 41.0.
+
+## Conclusion
+
+We presented the Transformer, the first transduction model based entirely on attention, replacing the recurrent layers most commonly used in encoder-decoder architectures with multi-headed self-attention. This architecture allows for significantly more parallelization and achieves state-of-the-art results on machine translation tasks.
diff --git a/docs/assets/examples/zh/transformer_paper.txt b/docs/assets/examples/zh/transformer_paper.txt
new file mode 100644
index 0000000..4b6bd66
--- /dev/null
+++ b/docs/assets/examples/zh/transformer_paper.txt
@@ -0,0 +1,40 @@
+# 注意力机制就是你所需要的一切
+
+## 摘要
+
+主流的序列转导模型基于复杂的循环或卷积神经网络,包含编码器和解码器。表现最好的模型还通过注意力机制连接编码器和解码器。我们提出了一种新的简单网络架构——Transformer,完全基于注意力机制,彻底摒弃了循环和卷积。在两个机器翻译任务上的实验表明,这些模型在质量上更优,同时具有更强的并行化能力,训练时间显著减少。
+
+## 作者
+
+- Ashish Vaswani
+- Noam Shazeer
+- Niki Parmar
+- Jakob Uszkoreit
+- Llion Jones
+- Aidan N. Gomez
+- Lukasz Kaiser
+- Illia Polosukhin
+
+## 引言
+
+循环神经网络,特别是长短期记忆网络(LSTM)和门控循环神经网络(GRU),已经在序列建模和转导问题(如语言建模和机器翻译)中被牢固确立为最先进的方法。此后,众多努力持续推动循环语言模型和编码器-解码器架构的边界。
+
+## 核心创新
+
+Transformer 摒弃了循环结构,转而完全依赖注意力机制来建模输入和输出序列之间的全局依赖关系。这允许更高程度的并行化,并且在使用八个 P100 GPU 训练仅十二小时后就能达到翻译质量的新最先进水平。
+
+## 模型架构
+
+大多数竞争性的神经序列转导模型都具有编码器-解码器结构。编码器将符号表示的输入序列映射到连续表示的序列。给定连续表示后,解码器逐个元素地生成符号的输出序列。
+
+## 注意力机制
+
+注意力函数可以描述为将查询和一组键-值对映射到输出,其中查询、键、值和输出都是向量。输出被计算为值的加权和,其中分配给每个值的权重由查询与相应键的兼容性函数计算得出。
+
+## 性能表现
+
+在 WMT 2014 英德翻译任务上,我们的模型取得了 28.4 的 BLEU 分数,超过了所有现有模型(包括集成模型)2.0 分以上。在 WMT 2014 英法翻译任务上,我们的模型建立了新的单模型最先进水平,BLEU 分数达到 41.0。
+
+## 结论
+
+我们提出了 Transformer,第一个完全基于注意力的转导模型,用多头自注意力取代了编码器-解码器架构中最常用的循环层。这种架构允许显著更多的并行化,并在机器翻译任务上达到了最先进的成果。
diff --git a/docs/en/cli/commands/build-index.md b/docs/en/cli/commands/build-index.md
index 87b309c..dddf333 100644
--- a/docs/en/cli/commands/build-index.md
+++ b/docs/en/cli/commands/build-index.md
@@ -1,6 +1,6 @@
# he build-index
-Build or rebuild the vector search index for a knowledge base.
+Build or rebuild the vector search index for a knowledge abstract.
---
@@ -14,7 +14,7 @@ he build-index KA_PATH [OPTIONS]
| Argument | Description |
|----------|-------------|
-| `KA_PATH` | Path to knowledge base directory |
+| `KA_PATH` | Path to knowledge abstract directory |
## Options
@@ -28,7 +28,7 @@ he build-index KA_PATH [OPTIONS]
Builds a vector search index for semantic search and chat functionality:
-1. **Reads all entities/relations** — From the knowledge base data
+1. **Reads all entities/relations** — From the knowledge abstract data
2. **Generates embeddings** — Using the configured embedding model
3. **Builds FAISS index** — For fast similarity search
4. **Saves to disk** — In the `index/` subdirectory
@@ -74,14 +74,14 @@ he build-index ./output/ -f
By default, `he parse` builds the index automatically:
```bash
-he parse doc.md -t general/biography_graph -o ./kb/ -l en
+he parse doc.md -t general/biography_graph -o ./ka/ -l en
# Index is built automatically
```
Skip with `--no-index` if you don't need search/chat:
```bash
-he parse doc.md -t general/biography_graph -o ./kb/ -l en --no-index
+he parse doc.md -t general/biography_graph -o ./ka/ -l en --no-index
```
### After Feed
@@ -89,8 +89,8 @@ he parse doc.md -t general/biography_graph -o ./kb/ -l en --no-index
Always rebuild after feeding new documents:
```bash
-he feed ./kb/ new_doc.md
-he build-index ./kb/
+he feed ./ka/ new_doc.md
+he build-index ./ka/
```
### After Manual Changes
@@ -98,17 +98,17 @@ he build-index ./kb/
If you modify `data.json` manually:
```bash
-he build-index ./kb/ -f
+he build-index ./ka/ -f
```
---
## Index Storage
-The index is stored in the knowledge base directory:
+The index is stored in the knowledge abstract directory:
```
-./kb/
+./ka/
├── data.json
├── metadata.json
└── index/ # Index directory
@@ -122,7 +122,7 @@ The index is stored in the knowledge base directory:
### Build Time
-| Knowledge Base Size | Approximate Build Time |
+| Knowledge Abstract Size | Approximate Build Time |
|---------------------|----------------------|
| Small (< 100 items) | < 5 seconds |
| Medium (100-1000) | 5-30 seconds |
@@ -133,7 +133,7 @@ The index is stored in the knowledge base directory:
Once built, searches are fast:
```bash
-he search ./kb/ "query" # Typically < 1 second
+he search ./ka/ "query" # Typically < 1 second
```
---
@@ -153,16 +153,16 @@ For processing multiple documents efficiently:
```bash
# Parse all without building index
-he parse doc1.md -t general/biography_graph -o ./kb/ -l en --no-index
-he feed ./kb/ doc2.md
-he feed ./kb/ doc3.md
+he parse doc1.md -t general/biography_graph -o ./ka/ -l en --no-index
+he feed ./ka/ doc2.md
+he feed ./ka/ doc3.md
# Build index once at the end
-he build-index ./kb/
+he build-index ./ka/
# Now ready for search/chat
-he search ./kb/ "query"
-he talk ./kb/ -q "question"
+he search ./ka/ "query"
+he talk ./ka/ -q "question"
```
---
@@ -174,13 +174,13 @@ he talk ./kb/ -q "question"
Use `-f` to force rebuild:
```bash
-he build-index ./kb/ -f
+he build-index ./ka/ -f
```
### "Failed to build index"
Check:
-1. Knowledge base has data: `he info ./kb/`
+1. Knowledge base has data: `he info ./ka/`
2. API key is configured: `he config show`
3. Sufficient disk space for index
@@ -189,7 +189,7 @@ Check:
Try force rebuild:
```bash
-he build-index ./kb/ -f
+he build-index ./ka/ -f
```
---
diff --git a/docs/en/cli/commands/config.md b/docs/en/cli/commands/config.md
index 23c402d..be92f67 100644
--- a/docs/en/cli/commands/config.md
+++ b/docs/en/cli/commands/config.md
@@ -1,6 +1,6 @@
# he config
-Manage Hyper-Extract configuration.
+Manage Hyper-Extract configuration for LLM and embedder settings.
---
@@ -14,16 +14,19 @@ he config [COMMAND] [OPTIONS]
| Command | Description |
|---------|-------------|
-| `init` | Initialize configuration |
+| `init` | Initialize configuration (lazy defaults: `gpt-4o-mini` + `text-embedding-3-small`) |
| `show` | Display current configuration |
-| `set` | Set a configuration value |
-| `get` | Get a configuration value |
+| `llm` | Configure LLM settings |
+| `embedder` | Configure embedder settings |
---
## he config init
-Initialize configuration with API credentials.
+Initialize configuration. This is the **lazy one-step setup** — if you pass `-k`, it skips all prompts and uses the built-in defaults:
+
+- **LLM**: `gpt-4o-mini`
+- **Embedder**: `text-embedding-3-small`
```bash
he config init [OPTIONS]
@@ -33,36 +36,30 @@ he config init [OPTIONS]
| Option | Short | Description |
|--------|-------|-------------|
-| `--key` | `-k` | OpenAI API key |
-| `--base-url` | `-u` | API base URL (optional) |
-| `--model` | `-m` | Default model (default: gpt-4o-mini) |
-| `--embedder` | `-e` | Embedding model (default: text-embedding-3-small) |
+| `--api-key` | `-k` | API key for both LLM and embedder |
+| `--base-url` | `-u` | Custom API base URL (optional) |
### Examples
-#### Basic Setup
+#### Lazy one-step setup (recommended)
```bash
he config init -k sk-your-api-key-here
```
-#### With Custom Base URL
-
-```bash
-he config init -k sk-your-key -u https://api.openai.com/v1
-```
+This saves `gpt-4o-mini` and `text-embedding-3-small` automatically.
-#### With Custom Models
+#### With custom base URL
```bash
-he config init -k sk-your-key -m gpt-4o -e text-embedding-3-large
+he config init -k sk-your-key -u https://api.openai.com/v1
```
-#### Interactive Mode
+#### Interactive setup
```bash
he config init
-# Prompts for API key interactively
+# Prompts for model names and API keys step by step
```
---
@@ -76,65 +73,85 @@ he config show
```
**Output:**
-```
-Configuration (from ~/.he/config.toml):
-
-[llm]
-model = "gpt-4o-mini"
-api_key = "sk-...***"
-base_url = "https://api.openai.com/v1"
-[embedder]
-model = "text-embedding-3-small"
-api_key = "sk-...***"
-
-[defaults]
-language = "en"
-chunk_size = 2048
-max_workers = 10
+```
+┌─────────────────────────────────────────────────────────┐
+│ Hyper-Extract Configuration │
+├──────────┬─────────────────────┬─────────────┬──────────┤
+│ Service │ Model │ API Key │ Base URL │
+├──────────┼─────────────────────┼─────────────┼──────────┤
+│ LLM │ gpt-4o-mini │ sk-xxxxx... │ (default)│
+│ Embedder │ text-embedding-3... │ sk-xxxxx... │ (default)│
+└──────────┴─────────────────────┴─────────────┴──────────┘
```
---
-## he config set
+## he config llm
-Set a configuration value.
+Configure LLM settings individually.
```bash
-he config set <KEY> <VALUE>
+he config llm [OPTIONS]
```
+### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--api-key` | `-k` | LLM API key |
+| `--model` | `-m` | LLM model name |
+| `--base-url` | `-u` | Custom API base URL |
+| `--show` | — | Show current LLM configuration |
+| `--unset` | — | Clear LLM configuration |
+
### Examples
```bash
-# Change default model
-he config set llm.model gpt-4o
+# View LLM config
+he config llm --show
-# Change embedding model
-he config set embedder.model text-embedding-3-large
+# Update LLM model
+he config llm --model gpt-4o
-# Set default language
-he config set defaults.language zh
+# Update LLM API key and endpoint
+he config llm --api-key sk-your-key --base-url https://api.openai.com/v1
+
+# Reset LLM config
+he config llm --unset
```
---
-## he config get
+## he config embedder
-Get a configuration value.
+Configure embedder settings individually.
```bash
-he config get <KEY>
+he config embedder [OPTIONS]
```
+### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--api-key` | `-k` | Embedder API key |
+| `--model` | `-m` | Embedder model name |
+| `--base-url` | `-u` | Custom API base URL |
+| `--show` | — | Show current embedder configuration |
+| `--unset` | — | Clear embedder configuration |
+
### Examples
```bash
-he config get llm.model
-# Output: gpt-4o-mini
+# View embedder config
+he config embedder --show
+
+# Use a different embedding model
+he config embedder --model text-embedding-3-large
-he config get defaults.language
-# Output: en
+# Reset embedder config
+he config embedder --unset
```
---
@@ -146,7 +163,7 @@ Configuration is stored at:
- **Linux/macOS**: `~/.he/config.toml`
- **Windows**: `%USERPROFILE%\.he\config.toml`
-### Example Configuration
+### Example
```toml
[llm]
@@ -156,39 +173,18 @@ base_url = "https://api.openai.com/v1"
[embedder]
model = "text-embedding-3-small"
-api_key = "sk-your-api-key"
-
-[defaults]
-language = "en"
-chunk_size = 2048
-chunk_overlap = 256
-max_workers = 10
-verbose = false
+api_key = "" # Empty inherits from llm.api_key
+base_url = "" # Empty inherits from llm.base_url
```
----
-
## Environment Variables
-Configuration can also be set via environment variables (higher priority):
-
| Variable | Description |
|----------|-------------|
-| `OPENAI_API_KEY` | API key for LLM and embedder |
-| `OPENAI_BASE_URL` | Custom API base URL |
-| `HE_LLM_MODEL` | Default LLM model |
-| `HE_EMBEDDER_MODEL` | Default embedding model |
-
----
-
-## Priority Order
-
-Configuration is resolved in this order (highest first):
+| `OPENAI_API_KEY` | API key fallback for LLM and embedder |
+| `OPENAI_BASE_URL` | Custom API base URL fallback |
-1. Command-line flags
-2. Environment variables
-3. Configuration file
-4. Built-in defaults
+**Priority (highest first):** command-line flags → environment variables → config file → defaults.
---
@@ -196,31 +192,18 @@ Configuration is resolved in this order (highest first):
### "API key not found"
-Initialize configuration:
-
```bash
he config init -k your-api-key
```
-Or set environment variable:
+Or:
```bash
export OPENAI_API_KEY=your-api-key
```
-### "Invalid API key"
-
-Check your API key:
-
-```bash
-he config show
-# Verify the key is correct
-```
-
### "Configuration file not found"
-Run init to create it:
-
```bash
he config init -k your-api-key
```
diff --git a/docs/en/cli/commands/feed.md b/docs/en/cli/commands/feed.md
index 497eba4..8bdc72e 100644
--- a/docs/en/cli/commands/feed.md
+++ b/docs/en/cli/commands/feed.md
@@ -1,6 +1,6 @@
# he feed
-Add documents to an existing knowledge base incrementally.
+Add documents to an existing knowledge abstract incrementally.
---
@@ -14,7 +14,7 @@ he feed KA_PATH INPUT [OPTIONS]
| Argument | Description |
|----------|-------------|
-| `KA_PATH` | Path to existing knowledge base directory |
+| `KA_PATH` | Path to existing knowledge abstract directory |
| `INPUT` | Input file path or `-` for stdin |
## Options
@@ -28,15 +28,15 @@ he feed KA_PATH INPUT [OPTIONS]
## Description
-The `feed` command adds new documents to an existing knowledge base without losing existing data:
+The `feed` command adds new documents to an existing knowledge abstract without losing existing data:
-1. **Loads existing knowledge** — Reads current knowledge base state
+1. **Loads existing knowledge** — Reads current knowledge abstract state
2. **Extracts from new document** — Processes the new content
3. **Merges intelligently** — Combines new and existing data, handling duplicates
4. **Updates metadata** — Records the update timestamp
This is ideal for:
-- Building knowledge bases over time
+- Building knowledge abstracts over time
- Adding updates to existing documents
- Combining information from multiple sources
@@ -57,23 +57,23 @@ he feed ./tesla_kb/ tesla_inventions.md
### Feed Multiple Documents
```bash
-he feed ./kb/ doc1.md
-he feed ./kb/ doc2.md
-he feed ./kb/ doc3.md
+he feed ./ka/ doc1.md
+he feed ./ka/ doc2.md
+he feed ./ka/ doc3.md
```
Or use a loop:
```bash
for file in updates/*.md; do
- he feed ./kb/ "$file"
+ he feed ./ka/ "$file"
done
```
### From Stdin
```bash
-cat new_content.md | he feed ./kb/ -
+cat new_content.md | he feed ./ka/ -
```
---
@@ -86,14 +86,14 @@ The merge process handles:
|----------|----------|
| Same entity | Merged, descriptions combined |
| Same relation | Updated with latest information |
-| New entities | Added to knowledge base |
+| New entities | Added to knowledge abstract |
| New relations | Added connecting existing/new entities |
---
## Workflow Example
-### Building a Research Knowledge Base
+### Building a Research Knowledge Abstract
```bash
# Day 1: Initial paper
@@ -133,7 +133,7 @@ he show ./bio_kb/
Check that the feed worked:
```bash
-he info ./kb/
+he info ./ka/
```
Look for:
@@ -147,8 +147,8 @@ Look for:
1. **Use same template** — Feeding should use compatible templates
2. **Match language** — Use consistent language for best results
-3. **Rebuild index after** — `he build-index ./kb/` for search/chat
-4. **Visualize changes** — `he show ./kb/` to see updates
+3. **Rebuild index after** — `he build-index ./ka/` for search/chat
+4. **Visualize changes** — `he show ./ka/` to see updates
---
@@ -156,10 +156,10 @@ Look for:
### "Not a valid Knowledge Abstract directory"
-The directory doesn't contain a valid knowledge base. Check:
+The directory doesn't contain a valid knowledge abstract. Check:
```bash
-ls ./kb/
+ls ./ka/
# Should contain: data.json, metadata.json
```
@@ -168,13 +168,13 @@ ls ./kb/
Feeding works best with the same template type. Override if needed:
```bash
-he feed ./kb/ doc.md -t general/biography_graph
+he feed ./ka/ doc.md -t general/biography_graph
```
---
## See Also
-- [`he parse`](parse.md) — Create new knowledge base
-- [`he info`](info.md) — View knowledge base statistics
+- [`he parse`](parse.md) — Create new knowledge abstract
+- [`he info`](info.md) — View knowledge abstract statistics
- [`he build-index`](build-index.md) — Rebuild search index after feeding
diff --git a/docs/en/cli/commands/info.md b/docs/en/cli/commands/info.md
index 06e10b7..3de2f3c 100644
--- a/docs/en/cli/commands/info.md
+++ b/docs/en/cli/commands/info.md
@@ -1,6 +1,6 @@
# he info
-Display information and statistics about a knowledge base.
+Display information and statistics about a knowledge abstract.
---
@@ -14,15 +14,15 @@ he info KA_PATH
| Argument | Description |
|----------|-------------|
-| `KA_PATH` | Path to knowledge base directory |
+| `KA_PATH` | Path to knowledge abstract directory |
---
## Description
-Shows metadata and statistics for a knowledge base:
+Shows metadata and statistics for a knowledge abstract:
-- **Path** — Location of the knowledge base
+- **Path** — Location of the knowledge abstract
- **Template** — Template used for extraction
- **Language** — Language code (en/zh)
- **Timestamps** — Creation and last update times
@@ -56,15 +56,15 @@ Index Built
### After Extraction
```bash
-he parse tesla.md -t general/biography_graph -o ./kb/ -l en
-he info ./kb/
+he parse tesla.md -t general/biography_graph -o ./ka/ -l en
+he info ./ka/
```
### After Feed
```bash
-he feed ./kb/ more_content.md
-he info ./kb/
+he feed ./ka/ more_content.md
+he info ./ka/
# Note the updated node/edge counts and timestamp
```
@@ -74,7 +74,7 @@ he info ./kb/
| Field | Description |
|-------|-------------|
-| `Path` | Absolute path to knowledge base |
+| `Path` | Absolute path to knowledge abstract |
| `Template` | Template identifier (e.g., `general/biography_graph`) |
| `Language` | Processing language (`en` or `zh`) |
| `Created` | Initial extraction timestamp |
@@ -92,7 +92,7 @@ he info ./kb/
Check that extraction worked:
```bash
-he info ./kb/
+he info ./ka/
# Should show Nodes > 0, Edges > 0
```
@@ -101,20 +101,20 @@ he info ./kb/
Before using search or chat:
```bash
-he info ./kb/
+he info ./ka/
# If Index shows "Not Built", run:
-he build-index ./kb/
+he build-index ./ka/
```
### Monitor Growth
-Track knowledge base growth over time:
+Track knowledge abstract growth over time:
```bash
-he info ./kb/
+he info ./ka/
# Feed more documents
-he feed ./kb/ update.md
-he info ./kb/
+he feed ./ka/ update.md
+he info ./ka/
# Compare node/edge counts
```
@@ -125,12 +125,12 @@ Use in automation scripts:
```bash
#!/bin/bash
-if he info ./kb/ 2>/dev/null; then
+if he info ./ka/ 2>/dev/null; then
echo "Knowledge base exists"
- he feed ./kb/ new_doc.md
+ he feed ./ka/ new_doc.md
else
- echo "Creating new knowledge base"
- he parse new_doc.md -t general/biography_graph -o ./kb/ -l en
+ echo "Creating new knowledge abstract"
+ he parse new_doc.md -t general/biography_graph -o ./ka/ -l en
fi
```
@@ -140,11 +140,11 @@ fi
### "Knowledge base directory not found"
-The directory doesn't exist or doesn't contain a knowledge base:
+The directory doesn't exist or doesn't contain a knowledge abstract:
```bash
# Check directory exists
-ls ./kb/
+ls ./ka/
# Should contain:
# - data.json
@@ -156,17 +156,17 @@ ls ./kb/
If metadata is corrupted, template/language show as "unknown":
```bash
-he info ./kb/
+he info ./ka/
# Template: [yellow]unknown[/yellow]
# Language: [yellow]unknown[/yellow]
```
-The knowledge base is still usable but some features may be limited.
+The knowledge abstract is still usable but some features may be limited.
---
## See Also
-- [`he parse`](parse.md) — Create knowledge base
-- [`he feed`](feed.md) — Add to knowledge base
+- [`he parse`](parse.md) — Create knowledge abstract
+- [`he feed`](feed.md) — Add to knowledge abstract
- [`he build-index`](build-index.md) — Build search index
diff --git a/docs/en/cli/commands/list.md b/docs/en/cli/commands/list.md
index 03265c2..3dac9e9 100644
--- a/docs/en/cli/commands/list.md
+++ b/docs/en/cli/commands/list.md
@@ -32,9 +32,9 @@ he list template
Available Templates:
Path Type Description
-general/base_model model Basic model extraction
-general/base_list list Basic list extraction
-general/base_graph graph Basic graph extraction
+general/model model Basic model extraction
+general/list list Basic list extraction
+general/graph graph Basic graph extraction
general/biography_graph temporal_graph Biography graph with timeline
finance/earnings_summary model Financial earnings summary
finance/ownership_graph graph Company ownership structure
diff --git a/docs/en/cli/commands/parse.md b/docs/en/cli/commands/parse.md
index 9ce1759..9f171c5 100644
--- a/docs/en/cli/commands/parse.md
+++ b/docs/en/cli/commands/parse.md
@@ -1,6 +1,6 @@
# he parse
-Extract knowledge from documents and save to a knowledge base.
+Extract knowledge from documents and save to a knowledge abstract.
---
@@ -49,7 +49,7 @@ he parse document.md -o ./output/ -l en
# You'll see:
# Select a template:
# [1] general/biography_graph
-# [2] general/knowledge_graph
+# [2] general/graph
# [3] finance/earnings_summary
# ...
# Enter number or search keyword:
diff --git a/docs/en/cli/commands/search.md b/docs/en/cli/commands/search.md
index 0b7da7d..b16d51c 100644
--- a/docs/en/cli/commands/search.md
+++ b/docs/en/cli/commands/search.md
@@ -1,6 +1,6 @@
# he search
-Perform semantic search over a knowledge base.
+Perform semantic search over a knowledge abstract.
---
@@ -14,7 +14,7 @@ he search KA_PATH QUERY [OPTIONS]
| Argument | Description |
|----------|-------------|
-| `KA_PATH` | Path to knowledge base directory |
+| `KA_PATH` | Path to knowledge abstract directory |
| `QUERY` | Search query string |
## Options
@@ -54,9 +54,9 @@ he search ./output/ "electrical engineering" -n 10
### Natural Language Queries
```bash
-he search ./kb/ "What were the major achievements?"
-he search ./kb/ "People who worked with Edison"
-he search ./kb/ "Important dates in the timeline"
+he search ./ka/ "What were the major achievements?"
+he search ./ka/ "People who worked with Edison"
+he search ./ka/ "Important dates in the timeline"
```
### After Building Index
@@ -100,7 +100,7 @@ Result 3:
## How It Works
1. **Query Embedding** — Converts your query to a vector
-2. **Index Search** — Finds nearest vectors in the knowledge base
+2. **Index Search** — Finds nearest vectors in the knowledge abstract
3. **Result Ranking** — Returns top-k most similar items
---
@@ -147,6 +147,6 @@ Try:
## See Also
-- [`he talk`](talk.md) — Chat with knowledge base
+- [`he talk`](talk.md) — Chat with knowledge abstract
- [`he build-index`](build-index.md) — Build search index
- [`he parse`](parse.md) — Extract with index building
diff --git a/docs/en/cli/commands/show.md b/docs/en/cli/commands/show.md
index 903fffe..13df29c 100644
--- a/docs/en/cli/commands/show.md
+++ b/docs/en/cli/commands/show.md
@@ -14,7 +14,7 @@ he show KA_PATH
| Argument | Description |
|----------|-------------|
-| `KA_PATH` | Path to knowledge base directory |
+| `KA_PATH` | Path to knowledge abstract directory |
---
@@ -115,20 +115,20 @@ http://localhost:xxxx
Check that extraction worked:
```bash
-he info ./kb/
+he info ./ka/
# Should show Nodes > 0 and Edges > 0
```
### "Error loading visualization"
-Ensure the knowledge base is valid:
+Ensure the knowledge abstract is valid:
```bash
# Check data file exists
-ls ./kb/data.json
+ls ./ka/data.json
# Try reloading
-he show ./kb/
+he show ./ka/
```
---
@@ -137,4 +137,4 @@ he show ./kb/
- [`he parse`](parse.md) — Extract knowledge
- [`he feed`](feed.md) — Add documents incrementally
-- [`he info`](info.md) — View knowledge base statistics
+- [`he info`](info.md) — View knowledge abstract statistics
diff --git a/docs/en/cli/commands/talk.md b/docs/en/cli/commands/talk.md
index 5137c84..258caa7 100644
--- a/docs/en/cli/commands/talk.md
+++ b/docs/en/cli/commands/talk.md
@@ -1,6 +1,6 @@
# he talk
-Chat with your knowledge base using natural language.
+Chat with your knowledge abstract using natural language.
---
@@ -14,7 +14,7 @@ he talk KA_PATH [OPTIONS]
| Argument | Description |
|----------|-------------|
-| `KA_PATH` | Path to knowledge base directory |
+| `KA_PATH` | Path to knowledge abstract directory |
## Options
@@ -28,7 +28,7 @@ he talk KA_PATH [OPTIONS]
## Description
-The `talk` command lets you have a conversation with your knowledge base:
+The `talk` command lets you have a conversation with your knowledge abstract:
1. **Retrieves relevant context** — Searches for information related to your question
2. **Generates answer** — Uses LLM to synthesize a natural language response
@@ -152,7 +152,7 @@ he talk ./bio_kb/ -q "What events led to Tesla's financial difficulties?"
## How It Works
-1. **Semantic Search** — Finds relevant items in the knowledge base
+1. **Semantic Search** — Finds relevant items in the knowledge abstract
2. **Context Assembly** — Combines retrieved items into context
3. **LLM Generation** — Generates answer using the context
4. **Source Attribution** — Shows which items informed the answer
@@ -191,7 +191,7 @@ he build-index ./output/
- Try rephrasing your question
- Increase context with `-n 10`
-- Verify knowledge base has relevant data: `he info ./output/`
+- Verify knowledge abstract has relevant data: `he info ./output/`
---
diff --git a/docs/en/cli/configuration.md b/docs/en/cli/configuration.md
index b3d1043..c1b9521 100644
--- a/docs/en/cli/configuration.md
+++ b/docs/en/cli/configuration.md
@@ -1,173 +1,171 @@
# CLI Configuration Reference
-Complete reference for Hyper-Extract CLI configuration.
+Configuration guide for Hyper-Extract CLI, from quick start to advanced settings.
---
-## Configuration File Location
+## Quick Start
-- **Linux/macOS**: `~/.he/config.toml`
-- **Windows**: `%USERPROFILE%\.he\config.toml`
+Complete configuration in 3 steps.
----
+### 1. Initialize Configuration
-## Configuration Sections
+```bash
+he config init -k YOUR_API_KEY
+```
-### [llm] — Language Model Settings
+This creates `~/.he/config.toml` with the following defaults:
+- **LLM**: `gpt-4o-mini`
+- **Embedder**: `text-embedding-3-small`
-| Key | Description | Default |
-|-----|-------------|---------|
-| `model` | LLM model name | `gpt-4o-mini` |
-| `api_key` | OpenAI API key | *required* |
-| `base_url` | API base URL | `https://api.openai.com/v1` |
+### 2. Verify Configuration
-**Example:**
-```toml
-[llm]
-model = "gpt-4o"
-api_key = "sk-your-api-key"
-base_url = "https://api.openai.com/v1"
+```bash
+he config show
```
-**Supported Models:**
-- `gpt-4o-mini` — Fast, cost-effective
-- `gpt-4o` — High quality
-- `gpt-4-turbo` — Best quality
-- Other OpenAI-compatible models
+You should see output like this:
----
+```
+┌─────────────────────────────────────────────────────────┐
+│ Hyper-Extract Configuration │
+├──────────┬─────────────────────┬─────────────┬──────────┤
+│ Service │ Model │ API Key │ Base URL │
+├──────────┼─────────────────────┼─────────────┼──────────┤
+│ LLM │ gpt-4o-mini │ sk-xxxxx... │ (default)│
+│ Embedder │ text-embedding-3... │ sk-xxxxx... │ (default)│
+└──────────┴─────────────────────┴─────────────┴──────────┘
+```
+
+### 3. Modify Configuration (Optional)
-### [embedder] — Embedding Model Settings
+```bash
+# Change LLM model
+he config llm --model gpt-4o
-| Key | Description | Default |
-|-----|-------------|---------|
-| `model` | Embedding model name | `text-embedding-3-small` |
-| `api_key` | API key (defaults to llm.api_key) | — |
+# Use different embedder model
+he config embedder --model text-embedding-3-large
-**Example:**
-```toml
-[embedder]
-model = "text-embedding-3-large"
+# Configure custom API endpoint
+he config llm --base-url https://your-api-endpoint.com/v1
```
-**Supported Models:**
-- `text-embedding-3-small` — Fast, cost-effective
-- `text-embedding-3-large` — Better quality
-- `text-embedding-ada-002` — Legacy
-
---
-### [defaults] — Default Behavior Settings
+## CLI Command Reference
-| Key | Description | Default |
-|-----|-------------|---------|
-| `language` | Default language (`en` or `zh`) | `en` |
-| `chunk_size` | Text chunk size for processing | `2048` |
-| `chunk_overlap` | Overlap between chunks | `256` |
-| `max_workers` | Parallel processing workers | `10` |
-| `verbose` | Enable verbose output | `false` |
+### Command Overview
-**Example:**
-```toml
-[defaults]
-language = "en"
-chunk_size = 4096
-chunk_overlap = 512
-max_workers = 5
-verbose = true
+| Command | Common Flags | Description |
+|---------|-------------|-------------|
+| `he config init` | `-k, --api-key` — API key<br>`-u, --base-url` — Custom API base URL | Initialize configuration (first time) |
+| `he config llm` | `-m, --model` — Model name<br>`-k, --api-key` — API key<br>`-u, --base-url` — Custom API base URL<br>`--show` — Show current config<br>`--unset` — Clear configuration | Configure LLM |
+| `he config embedder` | `-m, --model` — Model name<br>`-k, --api-key` — API key<br>`-u, --base-url` — Custom API base URL<br>`--show` — Show current config<br>`--unset` — Clear configuration | Configure embedder |
+| `he config show` | — | View complete configuration |
+
+### Common Usage Examples
+
+**Interactive initialization (recommended for first-time users):**
+```bash
+he config init
+# Follow prompts to enter model name, API key, etc.
```
----
+**Non-interactive initialization (for scripts):**
+```bash
+he config init -k sk-your-api-key
+```
-## Environment Variables
+**View LLM configuration:**
+```bash
+he config llm --show
+```
-All configuration options can be set via environment variables:
+**Configure embedder separately (using different key):**
+```bash
+he config embedder --api-key sk-embedder-key --model text-embedding-3-large
+```
-| Variable | Maps To | Example |
-|----------|---------|---------|
-| `OPENAI_API_KEY` | `llm.api_key`, `embedder.api_key` | `sk-...` |
-| `OPENAI_BASE_URL` | `llm.base_url` | `https://api.openai.com/v1` |
-| `HE_LLM_MODEL` | `llm.model` | `gpt-4o` |
-| `HE_EMBEDDER_MODEL` | `embedder.model` | `text-embedding-3-large` |
-| `HE_DEFAULT_LANGUAGE` | `defaults.language` | `zh` |
-| `HE_CHUNK_SIZE` | `defaults.chunk_size` | `4096` |
-| `HE_VERBOSE` | `defaults.verbose` | `true` |
+**Clear configuration (reset to defaults):**
+```bash
+he config llm --unset
+he config embedder --unset
+```
---
-## Complete Example
+## Configuration File Details
-```toml
-# ~/.he/config.toml
+Running `he config init` automatically creates `~/.he/config.toml`.
+
+### File Location
+
+- **Linux/macOS**: `~/.he/config.toml`
+- **Windows**: `%USERPROFILE%\.he\config.toml`
+### Configuration Format
+
+```toml
[llm]
model = "gpt-4o-mini"
-api_key = "sk-your-api-key-here"
+api_key = "sk-your-api-key"
base_url = "https://api.openai.com/v1"
[embedder]
model = "text-embedding-3-small"
-# api_key defaults to llm.api_key
-
-[defaults]
-language = "en"
-chunk_size = 2048
-chunk_overlap = 256
-max_workers = 10
-verbose = false
+api_key = "" # Empty means inherit from llm.api_key
+base_url = "" # Empty means inherit from llm.base_url
```
----
-
-## Configuration Priority
+### Configuration Options
-Settings are resolved in this order (highest priority first):
+| Section | Key | Description | Default |
+|---------|-----|-------------|---------|
+| `[llm]` | `model` | LLM model name | `gpt-4o-mini` |
+| `[llm]` | `api_key` | OpenAI API key | Required |
+| `[llm]` | `base_url` | API base URL | `https://api.openai.com/v1` |
+| `[embedder]` | `model` | Embedding model name | `text-embedding-3-small` |
+| `[embedder]` | `api_key` | API key (empty inherits from llm) | — |
+| `[embedder]` | `base_url` | API base URL (empty inherits from llm) | — |
-1. **Command-line flags** (e.g., `-l zh`)
-2. **Environment variables** (e.g., `OPENAI_API_KEY`)
-3. **Configuration file** (`~/.he/config.toml`)
-4. **Built-in defaults**
+### Supported Models
----
-
-## Managing Configuration
-
-### Initialize
-
-```bash
-he config init -k your-api-key
-```
+**LLM Models:**
+- `gpt-4o-mini` — Fast, cost-effective (default)
+- `gpt-4o` — High quality
+- `gpt-4-turbo` — Best quality
+- Other OpenAI-compatible models
-### View Current Settings
+**Embedding Models:**
+- `text-embedding-3-small` — Fast, cost-effective (default)
+- `text-embedding-3-large` — Better quality
+- `text-embedding-ada-002` — Legacy model
-```bash
-he config show
-```
+---
-### Update Settings
+## Environment Variables
-```bash
-# Update single value
-he config set llm.model gpt-4o
+The following environment variables can be used as configuration fallback:
-# Or edit file directly
-nano ~/.he/config.toml
-```
+| Variable | Maps To | Example |
+|----------|---------|---------|
+| `OPENAI_API_KEY` | `llm.api_key`, `embedder.api_key` | `sk-...` |
+| `OPENAI_BASE_URL` | `llm.base_url` | `https://api.openai.com/v1` |
-### Reset to Defaults
+**Priority Note:** Environment variables take precedence over config file, but are overridden by command-line flags.
-```bash
-rm ~/.he/config.toml
-he config init -k your-api-key
-```
+**Use Cases:**
+- Temporarily switch API keys
+- Inject secrets in CI/CD environments
+- Avoid hardcoding keys in config files
---
## Advanced Configuration
-### Custom API Endpoint
+### Using OpenAI-Compatible APIs
-For OpenAI-compatible APIs (Azure, local models, etc.):
+For Azure, local models, and other OpenAI-compatible APIs:
```toml
[llm]
@@ -179,39 +177,66 @@ base_url = "https://your-api-endpoint.com/v1"
model = "your-embedding-model"
```
-### Different Keys for LLM and Embedder
+### Different Keys and Base URLs for LLM and Embedder
```toml
[llm]
model = "gpt-4o-mini"
api_key = "sk-llm-key"
+base_url = "https://api.openai.com/v1"
[embedder]
-model = "text-embedding-3-small"
+model = "text-embedding-3-large"
api_key = "sk-embedder-key"
+base_url = "https://your-embedder-provider.com/v1"
```
---
## Troubleshooting
+### "API key not found"
+
+**Cause**: API key not configured
+
+**Solution**:
+
+```bash
+he config init -k YOUR_API_KEY
+```
+
+### "Failed to connect to API"
+
+**Cause**: Network issues or incorrect base_url
+
+**Solution**:
+
+```bash
+# Check configuration
+he config llm --show
+
+# Reset base_url
+he config llm --base-url https://api.openai.com/v1
+```
+
### Permission Denied
+**Solution**:
+
```bash
-# Fix permissions
chmod 600 ~/.he/config.toml
```
### Invalid TOML Format
-Validate your configuration:
+**Validate configuration**:
```bash
-# Using Python
-python -c "import tomllib; tomllib.load(open('~/.he/config.toml', 'rb'))"
+python3 -c "import tomllib; tomllib.load(open('$HOME/.he/config.toml', 'rb'))"
```
-Common issues:
+**Common issues**:
+
- Missing quotes around strings
- Trailing commas
- Incorrect section headers
@@ -220,5 +245,5 @@ Common issues:
## See Also
-- [`he config`](commands/config.md) — Configuration commands
-- [Installation Guide](../getting-started/installation.md) — Initial setup
+- [`he config`](commands/config.md) — Detailed configuration command reference
+- [Installation Guide](../getting-started/installation.md) — Initial setup steps
diff --git a/docs/en/cli/index.md b/docs/en/cli/index.md
index ec6543f..ffd6e3d 100644
--- a/docs/en/cli/index.md
+++ b/docs/en/cli/index.md
@@ -32,10 +32,10 @@ he --version
|---------|---------|--------------|
| `he parse` | Extract knowledge from documents | `-t` template, `-o` output, `-l` language |
| `he show` | Visualize knowledge graph | — |
-| `he search` | Semantic search in knowledge base | `-n` top-k results |
-| `he talk` | Chat with knowledge base | `-i` interactive, `-q` query |
+| `he search` | Semantic search in knowledge abstract | `-n` top-k results |
+| `he talk` | Chat with knowledge abstract | `-i` interactive, `-q` query |
| `he feed` | Add documents incrementally | — |
-| `he info` | Show knowledge base statistics | — |
+| `he info` | Show knowledge abstract statistics | — |
| `he build-index` | Build/rebuild search index | `-f` force rebuild |
| `he list` | List templates and methods | `template` or `method` |
| `he config` | Manage configuration | `init`, `show`, `set` |
@@ -49,22 +49,22 @@ The typical workflow for extracting and interacting with knowledge:
```mermaid
flowchart TB
subgraph Create ["🚀 Create"]
- D[📄 Document] -->|he parse| KB[(💡 Knowledge Base)]
+ D[📄 Document] -->|he parse| KA[(💡 Knowledge Abstract)]
end
subgraph Enhance ["✨ Enhance (Optional)"]
- KB -->|he feed| KB
- KB -->|he build-index| IDX[(🔍 Index)]
+ KA -->|he feed| KA
+ KA -->|he build-index| IDX[(🔍 Index)]
end
subgraph Explore ["🔍 Explore"]
- KB -->|he show| VIS[👁️ Visualize]
+ KA -->|he show| VIS[👁️ Visualize]
IDX -->|he search| SRCH[🔎 Search]
IDX -->|he talk| CHAT[💬 Chat]
end
subgraph Save ["💾 Save"]
- KB -->|he dump| DISK[💾 Disk]
+ KA -->|he dump| DISK[💾 Disk]
end
```
@@ -104,14 +104,14 @@ he show ./output/
### Knowledge Extraction
- **[`he parse`](commands/parse.md)** — Extract knowledge from documents
-- **[`he feed`](commands/feed.md)** — Add documents to existing knowledge base
+- **[`he feed`](commands/feed.md)** — Add documents to existing knowledge abstract
### Exploration
- **[`he show`](commands/show.md)** — Visualize knowledge graph
- **[`he search`](commands/search.md)** — Semantic search
-- **[`he talk`](commands/talk.md)** — Chat with knowledge base
-- **[`he info`](commands/info.md)** — View knowledge base statistics
+- **[`he talk`](commands/talk.md)** — Chat with knowledge abstract
+- **[`he info`](commands/info.md)** — View knowledge abstract statistics
### Management
diff --git a/docs/en/cli/workflow.md b/docs/en/cli/workflow.md
index e722404..7d0fc53 100644
--- a/docs/en/cli/workflow.md
+++ b/docs/en/cli/workflow.md
@@ -12,45 +12,11 @@ Imagine you're a researcher who wants to extract and interact with knowledge fro
## Step 1: Prepare Your Document
-First, ensure your document is in a supported format (`.md`, `.txt`):
+Hyper-Extract supports `.md` and `.txt` files. Download the sample research paper below to follow this guide:
-```bash
-# Example: Convert PDF to text (using external tools)
-pdftotext paper.pdf paper.md
-```
+<a href="/assets/examples/en/transformer_paper.txt" download class="md-button">📥 Download Sample Document</a>
-Or create a sample document:
-
-```bash
-cat > transformer_paper.md << 'EOF'
-# Attention Is All You Need
-
-## Abstract
-The dominant sequence transduction models are based on complex recurrent or
-convolutional neural networks that include an encoder and a decoder. The best
-performing models also connect the encoder and decoder through an attention
-mechanism. We propose a new simple network architecture, the Transformer,
-based solely on attention mechanisms.
-
-## Authors
-- Ashish Vaswani
-- Noam Shazeer
-- Niki Parmar
-- Jakob Uszkoreit
-- Llion Jones
-- Aidan N. Gomez
-- Lukasz Kaiser
-- Illia Polosukhin
-
-## Key Innovation
-The Transformer eschews recurrence and instead relies entirely on an attention
-mechanism to draw global dependencies between input and output sequences.
-
-## Performance
-On the WMT 2014 English-to-German translation task, our model achieves a
-BLEU score of 28.4, outperforming all existing models.
-EOF
-```
+Save the file as `transformer_paper.md` in your working directory.
---
@@ -105,7 +71,10 @@ Index Built
he show ./transformer_kb/
```
+![Knowledge Graph Visualization](../../assets/en_show.png)
+
This opens an interactive graph in your browser showing:
+
- **Nodes**: Authors, concepts, models, metrics
- **Edges**: Relationships between them
@@ -190,7 +159,7 @@ Goodbye!
---
-## Step 6: Expand Your Knowledge Base
+## Step 6: Expand Your Knowledge Abstract
### Add Another Document
@@ -198,7 +167,7 @@ Goodbye!
# Download another paper
curl -o bert_paper.md https://example.com/bert.md
-# Add to existing knowledge base
+# Add to existing knowledge abstract
he feed ./transformer_kb/ bert_paper.md
```
@@ -274,17 +243,17 @@ Process multiple documents at once:
```bash
# Create output directories
-mkdir -p ./kb/paper1 ./kb/paper2 ./kb/paper3
+mkdir -p ./ka/paper1 ./ka/paper2 ./ka/paper3
# Process each
-he parse papers/paper1.md -t general/concept_graph -o ./kb/paper1/ -l en
-he parse papers/paper2.md -t general/concept_graph -o ./kb/paper2/ -l en
-he parse papers/paper3.md -t general/concept_graph -o ./kb/paper3/ -l en
+he parse papers/paper1.md -t general/concept_graph -o ./ka/paper1/ -l en
+he parse papers/paper2.md -t general/concept_graph -o ./ka/paper2/ -l en
+he parse papers/paper3.md -t general/concept_graph -o ./ka/paper3/ -l en
# Or use a loop
for file in papers/*.md; do
name=$(basename "$file" .md)
- he parse "$file" -t general/concept_graph -o "./kb/$name/" -l en
+ he parse "$file" -t general/concept_graph -o "./ka/$name/" -l en
done
```
@@ -296,15 +265,15 @@ done
```bash
# Initial extraction
-he parse initial_doc.md -t general/biography_graph -o ./kb/ -l en
+he parse initial_doc.md -t general/biography_graph -o ./ka/ -l en
# Weekly updates
-he feed ./kb/ week1_update.md
-he feed ./kb/ week2_update.md
-he feed ./kb/ week3_update.md
+he feed ./ka/ week1_update.md
+he feed ./ka/ week2_update.md
+he feed ./ka/ week3_update.md
# Monthly rebuild
-he build-index ./kb/ -f
+he build-index ./ka/ -f
```
### Pattern 2: Multi-Domain Project
@@ -314,7 +283,7 @@ he build-index ./kb/ -f
he parse api_docs.md -t general/concept_graph -o ./project_kb/tech/ -l en
# Legal contracts
-he parse contract.pdf -t legal/contract_obligation -o ./project_kb/legal/ -l en
+he parse contract.md -t legal/contract_obligation -o ./project_kb/legal/ -l en
# Financial reports
he parse q4_report.md -t finance/earnings_summary -o ./project_kb/finance/ -l en
@@ -324,12 +293,12 @@ he parse q4_report.md -t finance/earnings_summary -o ./project_kb/finance/ -l en
```bash
# Extract two versions
-he parse draft_v1.md -t general/concept_graph -o ./kb/v1/ -l en
-he parse draft_v2.md -t general/concept_graph -o ./kb/v2/ -l en
+he parse draft_v1.md -t general/concept_graph -o ./ka/v1/ -l en
+he parse draft_v2.md -t general/concept_graph -o ./ka/v2/ -l en
# Compare via chat
-he talk ./kb/v1/ -q "What are the main topics?"
-he talk ./kb/v2/ -q "What are the main topics?"
+he talk ./ka/v1/ -q "What are the main topics?"
+he talk ./ka/v2/ -q "What are the main topics?"
```
---
@@ -339,7 +308,7 @@ he talk ./kb/v2/ -q "What are the main topics?"
| Issue | Solution |
|-------|----------|
| Extraction is slow | Long documents are chunked; use `--no-index` to skip indexing during parse |
-| Search returns nothing | Ensure index is built: `he build-index ./kb/` |
+| Search returns nothing | Ensure index is built: `he build-index ./ka/` |
| Template not found | List available: `he list template` |
| Out of memory | Reduce chunk size in config or process smaller documents |
diff --git a/docs/en/concepts/autotypes.md b/docs/en/concepts/autotypes.md
index 796c590..8eb0700 100644
--- a/docs/en/concepts/autotypes.md
+++ b/docs/en/concepts/autotypes.md
@@ -1,282 +1,308 @@
# Auto-Types
-Complete guide to the 8 knowledge structure types.
+Understanding the 8 knowledge structure types: what they are and when to use them.
---
-## Overview
+## What Are Auto-Types?
-Auto-Types are intelligent data structures that:
-- Define extraction output format
-- Provide type-safe schemas
-- Include built-in operations (search, visualize, etc.)
-- Support serialization
+Auto-Types are intelligent data structures that define how extracted knowledge is organized. Think of them as "containers" that shape what comes out of your documents.
+
+Key characteristics:
+
+| Characteristic | Description |
+|----------------|-------------|
+| **Type-Safe** | Pydantic-based validation ensures consistent data |
+| **Self-Contained** | Built-in operations (search, visualize, save) |
+| **Serializable** | Save to disk, load later |
+| **Composable** | Merge, update, extend incrementally |
---
## The 8 Auto-Types
+Organized into two categories:
+
```mermaid
graph TD
- A[Auto-Types] --> B[Scalar Types]
- A --> C[Graph Types]
- A --> D[Temporal Types]
-
- B --> B1[AutoModel]
- B --> B2[AutoList]
- B --> B3[AutoSet]
-
- C --> C1[AutoGraph]
- C --> C2[AutoHypergraph]
-
- D --> D1[AutoTemporalGraph]
- D --> D2[AutoSpatialGraph]
- D --> D3[AutoSpatioTemporalGraph]
+ A[Auto-Types] --> B[Record Types<br/>Store data, no entity relations]
+ A --> C[Graph Types<br/>Entity relationships]
+
+ B --> B1[AutoModel<br/>One structured object]
+ B --> B2[AutoList<br/>Ordered items]
+ B --> B3[AutoSet<br/>Unique items]
+
+ C --> C1[AutoGraph<br/>Binary relationships]
+ C --> C2[AutoHypergraph<br/>Multi-entity relationships]
+ C --> C3[AutoTemporalGraph<br/>+ Time]
+ C --> C4[AutoSpatialGraph<br/>+ Location]
+ C --> C5[AutoSpatioTemporalGraph<br/>+ Time + Location]
```
---
-## Scalar Types
+## Record Types
+
+For **recording and storing data** without relationships between entities.
+
+Record types extract **independent data items**, where each item does not contain information about its relationship to other items.
### AutoModel
-**Purpose**: Single structured object
+**Purpose**: Extract a single structured object
+
+**Think of it as**: A form with fields you want to fill in
+
+**Example use cases**:
+
+- Company earnings report (revenue, profit, growth)
+- Product specification (name, price, features)
+- Person profile (name, birth date, occupation)
-**Use When**:
-- Extracting a summary/report
-- Structured data with known fields
-- Single entity with many attributes
+**Example output structure**:
-**Example Output**:
-```python
+```json
{
"company_name": "Tesla Inc",
"revenue": 81.46,
- "eps": 4.07,
"employees": 127855
}
```
-**Common Templates**:
-- `finance/earnings_summary`
-- `general/base_model`
+**Common templates**: `finance/earnings_summary`, `general/model`
---
### AutoList
-**Purpose**: Ordered collection
+**Purpose**: Extract an ordered collection
-**Use When**:
-- Sequence matters
-- Ranked items
-- Timeline events (simple)
+**Think of it as**: A ranked list or sequence
-**Example Output**:
-```python
+**Example use cases**:
+
+- Top 10 movies of all time
+- Step-by-step procedures
+- Timeline events (simple chronological list)
+
+**Example output structure**:
+
+```json
{
"items": [
- {"name": "AC Motor", "year": 1888},
{"name": "Tesla Coil", "year": 1891},
{"name": "Radio", "year": 1898}
]
}
```
-**Common Templates**:
-- `general/base_list`
-- `legal/compliance_list`
+**Key property**: Order matters - items are in sequence
+
+**Common templates**: `general/list`, `legal/compliance_list`
---
### AutoSet
-**Purpose**: Deduplicated collection
+**Purpose**: Extract unique items (no duplicates)
+
+**Think of it as**: A bag of unique tags
+
+**Example use cases**:
+
+- Keywords from a document
+- Categories or tags
+- Skill sets
-**Use When**:
-- Unique items only
-- Tags/categories
-- Membership testing
+**Example output structure**:
-**Example Output**:
-```python
+```json
{
- "items": [
- "Electrical Engineering",
- "Physics",
- "Invention",
- "Renewable Energy"
- ]
+ "items": ["Electrical Engineering", "Physics", "Invention"]
}
```
-**Common Templates**:
-- `general/base_set`
-- `finance/risk_factor_set`
+**Key property**: Duplicates are automatically removed
+
+**Common templates**: `general/set`, `finance/risk_factor_set`
---
## Graph Types
-### AutoGraph
+For representing **relationships between entities**. Graph types include both the entities themselves (nodes) and the connections between them (edges).
+
+Graph types are divided into subtypes based on relationship complexity and additional dimensional information:
+
+### Basic Graphs
+
+#### AutoGraph
+
+**Purpose**: Extract binary relationships (two entities at a time)
-**Purpose**: Entity-relationship network
+**Think of it as**: A social network diagram
-**Use When**:
-- People, organizations, concepts
-- Binary relationships
-- Knowledge graphs
+**Example use cases**:
-**Example Output**:
-```python
+- People and their connections (worked with, married to)
+- Concepts and their relationships (is-a, part-of)
+- Organizations and interactions
+
+**Example output structure**:
+
+```json
{
"nodes": [
{"name": "Tesla", "type": "person"},
- {"name": "Edison", "type": "person"},
{"name": "AC Motor", "type": "invention"}
],
"edges": [
- {"source": "Tesla", "target": "AC Motor", "type": "invented"},
- {"source": "Tesla", "target": "Edison", "type": "rivals"}
+ {"source": "Tesla", "target": "AC Motor", "type": "invented"}
]
}
```
-**Common Templates**:
-- `general/knowledge_graph`
-- `general/biography_graph`
+**Key property**: Every relationship connects exactly two entities
+
+**Common templates**: `general/graph`, `general/biography_graph`
---
-### AutoHypergraph
+#### AutoHypergraph
+
+**Purpose**: Extract relationships involving 3+ entities
-**Purpose**: Multi-entity relationships
+**Think of it as**: A project team where multiple people collaborate
-**Use When**:
-- Relationships involve 3+ entities
-- Complex interactions
-- N-ary associations
+**Example use cases**:
-**Example Output**:
-```python
+- Multi-party collaborations
+- Complex interactions (buyer, seller, broker)
+- Group memberships
+
+**Example output structure**:
+
+```json
{
"nodes": [...],
"edges": [
{
"entities": ["Tesla", "Westinghouse", "Niagara"],
- "type": "collaboration",
- "description": "Power plant project"
+ "type": "collaboration"
}
]
}
```
-**Common Templates**:
-- `general/base_hypergraph`
+**Key property**: One "edge" can connect multiple entities
+
+**Common template**: `general/base_hypergraph`
---
-## Temporal Types
+### Enhanced Graphs (with dimensional information)
-### AutoTemporalGraph
+Built on basic graphs with added **time** or **space** dimensions for richer relationship descriptions.
-**Purpose**: Graph + time information
+#### AutoTemporalGraph (Temporal Graph)
-**Use When**:
-- Timeline is important
-- Event sequences
+**Purpose**: Extract relationships with time information
+
+**Think of it as**: A timeline with connections
+
+**Example use cases**:
+
+- Biographies (life events with dates)
+- Project histories
- Historical analysis
-**Example Output**:
-```python
+**Example output structure**:
+
+```json
{
- "nodes": [...],
"edges": [
{
"source": "Tesla",
"target": "AC Motor",
"type": "invented",
"time": "1888"
- },
- {
- "source": "Tesla",
- "target": "Wardenclyffe Tower",
- "type": "built",
- "time": "1901-1902"
}
]
}
```
-**Common Templates**:
-- `general/base_temporal_graph`
-- `finance/event_timeline`
+**Key property**: Every relationship has a time component
+
+**Common templates**: `general/base_temporal_graph`, `finance/event_timeline`
---
-### AutoSpatialGraph
+#### AutoSpatialGraph (Spatial Graph)
-**Purpose**: Graph + location information
+**Purpose**: Extract relationships with location information
-**Use When**:
-- Geographic data
-- Location-based analysis
-- Mapping
+**Think of it as**: A map with connections
-**Example Output**:
-```python
+**Example use cases**:
+
+- Travel logs
+- Geographic networks
+- Location-based asset tracking
+
+**Example output structure**:
+
+```json
{
"entities": [
- {
- "name": "Colorado Springs",
- "type": "location",
- "coordinates": "38.8339,-104.8214"
- }
+ {"name": "Colorado Springs", "location": "38.83,-104.82"}
],
"relations": [
{
"source": "Tesla",
"target": "Colorado Springs",
- "type": "conducted_experiments",
- "location": "Colorado Springs"
+ "type": "conducted_experiments"
}
]
}
```
-**Common Templates**:
-- `general/base_spatial_graph`
+**Key property**: Entities or relationships have geographic coordinates
+
+**Common template**: `general/base_spatial_graph`
---
-### AutoSpatioTemporalGraph
+#### AutoSpatioTemporalGraph (Spatio-Temporal Graph)
+
+**Purpose**: Extract relationships with both time and location
-**Purpose**: Graph + time + space
+**Think of it as**: A historical map with dated events
-**Use When**:
-- Full context needed
-- Historical geography
-- Event analysis with when and where
+**Example use cases**:
-**Example Output**:
-```python
+- Military history (battles with when and where)
+- Epidemic tracking
+- Historical migrations
+
+**Example output structure**:
+
+```json
{
- "entities": [...],
"relations": [
{
"source": "Tesla",
"target": "AC Motor",
"type": "demonstrated",
"time": "1888",
- "location": "Pittsburgh",
- "description": "Demonstration at Westinghouse"
+ "location": "Pittsburgh"
}
]
}
```
-**Common Templates**:
-- `general/base_spatio_temporal_graph`
+**Key property**: Complete context - who, what, when, and where
+
+**Common template**: `general/base_spatio_temporal_graph`
---
@@ -287,78 +313,69 @@ graph TD
```
What do you need to extract?
│
-├─ Single structured object → AutoModel
+├─ Single structured object (like a form)
+│ └─ AutoModel
│
├─ Collection of items
-│ ├─ Ordered/Ranked → AutoList
-│ └─ Unique/Tags → AutoSet
+│ ├─ Order matters? → AutoList
+│ └─ Just unique items? → AutoSet
│
-└─ Relationships
- ├─ Simple (binary)
- │ ├─ With time → AutoTemporalGraph
- │ ├─ With space → AutoSpatialGraph
- │ ├─ With both → AutoSpatioTemporalGraph
- │ └─ Neither → AutoGraph
- │
- └─ Complex (multi-entity)
- └─ AutoHypergraph
+└─ Relationships between entities → Graph Types
+ ├─ Relationship arity
+ │ ├─ Binary (2 entities) → Basic Graphs
+ │ │ ├─ Need time info? → AutoTemporalGraph
+ │ │ ├─ Need location info? → AutoSpatialGraph
+ │ │ ├─ Need both? → AutoSpatioTemporalGraph
+ │ │ └─ Neither? → AutoGraph
+ │ │
+ │ └─ Multi-entity (3+ entities) → AutoHypergraph
```
### By Use Case
-| Use Case | Recommended Type |
-|----------|------------------|
-| Company report | AutoModel |
-| Top 10 list | AutoList |
-| Tags/keywords | AutoSet |
-| People network | AutoGraph |
-| Project teams | AutoHypergraph |
-| Biography timeline | AutoTemporalGraph |
-| Travel log | AutoSpatialGraph |
-| Historical events | AutoSpatioTemporalGraph |
+| Use Case | Auto-Type | Why |
+|----------|-----------|-----|
+| Company financial report | AutoModel | Single structured summary |
+| Top 10 list | AutoList | Ordered/ranked items |
+| Keywords/tags | AutoSet | Unique collection |
+| People network | AutoGraph | Binary relationships |
+| Project teams | AutoHypergraph | Multi-person collaborations |
+| Biography timeline | AutoTemporalGraph | Events with dates |
+| Travel itinerary | AutoSpatialGraph | Places with connections |
+| Historical events | AutoSpatioTemporalGraph | Full context needed |
+
+### Quick Reference
+
+#### Record Types
+
+| Auto-Type | Output Shape | Key Feature |
+|-----------|--------------|-------------|
+| AutoModel | Single object | Fixed schema fields |
+| AutoList | Array | Maintains order |
+| AutoSet | Array | Deduplicates |
+
+#### Graph Types
+
+| Auto-Type | Output Shape | Key Feature |
+|-----------|--------------|-------------|
+| AutoGraph | Nodes + Edges | Binary relations (2 entities) |
+| AutoHypergraph | Nodes + Hyperedges | Multi-entity relations (3+ entities) |
+| AutoTemporalGraph | Nodes + Time-Edges | Binary relations + time dimension |
+| AutoSpatialGraph | Nodes + Geo-Edges | Binary relations + geographic dimension |
+| AutoSpatioTemporalGraph | Nodes + Spatio-Temporal-Edges | Binary relations + time + space |
---
-## Common Operations
-
-All Auto-Types support:
-
-```python
-# Extraction
-result = ka.parse(text)
-
-# Incremental update
-result.feed_text(more_text)
-
-# Build index (required for search, chat, and interactive visualization)
-result.build_index()
+## Next Steps
-# Search
-results = result.search("query")
+Ready to use Auto-Types? Choose your path:
-# Chat
-response = result.chat("question")
-
-# Visualization (interactive with search/chat capabilities)
-result.show()
-
-# Persistence
-result.dump("./path/")
-result.load("./path/")
-
-# Check empty
-if result.empty():
- print("No data")
-
-# Clear
-result.clear()
-result.clear_index()
-```
-
----
+**Quick Start**: Use built-in [Templates](../templates/index.md) — no Auto-Type knowledge needed
-## See Also
+**More Control**: Learn how to work with Auto-Types in Python:
+- [Working with Auto-Types](../python/guides/working-with-autotypes.md) — practical examples
+- [Python SDK Quickstart](../python/quickstart.md) — get started in 5 minutes
-- [Working with Auto-Types](../python/guides/working-with-autotypes.md)
-- [Template Library](../templates/index.md)
-- [Methods](methods.md)
+**Advanced**: Create custom Auto-Type configurations
+- [Creating Custom Templates](../python/guides/custom-templates.md)
+- [API Reference](../python/api-reference/autotypes/base.md)
diff --git a/docs/en/concepts/index.md b/docs/en/concepts/index.md
index c34f8d4..70d0be1 100644
--- a/docs/en/concepts/index.md
+++ b/docs/en/concepts/index.md
@@ -42,9 +42,8 @@ graph TD
The 8 data structure types that define extraction output:
-- **Scalar Types**: AutoModel, AutoList, AutoSet
-- **Graph Types**: AutoGraph, AutoHypergraph
-- **Temporal Types**: AutoTemporalGraph, AutoSpatialGraph, AutoSpatioTemporalGraph
+- **Record Types**: AutoModel, AutoList, AutoSet (store data, no entity relations)
+- **Graph Types**: AutoGraph, AutoHypergraph, AutoTemporalGraph, AutoSpatialGraph, AutoSpatioTemporalGraph (represent entity relationships)
→ [Learn about Auto-Types](autotypes.md)
diff --git a/docs/en/concepts/methods.md b/docs/en/concepts/methods.md
index e876037..7541ad8 100644
--- a/docs/en/concepts/methods.md
+++ b/docs/en/concepts/methods.md
@@ -15,6 +15,18 @@ Methods are the underlying algorithms that extract knowledge from text. They det
## Method Categories
+### Typical Methods
+
+**Direct extraction** without retrieval.
+
+**Best for**: Smaller documents, direct extraction
+
+```mermaid
+graph LR
+ A[Document] --> B[LLM Processing]
+ B --> C[Extract Structure]
+```
+
### RAG-Based Methods
**Retrieval-Augmented Generation** combines information retrieval with text generation.
@@ -29,16 +41,102 @@ graph LR
D --> E[Extract Structure]
```
-### Typical Methods
+---
-**Direct extraction** without retrieval.
+## Typical Methods
-**Best for**: Smaller documents, direct extraction
+### itext2kg
-```mermaid
-graph LR
- A[Document] --> B[LLM Processing]
- B --> C[Extract Structure]
+**Description**: High-quality triple-based extraction
+
+**Characteristics**:
+
+- Optimized for triple quality
+- Iterative refinement
+- Good for knowledge abstract construction
+
+**Best for**:
+
+- Knowledge graph construction
+- High-quality requirements
+- Triple extraction
+
+**Usage**:
+
+```python
+ka = Template.create("method/itext2kg")
+```
+
+---
+
+### itext2kg_star
+
+**Description**: Enhanced iText2KG
+
+**Characteristics**:
+
+- Improved extraction quality
+- Better handling of complex cases
+- Enhanced entity linking
+
+**Best for**:
+
+- When quality is critical
+- Complex extraction scenarios
+- Production systems
+
+**Usage**:
+
+```python
+ka = Template.create("method/itext2kg_star")
+```
+
+---
+
+### kg_gen
+
+**Description**: Knowledge Graph Generator
+
+**Characteristics**:
+
+- Configurable generation
+- Flexible schema
+- Fast processing
+
+**Best for**:
+
+- Custom schemas
+- Rapid prototyping
+- Flexible requirements
+
+**Usage**:
+
+```python
+ka = Template.create("method/kg_gen")
+```
+
+---
+
+### atom
+
+**Description**: Temporal knowledge graph with evidence
+
+**Characteristics**:
+
+- Temporal fact extraction
+- Evidence attribution
+- Confidence scoring
+
+**Best for**:
+
+- Temporal analysis
+- Fact verification
+- Timeline extraction
+
+**Usage**:
+
+```python
+ka = Template.create("method/atom")
```
---
@@ -50,12 +148,14 @@ graph LR
**Description**: Lightweight Graph-based RAG
**Characteristics**:
+
- Fastest RAG method
- Binary edges (source → target)
- Good balance of speed/quality
- Suitable for most use cases
**Best for**:
+
- General-purpose extraction
- Medium to large documents
- Quick results
@@ -72,12 +172,14 @@ ka = Template.create("method/light_rag")
**Description**: Graph-RAG with Community Detection
**Characteristics**:
+
- Community detection for organization
- Hierarchical summaries
- Best for very large documents
- Slower but thorough
**Best for**:
+
- Very large documents (books, long papers)
- Complex topic structures
- Research papers
@@ -94,11 +196,13 @@ ka = Template.create("method/graph_rag")
**Description**: Hypergraph-based RAG
**Characteristics**:
+
- N-ary hyperedges (2+ entities)
- Captures complex relationships
- Richer graph structure
**Best for**:
+
- Multi-party relationships
- Project collaborations
- Complex organizational structures
@@ -115,14 +219,17 @@ ka = Template.create("method/hyper_rag")
**Description**: Advanced Hypergraph RAG
**Characteristics**:
+
- Enhanced hypergraph capabilities
- Advanced relationship modeling
**Best for**:
+
- Complex hypergraph scenarios
- Advanced relationship analysis
**Usage**:
+
```python
ka = Template.create("method/hypergraph_rag")
```
@@ -134,102 +241,19 @@ ka = Template.create("method/hypergraph_rag")
**Description**: Cognitive RAG
**Characteristics**:
+
- Cognitive retrieval mechanisms
- Reasoning-focused
**Best for**:
+
- Reasoning tasks
- Question-answering systems
**Usage**:
-```python
-ka = Template.create("method/cog_rag")
-```
-
----
-
-## Typical Methods
-
-### itext2kg
-
-**Description**: High-quality triple-based extraction
-
-**Characteristics**:
-- Optimized for triple quality
-- Iterative refinement
-- Good for knowledge base construction
-
-**Best for**:
-- Knowledge graph construction
-- High-quality requirements
-- Triple extraction
-**Usage**:
```python
-ka = Template.create("method/itext2kg")
-```
-
----
-
-### itext2kg_star
-
-**Description**: Enhanced iText2KG
-
-**Characteristics**:
-- Improved extraction quality
-- Better handling of complex cases
-- Enhanced entity linking
-
-**Best for**:
-- When quality is critical
-- Complex extraction scenarios
-- Production systems
-
-**Usage**:
-```python
-ka = Template.create("method/itext2kg_star")
-```
-
----
-
-### kg_gen
-
-**Description**: Knowledge Graph Generator
-
-**Characteristics**:
-- Configurable generation
-- Flexible schema
-- Fast processing
-
-**Best for**:
-- Custom schemas
-- Rapid prototyping
-- Flexible requirements
-
-**Usage**:
-```python
-ka = Template.create("method/kg_gen")
-```
-
----
-
-### atom
-
-**Description**: Temporal knowledge graph with evidence
-
-**Characteristics**:
-- Temporal fact extraction
-- Evidence attribution
-- Confidence scoring
-
-**Best for**:
-- Temporal analysis
-- Fact verification
-- Timeline extraction
-
-**Usage**:
-```python
-ka = Template.create("method/atom")
+ka = Template.create("method/cog_rag")
```
---
@@ -271,12 +295,13 @@ ka = Template.create("method/atom")
| Method | Speed | Quality | Memory | Best For |
|--------|-------|---------|--------|----------|
+| itext2kg | ⭐⭐⭐ | ⭐⭐⭐ | ⭐ | Quality focused |
+| itext2kg_star | ⭐⭐⭐ | ⭐⭐⭐ | ⭐ | Production quality |
+| kg_gen | ⭐⭐⭐ | ⭐⭐ | ⭐ | Flexibility |
+| atom | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ | Temporal data |
| light_rag | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ | General use |
| graph_rag | ⭐ | ⭐⭐⭐ | ⭐⭐⭐ | Large docs |
| hyper_rag | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | Complex relations |
-| itext2kg | ⭐⭐⭐ | ⭐⭐⭐ | ⭐ | Quality focused |
-| atom | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ | Temporal data |
-| kg_gen | ⭐⭐⭐ | ⭐⭐ | ⭐ | Flexibility |
---
@@ -295,6 +320,6 @@ for name, info in methods.items():
## See Also
-- [Choosing Methods Guide](../python/guides/choosing-methods.md)
+- [Using Methods Guide](../python/guides/using-methods.md)
- [Templates](../templates/index.md)
- [Auto-Types](autotypes.md)
diff --git a/docs/en/getting-started/cli-quickstart.md b/docs/en/getting-started/cli-quickstart.md
index c7b542d..3b11a88 100644
--- a/docs/en/getting-started/cli-quickstart.md
+++ b/docs/en/getting-started/cli-quickstart.md
@@ -84,6 +84,7 @@ Template resolved: Biography Graph Template
What's next?
he show ./output/ # Visualize knowledge graph
+ he feed ./output/ <new_document> # Append more documents
he search ./output/ "keyword" # Semantic search
he talk ./output/ -i # Interactive chat
```
@@ -104,7 +105,7 @@ This opens an interactive visualization in your browser, showing:
---
-## Step 5: Search Your Knowledge Base
+## Step 5: Search Your Knowledge Abstract
```bash
he search ./output/ "What were Tesla's major inventions?"
diff --git a/docs/en/getting-started/python-quickstart.md b/docs/en/getting-started/python-quickstart.md
index 0da4a1b..48472aa 100644
--- a/docs/en/getting-started/python-quickstart.md
+++ b/docs/en/getting-started/python-quickstart.md
@@ -95,6 +95,8 @@ result.build_index()
result.show()
```
+![Knowledge Graph Visualization](../../assets/en_show.png)
+
---
## Step 4: Run the Script
@@ -131,7 +133,7 @@ for node in result.nodes:
for edge in result.edges:
print(f"- {edge.source} --{edge.type}--> {edge.target}")
-# Search within the knowledge base
+# Search within the knowledge abstract
result.build_index()
nodes, edges = result.search("inventions", top_k=3)
for node in nodes:
@@ -144,15 +146,15 @@ for edge in edges:
## Step 6: Save and Load
-Save your knowledge base for later use:
+Save your knowledge abstract for later use:
```python
# Save to disk
-result.dump("./my_knowledge_base/")
+result.dump("./my_ka/")
# Load it back later
new_ka = Template.create("general/biography_graph", language="en")
-new_ka.load("./my_knowledge_base/")
+new_ka.load("./my_ka/")
```
---
@@ -177,6 +179,8 @@ result.build_index()
result.show()
```
+![Updated Knowledge Graph Visualization](../../assets/en_show.png)
+
---
## Complete Example
@@ -231,6 +235,9 @@ def main():
result.show()
print("\nDone!")
+```
+
+![Interactive Knowledge Graph Visualization](../../assets/en_show.png)
if __name__ == "__main__":
diff --git a/docs/en/index.md b/docs/en/index.md
index 450dfee..c66b38d 100644
--- a/docs/en/index.md
+++ b/docs/en/index.md
@@ -76,7 +76,7 @@
---
- Feed new documents to continuously expand your knowledge base. No need to reprocess everything.
+ Feed new documents to continuously expand your knowledge abstract. No need to reprocess everything.
</div>
@@ -94,7 +94,7 @@
- Quick knowledge extraction
- Batch document processing
- - Building knowledge bases without coding
+ - Building knowledge abstracts without coding
[:octicons-arrow-right-24: CLI Guide](cli/index.md)
diff --git a/docs/en/python/api-reference/autotypes.md b/docs/en/python/api-reference/autotypes.md
deleted file mode 100644
index 1c13560..0000000
--- a/docs/en/python/api-reference/autotypes.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# Auto-Types API
-
-## BaseAutoType
-
-::: hyperextract.types.BaseAutoType
- options:
- members:
- - parse
- - feed_text
- - search
- - chat
- - build_index
- - dump
- - load
- - show
- - empty
- - clear
- - data
- - data_schema
- - metadata
-
-## AutoModel
-
-::: hyperextract.types.AutoModel
- options:
- members: true
-
-## AutoList
-
-::: hyperextract.types.AutoList
- options:
- members: true
-
-## AutoSet
-
-::: hyperextract.types.AutoSet
- options:
- members: true
-
-## AutoGraph
-
-::: hyperextract.types.AutoGraph
- options:
- members: true
-
-## AutoHypergraph
-
-::: hyperextract.types.AutoHypergraph
- options:
- members: true
-
-## AutoTemporalGraph
-
-::: hyperextract.types.AutoTemporalGraph
- options:
- members: true
-
-## AutoSpatialGraph
-
-::: hyperextract.types.AutoSpatialGraph
- options:
- members: true
-
-## AutoSpatioTemporalGraph
-
-::: hyperextract.types.AutoSpatioTemporalGraph
- options:
- members: true
diff --git a/docs/en/python/api-reference/autotypes/base.md b/docs/en/python/api-reference/autotypes/base.md
new file mode 100644
index 0000000..bcf32de
--- /dev/null
+++ b/docs/en/python/api-reference/autotypes/base.md
@@ -0,0 +1,20 @@
+# Base Auto-Type
+
+Common interface shared by all extraction result types.
+
+---
+
+::: hyperextract.types.BaseAutoType
+ options:
+ members:
+ - parse
+ - feed_text
+ - search
+ - chat
+ - build_index
+ - dump
+ - load
+ - empty
+ - clear
+ - data
+ - data_schema
diff --git a/docs/en/python/api-reference/autotypes/graphs.md b/docs/en/python/api-reference/autotypes/graphs.md
new file mode 100644
index 0000000..f45d9df
--- /dev/null
+++ b/docs/en/python/api-reference/autotypes/graphs.md
@@ -0,0 +1,43 @@
+# Graph Types
+
+Auto-Types for representing relationships between entities.
+
+---
+
+## AutoGraph
+
+::: hyperextract.types.AutoGraph
+ options:
+ members: true
+
+---
+
+## AutoHypergraph
+
+::: hyperextract.types.AutoHypergraph
+ options:
+ members: true
+
+---
+
+## AutoTemporalGraph
+
+::: hyperextract.types.AutoTemporalGraph
+ options:
+ members: true
+
+---
+
+## AutoSpatialGraph
+
+::: hyperextract.types.AutoSpatialGraph
+ options:
+ members: true
+
+---
+
+## AutoSpatioTemporalGraph
+
+::: hyperextract.types.AutoSpatioTemporalGraph
+ options:
+ members: true
diff --git a/docs/en/python/api-reference/autotypes/structures.md b/docs/en/python/api-reference/autotypes/structures.md
new file mode 100644
index 0000000..2602a0a
--- /dev/null
+++ b/docs/en/python/api-reference/autotypes/structures.md
@@ -0,0 +1,27 @@
+# Record Types
+
+Auto-Types for recording and storing data without entity relationships.
+
+---
+
+## AutoModel
+
+::: hyperextract.types.AutoModel
+ options:
+ members: true
+
+---
+
+## AutoList
+
+::: hyperextract.types.AutoList
+ options:
+ members: true
+
+---
+
+## AutoSet
+
+::: hyperextract.types.AutoSet
+ options:
+ members: true
diff --git a/docs/en/python/api-reference/methods.md b/docs/en/python/api-reference/methods.md
deleted file mode 100644
index 3077767..0000000
--- a/docs/en/python/api-reference/methods.md
+++ /dev/null
@@ -1,136 +0,0 @@
-# Methods API
-
-API reference for extraction methods.
-
----
-
-## Registry Functions
-
-::: hyperextract.methods.registry
- options:
- members:
- - register_method
- - get_method
- - list_methods
- - get_method_cfg
- - list_method_cfgs
-
----
-
-## Method Configuration
-
-::: hyperextract.methods.registry.MethodCfg
- options:
- members: true
-
----
-
-## RAG-Based Methods
-
-### LightRAG
-
-::: hyperextract.methods.rag.Light_RAG
- options:
- members: true
-
-### GraphRAG
-
-::: hyperextract.methods.rag.Graph_RAG
- options:
- members: true
-
-### HyperRAG
-
-::: hyperextract.methods.rag.Hyper_RAG
- options:
- members: true
-
-### HyperGraphRAG
-
-::: hyperextract.methods.rag.HyperGraph_RAG
- options:
- members: true
-
-### CogRAG
-
-::: hyperextract.methods.rag.Cog_RAG
- options:
- members: true
-
----
-
-## Typical Methods
-
-### iText2KG
-
-::: hyperextract.methods.typical.iText2KG
- options:
- members: true
-
-### iText2KG_Star
-
-::: hyperextract.methods.typical.iText2KG_Star
- options:
- members: true
-
-### KG_Gen
-
-::: hyperextract.methods.typical.KG_Gen
- options:
- members: true
-
-### Atom
-
-::: hyperextract.methods.typical.Atom
- options:
- members: true
-
----
-
-## Using Methods Directly
-
-```python
-from hyperextract.methods import Light_RAG
-from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-
-# Create method instance
-llm = ChatOpenAI()
-emb = OpenAIEmbeddings()
-
-method = Light_RAG(
- llm_client=llm,
- embedder=emb
-)
-
-# Extract knowledge
-result = method.parse(text)
-```
-
----
-
-## Registering Custom Methods
-
-```python
-from hyperextract.methods import register_method
-
-class MyCustomMethod:
- def __init__(self, llm_client, embedder, **kwargs):
- self.llm_client = llm_client
- self.embedder = embedder
-
- def parse(self, text):
- # Your extraction logic
- pass
-
-# Register the method
-register_method(
- name="my_method",
- method_class=MyCustomMethod,
- autotype="graph",
- description="My custom extraction method"
-)
-
-# Use via Template API
-from hyperextract import Template
-ka = Template.create("method/my_method")
-```
diff --git a/docs/en/python/api-reference/methods/rag.md b/docs/en/python/api-reference/methods/rag.md
new file mode 100644
index 0000000..f9519f4
--- /dev/null
+++ b/docs/en/python/api-reference/methods/rag.md
@@ -0,0 +1,43 @@
+# RAG-Based Methods
+
+Retrieval-Augmented Generation methods for large-document extraction.
+
+---
+
+## LightRAG
+
+::: hyperextract.methods.rag.Light_RAG
+ options:
+ members: true
+
+---
+
+## GraphRAG
+
+::: hyperextract.methods.rag.Graph_RAG
+ options:
+ members: true
+
+---
+
+## HyperRAG
+
+::: hyperextract.methods.rag.Hyper_RAG
+ options:
+ members: true
+
+---
+
+## HyperGraphRAG
+
+::: hyperextract.methods.rag.HyperGraph_RAG
+ options:
+ members: true
+
+---
+
+## CogRAG
+
+::: hyperextract.methods.rag.Cog_RAG
+ options:
+ members: true
diff --git a/docs/en/python/api-reference/methods/registry.md b/docs/en/python/api-reference/methods/registry.md
new file mode 100644
index 0000000..7d51948
--- /dev/null
+++ b/docs/en/python/api-reference/methods/registry.md
@@ -0,0 +1,24 @@
+# Method Registry
+
+Registry functions and configuration for extraction methods.
+
+---
+
+## Registry Functions
+
+::: hyperextract.methods.registry
+ options:
+ members:
+ - register_method
+ - get_method
+ - list_methods
+ - get_method_cfg
+ - list_method_cfgs
+
+---
+
+## Method Configuration
+
+::: hyperextract.methods.registry.MethodCfg
+ options:
+ members: true
diff --git a/docs/en/python/api-reference/methods/typical.md b/docs/en/python/api-reference/methods/typical.md
new file mode 100644
index 0000000..7825be6
--- /dev/null
+++ b/docs/en/python/api-reference/methods/typical.md
@@ -0,0 +1,35 @@
+# Typical Methods
+
+Direct extraction methods that process text without retrieval.
+
+---
+
+## iText2KG
+
+::: hyperextract.methods.typical.iText2KG
+ options:
+ members: true
+
+---
+
+## iText2KG_Star
+
+::: hyperextract.methods.typical.iText2KG_Star
+ options:
+ members: true
+
+---
+
+## KG_Gen
+
+::: hyperextract.methods.typical.KG_Gen
+ options:
+ members: true
+
+---
+
+## Atom
+
+::: hyperextract.methods.typical.Atom
+ options:
+ members: true
diff --git a/docs/en/python/api-reference/template.md b/docs/en/python/api-reference/template.md
index 5fe4927..2d83205 100644
--- a/docs/en/python/api-reference/template.md
+++ b/docs/en/python/api-reference/template.md
@@ -1,6 +1,6 @@
# Template API
-::: hyperextract.utils.template_engine.Template
+::: hyperextract.Template
options:
members:
- create
diff --git a/docs/en/python/core-concepts.md b/docs/en/python/core-concepts.md
index 7b2acaa..65f0bdf 100644
--- a/docs/en/python/core-concepts.md
+++ b/docs/en/python/core-concepts.md
@@ -85,7 +85,7 @@ for path, cfg in templates.items():
from hyperextract import Template
# Graph extraction
-ka = Template.create("general/knowledge_graph", "en")
+ka = Template.create("general/graph", "en")
result = ka.parse(text)
# Access graph data
@@ -227,6 +227,8 @@ result.build_index()
result.show()
```
+![Interactive Visualization](../../assets/en_show.png)
+
### Method Approach (Advanced)
```python
@@ -243,15 +245,16 @@ result.build_index()
results = result.search("query")
```
-### Direct Auto-Type (Full Control)
+### Direct Auto-Type Usage (Advanced)
+
+For full control over extraction, you can instantiate Auto-Types directly. This requires defining your own schemas and extraction logic.
```python
from hyperextract import AutoGraph
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-
-# 1. Define schema
from pydantic import BaseModel
+# Define schemas
class Entity(BaseModel):
name: str
type: str
@@ -261,29 +264,34 @@ class Relation(BaseModel):
target: str
type: str
-class MyGraph(BaseModel):
- entities: list[Entity]
- relations: list[Relation]
-
-# 2. Create Auto-Type
+# Create with full control
llm = ChatOpenAI()
emb = OpenAIEmbeddings()
-ka = AutoGraph(
- data_schema=MyGraph,
+ka = AutoGraph[Entity, Relation](
+ node_schema=Entity,
+ edge_schema=Relation,
llm_client=llm,
- embedder=emb
+ embedder=emb,
+ # Plus additional configuration...
)
-# 3. Extract
result = ka.parse(text)
```
+!!! note "Advanced Topic"
+ Direct Auto-Type usage requires understanding of:
+ - Pydantic schema definitions
+ - LLM client configuration
+ - Key extractors for deduplication
+
+ See [Working with Auto-Types](guides/working-with-autotypes.md#advanced-usage) for complete examples.
+
---
## Next Steps
- [Using Templates](guides/using-templates.md)
-- [Choosing Methods](guides/choosing-methods.md)
+- [Using Methods](guides/using-methods.md)
- [Working with Auto-Types](guides/working-with-autotypes.md)
- [Auto-Types Reference](../concepts/autotypes.md)
diff --git a/docs/en/python/guides/custom-templates.md b/docs/en/python/guides/custom-templates.md
index 404747b..36fbf5b 100644
--- a/docs/en/python/guides/custom-templates.md
+++ b/docs/en/python/guides/custom-templates.md
@@ -1,5 +1,8 @@
# Creating Custom Templates
+!!! tip "Level 2+ - Intermediate Extension"
+ This guide shows how to create reusable templates. Before reading, complete [Level 1: Using Templates](using-templates.md) or [Level 2: Working with Auto-Types](working-with-autotypes.md).
+
Learn how to create your own templates for specialized extraction tasks.
---
@@ -289,6 +292,65 @@ display:
---
+## Using Method Classes Directly
+
+If you need full control over the extraction process, you can instantiate method classes directly instead of going through `Template.create`:
+
+```python
+from hyperextract.methods import Light_RAG
+from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+
+# Create method instance directly
+llm = ChatOpenAI()
+emb = OpenAIEmbeddings()
+
+method = Light_RAG(
+ llm_client=llm,
+ embedder=emb,
+ # Method-specific parameters
+ chunk_size=1024,
+ max_workers=5
+)
+
+# Extract knowledge
+result = method.parse(text)
+```
+
+This approach is useful for advanced scenarios where you want to bypass the Template layer and tune algorithm parameters directly.
+
+---
+
+## Registering Custom Methods
+
+You can also register custom extraction methods and use them through the Template API:
+
+```python
+from hyperextract.methods import register_method
+
+class MyCustomMethod:
+ def __init__(self, llm_client, embedder, **kwargs):
+ self.llm_client = llm_client
+ self.embedder = embedder
+
+ def parse(self, text):
+ # Your extraction logic
+ pass
+
+# Register the method
+register_method(
+ name="my_method",
+ method_class=MyCustomMethod,
+ autotype="graph",
+ description="My custom extraction method"
+)
+
+# Use via Template API
+from hyperextract import Template
+ka = Template.create("method/my_method")
+```
+
+---
+
## Sharing Templates
### Register Globally
@@ -344,6 +406,11 @@ python -c "import yaml; yaml.safe_load(open('template.yaml'))"
## See Also
+**Prerequisites:**
- [Template Format Reference](../../concepts/templates-format.md) — Complete YAML specification
-- [Using Templates](using-templates.md) — How to use templates in code
+- [Using Templates](using-templates.md) — Level 1: Basic template usage
+
+**Advanced Usage:**
+- [Incremental Updates](incremental-updates.md) — Add more documents
+- [Search and Chat](search-and-chat.md) — Use extracted knowledge
- [Template Library](../../templates/index.md) — Browse existing templates
diff --git a/docs/en/python/guides/incremental-updates.md b/docs/en/python/guides/incremental-updates.md
index 38942e9..def591e 100644
--- a/docs/en/python/guides/incremental-updates.md
+++ b/docs/en/python/guides/incremental-updates.md
@@ -1,12 +1,15 @@
# Incremental Updates
-Add new information to existing knowledge bases without reprocessing.
+!!! tip "Advanced - Post-Extraction"
+ This guide covers adding more documents after initial extraction. You should be comfortable with [Level 1: Using Templates](using-templates.md) first.
+
+Add new information to existing knowledge abstracts without reprocessing.
---
## Overview
-The `feed_text()` method allows you to incrementally add documents to an existing knowledge base:
+The `feed_text()` method allows you to incrementally add documents to an existing knowledge abstract:
1. **Preserves existing data** — Won't overwrite what's already there
2. **Intelligent merging** — Handles duplicates and conflicts
@@ -38,43 +41,45 @@ print(f"After feed: {len(result.nodes)} nodes")
```python
ka = Template.create("general/biography_graph", "en")
-kb = ka.parse(early_life_text)
+ka = ka.parse(early_life_text)
# Add career information
-kb.feed_text(career_text)
+ka.feed_text(career_text)
# Add later years
-kb.feed_text(later_years_text)
+ka.feed_text(later_years_text)
# Rebuild index after feeding new data
-kb.build_index()
+ka.build_index()
# Final result combines all periods (with interactive search/chat)
-kb.show()
+ka.show()
```
+![Interactive Visualization](../../../assets/en_show.png)
+
### Processing Multiple Documents
```python
ka = Template.create("general/concept_graph", "en")
-kb = ka.parse(documents[0])
+ka = ka.parse(documents[0])
for doc in documents[1:]:
- kb.feed_text(doc)
- print(f"Added document, now {len(kb.nodes)} nodes")
+ ka.feed_text(doc)
+ print(f"Added document, now {len(ka.nodes)} nodes")
```
### Updating with New Information
```python
# Original extraction
-kb = ka.parse(original_paper)
+ka = ka.parse(original_paper)
# Add corrections/updates
-kb.feed_text(corrections)
+ka.feed_text(corrections)
# Save updated version
-kb.dump("./updated_kb/")
+ka.dump("./updated_ka/")
```
---
@@ -112,8 +117,8 @@ Ensure you're using compatible Auto-Types:
```python
# Good: Same template type
-kb = ka.parse(text1) # biography_graph
-kb.feed_text(text2) # same type
+ka = ka.parse(text1) # biography_graph
+ka.feed_text(text2) # same type
# Be careful: Mixing types may cause issues
```
@@ -121,27 +126,27 @@ kb.feed_text(text2) # same type
### 2. Rebuild Index After Feeding
```python
-kb.feed_text(new_text)
-kb.build_index() # Required for search/chat
+ka.feed_text(new_text)
+ka.build_index() # Required for search/chat
```
### 3. Save Intermediate States
```python
# Save after major updates
-kb.feed_text(chapter1)
-kb.dump("./kb_v1/")
+ka.feed_text(chapter1)
+ka.dump("./kb_v1/")
-kb.feed_text(chapter2)
-kb.dump("./kb_v2/")
+ka.feed_text(chapter2)
+ka.dump("./kb_v2/")
```
### 4. Monitor Growth
```python
-initial_count = len(kb.nodes)
-kb.feed_text(new_text)
-new_count = len(kb.nodes)
+initial_count = len(ka.nodes)
+ka.feed_text(new_text)
+new_count = len(ka.nodes)
print(f"Added {new_count - initial_count} new nodes")
```
@@ -151,7 +156,7 @@ print(f"Added {new_count - initial_count} new nodes")
## Complete Example
```python
-"""Build a knowledge base incrementally from multiple sources."""
+"""Build a knowledge abstract incrementally from multiple sources."""
from hyperextract import Template
from pathlib import Path
@@ -168,27 +173,27 @@ def build_knowledge_base(source_dir, output_dir):
# Initial extraction from first file
print(f"Processing {files[0].name}...")
- kb = ka.parse(files[0].read_text())
+ ka = ka.parse(files[0].read_text())
# Feed remaining files
for file in files[1:]:
print(f"Adding {file.name}...")
- kb.feed_text(file.read_text())
- print(f" Now {len(kb.nodes)} nodes")
+ ka.feed_text(file.read_text())
+ print(f" Now {len(ka.nodes)} nodes")
# Build index for search/chat
print("Building search index...")
- kb.build_index()
+ ka.build_index()
# Save
print(f"Saving to {output_dir}...")
- kb.dump(output_dir)
+ ka.dump(output_dir)
print("Done!")
- return kb
+ return ka
# Usage
-kb = build_knowledge_base("./sources/", "./combined_kb/")
+ka = build_knowledge_base("./sources/", "./combined_ka/")
```
---
@@ -197,8 +202,8 @@ kb = build_knowledge_base("./sources/", "./combined_kb/")
| Operation | Use When | Result |
|-----------|----------|--------|
-| `parse()` | Starting fresh | New knowledge base |
-| `feed_text()` | Adding to existing | Updated knowledge base |
+| `parse()` | Starting fresh | New knowledge abstract |
+| `feed_text()` | Adding to existing | Updated knowledge abstract |
### Chaining Operations
@@ -217,12 +222,12 @@ result1.feed_text(text2) # result1 is updated
### 1. Memory Usage
-Large knowledge bases consume memory:
+Large knowledge abstracts consume memory:
```python
# Monitor size
import sys
-size = sys.getsizeof(kb.data)
+size = sys.getsizeof(ka.data)
print(f"Knowledge base size: {size} bytes")
```
@@ -230,15 +235,15 @@ print(f"Knowledge base size: {size} bytes")
Merging isn't perfect:
- Similar but not identical entities may not merge
-- Very large knowledge bases may slow down
+- Very large knowledge abstracts may slow down
### 3. Index Staleness
Always rebuild after feeding:
```python
-kb.feed_text(text)
-kb.build_index() # Don't forget!
+ka.feed_text(text)
+ka.build_index() # Don't forget!
```
---
@@ -252,8 +257,8 @@ Process in smaller batches:
```python
for batch in chunks(documents, batch_size=5):
for doc in batch:
- kb.feed_text(doc)
- kb.dump(f"./kb_checkpoint/") # Save periodically
+ ka.feed_text(doc)
+ ka.dump(f"./kb_checkpoint/") # Save periodically
```
### "Duplicate entities"
@@ -269,13 +274,17 @@ Normalize entity names in your text:
```python
# Forgot to rebuild?
-kb.build_index()
+ka.build_index()
```
---
## See Also
-- [Saving and Loading](saving-loading.md)
-- [Search and Chat](search-and-chat.md)
-- [Working with Auto-Types](working-with-autotypes.md)
+**Related Workflows:**
+- [Search and Chat](search-and-chat.md) — Query your updated knowledge
+- [Saving and Loading](saving-loading.md) — Persist merged results
+
+**Basics:**
+- [Using Templates](using-templates.md) — Level 1 fundamentals
+- [Working with Auto-Types](working-with-autotypes.md) — Level 2 customization
diff --git a/docs/en/python/guides/saving-loading.md b/docs/en/python/guides/saving-loading.md
index 19800a3..30f91ef 100644
--- a/docs/en/python/guides/saving-loading.md
+++ b/docs/en/python/guides/saving-loading.md
@@ -1,6 +1,7 @@
# Saving and Loading
-Persist knowledge bases to disk and restore them later.
+!!! tip "Advanced - Post-Extraction"
+ This guide covers persisting extracted knowledge. You should be comfortable with [Level 1: Using Templates](using-templates.md) first.
---
@@ -13,7 +14,7 @@ Hyper-Extract provides serialization for:
---
-## Saving Knowledge Bases
+## Saving Knowledge Abstracts
### Basic Save
@@ -24,13 +25,13 @@ ka = Template.create("general/biography_graph", "en")
result = ka.parse(text)
# Save to directory
-result.dump("./my_kb/")
+result.dump("./my_ka/")
```
### Save Structure
```
-./my_kb/
+./my_ka/
├── data.json # Extracted knowledge
├── metadata.json # Extraction info
└── index/ # Search index (if built)
@@ -45,12 +46,12 @@ result.dump("./my_kb/")
result.build_index()
# Then save
-result.dump("./my_kb/")
+result.dump("./my_ka/")
```
---
-## Loading Knowledge Bases
+## Loading Knowledge Abstracts
### Basic Load
@@ -61,7 +62,7 @@ from hyperextract import Template
ka = Template.create("general/biography_graph", "en")
# Load saved data
-ka.load("./my_kb/")
+ka.load("./my_ka/")
# Use
print(f"Loaded {len(ka.nodes)} nodes")
@@ -70,7 +71,7 @@ print(f"Loaded {len(ka.nodes)} nodes")
### Verify Loaded Data
```python
-ka.load("./my_kb/")
+ka.load("./my_ka/")
# Check it's not empty
if ka.empty():
@@ -99,14 +100,14 @@ ka2.load("./research_paper_kb/")
response = ka2.chat("What are the main findings?")
```
-### Sharing Knowledge Bases
+### Sharing Knowledge Abstracts
```python
# Save to shared location
-result.dump("/shared/kb/project_x/")
+result.dump("/shared/ka/project_x/")
# Others can load
-ka.load("/shared/kb/project_x/")
+ka.load("/shared/ka/project_x/")
```
### Backup and Versioning
@@ -128,20 +129,20 @@ result.dump("./kb_v2/")
## Working with the Filesystem
-### Checking for Existing KB
+### Checking for Existing KA
```python
from pathlib import Path
-kb_path = Path("./my_kb/")
+ka_path = Path("./my_ka/")
-if kb_path.exists() and (kb_path / "data.json").exists():
+if ka_path.exists() and (ka_path / "data.json").exists():
print("Knowledge base exists, loading...")
- ka.load(kb_path)
+ ka.load(ka_path)
else:
- print("Creating new knowledge base...")
+ print("Creating new knowledge abstract...")
result = ka.parse(text)
- result.dump(kb_path)
+ result.dump(ka_path)
```
### Listing Saved KBs
@@ -150,7 +151,7 @@ else:
import os
kb_dirs = [d for d in os.listdir("./") if os.path.isdir(d) and "_kb" in d]
-print("Available knowledge bases:", kb_dirs)
+print("Available knowledge abstracts:", kb_dirs)
```
### Moving/Copying
@@ -158,10 +159,10 @@ print("Available knowledge bases:", kb_dirs)
```python
import shutil
-# Copy knowledge base
+# Copy knowledge abstract
shutil.copytree("./kb_v1/", "./kb_backup/")
-# Move knowledge base
+# Move knowledge abstract
shutil.move("./old_location/", "./new_location/")
```
@@ -172,7 +173,7 @@ shutil.move("./old_location/", "./new_location/")
### Accessing Metadata
```python
-result.dump("./my_kb/")
+result.dump("./my_ka/")
# Metadata is saved automatically
# Contents:
@@ -189,7 +190,7 @@ result.dump("./my_kb/")
result.metadata["project"] = "Research Project X"
result.metadata["version"] = "1.0"
-result.dump("./my_kb/")
+result.dump("./my_ka/")
```
---
@@ -197,7 +198,7 @@ result.dump("./my_kb/")
## Complete Example
```python
-"""Manage knowledge bases with save/load."""
+"""Manage knowledge abstracts with save/load."""
from hyperextract import Template
from pathlib import Path
@@ -208,32 +209,32 @@ class KnowledgeBaseManager:
self.storage_dir = Path(storage_dir)
self.storage_dir.mkdir(exist_ok=True)
- def save(self, kb, name):
- """Save knowledge base."""
- kb_path = self.storage_dir / name
- kb.dump(kb_path)
- print(f"Saved to {kb_path}")
- return kb_path
+ def save(self, ka, name):
+ """Save knowledge abstract."""
+ ka_path = self.storage_dir / name
+ ka.dump(ka_path)
+ print(f"Saved to {ka_path}")
+ return ka_path
def load(self, name, template="general/biography_graph", lang="en"):
- """Load knowledge base."""
- kb_path = self.storage_dir / name
+ """Load knowledge abstract."""
+ ka_path = self.storage_dir / name
- if not kb_path.exists():
+ if not ka_path.exists():
raise FileNotFoundError(f"Knowledge base not found: {name}")
ka = Template.create(template, lang)
- ka.load(kb_path)
+ ka.load(ka_path)
return ka
def list(self):
- """List available knowledge bases."""
+ """List available knowledge abstracts."""
return [d.name for d in self.storage_dir.iterdir() if d.is_dir()]
def info(self, name):
- """Get knowledge base info."""
- kb_path = self.storage_dir / name
- meta_path = kb_path / "metadata.json"
+ """Get knowledge abstract info."""
+ ka_path = self.storage_dir / name
+ meta_path = ka_path / "metadata.json"
if meta_path.exists():
return json.loads(meta_path.read_text())
@@ -251,8 +252,8 @@ manager.save(result, "tesla_biography")
print(manager.list()) # ['tesla_biography']
# Load
-kb = manager.load("tesla_biography")
-print(kb.chat("What did Tesla invent?"))
+ka = manager.load("tesla_biography")
+print(ka.chat("What did Tesla invent?"))
```
---
@@ -267,16 +268,16 @@ ka = Template.create("general/biography_graph", "en")
# Load with same template
ka2 = Template.create("general/biography_graph", "en")
-ka2.load("./kb/")
+ka2.load("./ka/")
```
### 2. Build Index After Loading
```python
-ka.load("./kb/")
+ka.load("./ka/")
# Check if index exists, otherwise rebuild
-index_path = Path("./kb/") / "index"
+index_path = Path("./ka/") / "index"
if not index_path.exists():
ka.build_index()
```
@@ -285,9 +286,9 @@ if not index_path.exists():
```python
try:
- ka.load("./kb/")
+ ka.load("./ka/")
if ka.empty():
- print("Warning: Empty knowledge base")
+ print("Warning: Empty knowledge abstract")
except FileNotFoundError:
print("Knowledge base not found")
```
@@ -296,10 +297,10 @@ except FileNotFoundError:
```python
# Good
-result.dump("./kb/tesla_2024_01_15/")
+result.dump("./ka/tesla_2024_01_15/")
# Avoid
-result.dump("./kb/temp/")
+result.dump("./ka/temp/")
```
---
@@ -311,9 +312,9 @@ result.dump("./kb/temp/")
```python
from pathlib import Path
-kb_path = Path("./my_kb/")
-if not kb_path.exists():
- print(f"Directory not found: {kb_path}")
+ka_path = Path("./my_ka/")
+if not ka_path.exists():
+ print(f"Directory not found: {ka_path}")
print(f"Available: {list(Path('.').glob('*/'))}")
```
@@ -322,17 +323,17 @@ if not kb_path.exists():
```python
# Check data file
import json
-data = json.load(open("./my_kb/data.json"))
+data = json.load(open("./my_ka/data.json"))
print(f"Keys: {data.keys()}")
```
### "Index not loaded"
```python
-ka.load("./kb/")
+ka.load("./ka/")
# Check if index exists
-if (Path("./kb/") / "index").exists():
+if (Path("./ka/") / "index").exists():
print("Index directory exists")
else:
print("No index, building...")
@@ -343,6 +344,10 @@ else:
## See Also
-- [Incremental Updates](incremental-updates.md)
-- [Search and Chat](search-and-chat.md)
-- [CLI `he parse` command](../../cli/commands/parse.md)
+**Related Workflows:**
+- [Incremental Updates](incremental-updates.md) — Add more content
+- [Search and Chat](search-and-chat.md) — Use loaded knowledge
+
+**Basics:**
+- [Using Templates](using-templates.md) — Level 1 fundamentals
+- [CLI `he parse` command](../../cli/commands/parse.md) — Command-line extraction
diff --git a/docs/en/python/guides/search-and-chat.md b/docs/en/python/guides/search-and-chat.md
index 666f55d..e430d44 100644
--- a/docs/en/python/guides/search-and-chat.md
+++ b/docs/en/python/guides/search-and-chat.md
@@ -1,6 +1,9 @@
# Search and Chat
-Query your knowledge base using semantic search and conversational AI.
+!!! tip "Advanced - Post-Extraction"
+ This guide covers using extracted knowledge. You should be comfortable with [Level 1: Using Templates](using-templates.md) first.
+
+Query your knowledge abstract using semantic search and conversational AI.
---
@@ -195,9 +198,9 @@ print(response.content)
```python
class ResearchAssistant:
- def __init__(self, kb_path):
+ def __init__(self, ka_path):
self.ka = Template.create("general/concept_graph", "en")
- self.ka.load(kb_path)
+ self.ka.load(ka_path)
self.ka.build_index()
def ask(self, question):
@@ -271,6 +274,10 @@ response = result.chat("Be more specific: ...")
## See Also
-- [Working with Auto-Types](working-with-autotypes.md)
-- [Incremental Updates](incremental-updates.md)
-- [Saving and Loading](saving-loading.md)
+**Related Workflows:**
+- [Incremental Updates](incremental-updates.md) — Add more content
+- [Saving and Loading](saving-loading.md) — Persist for later use
+
+**Basics:**
+- [Using Templates](using-templates.md) — Level 1 fundamentals
+- [Working with Auto-Types](working-with-autotypes.md) — Level 2 customization
diff --git a/docs/en/python/guides/choosing-methods.md b/docs/en/python/guides/using-methods.md
similarity index 71%
rename from docs/en/python/guides/choosing-methods.md
rename to docs/en/python/guides/using-methods.md
index f96e53a..24eec7a 100644
--- a/docs/en/python/guides/choosing-methods.md
+++ b/docs/en/python/guides/using-methods.md
@@ -1,28 +1,31 @@
-# Choosing Methods
+# Using Methods
-Understand extraction methods and when to use each.
+!!! tip "Level 1 - Beginner"
+ This guide is for beginners. Before reading, please complete the [Quickstart](../quickstart.md) and [Using Templates](using-templates.md).
+
+Learn about Hyper-Extract extraction methods and how to quickly switch between algorithms in `Template.create`.
---
## What Are Methods?
-Methods are the underlying algorithms that power knowledge extraction. While templates provide easy-to-use, domain-specific configurations, methods give you direct access to the extraction algorithms.
+A **Method** is the underlying algorithm that drives knowledge extraction. In Hyper-Extract, both methods and templates can be called directly through `Template.create`:
----
+```python
+# Using a template
+ka = Template.create("general/biography_graph", language="en")
-## Method Categories
+# Using a method
+ka = Template.create("method/light_rag")
+```
-### RAG-Based Methods
+The difference:
+- **Template** = Pre-configured domain solution (structure + prompts + language)
+- **Method** = Pure extraction algorithm, lighter weight, ideal when you need to switch algorithms
-**Retrieval-Augmented Generation** methods excel at processing large documents by combining retrieval with generation.
+---
-| Method | Best For | Key Feature |
-|--------|----------|-------------|
-| `light_rag` | General use | Fast, lightweight |
-| `graph_rag` | Large documents | Community detection |
-| `hyper_rag` | Complex relationships | N-ary hyperedges |
-| `hypergraph_rag` | Advanced scenarios | Enhanced hypergraph |
-| `cog_rag` | Reasoning tasks | Cognitive retrieval |
+## Method Categories
### Typical Methods
@@ -35,19 +38,29 @@ Methods are the underlying algorithms that power knowledge extraction. While tem
| `kg_gen` | Flexibility | Configurable generation |
| `atom` | Temporal data | Evidence attribution |
+### RAG-Based Methods
+
+**Retrieval-Augmented Generation** methods excel at processing large documents by combining retrieval with generation.
+
+| Method | Best For | Key Feature |
+|--------|----------|-------------|
+| `light_rag` | General use | Fast, lightweight |
+| `graph_rag` | Large documents | Community detection |
+| `hyper_rag` | Complex relationships | N-ary hyperedges |
+| `hypergraph_rag` | Advanced scenarios | Enhanced hypergraph |
+| `cog_rag` | Reasoning tasks | Cognitive retrieval |
+
---
-## Using Methods
+## Basic Usage
-### Basic Usage
+### Default Configuration
```python
from hyperextract import Template
-# Create from method
+# Create and extract
ka = Template.create("method/light_rag")
-
-# Extract
result = ka.parse(text)
```
@@ -82,7 +95,7 @@ graph TD
D -->|No| F{Prioritize quality?}
F -->|Yes| G[iText2KG]
F -->|No| H[kg_gen]
-
+
C --> I{Relationship complexity?}
I -->|Simple| J[light_rag]
I -->|Standard| K[graph_rag]
@@ -141,7 +154,59 @@ ka = Template.create("method/atom")
---
-## Method Details
+## Method Quick Reference
+
+### itext2kg
+
+Best for: High-quality triple extraction
+
+```python
+ka = Template.create("method/itext2kg")
+
+# Characteristics:
+# - Optimized for triple quality
+# - Iterative refinement
+# - Good for knowledge base construction
+```
+
+### itext2kg_star
+
+Best for: Enhanced quality extraction
+
+```python
+ka = Template.create("method/itext2kg_star")
+
+# Characteristics:
+# - Improved extraction quality
+# - Better handling of complex cases
+# - Enhanced entity linking
+```
+
+### kg_gen
+
+Best for: Flexible, configurable extraction
+
+```python
+ka = Template.create("method/kg_gen")
+
+# Characteristics:
+# - Configurable generation
+# - Flexible schema
+# - Fast processing
+```
+
+### atom
+
+Best for: Temporal analysis with evidence
+
+```python
+ka = Template.create("method/atom")
+
+# Characteristics:
+# - Temporal fact extraction
+# - Evidence attribution
+# - Confidence scoring
+```
### light_rag
@@ -182,35 +247,9 @@ ka = Template.create("method/hyper_rag")
# - Richer graph structure
```
-### itext2kg
-
-Best for: High-quality triple extraction
-
-```python
-ka = Template.create("method/itext2kg")
-
-# Characteristics:
-# - Optimized for triple quality
-# - Iterative refinement
-# - Good for knowledge base construction
-```
-
-### atom
-
-Best for: Temporal analysis with evidence
-
-```python
-ka = Template.create("method/atom")
-
-# Characteristics:
-# - Temporal fact extraction
-# - Evidence attribution
-# - Confidence scoring
-```
-
---
-## Listing Methods
+## Listing Available Methods
```python
from hyperextract import Template
@@ -225,32 +264,6 @@ for name, info in methods.items():
---
-## Method Configuration
-
-Methods can be configured through parameters:
-
-```python
-from hyperextract import Template
-
-# Most methods use default configuration
-# Advanced users can create method instances directly
-from hyperextract.methods import Light_RAG
-from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-
-llm = ChatOpenAI()
-emb = OpenAIEmbeddings()
-
-ka = Light_RAG(
- llm_client=llm,
- embedder=emb,
- # Method-specific parameters
- chunk_size=1024,
- max_workers=5
-)
-```
-
----
-
## Best Practices
1. **Start with light_rag** — Good default for most cases
@@ -261,22 +274,15 @@ ka = Light_RAG(
---
-## When to Use Templates vs Methods
-
-| Scenario | Recommendation |
-|----------|----------------|
-| Quick start | Templates |
-| Domain-specific task | Templates |
-| Production system | Templates |
-| Research/Experimentation | Methods |
-| Custom requirements | Methods |
-| Performance optimization | Methods |
-| Full control | Methods |
+## See Also
----
+**Prerequisites:**
+- [Using Templates](using-templates.md) — Level 1: Ready-to-use domain solutions
-## See Also
+**Next Steps:**
+- [Working with Auto-Types](working-with-autotypes.md) — Level 2: Custom schemas and extraction configs
+- [Creating Custom Templates](custom-templates.md) — Package your custom configs into reusable templates
-- [Using Templates](using-templates.md)
-- [Template Library](../../templates/index.md)
-- [Methods Concept Doc](../../concepts/methods.md)
+**Reference:**
+- [Methods Concept Doc](../../concepts/methods.md) — Detailed algorithm explanations
+- [Template Library](../../templates/index.md) — Browse existing templates
diff --git a/docs/en/python/guides/using-templates.md b/docs/en/python/guides/using-templates.md
index 5384eb2..0002727 100644
--- a/docs/en/python/guides/using-templates.md
+++ b/docs/en/python/guides/using-templates.md
@@ -1,5 +1,8 @@
# Using Templates
+!!! tip "Level 1 - Beginner"
+ This guide is for beginners. Before reading, please complete the [Quickstart](../quickstart.md).
+
Learn how to use and customize templates for knowledge extraction.
---
@@ -7,6 +10,7 @@ Learn how to use and customize templates for knowledge extraction.
## What Are Templates?
Templates are pre-configured extraction setups that combine:
+
- **Auto-Type** — Output data structure
- **Prompts** — Instructions for the LLM
- **Schema** — Field definitions and types
@@ -143,6 +147,72 @@ print(cfg.language) # Supported languages
---
+## Understanding Template Outputs
+
+`Template.create` returns an **AutoType** object. Different templates use different AutoTypes, so the way you access extracted results varies:
+
+| Type | AutoType | Typical Access | Use Case |
+|------|----------|----------------|----------|
+| **Model** | `AutoModel` | `result.data.field_name` | Reports, profiles, structured objects |
+| **List** | `AutoList` | `result.data.items` | Ordered collections, steps |
+| **Set** | `AutoSet` | `result.data.items` | Deduplicated tags, keywords |
+| **Graph** | `AutoGraph` | `result.nodes` / `result.edges` | Binary entity relationships |
+| **Hypergraph** | `AutoHypergraph` | `result.nodes` / `result.edges` | Multi-entity relationships |
+| **Temporal Graph** | `AutoTemporalGraph` | `result.nodes` / `result.edges` (with `time`) | Timelines, biographies |
+| **Spatial Graph** | `AutoSpatialGraph` | `result.nodes` / `result.edges` (with `location`) | Geographic networks |
+| **Spatio-Temporal Graph** | `AutoSpatioTemporalGraph` | `result.nodes` / `result.edges` (with `time` + `location`) | Historical events |
+
+!!! info "Related Docs"
+ - Learn more about the design and use cases of each AutoType in [Auto-Types Concepts](../../concepts/autotypes.md).
+ - Learn how to customize schemas and configs in [Working with Auto-Types](working-with-autotypes.md).
+
+### Quick Examples
+
+#### Model (AutoModel)
+
+```python
+ka = Template.create("finance/earnings_summary", "en")
+result = ka.parse(report_text)
+
+print(result.data.company_name)
+print(result.data.revenue)
+```
+
+#### List (AutoList)
+
+```python
+ka = Template.create("general/list", "en")
+result = ka.parse(text)
+
+for item in result.data.items:
+ print(item)
+```
+
+#### Set (AutoSet)
+
+```python
+ka = Template.create("general/set", "en")
+result = ka.parse(text)
+
+for item in result.data.items:
+ print(item) # deduplicated
+```
+
+#### Graph (AutoGraph)
+
+```python
+ka = Template.create("general/graph", "en")
+result = ka.parse(text)
+
+for node in result.nodes:
+ print(f"{node.name} ({node.type})")
+
+for edge in result.edges:
+ print(f"{edge.source} --{edge.type}--> {edge.target}")
+```
+
+---
+
## Common Template Patterns
### Pattern 1: Biography Analysis
@@ -166,6 +236,8 @@ result.build_index()
result.show() # Visualize life timeline with search/chat
```
+![Interactive Visualization](../../../assets/en_show.png)
+
### Pattern 2: Financial Report
```python
@@ -206,7 +278,7 @@ ka = Template.create("general/concept_graph", "en")
paper = ka.parse(paper_text)
-# Build searchable knowledge base
+# Build searchable knowledge abstract
paper.build_index()
# Query findings
@@ -290,6 +362,10 @@ ka = Template.create("general/biography_graph", "fr") # May fail
## See Also
+**Next Steps:**
+- [Working with Auto-Types](working-with-autotypes.md) — Level 2: Custom schemas
+- [Creating Custom Templates](custom-templates.md) — Level 2+: Write your own templates
+
+**Reference:**
- [Template Library](../../templates/index.md) — Browse all templates
-- [Creating Custom Templates](custom-templates.md) — Write your own
-- [Choosing Methods](choosing-methods.md) — When to use methods instead
+- [Using Methods](using-methods.md) — When to use methods instead
diff --git a/docs/en/python/guides/working-with-autotypes.md b/docs/en/python/guides/working-with-autotypes.md
index 683f2a9..86baa02 100644
--- a/docs/en/python/guides/working-with-autotypes.md
+++ b/docs/en/python/guides/working-with-autotypes.md
@@ -1,161 +1,171 @@
# Working with Auto-Types
-Extract, manipulate, and utilize structured knowledge data.
+!!! tip "Level 2 - Intermediate"
+ This guide covers configured Auto-Type usage. Before reading, please complete [Level 1: Using Templates](using-templates.md) and [Level 1: Using Methods](using-methods.md).
+
+Learn how to configure Auto-Types directly to customize schemas, deduplication logic, and extraction behavior.
---
## What Are Auto-Types?
-Auto-Types are intelligent data structures that automatically extract and organize knowledge from text. They provide:
+Auto-Types are the core data structures in Hyper-Extract that extract, organize, and store structured knowledge from text. They provide:
- **Type-safe schemas** — Pydantic-based validation
- **LLM-powered extraction** — Automatic content processing
- **Built-in operations** — Search, merge, visualize
- **Serialization** — Save/load to disk
----
-
-## The 8 Auto-Types
-
-### Scalar Types
-
-#### AutoModel
-
-Single structured object extraction.
-
-```python
-from hyperextract import Template
-
-ka = Template.create("finance/earnings_summary", "en")
-result = ka.parse(report_text)
-
-# Access fields directly
-print(result.data.company_name)
-print(result.data.revenue)
-print(result.data.eps)
-```
-
-#### AutoList
-
-Ordered collection extraction.
-
-```python
-from hyperextract import Template
-
-ka = Template.create("general/base_list", "en")
-result = ka.parse(text)
-
-# Iterate over items
-for item in result.data.items:
- print(item)
-
-# Access by index
-first = result.data.items[0]
-```
-
-#### AutoSet
-
-Deduplicated collection extraction.
-
-```python
-from hyperextract import Template
-
-ka = Template.create("general/base_set", "en")
-result = ka.parse(text)
-
-# Items are unique
-for item in result.data.items:
- print(item)
-```
-
-### Graph Types
-
-#### AutoGraph
+All Auto-Types inherit from `BaseAutoType`, so they share a common set of capabilities (e.g., `parse`, `feed_text`, `build_index`, `search`, `chat`, `dump`, `load`).
-Entity-relationship graph extraction.
-
-```python
-from hyperextract import Template
-
-ka = Template.create("general/knowledge_graph", "en")
-result = ka.parse(text)
+---
-# Access nodes
-for node in result.nodes:
- print(f"{node.name} ({node.type})")
- print(f" Description: {node.description}")
+## Three-Level Usage Architecture
-# Access edges
-for edge in result.edges:
- print(f"{edge.source} --{edge.type}--> {edge.target}")
-```
+Hyper-Extract provides three levels of control. This guide focuses on **Level 2**.
-#### AutoHypergraph
+| Level | Approach | When to Use | Reference |
+|-------|----------|-------------|-----------|
+| **Level 1** | Templates / Methods | Quick start, standard use cases | [Using Templates](using-templates.md), [Using Methods](using-methods.md) |
+| **Level 2** | Configured Auto-Type | Custom schemas, same extraction logic | **This guide** |
+| **Level 3** | Fully custom methods | Complete control over extraction | [Methods Concepts](../../concepts/methods.md) |
-Multi-entity relationship extraction.
+---
-```python
-from hyperextract import Template
+## Level 2: Configured Auto-Type Usage
-ka = Template.create("general/base_hypergraph", "en")
-result = ka.parse(text)
+When you need custom schemas but don't want to implement full extraction logic from scratch, instantiate an Auto-Type directly and pass configuration parameters.
-# Hyperedges connect multiple entities
-for edge in result.edges:
- print(f"Type: {edge.type}")
- print(f"Entities: {edge.entities}")
-```
+### When to Use Level 2
-#### AutoTemporalGraph
+- You need custom node/edge schemas
+- You want to control deduplication logic
+- Template output doesn't match your exact needs
+- You're building reusable Python components
-Time-based graph extraction.
+### Complete Example: Custom Graph
```python
-from hyperextract import Template
-
-ka = Template.create("general/base_temporal_graph", "en")
-result = ka.parse(text)
-
-# Relations include time information
-for edge in result.edges:
- print(f"{edge.source} --{edge.type}--> {edge.target}")
- if hasattr(edge, 'time'):
- print(f" Time: {edge.time}")
+from hyperextract import AutoGraph
+from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+from pydantic import BaseModel, Field
+
+# Step 1: Define custom schemas
+class Person(BaseModel):
+ """Custom node schema"""
+ name: str = Field(description="Person's full name")
+ role: str = Field(description="Job title or role")
+ expertise: list[str] = Field(default=[], description="Areas of expertise")
+
+class Collaboration(BaseModel):
+ """Custom edge schema"""
+ source: str = Field(description="First person's name")
+ target: str = Field(description="Second person's name")
+ project: str = Field(description="Project they worked on together")
+ year: int = Field(description="Year of collaboration")
+
+# Step 2: Configure LLM clients
+llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+embedder = OpenAIEmbeddings(model="text-embedding-3-small")
+
+# Step 3: Create configured AutoGraph
+graph = AutoGraph[Person, Collaboration](
+ node_schema=Person,
+ edge_schema=Collaboration,
+ # Define how to extract unique keys for deduplication
+ node_key_extractor=lambda p: p.name,
+ edge_key_extractor=lambda c: f"{c.source}-{c.target}-{c.project}",
+ # Define how to extract node references from edges
+ nodes_in_edge_extractor=lambda c: (c.source, c.target),
+ # LLM clients
+ llm_client=llm,
+ embedder=embedder,
+)
+
+# Step 4: Extract
+text = """
+Dr. Sarah Chen and Dr. Michael Wang collaborated on the Climate AI project in 2023.
+Sarah is a machine learning researcher with expertise in neural networks and climate modeling.
+Michael specializes in data engineering and distributed systems.
+"""
+
+graph.feed_text(text)
+
+# Step 5: Access results
+print(f"Extracted {len(graph.nodes)} people")
+for person in graph.nodes:
+ print(f"- {person.name}: {person.role}")
+ print(f" Expertise: {', '.join(person.expertise)}")
+
+print(f"\nExtracted {len(graph.edges)} collaborations")
+for collab in graph.edges:
+ print(f"- {collab.source} & {collab.target}: {collab.project} ({collab.year})")
+
+# Step 6: Use built-in features
+graph.build_index()
+
+# Search
+nodes, edges = graph.search("machine learning", top_k=2)
+print(f"\nSearch found: {len(nodes)} people")
+
+# Visualize
+graph.show()
```
-#### AutoSpatialGraph
+### Key Configuration Parameters
-Location-based graph extraction.
-
-```python
-from hyperextract import Template
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `node_schema` / `edge_schema` | Yes | Pydantic model defining the structure |
+| `node_key_extractor` | Yes | Function to extract unique key from node |
+| `edge_key_extractor` | Yes | Function to extract unique key from edge |
+| `nodes_in_edge_extractor` | Yes | Function to get (source, target) from edge |
+| `llm_client` | Yes | LangChain-compatible LLM client |
+| `embedder` | Yes | LangChain-compatible embeddings client |
-ka = Template.create("general/base_spatial_graph", "en")
-result = ka.parse(text)
+### Comparison: Template vs Configured Auto-Type
-# Nodes/edges include location
-for node in result.nodes:
- if hasattr(node, 'location'):
- print(f"{node.name} at {node.location}")
-```
+| Aspect | Template | Configured Auto-Type |
+|--------|----------|---------------------|
+| Schema definition | YAML file | Python Pydantic classes |
+| Extraction logic | Pre-built | Same pre-built logic |
+| Deduplication | Pre-configured | You define key extractors |
+| Language support | Built-in | You provide prompts |
+| Reusability | Share YAML files | Package as Python module |
-#### AutoSpatioTemporalGraph
+### More Configuration Examples
-Combined time and space extraction.
+#### Temporal Graph
```python
-from hyperextract import Template
-
-ka = Template.create("general/base_spatio_temporal_graph", "en")
-result = ka.parse(text)
-
-# Full context: who, what, when, where
-for edge in result.edges:
- print(f"Event: {edge.type}")
- if hasattr(edge, 'time'):
- print(f" When: {edge.time}")
- if hasattr(edge, 'location'):
- print(f" Where: {edge.location}")
+from hyperextract import AutoTemporalGraph
+from pydantic import BaseModel, Field
+
+class Event(BaseModel):
+ """Node: A historical event"""
+ name: str = Field(description="Event name")
+ category: str = Field(description="Type of event")
+
+class CausalLink(BaseModel):
+ """Edge: Time-aware causal relationship"""
+ source: str = Field(description="Earlier event")
+ target: str = Field(description="Later event")
+ relationship: str = Field(description="How they connect")
+ time: str = Field(description="When the link occurred")
+
+timeline = AutoTemporalGraph[Event, CausalLink](
+ node_schema=Event,
+ edge_schema=CausalLink,
+ node_key_extractor=lambda e: e.name,
+ edge_key_extractor=lambda l: f"{l.source}-{l.target}-{l.time}",
+ nodes_in_edge_extractor=lambda l: (l.source, l.target),
+ llm_client=llm,
+ embedder=embedder,
+ # Temporal-specific: extract time from edge
+ time_extractor=lambda l: l.time,
+)
+
+timeline.feed_text(historical_text)
```
---
@@ -273,7 +283,7 @@ print(f"Edges: {edge_types}")
## Advanced Usage
-### Custom Schema Access
+### Accessing the Schema
```python
# Access the schema
@@ -305,15 +315,31 @@ elif isinstance(result, AutoList):
## Best Practices
-1. **Check hasattr before optional fields** — Schema fields may vary
+### Level 2 (Configured Auto-Types)
+
+1. **Design schemas carefully** — Fields become LLM extraction targets
+2. **Use clear Field descriptions** — Help LLM understand expectations
+3. **Choose good key extractors** — Critical for deduplication
+4. **Test with small samples** — Iterate on schema design
+
+### General
+
+1. **Check `hasattr` before optional fields** — Schema fields may vary
2. **Handle empty results** — Always check `empty()`
-3. **Use model_dump for serialization** — Proper JSON conversion
+3. **Use `model_dump` for serialization** — Proper JSON conversion
4. **Leverage type hints** — IDE support for autocomplete
---
## See Also
-- [Search and Chat](search-and-chat.md)
-- [Saving and Loading](saving-loading.md)
-- [Auto-Types Reference](../../concepts/autotypes.md)
+**Prerequisites:**
+- [Using Templates](using-templates.md) — Level 1 basics
+- [Using Methods](using-methods.md) — Level 1 basics
+- [Auto-Types Concepts](../../concepts/autotypes.md) — What each type does
+
+**Next Steps:**
+- [Creating Custom Templates](custom-templates.md) — Package your configurations
+- [Incremental Updates](incremental-updates.md) — Add more documents
+- [Search and Chat](search-and-chat.md) — Use extracted knowledge
+- [Saving and Loading](saving-loading.md) — Persist your results
diff --git a/docs/en/python/index.md b/docs/en/python/index.md
index d33b029..a51df04 100644
--- a/docs/en/python/index.md
+++ b/docs/en/python/index.md
@@ -41,6 +41,8 @@ result.build_index()
result.show()
```
+![Interactive Visualization](../../assets/en_show.png)
+
---
## Core Classes
@@ -104,6 +106,8 @@ result.load("./output/") # Load from disk
result.show() # Interactive visualization
```
+![Interactive Visualization](../../assets/en_show.png)
+
---
## Documentation Structure
@@ -112,15 +116,15 @@ result.show() # Interactive visualization
- **[Core Concepts](core-concepts.md)** — Template, AutoType, Method explained
- **Guides:**
- [Using Templates](guides/using-templates.md)
- - [Choosing Methods](guides/choosing-methods.md)
+ - [Using Methods](guides/using-methods.md)
- [Working with Auto-Types](guides/working-with-autotypes.md)
- [Search and Chat](guides/search-and-chat.md)
- [Incremental Updates](guides/incremental-updates.md)
- [Saving and Loading](guides/saving-loading.md)
- **API Reference:**
- [Template](api-reference/template.md)
- - [Auto-Types](api-reference/autotypes.md)
- - [Methods](api-reference/methods.md)
+ - [Auto-Types](api-reference/autotypes/base.md)
+ - [Methods](api-reference/methods/registry.md)
---
@@ -136,7 +140,7 @@ ka = Template.create("general/concept_graph", language="en")
with open("paper.md") as f:
paper = ka.parse(f.read())
-# Build searchable knowledge base
+# Build searchable knowledge abstract
paper.build_index()
# Ask questions
@@ -156,22 +160,22 @@ print(report.data.revenue)
print(report.data.eps)
```
-### Building a Knowledge Base
+### Building a Knowledge Abstract
```python
from hyperextract import Template
-ka = Template.create("general/knowledge_graph", language="en")
+ka = Template.create("general/graph", language="en")
# Initial extraction
-kb = ka.parse(doc1_text)
+ka = ka.parse(doc1_text)
# Add more documents
-kb.feed_text(doc2_text)
-kb.feed_text(doc3_text)
+ka.feed_text(doc2_text)
+ka.feed_text(doc3_text)
# Save for later
-kb.dump("./my_kb/")
+ka.dump("./my_ka/")
```
---
@@ -220,7 +224,7 @@ Hyper-Extract is fully typed for IDE support:
```python
from hyperextract import Template, AutoGraph
-ka: AutoGraph = Template.create("general/knowledge_graph", "en")
+ka: AutoGraph = Template.create("general/graph", "en")
result = ka.parse(text)
# IDE autocomplete works
diff --git a/docs/en/python/quickstart.md b/docs/en/python/quickstart.md
index de13239..740151e 100644
--- a/docs/en/python/quickstart.md
+++ b/docs/en/python/quickstart.md
@@ -80,6 +80,8 @@ result.build_index()
result.show()
```
+![Interactive Visualization](../../assets/en_show.png)
+
### 4. Search
```python
@@ -158,7 +160,7 @@ def main():
print(f"\nSearch results: {len(search_nodes)} nodes, {len(search_edges)} edges")
# Save
- print("\nSaving knowledge base...")
+ print("\nSaving knowledge abstract...")
result.dump("./ada_kb/")
print("\nDone! Try: he show ./ada_kb/")
diff --git a/docs/en/resources/faq.md b/docs/en/resources/faq.md
index 911652b..7bccbe1 100644
--- a/docs/en/resources/faq.md
+++ b/docs/en/resources/faq.md
@@ -100,21 +100,21 @@ he list template
Convert to text first:
```bash
pdftotext document.pdf document.txt
-he parse document.txt -t general/knowledge_graph -l en
+he parse document.txt -t general/graph -l en
```
### Can I process multiple documents?
**Option 1**: Feed incrementally
```bash
-he parse doc1.md -t general/graph -o ./kb/ -l en
-he feed ./kb/ doc2.md
-he feed ./kb/ doc3.md
+he parse doc1.md -t general/graph -o ./ka/ -l en
+he feed ./ka/ doc2.md
+he feed ./ka/ doc3.md
```
**Option 2**: Process directory
```bash
-he parse ./docs/ -t general/graph -o ./kb/ -l en
+he parse ./docs/ -t general/graph -o ./ka/ -l en
```
### How do I extract in Chinese?
@@ -145,8 +145,8 @@ Process in smaller batches:
```python
for batch in chunks(documents, 5):
for doc in batch:
- kb.feed_text(doc)
- kb.dump("./checkpoint/")
+ ka.feed_text(doc)
+ ka.dump("./checkpoint/")
```
---
@@ -176,6 +176,8 @@ result.build_index()
result.show()
```
+![Interactive Visualization](../../assets/en_show.png)
+
### Can I export to other formats?
```python
@@ -217,8 +219,8 @@ he build-index ./output/
Try:
- Different search terms
-- Increase `top_k`: `he search ./kb/ "query" -n 10`
-- Check if index is built: `he info ./kb/`
+- Increase `top_k`: `he search ./ka/ "query" -n 10`
+- Check if index is built: `he info ./ka/`
---
diff --git a/docs/en/resources/troubleshooting.md b/docs/en/resources/troubleshooting.md
index cc00b10..8e90938 100644
--- a/docs/en/resources/troubleshooting.md
+++ b/docs/en/resources/troubleshooting.md
@@ -11,6 +11,7 @@ Solutions to common issues.
**Problem**: Installation fails with errors
**Solutions**:
+
1. Upgrade pip: `pip install --upgrade pip`
2. Use Python 3.11+: `python --version`
3. Install in virtual environment:
@@ -25,6 +26,7 @@ Solutions to common issues.
**Problem**: Can't import after installation
**Solutions**:
+
1. Check Python version: `python --version` (need 3.11+)
2. Verify installation: `pip list | grep hyper`
3. Check virtual environment is activated
@@ -60,6 +62,7 @@ Solutions to common issues.
**Error**: `Authentication failed`
**Solutions**:
+
1. Verify key is correct
2. Check for extra spaces
3. Try regenerating key in OpenAI dashboard
@@ -100,6 +103,7 @@ Solutions to common issues.
**Error**: `--lang is required`
**Solution**:
+
```bash
# Add language flag
he parse doc.md -t general/biography_graph -o ./out/ -l en
@@ -138,6 +142,7 @@ Note: Method templates don't require language.
**Error**: `Search index not built`
**Solution**:
+
```bash
he build-index ./output/
```
@@ -175,6 +180,7 @@ he build-index ./output/
**Error**: `Chat failed: index not found`
**Solution**:
+
```bash
he build-index ./output/
he talk ./output/ -q "your question"
@@ -250,7 +256,7 @@ he talk ./output/ -q "your question"
2. **Try different template**:
```bash
- he parse doc.md -t general/base_model -l en
+ he parse doc.md -t general/model -l en
```
3. **Check language**:
@@ -262,7 +268,7 @@ he talk ./output/ -q "your question"
he parse chinese_doc.md -t general/graph -l zh
```
-### Corrupted Knowledge Base
+### Corrupted Knowledge Abstract
**Problem**: Can't load or errors reading
@@ -270,19 +276,19 @@ he talk ./output/ -q "your question"
1. **Check file structure**:
```bash
- ls ./kb/
+ ls ./ka/
# Should have: data.json, metadata.json
```
2. **Validate JSON**:
```bash
- python -c "import json; json.load(open('./kb/data.json'))"
+ python -c "import json; json.load(open('./ka/data.json'))"
```
3. **Re-extract**:
```bash
- rm -rf ./kb/
- he parse doc.md -t general/graph -o ./kb/ -l en
+ rm -rf ./ka/
+ he parse doc.md -t general/graph -o ./ka/ -l en
```
---
diff --git a/docs/en/templates/choosing/by-output.md b/docs/en/templates/choosing/by-output.md
new file mode 100644
index 0000000..758b932
--- /dev/null
+++ b/docs/en/templates/choosing/by-output.md
@@ -0,0 +1,279 @@
+# Choose by Output Type
+
+Select a template based on what kind of output you need.
+
+---
+
+## Decision Tree
+
+```mermaid
+graph TD
+ A[What output do you need?] --> B{Structured summary?}
+ B -->|Yes| C[AutoModel]
+ B -->|No| D{Collection of items?}
+ D -->|No| E{Relationships between items?}
+ E -->|No| F[Consider AutoModel or restructure task]
+ E -->|Yes| G{Multiple entities per relationship?}
+ G -->|Yes| H[AutoHypergraph]
+ G -->|No| I{Time dimension?}
+ I -->|Yes| J{Space dimension?}
+ J -->|Yes| K[AutoSpatioTemporalGraph]
+ J -->|No| L[AutoTemporalGraph]
+ I -->|No| M{Space dimension?}
+ M -->|Yes| N[AutoSpatialGraph]
+ M -->|No| O[AutoGraph]
+ D -->|Yes| P{Ordered list?}
+ P -->|Yes| Q[AutoList]
+ P -->|No| R[AutoSet]
+```
+
+---
+
+## AutoModel — Structured Summary
+
+**Use when:** You need a structured report or summary
+
+**Output:** Single structured object with fields
+
+**Examples:**
+- Financial earnings summary
+- Patient discharge summary
+- Product catalog entry
+
+**Templates:**
+
+| Template | Domain |
+|----------|--------|
+| `general/model` | General purpose |
+| `finance/earnings_summary` | Financial reports |
+| `medicine/discharge_instruction` | Medical |
+| `tcm/herb_property` | TCM |
+
+**Example:**
+```python
+from hyperextract import Template
+
+ka = Template.create("finance/earnings_summary", "en")
+result = ka.parse(earnings_report)
+
+print(result.data.revenue) # 1000000
+print(result.data.eps) # 2.50
+print(result.data.yoy_growth) # 15.3
+```
+
+---
+
+## AutoList — Ordered Collection
+
+**Use when:** You need an ordered list of items
+
+**Output:** Ordered list with possible duplicates
+
+**Examples:**
+- Compliance checklist (ordered by importance)
+- Step-by-step procedures
+- Ranked items
+
+**Templates:**
+
+| Template | Domain |
+|----------|--------|
+| `general/list` | General purpose |
+| `legal/compliance_list` | Legal compliance |
+| `legal/contract_obligation` | Contract obligations |
+| `medicine/symptom_list` | Medical symptoms |
+
+**Example:**
+```python
+ka = Template.create("legal/compliance_list", "en")
+result = ka.parse(contract_text)
+
+for item in result.data.items:
+ print(f"{item.priority}: {item.description}")
+```
+
+---
+
+## AutoSet — Unique Collection
+
+**Use when:** You need unique items without order
+
+**Output:** Set of unique items
+
+**Examples:**
+- Risk factors (unique categories)
+- Defined terms in a contract
+- Key concepts
+
+**Templates:**
+
+| Template | Domain |
+|----------|--------|
+| `general/set` | General purpose |
+| `finance/risk_factor_set` | Financial risks |
+| `legal/defined_term_set` | Legal terms |
+
+**Example:**
+```python
+ka = Template.create("finance/risk_factor_set", "en")
+result = ka.parse(filing_text)
+
+for risk in result.data.items:
+ print(f"{risk.category}: {risk.description}")
+```
+
+---
+
+## AutoGraph — Entity Network
+
+**Use when:** You need binary relationships (A → B)
+
+**Output:** Graph with entities and binary edges
+
+**Examples:**
+- Knowledge graphs
+- Concept maps
+- Social networks
+- Ownership structures
+
+**Templates:**
+
+| Template | Domain |
+|----------|--------|
+| `general/graph` | General purpose |
+| `general/graph` | Domain knowledge |
+| `general/concept_graph` | Research concepts |
+| `finance/ownership_graph` | Company ownership |
+| `medicine/anatomy_graph` | Anatomy |
+
+**Example:**
+```python
+ka = Template.create("general/concept_graph", "en")
+result = ka.parse(paper_text)
+
+# Access entities
+for node in result.nodes:
+ print(f"Concept: {node.name} ({node.type})")
+
+# Access relationships
+for edge in result.edges:
+ print(f"{edge.source} → {edge.target}: {edge.type}")
+```
+
+---
+
+## AutoTemporalGraph — Timeline + Network
+
+**Use when:** You need relationships that happen over time
+
+**Output:** Graph with time-annotated edges
+
+**Examples:**
+- Biographies and life events
+- Case chronologies
+- Event sequences
+
+**Templates:**
+
+| Template | Domain |
+|----------|--------|
+| `general/base_temporal_graph` | General purpose |
+| `general/biography_graph` | Person's life story |
+| `finance/event_timeline` | Financial events |
+| `legal/case_fact_timeline` | Legal case timeline |
+| `medicine/hospital_timeline` | Patient timeline |
+
+**Example:**
+```python
+ka = Template.create("general/biography_graph", "en")
+result = ka.parse(biography_text)
+
+# Build index for visualization
+result.build_index()
+result.show() # Interactive timeline view
+
+# Query by time
+response = result.chat("What happened between 1880-1890?")
+```
+
+---
+
+## AutoSpatialGraph — Location + Network
+
+**Use when:** You need geographic/spatial relationships
+
+**Output:** Graph with location-annotated entities
+
+**Examples:**
+- Geographic networks
+- Location-based systems
+- Spatial topology
+
+**Templates:**
+
+| Template | Domain |
+|----------|--------|
+| `general/base_spatial_graph` | General purpose |
+
+---
+
+## AutoSpatioTemporalGraph — Time + Space + Network
+
+**Use when:** You need both time and location dimensions
+
+**Output:** Graph with both temporal and spatial annotations
+
+**Examples:**
+- Historical events with locations
+- Movement tracking
+- Geopolitical changes over time
+
+**Templates:**
+
+| Template | Domain |
+|----------|--------|
+| `general/base_spatio_temporal_graph` | General purpose |
+
+---
+
+## AutoHypergraph — Complex Relationships
+
+**Use when:** You need relationships connecting 2+ entities
+
+**Output:** Hypergraph with n-ary hyperedges
+
+**Examples:**
+- Multi-party contracts
+- Complex chemical reactions
+- Conference proceedings (multiple authors)
+
+**Templates:**
+
+| Template | Domain |
+|----------|--------|
+| `general/base_hypergraph` | General purpose |
+
+**Note:** Hypergraphs are advanced. Most use cases can be satisfied with AutoGraph.
+
+---
+
+## Quick Reference
+
+| Output Type | Auto-Type | Use When... |
+|-------------|-----------|-------------|
+| Structured report | AutoModel | Need a summary with fields |
+| Ordered list | AutoList | Items have priority/sequence |
+| Unique items | AutoSet | Need deduplicated collection |
+| Binary network | AutoGraph | A relates to B relationships |
+| Timeline network | AutoTemporalGraph | Events over time |
+| Geographic network | AutoSpatialGraph | Location-based relationships |
+| Time + space network | AutoSpatioTemporalGraph | Both dimensions needed |
+| Complex relations | AutoHypergraph | Multi-entity relationships |
+
+---
+
+## Learn More
+
+- [Auto-Types Concept Guide](../../concepts/autotypes.md)
+- [Choose by Task](by-task.md)
+- [Template Overview](../reference/overview.md)
diff --git a/docs/en/templates/choosing/by-task.md b/docs/en/templates/choosing/by-task.md
new file mode 100644
index 0000000..b7eaa76
--- /dev/null
+++ b/docs/en/templates/choosing/by-task.md
@@ -0,0 +1,275 @@
+# Choose by Task
+
+Find the right template for your specific task.
+
+---
+
+## Research & Academic
+
+### Analyzing a Research Paper
+
+**Goal:** Extract concepts, methods, results, and their relationships
+
+**Recommended:** `general/concept_graph`
+
+```bash
+he parse paper.md -t general/concept_graph -l en -o ./paper_kb/
+```
+
+**Why this template?**
+- Identifies key concepts and their definitions
+- Maps relationships between concepts
+- Supports hierarchical structures (e.g., "Neural Networks" → "CNNs")
+
+**Alternatives:**
+
+| Template | When to Use |
+|----------|-------------|
+| `general/graph` | Broader domain knowledge |
+| `general/doc_structure` | Document outline extraction |
+| `general/workflow_graph` | Method/process workflows |
+
+---
+
+### Extracting from a Technical Document
+
+**Goal:** Get structured information from manuals, specs, or documentation
+
+**Recommended:** `general/model`
+
+```python
+from hyperextract import Template
+
+ka = Template.create("general/model", "en")
+result = ka.parse(spec_text)
+
+print(result.data)
+```
+
+---
+
+## People & Biographies
+
+### Analyzing a Biography
+
+**Goal:** Extract life events, relationships, and timeline
+
+**Recommended:** `general/biography_graph`
+
+```bash
+he parse biography.md -t general/biography_graph -l en -o ./bio_kb/
+```
+
+**Features:**
+- Extracts people, places, events
+- Captures temporal relationships
+- Creates timeline visualization
+
+**Example Output:**
+```python
+{
+ "entities": [
+ {"name": "Nikola Tesla", "type": "person"},
+ {"name": "AC Motor", "type": "invention"}
+ ],
+ "relations": [
+ {"source": "Nikola Tesla", "target": "AC Motor", "type": "invented", "time": "1888"}
+ ]
+}
+```
+
+**Alternatives:**
+
+| Template | When to Use |
+|----------|-------------|
+| `general/model` | Simple person summary |
+| `general/graph` | Complex relationships beyond timeline |
+
+---
+
+### Creating a Profile Summary
+
+**Goal:** Structured summary of a person
+
+**Recommended:** `general/model`
+
+---
+
+## Finance & Business
+
+### Analyzing Earnings Reports
+
+**Goal:** Extract financial metrics and summaries
+
+**Recommended:** `finance/earnings_summary`
+
+```bash
+he parse earnings.md -t finance/earnings_summary -l en -o ./earnings/
+```
+
+**Extracts:**
+- Revenue, EPS, YoY growth
+- Segment performance
+- Guidance information
+
+---
+
+### Identifying Risk Factors
+
+**Goal:** Extract risk factors from SEC filings or reports
+
+**Recommended:** `finance/risk_factor_set`
+
+```bash
+he parse 10k.md -t finance/risk_factor_set -l en -o ./risks/
+```
+
+**Output:** Unique set of risk factors with categories
+
+---
+
+### Mapping Company Ownership
+
+**Goal:** Extract ownership structure and subsidiaries
+
+**Recommended:** `finance/ownership_graph`
+
+```bash
+he parse report.md -t finance/ownership_graph -l en -o ./ownership/
+```
+
+---
+
+## Legal Documents
+
+### Analyzing Contracts
+
+**Goal:** Extract obligations, parties, and deadlines
+
+**Recommended:** `legal/contract_obligation`
+
+```bash
+he parse contract.md -t legal/contract_obligation -l en -o ./contract/
+```
+
+**Extracts:**
+- Party obligations
+- Deadlines and milestones
+- Conditions and terms
+
+---
+
+### Tracking Case Chronologies
+
+**Goal:** Create timeline of legal case events
+
+**Recommended:** `legal/case_fact_timeline`
+
+```bash
+he parse case.md -t legal/case_fact_timeline -l en -o ./case/
+```
+
+---
+
+### Extracting Defined Terms
+
+**Goal:** Get all defined terms from a contract
+
+**Recommended:** `legal/defined_term_set`
+
+```bash
+he parse contract.md -t legal/defined_term_set -l en -o ./terms/
+```
+
+---
+
+## Medical & Healthcare
+
+### Patient Timeline
+
+**Goal:** Track hospital stay or treatment timeline
+
+**Recommended:** `medicine/hospital_timeline`
+
+```bash
+he parse record.md -t medicine/hospital_timeline -l en -o ./patient/
+```
+
+---
+
+### Drug Information
+
+**Goal:** Extract drug interactions and properties
+
+**Recommended:** `medicine/drug_interaction`
+
+```bash
+he parse drug_info.md -t medicine/drug_interaction -l en -o ./drugs/
+```
+
+---
+
+### Discharge Summary
+
+**Goal:** Generate patient discharge summary
+
+**Recommended:** `medicine/discharge_instruction`
+
+---
+
+## Traditional Chinese Medicine
+
+### Herb Properties
+
+**Goal:** Extract herb characteristics and uses
+
+**Recommended:** `tcm/herb_property`
+
+---
+
+### Formula Analysis
+
+**Goal:** Analyze herbal formula composition
+
+**Recommended:** `tcm/formula_composition`
+
+---
+
+## Industrial & Manufacturing
+
+### Equipment Documentation
+
+**Goal:** Map equipment topology and connections
+
+**Recommended:** `industry/equipment_topology`
+
+---
+
+### Safety Procedures
+
+**Goal:** Extract safety control systems
+
+**Recommended:** `industry/safety_control`
+
+---
+
+## Quick Reference
+
+| Task | Template | Type |
+|------|----------|------|
+| Research paper concepts | `general/concept_graph` | graph |
+| Person biography | `general/biography_graph` | temporal_graph |
+| Financial summary | `finance/earnings_summary` | model |
+| Risk factors | `finance/risk_factor_set` | set |
+| Contract obligations | `legal/contract_obligation` | list |
+| Case timeline | `legal/case_fact_timeline` | temporal_graph |
+| Hospital timeline | `medicine/hospital_timeline` | temporal_graph |
+| Drug interactions | `medicine/drug_interaction` | graph |
+
+---
+
+## Still Not Sure?
+
+→ [Choose by Output Type](by-output.md)
+→ [How to Choose](../how-to-choose.md)
+→ [Template Overview](../reference/overview.md)
diff --git a/docs/en/templates/examples/financial-report.md b/docs/en/templates/examples/financial-report.md
new file mode 100644
index 0000000..c3f8796
--- /dev/null
+++ b/docs/en/templates/examples/financial-report.md
@@ -0,0 +1,344 @@
+# Financial Report Analysis
+
+Complete guide for extracting financial information from earnings reports and SEC filings.
+
+---
+
+## Scenario
+
+You have a financial document and want to:
+- Extract earnings metrics (revenue, EPS, growth)
+- Identify risk factors
+- Map ownership structures
+- Create event timelines
+
+---
+
+## Recommended Templates by Task
+
+### Earnings Summary
+
+**Template:** `finance/earnings_summary`
+
+Best for quarterly/annual earnings reports, 10-Q, 10-K filings.
+
+**Extracts:**
+- Revenue and net income
+- EPS (basic and diluted)
+- YoY and QoQ growth rates
+- Segment performance
+- Forward guidance
+
+---
+
+### Risk Factors
+
+**Template:** `finance/risk_factor_set`
+
+Best for risk assessment sections of SEC filings.
+
+**Extracts:**
+- Risk categories
+- Risk descriptions
+- Impact assessments
+
+---
+
+### Ownership Structure
+
+**Template:** `finance/ownership_graph`
+
+Best for mapping subsidiaries, investments, and corporate structures.
+
+**Extracts:**
+- Subsidiary relationships
+- Ownership percentages
+- Investment entities
+
+---
+
+## Complete Workflow: Earnings Analysis
+
+### Step 1: Extract Earnings Data
+
+=== "CLI"
+
+ ```bash
+ he parse earnings_10k.md -t finance/earnings_summary -l en -o ./earnings/
+ ```
+
+=== "Python"
+
+ ```python
+ from hyperextract import Template
+
+ # Load report
+ with open("earnings_report.md", "r") as f:
+ report = f.read()
+
+ # Create template
+ ka = Template.create("finance/earnings_summary", "en")
+
+ # Extract
+ result = ka.parse(report)
+
+ # Access data
+ print(f"Revenue: ${result.data.revenue:,.0f}")
+ print(f"EPS: ${result.data.eps:.2f}")
+ print(f"YoY Growth: {result.data.yoy_growth}%")
+ ```
+
+**Example Output:**
+```python
+{
+ "revenue": 1234567890,
+ "net_income": 98765432,
+ "eps": 2.45,
+ "eps_diluted": 2.40,
+ "yoy_growth": 15.3,
+ "qoq_growth": 3.2,
+ "segments": [
+ {"name": "Cloud Services", "revenue": 500000000},
+ {"name": "Hardware", "revenue": 734567890}
+ ],
+ "guidance": {
+ "next_quarter_revenue": "$1.3B - $1.4B",
+ "full_year_eps": "$10.00 - $11.00"
+ }
+}
+```
+
+---
+
+### Step 2: Extract Risk Factors
+
+> **Note:** The following steps assume you used the Python approach in Step 1. If you used CLI, load the result with `ka.load("./earnings/")`.
+
+```python
+# Extract risks
+risk_ka = Template.create("finance/risk_factor_set", "en")
+risk_result = risk_ka.parse(report)
+
+print(f"\nIdentified {len(risk_result.data.items)} risk factors:")
+for risk in risk_result.data.items:
+ print(f"\n[{risk.category}] {risk.description[:100]}...")
+```
+
+---
+
+### Step 3: Save and Compare
+
+```python
+# Save earnings data
+result.dump("./earnings_q3_2024/")
+
+# Later, compare quarters
+from pathlib import Path
+import json
+
+def compare_quarters(q1_path, q2_path):
+ """Compare earnings between two quarters."""
+ q1_data = json.load(open(Path(q1_path) / "data.json"))
+ q2_data = json.load(open(Path(q2_path) / "data.json"))
+
+ revenue_change = ((q2_data["revenue"] - q1_data["revenue"])
+ / q1_data["revenue"] * 100)
+
+ print(f"Revenue Change: {revenue_change:+.1f}%")
+ print(f"Q1: ${q1_data['revenue']:,.0f}")
+ print(f"Q2: ${q2_data['revenue']:,.0f}")
+
+compare_quarters("./earnings_q2_2024/", "./earnings_q3_2024/")
+```
+
+---
+
+## Ownership Structure Analysis
+
+### Extract Corporate Structure
+
+```python
+from hyperextract import Template
+
+# Analyze ownership
+ka = Template.create("finance/ownership_graph", "en")
+result = ka.parse(ownership_report)
+
+# Visualize structure
+result.build_index()
+result.show()
+
+# Query ownership
+response = result.chat("What subsidiaries does the company own 100%?")
+print(response.content)
+```
+
+**Example Output:**
+```python
+# Entities
+[
+ {"name": "Parent Corp", "type": "holding_company"},
+ {"name": "Subsidiary A", "type": "subsidiary"},
+ {"name": "Joint Venture B", "type": "joint_venture"}
+]
+
+# Relations
+[
+ {"source": "Parent Corp", "target": "Subsidiary A",
+ "type": "owns", "percentage": 100},
+ {"source": "Parent Corp", "target": "Joint Venture B",
+ "type": "owns", "percentage": 51}
+]
+```
+
+---
+
+## Financial Event Timeline
+
+### Track Financial Events
+
+```python
+# Extract event timeline
+ka = Template.create("finance/event_timeline", "en")
+result = ka.parse(report)
+
+# Show timeline
+for edge in result.edges:
+ if hasattr(edge, 'time'):
+ print(f"{edge.time}: {edge.source} - {edge.type} - {edge.target}")
+```
+
+**Example Events:**
+- Product launches
+- Acquisition announcements
+- Dividend declarations
+- Management changes
+
+---
+
+## Comparison Table
+
+| Template | Best For | Output |
+|----------|----------|--------|
+| `earnings_summary` | Financial metrics | Structured model |
+| `risk_factor_set` | Risk assessment | Unique risk items |
+| `ownership_graph` | Corporate structure | Entity network |
+| `event_timeline` | Financial events | Temporal graph |
+| `sentiment_model` | Market sentiment | Sentiment analysis |
+
+---
+
+## Batch Processing Multiple Reports
+
+```python
+"""Batch process financial reports."""
+
+from hyperextract import Template
+from pathlib import Path
+import pandas as pd
+
+def batch_extract_reports(report_dir, output_dir):
+ """Extract data from multiple financial reports."""
+
+ ka = Template.create("finance/earnings_summary", "en")
+ results = []
+
+ for report_file in Path(report_dir).glob("*.md"):
+ print(f"Processing {report_file.name}...")
+
+ text = report_file.read_text()
+ result = ka.parse(text)
+
+ # Save individual
+ output_path = Path(output_dir) / report_file.stem
+ result.dump(output_path)
+
+ # Collect for aggregation
+ results.append({
+ "file": report_file.name,
+ "revenue": result.data.revenue,
+ "eps": result.data.eps,
+ "yoy_growth": result.data.yoy_growth
+ })
+
+ # Create summary table
+ df = pd.DataFrame(results)
+ df.to_csv(Path(output_dir) / "summary.csv", index=False)
+
+ print(f"\nProcessed {len(results)} reports")
+ print(f"Summary saved to: {output_dir}/summary.csv")
+
+ return df
+
+# Usage
+df = batch_extract_reports("./reports/", "./extracted/")
+```
+
+---
+
+## Tips for Best Results
+
+### 1. Document Types
+
+| Document | Recommended Template |
+|----------|---------------------|
+| 10-K Annual Report | `earnings_summary` + `risk_factor_set` |
+| 10-Q Quarterly | `earnings_summary` |
+| Proxy Statement | `ownership_graph` |
+| Earnings Call Transcript | `sentiment_model` + `event_timeline` |
+| Investor Presentation | `earnings_summary` |
+
+### 2. Language Support
+
+=== "CLI"
+
+ ```bash
+ # US companies (English)
+ he parse report.md -t finance/earnings_summary -l en
+
+ # Chinese companies (中文财报)
+ he parse report.md -t finance/earnings_summary -l zh
+ ```
+
+### 3. Combining Templates
+
+```python
+from hyperextract import Template
+
+# Parse report with multiple templates
+text = open("10k_report.md").read()
+
+# Extract earnings
+earnings = Template.create("finance/earnings_summary", "en").parse(text)
+
+# Extract risks
+risks = Template.create("finance/risk_factor_set", "en").parse(text)
+
+# Save combined
+earnings.dump("./10k_earnings/")
+risks.dump("./10k_risks/")
+```
+
+### 4. Data Validation
+
+```python
+# Check extracted data
+result = ka.parse(report)
+
+def validate_earnings(data):
+ """Validate earnings data."""
+ assert data.revenue > 0, "Revenue must be positive"
+ assert data.eps is not None, "EPS is required"
+ assert -100 < data.yoy_growth < 1000, "Growth seems unreasonable"
+ print("✓ Data validation passed")
+
+validate_earnings(result.data)
+```
+
+---
+
+## See Also
+
+- [Choose by Task](../choosing/by-task.md) — Other financial analysis templates
+- [Finance Templates](../reference/finance.md) — All finance templates
+- [Custom Templates Guide](../../python/guides/custom-templates.md) — Create custom financial templates
diff --git a/docs/en/templates/examples/legal-contract.md b/docs/en/templates/examples/legal-contract.md
new file mode 100644
index 0000000..c738e1b
--- /dev/null
+++ b/docs/en/templates/examples/legal-contract.md
@@ -0,0 +1,429 @@
+# Legal Document Analysis
+
+Complete guide for extracting information from legal contracts and case documents.
+
+---
+
+## Scenario
+
+You have a legal document and want to:
+- Extract contract obligations and deadlines
+- Identify defined terms
+- Create case chronologies
+- Map precedent relationships
+
+---
+
+## Recommended Templates by Task
+
+### Contract Obligations
+
+**Template:** `legal/contract_obligation`
+
+Best for service agreements, NDAs, employment contracts, vendor agreements.
+
+**Extracts:**
+- Party obligations
+- Deadlines and milestones
+- Deliverables
+- Conditions precedent
+- Breach consequences
+
+---
+
+### Defined Terms
+
+**Template:** `legal/defined_term_set`
+
+Best for extracting all capitalized defined terms from contracts.
+
+**Extracts:**
+- Term definitions
+- Cross-references
+- Definition locations
+
+---
+
+### Case Timeline
+
+**Template:** `legal/case_fact_timeline`
+
+Best for litigation chronologies, case summaries.
+
+**Extracts:**
+- Chronological events
+- Party actions
+- Court decisions
+
+---
+
+## Complete Workflow: Contract Analysis
+
+### Step 1: Extract Obligations
+
+=== "CLI"
+
+ ```bash
+ he parse contract.md -t legal/contract_obligation -l en -o ./contract/
+ ```
+
+=== "Python"
+
+ ```python
+ from hyperextract import Template
+
+ # Load contract
+ with open("service_agreement.md", "r") as f:
+ contract = f.read()
+
+ # Create template
+ ka = Template.create("legal/contract_obligation", "en")
+
+ # Extract
+ result = ka.parse(contract)
+
+ print(f"Found {len(result.data.items)} obligations")
+ ```
+
+**Example Output:**
+```python
+{
+ "items": [
+ {
+ "party": "Service Provider",
+ "obligation": "Deliver software module within 30 days",
+ "deadline": "2024-03-15",
+ "deliverable": "Source code and documentation",
+ "conditions": "Upon receipt of payment"
+ },
+ {
+ "party": "Client",
+ "obligation": "Pay milestone payment",
+ "deadline": "2024-03-01",
+ "amount": "$50,000",
+ "conditions": "Upon acceptance of deliverables"
+ }
+ ]
+}
+```
+
+---
+
+### Step 2: Extract Defined Terms
+
+> **Note:** The following steps assume you used the Python approach in Step 1. If you used CLI, load the result with `ka.load("./contract/")`.
+
+```python
+# Extract defined terms
+terms_ka = Template.create("legal/defined_term_set", "en")
+terms_result = terms_ka.parse(contract)
+
+print(f"\nFound {len(terms_result.data.items)} defined terms:")
+for term in terms_result.data.items:
+ print(f"\n{term.term}: {term.definition}")
+```
+
+**Example:**
+```
+"Confidential Information": Any and all non-public, proprietary, or confidential information...
+
+"Deliverables": The software, documentation, and materials to be delivered...
+
+"Effective Date": The date first written above...
+```
+
+---
+
+### Step 3: Build Contract Knowledge Base
+
+```python
+# Build index for querying
+result.build_index()
+
+# Save for future reference
+result.dump("./contract_analysis/")
+
+# Query obligations
+response = result.chat("What are Service Provider's obligations related to data security?")
+print(response.content)
+
+response = result.chat("List all payment milestones and their due dates")
+print(response.content)
+```
+
+---
+
+## Case Analysis Workflow
+
+### Extract Case Timeline
+
+```python
+from hyperextract import Template
+
+# Load case document
+with open("case_summary.md", "r") as f:
+ case = f.read()
+
+# Extract timeline
+ka = Template.create("legal/case_fact_timeline", "en")
+result = ka.parse(case)
+
+# Display chronology
+print("Case Timeline:")
+for edge in sorted(result.edges, key=lambda e: e.time if hasattr(e, 'time') else ''):
+ if hasattr(edge, 'time'):
+ print(f"\n{edge.time}:")
+ print(f" Event: {edge.source}")
+ print(f" Action: {edge.type}")
+ print(f" Party: {edge.target}")
+
+# Visualize
+result.build_index()
+result.show()
+```
+
+**Example Output:**
+```
+2023-01-15:
+ Event: Complaint filed
+ Action: initiated
+ Party: Plaintiff
+
+2023-02-01:
+ Event: Motion to dismiss
+ Action: filed
+ Party: Defendant
+
+2023-03-15:
+ Event: Discovery phase
+ Action: began
+ Party: Both parties
+```
+
+---
+
+## Case Precedent Analysis
+
+### Map Precedent Relationships
+
+```python
+# Extract case citations
+ka = Template.create("legal/case_citation", "en")
+result = ka.parse(legal_opinion)
+
+# Analyze citation network
+print("Cases cited:")
+for node in result.nodes:
+ if node.type == "case":
+ print(f" - {node.name} ({node.citation})")
+ print(f" Principle: {node.principle[:100]}...")
+
+# Visualize precedent network
+result.build_index()
+result.show()
+```
+
+---
+
+## Comparison Table
+
+| Template | Best For | Output |
+|----------|----------|--------|
+| `contract_obligation` | Service agreements, NDAs | List of obligations |
+| `defined_term_set` | Defined terms extraction | Set of term definitions |
+| `case_fact_timeline` | Litigation chronologies | Temporal graph |
+| `case_citation` | Precedent analysis | Citation network |
+| `compliance_list` | Regulatory requirements | Compliance checklist |
+
+---
+
+## Batch Contract Processing
+
+```python
+"""Batch analyze multiple contracts."""
+
+from hyperextract import Template
+from pathlib import Path
+import pandas as pd
+
+def analyze_contract_folder(folder_path, output_dir):
+ """Extract obligations from all contracts in folder."""
+
+ ka = Template.create("legal/contract_obligation", "en")
+ all_obligations = []
+
+ for contract_file in Path(folder_path).glob("*.md"):
+ print(f"Processing {contract_file.name}...")
+
+ text = contract_file.read_text()
+ result = ka.parse(text)
+
+ # Save individual
+ output_path = Path(output_dir) / contract_file.stem
+ result.dump(output_path)
+
+ # Collect obligations
+ for obl in result.data.items:
+ all_obligations.append({
+ "contract": contract_file.name,
+ "party": obl.party,
+ "obligation": obl.obligation,
+ "deadline": getattr(obl, 'deadline', 'N/A'),
+ "deliverable": getattr(obl, 'deliverable', 'N/A')
+ })
+
+ # Create summary
+ df = pd.DataFrame(all_obligations)
+ df.to_csv(Path(output_dir) / "all_obligations.csv", index=False)
+
+ print(f"\nProcessed {len(list(Path(folder_path).glob('*.md')))} contracts")
+ print(f"Found {len(all_obligations)} total obligations")
+
+ return df
+
+# Usage
+df = analyze_contract_folder("./contracts/", "./contract_analysis/")
+
+# Find upcoming deadlines
+from datetime import datetime
+df['deadline'] = pd.to_datetime(df['deadline'], errors='coerce')
+upcoming = df[df['deadline'] > datetime.now()].sort_values('deadline')
+print("\nUpcoming deadlines:")
+print(upcoming[['contract', 'party', 'deadline', 'obligation']].head(10))
+```
+
+---
+
+## Tips for Best Results
+
+### 1. Document Preparation
+
+- Convert PDFs to clean Markdown
+- Remove headers/footers/page numbers
+- Preserve paragraph structure
+- Keep section headings
+
+### 2. Contract Types
+
+| Contract Type | Primary Template | Secondary Template |
+|--------------|------------------|-------------------|
+| Service Agreement | `contract_obligation` | `defined_term_set` |
+| NDA | `contract_obligation` | `defined_term_set` |
+| Employment Contract | `contract_obligation` | `defined_term_set` |
+| License Agreement | `contract_obligation` | `defined_term_set` |
+| Litigation Summary | `case_fact_timeline` | `case_citation` |
+| Regulatory Document | `compliance_list` | - |
+
+### 3. Multi-Language Support
+
+=== "CLI"
+
+ ```bash
+ # English contracts
+ he parse contract.md -t legal/contract_obligation -l en
+
+ # Chinese contracts (中文合同)
+ he parse contract.md -t legal/contract_obligation -l zh
+ ```
+
+### 4. Combining Templates
+
+```python
+# Comprehensive contract analysis
+text = open("contract.md").read()
+
+# Extract obligations
+obligations = Template.create("legal/contract_obligation", "en").parse(text)
+
+# Extract defined terms
+terms = Template.create("legal/defined_term_set", "en").parse(text)
+
+# Save both
+obligations.dump("./contract_obligations/")
+terms.dump("./contract_terms/")
+
+# Cross-reference
+print("\nObligations referencing defined terms:")
+for obl in obligations.data.items:
+ for term in terms.data.items:
+ if term.term.lower() in obl.obligation.lower():
+ print(f" '{term.term}' in: {obl.obligation[:60]}...")
+```
+
+---
+
+## Example: Contract Review Checklist
+
+```python
+"""Automated contract review checklist."""
+
+from hyperextract import Template
+from datetime import datetime
+
+def contract_review_checklist(contract_path):
+ """Generate review checklist from contract."""
+
+ text = open(contract_path).read()
+
+ # Extract obligations
+ obl_ka = Template.create("legal/contract_obligation", "en")
+ obl_result = obl_ka.parse(text)
+
+ # Extract terms
+ terms_ka = Template.create("legal/defined_term_set", "en")
+ terms_result = terms_ka.parse(text)
+
+ print("=" * 60)
+ print("CONTRACT REVIEW CHECKLIST")
+ print("=" * 60)
+
+ # Obligations summary
+ print("\n## OBLIGATIONS SUMMARY")
+ print(f"Total obligations: {len(obl_result.data.items)}")
+
+ party_obligations = {}
+ for obl in obl_result.data.items:
+ party = obl.party
+ if party not in party_obligations:
+ party_obligations[party] = []
+ party_obligations[party].append(obl)
+
+ for party, obligations in party_obligations.items():
+ print(f"\n{party}: {len(obligations)} obligations")
+ for obl in obligations[:3]: # Show first 3
+ deadline = getattr(obl, 'deadline', 'No deadline')
+ print(f" - {obl.obligation[:50]}... (Due: {deadline})")
+
+ # Critical dates
+ print("\n## CRITICAL DATES")
+ deadlines = [obl.deadline for obl in obl_result.data.items
+ if hasattr(obl, 'deadline') and obl.deadline]
+ for deadline in sorted(deadlines)[:5]:
+ print(f" - {deadline}")
+
+ # Key terms
+ print("\n## KEY DEFINED TERMS")
+ for term in terms_result.data.items[:10]:
+ print(f" - {term.term}")
+
+ # Risk flags
+ print("\n## RISK FLAGS TO REVIEW")
+ risk_keywords = ['unlimited', 'perpetual', 'sole discretion', 'waiver', 'indemnify']
+ for obl in obl_result.data.items:
+ for keyword in risk_keywords:
+ if keyword.lower() in obl.obligation.lower():
+ print(f" ⚠ Contains '{keyword}': {obl.obligation[:60]}...")
+
+ print("\n" + "=" * 60)
+
+# Usage
+contract_review_checklist("service_agreement.md")
+```
+
+---
+
+## See Also
+
+- [Choose by Task](../choosing/by-task.md) — Other legal analysis templates
+- [Legal Templates](../reference/legal.md) — All legal templates
+- [Custom Templates Guide](../../python/guides/custom-templates.md) — Create custom legal templates
diff --git a/docs/en/templates/examples/research-paper.md b/docs/en/templates/examples/research-paper.md
new file mode 100644
index 0000000..19a5eb6
--- /dev/null
+++ b/docs/en/templates/examples/research-paper.md
@@ -0,0 +1,332 @@
+# Research Paper Analysis
+
+Complete guide for extracting knowledge from research papers.
+
+---
+
+## Scenario
+
+You have a research paper and want to:
+- Extract key concepts and their definitions
+- Map relationships between concepts
+- Build a queryable knowledge base
+- Visualize the concept network
+
+---
+
+## Recommended Template
+
+### `general/concept_graph`
+
+Best for extracting concepts, methods, and their relationships from academic papers.
+
+**Why this template?**
+- Automatically identifies key concepts
+- Maps "is-a", "uses", "relates-to" relationships
+- Supports hierarchical structures
+- Optimized for academic language
+
+---
+
+## Complete Workflow
+
+### Step 1: Extract Knowledge
+
+=== "CLI"
+
+ ```bash
+ he parse paper.md -t general/concept_graph -l en -o ./paper_kb/
+ ```
+
+=== "Python"
+
+ ```python
+ from hyperextract import Template
+
+ # Load paper
+ with open("paper.md", "r") as f:
+ paper_text = f.read()
+
+ # Create template
+ ka = Template.create("general/concept_graph", "en")
+
+ # Extract
+ result = ka.parse(paper_text)
+
+ print(f"Extracted {len(result.nodes)} concepts")
+ print(f"Extracted {len(result.edges)} relationships")
+ ```
+
+**Example Output:**
+```python
+{
+ "entities": [
+ {"name": "Transformer", "type": "model"},
+ {"name": "Attention Mechanism", "type": "concept"},
+ {"name": "BLEU Score", "type": "metric"}
+ ],
+ "relations": [
+ {"source": "Transformer", "target": "Attention Mechanism", "type": "uses"},
+ {"source": "Transformer", "target": "BLEU Score", "type": "achieves"}
+ ]
+}
+```
+
+---
+
+### Step 2: Explore Results
+
+> **Note:** The following steps assume you used the Python approach in Step 1. If you used CLI, load the result with `ka.load("./paper_kb/")`.
+
+```python
+# List all concepts
+print("\nConcepts found:")
+for node in result.nodes:
+ print(f" - {node.name} ({node.type})")
+ if hasattr(node, 'description'):
+ print(f" {node.description[:100]}...")
+
+# List relationships
+print("\nRelationships:")
+for edge in result.edges:
+ print(f" - {edge.source} → {edge.target}: {edge.type}")
+```
+
+**Example Output:**
+```
+Concepts found:
+ - Transformer (architecture)
+ A neural network architecture based on self-attention mechanisms...
+ - Attention Mechanism (method)
+ A technique allowing models to focus on relevant parts of input...
+ - BERT (model)
+ Bidirectional Encoder Representations from Transformers...
+
+Relationships:
+ - BERT → Transformer: implements
+ - Transformer → Attention Mechanism: uses
+ - BERT → NLP: applied_in
+```
+
+---
+
+### Step 3: Build Searchable Index
+
+```python
+# Build index for search and chat
+result.build_index()
+
+# Save for later use
+result.dump("./paper_kb/")
+```
+
+---
+
+### Step 4: Visualize
+
+```python
+# Open interactive visualization
+result.show()
+```
+
+This opens an interactive browser view where you can:
+- Explore the concept graph visually
+- Search for specific concepts
+- Ask questions about the paper
+
+---
+
+### Step 5: Query
+
+```python
+# Semantic search
+nodes, edges = result.search("attention mechanisms", top_k=5)
+
+print("Related concepts:")
+for node in nodes:
+ print(f" - {node.name}")
+
+# Chat interface
+response = result.chat("What is the main contribution of this paper?")
+print(response.content)
+
+response = result.chat("How does the proposed method compare to previous approaches?")
+print(response.content)
+```
+
+---
+
+## Alternative Templates
+
+### Document Structure
+
+If you need the paper's outline and structure:
+
+=== "CLI"
+
+ ```bash
+ he parse paper.md -t general/doc_structure -l en -o ./structure/
+ ```
+
+**Extracts:**
+- Section headings
+- Key points per section
+- Paper organization
+
+### Knowledge Graph
+
+For broader domain knowledge beyond just concepts:
+
+=== "CLI"
+
+ ```bash
+ he parse paper.md -t general/graph -l en -o ./knowledge/
+ ```
+
+**Difference from concept_graph:**
+- Broader entity types (people, organizations, methods)
+- General relationships
+- Less focused on conceptual definitions
+
+### Workflow Graph
+
+If the paper describes a process or algorithm:
+
+=== "CLI"
+
+ ```bash
+ he parse paper.md -t general/workflow_graph -l en -o ./workflow/
+ ```
+
+**Extracts:**
+- Process steps
+- Decision points
+- Flow relationships
+
+---
+
+## Comparison Table
+
+| Template | Best For | Output |
+|----------|----------|--------|
+| `concept_graph` | Research papers with concepts/definitions | Concept network |
+| `graph` | Broader domain knowledge | General entity network |
+| `doc_structure` | Document outline | Hierarchical structure |
+| `workflow_graph` | Process/method descriptions | Process flow |
+
+---
+
+## Tips for Best Results
+
+### 1. Document Preparation
+
+- Remove headers/footers
+- Ensure clean Markdown or plain text
+- Keep equations as LaTeX or plain text
+
+### 2. Language Selection
+
+=== "CLI"
+
+ ```bash
+ # English paper
+ he parse paper.md -t general/concept_graph -l en
+
+ # Chinese paper
+ he parse paper.md -t general/concept_graph -l zh
+ ```
+
+### 3. Processing Long Papers
+
+For papers over 5000 words:
+
+```python
+# Option 1: Use RAG method
+ka = Template.create("method/graph_rag")
+result = ka.parse(paper_text)
+
+# Option 2: Process by sections
+sections = split_paper_into_sections(paper_text)
+ka = Template.create("general/concept_graph", "en")
+result = ka.parse(sections[0])
+
+for section in sections[1:]:
+ result.feed_text(section)
+```
+
+### 4. Post-Processing
+
+```python
+# Filter by concept type
+concepts = [n for n in result.nodes if n.type == "concept"]
+methods = [n for n in result.nodes if n.type == "method"]
+
+# Find central concepts (most connected)
+from collections import Counter
+edge_counts = Counter([e.source for e in result.edges] +
+ [e.target for e in result.edges])
+top_concepts = edge_counts.most_common(5)
+```
+
+---
+
+## Example: Complete Analysis Script
+
+```python
+"""Complete research paper analysis workflow."""
+
+from hyperextract import Template
+from pathlib import Path
+
+def analyze_paper(paper_path, output_dir="./paper_analysis/"):
+ """Analyze a research paper and create a knowledge base."""
+
+ # Load paper
+ text = Path(paper_path).read_text()
+
+ # Extract concepts
+ print("Extracting concepts...")
+ ka = Template.create("general/concept_graph", "en")
+ result = ka.parse(text)
+
+ print(f"Found {len(result.nodes)} concepts")
+ print(f"Found {len(result.edges)} relationships")
+
+ # Build index
+ print("Building search index...")
+ result.build_index()
+
+ # Save
+ output_path = Path(output_dir)
+ output_path.mkdir(parents=True, exist_ok=True)
+ result.dump(output_path)
+
+ # Generate summary
+ print("\n=== Paper Summary ===")
+ response = result.chat("Summarize the main contributions in 3 sentences")
+ print(response.content)
+
+ print("\n=== Key Concepts ===")
+ for node in result.nodes[:5]:
+ print(f"- {node.name}")
+
+ print(f"\nSaved to: {output_path}")
+ print(f"\nTo explore: result.show()")
+
+ return result
+
+# Usage
+if __name__ == "__main__":
+ result = analyze_paper("paper.md")
+
+ # Interactive exploration
+ result.show()
+```
+
+---
+
+## See Also
+
+- [Choose by Task](../choosing/by-task.md) — Other task templates
+- [Concept Graph Template](../reference/general.md) — Template details
+- [Python Quickstart](../../python/quickstart.md) — Getting started with Python SDK
diff --git a/docs/en/templates/how-to-choose.md b/docs/en/templates/how-to-choose.md
index 4165f56..4f2eb56 100644
--- a/docs/en/templates/how-to-choose.md
+++ b/docs/en/templates/how-to-choose.md
@@ -34,7 +34,7 @@ graph TD
| Template | Output | Best For |
|----------|--------|----------|
| `general/biography_graph` | Temporal graph | Life stories, profiles |
-| `general/base_model` | Model | Person summaries |
+| `general/model` | Model | Person summaries |
**Example:**
```bash
@@ -46,7 +46,7 @@ he parse bio.md -t general/biography_graph -l en -o ./out/
| Template | Output | Best For |
|----------|--------|----------|
| `general/concept_graph` | Graph | Research papers |
-| `general/knowledge_graph` | Graph | Technical documents |
+| `general/graph` | Graph | Technical documents |
| `general/doc_structure` | Model | Document outlines |
### Financial
@@ -55,7 +55,7 @@ he parse bio.md -t general/biography_graph -l en -o ./out/
|----------|--------|----------|
| `finance/earnings_summary` | Model | Earnings reports |
| `finance/ownership_graph` | Graph | Company structures |
-| `finance/event_timeline` | Temporal | Financial events |
+| `finance/event_timeline` | Graph (Temporal) | Financial events |
| `finance/risk_factor_set` | Set | Risk assessments |
### Legal
@@ -64,7 +64,7 @@ he parse bio.md -t general/biography_graph -l en -o ./out/
|----------|--------|----------|
| `legal/contract_obligation` | List | Contract terms |
| `legal/case_citation` | Graph | Legal precedents |
-| `legal/case_fact_timeline` | Temporal | Case chronologies |
+| `legal/case_fact_timeline` | Graph (Temporal) | Case chronologies |
### Medical
@@ -112,7 +112,7 @@ ka = Template.create("legal/defined_term_set", "en")
```python
# General knowledge
-ka = Template.create("general/knowledge_graph", "en")
+ka = Template.create("general/graph", "en")
# Company ownership
ka = Template.create("finance/ownership_graph", "en")
@@ -227,7 +227,7 @@ ka = Template.create("method/graph_rag")
ka = Template.create("method/itext2kg")
```
-→ [Choosing Methods](../python/guides/choosing-methods.md)
+→ [Using Methods](../python/guides/using-methods.md)
---
@@ -259,6 +259,6 @@ print(cfg.description)
## See Also
-- [Browse All Templates](browse.md)
+- [Template Overview](reference/overview.md)
- [Template Library](index.md)
- [Custom Templates](../python/guides/custom-templates.md)
diff --git a/docs/en/templates/index.md b/docs/en/templates/index.md
index 623accf..be40fcd 100644
--- a/docs/en/templates/index.md
+++ b/docs/en/templates/index.md
@@ -1,211 +1,141 @@
# Template Library
-Browse and choose from 80+ domain-specific extraction templates.
+Choose a template based on what you want to extract.
---
-## What Are Templates?
+## I want to analyze...
-Templates are pre-configured extraction setups that combine:
-- **Auto-Type** — Output data structure
-- **Prompts** — Optimized for specific domains
-- **Schema** — Field definitions for your use case
-- **Guidelines** — Extraction rules
+<div class="grid cards" markdown>
----
+- :material-file-document:{ .lg .middle } **Research Papers**
-## Template Categories
+ ---
-<div class="grid cards" markdown>
+ Extract concepts, methods, results, and relationships
+
+ - [Concept Graph](examples/research-paper.md) — *Recommended*
+ - [Knowledge Graph](examples/research-paper.md#knowledge-graph)
+ - [Document Structure](examples/research-paper.md#document-structure)
-- :material-folder:{ .lg .middle } __General__
+- :material-account:{ .lg .middle } **Biographies & Profiles**
---
- Base types and common extraction tasks
-
- - Biography graphs
- - Knowledge graphs
- - Concept extraction
-
- [:octicons-arrow-right-24: Browse](general/index.md)
+ Extract life events, relationships, and timeline
-- :material-chart-line:{ .lg .middle } __Finance__
+ - [Biography Graph](reference/general.md) — *Recommended*
+ - [Person Summary](reference/general.md)
+
+- :material-chart-line:{ .lg .middle } **Financial Reports**
---
- Financial document analysis
-
- - Earnings summaries
- - Risk factors
- - Ownership structures
-
- [:octicons-arrow-right-24: Browse](finance.md)
+ Extract earnings, risks, and ownership structures
+
+ - [Earnings Summary](examples/financial-report.md) — *Recommended*
+ - [Risk Factors](examples/financial-report.md#risk-factors)
+ - [Ownership Graph](examples/financial-report.md#ownership-structure)
-- :material-scale-balance:{ .lg .middle } __Legal__
+- :material-scale-balance:{ .lg .middle } **Legal Documents**
---
- Legal document processing
-
- - Contract obligations
- - Case citations
- - Compliance lists
-
- [:octicons-arrow-right-24: Browse](legal.md)
+ Extract obligations, cases, and compliance items
-- :material-hospital:{ .lg .middle } __Medical__
+ - [Contract Obligations](examples/legal-contract.md) — *Recommended*
+ - [Case Timeline](examples/legal-contract.md#case-timeline)
+ - [Defined Terms](examples/legal-contract.md#defined-terms)
+
+- :material-hospital:{ .lg .middle } **Medical Records**
---
- Medical text analysis
-
- - Anatomy graphs
- - Drug interactions
- - Treatment plans
-
- [:octicons-arrow-right-24: Browse](medicine.md)
+ Extract symptoms, treatments, and timelines
+
+ - [Hospital Timeline](reference/medicine.md) — *Recommended*
+ - [Drug Interactions](reference/medicine.md)
+ - [Discharge Summary](reference/medicine.md)
-- :material-leaf:{ .lg .middle } __TCM__
+- :material-leaf:{ .lg .middle } **TCM Texts**
---
- Traditional Chinese Medicine
-
- - Herb properties
- - Formula composition
- - Meridian graphs
-
- [:octicons-arrow-right-24: Browse](tcm.md)
+ Extract herb properties and formula compositions
-- :material-factory:{ .lg .middle } __Industry__
+ - [Herb Properties](reference/tcm.md) — *Recommended*
+ - [Formula Composition](reference/tcm.md)
+ - [Meridian Graph](reference/tcm.md)
+
+- :material-factory:{ .lg .middle } **Industrial Documents**
---
- Industrial documentation
-
- - Equipment topology
- - Safety controls
- - Operation flows
-
- [:octicons-arrow-right-24: Browse](industry.md)
+ Extract equipment, safety, and operation flows
+
+ - [Equipment Topology](reference/industry.md) — *Recommended*
+ - [Safety Controls](reference/industry.md)
+ - [Operation Flow](reference/industry.md)
</div>
---
-## Quick Selection Guide
-
-| I want to extract... | Use Template |
-|---------------------|--------------|
-| Person's life story | `general/biography_graph` |
-| Research paper concepts | `general/concept_graph` |
-| Company earnings | `finance/earnings_summary` |
-| Contract terms | `legal/contract_obligation` |
-| Medical symptoms | `medicine/symptom_list` |
-| Chinese herbs | `tcm/herb_property` |
-| Equipment specs | `industry/equipment_topology` |
-
----
+## Not sure what to choose?
-## How to Choose
+**By task type:**
-### By Document Type
+| Task | Recommended Template |
+|------|---------------------|
+| Summarize a document | `general/model` |
+| Extract a list of items | `general/list` |
+| Build a knowledge network | `general/graph` |
+| Create a timeline | `general/base_temporal_graph` |
-| Document | Template Category |
-|----------|-------------------|
-| Biographies, profiles | General |
-| Financial reports, 10-K | Finance |
-| Contracts, legal briefs | Legal |
-| Medical records, papers | Medical |
-| TCM texts, prescriptions | TCM |
-| Manuals, procedures | Industry |
+→ [More task-based guidance](choosing/by-task.md)
-### By Output Type
+**By output type:**
-| Need | Auto-Type | Example Templates |
-|------|-----------|-------------------|
-| Summary report | AutoModel | `earnings_summary`, `discharge_instruction` |
-| List of items | AutoList | `compliance_list`, `symptom_list` |
-| Unique items | AutoSet | `risk_factor_set`, `defined_term_set` |
-| Network/Graph | AutoGraph | `knowledge_graph`, `ownership_graph` |
-| Timeline | AutoTemporalGraph | `event_timeline`, `biography_graph` |
+| Output | Auto-Type | Use When... |
+|--------|-----------|-------------|
+| Structured summary | AutoModel | Need a report |
+| Network/Graph | AutoGraph | Need relationships |
+| Timeline | AutoTemporalGraph | Need time sequence |
-→ [Complete Selection Guide](how-to-choose.md)
+→ [More output type guidance](choosing/by-output.md)
---
-## Using Templates
-
-### CLI
+## Quick Start
```bash
-# List available
+# List all templates
he list template
# Use a template
-he parse doc.md -t general/biography_graph -o ./out/ -l en
+he parse document.md -t general/biography_graph -l en -o ./output/
```
-### Python
-
```python
from hyperextract import Template
-# Create from preset
+# Create template
ka = Template.create("general/biography_graph", "en")
-# List all
-all_templates = Template.list()
-
-# Filter by domain
-finance = Template.list(filter_by_tag="finance")
-```
-
----
-
-## Template Properties
-
-Each template has:
-
-- **Name** — Unique identifier
-- **Type** — Auto-Type (graph, list, model, etc.)
-- **Tags** — Domain categorization
-- **Languages** — Supported languages (zh, en)
-- **Description** — What it extracts
-
-### Viewing Template Details
-
-```python
-from hyperextract import Template
-
-# Get template info
-cfg = Template.get("general/biography_graph")
-
-print(cfg.name) # biography_graph
-print(cfg.type) # temporal_graph
-print(cfg.tags) # ['general', 'biography']
-print(cfg.description) # Description text
+# Extract
+result = ka.parse(text)
```
---
## Browse All Templates
-→ [Complete Template Browser](browse.md)
+→ [Complete Template Reference](reference/overview.md)
---
-## Creating Custom Templates
+## Create Custom Templates
-Need something specific? Create your own template:
+Need something specific? Learn to create your own:
→ [Custom Templates Guide](../python/guides/custom-templates.md)
-
----
-
-## Template Format Reference
-
-Learn about the YAML structure:
-
-→ [Template Format](../concepts/templates-format.md)
diff --git a/docs/en/templates/finance.md b/docs/en/templates/reference/finance.md
similarity index 65%
rename from docs/en/templates/finance.md
rename to docs/en/templates/reference/finance.md
index 80526e3..423a602 100644
--- a/docs/en/templates/finance.md
+++ b/docs/en/templates/reference/finance.md
@@ -24,6 +24,7 @@ Finance templates are optimized for extracting structured information from finan
- Earnings call transcripts
**Fields**:
+
| Field | Type | Description |
|-------|------|-------------|
| `company_name` | str | Company name |
@@ -33,19 +34,21 @@ Finance templates are optimized for extracting structured information from finan
| `eps` | float | Earnings per share |
| `yoy_growth` | float | Year-over-year growth |
-**Example:**
-```bash
-he parse 10q.md -t finance/earnings_summary -l en
-```
+=== "CLI"
-**Python:**
-```python
-ka = Template.create("finance/earnings_summary", "en")
-result = ka.parse(earnings_text)
+ ```bash
+ he parse 10q.md -t finance/earnings_summary -l en
+ ```
-print(f"Revenue: ${result.data.revenue}B")
-print(f"EPS: ${result.data.eps}")
-```
+=== "Python"
+
+ ```python
+ ka = Template.create("finance/earnings_summary", "en")
+ result = ka.parse(earnings_text)
+
+ print(f"Revenue: ${result.data.revenue}B")
+ print(f"EPS: ${result.data.eps}")
+ ```
---
@@ -70,18 +73,23 @@ print(f"EPS: ${result.data.eps}")
- `controls` — Control relationships
- `subsidiary_of` — Subsidiary relationships
-**Example:**
-```bash
-he parse proxy.md -t finance/ownership_graph -l en
-```
+=== "CLI"
-**Visualization:**
-```python
-# Build index for interactive search/chat in visualization
-result.build_index()
+ ```bash
+ he parse proxy.md -t finance/ownership_graph -l en
+ ```
-result.show() # Shows ownership network with interactive features
-```
+=== "Python"
+
+ ```python
+ ka = Template.create("finance/ownership_graph", "en")
+ result = ka.parse(proxy_statement)
+
+ # Build index for interactive search/chat in visualization
+ result.build_index()
+
+ result.show() # Shows ownership network with interactive features
+ ```
---
@@ -97,14 +105,27 @@ result.show() # Shows ownership network with interactive features
- Market events
**Features**:
+
- Event dates
- Event types (merger, acquisition, IPO, etc.)
- Related entities
-**Example:**
-```bash
-he parse history.md -t finance/event_timeline -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse history.md -t finance/event_timeline -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("finance/event_timeline", "en")
+ result = ka.parse(history_text)
+
+ print(f"Events: {len(result.nodes)}")
+ for node in result.nodes:
+ print(f" - {node.name}")
+ ```
---
@@ -119,22 +140,22 @@ he parse history.md -t finance/event_timeline -l en
- Due diligence reports
- Risk assessments
-**Example:**
-```bash
-he parse 10k.md -t finance/risk_factor_set -l en
-```
+=== "CLI"
-**Output:**
-```python
-{
- "items": [
- "Market volatility",
- "Regulatory changes",
- "Competition",
- "Supply chain risks"
- ]
-}
-```
+ ```bash
+ he parse 10k.md -t finance/risk_factor_set -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("finance/risk_factor_set", "en")
+ result = ka.parse(risk_section)
+
+ print(f"Found {len(result.data.items)} risk factors")
+ for risk in result.data.items:
+ print(f" - {risk}")
+ ```
---
@@ -150,16 +171,30 @@ he parse 10k.md -t finance/risk_factor_set -l en
- Social media sentiment
**Fields**:
+
| Field | Type | Description |
|-------|------|-------------|
| `sentiment` | str | Overall sentiment (positive/negative/neutral) |
| `confidence` | float | Confidence score |
| `key_points` | list[str] | Key sentiment indicators |
-**Example:**
-```bash
-he parse article.md -t finance/sentiment_model -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse article.md -t finance/sentiment_model -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("finance/sentiment_model", "en")
+ result = ka.parse(article_text)
+
+ print(f"Sentiment: {result.data.sentiment}")
+ print(f"Confidence: {result.data.confidence}")
+ for point in result.data.key_points:
+ print(f" - {point}")
+ ```
---
@@ -235,6 +270,6 @@ These templates work well with:
## See Also
-- [Browse All Templates](browse.md)
-- [How to Choose](how-to-choose.md)
-- [General Templates](general/index.md)
+- [Template Overview](overview.md)
+- [How to Choose](../how-to-choose.md)
+- [General Templates](general.md)
diff --git a/docs/en/templates/general/index.md b/docs/en/templates/reference/general.md
similarity index 58%
rename from docs/en/templates/general/index.md
rename to docs/en/templates/reference/general.md
index 6a0929b..166de04 100644
--- a/docs/en/templates/general/index.md
+++ b/docs/en/templates/reference/general.md
@@ -20,10 +20,20 @@ General templates provide fundamental extraction capabilities suitable for a wid
**Use for**: Simple summaries, form-like data
-**Example:**
-```bash
-he parse doc.md -t general/base_model -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse doc.md -t general/model -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/model", "en")
+ result = ka.parse(doc_text)
+
+ print(result.data)
+ ```
**Output Schema**:
```python
@@ -43,10 +53,21 @@ he parse doc.md -t general/base_model -l en
**Use for**: Sequences, rankings
-**Example:**
-```bash
-he parse doc.md -t general/base_list -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse doc.md -t general/list -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/list", "en")
+ result = ka.parse(doc_text)
+
+ for item in result.data.items:
+ print(f"- {item}")
+ ```
**Output Schema**:
```python
@@ -65,10 +86,21 @@ he parse doc.md -t general/base_list -l en
**Use for**: Tags, categories, keywords
-**Example:**
-```bash
-he parse doc.md -t general/base_set -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse doc.md -t general/set -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/set", "en")
+ result = ka.parse(doc_text)
+
+ for item in result.data.items:
+ print(f"- {item}")
+ ```
**Output Schema**:
```python
@@ -87,10 +119,21 @@ he parse doc.md -t general/base_set -l en
**Use for**: Knowledge graphs, networks
-**Example:**
-```bash
-he parse doc.md -t general/base_graph -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse doc.md -t general/graph -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/graph", "en")
+ result = ka.parse(doc_text)
+
+ print(f"Entities: {len(result.nodes)}")
+ print(f"Relations: {len(result.edges)}")
+ ```
**Output Schema**:
```python
@@ -117,10 +160,28 @@ he parse doc.md -t general/base_graph -l en
**Best for**: Biographies, profiles, memoirs
-**Example Use:**
-```bash
-he parse tesla_bio.md -t general/biography_graph -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse tesla_bio.md -t general/biography_graph -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/biography_graph", "en")
+ result = ka.parse(biography_text)
+
+ # Build index for interactive features
+ result.build_index()
+
+ # Visualize life events (with search/chat capabilities)
+ result.show()
+
+ # Ask questions
+ response = result.chat("What were the major achievements?")
+ print(response.content)
+ ```
**Features**:
- Extracts people, places, events
@@ -155,10 +216,25 @@ he parse tesla_bio.md -t general/biography_graph -l en
**Best for**: Research papers, technical documents, articles
-**Example Use:**
-```bash
-he parse paper.md -t general/concept_graph -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse paper.md -t general/concept_graph -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/concept_graph", "en")
+ result = ka.parse(paper_text)
+
+ # Get concept map
+ for node in result.nodes:
+ print(f"Concept: {node.name}")
+
+ for edge in result.edges:
+ print(f"{edge.source} → {edge.target}")
+ ```
**Features**:
- Concept identification
@@ -175,10 +251,24 @@ he parse paper.md -t general/concept_graph -l en
**Best for**: Long documents, reports, books
-**Example Use:**
-```bash
-he parse report.md -t general/doc_structure -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse report.md -t general/doc_structure -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/doc_structure", "en")
+ result = ka.parse(report_text)
+
+ print(f"Title: {result.data.title}")
+ print(f"Sections: {len(result.data.sections)}")
+
+ for section in result.data.sections:
+ print(f"- {section.heading}")
+ ```
**Features**:
- Section identification
@@ -195,10 +285,28 @@ he parse report.md -t general/doc_structure -l en
**Best for**: Procedures, processes, workflows
-**Example Use:**
-```bash
-he parse procedure.md -t general/workflow_graph -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse procedure.md -t general/workflow_graph -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/workflow_graph", "en")
+ result = ka.parse(procedure_text)
+
+ # Build index for visualization
+ result.build_index()
+
+ # Visualize workflow
+ result.show()
+
+ # Query workflow
+ response = result.chat("What is the first step?")
+ print(response.content)
+ ```
**Features**:
- Step identification
@@ -228,7 +336,7 @@ he parse procedure.md -t general/workflow_graph -l en
```python
from hyperextract import Template
-ka = Template.create("general/base_model", "en")
+ka = Template.create("general/model", "en")
result = ka.parse("""
Meeting Notes:
Date: January 15, 2024
@@ -275,6 +383,6 @@ for edge in result.edges:
## See Also
-- [Browse All Templates](../browse.md)
+- [Template Overview](overview.md)
- [How to Choose](../how-to-choose.md)
- [Auto-Types](../../concepts/autotypes.md)
diff --git a/docs/en/templates/industry.md b/docs/en/templates/reference/industry.md
similarity index 63%
rename from docs/en/templates/industry.md
rename to docs/en/templates/reference/industry.md
index 263ae44..5d26791 100644
--- a/docs/en/templates/industry.md
+++ b/docs/en/templates/reference/industry.md
@@ -25,27 +25,34 @@ Industry templates are designed for extracting information from industrial docum
- Network layouts
**Entities**:
+
- Equipment (pumps, valves, tanks, etc.)
- Sensors
- Control systems
**Relations**:
+
- `connected_to` — Physical connections
- `controlled_by` — Control relationships
- `monitors` — Monitoring relationships
-**Example:**
-```bash
-he parse system_diagram.md -t industry/equipment_topology -l en
-```
+=== "CLI"
-**Visualization:**
-```python
-# Build index for interactive search/chat in visualization
-result.build_index()
+ ```bash
+ he parse system_diagram.md -t industry/equipment_topology -l en
+ ```
-result.show() # Shows equipment network with interactive features
-```
+=== "Python"
+
+ ```python
+ ka = Template.create("industry/equipment_topology", "en")
+ result = ka.parse(pandid_description)
+
+ # Build index for interactive search/chat in visualization
+ result.build_index()
+
+ result.show() # Shows equipment network with interactive features
+ ```
---
@@ -62,6 +69,7 @@ result.show() # Shows equipment network with interactive features
- Emergency procedures
**Entities**:
+
- Safety functions
- Hazards
- Safeguards
@@ -69,14 +77,30 @@ result.show() # Shows equipment network with interactive features
- Actuators
**Relations**:
+
- `protects_against` — Safeguard-hazard relationship
- `triggers` — Sensor-action relationship
- `implements` — System-function relationship
-**Example:**
-```bash
-he parse safety_manual.md -t industry/safety_control -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse safety_manual.md -t industry/safety_control -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("industry/safety_control", "en")
+ result = ka.parse(safety_text)
+
+ print(f"Safety functions: {len(result.nodes)}")
+ print(f"Protections: {len(result.edges)}")
+
+ # Visualize safety system
+ result.build_index()
+ result.show()
+ ```
---
@@ -93,15 +117,31 @@ he parse safety_manual.md -t industry/safety_control -l en
- Work instructions
**Features**:
+
- Step sequences
- Decision points
- Parallel operations
- Dependencies
-**Example:**
-```bash
-he parse sop.md -t industry/operation_flow -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse sop.md -t industry/operation_flow -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("industry/operation_flow", "en")
+ result = ka.parse(sop_text)
+
+ print(f"Steps: {len(result.nodes)}")
+ print(f"Flow connections: {len(result.edges)}")
+
+ # Visualize operational workflow
+ result.build_index()
+ result.show()
+ ```
---
@@ -117,20 +157,37 @@ he parse sop.md -t industry/operation_flow -l en
- Crisis management protocols
**Entities**:
+
- Emergency types
- Response actions
- Responsible parties
- Resources
**Relations**:
+
- `responds_to` — Action-emergency relationship
- `requires` — Resource requirements
- `notifies` — Notification chain
-**Example:**
-```bash
-he parse emergency_plan.md -t industry/emergency_response -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse emergency_plan.md -t industry/emergency_response -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("industry/emergency_response", "en")
+ result = ka.parse(emergency_text)
+
+ print(f"Emergency types: {len(result.nodes)}")
+ print(f"Response actions: {len(result.edges)}")
+
+ # Visualize emergency response plan
+ result.build_index()
+ result.show()
+ ```
---
@@ -146,15 +203,33 @@ he parse emergency_plan.md -t industry/emergency_response -l en
- Failure mode documentation
**Features**:
+
- Timeline of events
- Contributing factors
- Root causes
- Corrective actions
-**Example:**
-```bash
-he parse incident_report.md -t industry/failure_case -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse incident_report.md -t industry/failure_case -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("industry/failure_case", "en")
+ result = ka.parse(incident_text)
+
+ print(f"Events: {len(result.nodes)}")
+ for edge in result.edges:
+ if hasattr(edge, 'time'):
+ print(f" {edge.time}: {edge.source} -> {edge.target}")
+
+ # Visualize failure timeline
+ result.build_index()
+ result.show()
+ ```
---
@@ -228,5 +303,5 @@ results = procedure.search("startup sequence")
## See Also
-- [Browse All Templates](browse.md)
-- [General Templates](general/index.md)
+- [Template Overview](overview.md)
+- [General Templates](general.md)
diff --git a/docs/en/templates/legal.md b/docs/en/templates/reference/legal.md
similarity index 63%
rename from docs/en/templates/legal.md
rename to docs/en/templates/reference/legal.md
index 25008c1..b89f9d6 100644
--- a/docs/en/templates/legal.md
+++ b/docs/en/templates/reference/legal.md
@@ -25,6 +25,7 @@ Legal templates are designed for extracting structured information from legal do
- License agreements
**Fields**:
+
| Field | Type | Description |
|-------|------|-------------|
| `party` | str | Obligated party |
@@ -32,21 +33,23 @@ Legal templates are designed for extracting structured information from legal do
| `deadline` | str | Due date/timeline |
| `conditions` | str | Conditions or caveats |
-**Example:**
-```bash
-he parse contract.md -t legal/contract_obligation -l en
-```
+=== "CLI"
-**Python:**
-```python
-ka = Template.create("legal/contract_obligation", "en")
-result = ka.parse(contract_text)
+ ```bash
+ he parse contract.md -t legal/contract_obligation -l en
+ ```
-for obl in result.data.items:
- print(f"{obl.party}: {obl.obligation}")
- if obl.deadline:
- print(f" Due: {obl.deadline}")
-```
+=== "Python"
+
+ ```python
+ ka = Template.create("legal/contract_obligation", "en")
+ result = ka.parse(contract_text)
+
+ for obl in result.data.items:
+ print(f"{obl.party}: {obl.obligation}")
+ if obl.deadline:
+ print(f" Due: {obl.deadline}")
+ ```
---
@@ -63,20 +66,37 @@ for obl in result.data.items:
- Case law analysis
**Entities**:
+
- Cases
- Statutes
- Regulations
- Courts
**Relations**:
+
- `cited_by` — Citation relationships
- `overruled` — Overruling relationships
- `distinguished` — Distinction relationships
-**Example:**
-```bash
-he parse brief.md -t legal/case_citation -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse brief.md -t legal/case_citation -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("legal/case_citation", "en")
+ result = ka.parse(brief_text)
+
+ print(f"Entities: {len(result.nodes)}")
+ print(f"Relations: {len(result.edges)}")
+
+ # Build index for interactive visualization
+ result.build_index()
+ result.show()
+ ```
---
@@ -92,14 +112,32 @@ he parse brief.md -t legal/case_citation -l en
- Litigation timelines
**Features**:
+
- Event dates
- Fact descriptions
- Related parties
-**Example:**
-```bash
-he parse case_summary.md -t legal/case_fact_timeline -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse case_summary.md -t legal/case_fact_timeline -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("legal/case_fact_timeline", "en")
+ result = ka.parse(case_text)
+
+ print(f"Events: {len(result.nodes)}")
+ for edge in result.edges:
+ if hasattr(edge, 'time'):
+ print(f" {edge.time}: {edge.source} -> {edge.target}")
+
+ # Visualize timeline
+ result.build_index()
+ result.show()
+ ```
---
@@ -115,16 +153,29 @@ he parse case_summary.md -t legal/case_fact_timeline -l en
- Policy documents
**Fields**:
+
| Field | Type | Description |
|-------|------|-------------|
| `requirement` | str | Compliance requirement |
| `regulation` | str | Source regulation |
| `priority` | str | Priority level |
-**Example:**
-```bash
-he parse compliance.md -t legal/compliance_list -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse compliance.md -t legal/compliance_list -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("legal/compliance_list", "en")
+ result = ka.parse(compliance_text)
+
+ for item in result.data.items:
+ print(f"[{item.priority}] {item.requirement}")
+ print(f" Regulation: {item.regulation}")
+ ```
---
@@ -139,21 +190,21 @@ he parse compliance.md -t legal/compliance_list -l en
- Technical legal documents
- Glossary extraction
-**Example:**
-```bash
-he parse agreement.md -t legal/defined_term_set -l en
-```
+=== "CLI"
-**Output:**
-```python
-{
- "items": [
- "Confidential Information: means any and all non-public...",
- "Effective Date: means the date of execution...",
- "Party: means either signatory..."
- ]
-}
-```
+ ```bash
+ he parse agreement.md -t legal/defined_term_set -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("legal/defined_term_set", "en")
+ result = ka.parse(agreement_text)
+
+ for term in result.data.items:
+ print(f"{term.term}: {term.definition}")
+ ```
---
@@ -219,5 +270,5 @@ high_risk_obligations = [
## See Also
-- [Browse All Templates](browse.md)
+- [Template Overview](overview.md)
- [Finance Templates](finance.md)
diff --git a/docs/en/templates/medicine.md b/docs/en/templates/reference/medicine.md
similarity index 64%
rename from docs/en/templates/medicine.md
rename to docs/en/templates/reference/medicine.md
index aa0ebcb..27d6666 100644
--- a/docs/en/templates/medicine.md
+++ b/docs/en/templates/reference/medicine.md
@@ -26,20 +26,37 @@ Medical templates are designed for extracting clinical information from medical
- Medical education materials
**Entities**:
+
- Body parts
- Organs
- Systems
- Structures
**Relations**:
+
- `part_of` — Anatomical hierarchy
- `connected_to` — Structural connections
- `supplies` — Blood/nerve supply
-**Example:**
-```bash
-he parse anatomy.md -t medicine/anatomy_graph -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse anatomy.md -t medicine/anatomy_graph -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("medicine/anatomy_graph", "en")
+ result = ka.parse(anatomy_text)
+
+ print(f"Structures: {len(result.nodes)}")
+ print(f"Relationships: {len(result.edges)}")
+
+ # Build index for interactive exploration
+ result.build_index()
+ result.show()
+ ```
---
@@ -55,6 +72,7 @@ he parse anatomy.md -t medicine/anatomy_graph -l en
- After-visit summaries
**Fields**:
+
| Field | Type | Description |
|-------|------|-------------|
| `diagnosis` | str | Primary diagnosis |
@@ -63,19 +81,21 @@ he parse anatomy.md -t medicine/anatomy_graph -l en
| `follow_up` | str | Follow-up instructions |
| `warnings` | list[str] | Warning signs |
-**Example:**
-```bash
-he parse discharge.md -t medicine/discharge_instruction -l en
-```
+=== "CLI"
-**Python:**
-```python
-ka = Template.create("medicine/discharge_instruction", "en")
-summary = ka.parse(discharge_text)
+ ```bash
+ he parse discharge.md -t medicine/discharge_instruction -l en
+ ```
-print(f"Diagnosis: {summary.data.diagnosis}")
-print(f"Follow-up: {summary.data.follow_up}")
-```
+=== "Python"
+
+ ```python
+ ka = Template.create("medicine/discharge_instruction", "en")
+ summary = ka.parse(discharge_text)
+
+ print(f"Diagnosis: {summary.data.diagnosis}")
+ print(f"Follow-up: {summary.data.follow_up}")
+ ```
---
@@ -91,19 +111,33 @@ print(f"Follow-up: {summary.data.follow_up}")
- Medication reconciliation
**Entities**:
+
- Drugs
- Drug classes
- Effects
**Relations**:
+
- `interacts_with` — Drug interactions
- `contraindicated_with` — Contraindications
- `synergizes_with` — Synergistic effects
-**Example:**
-```bash
-he parse drug_ref.md -t medicine/drug_interaction -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse drug_ref.md -t medicine/drug_interaction -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("medicine/drug_interaction", "en")
+ result = ka.parse(drug_text)
+
+ print(f"Drugs: {len(result.nodes)}")
+ for relation in result.edges:
+ print(f"{relation.source} {relation.type} {relation.target}")
+ ```
---
@@ -119,14 +153,32 @@ he parse drug_ref.md -t medicine/drug_interaction -l en
- Transfer summaries
**Features**:
+
- Admission/discharge dates
- Procedures and events
- Timeline visualization
-**Example:**
-```bash
-he parse hospital_notes.md -t medicine/hospital_timeline -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse hospital_notes.md -t medicine/hospital_timeline -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("medicine/hospital_timeline", "en")
+ result = ka.parse(notes_text)
+
+ print(f"Events: {len(result.nodes)}")
+ for edge in result.edges:
+ if hasattr(edge, 'time'):
+ print(f" {edge.time}: {edge.source} -> {edge.target}")
+
+ # Visualize timeline
+ result.build_index()
+ result.show()
+ ```
---
@@ -141,10 +193,25 @@ he parse hospital_notes.md -t medicine/hospital_timeline -l en
- Care pathways
- Protocol documents
-**Example:**
-```bash
-he parse protocol.md -t medicine/treatment_map -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse protocol.md -t medicine/treatment_map -l en
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("medicine/treatment_map", "en")
+ result = ka.parse(protocol_text)
+
+ print(f"Steps: {len(result.nodes)}")
+ print(f"Flow relationships: {len(result.edges)}")
+
+ # Visualize treatment pathway
+ result.build_index()
+ result.show()
+ ```
---
@@ -224,5 +291,5 @@ When working with medical data:
## See Also
-- [Browse All Templates](browse.md)
+- [Template Overview](overview.md)
- [TCM Templates](tcm.md)
diff --git a/docs/en/templates/browse.md b/docs/en/templates/reference/overview.md
similarity index 58%
rename from docs/en/templates/browse.md
rename to docs/en/templates/reference/overview.md
index 7bdb3d5..f2bc3f8 100644
--- a/docs/en/templates/browse.md
+++ b/docs/en/templates/reference/overview.md
@@ -1,6 +1,6 @@
-# Browse All Templates
+# Template Overview
-Complete list of available templates.
+Complete overview of all available templates.
---
@@ -19,16 +19,17 @@ Complete list of available templates.
| Template | Type | Description |
|----------|------|-------------|
-| `general/base_model` | model | Basic structured model |
-| `general/base_list` | list | Basic ordered list |
-| `general/base_set` | set | Basic unique set |
-| `general/base_graph` | graph | Basic knowledge graph |
+| `general/model` | model | Basic structured model |
+| `general/list` | list | Basic ordered list |
+| `general/set` | set | Basic unique set |
+| `general/graph` | graph | Basic knowledge graph |
| `general/base_hypergraph` | hypergraph | Basic hypergraph |
| `general/base_temporal_graph` | temporal_graph | Basic temporal graph |
| `general/base_spatial_graph` | spatial_graph | Basic spatial graph |
| `general/base_spatio_temporal_graph` | spatio_temporal_graph | Basic spatio-temporal graph |
| `general/biography_graph` | temporal_graph | Person's life timeline |
| `general/concept_graph` | graph | Research concept extraction |
+| `general/graph` | graph | General knowledge extraction |
| `general/doc_structure` | model | Document outline structure |
| `general/workflow_graph` | graph | Process workflows |
@@ -60,9 +61,10 @@ Complete list of available templates.
| `medicine/discharge_instruction` | model | Patient discharge summary |
| `medicine/drug_interaction` | graph | Drug interactions |
| `medicine/hospital_timeline` | temporal_graph | Hospital stay timeline |
+| `medicine/symptom_list` | list | Symptoms |
| `medicine/treatment_map` | graph | Treatment protocols |
-### TCM (Traditional Chinese Medicine) Templates
+### TCM Templates
| Template | Type | Description |
|----------|------|-------------|
@@ -90,7 +92,7 @@ Complete list of available templates.
| Template | Domain | Description |
|----------|--------|-------------|
-| `general/base_model` | general | Basic structured model |
+| `general/model` | general | Basic structured model |
| `finance/earnings_summary` | finance | Financial summary |
| `finance/sentiment_model` | finance | Sentiment analysis |
| `medicine/discharge_instruction` | medical | Discharge summary |
@@ -100,15 +102,16 @@ Complete list of available templates.
| Template | Domain | Description |
|----------|--------|-------------|
-| `general/base_list` | general | Basic list |
+| `general/list` | general | Basic list |
| `legal/compliance_list` | legal | Compliance requirements |
| `legal/contract_obligation` | legal | Contract obligations |
+| `medicine/symptom_list` | medical | Symptoms |
### Set Templates
| Template | Domain | Description |
|----------|--------|-------------|
-| `general/base_set` | general | Basic set |
+| `general/set` | general | Basic set |
| `finance/risk_factor_set` | finance | Risk factors |
| `legal/defined_term_set` | legal | Defined terms |
@@ -116,56 +119,84 @@ Complete list of available templates.
| Template | Domain | Description |
|----------|--------|-------------|
-| `general/base_graph` | general | Basic graph |
-| `general/knowledge_graph` | general | Knowledge graph |
+| `general/graph` | general | Basic graph |
+| `general/graph` | general | Knowledge graph |
| `general/concept_graph` | general | Concept graph |
+| `general/workflow_graph` | general | Process workflows |
| `finance/ownership_graph` | finance | Ownership structure |
| `legal/case_citation` | legal | Case precedents |
| `medicine/anatomy_graph` | medical | Anatomy |
+| `medicine/drug_interaction` | medical | Drug interactions |
+| `medicine/treatment_map` | medical | Treatment protocols |
| `tcm/herb_relation` | tcm | Herb relationships |
+| `tcm/meridian_graph` | tcm | Meridian pathways |
+| `tcm/syndrome_reasoning` | tcm | Syndrome differentiation |
+| `industry/equipment_topology` | industry | Equipment connections |
+| `industry/operation_flow` | industry | Operational workflows |
+| `industry/safety_control` | industry | Safety control systems |
### Temporal Graph Templates
| Template | Domain | Description |
|----------|--------|-------------|
+| `general/base_temporal_graph` | general | Basic temporal graph |
| `general/biography_graph` | general | Biography timeline |
| `finance/event_timeline` | finance | Financial events |
| `legal/case_fact_timeline` | legal | Case timeline |
| `medicine/hospital_timeline` | medical | Hospital timeline |
+| `industry/failure_case` | industry | Failure analysis |
----
+### Spatial Graph Templates
+
+| Template | Domain | Description |
+|----------|--------|-------------|
+| `general/base_spatial_graph` | general | Basic spatial graph |
+
+### Spatio-Temporal Graph Templates
+
+| Template | Domain | Description |
+|----------|--------|-------------|
+| `general/base_spatio_temporal_graph` | general | Basic spatio-temporal graph |
-## By Language
+### Hypergraph Templates
-### English Only
+| Template | Domain | Description |
+|----------|--------|-------------|
+| `general/base_hypergraph` | general | Basic hypergraph |
-Methods (not templates):
-- `method/light_rag`
-- `method/graph_rag`
-- `method/hyper_rag`
-- `method/itext2kg`
-- etc.
+---
-### Bilingual (zh, en)
+## Methods (Algorithm-level Access)
-All templates support both languages:
-- `general/biography_graph`
-- `finance/earnings_summary`
-- `legal/contract_obligation`
-- etc.
+Methods provide direct access to extraction algorithms:
+
+| Method | Type | Best For |
+|--------|------|----------|
+| `method/light_rag` | RAG | General purpose, fast |
+| `method/graph_rag` | RAG | Large documents |
+| `method/hyper_rag` | RAG | Complex relationships |
+| `method/itext2kg` | Standard | High-quality triples |
+| `method/itext2kg_star` | Standard | Enhanced quality |
+| `method/kg_gen` | Standard | Flexible generation |
+| `method/atom` | Standard | Temporal with evidence |
+
+→ [When to use methods](../../python/guides/using-methods.md)
---
-## Using This List
+## Using This Reference
### CLI
```bash
-# List all
+# List all templates
he list template
# Filter by domain
he list template | grep finance
+
+# Get template info
+he info template general/biography_graph
```
### Python
@@ -173,20 +204,31 @@ he list template | grep finance
```python
from hyperextract import Template
-# Get all
+# Get all templates
templates = Template.list()
# Filter by type
graphs = Template.list(filter_by_type="graph")
+temporal = Template.list(filter_by_type="temporal_graph")
-# Filter by tag
+# Filter by domain/tag
finance = Template.list(filter_by_tag="finance")
+medical = Template.list(filter_by_tag="medicine")
+
+# Get template details
+cfg = Template.get("general/biography_graph")
+print(cfg.name) # biography_graph
+print(cfg.type) # temporal_graph
+print(cfg.description) # Description text
+print(cfg.tags) # ['general', 'biography']
+print(cfg.language) # ['zh', 'en']
```
---
## See Also
-- [How to Choose](how-to-choose.md)
-- [Template Library](index.md)
-- [Domain-Specific Guides](general/index.md)
+- [Choose by Task](../choosing/by-task.md) — Task-based selection
+- [Choose by Output Type](../choosing/by-output.md) — Output-based selection
+- [Template Library Home](../index.md) — Back to main template page
+- [Custom Templates Guide](../../python/guides/custom-templates.md) — Create your own
diff --git a/docs/en/templates/tcm.md b/docs/en/templates/reference/tcm.md
similarity index 66%
rename from docs/en/templates/tcm.md
rename to docs/en/templates/reference/tcm.md
index 8ea8b3b..26880ef 100644
--- a/docs/en/templates/tcm.md
+++ b/docs/en/templates/reference/tcm.md
@@ -24,6 +24,7 @@ TCM (Traditional Chinese Medicine) templates are designed for extracting knowled
- Prescription references
**Fields**:
+
| Field | Type | Description |
|-------|------|-------------|
| `name` | str | Herb name (Chinese/pinyin) |
@@ -33,20 +34,22 @@ TCM (Traditional Chinese Medicine) templates are designed for extracting knowled
| `functions` | list[str] | Main functions |
| `indications` | list[str] | Clinical indications |
-**Example:**
-```bash
-he parse herb_text.md -t tcm/herb_property -l zh
-```
+=== "CLI"
-**Python:**
-```python
-ka = Template.create("tcm/herb_property", "zh")
-herb = ka.parse(huang_qi_text)
+ ```bash
+ he parse herb_text.md -t tcm/herb_property -l zh
+ ```
-print(f"Name: {herb.data.name}")
-print(f"Nature: {', '.join(herb.data.properties)}")
-print(f"Functions: {', '.join(herb.data.functions)}")
-```
+=== "Python"
+
+ ```python
+ ka = Template.create("tcm/herb_property", "zh")
+ herb = ka.parse(huang_qi_text)
+
+ print(f"Name: {herb.data.name}")
+ print(f"Nature: {', '.join(herb.data.properties)}")
+ print(f"Functions: {', '.join(herb.data.functions)}")
+ ```
---
@@ -62,19 +65,37 @@ print(f"Functions: {', '.join(herb.data.functions)}")
- Classic texts (伤寒论, 金匮要略)
**Entities**:
+
- Herbs (药物)
- Formulas (方剂)
- Conditions (病症)
**Relations**:
+
- `contains` — Formula contains herb
- `treats` — Formula treats condition
- `modifies` — Modified formula relationship
-**Example:**
-```bash
-he parse formula_book.md -t tcm/formula_composition -l zh
-```
+=== "CLI"
+
+ ```bash
+ he parse formula_book.md -t tcm/formula_composition -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("tcm/formula_composition", "zh")
+ result = ka.parse(formula_text)
+
+ print(f"Entities: {len(result.nodes)}")
+ print(f"Relations: {len(result.edges)}")
+
+ # List herbs in formula
+ for edge in result.edges:
+ if edge.type == "contains":
+ print(f" - {edge.target}")
+ ```
---
@@ -90,14 +111,27 @@ he parse formula_book.md -t tcm/formula_composition -l zh
- Combination guides
**Relations**:
+
- `pairs_with` — Common pairing
- `synergizes_with` — Synergistic effect
- `incompatible_with` — Contraindicated combination
-**Example:**
-```bash
-he parse herb_pairs.md -t tcm/herb_relation -l zh
-```
+=== "CLI"
+
+ ```bash
+ he parse herb_pairs.md -t tcm/herb_relation -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("tcm/herb_relation", "zh")
+ result = ka.parse(herb_text)
+
+ print(f"Herbs: {len(result.nodes)}")
+ for edge in result.edges:
+ print(f"{edge.source} {edge.type} {edge.target}")
+ ```
---
@@ -113,19 +147,36 @@ he parse herb_pairs.md -t tcm/herb_relation -l zh
- Point location references
**Entities**:
+
- Meridians (经脉)
- Acupoints (穴位)
- Organs (脏腑)
**Relations**:
+
- `connects_to` — Meridian connections
- `belongs_to` — Point to meridian
- `influences` — Meridian-organ relationship
-**Example:**
-```bash
-he parse acupuncture.md -t tcm/meridian_graph -l zh
-```
+=== "CLI"
+
+ ```bash
+ he parse acupuncture.md -t tcm/meridian_graph -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("tcm/meridian_graph", "zh")
+ result = ka.parse(acupuncture_text)
+
+ print(f"Meridians: {len(result.nodes)}")
+ print(f"Connections: {len(result.edges)}")
+
+ # Visualize meridian pathways
+ result.build_index()
+ result.show()
+ ```
---
@@ -141,19 +192,36 @@ he parse acupuncture.md -t tcm/meridian_graph -l zh
- Syndrome differentiation guides
**Entities**:
+
- Symptoms (症状)
- Syndromes (证型)
- Patterns (病机)
**Relations**:
+
- `indicates` — Symptom indicates syndrome
- `differentiates_from` — Differential diagnosis
- `leads_to` — Pattern progression
-**Example:**
-```bash
-he parse diagnostics.md -t tcm/syndrome_reasoning -l zh
-```
+=== "CLI"
+
+ ```bash
+ he parse diagnostics.md -t tcm/syndrome_reasoning -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("tcm/syndrome_reasoning", "zh")
+ result = ka.parse(diagnostics_text)
+
+ print(f"Symptoms: {len(result.nodes)}")
+ print(f"Indications: {len(result.edges)}")
+
+ # Explore syndrome relationships
+ result.build_index()
+ result.show()
+ ```
---
@@ -220,5 +288,5 @@ for r in related:
## See Also
-- [Browse All Templates](browse.md)
+- [Template Overview](overview.md)
- [Medical Templates](medicine.md)
diff --git a/docs/en/tutorials/document-analysis/index.md b/docs/en/tutorials/document-analysis/index.md
index 877aa1a..2698647 100644
--- a/docs/en/tutorials/document-analysis/index.md
+++ b/docs/en/tutorials/document-analysis/index.md
@@ -48,7 +48,7 @@ document-analysis/
│ ├── pending/ # Documents to process
│ ├── processing/ # Currently processing
│ └── completed/ # Successfully processed
-├── output/ # Extracted knowledge bases
+├── output/ # Extracted knowledge abstracts
│ ├── batch_001/
│ ├── batch_002/
│ └── combined/
@@ -117,7 +117,7 @@ class BatchDocumentProcessor:
def __init__(
self,
- template: str = "general/knowledge_graph",
+ template: str = "general/graph",
language: str = "en",
batch_size: int = 10,
max_workers: int = 4
@@ -285,7 +285,7 @@ class BatchDocumentProcessor:
logger.info(f"Results log saved: {log_file}")
def combine_results(self, output_name: str = "combined"):
- """Combine all individual results into one knowledge base."""
+ """Combine all individual results into one knowledge abstract."""
logger.info("Combining results...")
output_dirs = [d for d in Path("output").iterdir() if d.is_dir()]
@@ -300,15 +300,15 @@ class BatchDocumentProcessor:
# Merge remaining
for output_dir in output_dirs[1:]:
- kb = Template.create(self.template, self.language)
- kb.load(str(output_dir))
+ ka = Template.create(self.template, self.language)
+ ka.load(str(output_dir))
# Merge entities and relations
- for entity in kb.data.entities:
+ for entity in ka.data.entities:
if entity not in combined.data.entities:
combined.data.entities.append(entity)
- for relation in kb.data.relations:
+ for relation in ka.data.relations:
if relation not in combined.data.relations:
combined.data.relations.append(relation)
@@ -317,7 +317,7 @@ class BatchDocumentProcessor:
combined_path = Path("output") / output_name
combined.dump(str(combined_path))
- logger.info(f"Combined knowledge base saved: {combined_path}")
+ logger.info(f"Combined knowledge abstract saved: {combined_path}")
return combined
@@ -326,7 +326,7 @@ if __name__ == "__main__":
import argparse
parser = argparse.ArgumentParser(description="Batch Document Processor")
- parser.add_argument("--template", default="general/knowledge_graph", help="Template to use")
+ parser.add_argument("--template", default="general/graph", help="Template to use")
parser.add_argument("--language", default="en", help="Document language")
parser.add_argument("--batch-size", type=int, default=10, help="Batch size")
parser.add_argument("--parallel", action="store_true", help="Enable parallel processing")
@@ -556,7 +556,7 @@ You now have a complete batch processing system that can:
✓ Handle errors and retries
✓ Run in parallel for speed
✓ Monitor progress and collect metrics
-✓ Combine results into unified knowledge bases
+✓ Combine results into unified knowledge abstracts
### Next Steps
@@ -570,4 +570,4 @@ You now have a complete batch processing system that can:
## See Also
- [Research Assistant Tutorial](../research-assistant/index.md)
-- [Knowledge Base Tutorial](../knowledge-base/index.md)
+- [Knowledge Abstract Tutorial](../knowledge-base/index.md)
diff --git a/docs/en/tutorials/index.md b/docs/en/tutorials/index.md
index eee941b..d9399a3 100644
--- a/docs/en/tutorials/index.md
+++ b/docs/en/tutorials/index.md
@@ -20,11 +20,11 @@ Hands-on tutorials for real-world use cases.
[:octicons-arrow-right-24: Start Tutorial](research-assistant/index.md)
-- :material-database:{ .lg .middle } __Knowledge Base__
+- :material-database:{ .lg .middle } __Knowledge Abstract__
---
- Build and maintain a domain-specific knowledge base.
+ Build and maintain a domain-specific knowledge abstract.
- Incremental document ingestion
- Version management
diff --git a/docs/en/tutorials/knowledge-base/index.md b/docs/en/tutorials/knowledge-base/index.md
index bb4094a..b672e80 100644
--- a/docs/en/tutorials/knowledge-base/index.md
+++ b/docs/en/tutorials/knowledge-base/index.md
@@ -1,12 +1,12 @@
-# Knowledge Base Tutorial
+# Knowledge Abstract Tutorial
-Build and maintain a domain-specific knowledge base.
+Build and maintain a domain-specific knowledge abstract.
---
## What You'll Build
-A production-ready knowledge base that:
+A production-ready knowledge abstract that:
- Ingests documents incrementally
- Supports versioning and backups
- Provides query and search capabilities
@@ -19,21 +19,21 @@ A production-ready knowledge base that:
| Step | Topic | What You'll Learn |
|------|-------|-------------------|
| 1 | [Setup](step1-setup.md) | Project structure and template selection |
-| 2 | [Ingest](step2-ingest.md) | Add documents to your knowledge base |
+| 2 | [Ingest](step2-ingest.md) | Add documents to your knowledge abstract |
| 3 | [Query](step3-query.md) | Search, update, and maintain |
---
## Use Cases
-### Use Case 1: Company Knowledge Base
+### Use Case 1: Company Knowledge Abstract
Centralize company documentation:
- Policies and procedures
- Technical documentation
- Meeting notes and decisions
-### Use Case 2: Research Knowledge Base
+### Use Case 2: Research Knowledge Abstract
Build a personal research database:
- Academic papers
@@ -55,7 +55,7 @@ Manage legal documents:
knowledge-base/
├── config.yaml # Configuration
├── documents/ # Source documents
-├── kb/ # Knowledge base storage
+├── ka/ # Knowledge base storage
│ ├── v1/ # Version 1
│ ├── v2/ # Version 2
│ └── current/ # Current version
diff --git a/docs/en/tutorials/knowledge-base/step1-setup.md b/docs/en/tutorials/knowledge-base/step1-setup.md
index 0d13ffc..3b23b96 100644
--- a/docs/en/tutorials/knowledge-base/step1-setup.md
+++ b/docs/en/tutorials/knowledge-base/step1-setup.md
@@ -6,7 +6,7 @@ Project structure and template selection.
## Goal
-Set up a robust project structure for maintaining a domain-specific knowledge base.
+Set up a robust project structure for maintaining a domain-specific knowledge abstract.
---
@@ -15,18 +15,18 @@ Set up a robust project structure for maintaining a domain-specific knowledge ba
Create the following directory structure:
```bash
-mkdir -p my_knowledge_base/{documents,kb,backups,logs}
-cd my_knowledge_base
+mkdir -p my_ka/{documents,ka,backups,logs}
+cd my_ka
```
Structure:
```
-my_knowledge_base/
+my_ka/
├── config.yaml # Project configuration
├── documents/ # Source documents
│ ├── raw/ # Original files
│ └── processed/ # Processing log
-├── kb/ # Knowledge base versions
+├── ka/ # Knowledge base versions
│ └── current/ # Current version (symlink)
├── backups/ # Version backups
├── logs/ # Operation logs
@@ -40,8 +40,8 @@ my_knowledge_base/
### config.yaml
```yaml
-# Knowledge Base Configuration
-name: "Company Knowledge Base"
+# Knowledge Abstract Configuration
+name: "Company Knowledge Abstract"
domain: "legal" # or finance, medical, etc.
# Template settings
@@ -58,7 +58,7 @@ auto_backup: true
# Paths
documents_dir: "./documents/raw"
-kb_dir: "./kb"
+ka_dir: "./ka"
backup_dir: "./backups"
```
@@ -69,7 +69,7 @@ backup_dir: "./backups"
| Legal | `legal/contract_obligation` | list |
| Finance | `finance/earnings_summary` | model |
| Medical | `medicine/anatomy_graph` | graph |
-| General | `general/knowledge_graph` | graph |
+| General | `general/graph` | graph |
| Research | `general/concept_graph` | graph |
---
@@ -79,7 +79,7 @@ backup_dir: "./backups"
### kb_manager.py (Starter)
```python
-"""Knowledge Base Manager."""
+"""Knowledge Abstract Manager."""
import yaml
import json
@@ -97,7 +97,7 @@ class KBConfig:
template: str
language: str
documents_dir: str
- kb_dir: str
+ ka_dir: str
backup_dir: str
class KnowledgeBaseManager:
@@ -113,7 +113,7 @@ class KnowledgeBaseManager:
return KBConfig(**data)
def initialize(self):
- """Initialize knowledge base."""
+ """Initialize knowledge abstract."""
print(f"Initializing: {self.config.name}")
# Create directories
@@ -136,7 +136,7 @@ class KnowledgeBaseManager:
return Path(self.config.kb_dir) / version
def save_version(self, kb_instance, version: Optional[str] = None):
- """Save knowledge base version."""
+ """Save knowledge abstract version."""
path = self.get_version_path(version)
kb_instance.dump(str(path))
@@ -163,12 +163,12 @@ if __name__ == "__main__":
```bash
cat > config.yaml << 'EOF'
-name: "My Knowledge Base"
+name: "My Knowledge Abstract"
domain: "general"
-template: "general/knowledge_graph"
+template: "general/graph"
language: "en"
documents_dir: "./documents/raw"
-kb_dir: "./kb"
+ka_dir: "./ka"
backup_dir: "./backups"
EOF
```
@@ -181,14 +181,14 @@ python kb_manager.py
Expected output:
```
-Initializing: My Knowledge Base
+Initializing: My Knowledge Abstract
✓ Initialization complete
```
### 3. Verify Structure
```bash
-tree my_knowledge_base/
+tree my_ka/
```
---
diff --git a/docs/en/tutorials/knowledge-base/step2-ingest.md b/docs/en/tutorials/knowledge-base/step2-ingest.md
index cb204b9..1417cf0 100644
--- a/docs/en/tutorials/knowledge-base/step2-ingest.md
+++ b/docs/en/tutorials/knowledge-base/step2-ingest.md
@@ -1,12 +1,12 @@
# Step 2: Ingest
-Add documents to your knowledge base.
+Add documents to your knowledge abstract.
---
## Goal
-Ingest documents into the knowledge base with proper version control.
+Ingest documents into the knowledge abstract with proper version control.
---
@@ -55,20 +55,20 @@ def initial_ingest(self, documents_dir: str):
# Parse first document
print(f"Processing: {docs[0].name}")
text = docs[0].read_text(encoding="utf-8")
- kb = self.ka.parse(text)
+ ka = self.ka.parse(text)
# Feed remaining documents
for doc in docs[1:]:
print(f"Adding: {doc.name}")
text = doc.read_text(encoding="utf-8")
- kb.feed_text(text)
+ ka.feed_text(text)
# Build index
print("Building search index...")
- kb.build_index()
+ ka.build_index()
# Save version
- version_path = self.save_version(kb, "v1.0")
+ version_path = self.save_version(ka, "v1.0")
# Log processing
self._log_processing(docs, version_path)
@@ -76,22 +76,22 @@ def initial_ingest(self, documents_dir: str):
print(f"✓ Ingested {len(docs)} documents")
print(f"✓ Knowledge base: {version_path}")
- return kb
+ return ka
```
### Method 2: Incremental Updates
-Add new documents to existing KB:
+Add new documents to existing KA:
```python
def add_documents(self, document_paths: list[str]):
- """Add new documents to existing knowledge base."""
- print("Loading current knowledge base...")
+ """Add new documents to existing knowledge abstract."""
+ print("Loading current knowledge abstract...")
# Load current version
current_path = Path(self.config.kb_dir) / "current"
- kb = Template.create(self.config.template, self.config.language)
- kb.load(current_path)
+ ka = Template.create(self.config.template, self.config.language)
+ ka.load(current_path)
# Add new documents
for path in document_paths:
@@ -99,20 +99,20 @@ def add_documents(self, document_paths: list[str]):
print(f"Adding: {doc_path.name}")
text = doc_path.read_text(encoding="utf-8")
- kb.feed_text(text)
+ ka.feed_text(text)
# Rebuild index
print("Rebuilding search index...")
- kb.build_index()
+ ka.build_index()
# Save new version
version = self._get_next_version()
- version_path = self.save_version(kb, version)
+ version_path = self.save_version(ka, version)
print(f"✓ Added {len(document_paths)} documents")
print(f"✓ New version: {version}")
- return kb
+ return ka
def _get_next_version(self) -> str:
"""Generate next version number."""
@@ -146,7 +146,7 @@ from pathlib import Path
from kb_manager import KnowledgeBaseManager
def main():
- parser = argparse.ArgumentParser(description="Ingest documents into KB")
+ parser = argparse.ArgumentParser(description="Ingest documents into KA")
parser.add_argument("--initial", action="store_true", help="Initial ingestion")
parser.add_argument("--add", nargs="+", help="Add specific documents")
parser.add_argument("--dir", default="./documents/raw", help="Documents directory")
@@ -158,20 +158,20 @@ def main():
if args.initial:
# Initial ingestion
- kb = manager.initial_ingest(args.dir)
+ ka = manager.initial_ingest(args.dir)
# Print stats
- print("\nKnowledge Base Stats:")
- print(f" Nodes: {len(kb.nodes)}")
- print(f" Edges: {len(kb.edges)}")
+ print("\nKnowledge Abstract Stats:")
+ print(f" Nodes: {len(ka.nodes)}")
+ print(f" Edges: {len(ka.edges)}")
elif args.add:
# Add specific documents
- kb = manager.add_documents(args.add)
+ ka = manager.add_documents(args.add)
- print("\nKnowledge Base Stats:")
- print(f" Nodes: {len(kb.nodes)}")
- print(f" Edges: {len(kb.edges)}")
+ print("\nKnowledge Abstract Stats:")
+ print(f" Nodes: {len(ka.nodes)}")
+ print(f" Edges: {len(ka.edges)}")
if __name__ == "__main__":
main()
@@ -227,11 +227,11 @@ BATCH_SIZE = 10
for i in range(0, len(docs), BATCH_SIZE):
batch = docs[i:i + BATCH_SIZE]
for doc in batch:
- kb.feed_text(doc.read_text())
+ ka.feed_text(doc.read_text())
# Save checkpoint
if i % (BATCH_SIZE * 5) == 0:
- kb.dump(f"./kb/checkpoint_{i}/")
+ ka.dump(f"./ka/checkpoint_{i}/")
```
### 2. Error Handling
@@ -239,7 +239,7 @@ for i in range(0, len(docs), BATCH_SIZE):
```python
try:
text = doc.read_text(encoding="utf-8")
- kb.feed_text(text)
+ ka.feed_text(text)
except Exception as e:
print(f"Error processing {doc}: {e}")
# Log error, continue with next
@@ -249,14 +249,14 @@ except Exception as e:
### 3. Validation
```python
-def validate_ingestion(self, kb):
- """Validate knowledge base after ingestion."""
- assert not kb.empty(), "Knowledge base is empty"
- assert len(kb.data.entities) > 0, "No entities extracted"
+def validate_ingestion(self, ka):
+ """Validate knowledge abstract after ingestion."""
+ assert not ka.empty(), "Knowledge base is empty"
+ assert len(ka.data.entities) > 0, "No entities extracted"
# Try to build index
try:
- kb.build_index()
+ ka.build_index()
except Exception as e:
raise ValueError(f"Failed to build index: {e}")
```
diff --git a/docs/en/tutorials/knowledge-base/step3-query.md b/docs/en/tutorials/knowledge-base/step3-query.md
index d81f4c9..ad6d09c 100644
--- a/docs/en/tutorials/knowledge-base/step3-query.md
+++ b/docs/en/tutorials/knowledge-base/step3-query.md
@@ -1,12 +1,12 @@
# Step 3: Query
-Search, update, and maintain your knowledge base.
+Search, update, and maintain your knowledge abstract.
---
## Goal
-Query the knowledge base and implement maintenance workflows.
+Query the knowledge abstract and implement maintenance workflows.
---
@@ -16,13 +16,13 @@ Query the knowledge base and implement maintenance workflows.
```python
def search(self, query: str, top_k: int = 5):
- """Search the knowledge base."""
+ """Search the knowledge abstract."""
current_path = Path(self.config.kb_dir) / "current"
- kb = Template.create(self.config.template, self.config.language)
- kb.load(current_path)
+ ka = Template.create(self.config.template, self.config.language)
+ ka.load(current_path)
- results = kb.search(query, top_k=top_k)
+ results = ka.search(query, top_k=top_k)
return results
```
@@ -30,13 +30,13 @@ def search(self, query: str, top_k: int = 5):
```python
def ask(self, question: str, top_k: int = 5):
- """Ask a question about the knowledge base."""
+ """Ask a question about the knowledge abstract."""
current_path = Path(self.config.kb_dir) / "current"
- kb = Template.create(self.config.template, self.config.language)
- kb.load(current_path)
+ ka = Template.create(self.config.template, self.config.language)
+ ka.load(current_path)
- response = kb.chat(question, top_k=top_k)
+ response = ka.chat(question, top_k=top_k)
return response.content
```
@@ -52,49 +52,49 @@ from kb_manager import KnowledgeBaseManager
class KBQueryShell(cmd.Cmd):
intro = """
-Knowledge Base Query Shell
+Knowledge Abstract Query Shell
==========================
Type 'help' for commands, 'quit' to exit
Commands:
search <query> - Semantic search
ask <question> - Ask a question
- stats - Show KB statistics
+ stats - Show KA statistics
versions - List versions
backup - Create backup
"""
- prompt = "kb> "
+ prompt = "ka> "
def __init__(self):
super().__init__()
self.manager = KnowledgeBaseManager()
- self.kb = None
+ self.ka = None
self._load_kb()
def _load_kb(self):
- """Load current knowledge base."""
+ """Load current knowledge abstract."""
current_path = Path(self.manager.config.kb_dir) / "current"
if current_path.exists():
- self.kb = Template.create(
+ self.ka = Template.create(
self.manager.config.template,
self.manager.config.language
)
- self.kb.load(current_path)
+ self.ka.load(current_path)
print(f"Loaded: {self.manager.config.name}")
else:
- print("Warning: No knowledge base found")
+ print("Warning: No knowledge abstract found")
def do_search(self, arg):
- """Search the knowledge base: search <query>"""
+ """Search the knowledge abstract: search <query>"""
if not arg:
print("Usage: search <query>")
return
- if not self.kb:
- print("No knowledge base loaded")
+ if not self.ka:
+ print("No knowledge abstract loaded")
return
- nodes, edges = self.kb.search(arg, top_k=5)
+ nodes, edges = self.ka.search(arg, top_k=5)
print(f"\nFound {len(nodes)} nodes and {len(edges)} edges:\n")
for i, node in enumerate(nodes, 1):
@@ -109,28 +109,28 @@ Commands:
print("Usage: ask <question>")
return
- if not self.kb:
- print("No knowledge base loaded")
+ if not self.ka:
+ print("No knowledge abstract loaded")
return
print("\nThinking...")
- answer = self.kb.chat(arg).content
+ answer = self.ka.chat(arg).content
print(f"\n{answer}\n")
def do_stats(self, arg):
- """Show knowledge base statistics."""
- if not self.kb:
- print("No knowledge base loaded")
+ """Show knowledge abstract statistics."""
+ if not self.ka:
+ print("No knowledge abstract loaded")
return
- print("\nKnowledge Base Statistics:")
- print(f" Nodes: {len(self.kb.nodes)}")
- print(f" Edges: {len(self.kb.edges)}")
+ print("\nKnowledge Abstract Statistics:")
+ print(f" Nodes: {len(self.ka.nodes)}")
+ print(f" Edges: {len(self.ka.edges)}")
print(f" Template: {self.manager.config.template}")
# Node types
from collections import Counter
- types = Counter(n.type for n in self.kb.nodes)
+ types = Counter(n.type for n in self.ka.nodes)
print("\nNode Types:")
for t, count in types.most_common():
print(f" {t}: {count}")
@@ -181,7 +181,7 @@ if __name__ == "__main__":
```python
def create_backup(self, name: Optional[str] = None):
- """Create a backup of current knowledge base."""
+ """Create a backup of current knowledge abstract."""
import shutil
current = Path(self.config.kb_dir) / "current"
@@ -285,15 +285,15 @@ def cleanup_old_versions(self, keep: int = 10):
```python
def export_to_json(self, output_file: str = "kb_export.json"):
- """Export knowledge base to JSON."""
+ """Export knowledge abstract to JSON."""
data = {
"config": {
"name": self.config.name,
"template": self.config.template,
"language": self.config.language
},
- "data": self.kb.data.model_dump(),
- "metadata": self.kb.metadata
+ "data": self.ka.data.model_dump(),
+ "metadata": self.ka.metadata
}
with open(output_file, "w") as f:
@@ -306,19 +306,19 @@ def export_to_json(self, output_file: str = "kb_export.json"):
```python
def generate_report(self):
- """Generate knowledge base report."""
+ """Generate knowledge abstract report."""
from collections import Counter
report = []
- report.append("# Knowledge Base Report")
+ report.append("# Knowledge Abstract Report")
report.append(f"\nName: {self.config.name}")
report.append(f"Template: {self.config.template}")
report.append(f"\nStatistics:")
- report.append(f"- Entities: {len(self.kb.data.entities)}")
- report.append(f"- Relations: {len(self.kb.data.relations)}")
+ report.append(f"- Entities: {len(self.ka.data.entities)}")
+ report.append(f"- Relations: {len(self.ka.data.relations)}")
# Entity types
- types = Counter(e.type for e in self.kb.data.entities)
+ types = Counter(e.type for e in self.ka.data.entities)
report.append("\n## Entity Types")
for t, count in types.most_common():
report.append(f"- {t}: {count}")
@@ -330,7 +330,7 @@ def generate_report(self):
## Summary
-You now have a complete knowledge base system with:
+You now have a complete knowledge abstract system with:
✓ Document ingestion with versioning
✓ Search and Q&A capabilities
@@ -341,7 +341,7 @@ You now have a complete knowledge base system with:
### Next Steps
- Schedule regular backups
-- Monitor knowledge base growth
+- Monitor knowledge abstract growth
- Set up automated ingestion pipelines
- Integrate with your applications
diff --git a/docs/en/tutorials/research-assistant/index.md b/docs/en/tutorials/research-assistant/index.md
index 6d195fb..7146da6 100644
--- a/docs/en/tutorials/research-assistant/index.md
+++ b/docs/en/tutorials/research-assistant/index.md
@@ -19,7 +19,7 @@ By the end of this tutorial, you'll have a research assistant that can:
| Step | Topic | What You'll Learn |
|------|-------|-------------------|
| 1 | [Extract Knowledge](step1-extract.md) | Parse a research paper and extract concepts |
-| 2 | [Semantic Search](step2-search.md) | Build a searchable knowledge base |
+| 2 | [Semantic Search](step2-search.md) | Build a searchable knowledge abstract |
| 3 | [Q&A System](step3-chat.md) | Create an interactive Q&A interface |
---
@@ -43,7 +43,7 @@ Quickly understand a new paper by asking questions:
### Use Case 2: Literature Review
-Build a knowledge base from multiple papers:
+Build a knowledge abstract from multiple papers:
- Extract concepts from 10+ papers
- Search across all papers
- Find connections between works
diff --git a/docs/en/tutorials/research-assistant/step1-extract.md b/docs/en/tutorials/research-assistant/step1-extract.md
index bc410e1..7057a3b 100644
--- a/docs/en/tutorials/research-assistant/step1-extract.md
+++ b/docs/en/tutorials/research-assistant/step1-extract.md
@@ -177,7 +177,7 @@ The concept graph template extracts:
### "No entities extracted"
- Check paper is not empty: `wc -l paper.md`
-- Try different template: `general/knowledge_graph`
+- Try different template: `general/graph`
- Check language setting matches document
### "Extraction is slow"
diff --git a/docs/en/tutorials/research-assistant/step2-search.md b/docs/en/tutorials/research-assistant/step2-search.md
index ef9e535..e18ac46 100644
--- a/docs/en/tutorials/research-assistant/step2-search.md
+++ b/docs/en/tutorials/research-assistant/step2-search.md
@@ -1,6 +1,6 @@
# Step 2: Semantic Search
-Build a searchable knowledge base.
+Build a searchable knowledge abstract.
---
@@ -46,7 +46,7 @@ he search ./paper_kb/ "transformer architecture" -n 10
### Script
```python
-"""Step 2: Semantic search over knowledge base."""
+"""Step 2: Semantic search over knowledge abstract."""
from dotenv import load_dotenv
load_dotenv()
@@ -56,8 +56,8 @@ from hyperextract import Template
KB_DIR = "./paper_kb/"
def main():
- # Load knowledge base
- print("Loading knowledge base...")
+ # Load knowledge abstract
+ print("Loading knowledge abstract...")
ka = Template.create("general/concept_graph", language="en")
ka.load(KB_DIR)
@@ -155,9 +155,9 @@ Search: quit
```python
class ResearchSearch:
- def __init__(self, kb_path):
+ def __init__(self, ka_path):
self.ka = Template.create("general/concept_graph", "en")
- self.ka.load(kb_path)
+ self.ka.load(ka_path)
self.ka.build_index()
def find_concepts(self, query, n=5):
diff --git a/docs/en/tutorials/research-assistant/step3-chat.md b/docs/en/tutorials/research-assistant/step3-chat.md
index 70e89f0..3a4ad5a 100644
--- a/docs/en/tutorials/research-assistant/step3-chat.md
+++ b/docs/en/tutorials/research-assistant/step3-chat.md
@@ -13,7 +13,7 @@ Build a conversational interface that answers questions about the research paper
## How It Works
1. User asks a question
-2. System retrieves relevant context from knowledge base
+2. System retrieves relevant context from knowledge abstract
3. LLM generates answer based on retrieved context
4. Response includes citations from the paper
@@ -69,10 +69,10 @@ from hyperextract import Template
KB_DIR = "./paper_kb/"
class ResearchAssistant:
- def __init__(self, kb_path):
+ def __init__(self, ka_path):
print("Loading research assistant...")
self.ka = Template.create("general/concept_graph", "en")
- self.ka.load(kb_path)
+ self.ka.load(ka_path)
self.ka.build_index()
print("✓ Ready!\n")
@@ -208,30 +208,30 @@ from pathlib import Path
class ResearchAssistantApp:
def __init__(self, paper_path, kb_dir="./paper_kb/"):
self.paper_path = paper_path
- self.kb_dir = kb_dir
+ self.ka_dir = kb_dir
self.ka = None
- # Load or create knowledge base
+ # Load or create knowledge abstract
if Path(kb_dir).exists():
self._load_kb()
else:
self._create_kb()
def _create_kb(self):
- """Create knowledge base from paper."""
- print("Creating knowledge base...")
+ """Create knowledge abstract from paper."""
+ print("Creating knowledge abstract...")
ka = Template.create("general/concept_graph", "en")
text = Path(self.paper_path).read_text()
self.ka = ka.parse(text)
self.ka.build_index()
- self.ka.dump(self.kb_dir)
+ self.ka.dump(self.ka_dir)
print("✓ Knowledge base created\n")
def _load_kb(self):
- """Load existing knowledge base."""
- print("Loading knowledge base...")
+ """Load existing knowledge abstract."""
+ print("Loading knowledge abstract...")
self.ka = Template.create("general/concept_graph", "en")
- self.ka.load(self.kb_dir)
+ self.ka.load(self.ka_dir)
print("✓ Knowledge base loaded\n")
def search(self, query):
@@ -245,7 +245,9 @@ class ResearchAssistantApp:
def visualize(self):
"""Open visualization."""
self.ka.show()
-
+
+![Interactive Visualization](../../../../assets/en_show.png)
+
def run(self):
"""Run interactive session."""
print("="*60)
@@ -299,5 +301,5 @@ Congratulations! You've built a complete research assistant that can:
## See Also
-- [Knowledge Base Tutorial](../knowledge-base/index.md)
+- [Knowledge Abstract Tutorial](../knowledge-base/index.md)
- [Document Analysis Tutorial](../document-analysis/index.md)
diff --git a/docs/zh/cli/commands/build-index.md b/docs/zh/cli/commands/build-index.md
index cea1e8f..19bb9dc 100644
--- a/docs/zh/cli/commands/build-index.md
+++ b/docs/zh/cli/commands/build-index.md
@@ -53,7 +53,7 @@ Language: en
Success! Index built for ./output/
Now you can:
- he search ./output/ "keyword" # Semantic search
+ he search ./output/ "关键词" # Semantic search
he talk ./output/ -i # Interactive chat
```
@@ -74,14 +74,14 @@ he build-index ./output/ -f
默认情况下,`he parse` 会自动构建索引:
```bash
-he parse doc.md -t general/biography_graph -o ./kb/ -l en
+he parse doc.md -t general/biography_graph -o ./ka/ -l zh
# 索引自动构建
```
如果不需要搜索/聊天,使用 `--no-index` 跳过:
```bash
-he parse doc.md -t general/biography_graph -o ./kb/ -l en --no-index
+he parse doc.md -t general/biography_graph -o ./ka/ -l zh --no-index
```
### Feed 后
@@ -89,8 +89,8 @@ he parse doc.md -t general/biography_graph -o ./kb/ -l en --no-index
喂养新文档后始终重建:
```bash
-he feed ./kb/ new_doc.md
-he build-index ./kb/
+he feed ./ka/ new_doc.md
+he build-index ./ka/
```
### 手动更改后
@@ -98,7 +98,7 @@ he build-index ./kb/
如果您手动修改了 `data.json`:
```bash
-he build-index ./kb/ -f
+he build-index ./ka/ -f
```
---
@@ -108,7 +108,7 @@ he build-index ./kb/ -f
索引存储在知识库目录中:
```
-./kb/
+./ka/
├── data.json
├── metadata.json
└── index/ # 索引目录
@@ -133,7 +133,7 @@ he build-index ./kb/ -f
一旦构建完成,搜索非常快:
```bash
-he search ./kb/ "query" # 通常 < 1 秒
+he search ./ka/ "查询" # 通常 < 1 秒
```
---
@@ -153,16 +153,16 @@ he search ./kb/ "query" # 通常 < 1 秒
```bash
# 解析所有文件,不构建索引
-he parse doc1.md -t general/biography_graph -o ./kb/ -l en --no-index
-he feed ./kb/ doc2.md
-he feed ./kb/ doc3.md
+he parse doc1.md -t general/biography_graph -o ./ka/ -l zh --no-index
+he feed ./ka/ doc2.md
+he feed ./ka/ doc3.md
# 最后统一构建索引
-he build-index ./kb/
+he build-index ./ka/
# 现在可以进行搜索/聊天
-he search ./kb/ "query"
-he talk ./kb/ -q "question"
+he search ./ka/ "查询"
+he talk ./ka/ -q "问题"
```
---
@@ -174,13 +174,13 @@ he talk ./kb/ -q "question"
使用 `-f` 强制重建:
```bash
-he build-index ./kb/ -f
+he build-index ./ka/ -f
```
### "索引构建失败"
检查:
-1. 知识库有数据:`he info ./kb/`
+1. 知识库有数据:`he info ./ka/`
2. API 密钥已配置:`he config show`
3. 有足够的磁盘空间存储索引
@@ -189,7 +189,7 @@ he build-index ./kb/ -f
尝试强制重建:
```bash
-he build-index ./kb/ -f
+he build-index ./ka/ -f
```
---
diff --git a/docs/zh/cli/commands/config.md b/docs/zh/cli/commands/config.md
index 6f192c1..f885c91 100644
--- a/docs/zh/cli/commands/config.md
+++ b/docs/zh/cli/commands/config.md
@@ -1,6 +1,6 @@
# he config
-管理 Hyper-Extract 配置。
+管理 Hyper-Extract 的 LLM 和嵌入模型配置。
---
@@ -14,16 +14,19 @@ he config [COMMAND] [OPTIONS]
| 命令 | 描述 |
|---------|-------------|
-| `init` | 初始化配置 |
+| `init` | 初始化配置(懒人模式默认使用 `gpt-4o-mini` + `text-embedding-3-small`) |
| `show` | 显示当前配置 |
-| `set` | 设置配置值 |
-| `get` | 获取配置值 |
+| `llm` | 配置 LLM 设置 |
+| `embedder` | 配置嵌入模型设置 |
---
## he config init
-使用 API 凭证初始化配置。
+初始化配置。这是**懒人一键配置** —— 只要传入 `-k`,就会自动使用内置默认值,无需任何交互:
+
+- **LLM**: `gpt-4o-mini`
+- **嵌入模型**: `text-embedding-3-small`
```bash
he config init [OPTIONS]
@@ -33,36 +36,30 @@ he config init [OPTIONS]
| 选项 | 简写 | 描述 |
|--------|-------|-------------|
-| `--key` | `-k` | OpenAI API 密钥 |
-| `--base-url` | `-u` | API 基础 URL(可选) |
-| `--model` | `-m` | 默认模型(默认:gpt-4o-mini) |
-| `--embedder` | `-e` | 嵌入模型(默认:text-embedding-3-small) |
+| `--api-key` | `-k` | LLM 和嵌入模型的 API 密钥 |
+| `--base-url` | `-u` | 自定义 API 基础 URL(可选) |
### 示例
-#### 基本设置
+#### 懒人一键配置(推荐)
```bash
he config init -k sk-your-api-key-here
```
+执行后会自动保存默认模型 `gpt-4o-mini` 和 `text-embedding-3-small`。
+
#### 使用自定义基础 URL
```bash
he config init -k sk-your-key -u https://api.openai.com/v1
```
-#### 使用自定义模型
-
-```bash
-he config init -k sk-your-key -m gpt-4o -e text-embedding-3-large
-```
-
-#### 交互模式
+#### 交互式初始化
```bash
he config init
-# 交互式提示输入 API 密钥
+# 按步骤交互式输入模型名称和 API 密钥
```
---
@@ -75,66 +72,86 @@ he config init
he config show
```
-**输出:**
-```
-Configuration (from ~/.he/config.toml):
-
-[llm]
-model = "gpt-4o-mini"
-api_key = "sk-...***"
-base_url = "https://api.openai.com/v1"
-
-[embedder]
-model = "text-embedding-3-small"
-api_key = "sk-...***"
+**输出示例:**
-[defaults]
-language = "en"
-chunk_size = 2048
-max_workers = 10
+```
+┌─────────────────────────────────────────────────────────┐
+│ Hyper-Extract Configuration │
+├──────────┬─────────────────────┬─────────────┬──────────┤
+│ Service │ Model │ API Key │ Base URL │
+├──────────┼─────────────────────┼─────────────┼──────────┤
+│ LLM │ gpt-4o-mini │ sk-xxxxx... │ (default)│
+│ Embedder │ text-embedding-3... │ sk-xxxxx... │ (default)│
+└──────────┴─────────────────────┴─────────────┴──────────┘
```
---
-## he config set
+## he config llm
-设置配置值。
+单独配置 LLM 设置。
```bash
-he config set <KEY> <VALUE>
+he config llm [OPTIONS]
```
+### 选项
+
+| 选项 | 简写 | 描述 |
+|--------|-------|-------------|
+| `--api-key` | `-k` | LLM API 密钥 |
+| `--model` | `-m` | LLM 模型名称 |
+| `--base-url` | `-u` | 自定义 API 基础 URL |
+| `--show` | — | 查看当前 LLM 配置 |
+| `--unset` | — | 清除 LLM 配置 |
+
### 示例
```bash
-# 更改默认模型
-he config set llm.model gpt-4o
+# 查看 LLM 配置
+he config llm --show
-# 更改嵌入模型
-he config set embedder.model text-embedding-3-large
+# 修改 LLM 模型
+he config llm --model gpt-4o
-# 设置默认语言
-he config set defaults.language zh
+# 修改 LLM API 密钥和接口地址
+he config llm --api-key sk-your-key --base-url https://api.openai.com/v1
+
+# 重置 LLM 配置
+he config llm --unset
```
---
-## he config get
+## he config embedder
-获取配置值。
+单独配置嵌入模型设置。
```bash
-he config get <KEY>
+he config embedder [OPTIONS]
```
+### 选项
+
+| 选项 | 简写 | 描述 |
+|--------|-------|-------------|
+| `--api-key` | `-k` | 嵌入模型 API 密钥 |
+| `--model` | `-m` | 嵌入模型名称 |
+| `--base-url` | `-u` | 自定义 API 基础 URL |
+| `--show` | — | 查看当前嵌入模型配置 |
+| `--unset` | — | 清除嵌入模型配置 |
+
### 示例
```bash
-he config get llm.model
-# Output: gpt-4o-mini
+# 查看嵌入模型配置
+he config embedder --show
+
+# 使用更大的嵌入模型
+he config embedder --model text-embedding-3-large
-he config get defaults.language
-# Output: en
+# 重置嵌入模型配置
+he config embedder --unset
```
---
@@ -156,39 +173,18 @@ base_url = "https://api.openai.com/v1"
[embedder]
model = "text-embedding-3-small"
-api_key = "sk-your-api-key"
-
-[defaults]
-language = "en"
-chunk_size = 2048
-chunk_overlap = 256
-max_workers = 10
-verbose = false
+api_key = "" # 空字符串表示继承 llm.api_key
+base_url = "" # 空字符串表示继承 llm.base_url
```
----
-
## 环境变量
-也可以通过环境变量设置配置(更高优先级):
-
| 变量 | 描述 |
|----------|-------------|
-| `OPENAI_API_KEY` | LLM 和嵌入器的 API 密钥 |
-| `OPENAI_BASE_URL` | 自定义 API 基础 URL |
-| `HE_LLM_MODEL` | 默认 LLM 模型 |
-| `HE_EMBEDDER_MODEL` | 默认嵌入模型 |
-
----
-
-## 优先级顺序
-
-配置按以下顺序解析(最高优先):
+| `OPENAI_API_KEY` | LLM 和嵌入模型的 API 密钥备用方案 |
+| `OPENAI_BASE_URL` | 自定义 API 基础 URL 备用方案 |
-1. 命令行参数
-2. 环境变量
-3. 配置文件
-4. 内置默认值
+**优先级(从高到低):** 命令行参数 → 环境变量 → 配置文件 → 默认值。
---
@@ -196,31 +192,18 @@ verbose = false
### "未找到 API 密钥"
-初始化配置:
-
```bash
he config init -k your-api-key
```
-或设置环境变量:
+或:
```bash
export OPENAI_API_KEY=your-api-key
```
-### "API 密钥无效"
-
-检查您的 API 密钥:
-
-```bash
-he config show
-# 验证密钥是否正确
-```
-
### "未找到配置文件"
-运行 init 创建:
-
```bash
he config init -k your-api-key
```
@@ -229,5 +212,5 @@ he config init -k your-api-key
## 另请参见
-- [配置参考](../configuration.md) — 详细配置选项
-- [安装指南](../../getting-started/installation.md) — 初始设置
+- [配置参考](../configuration.md) — 详细配置选项说明
+- [安装指南](../../getting-started/installation.md) — 初始安装步骤
diff --git a/docs/zh/cli/commands/feed.md b/docs/zh/cli/commands/feed.md
index 7521b92..b8cbed8 100644
--- a/docs/zh/cli/commands/feed.md
+++ b/docs/zh/cli/commands/feed.md
@@ -57,23 +57,23 @@ he feed ./sushi_kb/ more_sushi.md
### 喂养多个文档
```bash
-he feed ./kb/ doc1.md
-he feed ./kb/ doc2.md
-he feed ./kb/ doc3.md
+he feed ./ka/ doc1.md
+he feed ./ka/ doc2.md
+he feed ./ka/ doc3.md
```
或使用循环:
```bash
for file in updates/*.md; do
- he feed ./kb/ "$file"
+ he feed ./ka/ "$file"
done
```
### 从标准输入
```bash
-cat new_content.md | he feed ./kb/ -
+cat new_content.md | he feed ./ka/ -
```
---
@@ -97,7 +97,7 @@ cat new_content.md | he feed ./kb/ -
```bash
# 第 1 天:初始论文
-he parse paper_v1.md -t general/concept_graph -o ./research_kb/ -l en
+he parse paper_v1.md -t general/concept_graph -o ./research_kb/ -l zh
he show ./research_kb/
# 第 7 天:更新版本
@@ -114,7 +114,7 @@ he talk ./research_kb/ -q "所有论文中的关键概念是什么?"
```bash
# 从早年生活开始
-he parse early_life.md -t general/biography_graph -o ./bio_kb/ -l en
+he parse early_life.md -t general/biography_graph -o ./bio_kb/ -l zh
# 添加职业生涯
he feed ./bio_kb/ career.md
@@ -133,7 +133,7 @@ he show ./bio_kb/
检查 feed 是否成功:
```bash
-he info ./kb/
+he info ./ka/
```
查看:
@@ -147,8 +147,8 @@ he info ./kb/
1. **使用相同模板** — Feed 应使用兼容的模板
2. **匹配语言** — 为获得最佳效果,使用一致的语言
-3. **之后重建索引** — 搜索/聊天需要 `he build-index ./kb/`
-4. **可视化更改** — 使用 `he show ./kb/` 查看更新
+3. **之后重建索引** — 搜索/聊天需要 `he build-index ./ka/`
+4. **可视化更改** — 使用 `he show ./ka/` 查看更新
---
@@ -159,7 +159,7 @@ he info ./kb/
目录不包含有效的知识库。检查:
```bash
-ls ./kb/
+ls ./ka/
# 应该包含:data.json, metadata.json
```
@@ -168,7 +168,7 @@ ls ./kb/
Feed 最适合使用相同类型的模板。如有需要可以覆盖:
```bash
-he feed ./kb/ doc.md -t general/biography_graph
+he feed ./ka/ doc.md -t general/biography_graph
```
---
diff --git a/docs/zh/cli/commands/info.md b/docs/zh/cli/commands/info.md
index 5fb808e..e72458b 100644
--- a/docs/zh/cli/commands/info.md
+++ b/docs/zh/cli/commands/info.md
@@ -56,15 +56,15 @@ Index Built
### 提取后
```bash
-he parse sushi.md -t general/biography_graph -o ./kb/ -l zh
-he info ./kb/
+he parse sushi.md -t general/biography_graph -o ./ka/ -l zh
+he info ./ka/
```
### Feed 后
```bash
-he feed ./kb/ more_content.md
-he info ./kb/
+he feed ./ka/ more_content.md
+he info ./ka/
# 注意更新的节点/边数和时间戳
```
@@ -92,7 +92,7 @@ he info ./kb/
检查提取是否成功:
```bash
-he info ./kb/
+he info ./ka/
# 应该显示 Nodes > 0, Edges > 0
```
@@ -101,9 +101,9 @@ he info ./kb/
在使用搜索或聊天之前:
```bash
-he info ./kb/
+he info ./ka/
# 如果索引显示 "Not Built",运行:
-he build-index ./kb/
+he build-index ./ka/
```
### 监控增长
@@ -111,10 +111,10 @@ he build-index ./kb/
跟踪知识库随时间的增长:
```bash
-he info ./kb/
+he info ./ka/
# 喂养更多文档
-he feed ./kb/ update.md
-he info ./kb/
+he feed ./ka/ update.md
+he info ./ka/
# 比较节点/边数
```
@@ -125,12 +125,12 @@ he info ./kb/
```bash
#!/bin/bash
-if he info ./kb/ 2>/dev/null; then
+if he info ./ka/ 2>/dev/null; then
echo "Knowledge base exists"
- he feed ./kb/ new_doc.md
+ he feed ./ka/ new_doc.md
else
- echo "Creating new knowledge base"
- he parse new_doc.md -t general/biography_graph -o ./kb/ -l en
+ echo "Creating new knowledge abstract"
+ he parse new_doc.md -t general/biography_graph -o ./ka/ -l zh
fi
```
@@ -144,7 +144,7 @@ fi
```bash
# 检查目录存在
-ls ./kb/
+ls ./ka/
# 应该包含:
# - data.json
@@ -156,7 +156,7 @@ ls ./kb/
如果元数据损坏,模板/语言显示为 "unknown":
```bash
-he info ./kb/
+he info ./ka/
# Template: [yellow]unknown[/yellow]
# Language: [yellow]unknown[/yellow]
```
diff --git a/docs/zh/cli/commands/list.md b/docs/zh/cli/commands/list.md
index b2acb33..73a5eed 100644
--- a/docs/zh/cli/commands/list.md
+++ b/docs/zh/cli/commands/list.md
@@ -32,9 +32,9 @@ he list template
Available Templates:
Path Type Description
-general/base_model model Basic model extraction
-general/base_list list Basic list extraction
-general/base_graph graph Basic graph extraction
+general/model model Basic model extraction
+general/list list Basic list extraction
+general/graph graph Basic graph extraction
general/biography_graph temporal_graph Biography graph with timeline
finance/earnings_summary model Financial earnings summary
finance/ownership_graph graph Company ownership structure
@@ -102,7 +102,7 @@ atom graph Temporal knowledge graph
he list template
# 然后使用一个
-he parse doc.md -t general/biography_graph -o ./out/ -l en
+he parse doc.md -t general/biography_graph -o ./out/ -l zh
```
### 选择方法
diff --git a/docs/zh/cli/commands/parse.md b/docs/zh/cli/commands/parse.md
index b59831b..15c36e8 100644
--- a/docs/zh/cli/commands/parse.md
+++ b/docs/zh/cli/commands/parse.md
@@ -36,7 +36,7 @@ he parse INPUT [OPTIONS]
从单个文件提取:
```bash
-he parse document.md -t general/biography_graph -o ./output/ -l en
+he parse document.md -t general/biography_graph -o ./output/ -l zh
```
### 交互式模板选择
@@ -44,12 +44,12 @@ he parse document.md -t general/biography_graph -o ./output/ -l en
省略 `-t` 以从可用模板中选择:
```bash
-he parse document.md -o ./output/ -l en
+he parse document.md -o ./output/ -l zh
# 您将看到:
# Select a template:
# [1] general/biography_graph
-# [2] general/knowledge_graph
+# [2] general/graph
# [3] finance/earnings_summary
# ...
# Enter number or search keyword:
@@ -60,7 +60,7 @@ he parse document.md -o ./output/ -l en
从目录中的所有 `.md` 和 `.txt` 文件提取:
```bash
-he parse ./documents/ -t general/concept_graph -o ./output/ -l en
+he parse ./documents/ -t general/concept_graph -o ./output/ -l zh
```
文件按字母顺序组合后进行提取。
@@ -80,7 +80,7 @@ he parse document.md -m light_rag -o ./output/
覆盖现有输出目录:
```bash
-he parse document.md -t general/biography_graph -o ./output/ -l en -f
+he parse document.md -t general/biography_graph -o ./output/ -l zh -f
```
### 跳过索引构建
@@ -88,7 +88,7 @@ he parse document.md -t general/biography_graph -o ./output/ -l en -f
如果您不需要搜索/聊天,可以加快提取速度:
```bash
-he parse document.md -t general/biography_graph -o ./output/ -l en --no-index
+he parse document.md -t general/biography_graph -o ./output/ -l zh --no-index
```
之后使用 `he build-index` 构建索引。
@@ -96,7 +96,7 @@ he parse document.md -t general/biography_graph -o ./output/ -l en --no-index
### 从标准输入读取
```bash
-cat document.md | he parse - -t general/biography_graph -o ./output/ -l en
+cat document.md | he parse - -t general/biography_graph -o ./output/ -l zh
```
---
@@ -124,7 +124,7 @@ cat document.md | he parse - -t general/biography_graph -o ./output/ -l en
```bash
# 英文
-he parse doc.md -t general/biography_graph -l en -o ./output/
+he parse doc.md -t general/biography_graph -o ./output/ -l zh -o ./output/
# 中文
he parse doc.md -t general/biography_graph -l zh -o ./output/
@@ -139,25 +139,25 @@ he parse doc.md -t general/biography_graph -l zh -o ./output/
### 研究论文
```bash
-he parse paper.md -t general/concept_graph -o ./paper_kb/ -l en
+he parse paper.md -t general/concept_graph -o ./paper_kb/ -l zh
```
### 传记
```bash
-he parse biography.md -t general/biography_graph -o ./bio_kb/ -l en
+he parse biography.md -t general/biography_graph -o ./output/ -l zh
```
### 法律合同
```bash
-he parse contract.md -t legal/contract_obligation -o ./contract_kb/ -l en
+he parse contract.md -t legal/contract_obligation -o ./contract_kb/ -l zh
```
### 财务报告
```bash
-he parse earnings.md -t finance/earnings_summary -o ./finance_kb/ -l en
+he parse earnings.md -t finance/earnings_summary -o ./finance_kb/ -l zh
```
---
@@ -186,7 +186,7 @@ he parse earnings.md -t finance/earnings_summary -o ./finance_kb/ -l en
```bash
# 模板 - 需要 -l
-he parse doc.md -t general/biography_graph -o ./out/ -l en
+he parse doc.md -t general/biography_graph -o ./output/ -l zh
# 方法 - 不需要 -l
he parse doc.md -m light_rag -o ./out/
diff --git a/docs/zh/cli/commands/search.md b/docs/zh/cli/commands/search.md
index 3f9a410..c278f32 100644
--- a/docs/zh/cli/commands/search.md
+++ b/docs/zh/cli/commands/search.md
@@ -48,15 +48,15 @@ he search ./output/ "苏轼的代表作"
### 获取更多结果
```bash
-he search ./output/ "electrical engineering" -n 10
+he search ./output/ "电气工程" -n 10
```
### 自然语言查询
```bash
-he search ./kb/ "主要成就是什么?"
-he search ./kb/ "与欧阳修相关的人"
-he search ./kb/ "苏轼生平重要年份"
+he search ./ka/ "主要成就是什么?"
+he search ./ka/ "与欧阳修相关的人"
+he search ./ka/ "苏轼生平重要年份"
```
### 构建索引后
@@ -66,7 +66,7 @@ he search ./kb/ "苏轼生平重要年份"
he build-index ./output/
# 然后搜索
-he search ./output/ "innovation"
+he search ./output/ "创新"
```
---
diff --git a/docs/zh/cli/commands/show.md b/docs/zh/cli/commands/show.md
index 83d9c91..aa0e6f8 100644
--- a/docs/zh/cli/commands/show.md
+++ b/docs/zh/cli/commands/show.md
@@ -115,7 +115,7 @@ http://localhost:xxxx
检查提取是否成功:
```bash
-he info ./kb/
+he info ./ka/
# 应该显示 Nodes > 0 和 Edges > 0
```
@@ -125,10 +125,10 @@ he info ./kb/
```bash
# 检查数据文件存在
-ls ./kb/data.json
+ls ./ka/data.json
# 尝试重新加载
-he show ./kb/
+he show ./ka/
```
---
diff --git a/docs/zh/cli/commands/talk.md b/docs/zh/cli/commands/talk.md
index 0e5c7dc..f6dbc50 100644
--- a/docs/zh/cli/commands/talk.md
+++ b/docs/zh/cli/commands/talk.md
@@ -99,7 +99,7 @@ Goodbye!
Other useful commands:
he show ./output/ # 可视化
- he search ./output/ "keyword" # 搜索
+ he search ./output/ "关键词" # 搜索
he info ./output/ # 查看信息
```
diff --git a/docs/zh/cli/configuration.md b/docs/zh/cli/configuration.md
index 5de5f63..5dfb22a 100644
--- a/docs/zh/cli/configuration.md
+++ b/docs/zh/cli/configuration.md
@@ -1,173 +1,171 @@
# CLI 配置参考
-Hyper-Extract CLI 配置的完整参考。
+Hyper-Extract CLI 的配置指南,从快速入门到高级设置。
---
-## 配置文件位置
+## 快速开始
-- **Linux/macOS**: `~/.he/config.toml`
-- **Windows**: `%USERPROFILE%\.he\config.toml`
+只需 3 步完成配置。
----
+### 1. 初始化配置
-## 配置部分
+```bash
+he config init -k YOUR_API_KEY
+```
-### [llm] — 语言模型设置
+这会创建 `~/.he/config.toml` 配置文件,使用以下默认值:
+- **LLM**: `gpt-4o-mini`
+- **嵌入模型**: `text-embedding-3-small`
-| 键 | 描述 | 默认值 |
-|-----|-------------|---------|
-| `model` | LLM 模型名称 | `gpt-4o-mini` |
-| `api_key` | OpenAI API 密钥 | *必填* |
-| `base_url` | API 基础 URL | `https://api.openai.com/v1` |
+### 2. 验证配置
-**示例:**
-```toml
-[llm]
-model = "gpt-4o"
-api_key = "sk-your-api-key"
-base_url = "https://api.openai.com/v1"
+```bash
+he config show
```
-**支持的模型:**
-- `gpt-4o-mini` — 快速、成本效益高
-- `gpt-4o` — 高质量
-- `gpt-4-turbo` — 最佳质量
-- 其他 OpenAI 兼容模型
+看到类似输出即配置成功:
----
+```
+┌─────────────────────────────────────────────────────────┐
+│ Hyper-Extract Configuration │
+├──────────┬─────────────────────┬─────────────┬──────────┤
+│ Service │ Model │ API Key │ Base URL │
+├──────────┼─────────────────────┼─────────────┼──────────┤
+│ LLM │ gpt-4o-mini │ sk-xxxxx... │ (default)│
+│ Embedder │ text-embedding-3... │ sk-xxxxx... │ (default)│
+└──────────┴─────────────────────┴─────────────┴──────────┘
+```
-### [embedder] — 嵌入模型设置
+### 3. 修改配置(如需)
-| 键 | 描述 | 默认值 |
-|-----|-------------|---------|
-| `model` | 嵌入模型名称 | `text-embedding-3-small` |
-| `api_key` | API 密钥(默认为 llm.api_key) | — |
+```bash
+# 更换 LLM 模型
+he config llm --model gpt-4o
-**示例:**
-```toml
-[embedder]
-model = "text-embedding-3-large"
-```
+# 使用不同的嵌入模型
+he config embedder --model text-embedding-3-large
-**支持的模型:**
-- `text-embedding-3-small` — 快速、成本效益高
-- `text-embedding-3-large` — 更好的质量
-- `text-embedding-ada-002` — 传统模型
+# 配置自定义 API 端点
+he config llm --base-url https://your-api-endpoint.com/v1
+```
---
-### [defaults] — 默认行为设置
+## CLI 命令参考
-| 键 | 描述 | 默认值 |
-|-----|-------------|---------|
-| `language` | 默认语言(`en` 或 `zh`) | `en` |
-| `chunk_size` | 处理文本的块大小 | `2048` |
-| `chunk_overlap` | 块之间的重叠 | `256` |
-| `max_workers` | 并行处理工作线程数 | `10` |
-| `verbose` | 启用详细输出 | `false` |
+### 命令概览
-**示例:**
-```toml
-[defaults]
-language = "en"
-chunk_size = 4096
-chunk_overlap = 512
-max_workers = 5
-verbose = true
+| 命令 | 常用参数 | 描述 |
+|------|---------|------|
+| `he config init` | `-k, --api-key` — API 密钥<br>`-u, --base-url` — 自定义 API 地址 | 初始化配置(首次使用) |
+| `he config llm` | `-m, --model` — 模型名称<br>`-k, --api-key` — API 密钥<br>`-u, --base-url` — 自定义 API 地址<br>`--show` — 查看当前配置<br>`--unset` — 清除配置 | 配置 LLM |
+| `he config embedder` | `-m, --model` — 模型名称<br>`-k, --api-key` — API 密钥<br>`-u, --base-url` — 自定义 API 地址<br>`--show` — 查看当前配置<br>`--unset` — 清除配置 | 配置嵌入模型 |
+| `he config show` | — | 查看完整配置 |
+
+### 常见用法示例
+
+**交互式初始化(推荐首次使用):**
+```bash
+he config init
+# 按提示输入模型名、API 密钥等信息
```
----
+**非交互式初始化(脚本中使用):**
+```bash
+he config init -k sk-your-api-key
+```
-## 环境变量
+**查看 LLM 配置:**
+```bash
+he config llm --show
+```
-所有配置选项都可以通过环境变量设置:
+**单独配置嵌入模型(使用不同密钥):**
+```bash
+he config embedder --api-key sk-embedder-key --model text-embedding-3-large
+```
-| 变量 | 映射到 | 示例 |
-|----------|---------|---------|
-| `OPENAI_API_KEY` | `llm.api_key`, `embedder.api_key` | `sk-...` |
-| `OPENAI_BASE_URL` | `llm.base_url` | `https://api.openai.com/v1` |
-| `HE_LLM_MODEL` | `llm.model` | `gpt-4o` |
-| `HE_EMBEDDER_MODEL` | `embedder.model` | `text-embedding-3-large` |
-| `HE_DEFAULT_LANGUAGE` | `defaults.language` | `zh` |
-| `HE_CHUNK_SIZE` | `defaults.chunk_size` | `4096` |
-| `HE_VERBOSE` | `defaults.verbose` | `true` |
+**清除配置(重置为默认值):**
+```bash
+he config llm --unset
+he config embedder --unset
+```
---
-## 完整示例
+## 配置文件详解
-```toml
-# ~/.he/config.toml
+当你运行 `he config init` 时,会自动创建 `~/.he/config.toml` 文件。
+
+### 文件位置
+
+- **Linux/macOS**: `~/.he/config.toml`
+- **Windows**: `%USERPROFILE%\.he\config.toml`
+### 配置格式
+
+```toml
[llm]
model = "gpt-4o-mini"
-api_key = "sk-your-api-key-here"
+api_key = "sk-your-api-key"
base_url = "https://api.openai.com/v1"
[embedder]
model = "text-embedding-3-small"
-# api_key 默认为 llm.api_key
-
-[defaults]
-language = "en"
-chunk_size = 2048
-chunk_overlap = 256
-max_workers = 10
-verbose = false
+api_key = "" # 空字符串表示继承 llm.api_key
+base_url = "" # 空字符串表示继承 llm.base_url
```
----
-
-## 配置优先级
+### 配置项说明
-设置按以下顺序解析(最高优先级优先):
+| 节 | 键 | 描述 | 默认值 |
+|---|-----|------|--------|
+| `[llm]` | `model` | LLM 模型名称 | `gpt-4o-mini` |
+| `[llm]` | `api_key` | OpenAI API 密钥 | 必填 |
+| `[llm]` | `base_url` | API 基础 URL | `https://api.openai.com/v1` |
+| `[embedder]` | `model` | 嵌入模型名称 | `text-embedding-3-small` |
+| `[embedder]` | `api_key` | API 密钥(留空继承 llm) | — |
+| `[embedder]` | `base_url` | API 基础 URL(留空继承 llm) | — |
-1. **命令行参数**(例如 `-l zh`)
-2. **环境变量**(例如 `OPENAI_API_KEY`)
-3. **配置文件**(`~/.he/config.toml`)
-4. **内置默认值**
+### 支持的模型
----
-
-## 管理配置
-
-### 初始化
-
-```bash
-he config init -k your-api-key
-```
+**LLM 模型:**
+- `gpt-4o-mini` — 快速、成本效益高(默认)
+- `gpt-4o` — 高质量
+- `gpt-4-turbo` — 最佳质量
+- 其他 OpenAI 兼容模型
-### 查看当前设置
+**嵌入模型:**
+- `text-embedding-3-small` — 快速、成本效益高(默认)
+- `text-embedding-3-large` — 更好的质量
+- `text-embedding-ada-002` — 传统模型
-```bash
-he config show
-```
+---
-### 更新设置
+## 环境变量
-```bash
-# 更新单个值
-he config set llm.model gpt-4o
+以下环境变量可作为配置的备选方案:
-# 或直接编辑文件
-nano ~/.he/config.toml
-```
+| 变量 | 映射到 | 示例 |
+|------|--------|------|
+| `OPENAI_API_KEY` | `llm.api_key`, `embedder.api_key` | `sk-...` |
+| `OPENAI_BASE_URL` | `llm.base_url` | `https://api.openai.com/v1` |
-### 重置为默认值
+**优先级说明:** 环境变量优先级高于配置文件,低于命令行参数。
-```bash
-rm ~/.he/config.toml
-he config init -k your-api-key
-```
+**使用场景:**
+- 临时切换 API 密钥
+- CI/CD 环境中注入密钥
+- 不想在配置文件中硬编码密钥
---
## 高级配置
-### 自定义 API 端点
+### 使用 OpenAI 兼容 API
-对于 OpenAI 兼容 API(Azure、本地模型等):
+对于 Azure、本地模型等 OpenAI 兼容 API:
```toml
[llm]
@@ -179,46 +177,73 @@ base_url = "https://your-api-endpoint.com/v1"
model = "your-embedding-model"
```
-### LLM 和嵌入器使用不同密钥
+### LLM 和嵌入器使用不同密钥和不同 base_url
```toml
[llm]
model = "gpt-4o-mini"
api_key = "sk-llm-key"
+base_url = "https://api.openai.com/v1"
[embedder]
-model = "text-embedding-3-small"
+model = "text-embedding-3-large"
api_key = "sk-embedder-key"
+base_url = "https://your-embedder-provider.com/v1"
```
---
## 故障排除
+### "API key not found"
+
+**原因**: 未配置 API 密钥
+
+**解决**:
+
+```bash
+he config init -k YOUR_API_KEY
+```
+
+### "Failed to connect to API"
+
+**原因**: 网络问题或 base_url 配置错误
+
+**解决**:
+
+```bash
+# 检查配置
+he config llm --show
+
+# 重新设置 base_url
+he config llm --base-url https://api.openai.com/v1
+```
+
### 权限被拒绝
+**解决**:
+
```bash
-# 修复权限
chmod 600 ~/.he/config.toml
```
### 无效的 TOML 格式
-验证配置:
+**验证配置**:
```bash
-# 使用 Python
-python -c "import tomllib; tomllib.load(open('~/.he/config.toml', 'rb'))"
+python3 -c "import tomllib; tomllib.load(open('$HOME/.he/config.toml', 'rb'))"
```
-常见问题:
+**常见问题**:
+
- 字符串缺少引号
-- 尾部逗号
-- 错误的节标题
+- 多余的逗号
+- 错误的节标题(如使用中文标点)
---
## 另请参见
-- [`he config`](commands/config.md) — 配置命令
-- [安装指南](../getting-started/installation.md) — 初始设置
+- [`he config`](commands/config.md) — 详细的配置命令说明
+- [安装指南](../getting-started/installation.md) — 初始安装步骤
diff --git a/docs/zh/cli/index.md b/docs/zh/cli/index.md
index 96b7841..e9d377d 100644
--- a/docs/zh/cli/index.md
+++ b/docs/zh/cli/index.md
@@ -49,22 +49,22 @@ he --version
```mermaid
flowchart TB
subgraph Create ["🚀 创建"]
- D[📄 Document] -->|he parse| KB[(💡 Knowledge Base)]
+ D[📄 Document] -->|he parse| KA[(💡 Knowledge Abstract)]
end
subgraph Enhance ["✨ 增强(可选)"]
- KB -->|he feed| KB
- KB -->|he build-index| IDX[(🔍 Index)]
+ KA -->|he feed| KA
+ KA -->|he build-index| IDX[(🔍 Index)]
end
subgraph Explore ["🔍 探索"]
- KB -->|he show| VIS[👁️ Visualize]
+ KA -->|he show| VIS[👁️ Visualize]
IDX -->|he search| SRCH[🔎 Search]
IDX -->|he talk| CHAT[💬 Chat]
end
subgraph Save ["💾 保存"]
- KB -->|he dump| DISK[💾 Disk]
+ KA -->|he dump| DISK[💾 Disk]
end
```
@@ -88,7 +88,7 @@ he config init -k YOUR_OPENAI_API_KEY
### 2. 提取知识
```bash
-he parse document.md -t general/biography_graph -o ./output/ -l en
+he parse document.md -t general/biography_graph -o ./output/ -l zh
```
### 3. 可视化
@@ -138,7 +138,7 @@ Hyper-Extract 提供两种提取知识的方式:
特定领域的开箱即用配置:
```bash
-he parse doc.md -t general/biography_graph -l en
+he parse doc.md -t general/biography_graph -l zh
```
### 方法(高级)
@@ -159,7 +159,7 @@ he parse doc.md -m light_rag
```bash
# 英文
-he parse doc.md -t general/biography_graph -l en
+he parse doc.md -t general/biography_graph -l zh
# 中文
he parse doc.md -t general/biography_graph -l zh
@@ -175,7 +175,7 @@ he parse doc.md -t general/biography_graph -l zh
```bash
# 从研究论文提取
-he parse paper.md -t general/concept_graph -o ./paper_kb/ -l en
+he parse paper.md -t general/concept_graph -o ./paper_kb/ -l zh
# 提问
he talk ./paper_kb/ -q "主要贡献是什么?"
@@ -185,7 +185,7 @@ he talk ./paper_kb/ -q "主要贡献是什么?"
```bash
# 从传记提取
-he parse biography.md -t general/biography_graph -o ./bio_kb/ -l en
+he parse biography.md -t general/biography_graph -o ./bio_kb/ -l zh
# 可视化生平事件
he show ./bio_kb/
@@ -195,10 +195,10 @@ he show ./bio_kb/
```bash
# 提取合同义务
-he parse contract.md -t legal/contract_obligation -o ./contract_kb/ -l en
+he parse contract.md -t legal/contract_obligation -o ./contract_kb/ -l zh
# 搜索特定条款
-he search ./contract_kb/ "termination conditions"
+he search ./contract_kb/ "终止条件"
```
---
diff --git a/docs/zh/cli/workflow.md b/docs/zh/cli/workflow.md
index 69667f9..c2e46c7 100644
--- a/docs/zh/cli/workflow.md
+++ b/docs/zh/cli/workflow.md
@@ -12,45 +12,11 @@
## 步骤 1:准备文档
-首先,确保您的文档是支持的格式(`.md`、`.txt`):
+Hyper-Extract 支持 `.md` 和 `.txt` 文件。下载下面的示例研究论文以跟随本指南:
-```bash
-# 示例:将 PDF 转换为文本(使用外部工具)
-pdftotext paper.pdf paper.md
-```
+<a href="/assets/examples/zh/transformer_paper.txt" download class="md-button">📥 下载示例文档</a>
-或创建一个示例文档:
-
-```bash
-cat > transformer_paper.md << 'EOF'
-# Attention Is All You Need
-
-## Abstract
-The dominant sequence transduction models are based on complex recurrent or
-convolutional neural networks that include an encoder and a decoder. The best
-performing models also connect the encoder and decoder through an attention
-mechanism. We propose a new simple network architecture, the Transformer,
-based solely on attention mechanisms.
-
-## Authors
-- Ashish Vaswani
-- Noam Shazeer
-- Niki Parmar
-- Jakob Uszkoreit
-- Llion Jones
-- Aidan N. Gomez
-- Lukasz Kaiser
-- Illia Polosukhin
-
-## Key Innovation
-The Transformer eschews recurrence and instead relies entirely on an attention
-mechanism to draw global dependencies between input and output sequences.
-
-## Performance
-On the WMT 2014 English-to-German translation task, our model achieves a
-BLEU score of 28.4, outperforming all existing models.
-EOF
-```
+将文件保存为 `transformer_paper.md` 在你的工作目录中。
---
@@ -59,7 +25,7 @@ EOF
使用 `parse` 命令提取知识:
```bash
-he parse transformer_paper.md -t general/concept_graph -o ./transformer_kb/ -l en
+he parse transformer_paper.md -t general/concept_graph -o ./transformer_kb/ -l zh
```
**发生了什么:**
@@ -105,7 +71,10 @@ Index Built
he show ./transformer_kb/
```
+![知识图谱可视化](../../assets/zh_show.png)
+
这将在浏览器中打开交互式图谱,显示:
+
- **节点**:作者、概念、模型、指标
- **边**:它们之间的关系
@@ -118,7 +87,7 @@ he show ./transformer_kb/
即使关键词不完全匹配也能查找信息:
```bash
-he search ./transformer_kb/ "neural network architecture"
+he search ./transformer_kb/ "神经网络架构"
```
**结果:**
@@ -144,7 +113,7 @@ Result 2:
### 特定查询
```bash
-he search ./transformer_kb/ "performance metrics" -n 5
+he search ./transformer_kb/ "性能指标" -n 5
```
---
@@ -252,7 +221,7 @@ echo
# 步骤 3: 搜索示例
echo "Step 3: Sample search:"
-he search "$OUTPUT_DIR" "main contributions" -n 2
+he search "$OUTPUT_DIR" "主要贡献" -n 2
echo
# 步骤 4: 打开可视化
@@ -270,17 +239,17 @@ echo "=== Workflow Complete ==="
```bash
# 创建输出目录
-mkdir -p ./kb/paper1 ./kb/paper2 ./kb/paper3
+mkdir -p ./ka/paper1 ./ka/paper2 ./ka/paper3
# 处理每个
-he parse papers/paper1.md -t general/concept_graph -o ./kb/paper1/ -l en
-he parse papers/paper2.md -t general/concept_graph -o ./kb/paper2/ -l en
-he parse papers/paper3.md -t general/concept_graph -o ./kb/paper3/ -l en
+he parse papers/paper1.md -t general/concept_graph -o ./ka/paper1/ -l zh
+he parse papers/paper2.md -t general/concept_graph -o ./ka/paper2/ -l zh
+he parse papers/paper3.md -t general/concept_graph -o ./ka/paper3/ -l zh
# 或使用循环
for file in papers/*.md; do
name=$(basename "$file" .md)
- he parse "$file" -t general/concept_graph -o "./kb/$name/" -l en
+ he parse "$file" -t general/concept_graph -o "./ka/$name/" -l zh
done
```
@@ -292,40 +261,40 @@ done
```bash
# 初始提取
-he parse initial_doc.md -t general/biography_graph -o ./kb/ -l en
+he parse initial_doc.md -t general/biography_graph -o ./ka/ -l zh
# 每周更新
-he feed ./kb/ week1_update.md
-he feed ./kb/ week2_update.md
-he feed ./kb/ week3_update.md
+he feed ./ka/ week1_update.md
+he feed ./ka/ week2_update.md
+he feed ./ka/ week3_update.md
# 每月重建
-he build-index ./kb/ -f
+he build-index ./ka/ -f
```
### 模式 2:多领域项目
```bash
# 技术文档
-he parse api_docs.md -t general/concept_graph -o ./project_kb/tech/ -l en
+he parse api_docs.md -t general/concept_graph -o ./project_kb/tech/ -l zh
# 法律合同
-he parse contract.pdf -t legal/contract_obligation -o ./project_kb/legal/ -l en
+he parse contract.md -t legal/contract_obligation -o ./project_kb/legal/ -l zh
# 财务报告
-he parse q4_report.md -t finance/earnings_summary -o ./project_kb/finance/ -l en
+he parse q4_report.md -t finance/earnings_summary -o ./project_kb/finance/ -l zh
```
### 模式 3:比较文档
```bash
# 提取两个版本
-he parse draft_v1.md -t general/concept_graph -o ./kb/v1/ -l en
-he parse draft_v2.md -t general/concept_graph -o ./kb/v2/ -l en
+he parse draft_v1.md -t general/concept_graph -o ./ka/v1/ -l zh
+he parse draft_v2.md -t general/concept_graph -o ./ka/v2/ -l zh
# 通过聊天比较
-he talk ./kb/v1/ -q "主要主题是什么?"
-he talk ./kb/v2/ -q "主要主题是什么?"
+he talk ./ka/v1/ -q "主要主题是什么?"
+he talk ./ka/v2/ -q "主要主题是什么?"
```
---
@@ -335,7 +304,7 @@ he talk ./kb/v2/ -q "主要主题是什么?"
| 问题 | 解决方案 |
|-------|----------|
| 提取速度慢 | 长文档会被分块;使用 `--no-index` 在解析时跳过索引 |
-| 搜索无结果 | 确保索引已构建:`he build-index ./kb/` |
+| 搜索无结果 | 确保索引已构建:`he build-index ./ka/` |
| 模板未找到 | 列出可用模板:`he list template` |
| 内存不足 | 减少配置中的块大小或处理较小的文档 |
diff --git a/docs/zh/concepts/autotypes.md b/docs/zh/concepts/autotypes.md
index 94d467d..61d398e 100644
--- a/docs/zh/concepts/autotypes.md
+++ b/docs/zh/concepts/autotypes.md
@@ -1,286 +1,292 @@
# 自动类型
-8 种知识结构类型的完整指南。
+了解 8 种知识结构类型:它们是什么以及何时使用。
---
-## 概述
+## 什么是自动类型?
-自动类型是智能数据结构,具有以下功能:
-- 定义提取输出格式
-- 提供类型安全的 schema
-- 包含内置操作(搜索、可视化等)
-- 支持序列化
+自动类型是定义提取知识如何组织的智能数据结构。可以将它们视为塑造文档输出结果的"容器"。
+
+核心特性:
+
+| 特性 | 描述 |
+|----------------|-------------|
+| **类型安全** | 基于 Pydantic 的验证确保数据一致性 |
+| **自包含** | 内置操作(搜索、可视化、保存) |
+| **可序列化** | 可保存到磁盘,稍后加载 |
+| **可组合** | 可合并、更新、增量扩展 |
---
## 8 种自动类型
+分为两个类别:
+
```mermaid
graph TD
- A[Auto-Types] --> B[Scalar Types]
- A --> C[Graph Types]
- A --> D[Temporal Types]
-
- B --> B1[AutoModel]
- B --> B2[AutoList]
- B --> B3[AutoSet]
-
- C --> C1[AutoGraph]
- C --> C2[AutoHypergraph]
-
- D --> D1[AutoTemporalGraph]
- D --> D2[AutoSpatialGraph]
- D --> D3[AutoSpatioTemporalGraph]
+ A[自动类型] --> B[记录类型<br/>存储数据,无实体关系]
+ A --> C[图谱类型<br/>实体间关系]
+
+ B --> B1[AutoModel<br/>单个结构化对象]
+ B --> B2[AutoList<br/>有序项目]
+ B --> B3[AutoSet<br/>唯一项目]
+
+ C --> C1[AutoGraph<br/>二元关系]
+ C --> C2[AutoHypergraph<br/>多实体关系]
+ C --> C3[AutoTemporalGraph<br/>+ 时间]
+ C --> C4[AutoSpatialGraph<br/>+ 位置]
+ C --> C5[AutoSpatioTemporalGraph<br/>+ 时间 + 位置]
```
---
-## 标量类型
+## 记录类型
+
+用于**记录和存储数据**,不涉及实体之间的关系。
+
+记录类型提取的是**独立的数据项**,每个项目本身不包含与其他项目的关联信息。
### AutoModel
-**目的**:单个结构化对象
+**用途**:提取单个结构化对象
+
+**类比**:一个需要填写的表单
-**使用场景**:
-- 提取摘要/报告
-- 具有已知字段的结构化数据
-- 具有许多属性的单个实体
+**示例用例**:
+- 公司财报(收入、利润、增长)
+- 产品规格(名称、价格、特性)
+- 个人档案(姓名、出生日期、职业)
-**示例输出**:
-```python
+**示例输出结构**:
+```json
{
- "name": "苏轼",
- "style_name": "子瞻",
- "art_name": "东坡居士",
- "dynasty": "北宋",
- "birth_year": 1037,
- "masterpiece": "念奴娇·赤壁怀古"
+ "company_name": "Tesla Inc",
+ "revenue": 81.46,
+ "employees": 127855
}
```
-**常用模板**:
-- `finance/earnings_summary`
-- `general/base_model`
+**常用模板**:`finance/earnings_summary`, `general/model`
---
### AutoList
-**目的**:有序集合
+**用途**:提取有序集合
-**使用场景**:
-- 顺序很重要
-- 排名项目
-- 简单的时间线事件
+**类比**:排名列表或序列
-**示例输出**:
-```python
+**示例用例**:
+- 史上十佳电影
+- 分步骤流程
+- 时间线事件(简单时间顺序列表)
+
+**示例输出结构**:
+```json
{
"items": [
- {"name": "《念奴娇·赤壁怀古》", "year": 1082},
- {"name": "《水调歌头·明月几时有》", "year": 1076},
- {"name": "《赤壁赋》", "year": 1082}
+ {"name": "Tesla Coil", "year": 1891},
+ {"name": "Radio", "year": 1898}
]
}
```
-**常用模板**:
-- `general/base_list`
-- `legal/compliance_list`
+**关键特性**:顺序很重要 - 项目按序列排列
+
+**常用模板**:`general/list`, `legal/compliance_list`
---
### AutoSet
-**目的**:去重集合
+**用途**:提取唯一项目(无重复)
+
+**类比**:一组唯一的标签
-**使用场景**:
-- 仅唯一项目
-- 标签/类别
-- 成员资格测试
+**示例用例**:
+- 文档关键词
+- 类别或标签
+- 技能集合
-**示例输出**:
-```python
+**示例输出结构**:
+```json
{
- "items": [
- "豪放词",
- "行书",
- "文人画",
- "宋四家"
- ]
+ "items": ["Electrical Engineering", "Physics", "Invention"]
}
```
-**常用模板**:
-- `general/base_set`
-- `finance/risk_factor_set`
+**关键特性**:自动去重
+
+**常用模板**:`general/set`, `finance/risk_factor_set`
---
## 图谱类型
-### AutoGraph
+用于表示**实体之间的关系**。图谱类型不仅包含实体本身(节点),还包含实体之间的连接(边)。
+
+图谱类型根据关系的复杂程度和附加的维度信息,分为以下几种子类型:
+
+### 基础图谱
+
+#### AutoGraph
+
+**用途**:提取二元关系(一次两个实体)
-**目的**:实体关系网络
+**类比**:社交网络图
-**使用场景**:
-- 人物、组织、概念
-- 二元关系
-- 知识图谱
+**示例用例**:
+- 人际关系(合作过、结婚)
+- 概念关系(is-a、part-of)
+- 组织互动
-**示例输出**:
-```python
+**示例输出结构**:
+```json
{
"nodes": [
- {"name": "苏轼", "type": "人物"},
- {"name": "苏辙", "type": "人物"},
- {"name": "欧阳修", "type": "人物"},
- {"name": "《赤壁赋》", "type": "作品"}
+ {"name": "Tesla", "type": "person"},
+ {"name": "AC Motor", "type": "invention"}
],
"edges": [
- {"source": "苏轼", "target": "苏辙", "type": "兄弟"},
- {"source": "苏轼", "target": "欧阳修", "type": "师生"},
- {"source": "苏轼", "target": "《赤壁赋》", "type": "创作"}
+ {"source": "Tesla", "target": "AC Motor", "type": "invented"}
]
}
```
-**常用模板**:
-- `general/knowledge_graph`
-- `general/biography_graph`
+**关键特性**:每个关系连接恰好两个实体
+
+**常用模板**:`general/graph`, `general/biography_graph`
---
-### AutoHypergraph
+#### AutoHypergraph
+
+**用途**:提取涉及 3+ 实体的关系
-**目的**:多实体关系
+**类比**:多人协作的项目团队
-**使用场景**:
-- 关系涉及 3+ 个实体
-- 复杂交互
-- N 元关联
+**示例用例**:
+- 多方协作
+- 复杂交互(买方、卖方、经纪人)
+- 群体成员关系
-**示例输出**:
-```python
+**示例输出结构**:
+```json
{
"nodes": [...],
"edges": [
{
- "entities": ["苏轼", "苏辙", "苏洵"],
- "type": "三苏",
- "description": "父子三人同列唐宋八大家"
+ "entities": ["Tesla", "Westinghouse", "Niagara"],
+ "type": "collaboration"
}
]
}
```
-**常用模板**:
-- `general/base_hypergraph`
+**关键特性**:一个"边"可连接多个实体
+
+**常用模板**:`general/base_hypergraph`
---
-## 时序类型
+### 增强图谱(带维度信息)
+
+在基础图谱上增加了**时间**或**空间**维度,用于更丰富的关系描述。
+
+#### AutoTemporalGraph(时序图谱)
-### AutoTemporalGraph
+**用途**:提取带时间信息的关系
-**目的**:图谱 + 时间信息
+**类比**:带连接的时间线
-**使用场景**:
-- 时间线很重要
-- 事件序列
+**示例用例**:
+- 传记(带日期的生活事件)
+- 项目历史
- 历史分析
-**示例输出**:
-```python
+**示例输出结构**:
+```json
{
- "nodes": [...],
"edges": [
{
- "source": "苏轼",
- "target": "《念奴娇·赤壁怀古》",
- "type": "创作",
- "time": "1082"
- },
- {
- "source": "苏轼",
- "target": "黄州",
- "type": "贬谪",
- "time": "1080-1084"
+ "source": "Tesla",
+ "target": "AC Motor",
+ "type": "invented",
+ "time": "1888"
}
]
}
```
-**常用模板**:
-- `general/base_temporal_graph`
-- `finance/event_timeline`
+**关键特性**:每个关系都有时间组件
+
+**常用模板**:`general/base_temporal_graph`, `finance/event_timeline`
---
-### AutoSpatialGraph
+#### AutoSpatialGraph(空间图谱)
-**目的**:图谱 + 位置信息
+**用途**:提取带位置信息的关系
-**使用场景**:
-- 地理数据
-- 基于位置的分析
-- 映射
+**类比**:带连接的地图
-**示例输出**:
-```python
+**示例用例**:
+- 旅行日志
+- 地理网络
+- 基于位置的资产追踪
+
+**示例输出结构**:
+```json
{
- "nodes": [
- {
- "name": "黄州",
- "type": "地点",
- "coordinates": "湖北省黄冈市"
- }
+ "entities": [
+ {"name": "Colorado Springs", "location": "38.83,-104.82"}
],
- "edges": [
+ "relations": [
{
- "source": "苏轼",
- "target": "黄州",
- "type": "躬耕",
- "location": "东坡"
+ "source": "Tesla",
+ "target": "Colorado Springs",
+ "type": "conducted_experiments"
}
]
}
```
-**常用模板**:
-- `general/base_spatial_graph`
+**关键特性**:实体或关系具有地理坐标
+
+**常用模板**:`general/base_spatial_graph`
---
-### AutoSpatioTemporalGraph
+#### AutoSpatioTemporalGraph(时空图谱)
-**目的**:图谱 + 时间 + 空间
+**用途**:提取同时带时间和地点的关系
-**使用场景**:
-- 需要完整上下文
-- 历史地理
-- 带时间和地点的事件分析
+**类比**:带日期事件的历史地图
-**示例输出**:
-```python
+**示例用例**:
+- 军事历史(带时间和地点的战役)
+- 流行病追踪
+- 历史迁徙
+
+**示例输出结构**:
+```json
{
- "nodes": [...],
- "edges": [
+ "relations": [
{
- "source": "苏轼",
- "target": "《赤壁赋》",
- "type": "创作",
- "time": "1082",
- "location": "黄州",
- "description": "夜游赤壁,饮酒赋诗"
+ "source": "Tesla",
+ "target": "AC Motor",
+ "type": "demonstrated",
+ "time": "1888",
+ "location": "Pittsburgh"
}
]
}
```
-**常用模板**:
-- `general/base_spatio_temporal_graph`
+**关键特性**:完整上下文 - 谁、什么、何时、何地
+
+**常用模板**:`general/base_spatio_temporal_graph`
---
@@ -289,80 +295,71 @@ graph TD
### 决策树
```
-需要提取什么?
+你需要提取什么?
│
-├─ 单个结构化对象 → AutoModel
+├─ 单个结构化对象(如表单)
+│ └─ AutoModel
│
├─ 项目集合
-│ ├─ 有序/排名 → AutoList
-│ └─ 唯一/标签 → AutoSet
+│ ├─ 顺序重要? → AutoList
+│ └─ 仅需唯一项目? → AutoSet
│
-└─ 关系
- ├─ 简单(二元)
- │ ├─ 带时间 → AutoTemporalGraph
- │ ├─ 带空间 → AutoSpatialGraph
- │ ├─ 两者都 → AutoSpatioTemporalGraph
- │ └─ 两者都不 → AutoGraph
- │
- └─ 复杂(多实体)
- └─ AutoHypergraph
+└─ 实体之间的关系 → 图谱类型
+ ├─ 关系数量
+ │ ├─ 二元关系(2个实体)→ 基础图谱
+ │ │ ├─ 需要时间信息? → AutoTemporalGraph
+ │ │ ├─ 需要位置信息? → AutoSpatialGraph
+ │ │ ├─ 两者都需要? → AutoSpatioTemporalGraph
+ │ │ └─ 都不需要? → AutoGraph
+ │ │
+ │ └─ 多元关系(3+个实体)→ AutoHypergraph
```
-### 按用例
-
-| 用例 | 推荐类型 |
-|----------|------------------|
-| 公司报告 | AutoModel |
-| Top 10 列表 | AutoList |
-| 标签/关键词 | AutoSet |
-| 人物网络 | AutoGraph |
-| 项目团队 | AutoHypergraph |
-| 传记时间线 | AutoTemporalGraph |
-| 旅行日志 | AutoSpatialGraph |
-| 历史事件 | AutoSpatioTemporalGraph |
-
----
-
-## 常见操作
+### 按用例选择
-所有自动类型都支持:
+| 用例 | 自动类型 | 原因 |
+|----------|-----------|-----|
+| 公司财报 | AutoModel | 单结构摘要 |
+| Top 10 列表 | AutoList | 有序/排名项目 |
+| 关键词/标签 | AutoSet | 唯一集合 |
+| 人际网络 | AutoGraph | 二元关系 |
+| 项目团队 | AutoHypergraph | 多人协作 |
+| 传记时间线 | AutoTemporalGraph | 带日期事件 |
+| 旅行行程 | AutoSpatialGraph | 带连接地点 |
+| 历史事件 | AutoSpatioTemporalGraph | 需要完整上下文 |
-```python
-# 提取
-result = ka.parse(text)
+### 快速参考
-# 增量更新
-result.feed_text(more_text)
+#### 记录类型
-# 构建索引(搜索、聊天和交互式可视化都需要)
-result.build_index()
+| 自动类型 | 输出形状 | 关键特性 |
+|-----------|--------------|-------------|
+| AutoModel | 单个对象 | 固定 schema 字段 |
+| AutoList | 数组 | 保持顺序 |
+| AutoSet | 数组 | 去重 |
-# 搜索
-results = result.search("query")
+#### 图谱类型
-# 聊天
-response = result.chat("question")
+| 自动类型 | 输出形状 | 关键特性 |
+|-----------|--------------|-------------|
+| AutoGraph | 节点 + 边 | 二元关系(2个实体) |
+| AutoHypergraph | 节点 + 超边 | 多实体关系(3+个实体) |
+| AutoTemporalGraph | 节点 + 时间边 | 二元关系 + 时间维度 |
+| AutoSpatialGraph | 节点 + 地理边 | 二元关系 + 地理维度 |
+| AutoSpatioTemporalGraph | 节点 + 时空边 | 二元关系 + 时间 + 空间 |
-# 可视化(支持搜索/对话的交互式可视化)
-result.show()
+---
-# 持久化
-result.dump("./path/")
-result.load("./path/")
+## 下一步
-# 检查空
-if result.empty():
- print("No data")
+准备好使用自动类型了吗?选择你的路径:
-# 清除
-result.clear()
-result.clear_index()
-```
-
----
+**快速开始**:使用内置[模板](../templates/index.md) — 无需了解自动类型
-## 另请参见
+**更多控制**:学习如何在 Python 中使用自动类型:
+- [使用自动类型](../python/guides/working-with-autotypes.md) — 实践示例
+- [Python SDK 快速入门](../python/quickstart.md) — 5 分钟上手
-- [使用自动类型](../python/guides/working-with-autotypes.md)
-- [模板库](../templates/index.md)
-- [方法](methods.md)
+**高级用法**:创建自定义自动类型配置
+- [创建自定义模板](../python/guides/custom-templates.md)
+- [API 参考](../python/api-reference/autotypes/base.md)
diff --git a/docs/zh/concepts/index.md b/docs/zh/concepts/index.md
index 417fd6a..c5745ef 100644
--- a/docs/zh/concepts/index.md
+++ b/docs/zh/concepts/index.md
@@ -42,9 +42,8 @@ graph TD
8 种定义提取输出的数据结构类型:
-- **标量类型**:AutoModel、AutoList、AutoSet
-- **图谱类型**:AutoGraph、AutoHypergraph
-- **时序类型**:AutoTemporalGraph、AutoSpatialGraph、AutoSpatioTemporalGraph
+- **记录类型**:AutoModel、AutoList、AutoSet(存储数据,无实体关系)
+- **图谱类型**:AutoGraph、AutoHypergraph、AutoTemporalGraph、AutoSpatialGraph、AutoSpatioTemporalGraph(表示实体间关系)
→ [了解自动类型](autotypes.md)
diff --git a/docs/zh/concepts/methods.md b/docs/zh/concepts/methods.md
index 61b6ec5..b595f22 100644
--- a/docs/zh/concepts/methods.md
+++ b/docs/zh/concepts/methods.md
@@ -15,6 +15,18 @@
## 方法类别
+### 典型方法
+
+**直接提取**,无需检索。
+
+**最适合**:较小的文档、直接提取
+
+```mermaid
+graph LR
+ A[Document] --> B[LLM Processing]
+ B --> C[Extract Structure]
+```
+
### 基于 RAG 的方法
**检索增强生成** 将信息检索与文本生成相结合。
@@ -29,16 +41,90 @@ graph LR
D --> E[Extract Structure]
```
-### 典型方法
+---
-**直接提取**,无需检索。
+## 典型方法
-**最适合**:较小的文档、直接提取
+### itext2kg
-```mermaid
-graph LR
- A[Document] --> B[LLM Processing]
- B --> C[Extract Structure]
+**描述**:高质量基于三元组的提取
+
+**特点**:
+- 针对三元组质量优化
+- 迭代精炼
+- 适合知识库构建
+
+**最适合**:
+- 知识图谱构建
+- 高质量要求
+- 三元组提取
+
+**用法**:
+```python
+ka = Template.create("method/itext2kg")
+```
+
+---
+
+### itext2kg_star
+
+**描述**:增强版 iText2KG
+
+**特点**:
+- 提高提取质量
+- 更好地处理复杂情况
+- 增强的实体链接
+
+**最适合**:
+- 质量至关重要时
+- 复杂提取场景
+- 生产系统
+
+**用法**:
+```python
+ka = Template.create("method/itext2kg_star")
+```
+
+---
+
+### kg_gen
+
+**描述**:知识图谱生成器
+
+**特点**:
+- 可配置的生成
+- 灵活的 schema
+- 快速处理
+
+**最适合**:
+- 自定义 schema
+- 快速原型
+- 灵活需求
+
+**用法**:
+```python
+ka = Template.create("method/kg_gen")
+```
+
+---
+
+### atom
+
+**描述**:带证据的时序知识图谱
+
+**特点**:
+- 时序事实提取
+- 证据归属
+- 置信度评分
+
+**最适合**:
+- 时序分析
+- 事实验证
+- 时间线提取
+
+**用法**:
+```python
+ka = Template.create("method/atom")
```
---
@@ -148,92 +234,6 @@ ka = Template.create("method/cog_rag")
---
-## 典型方法
-
-### itext2kg
-
-**描述**:高质量基于三元组的提取
-
-**特点**:
-- 针对三元组质量优化
-- 迭代精炼
-- 适合知识库构建
-
-**最适合**:
-- 知识图谱构建
-- 高质量要求
-- 三元组提取
-
-**用法**:
-```python
-ka = Template.create("method/itext2kg")
-```
-
----
-
-### itext2kg_star
-
-**描述**:增强版 iText2KG
-
-**特点**:
-- 提高提取质量
-- 更好地处理复杂情况
-- 增强的实体链接
-
-**最适合**:
-- 质量至关重要时
-- 复杂提取场景
-- 生产系统
-
-**用法**:
-```python
-ka = Template.create("method/itext2kg_star")
-```
-
----
-
-### kg_gen
-
-**描述**:知识图谱生成器
-
-**特点**:
-- 可配置的生成
-- 灵活的 schema
-- 快速处理
-
-**最适合**:
-- 自定义 schema
-- 快速原型
-- 灵活需求
-
-**用法**:
-```python
-ka = Template.create("method/kg_gen")
-```
-
----
-
-### atom
-
-**描述**:带证据的时序知识图谱
-
-**特点**:
-- 时序事实提取
-- 证据归属
-- 置信度评分
-
-**最适合**:
-- 时序分析
-- 事实验证
-- 时间线提取
-
-**用法**:
-```python
-ka = Template.create("method/atom")
-```
-
----
-
## 选择指南
### 按文档大小
@@ -271,12 +271,13 @@ ka = Template.create("method/atom")
| 方法 | 速度 | 质量 | 内存 | 最佳用途 |
|--------|-------|---------|--------|----------|
+| itext2kg | ⭐⭐⭐ | ⭐⭐⭐ | ⭐ | 质量优先 |
+| itext2kg_star | ⭐⭐⭐ | ⭐⭐⭐ | ⭐ | 生产质量 |
+| kg_gen | ⭐⭐⭐ | ⭐⭐ | ⭐ | 灵活性 |
+| atom | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ | 时序数据 |
| light_rag | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ | 通用 |
| graph_rag | ⭐ | ⭐⭐⭐ | ⭐⭐⭐ | 大型文档 |
| hyper_rag | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | 复杂关系 |
-| itext2kg | ⭐⭐⭐ | ⭐⭐⭐ | ⭐ | 质量优先 |
-| atom | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ | 时序数据 |
-| kg_gen | ⭐⭐⭐ | ⭐⭐ | ⭐ | 灵活性 |
---
@@ -295,6 +296,6 @@ for name, info in methods.items():
## 另请参见
-- [选择方法指南](../python/guides/choosing-methods.md)
+- [使用方法指南](../python/guides/using-methods.md)
- [模板](../templates/index.md)
- [自动类型](autotypes.md)
diff --git a/docs/zh/getting-started/cli-quickstart.md b/docs/zh/getting-started/cli-quickstart.md
index 81033e9..2e3c356 100644
--- a/docs/zh/getting-started/cli-quickstart.md
+++ b/docs/zh/getting-started/cli-quickstart.md
@@ -79,7 +79,8 @@ Template resolved: Biography Graph Template
What's next?
he show ./output/ # 可视化知识图谱
- he search ./output/ "keyword" # 语义搜索
+ he feed ./output/ <new_document> # 追加更多文档
+ he search ./output/ "关键词" # 语义搜索
he talk ./output/ -i # 交互式对话
```
@@ -158,13 +159,13 @@ he show ./output/
```bash
# 1. 提取知识
-he parse document.md -t general/biography_graph -o ./output/ -l en
+he parse document.md -t general/biography_graph -o ./output/ -l zh
# 2. 可视化
he show ./output/
# 3. 搜索
-he search ./output/ "your query"
+he search ./output/ "你的查询"
# 4. 对话
he talk ./output/ -i
diff --git a/docs/zh/getting-started/python-quickstart.md b/docs/zh/getting-started/python-quickstart.md
index eb290ad..fcc5e3d 100644
--- a/docs/zh/getting-started/python-quickstart.md
+++ b/docs/zh/getting-started/python-quickstart.md
@@ -143,11 +143,11 @@ for edge in edges:
```python
# 保存到磁盘
-result.dump("./my_knowledge_base/")
+result.dump("./my_ka/")
# 稍后加载回来
-new_ka = Template.create("general/biography_graph", language="en")
-new_ka.load("./my_knowledge_base/")
+new_ka = Template.create("general/biography_graph", language="zh")
+new_ka.load("./my_ka/")
```
---
@@ -172,6 +172,8 @@ result.build_index()
result.show()
```
+![更新后的知识图谱可视化](../../assets/zh_show.png)
+
---
## 完整示例
@@ -232,6 +234,9 @@ if __name__ == "__main__":
main()
```
+![交互式知识图谱可视化](../../assets/zh_show.png)
+```
+
---
## 下一步
diff --git a/docs/zh/python/api-reference/autotypes.md b/docs/zh/python/api-reference/autotypes.md
deleted file mode 100644
index 418bf08..0000000
--- a/docs/zh/python/api-reference/autotypes.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# 自动类型 API
-
-## BaseAutoType
-
-::: hyperextract.types.BaseAutoType
- options:
- members:
- - parse
- - feed_text
- - search
- - chat
- - build_index
- - dump
- - load
- - show
- - empty
- - clear
- - data
- - data_schema
- - metadata
-
-## AutoModel
-
-::: hyperextract.types.AutoModel
- options:
- members: true
-
-## AutoList
-
-::: hyperextract.types.AutoList
- options:
- members: true
-
-## AutoSet
-
-::: hyperextract.types.AutoSet
- options:
- members: true
-
-## AutoGraph
-
-::: hyperextract.types.AutoGraph
- options:
- members: true
-
-## AutoHypergraph
-
-::: hyperextract.types.AutoHypergraph
- options:
- members: true
-
-## AutoTemporalGraph
-
-::: hyperextract.types.AutoTemporalGraph
- options:
- members: true
-
-## AutoSpatialGraph
-
-::: hyperextract.types.AutoSpatialGraph
- options:
- members: true
-
-## AutoSpatioTemporalGraph
-
-::: hyperextract.types.AutoSpatioTemporalGraph
- options:
- members: true
diff --git a/docs/zh/python/api-reference/autotypes/base.md b/docs/zh/python/api-reference/autotypes/base.md
new file mode 100644
index 0000000..12941ff
--- /dev/null
+++ b/docs/zh/python/api-reference/autotypes/base.md
@@ -0,0 +1,20 @@
+# 基础自动类型
+
+所有提取结果类型共享的通用接口。
+
+---
+
+::: hyperextract.types.BaseAutoType
+ options:
+ members:
+ - parse
+ - feed_text
+ - search
+ - chat
+ - build_index
+ - dump
+ - load
+ - empty
+ - clear
+ - data
+ - data_schema
diff --git a/docs/zh/python/api-reference/autotypes/graphs.md b/docs/zh/python/api-reference/autotypes/graphs.md
new file mode 100644
index 0000000..a51137e
--- /dev/null
+++ b/docs/zh/python/api-reference/autotypes/graphs.md
@@ -0,0 +1,43 @@
+# 图谱类型
+
+用于表示实体之间关系的自动类型。
+
+---
+
+## AutoGraph
+
+::: hyperextract.types.AutoGraph
+ options:
+ members: true
+
+---
+
+## AutoHypergraph
+
+::: hyperextract.types.AutoHypergraph
+ options:
+ members: true
+
+---
+
+## AutoTemporalGraph
+
+::: hyperextract.types.AutoTemporalGraph
+ options:
+ members: true
+
+---
+
+## AutoSpatialGraph
+
+::: hyperextract.types.AutoSpatialGraph
+ options:
+ members: true
+
+---
+
+## AutoSpatioTemporalGraph
+
+::: hyperextract.types.AutoSpatioTemporalGraph
+ options:
+ members: true
diff --git a/docs/zh/python/api-reference/autotypes/structures.md b/docs/zh/python/api-reference/autotypes/structures.md
new file mode 100644
index 0000000..b6a308f
--- /dev/null
+++ b/docs/zh/python/api-reference/autotypes/structures.md
@@ -0,0 +1,27 @@
+# 记录类型
+
+用于记录和存储数据,不涉及实体间关系。
+
+---
+
+## AutoModel
+
+::: hyperextract.types.AutoModel
+ options:
+ members: true
+
+---
+
+## AutoList
+
+::: hyperextract.types.AutoList
+ options:
+ members: true
+
+---
+
+## AutoSet
+
+::: hyperextract.types.AutoSet
+ options:
+ members: true
diff --git a/docs/zh/python/api-reference/methods.md b/docs/zh/python/api-reference/methods.md
deleted file mode 100644
index 28db62f..0000000
--- a/docs/zh/python/api-reference/methods.md
+++ /dev/null
@@ -1,136 +0,0 @@
-# 方法 API
-
-提取方法的 API 参考。
-
----
-
-## 注册表函数
-
-::: hyperextract.methods.registry
- options:
- members:
- - register_method
- - get_method
- - list_methods
- - get_method_cfg
- - list_method_cfgs
-
----
-
-## 方法配置
-
-::: hyperextract.methods.registry.MethodCfg
- options:
- members: true
-
----
-
-## 基于 RAG 的方法
-
-### LightRAG
-
-::: hyperextract.methods.rag.Light_RAG
- options:
- members: true
-
-### GraphRAG
-
-::: hyperextract.methods.rag.Graph_RAG
- options:
- members: true
-
-### HyperRAG
-
-::: hyperextract.methods.rag.Hyper_RAG
- options:
- members: true
-
-### HyperGraphRAG
-
-::: hyperextract.methods.rag.HyperGraph_RAG
- options:
- members: true
-
-### CogRAG
-
-::: hyperextract.methods.rag.Cog_RAG
- options:
- members: true
-
----
-
-## 典型方法
-
-### iText2KG
-
-::: hyperextract.methods.typical.iText2KG
- options:
- members: true
-
-### iText2KG_Star
-
-::: hyperextract.methods.typical.iText2KG_Star
- options:
- members: true
-
-### KG_Gen
-
-::: hyperextract.methods.typical.KG_Gen
- options:
- members: true
-
-### Atom
-
-::: hyperextract.methods.typical.Atom
- options:
- members: true
-
----
-
-## 直接使用方法
-
-```python
-from hyperextract.methods import Light_RAG
-from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-
-# 创建方法实例
-llm = ChatOpenAI()
-emb = OpenAIEmbeddings()
-
-method = Light_RAG(
- llm_client=llm,
- embedder=emb
-)
-
-# 提取知识
-result = method.parse(text)
-```
-
----
-
-## 注册自定义方法
-
-```python
-from hyperextract.methods import register_method
-
-class MyCustomMethod:
- def __init__(self, llm_client, embedder, **kwargs):
- self.llm_client = llm_client
- self.embedder = embedder
-
- def parse(self, text):
- # 您的提取逻辑
- pass
-
-# 注册方法
-register_method(
- name="my_method",
- method_class=MyCustomMethod,
- autotype="graph",
- description="我的自定义提取方法"
-)
-
-# 通过模板 API 使用
-from hyperextract import Template
-ka = Template.create("method/my_method")
-```
diff --git a/docs/zh/python/api-reference/methods/rag.md b/docs/zh/python/api-reference/methods/rag.md
new file mode 100644
index 0000000..6c7e447
--- /dev/null
+++ b/docs/zh/python/api-reference/methods/rag.md
@@ -0,0 +1,43 @@
+# 基于 RAG 的方法
+
+用于大型文档提取的检索增强生成方法。
+
+---
+
+## LightRAG
+
+::: hyperextract.methods.rag.Light_RAG
+ options:
+ members: true
+
+---
+
+## GraphRAG
+
+::: hyperextract.methods.rag.Graph_RAG
+ options:
+ members: true
+
+---
+
+## HyperRAG
+
+::: hyperextract.methods.rag.Hyper_RAG
+ options:
+ members: true
+
+---
+
+## HyperGraphRAG
+
+::: hyperextract.methods.rag.HyperGraph_RAG
+ options:
+ members: true
+
+---
+
+## CogRAG
+
+::: hyperextract.methods.rag.Cog_RAG
+ options:
+ members: true
diff --git a/docs/zh/python/api-reference/methods/registry.md b/docs/zh/python/api-reference/methods/registry.md
new file mode 100644
index 0000000..b057237
--- /dev/null
+++ b/docs/zh/python/api-reference/methods/registry.md
@@ -0,0 +1,24 @@
+# 方法注册表
+
+提取方法的注册表函数和配置。
+
+---
+
+## 注册表函数
+
+::: hyperextract.methods.registry
+ options:
+ members:
+ - register_method
+ - get_method
+ - list_methods
+ - get_method_cfg
+ - list_method_cfgs
+
+---
+
+## 方法配置
+
+::: hyperextract.methods.registry.MethodCfg
+ options:
+ members: true
diff --git a/docs/zh/python/api-reference/methods/typical.md b/docs/zh/python/api-reference/methods/typical.md
new file mode 100644
index 0000000..f5a7b05
--- /dev/null
+++ b/docs/zh/python/api-reference/methods/typical.md
@@ -0,0 +1,35 @@
+# 典型方法
+
+无需检索即可处理文本的直接提取方法。
+
+---
+
+## iText2KG
+
+::: hyperextract.methods.typical.iText2KG
+ options:
+ members: true
+
+---
+
+## iText2KG_Star
+
+::: hyperextract.methods.typical.iText2KG_Star
+ options:
+ members: true
+
+---
+
+## KG_Gen
+
+::: hyperextract.methods.typical.KG_Gen
+ options:
+ members: true
+
+---
+
+## Atom
+
+::: hyperextract.methods.typical.Atom
+ options:
+ members: true
diff --git a/docs/zh/python/api-reference/template.md b/docs/zh/python/api-reference/template.md
index 46df52c..9a0e79c 100644
--- a/docs/zh/python/api-reference/template.md
+++ b/docs/zh/python/api-reference/template.md
@@ -1,6 +1,6 @@
# 模板 API
-::: hyperextract.utils.template_engine.Template
+::: hyperextract.Template
options:
members:
- create
diff --git a/docs/zh/python/core-concepts.md b/docs/zh/python/core-concepts.md
index 7033d1a..9610369 100644
--- a/docs/zh/python/core-concepts.md
+++ b/docs/zh/python/core-concepts.md
@@ -36,10 +36,10 @@ graph TD
from hyperextract import Template
# 从预设创建
-ka = Template.create("general/biography_graph", language="en")
+ka = Template.create("general/biography_graph", language="zh")
# 从文件创建
-ka = Template.create("/path/to/custom.yaml", language="en")
+ka = Template.create("/path/to/custom.yaml", language="zh")
# 列出可用的
templates = Template.list()
@@ -85,7 +85,7 @@ for path, cfg in templates.items():
from hyperextract import Template
# 图谱提取
-ka = Template.create("general/knowledge_graph", "en")
+ka = Template.create("general/graph", "zh")
result = ka.parse(text)
# 访问图谱数据
@@ -215,7 +215,7 @@ result = ka.parse(text)
from hyperextract import Template
# 1. 选择模板
-ka = Template.create("general/biography_graph", "en")
+ka = Template.create("general/biography_graph", "zh")
# 2. 提取
result = ka.parse(text)
@@ -227,6 +227,8 @@ result.build_index()
result.show()
```
+![交互式可视化](../../assets/zh_show.png)
+
### 方法方法(高级)
```python
@@ -240,18 +242,19 @@ result = ka.parse(text)
# 3. 使用
result.build_index()
-results = result.search("query")
+results = result.search("查询")
```
-### 直接使用自动类型(完全控制)
+### 直接使用自动类型(高级)
+
+如需完全控制提取过程,可以直接实例化自动类型。这需要定义自己的 schema 和提取逻辑。
```python
from hyperextract import AutoGraph
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-
-# 1. 定义 schema
from pydantic import BaseModel
+# 定义 schema
class Entity(BaseModel):
name: str
type: str
@@ -261,29 +264,34 @@ class Relation(BaseModel):
target: str
type: str
-class MyGraph(BaseModel):
- entities: list[Entity]
- relations: list[Relation]
-
-# 2. 创建自动类型
+# 使用完整控制创建
llm = ChatOpenAI()
emb = OpenAIEmbeddings()
-ka = AutoGraph(
- data_schema=MyGraph,
+ka = AutoGraph[Entity, Relation](
+ node_schema=Entity,
+ edge_schema=Relation,
llm_client=llm,
- embedder=emb
+ embedder=emb,
+ # 还有更多配置...
)
-# 3. 提取
result = ka.parse(text)
```
+!!! note "高级主题"
+ 直接使用自动类型需要理解:
+ - Pydantic schema 定义
+ - LLM 客户端配置
+ - 用于去重的键提取器
+
+ 参见[使用自动类型](guides/working-with-autotypes.md#advanced-usage)获取完整示例。
+
---
## 下一步
- [使用模板](guides/using-templates.md)
-- [选择方法](guides/choosing-methods.md)
+- [使用方法](guides/using-methods.md)
- [使用自动类型](guides/working-with-autotypes.md)
- [自动类型参考](../concepts/autotypes.md)
diff --git a/docs/zh/python/guides/custom-templates.md b/docs/zh/python/guides/custom-templates.md
new file mode 100644
index 0000000..0f409f8
--- /dev/null
+++ b/docs/zh/python/guides/custom-templates.md
@@ -0,0 +1,416 @@
+# 创建自定义模板
+
+!!! tip "Level 2+ - 进阶拓展"
+ 本指南介绍如何创建可复用模板。在阅读前,请先完成 [Level 1: 使用模板](using-templates.md) 或 [Level 2: 使用自动类型](working-with-autotypes.md)。
+
+学习如何为专业提取任务创建自己的模板。
+
+---
+
+## 概述
+
+自定义模板允许您定义:
+
+- **输出 schema** — 要提取的实体和关系
+- **提取规则** — LLM 的指南
+- **显示配置** — 如何可视化结果
+
+---
+
+## 快速开始
+
+### 1. 创建模板文件
+
+在 `~/.hyperextract/templates/` 中创建 YAML 文件:
+
+```bash
+mkdir -p ~/.hyperextract/templates/my_domain
+```
+
+### 2. 定义模板结构
+
+```yaml
+language: [zh, en]
+
+name: my_template
+type: graph
+tags: [custom, domain]
+
+description:
+ zh: "自定义模板描述"
+ en: "Custom template description"
+
+output:
+ description:
+ zh: "输出描述"
+ en: "Output description"
+ entities:
+ description:
+ zh: "实体描述"
+ en: "Entity description"
+ fields:
+ - name: name
+ type: str
+ description:
+ zh: "名称"
+ en: "Name"
+ required: true
+ - name: category
+ type: str
+ description:
+ zh: "类别"
+ en: "Category"
+ required: true
+
+ relations:
+ description:
+ zh: "关系描述"
+ en: "Relation description"
+ fields:
+ - name: type
+ type: str
+ description:
+ zh: "关系类型"
+ en: "Relation type"
+ required: true
+
+guideline:
+ target:
+ zh: "提取目标描述"
+ en: "Extraction target description"
+ rules_for_entities:
+ zh:
+ - "规则1"
+ - "规则2"
+ en:
+ - "Rule 1"
+ - "Rule 2"
+ rules_for_relations:
+ zh:
+ - "关系规则1"
+ en:
+ - "Relation rule 1"
+
+identifiers:
+ entity_id: name
+ relation_id: "{source}|{type}|{target}"
+ relation_members:
+ source: source
+ target: target
+
+display:
+ entity_label: "{name} ({category})"
+ relation_label: "{type}"
+```
+
+### 3. 验证并使用
+
+```python
+from hyperextract import Template
+
+# 加载自定义模板
+ka = Template.create("my_domain/my_template", "zh")
+
+# 使用
+result = ka.parse("您的文档文本")
+```
+
+---
+
+## 字段类型
+
+| 类型 | 描述 | 示例 |
+|------|-------------|---------|
+| `str` | 字符串值 | `"Hello"` |
+| `int` | 整数 | `42` |
+| `float` | 浮点数 | `3.14` |
+| `bool` | 布尔值 | `true` |
+| `list[str]` | 字符串列表 | `["a", "b"]` |
+| `datetime` | 日期/时间 | `"2024-01-01"` |
+| `enum` | 枚举值 | 见下文 |
+
+### 枚举类型
+
+用于预定义值的字段:
+
+```yaml
+- name: priority
+ type: str
+ description:
+ zh: "优先级: high/medium/low"
+ en: "Priority: high/medium/low"
+ required: true
+```
+
+---
+
+## 自动类型
+
+为您的数据选择合适的自动类型:
+
+| 类型 | 用例 | 特性 |
+|------|----------|----------|
+| `graph` | 通用知识图谱 | 实体 + 关系 |
+| `temporal_graph` | 时序数据 | + 时间事件 |
+| `spatial_graph` | 地理空间数据 | + 位置坐标 |
+| `hypergraph` | 复杂关系 | + 超边 |
+| `tree` | 层次数据 | 父子结构 |
+| `table` | 结构化记录 | 基于行的数据 |
+
+---
+
+## 最佳实践
+
+### 1. 清晰的描述
+
+编写详细描述以指导 LLM:
+
+```yaml
+# 好
+description:
+ zh: "提取产品信息,包括名称、价格和类别"
+
+# 不好
+description:
+ zh: "产品信息"
+```
+
+### 2. 具体的规则
+
+提供具体的提取规则:
+
+```yaml
+guideline:
+ rules_for_entities:
+ zh:
+ - "仅提取定价部分中提到的产品"
+ - "类别必须是以下之一:电子产品、服装、食品、其他"
+ - "价格四舍五入到 2 位小数"
+```
+
+### 3. 必填字段
+
+将关键字段标记为必填:
+
+```yaml
+fields:
+ - name: id
+ type: str
+ required: true # 如果缺失,提取将失败
+ - name: notes
+ type: str
+ required: false # 可选字段
+```
+
+### 4. 验证
+
+使用样本文档测试模板:
+
+```python
+# 测试提取
+test_doc = """
+样本文档文本用于测试...
+"""
+
+result = ka.parse(test_doc)
+print(result.data.entities)
+print(result.data.relations)
+```
+
+---
+
+## 示例:产品目录模板
+
+```yaml
+language: [zh, en]
+
+name: product_catalog
+type: table
+tags: [ecommerce, products]
+
+description:
+ zh: "从商品目录中提取产品信息"
+ en: "Extract product information from catalogs"
+
+output:
+ description:
+ zh: "产品信息表"
+ en: "Product information table"
+ entities:
+ description:
+ zh: "产品实体"
+ en: "Product entities"
+ fields:
+ - name: sku
+ type: str
+ description:
+ zh: "产品SKU(唯一标识)"
+ en: "Product SKU (unique identifier)"
+ required: true
+ - name: name
+ type: str
+ description:
+ zh: "产品名称"
+ en: "Product name"
+ required: true
+ - name: price
+ type: float
+ description:
+ zh: "价格(数字)"
+ en: "Price (numeric value)"
+ required: true
+ - name: category
+ type: str
+ description:
+ zh: "类别:electronics/clothing/food/home/other"
+ en: "Category: electronics/clothing/food/home/other"
+ required: true
+ - name: in_stock
+ type: bool
+ description:
+ zh: "是否有库存"
+ en: "Whether in stock"
+ required: false
+
+guideline:
+ target:
+ zh: "提取所有产品信息,忽略缺货商品"
+ en: "Extract all product info, skip out-of-stock items"
+ rules_for_entities:
+ zh:
+ - "从表格和项目列表中提取产品"
+ - "将价格字符串转换为数值"
+ - "将类别名称映射到标准值"
+ - "如果明确提到缺货,则设置 in_stock=false"
+
+identifiers:
+ entity_id: sku
+
+display:
+ entity_label: "{name} (¥{price})"
+```
+
+---
+
+## 直接使用方法类
+
+如果你需要完全控制提取过程,可以直接使用方法类,而不通过 `Template.create`:
+
+```python
+from hyperextract.methods import Light_RAG
+from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+
+# 直接创建方法实例
+llm = ChatOpenAI()
+emb = OpenAIEmbeddings()
+
+method = Light_RAG(
+ llm_client=llm,
+ embedder=emb,
+ # 方法特定参数
+ chunk_size=1024,
+ max_workers=5
+)
+
+# 提取知识
+result = method.parse(text)
+```
+
+这种方式适合需要绕过模板层、直接调优算法参数的进阶场景。
+
+---
+
+## 注册自定义方法
+
+您还可以注册自定义提取方法,并通过 Template API 使用它们:
+
+```python
+from hyperextract.methods import register_method
+
+class MyCustomMethod:
+ def __init__(self, llm_client, embedder, **kwargs):
+ self.llm_client = llm_client
+ self.embedder = embedder
+
+ def parse(self, text):
+ # 您的提取逻辑
+ pass
+
+# 注册方法
+register_method(
+ name="my_method",
+ method_class=MyCustomMethod,
+ autotype="graph",
+ description="我的自定义提取方法"
+)
+
+# 通过 Template API 使用
+from hyperextract import Template
+ka = Template.create("method/my_method")
+```
+
+---
+
+## 分享模板
+
+### 全局注册
+
+将模板放在系统目录中:
+
+```bash
+# 系统范围(所有用户)
+/usr/share/hyperextract/templates/
+
+# 用户特定
+~/.hyperextract/templates/
+```
+
+### 模板仓库
+
+与社区分享:
+
+1. Fork [Hyper-Extract 仓库](https://github.com/yifanfeng97/hyper-extract)
+2. 添加模板到 `hyperextract/templates/`
+3. 提交 pull request
+
+---
+
+## 故障排除
+
+### 模板未找到
+
+```python
+# 检查模板路径
+Template.list() # 列出所有模板
+
+# 验证目录
+import os
+print(os.listdir("~/.hyperextract/templates/"))
+```
+
+### 提取质量不佳
+
+1. **添加更多示例** 在指南中
+2. **优化字段描述** 使用具体约束
+3. **拆分复杂模板** 为更小的模板
+4. **使用更严格的规则** 约束输出
+
+### 验证错误
+
+```bash
+# 验证 YAML 语法
+python -c "import yaml; yaml.safe_load(open('template.yaml'))"
+```
+
+---
+
+## 另请参见
+
+**前置知识:**
+- [模板格式参考](../../concepts/templates-format.md) — 完整 YAML 规范
+- [使用模板](using-templates.md) — Level 1: 模板基础用法
+
+**进阶使用:**
+- [增量更新](incremental-updates.md) — 添加更多文档
+- [搜索和聊天](search-and-chat.md) — 使用提取的知识
+- [模板库](../../templates/index.md) — 浏览现有模板
diff --git a/docs/zh/python/guides/incremental-updates.md b/docs/zh/python/guides/incremental-updates.md
index 8b4eed8..7a12b54 100644
--- a/docs/zh/python/guides/incremental-updates.md
+++ b/docs/zh/python/guides/incremental-updates.md
@@ -1,5 +1,8 @@
# 增量更新
+!!! tip "进阶 - 提取后操作"
+ 本指南涵盖初始提取后添加更多文档。您应该先熟悉 [Level 1: 使用模板](using-templates.md)。
+
在不重新处理的情况下向现有知识库添加新信息。
---
@@ -38,43 +41,45 @@ print(f"Feed 后: {len(result.nodes)} 个节点")
```python
ka = Template.create("general/biography_graph", "zh")
-kb = ka.parse(early_life_text)
+ka = ka.parse(early_life_text)
# 添加职业信息
-kb.feed_text(career_text)
+ka.feed_text(career_text)
# 添加晚年
-kb.feed_text(later_years_text)
+ka.feed_text(later_years_text)
# 在 feed 新数据后重建索引
-kb.build_index()
+ka.build_index()
# 最终结果组合所有时期(支持交互式搜索/对话)
-kb.show()
+ka.show()
```
+![交互式可视化](../../../assets/zh_show.png)
+
### 处理多个文档
```python
-ka = Template.create("general/concept_graph", "en")
-kb = ka.parse(documents[0])
+ka = Template.create("general/concept_graph", "zh")
+ka = ka.parse(documents[0])
for doc in documents[1:]:
- kb.feed_text(doc)
- print(f"已添加文档,现在有 {len(kb.nodes)} 个节点")
+ ka.feed_text(doc)
+ print(f"已添加文档,现在有 {len(ka.nodes)} 个节点")
```
### 使用新信息更新
```python
# 原始提取
-kb = ka.parse(original_paper)
+ka = ka.parse(original_paper)
# 添加更正/更新
-kb.feed_text(corrections)
+ka.feed_text(corrections)
# 保存更新版本
-kb.dump("./updated_kb/")
+ka.dump("./updated_ka/")
```
---
@@ -112,8 +117,8 @@ kb.dump("./updated_kb/")
```python
# 好:相同模板类型
-kb = ka.parse(text1) # biography_graph
-kb.feed_text(text2) # 相同类型
+ka = ka.parse(text1) # biography_graph
+ka.feed_text(text2) # 相同类型
# 注意:混合类型可能导致问题
```
@@ -121,27 +126,27 @@ kb.feed_text(text2) # 相同类型
### 2. Feed 后重建索引
```python
-kb.feed_text(new_text)
-kb.build_index() # 搜索/聊天需要
+ka.feed_text(new_text)
+ka.build_index() # 搜索/聊天需要
```
### 3. 保存中间状态
```python
# 重大更新后保存
-kb.feed_text(chapter1)
-kb.dump("./kb_v1/")
+ka.feed_text(chapter1)
+ka.dump("./kb_v1/")
-kb.feed_text(chapter2)
-kb.dump("./kb_v2/")
+ka.feed_text(chapter2)
+ka.dump("./kb_v2/")
```
### 4. 监控增长
```python
-initial_count = len(kb.nodes)
-kb.feed_text(new_text)
-new_count = len(kb.nodes)
+initial_count = len(ka.nodes)
+ka.feed_text(new_text)
+new_count = len(ka.nodes)
print(f"添加了 {new_count - initial_count} 个新节点")
```
@@ -156,7 +161,7 @@ print(f"添加了 {new_count - initial_count} 个新节点")
from hyperextract import Template
from pathlib import Path
-def build_knowledge_base(source_dir, output_dir):
+def build_ka(source_dir, output_dir):
ka = Template.create("general/biography_graph", "zh")
# 获取所有文本文件
@@ -168,27 +173,27 @@ def build_knowledge_base(source_dir, output_dir):
# 从第一个文件初始提取
print(f"处理 {files[0].name}...")
- kb = ka.parse(files[0].read_text())
+ ka = ka.parse(files[0].read_text())
# Feed 剩余文件
for file in files[1:]:
print(f"添加 {file.name}...")
- kb.feed_text(file.read_text())
- print(f" 现在有 {len(kb.nodes)} 个节点")
+ ka.feed_text(file.read_text())
+ print(f" 现在有 {len(ka.nodes)} 个节点")
# 为搜索/聊天构建索引
print("构建搜索索引...")
- kb.build_index()
+ ka.build_index()
# 保存
print(f"保存到 {output_dir}...")
- kb.dump(output_dir)
+ ka.dump(output_dir)
print("完成!")
- return kb
+ return ka
# 用法
-kb = build_knowledge_base("./sources/", "./combined_kb/")
+ka = build_ka("./sources/", "./combined_ka/")
```
---
@@ -222,7 +227,7 @@ result1.feed_text(text2) # result1 被更新
```python
# 监控大小
import sys
-size = sys.getsizeof(kb.data)
+size = sys.getsizeof(ka.data)
print(f"知识库大小: {size} 字节")
```
@@ -237,8 +242,8 @@ print(f"知识库大小: {size} 字节")
Feed 后始终重建:
```python
-kb.feed_text(text)
-kb.build_index() # 不要忘记!
+ka.feed_text(text)
+ka.build_index() # 不要忘记!
```
---
@@ -252,8 +257,8 @@ kb.build_index() # 不要忘记!
```python
for batch in chunks(documents, batch_size=5):
for doc in batch:
- kb.feed_text(doc)
- kb.dump(f"./kb_checkpoint/") # 定期保存
+ ka.feed_text(doc)
+ ka.dump(f"./kb_checkpoint/") # 定期保存
```
### "重复实体"
@@ -269,13 +274,17 @@ for batch in chunks(documents, batch_size=5):
```python
# 忘记重建了?
-kb.build_index()
+ka.build_index()
```
---
## 另请参见
-- [保存和加载](saving-loading.md)
-- [搜索和聊天](search-and-chat.md)
-- [使用自动类型](working-with-autotypes.md)
+**相关工作流:**
+- [搜索和聊天](search-and-chat.md) — 查询更新后的知识
+- [保存和加载](saving-loading.md) — 持久化合并结果
+
+**基础知识:**
+- [使用模板](using-templates.md) — Level 1 基础
+- [使用自动类型](working-with-autotypes.md) — Level 2 自定义
diff --git a/docs/zh/python/guides/saving-loading.md b/docs/zh/python/guides/saving-loading.md
index 061c9f7..5329f88 100644
--- a/docs/zh/python/guides/saving-loading.md
+++ b/docs/zh/python/guides/saving-loading.md
@@ -24,13 +24,13 @@ ka = Template.create("general/biography_graph", "zh")
result = ka.parse(text)
# 保存到目录
-result.dump("./my_kb/")
+result.dump("./my_ka/")
```
### 保存结构
```
-./my_kb/
+./my_ka/
├── data.json # 提取的知识
├── metadata.json # 提取信息
└── index/ # 搜索索引(如已构建)
@@ -45,7 +45,7 @@ result.dump("./my_kb/")
result.build_index()
# 然后保存
-result.dump("./my_kb/")
+result.dump("./my_ka/")
```
---
@@ -61,7 +61,7 @@ from hyperextract import Template
ka = Template.create("general/biography_graph", "zh")
# 加载保存的数据
-ka.load("./my_kb/")
+ka.load("./my_ka/")
# 使用
print(f"加载了 {len(ka.nodes)} 个节点")
@@ -70,7 +70,7 @@ print(f"加载了 {len(ka.nodes)} 个节点")
### 验证加载的数据
```python
-ka.load("./my_kb/")
+ka.load("./my_ka/")
# 检查是否为空
if ka.empty():
@@ -88,13 +88,13 @@ else:
```python
# 提取并保存
-ka = Template.create("general/concept_graph", "en")
+ka = Template.create("general/concept_graph", "zh")
result = ka.parse(research_paper)
result.build_index()
result.dump("./research_paper_kb/")
# 数周后使用
-ka2 = Template.create("general/concept_graph", "en")
+ka2 = Template.create("general/concept_graph", "zh")
ka2.load("./research_paper_kb/")
response = ka2.chat("主要发现是什么?")
```
@@ -103,10 +103,10 @@ response = ka2.chat("主要发现是什么?")
```python
# 保存到共享位置
-result.dump("/shared/kb/project_x/")
+result.dump("/shared/ka/project_x/")
# 其他人可以加载
-ka.load("/shared/kb/project_x/")
+ka.load("/shared/ka/project_x/")
```
### 备份和版本控制
@@ -128,23 +128,23 @@ result.dump("./kb_v2/")
## 使用文件系统
-### 检查现有 KB
+### 检查现有 KA
```python
from pathlib import Path
-kb_path = Path("./my_kb/")
+ka_path = Path("./my_ka/")
-if kb_path.exists() and (kb_path / "data.json").exists():
+if ka_path.exists() and (ka_path / "data.json").exists():
print("知识库存在,正在加载...")
- ka.load(kb_path)
+ ka.load(ka_path)
else:
print("创建新知识库...")
result = ka.parse(text)
- result.dump(kb_path)
+ result.dump(ka_path)
```
-### 列出保存的 KB
+### 列出保存的 KA
```python
import os
@@ -172,7 +172,7 @@ shutil.move("./old_location/", "./new_location/")
### 访问元数据
```python
-result.dump("./my_kb/")
+result.dump("./my_ka/")
# 元数据自动保存
# 内容:
@@ -189,7 +189,7 @@ result.dump("./my_kb/")
result.metadata["project"] = "研究项目 X"
result.metadata["version"] = "1.0"
-result.dump("./my_kb/")
+result.dump("./my_ka/")
```
---
@@ -208,22 +208,22 @@ class KnowledgeBaseManager:
self.storage_dir = Path(storage_dir)
self.storage_dir.mkdir(exist_ok=True)
- def save(self, kb, name):
+ def save(self, ka, name):
"""保存知识库。"""
- kb_path = self.storage_dir / name
- kb.dump(kb_path)
- print(f"保存到 {kb_path}")
- return kb_path
+ ka_path = self.storage_dir / name
+ ka.dump(ka_path)
+ print(f"保存到 {ka_path}")
+ return ka_path
- def load(self, name, template="general/biography_graph", lang="en"):
+ def load(self, name, template="general/biography_graph", lang="zh"):
"""加载知识库。"""
- kb_path = self.storage_dir / name
+ ka_path = self.storage_dir / name
- if not kb_path.exists():
+ if not ka_path.exists():
raise FileNotFoundError(f"未找到知识库: {name}")
ka = Template.create(template, lang)
- ka.load(kb_path)
+ ka.load(ka_path)
return ka
def list(self):
@@ -232,8 +232,8 @@ class KnowledgeBaseManager:
def info(self, name):
"""获取知识库信息。"""
- kb_path = self.storage_dir / name
- meta_path = kb_path / "metadata.json"
+ ka_path = self.storage_dir / name
+ meta_path = ka_path / "metadata.json"
if meta_path.exists():
return json.loads(meta_path.read_text())
@@ -251,8 +251,8 @@ manager.save(result, "苏轼传记")
print(manager.list()) # ['苏轼传记']
# 加载
-kb = manager.load("苏轼传记")
-print(kb.chat("苏轼创作了哪些代表作?"))
+ka = manager.load("苏轼传记")
+print(ka.chat("苏轼创作了哪些代表作?"))
```
---
@@ -266,17 +266,17 @@ print(kb.chat("苏轼创作了哪些代表作?"))
ka = Template.create("general/biography_graph", "zh")
# 使用相同模板加载
-ka2 = Template.create("general/biography_graph", "en")
-ka2.load("./kb/")
+ka2 = Template.create("general/biography_graph", "zh")
+ka2.load("./ka/")
```
### 2. 加载后构建索引
```python
-ka.load("./kb/")
+ka.load("./ka/")
# 索引可能需要重建
-index_path = Path("./kb/") / "index"
+index_path = Path("./ka/") / "index"
if not index_path.exists():
ka.build_index()
```
@@ -285,7 +285,7 @@ if not index_path.exists():
```python
try:
- ka.load("./kb/")
+ ka.load("./ka/")
if ka.empty():
print("警告:空知识库")
except FileNotFoundError:
@@ -296,10 +296,10 @@ except FileNotFoundError:
```python
# 好
-result.dump("./kb/sushi_2024_01_15/")
+result.dump("./ka/sushi_2024_01_15/")
# 避免
-result.dump("./kb/temp/")
+result.dump("./ka/temp/")
```
---
@@ -311,9 +311,9 @@ result.dump("./kb/temp/")
```python
from pathlib import Path
-kb_path = Path("./my_kb/")
-if not kb_path.exists():
- print(f"未找到目录: {kb_path}")
+ka_path = Path("./my_ka/")
+if not ka_path.exists():
+ print(f"未找到目录: {ka_path}")
print(f"可用: {list(Path('.').glob('*/'))}")
```
@@ -322,17 +322,17 @@ if not kb_path.exists():
```python
# 检查数据文件
import json
-data = json.load(open("./my_kb/data.json"))
+data = json.load(open("./my_ka/data.json"))
print(f"Keys: {data.keys()}")
```
### "索引未加载"
```python
-ka.load("./kb/")
+ka.load("./ka/")
# 检查索引是否存在
-if (Path("./kb/") / "index").exists():
+if (Path("./ka/") / "index").exists():
print("索引目录存在")
else:
print("无索引,正在构建...")
@@ -343,6 +343,10 @@ else:
## 另请参见
-- [增量更新](incremental-updates.md)
-- [搜索和聊天](search-and-chat.md)
-- [CLI `he parse` 命令](../../cli/commands/parse.md)
+**相关工作流:**
+- [增量更新](incremental-updates.md) — 添加更多内容
+- [搜索和聊天](search-and-chat.md) — 使用加载的知识
+
+**基础知识:**
+- [使用模板](using-templates.md) — Level 1 基础
+- [CLI `he parse` 命令](../../cli/commands/parse.md) — 命令行提取
diff --git a/docs/zh/python/guides/search-and-chat.md b/docs/zh/python/guides/search-and-chat.md
index 62d96c2..9000310 100644
--- a/docs/zh/python/guides/search-and-chat.md
+++ b/docs/zh/python/guides/search-and-chat.md
@@ -1,5 +1,8 @@
# 搜索和聊天
+!!! tip "进阶 - 提取后操作"
+ 本指南涵盖使用提取后的知识。您应该先熟悉 [Level 1: 使用模板](using-templates.md)。
+
使用语义搜索和对话 AI 查询您的知识库。
---
@@ -57,7 +60,7 @@ nodes, edges = result.search(
### 处理结果
```python
-nodes, edges = result.search("Nobel Prize")
+nodes, edges = result.search("代表作")
# 处理节点
for node in nodes:
@@ -195,9 +198,9 @@ print(response.content)
```python
class ResearchAssistant:
- def __init__(self, kb_path):
+ def __init__(self, ka_path):
self.ka = Template.create("general/concept_graph", "zh")
- self.ka.load(kb_path)
+ self.ka.load(ka_path)
self.ka.build_index()
def ask(self, question):
@@ -249,9 +252,9 @@ result.build_index()
```python
# 尝试不同的措辞
-results = result.search("inventions") # 尝试同义词
-results = result.search("discoveries")
-results = result.search("contributions")
+results = result.search("发明") # 尝试同义词
+results = result.search("发现")
+results = result.search("贡献")
# 增加 top_k
results = result.search("苏轼", top_k=20)
@@ -271,6 +274,10 @@ response = result.chat("请更具体地说明:...")
## 另请参见
-- [使用自动类型](working-with-autotypes.md)
-- [增量更新](incremental-updates.md)
-- [保存和加载](saving-loading.md)
+**相关工作流:**
+- [增量更新](incremental-updates.md) — 添加更多内容
+- [保存和加载](saving-loading.md) — 持久化以供后续使用
+
+**基础知识:**
+- [使用模板](using-templates.md) — Level 1 基础
+- [使用自动类型](working-with-autotypes.md) — Level 2 自定义
diff --git a/docs/zh/python/guides/choosing-methods.md b/docs/zh/python/guides/using-methods.md
similarity index 64%
rename from docs/zh/python/guides/choosing-methods.md
rename to docs/zh/python/guides/using-methods.md
index a69c4de..50e030d 100644
--- a/docs/zh/python/guides/choosing-methods.md
+++ b/docs/zh/python/guides/using-methods.md
@@ -1,28 +1,31 @@
-# 选择方法
+# 使用方法
-了解提取方法以及何时使用每种方法。
+!!! tip "Level 1 入门"
+ 本指南适合初学者。阅读本指南前,请先完成 [快速入门](../quickstart.md) 和 [使用模板](using-templates.md)。
+
+了解 Hyper-Extract 的提取方法,以及如何在 `Template.create` 中快速切换不同算法。
---
## 什么是方法?
-方法是驱动知识提取的底层算法。模板提供易于使用、特定领域的配置,而方法让您直接访问提取算法。
+**方法(Method)** 是驱动知识提取的底层算法。在 Hyper-Extract 中,方法和模板一样,都可以通过 `Template.create` 直接调用:
----
+```python
+# 使用模板
+ka = Template.create("general/biography_graph", language="zh")
-## 方法类别
+# 使用方法
+ka = Template.create("method/light_rag")
+```
-### 基于 RAG 的方法
+区别在于:
+- **模板** = 预配置好的领域方案(结构 + 提示 + 语言)
+- **方法** = 纯提取算法,更轻量,适合需要切换不同算法的场景
-**检索增强生成**方法通过结合检索与生成,在处理大型文档方面表现出色。
+---
-| 方法 | 最佳用途 | 关键特性 |
-|--------|----------|-------------|
-| `light_rag` | 通用用途 | 快速、轻量 |
-| `graph_rag` | 大型文档 | 社区检测 |
-| `hyper_rag` | 复杂关系 | N 元超边 |
-| `hypergraph_rag` | 高级场景 | 增强超图谱 |
-| `cog_rag` | 推理任务 | 认知检索 |
+## 方法类别
### 典型方法
@@ -35,19 +38,29 @@
| `kg_gen` | 灵活性 | 可配置生成 |
| `atom` | 时序数据 | 证据归属 |
+### 基于 RAG 的方法
+
+**检索增强生成**方法通过结合检索与生成,在处理大型文档方面表现出色。
+
+| 方法 | 最佳用途 | 关键特性 |
+|--------|----------|-------------|
+| `light_rag` | 通用用途 | 快速、轻量 |
+| `graph_rag` | 大型文档 | 社区检测 |
+| `hyper_rag` | 复杂关系 | N 元超边 |
+| `hypergraph_rag` | 高级场景 | 增强超图谱 |
+| `cog_rag` | 推理任务 | 认知检索 |
+
---
-## 使用方法
+## 基本用法
-### 基本用法
+### 默认配置
```python
from hyperextract import Template
-# 从方法创建
+# 创建并提取
ka = Template.create("method/light_rag")
-
-# 提取
result = ka.parse(text)
```
@@ -75,21 +88,21 @@ ka = Template.create(
```mermaid
graph TD
- A[Select Method] --> B{Document size?}
- B -->|Large| C[RAG-Based]
- B -->|Small/Medium| D{Need evidence?}
- D -->|Yes| E[atom]
- D -->|No| F{Prioritize quality?}
- F -->|Yes| G[iText2KG]
- F -->|No| H[kg_gen]
-
- C --> I{Relationship complexity?}
- I -->|Simple| J[light_rag]
- I -->|Standard| K[graph_rag]
- I -->|Complex| L[hyper_rag]
+ A[选择方法] --> B{文档大小?}
+ B -->|大文档| C[基于 RAG]
+ B -->|小/中文档| D{需要证据?}
+ D -->|是| E[atom]
+ D -->|否| F{注重质量?}
+ F -->|是| G[iText2KG]
+ F -->|否| H[kg_gen]
+
+ C --> I{关系复杂度?}
+ I -->|简单| J[light_rag]
+ I -->|标准| K[graph_rag]
+ I -->|复杂| L[hyper_rag]
```
-### 按用例
+### 按用例推荐
#### 快速提取(小文档)
@@ -122,7 +135,7 @@ ka = Template.create("method/hyper_rag")
#### 时序分析
```python
-# 带证据的基于时间的方法
+# 带证据的时序方法
ka = Template.create("method/atom")
```
@@ -141,7 +154,59 @@ ka = Template.create("method/atom")
---
-## 方法详情
+## 方法速查
+
+### itext2kg
+
+最佳用途:高质量三元组提取
+
+```python
+ka = Template.create("method/itext2kg")
+
+# 特点:
+# - 针对三元组质量优化
+# - 迭代精炼
+# - 适合知识库构建
+```
+
+### itext2kg_star
+
+最佳用途:增强质量提取
+
+```python
+ka = Template.create("method/itext2kg_star")
+
+# 特点:
+# - 提高提取质量
+# - 更好地处理复杂情况
+# - 增强的实体链接
+```
+
+### kg_gen
+
+最佳用途:灵活、可配置提取
+
+```python
+ka = Template.create("method/kg_gen")
+
+# 特点:
+# - 可配置的生成
+# - 灵活的 schema
+# - 快速处理
+```
+
+### atom
+
+最佳用途:带证据的时序分析
+
+```python
+ka = Template.create("method/atom")
+
+# 特点:
+# - 时序事实提取
+# - 证据归属
+# - 置信度评分
+```
### light_rag
@@ -182,35 +247,9 @@ ka = Template.create("method/hyper_rag")
# - 更丰富的图谱结构
```
-### itext2kg
-
-最佳用途:高质量三元组提取
-
-```python
-ka = Template.create("method/itext2kg")
-
-# 特点:
-# - 针对三元组质量优化
-# - 迭代精炼
-# - 适合知识库构建
-```
-
-### atom
-
-最佳用途:带证据的时序分析
-
-```python
-ka = Template.create("method/atom")
-
-# 特点:
-# - 时序事实提取
-# - 证据归属
-# - 置信度评分
-```
-
---
-## 列出方法
+## 列出可用方法
```python
from hyperextract import Template
@@ -220,33 +259,7 @@ from hyperextract.methods import list_methods
methods = list_methods()
for name, info in methods.items():
print(f"{name}: {info['description']}")
- print(f" Type: {info['type']}")
-```
-
----
-
-## 方法配置
-
-方法可以通过参数配置:
-
-```python
-from hyperextract import Template
-
-# 大多数方法使用默认配置
-# 高级用户可以直接创建方法实例
-from hyperextract.methods import Light_RAG
-from langchain_openai import ChatOpenAI, OpenAIEmbeddings
-
-llm = ChatOpenAI()
-emb = OpenAIEmbeddings()
-
-ka = Light_RAG(
- llm_client=llm,
- embedder=emb,
- # 方法特定参数
- chunk_size=1024,
- max_workers=5
-)
+ print(f" 类型: {info['type']}")
```
---
@@ -261,22 +274,15 @@ ka = Light_RAG(
---
-## 何时使用模板 vs 方法
-
-| 场景 | 建议 |
-|----------|----------------|
-| 快速开始 | 模板 |
-| 特定领域任务 | 模板 |
-| 生产系统 | 模板 |
-| 研究/实验 | 方法 |
-| 自定义需求 | 方法 |
-| 性能优化 | 方法 |
-| 完全控制 | 方法 |
+## 另请参见
----
+**前置知识:**
+- [使用模板](using-templates.md) — Level 1: 开箱即用的领域方案
-## 另请参见
+**下一步:**
+- [使用自动类型](working-with-autotypes.md) — Level 2: 自定义 schema 和提取配置
+- [创建自定义模板](custom-templates.md) — 将你的自定义配置打包成可复用模板
-- [使用模板](using-templates.md)
-- [模板库](../../templates/index.md)
-- [方法概念文档](../../concepts/methods.md)
+**参考:**
+- [方法概念文档](../../concepts/methods.md) — 详细算法解释
+- [模板库](../../templates/index.md) — 浏览现有模板
diff --git a/docs/zh/python/guides/using-templates.md b/docs/zh/python/guides/using-templates.md
index e847c1d..0113c68 100644
--- a/docs/zh/python/guides/using-templates.md
+++ b/docs/zh/python/guides/using-templates.md
@@ -1,5 +1,8 @@
# 使用模板
+!!! tip "Level 1 入门"
+ 本指南适合初学者。阅读本指南前,请先完成 [快速入门](../quickstart.md)。
+
学习如何使用和自定义模板进行知识提取。
---
@@ -7,6 +10,7 @@
## 什么是模板?
模板是预配置的提取设置,组合了:
+
- **自动类型** — 输出数据结构
- **提示** — LLM 指令
- **Schema** — 字段定义和类型
@@ -37,7 +41,7 @@ Hyper-Extract 包含 80+ 个跨 6 个领域的模板:
from hyperextract import Template
# 基本用法
-ka = Template.create("general/biography_graph", language="en")
+ka = Template.create("general/biography_graph", language="zh")
# 使用自定义客户端
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
@@ -47,7 +51,7 @@ emb = OpenAIEmbeddings()
ka = Template.create(
"general/biography_graph",
- language="en",
+ language="zh",
llm_client=llm,
embedder=emb
)
@@ -59,7 +63,7 @@ ka = Template.create(
# 加载自定义 YAML 模板
ka = Template.create(
"/path/to/my_template.yaml",
- language="en"
+ language="zh"
)
```
@@ -100,7 +104,7 @@ zh_templates = Template.list(filter_by_language="zh")
# 组合
results = Template.list(
filter_by_type="graph",
- filter_by_language="en"
+ filter_by_language="zh"
)
```
@@ -143,6 +147,72 @@ print(cfg.language) # 支持的语言
---
+## 理解模板返回值
+
+`Template.create` 返回的是**自动类型(AutoType)**对象。不同模板对应的 AutoType 不同,访问提取结果的方式也不同:
+
+| 类型 | AutoType | 典型访问方式 | 适用场景 |
+|------|----------|--------------|----------|
+| **模型** | `AutoModel` | `result.data.field_name` | 财报、档案等结构化对象 |
+| **列表** | `AutoList` | `result.data.items` | 有序集合、流程步骤 |
+| **集合** | `AutoSet` | `result.data.items` | 去重标签、关键词 |
+| **图谱** | `AutoGraph` | `result.nodes` / `result.edges` | 二元实体关系 |
+| **超图** | `AutoHypergraph` | `result.nodes` / `result.edges` | 多实体关系 |
+| **时序图** | `AutoTemporalGraph` | `result.nodes` / `result.edges`(边含 `time`) | 时间线、传记 |
+| **空间图** | `AutoSpatialGraph` | `result.nodes` / `result.edges`(含 `location`) | 地理网络 |
+| **时空图** | `AutoSpatioTemporalGraph` | `result.nodes` / `result.edges`(含 `time` + `location`) | 历史事件 |
+
+!!! info "相关文档"
+ - 想了解更多每种 AutoType 的设计理念和适用场景?参见 [自动类型概念](../../concepts/autotypes.md)。
+ - 想学习如何自定义 schema 和配置参数?参见 [使用自动类型](working-with-autotypes.md)。
+
+### 快速示例
+
+#### 模型(AutoModel)
+
+```python
+ka = Template.create("finance/earnings_summary", "zh")
+result = ka.parse(report_text)
+
+print(result.data.company_name)
+print(result.data.revenue)
+```
+
+#### 列表(AutoList)
+
+```python
+ka = Template.create("general/list", "zh")
+result = ka.parse(text)
+
+for item in result.data.items:
+ print(item)
+```
+
+#### 集合(AutoSet)
+
+```python
+ka = Template.create("general/set", "zh")
+result = ka.parse(text)
+
+for item in result.data.items:
+ print(item) # 自动去重
+```
+
+#### 图谱(AutoGraph)
+
+```python
+ka = Template.create("general/graph", "zh")
+result = ka.parse(text)
+
+for node in result.nodes:
+ print(f"{node.name} ({node.type})")
+
+for edge in result.edges:
+ print(f"{edge.source} --{edge.type}--> {edge.target}")
+```
+
+---
+
## 常见模板模式
### 模式 1:传记分析
@@ -150,7 +220,7 @@ print(cfg.language) # 支持的语言
```python
from hyperextract import Template
-ka = Template.create("general/biography_graph", "en")
+ka = Template.create("general/biography_graph", "zh")
with open("biography.md") as f:
result = ka.parse(f.read())
@@ -166,12 +236,14 @@ result.build_index()
result.show() # 可视化生平时间线(支持搜索/对话功能)
```
+![交互式可视化](../../../assets/zh_show.png)
+
### 模式 2:财务报告
```python
from hyperextract import Template
-ka = Template.create("finance/earnings_summary", "en")
+ka = Template.create("finance/earnings_summary", "zh")
report = ka.parse(earnings_text)
@@ -186,7 +258,7 @@ print(f"同比增长: {report.data.yoy_growth}%")
```python
from hyperextract import Template
-ka = Template.create("legal/contract_obligation", "en")
+ka = Template.create("legal/contract_obligation", "zh")
contract = ka.parse(contract_text)
@@ -202,7 +274,7 @@ for obligation in contract.data.obligations:
```python
from hyperextract import Template
-ka = Template.create("general/concept_graph", "en")
+ka = Template.create("general/concept_graph", "zh")
paper = ka.parse(paper_text)
@@ -240,10 +312,10 @@ result_zh = ka_zh.parse(chinese_text)
```python
# 首次调用加载模板
-ka1 = Template.create("general/biography_graph", "en")
+ka1 = Template.create("general/biography_graph", "zh")
# 第二次调用使用缓存版本
-ka2 = Template.create("general/biography_graph", "en")
+ka2 = Template.create("general/biography_graph", "zh")
# 两者是具有相同配置但独立的实例
```
@@ -290,6 +362,10 @@ ka = Template.create("general/biography_graph", "fr") # 可能失败
## 另请参见
+**下一步:**
+- [使用自动类型](working-with-autotypes.md) — Level 2: 自定义 schema
+- [创建自定义模板](custom-templates.md) — Level 2+: 编写自己的模板
+
+**参考:**
- [模板库](../../templates/index.md) — 浏览所有模板
-- [创建自定义模板](custom-templates.md) — 编写自己的模板
-- [选择方法](choosing-methods.md) — 何时使用方法
+- [使用方法](using-methods.md) — 何时使用方法
\ No newline at end of file
diff --git a/docs/zh/python/guides/working-with-autotypes.md b/docs/zh/python/guides/working-with-autotypes.md
index 4d768c3..7d9d369 100644
--- a/docs/zh/python/guides/working-with-autotypes.md
+++ b/docs/zh/python/guides/working-with-autotypes.md
@@ -1,161 +1,171 @@
# 使用自动类型
-提取、操作和利用结构化知识数据。
+!!! tip "Level 2 - 进阶"
+ 本指南涵盖配置化 Auto-Type 用法。在阅读前,请先完成 [Level 1: 使用模板](using-templates.md) 和 [Level 1: 使用方法](using-methods.md)。
+
+学习如何直接配置自动类型,以自定义 schema、去重逻辑和提取行为。
---
## 什么是自动类型?
-自动类型是智能数据结构,自动从文本中提取和组织知识。它们提供:
+自动类型是 Hyper-Extract 的核心数据结构,负责从文本中提取、组织和存储结构化知识。它们提供:
- **类型安全的 schema** — 基于 Pydantic 的验证
- **LLM 驱动的提取** — 自动内容处理
- **内置操作** — 搜索、合并、可视化
- **序列化** — 保存/加载到磁盘
----
-
-## 8 种自动类型
-
-### 标量类型
-
-#### AutoModel
-
-单个结构化对象提取。
-
-```python
-from hyperextract import Template
-
-ka = Template.create("finance/earnings_summary", "en")
-result = ka.parse(report_text)
-
-# 直接访问字段
-print(result.data.company_name)
-print(result.data.revenue)
-print(result.data.eps)
-```
-
-#### AutoList
-
-有序集合提取。
-
-```python
-from hyperextract import Template
-
-ka = Template.create("general/base_list", "en")
-result = ka.parse(text)
-
-# 遍历项目
-for item in result.data.items:
- print(item)
-
-# 按索引访问
-first = result.data.items[0]
-```
-
-#### AutoSet
-
-去重集合提取。
-
-```python
-from hyperextract import Template
-
-ka = Template.create("general/base_set", "en")
-result = ka.parse(text)
-
-# 项目是唯一的
-for item in result.data.items:
- print(item)
-```
-
-### 图谱类型
-
-#### AutoGraph
+所有自动类型都继承自 `BaseAutoType`,因此共享一组通用能力(如 `parse`、`feed_text`、`build_index`、`search`、`chat`、`dump`、`load` 等)。
-实体关系图谱提取。
-
-```python
-from hyperextract import Template
-
-ka = Template.create("general/knowledge_graph", "en")
-result = ka.parse(text)
+---
-# 访问节点
-for node in result.nodes:
- print(f"{node.name} ({node.type})")
- print(f" 描述: {node.description}")
+## 三层使用架构
-# 访问边
-for edge in result.edges:
- print(f"{edge.source} --{edge.type}--> {edge.target}")
-```
+Hyper-Extract 提供三个控制层级。本文档聚焦 **层级 2**。
-#### AutoHypergraph
+| 层级 | 方式 | 何时使用 | 参考文档 |
+|-------|----------|-------------|----------|
+| **层级 1** | 模板 / 方法 | 快速开始、标准用例 | [使用模板](using-templates.md)、[使用方法](using-methods.md) |
+| **层级 2** | 配置化自动类型 | 自定义 schema、保留预置提取逻辑 | **本文档** |
+| **层级 3** | 完全自定义方法 | 完全控制提取过程 | [方法概念](../../concepts/methods.md) |
-多实体关系提取。
+---
-```python
-from hyperextract import Template
+## 层级 2:配置化自动类型用法
-ka = Template.create("general/base_hypergraph", "en")
-result = ka.parse(text)
+当你需要自定义 schema,但不想从零实现提取逻辑时,可以直接实例化自动类型并传入配置参数。
-# 超边连接多个实体
-for edge in result.edges:
- print(f"类型: {edge.type}")
- print(f"实体: {edge.entities}")
-```
+### 何时使用层级 2
-#### AutoTemporalGraph
+- 你需要自定义节点/边 schema
+- 你想控制去重逻辑
+- 模板输出不完全匹配你的需求
+- 你在构建可复用的 Python 组件
-基于时间的图谱提取。
+### 完整示例:自定义图谱
```python
-from hyperextract import Template
-
-ka = Template.create("general/base_temporal_graph", "en")
-result = ka.parse(text)
-
-# 边包含时间信息
-for edge in result.edges:
- print(f"{edge.source} --{edge.type}--> {edge.target}")
- if hasattr(edge, 'time'):
- print(f" 时间: {edge.time}")
+from hyperextract import AutoGraph
+from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+from pydantic import BaseModel, Field
+
+# 步骤 1:定义自定义 schema
+class Person(BaseModel):
+ """自定义节点 schema"""
+ name: str = Field(description="人员全名")
+ role: str = Field(description="职位或角色")
+ expertise: list[str] = Field(default=[], description="专业领域")
+
+class Collaboration(BaseModel):
+ """自定义边 schema"""
+ source: str = Field(description="第一人姓名")
+ target: str = Field(description="第二人姓名")
+ project: str = Field(description="共同项目")
+ year: int = Field(description="协作年份")
+
+# 步骤 2:配置 LLM 客户端
+llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+embedder = OpenAIEmbeddings(model="text-embedding-3-small")
+
+# 步骤 3:创建配置化的 AutoGraph
+graph = AutoGraph[Person, Collaboration](
+ node_schema=Person,
+ edge_schema=Collaboration,
+ # 定义如何提取唯一键用于去重
+ node_key_extractor=lambda p: p.name,
+ edge_key_extractor=lambda c: f"{c.source}-{c.target}-{c.project}",
+ # 定义如何从边提取节点引用
+ nodes_in_edge_extractor=lambda c: (c.source, c.target),
+ # LLM 客户端
+ llm_client=llm,
+ embedder=embedder,
+)
+
+# 步骤 4:提取
+text = """
+陈博士和王博士在2023年合作了气候 AI 项目。
+陈博士是机器学习研究员,专长于神经网络和气候建模。
+王博士专攻数据工程和分布式系统。
+"""
+
+graph.feed_text(text)
+
+# 步骤 5:访问结果
+print(f"提取了 {len(graph.nodes)} 个人员")
+for person in graph.nodes:
+ print(f"- {person.name}: {person.role}")
+ print(f" 专业: {', '.join(person.expertise)}")
+
+print(f"\n提取了 {len(graph.edges)} 个协作关系")
+for collab in graph.edges:
+ print(f"- {collab.source} 和 {collab.target}: {collab.project} ({collab.year})")
+
+# 步骤 6:使用内置功能
+graph.build_index()
+
+# 搜索
+nodes, edges = graph.search("机器学习", top_k=2)
+print(f"\n搜索找到: {len(nodes)} 个人员")
+
+# 可视化
+graph.show()
```
-#### AutoSpatialGraph
+### 关键配置参数
-基于位置的图谱提取。
-
-```python
-from hyperextract import Template
+| 参数 | 必需 | 描述 |
+|-----------|----------|-------------|
+| `node_schema` / `edge_schema` | 是 | 定义结构的 Pydantic 模型 |
+| `node_key_extractor` | 是 | 从节点提取唯一键的函数 |
+| `edge_key_extractor` | 是 | 从边提取唯一键的函数 |
+| `nodes_in_edge_extractor` | 是 | 从边获取 (source, target) 的函数 |
+| `llm_client` | 是 | LangChain 兼容的 LLM 客户端 |
+| `embedder` | 是 | LangChain 兼容的嵌入客户端 |
-ka = Template.create("general/base_spatial_graph", "en")
-result = ka.parse(text)
+### 对比:模板 vs 配置化自动类型
-# 节点/边包含位置
-for node in result.nodes:
- if hasattr(node, 'location'):
- print(f"{node.name} at {node.location}")
-```
+| 方面 | 模板 | 配置化自动类型 |
+|--------|----------|---------------------|
+| Schema 定义 | YAML 文件 | Python Pydantic 类 |
+| 提取逻辑 | 预构建 | 相同预构建逻辑 |
+| 去重 | 预配置 | 你定义键提取器 |
+| 语言支持 | 内置 | 你提供提示 |
+| 可复用性 | 分享 YAML 文件 | 打包为 Python 模块 |
-#### AutoSpatioTemporalGraph
+### 更多配置示例
-时间和空间组合提取。
+#### 时序图谱
```python
-from hyperextract import Template
-
-ka = Template.create("general/base_spatio_temporal_graph", "en")
-result = ka.parse(text)
-
-# 完整上下文:谁、什么、何时、何地
-for edge in result.edges:
- print(f"事件: {edge.type}")
- if hasattr(edge, 'time'):
- print(f" 何时: {edge.time}")
- if hasattr(edge, 'location'):
- print(f" 何地: {edge.location}")
+from hyperextract import AutoTemporalGraph
+from pydantic import BaseModel, Field
+
+class Event(BaseModel):
+ """节点:历史事件"""
+ name: str = Field(description="事件名称")
+ category: str = Field(description="事件类型")
+
+class CausalLink(BaseModel):
+ """边:带时间的因果关系"""
+ source: str = Field(description="早期事件")
+ target: str = Field(description="后期事件")
+ relationship: str = Field(description="连接方式")
+ time: str = Field(description="连接发生时间")
+
+timeline = AutoTemporalGraph[Event, CausalLink](
+ node_schema=Event,
+ edge_schema=CausalLink,
+ node_key_extractor=lambda e: e.name,
+ edge_key_extractor=lambda l: f"{l.source}-{l.target}-{l.time}",
+ nodes_in_edge_extractor=lambda l: (l.source, l.target),
+ llm_client=llm,
+ embedder=embedder,
+ # 时序特有:从边提取时间
+ time_extractor=lambda l: l.time,
+)
+
+timeline.feed_text(historical_text)
```
---
@@ -271,9 +281,9 @@ print(f"边: {edge_types}")
---
-## 高级用法
+## 高级用法 {#advanced-usage}
-### 自定义 Schema 访问
+### 访问 Schema
```python
# 访问 schema
@@ -305,15 +315,31 @@ elif isinstance(result, AutoList):
## 最佳实践
-1. **访问可选字段前检查 hasattr** — Schema 字段可能不同
+### 层级 2(配置化自动类型)
+
+1. **仔细设计 schema** — 字段成为 LLM 提取目标
+2. **使用清晰的 Field 描述** — 帮助 LLM 理解期望
+3. **选择好的键提取器** — 对去重至关重要
+4. **用小样本测试** — 迭代 schema 设计
+
+### 通用
+
+1. **访问可选字段前检查 `hasattr`** — Schema 字段可能不同
2. **处理空结果** — 始终检查 `empty()`
-3. **使用 model_dump 进行序列化** — 正确的 JSON 转换
+3. **使用 `model_dump` 进行序列化** — 正确的 JSON 转换
4. **利用类型提示** — IDE 自动完成支持
---
## 另请参见
-- [搜索和聊天](search-and-chat.md)
-- [保存和加载](saving-loading.md)
-- [自动类型参考](../../concepts/autotypes.md)
+**前置知识:**
+- [使用模板](using-templates.md) — Level 1 基础
+- [使用方法](using-methods.md) — Level 1 基础
+- [自动类型概念](../../concepts/autotypes.md) — 每种类型的作用
+
+**下一步:**
+- [创建自定义模板](custom-templates.md) — 打包你的配置
+- [增量更新](incremental-updates.md) — 添加更多文档
+- [搜索和聊天](search-and-chat.md) — 使用提取的知识
+- [保存和加载](saving-loading.md) — 持久化结果
diff --git a/docs/zh/python/index.md b/docs/zh/python/index.md
index 5c64a34..d120f8c 100644
--- a/docs/zh/python/index.md
+++ b/docs/zh/python/index.md
@@ -24,7 +24,7 @@ pip install hyper-extract[dev]
from hyperextract import Template
# 创建模板
-ka = Template.create("general/biography_graph", language="en")
+ka = Template.create("general/biography_graph", language="zh")
# 提取知识
with open("document.md") as f:
@@ -41,6 +41,8 @@ result.build_index()
result.show()
```
+![交互式可视化](../../assets/zh_show.png)
+
---
## 核心类
@@ -53,10 +55,10 @@ result.show()
from hyperextract import Template
# 从预设创建
-ka = Template.create("general/biography_graph", language="en")
+ka = Template.create("general/biography_graph", language="zh")
# 从自定义 YAML 创建
-ka = Template.create("/path/to/custom_template.yaml", language="en")
+ka = Template.create("/path/to/custom_template.yaml", language="zh")
# 从方法创建
ka = Template.create("method/light_rag")
@@ -85,7 +87,7 @@ ka = Template.create("method/light_rag")
```python
# 创建
-ka = Template.create(template_path, language="en")
+ka = Template.create(template_path, language="zh")
# 提取
result = ka.parse(text) # 新提取
@@ -104,6 +106,8 @@ result.load("./output/") # 从磁盘加载
result.show() # 交互式可视化
```
+![交互式可视化](../../assets/zh_show.png)
+
---
## 文档结构
@@ -112,15 +116,15 @@ result.show() # 交互式可视化
- **[核心概念](core-concepts.md)** — 模板、自动类型、方法详解
- **指南:**
- [使用模板](guides/using-templates.md)
- - [选择方法](guides/choosing-methods.md)
+ - [使用方法](guides/using-methods.md)
- [使用自动类型](guides/working-with-autotypes.md)
- [搜索和聊天](guides/search-and-chat.md)
- [增量更新](guides/incremental-updates.md)
- [保存和加载](guides/saving-loading.md)
- **API 参考:**
- [模板](api-reference/template.md)
- - [自动类型](api-reference/autotypes.md)
- - [方法](api-reference/methods.md)
+ - [自动类型](api-reference/autotypes/base.md)
+ - [方法](api-reference/methods/registry.md)
---
@@ -131,7 +135,7 @@ result.show() # 交互式可视化
```python
from hyperextract import Template
-ka = Template.create("general/concept_graph", language="en")
+ka = Template.create("general/concept_graph", language="zh")
with open("paper.md") as f:
paper = ka.parse(f.read())
@@ -149,7 +153,7 @@ print(response.content)
```python
from hyperextract import Template
-ka = Template.create("finance/earnings_summary", language="en")
+ka = Template.create("finance/earnings_summary", language="zh")
report = ka.parse(earnings_text)
print(report.data.revenue)
@@ -161,17 +165,17 @@ print(report.data.eps)
```python
from hyperextract import Template
-ka = Template.create("general/knowledge_graph", language="en")
+ka = Template.create("general/graph", language="zh")
# 初始提取
-kb = ka.parse(doc1_text)
+ka = ka.parse(doc1_text)
# 添加更多文档
-kb.feed_text(doc2_text)
-kb.feed_text(doc3_text)
+ka.feed_text(doc2_text)
+ka.feed_text(doc3_text)
# 保存供以后使用
-kb.dump("./my_kb/")
+ka.dump("./my_ka/")
```
---
@@ -205,7 +209,7 @@ embedder = OpenAIEmbeddings(model="text-embedding-3-large")
ka = Template.create(
"general/biography_graph",
- language="en",
+ language="zh",
llm_client=llm,
embedder=embedder
)
@@ -220,7 +224,7 @@ Hyper-Extract 完全类型化,支持 IDE 自动完成:
```python
from hyperextract import Template, AutoGraph
-ka: AutoGraph = Template.create("general/knowledge_graph", "en")
+ka: AutoGraph = Template.create("general/graph", "zh")
result = ka.parse(text)
# IDE 自动完成有效
diff --git a/docs/zh/python/quickstart.md b/docs/zh/python/quickstart.md
index 777a34f..11ed90e 100644
--- a/docs/zh/python/quickstart.md
+++ b/docs/zh/python/quickstart.md
@@ -37,14 +37,24 @@ load_dotenv()
from hyperextract import Template
# 创建模板
-ka = Template.create("general/biography_graph", language="en")
+ka = Template.create("general/biography_graph", language="zh")
# 您的文本
text = """
-Marie Curie was a Polish-French physicist and chemist who conducted
-pioneering research on radioactivity. She was the first woman to win
-a Nobel Prize and the only person to win Nobel Prizes in two different
-scientific fields.
+苏轼,字子瞻,号东坡居士,是北宋时期最杰出的文学家、书画家、政治家。
+他与父亲苏洵、弟弟苏辙并称"三苏",同列唐宋八大家。
+
+苏轼于1037年出生于眉州眉山。1057年科举中举,受欧阳修赏识。
+后因乌台诗案被贬黄州,创作了大量千古传诵的名篇。
+
+代表作:《念奴娇·赤壁怀古》《水调歌头·明月几时有》《赤壁赋》
+
+苏轼一生宦海浮沉,历任杭州、密州、徐州、湖州等地知州。
+在杭州任上,他疏浚西湖,修筑苏堤,留下"欲把西湖比西子"的千古名句。
+晚年因新党执政被贬至惠州、儋州,仍心系百姓,兴办学堂,传播中原文化。
+
+其文学成就横跨诗、词、文、赋,书法位列"宋四家"之首,
+绘画开文人画先河,是中国历史上罕见的全才式人物。
"""
# 提取
@@ -63,11 +73,11 @@ if result.nodes:
**输出:**
```
-Entities: 5
-Relations: 4
+节点数: 5
+边数: 4
-First: Marie Curie (person)
-Description: Polish-French physicist and chemist
+第一个: 苏轼 (人物)
+描述: 北宋文学家、书画家、政治家
```
### 3. 可视化
@@ -80,6 +90,8 @@ result.build_index()
result.show()
```
+![交互式可视化](../../assets/zh_show.png)
+
### 4. 搜索
```python
@@ -87,7 +99,7 @@ result.show()
result.build_index()
# 搜索
-nodes, edges = result.search("Nobel Prize", top_k=3)
+nodes, edges = result.search("代表作", top_k=3)
for node in nodes:
print(f"节点: {node.name}")
for edge in edges:
@@ -98,7 +110,7 @@ for edge in edges:
```python
# 提问
-response = result.chat("Marie Curie 发现了什么?")
+response = result.chat("苏轼写过哪些著名的诗词?")
print(response.content)
```
@@ -106,11 +118,11 @@ print(response.content)
```python
# 保存到磁盘
-result.dump("./curie_kb/")
+result.dump("./sushi_kb/")
# 之后加载
-new_ka = Template.create("general/biography_graph", language="en")
-new_ka.load("./curie_kb/")
+new_ka = Template.create("general/biography_graph", language="zh")
+new_ka.load("./sushi_kb/")
```
---
@@ -128,14 +140,21 @@ from hyperextract import Template
def main():
# 创建模板
print("Creating template...")
- ka = Template.create("general/biography_graph", language="en")
+ ka = Template.create("general/biography_graph", language="zh")
# 示例文本
text = """
- Ada Lovelace was an English mathematician and writer, chiefly known
- for her work on Charles Babbage's early mechanical general-purpose
- computer, the Analytical Engine. She is often regarded as the first
- computer programmer.
+ 苏轼,字子瞻,号东坡居士,是北宋时期最杰出的文学家、书画家、政治家。
+ 他与父亲苏洵、弟弟苏辙并称"三苏",同列唐宋八大家。
+
+ 苏轼于1037年出生于眉州眉山。1057年科举中举,受欧阳修赏识。
+ 后因乌台诗案被贬黄州,创作了大量千古传诵的名篇。
+
+ 代表作:《念奴娇·赤壁怀古》《水调歌头·明月几时有》《赤壁赋》
+
+ 苏轼一生宦海浮沉,历任杭州、密州、徐州、湖州等地知州。
+ 在杭州任上,他疏浚西湖,修筑苏堤。
+ 晚年因新党执政被贬至惠州、儋州,仍心系百姓,兴办学堂,传播中原文化。
"""
# 提取知识
@@ -156,14 +175,14 @@ def main():
print("\nBuilding search index...")
result.build_index()
- search_nodes, search_edges = result.search("computer programming", top_k=2)
+ search_nodes, search_edges = result.search("西湖", top_k=2)
print(f"\n搜索结果: {len(search_nodes)} 个节点, {len(search_edges)} 条边")
# 保存
- print("\nSaving knowledge base...")
- result.dump("./ada_kb/")
+ print("\nSaving knowledge abstract...")
+ result.dump("./sushi_kb/")
- print("\nDone! Try: he show ./ada_kb/")
+ print("\nDone! Try: he show ./sushi_kb/")
if __name__ == "__main__":
main()
diff --git a/docs/zh/resources/contributing.md b/docs/zh/resources/contributing.md
new file mode 100644
index 0000000..5698fab
--- /dev/null
+++ b/docs/zh/resources/contributing.md
@@ -0,0 +1,211 @@
+# 贡献指南
+
+如何为 Hyper-Extract 做出贡献。
+
+---
+
+## 贡献方式
+
+- **报告 Bug** — 提交 GitHub Issue
+- **请求新功能** — 建议新功能
+- **改进文档** — 修复错别字,添加示例
+- **添加模板** — 分享领域特定模板
+- **提交代码** — 修复 Bug 或添加功能
+
+---
+
+## 快速开始
+
+### 1. Fork 仓库
+
+```bash
+git clone https://github.com/your-username/hyper-extract.git
+cd hyper-extract
+```
+
+### 2. 配置开发环境
+
+```bash
+# 创建虚拟环境
+python -m venv venv
+source venv/bin/activate # Windows: venv\Scripts\activate
+
+# 以可编辑模式安装
+pip install -e ".[dev]"
+```
+
+### 3. 运行测试
+
+```bash
+pytest
+```
+
+---
+
+## 开发规范
+
+### 代码风格
+
+- 遵循 PEP 8
+- 使用类型提示
+- 编写文档字符串(Google 风格)
+
+### 示例
+
+```python
+def process_data(text: str, max_length: int = 1000) -> dict:
+ """处理输入文本并返回结构化数据。
+
+ Args:
+ text: 要处理的输入文本
+ max_length: 最大处理长度
+
+ Returns:
+ 包含处理后数据的字典
+
+ Raises:
+ ValueError: 如果文本为空
+ """
+ if not text:
+ raise ValueError("Text cannot be empty")
+
+ # 处理逻辑
+ return {"result": text[:max_length]}
+```
+
+### 测试
+
+为新功能编写测试:
+
+```python
+def test_new_feature():
+ result = new_feature("input")
+ assert result["status"] == "success"
+```
+
+运行测试:
+```bash
+pytest tests/test_new_feature.py -v
+```
+
+---
+
+## 添加模板
+
+### 模板结构
+
+在 `hyperextract/templates/presets/<domain>/` 目录下创建 YAML 文件:
+
+```yaml
+language: [zh, en]
+
+name: my_template
+type: graph
+tags: [domain, category]
+
+description:
+ zh: "中文描述"
+ en: "English description"
+
+output:
+ # 模式定义
+
+guideline:
+ # LLM 指令
+
+identifiers:
+ # ID 规则
+
+display:
+ # 可视化设置
+```
+
+### 测试模板
+
+```python
+from hyperextract import Template
+
+# 测试你的模板
+ka = Template.create("domain/my_template", "en")
+result = ka.parse(test_text)
+
+# 验证输出
+assert len(result.nodes) > 0
+```
+
+### 提交模板
+
+1. 添加模板 YAML 文件
+2. 添加测试用例
+3. 更新文档
+4. 提交 PR 并附带描述
+
+---
+
+## 文档
+
+### 构建文档
+
+```bash
+# 安装文档依赖
+pip install mkdocs mkdocs-material mkdocstrings[python]
+
+# 本地预览
+mkdocs serve
+
+# 构建
+mkdocs build
+```
+
+### 文档规范
+
+- 编写清晰、简洁的说明
+- 包含代码示例
+- 测试所有示例
+- 使用 Markdown 格式
+
+---
+
+## Pull Request 流程
+
+1. **创建分支**:
+ ```bash
+ git checkout -b feature/my-feature
+ ```
+
+2. **进行更改**,提交信息清晰
+
+3. **添加测试**,覆盖新功能
+
+4. **更新文档**,如有需要
+
+5. **提交 PR**,包含:
+ - 清晰的描述
+ - 更改内容和原因
+ - 执行的测试
+ - 截图(如有 UI 更改)
+
+---
+
+## 代码审查
+
+所有提交都需要审查。我们会检查:
+
+- 代码质量和风格
+- 测试覆盖率
+- 文档
+- 向后兼容性
+
+---
+
+## 有问题?
+
+- 开启 [GitHub Discussion](https://github.com/yifanfeng97/hyper-extract/discussions)
+- 在现有 Issue 中评论
+- 邮件:[email protected]
+
+---
+
+## 许可证
+
+通过贡献,您同意您的贡献将在 Apache-2.0 许可证下授权。
diff --git a/docs/zh/resources/faq.md b/docs/zh/resources/faq.md
index 2a4c640..397590d 100644
--- a/docs/zh/resources/faq.md
+++ b/docs/zh/resources/faq.md
@@ -100,21 +100,21 @@ he list template
先转换为文本:
```bash
pdftotext document.pdf document.txt
-he parse document.txt -t general/knowledge_graph -l en
+he parse document.txt -t general/graph -l zh
```
### 可以处理多个文档吗?
**选项 1**:增量添加
```bash
-he parse doc1.md -t general/graph -o ./kb/ -l en
-he feed ./kb/ doc2.md
-he feed ./kb/ doc3.md
+he parse doc1.md -t general/graph -o ./ka/ -l zh
+he feed ./ka/ doc2.md
+he feed ./ka/ doc3.md
```
**选项 2**:处理目录
```bash
-he parse ./docs/ -t general/graph -o ./kb/ -l en
+he parse ./docs/ -t general/graph -o ./ka/ -l zh
```
### 如何提取中文内容?
@@ -145,8 +145,8 @@ he parse doc.md -t general/biography_graph -l zh
```python
for batch in chunks(documents, 5):
for doc in batch:
- kb.feed_text(doc)
- kb.dump("./checkpoint/")
+ ka.feed_text(doc)
+ ka.dump("./checkpoint/")
```
---
@@ -176,6 +176,8 @@ result.build_index()
result.show()
```
+![交互式可视化](../../assets/zh_show.png)
+
### 可以导出为其他格式吗?
```python
@@ -217,8 +219,8 @@ he build-index ./output/
尝试:
- 使用不同的搜索词
-- 增加 `top_k`:`he search ./kb/ "query" -n 10`
-- 检查索引是否已构建:`he info ./kb/`
+- 增加 `top_k`:`he search ./ka/ "查询" -n 10`
+- 检查索引是否已构建:`he info ./ka/`
---
@@ -249,7 +251,7 @@ from hyperextract import Template
class MyApp:
def __init__(self):
- self.ka = Template.create("general/graph", "en")
+ self.ka = Template.create("general/graph", "zh")
def process_document(self, text):
return self.ka.parse(text)
diff --git a/docs/zh/resources/troubleshooting.md b/docs/zh/resources/troubleshooting.md
index 77a6eed..ff443f0 100644
--- a/docs/zh/resources/troubleshooting.md
+++ b/docs/zh/resources/troubleshooting.md
@@ -102,7 +102,7 @@
**解决方案**:
```bash
# 添加语言参数
-he parse doc.md -t general/biography_graph -o ./out/ -l en
+he parse doc.md -t general/biography_graph -o ./out/ -l zh
```
注意:方法模板不需要语言参数。
@@ -115,18 +115,18 @@ he parse doc.md -t general/biography_graph -o ./out/ -l en
1. **强制覆盖**:
```bash
- he parse doc.md -t general/graph -o ./out/ -l en -f
+ he parse doc.md -t general/graph -o ./out/ -l zh -f
```
2. **使用不同目录**:
```bash
- he parse doc.md -t general/graph -o ./out2/ -l en
+ he parse doc.md -t general/graph -o ./out2/ -l zh
```
3. **删除现有目录**:
```bash
rm -rf ./out/
- he parse doc.md -t general/graph -o ./out/ -l en
+ he parse doc.md -t general/graph -o ./out/ -l zh
```
---
@@ -161,7 +161,7 @@ he build-index ./output/
3. **增加 top_k**:
```bash
- he search ./output/ "query" -n 10
+ he search ./output/ "查询" -n 10
```
4. **检查数据是否存在**:
@@ -177,7 +177,7 @@ he build-index ./output/
**解决方案**:
```bash
he build-index ./output/
-he talk ./output/ -q "your question"
+he talk ./output/ -q "你的问题"
```
---
@@ -192,18 +192,18 @@ he talk ./output/ -q "your question"
1. **批量处理时跳过索引**:
```bash
- he parse doc.md -t general/graph -o ./out/ -l en --no-index
+ he parse doc.md -t general/graph -o ./out/ -l zh --no-index
```
2. **减少分块大小**(Python):
```python
- ka = Template.create("general/graph", "en")
+ ka = Template.create("general/graph", "zh")
ka.chunk_size = 1024 # 默认:2048
```
3. **减少工作线程**(如果达到速率限制):
```python
- ka = Template.create("general/graph", "en")
+ ka = Template.create("general/graph", "zh")
ka.max_workers = 5 # 默认:10
```
@@ -250,7 +250,7 @@ he talk ./output/ -q "your question"
2. **尝试不同的模板**:
```bash
- he parse doc.md -t general/base_model -l en
+ he parse doc.md -t general/model -l zh
```
3. **检查语言**:
@@ -270,19 +270,19 @@ he talk ./output/ -q "your question"
1. **检查文件结构**:
```bash
- ls ./kb/
+ ls ./ka/
# 应该有:data.json, metadata.json
```
2. **验证 JSON**:
```bash
- python -c "import json; json.load(open('./kb/data.json'))"
+ python -c "import json; json.load(open('./ka/data.json'))"
```
3. **重新提取**:
```bash
- rm -rf ./kb/
- he parse doc.md -t general/graph -o ./kb/ -l en
+ rm -rf ./ka/
+ he parse doc.md -t general/graph -o ./ka/ -l zh
```
---
@@ -305,11 +305,11 @@ import logging
logging.basicConfig(level=logging.DEBUG)
from hyperextract import Template
-ka = Template.create("general/graph", "en")
+ka = Template.create("general/graph", "zh")
```
或在 CLI 配置中:
```toml
[defaults]
verbose = true
-```
+```
\ No newline at end of file
diff --git a/docs/zh/templates/browse.md b/docs/zh/templates/browse.md
deleted file mode 100644
index 7e8d257..0000000
--- a/docs/zh/templates/browse.md
+++ /dev/null
@@ -1,192 +0,0 @@
-# 浏览所有模板
-
-可用模板的完整列表。
-
----
-
-## 统计信息
-
-- **总模板数**:80+
-- **类别**:6 个领域
-- **自动类型**:8 种类型
-- **语言**:中文、英文
-
----
-
-## 按领域
-
-### 通用模板
-
-| 模板 | 类型 | 描述 |
-|------|------|------|
-| `general/base_model` | model | 基础结构化模型 |
-| `general/base_list` | list | 基础有序列表 |
-| `general/base_set` | set | 基础唯一集合 |
-| `general/base_graph` | graph | 基础知识图谱 |
-| `general/base_hypergraph` | hypergraph | 基础超图 |
-| `general/base_temporal_graph` | temporal_graph | 基础时序图 |
-| `general/base_spatial_graph` | spatial_graph | 基础空间图 |
-| `general/base_spatio_temporal_graph` | spatio_temporal_graph | 基础时空图 |
-| `general/biography_graph` | temporal_graph | 人物生平时间线 |
-| `general/concept_graph` | graph | 研究概念提取 |
-| `general/doc_structure` | model | 文档大纲结构 |
-| `general/workflow_graph` | graph | 流程工作流 |
-
-### 金融模板
-
-| 模板 | 类型 | 描述 |
-|------|------|------|
-| `finance/earnings_summary` | model | 季度/年度财报 |
-| `finance/event_timeline` | temporal_graph | 金融事件 |
-| `finance/ownership_graph` | graph | 公司股权结构 |
-| `finance/risk_factor_set` | set | 风险因素 |
-| `finance/sentiment_model` | model | 情感分析 |
-
-### 法律模板
-
-| 模板 | 类型 | 描述 |
-|------|------|------|
-| `legal/case_citation` | graph | 法律案例先例 |
-| `legal/case_fact_timeline` | temporal_graph | 案件时间线 |
-| `legal/compliance_list` | list | 合规要求 |
-| `legal/contract_obligation` | list | 合同义务 |
-| `legal/defined_term_set` | set | 定义术语 |
-
-### 医疗模板
-
-| 模板 | 类型 | 描述 |
-|------|------|------|
-| `medicine/anatomy_graph` | graph | 解剖结构 |
-| `medicine/discharge_instruction` | model | 患者出院摘要 |
-| `medicine/drug_interaction` | graph | 药物相互作用 |
-| `medicine/hospital_timeline` | temporal_graph | 住院时间线 |
-| `medicine/treatment_map` | graph | 治疗方案 |
-
-### 中医模板
-
-| 模板 | 类型 | 描述 |
-|------|------|------|
-| `tcm/formula_composition` | graph | 草药方剂组成 |
-| `tcm/herb_property` | model | 草药属性 |
-| `tcm/herb_relation` | graph | 草药关系 |
-| `tcm/meridian_graph` | graph | 经络路径 |
-| `tcm/syndrome_reasoning` | graph | 辨证推理 |
-
-### 工业模板
-
-| 模板 | 类型 | 描述 |
-|------|------|------|
-| `industry/emergency_response` | graph | 应急程序 |
-| `industry/equipment_topology` | graph | 设备连接 |
-| `industry/failure_case` | temporal_graph | 故障分析 |
-| `industry/operation_flow` | graph | 操作流程 |
-| `industry/safety_control` | graph | 安全控制系统 |
-
----
-
-## 按自动类型
-
-### Model 模板
-
-| 模板 | 领域 | 描述 |
-|------|------|------|
-| `general/base_model` | general | 基础结构化模型 |
-| `finance/earnings_summary` | finance | 财务摘要 |
-| `finance/sentiment_model` | finance | 情感分析 |
-| `medicine/discharge_instruction` | medical | 出院摘要 |
-| `tcm/herb_property` | tcm | 草药属性 |
-
-### List 模板
-
-| 模板 | 领域 | 描述 |
-|------|------|------|
-| `general/base_list` | general | 基础列表 |
-| `legal/compliance_list` | legal | 合规要求 |
-| `legal/contract_obligation` | legal | 合同义务 |
-
-### Set 模板
-
-| 模板 | 领域 | 描述 |
-|------|------|------|
-| `general/base_set` | general | 基础集合 |
-| `finance/risk_factor_set` | finance | 风险因素 |
-| `legal/defined_term_set` | legal | 定义术语 |
-
-### Graph 模板
-
-| 模板 | 领域 | 描述 |
-|------|------|------|
-| `general/base_graph` | general | 基础图谱 |
-| `general/knowledge_graph` | general | 知识图谱 |
-| `general/concept_graph` | general | 概念图谱 |
-| `finance/ownership_graph` | finance | 股权结构 |
-| `legal/case_citation` | legal | 案例先例 |
-| `medicine/anatomy_graph` | medical | 解剖结构 |
-| `tcm/herb_relation` | tcm | 草药关系 |
-
-### Temporal Graph 模板
-
-| 模板 | 领域 | 描述 |
-|------|------|------|
-| `general/biography_graph` | general | 传记时间线 |
-| `finance/event_timeline` | finance | 金融事件 |
-| `legal/case_fact_timeline` | legal | 案例时间线 |
-| `medicine/hospital_timeline` | medical | 住院时间线 |
-
----
-
-## 按语言
-
-### 仅英文
-
-方法(不是模板):
-- `method/light_rag`
-- `method/graph_rag`
-- `method/hyper_rag`
-- `method/itext2kg`
-- 等等
-
-### 双语(zh、en)
-
-所有模板都支持两种语言:
-- `general/biography_graph`
-- `finance/earnings_summary`
-- `legal/contract_obligation`
-- 等等
-
----
-
-## 使用此列表
-
-### CLI
-
-```bash
-# 列出所有
-he list template
-
-# 按领域筛选
-he list template | grep finance
-```
-
-### Python
-
-```python
-from hyperextract import Template
-
-# 获取所有
-templates = Template.list()
-
-# 按类型筛选
-graphs = Template.list(filter_by_type="graph")
-
-# 按标签筛选
-finance = Template.list(filter_by_tag="finance")
-```
-
----
-
-## 参见
-
-- [如何选择](how-to-choose.md)
-- [模板库](index.md)
-- [领域特定指南](general/index.md)
diff --git a/docs/zh/templates/choosing/by-output.md b/docs/zh/templates/choosing/by-output.md
new file mode 100644
index 0000000..0a9e638
--- /dev/null
+++ b/docs/zh/templates/choosing/by-output.md
@@ -0,0 +1,279 @@
+# 按输出类型选择
+
+根据您需要的输出类型选择模板。
+
+---
+
+## 决策树
+
+```mermaid
+graph TD
+ A[您需要什么输出?] --> B{结构化摘要?}
+ B -->|是| C[AutoModel]
+ B -->|否| D{项目集合?}
+ D -->|否| E{项目之间有关系的?}
+ E -->|否| F[考虑 AutoModel 或重组任务]
+ E -->|是| G{每个关系有多个实体?}
+ G -->|是| H[AutoHypergraph]
+ G -->|否| I{时间维度?}
+ I -->|是| J{空间维度?}
+ J -->|是| K[AutoSpatioTemporalGraph]
+ J -->|否| L[AutoTemporalGraph]
+ I -->|否| M{空间维度?}
+ M -->|是| N[AutoSpatialGraph]
+ M -->|否| O[AutoGraph]
+ D -->|是| P{有序列表?}
+ P -->|是| Q[AutoList]
+ P -->|否| R[AutoSet]
+```
+
+---
+
+## AutoModel — 结构化摘要
+
+**适用场景:** 需要结构化报告或摘要
+
+**输出:** 带有字段的单个结构化对象
+
+**示例:**
+- 财务收益摘要
+- 患者出院摘要
+- 产品目录条目
+
+**模板:**
+
+| 模板 | 领域 |
+|------|------|
+| `general/model` | 通用 |
+| `finance/earnings_summary` | 财务报告 |
+| `medicine/discharge_instruction` | 医疗 |
+| `tcm/herb_property` | 中医 |
+
+**示例:**
+```python
+from hyperextract import Template
+
+ka = Template.create("finance/earnings_summary", "zh")
+result = ka.parse(earnings_report)
+
+print(result.data.revenue) # 1000000
+print(result.data.eps) # 2.50
+print(result.data.yoy_growth) # 15.3
+```
+
+---
+
+## AutoList — 有序集合
+
+**适用场景:** 需要有序列表
+
+**输出:** 可能包含重复项的有序列表
+
+**示例:**
+- 合规清单(按重要性排序)
+- 分步程序
+- 排名项目
+
+**模板:**
+
+| 模板 | 领域 |
+|------|------|
+| `general/list` | 通用 |
+| `legal/compliance_list` | 法律合规 |
+| `legal/contract_obligation` | 合同义务 |
+| `medicine/symptom_list` | 医疗症状 |
+
+**示例:**
+```python
+ka = Template.create("legal/compliance_list", "zh")
+result = ka.parse(contract_text)
+
+for item in result.data.items:
+ print(f"{item.priority}: {item.description}")
+```
+
+---
+
+## AutoSet — 唯一集合
+
+**适用场景:** 需要无序的唯一项目
+
+**输出:** 唯一项目的集合
+
+**示例:**
+- 风险因素(唯一类别)
+- 合同中的定义术语
+- 关键概念
+
+**模板:**
+
+| 模板 | 领域 |
+|------|------|
+| `general/set` | 通用 |
+| `finance/risk_factor_set` | 财务风险 |
+| `legal/defined_term_set` | 法律术语 |
+
+**示例:**
+```python
+ka = Template.create("finance/risk_factor_set", "zh")
+result = ka.parse(filing_text)
+
+for risk in result.data.items:
+ print(f"{risk.category}: {risk.description}")
+```
+
+---
+
+## AutoGraph — 实体网络
+
+**适用场景:** 需要二元关系(A → B)
+
+**输出:** 带有实体和二元边的图
+
+**示例:**
+- 知识图谱
+- 概念地图
+- 社交网络
+- 股权结构
+
+**模板:**
+
+| 模板 | 领域 |
+|------|------|
+| `general/graph` | 通用 |
+| `general/graph` | 领域知识 |
+| `general/concept_graph` | 研究概念 |
+| `finance/ownership_graph` | 公司股权 |
+| `medicine/anatomy_graph` | 解剖学 |
+
+**示例:**
+```python
+ka = Template.create("general/concept_graph", "zh")
+result = ka.parse(paper_text)
+
+# 访问实体
+for node in result.nodes:
+ print(f"概念: {node.name} ({node.type})")
+
+# 访问关系
+for edge in result.edges:
+ print(f"{edge.source} → {edge.target}: {edge.type}")
+```
+
+---
+
+## AutoTemporalGraph — 时间线 + 网络
+
+**适用场景:** 需要随时间变化的关系
+
+**输出:** 带有时间标注边的图
+
+**示例:**
+- 传记和生平事件
+- 案例年表
+- 事件序列
+
+**模板:**
+
+| 模板 | 领域 |
+|------|------|
+| `general/base_temporal_graph` | 通用 |
+| `general/biography_graph` | 人物生平 |
+| `finance/event_timeline` | 财务事件 |
+| `legal/case_fact_timeline` | 法律案例时间线 |
+| `medicine/hospital_timeline` | 患者时间线 |
+
+**示例:**
+```python
+ka = Template.create("general/biography_graph", "zh")
+result = ka.parse(biography_text)
+
+# 构建索引用于可视化
+result.build_index()
+result.show() # 交互式时间线视图
+
+# 按时间查询
+response = result.chat("1080年到1090年间发生了什么?")
+```
+
+---
+
+## AutoSpatialGraph — 位置 + 网络
+
+**适用场景:** 需要地理/空间关系
+
+**输出:** 带有位置标注实体的图
+
+**示例:**
+- 地理网络
+- 基于位置的系统
+- 空间拓扑
+
+**模板:**
+
+| 模板 | 领域 |
+|------|------|
+| `general/base_spatial_graph` | 通用 |
+
+---
+
+## AutoSpatioTemporalGraph — 时间 + 空间 + 网络
+
+**适用场景:** 需要时间和位置两个维度
+
+**输出:** 带有时间和空间标注的图
+
+**示例:**
+- 带位置的历史事件
+- 移动追踪
+- 随时间变化的地理政治
+
+**模板:**
+
+| 模板 | 领域 |
+|------|------|
+| `general/base_spatio_temporal_graph` | 通用 |
+
+---
+
+## AutoHypergraph — 复杂关系
+
+**适用场景:** 需要连接 2+ 实体的关系
+
+**输出:** 带有 n 元超边的超图
+
+**示例:**
+- 多方合同
+- 复杂化学反应
+- 会议论文(多位作者)
+
+**模板:**
+
+| 模板 | 领域 |
+|------|------|
+| `general/base_hypergraph` | 通用 |
+
+**注意:** 超图是高级功能。大多数用例可以用 AutoGraph 满足。
+
+---
+
+## 快速参考
+
+| 输出类型 | 自动类型 | 适用场景 |
+|---------|---------|---------|
+| 结构化报告 | AutoModel | 需要带字段的摘要 |
+| 有序列表 | AutoList | 项目有优先级/顺序 |
+| 唯一项目 | AutoSet | 需要去重集合 |
+| 二元网络 | AutoGraph | A 与 B 的关系 |
+| 时间线网络 | AutoTemporalGraph | 随时间的事件 |
+| 地理网络 | AutoSpatialGraph | 基于位置的关系 |
+| 时间 + 空间网络 | AutoSpatioTemporalGraph | 需要两个维度 |
+| 复杂关系 | AutoHypergraph | 多实体关系 |
+
+---
+
+## 了解更多
+
+- [自动类型概念指南](../../concepts/autotypes.md)
+- [按任务选择](by-task.md)
+- [模板概览](../reference/overview.md)
diff --git a/docs/zh/templates/choosing/by-task.md b/docs/zh/templates/choosing/by-task.md
new file mode 100644
index 0000000..166a7ec
--- /dev/null
+++ b/docs/zh/templates/choosing/by-task.md
@@ -0,0 +1,276 @@
+# 按任务选择
+
+为您的具体任务找到合适的模板。
+
+---
+
+## 研究与学术
+
+### 分析研究论文
+
+**目标:** 提取概念、方法、结果及其关系
+
+**推荐:** `general/concept_graph`
+
+```bash
+he parse paper.md -t general/concept_graph -l zh -o ./paper_kb/
+```
+
+**为什么选这个模板?**
+- 自动识别关键概念及其定义
+- 映射概念之间的关系
+- 支持层次结构(如"神经网络" → "CNNs")
+
+**替代选项:**
+
+| 模板 | 适用场景 |
+|------|---------|
+| `general/graph` | 更广泛的领域知识 |
+| `general/doc_structure` | 文档大纲提取 |
+| `general/workflow_graph` | 方法/流程工作流 |
+
+---
+
+### 提取技术文档
+
+**目标:** 从手册、规格说明或文档中获取结构化信息
+
+**推荐:** `general/model`
+
+```python
+from hyperextract import Template
+
+ka = Template.create("general/model", "zh")
+result = ka.parse(spec_text)
+
+print(result.data)
+```
+
+---
+
+## 人物与传记
+
+### 分析传记
+
+**目标:** 提取生平事件、关系和时间线
+
+**推荐:** `general/biography_graph`
+
+```bash
+he parse biography.md -t general/biography_graph -l zh -o ./bio_kb/
+```
+
+**功能:**
+- 提取人物、地点、事件
+- 捕获时间关系
+- 创建时间线可视化
+
+**示例输出:**
+```python
+{
+ "entities": [
+ {"name": "苏轼", "type": "人物"},
+ {"name": "赤壁赋", "type": "作品"}
+ ],
+ "relations": [
+ {"source": "苏轼", "target": "赤壁赋", "type": "创作", "time": "1082"}
+ ]
+}
+```
+
+**替代选项:**
+
+| 模板 | 适用场景 |
+|------|---------|
+| `general/model` | 简单的人物摘要 |
+| `general/graph` | 时间线之外的复杂关系 |
+
+---
+
+### 创建人物摘要
+
+**目标:** 人物的结构化摘要
+
+**推荐:** `general/model`
+
+---
+
+## 金融与商业
+
+### 分析财报
+
+**目标:** 提取财务指标和摘要
+
+**推荐:** `finance/earnings_summary`
+
+```bash
+he parse earnings.md -t finance/earnings_summary -l zh -o ./earnings/
+```
+
+**提取内容:**
+- 收入、净利润、每股收益
+- 同比增长、环比增长
+n- 分部业绩
+- 业绩指引
+
+---
+
+### 识别风险因素
+
+**目标:** 从 SEC 文件或报告中提取风险因素
+
+**推荐:** `finance/risk_factor_set`
+
+```bash
+he parse 10k.md -t finance/risk_factor_set -l zh -o ./risks/
+```
+
+**输出:** 带分类的唯一风险因素集合
+
+---
+
+### 映射公司股权
+
+**目标:** 提取股权结构和子公司
+
+**推荐:** `finance/ownership_graph`
+
+```bash
+he parse report.md -t finance/ownership_graph -l zh -o ./ownership/
+```
+
+---
+
+## 法律文档
+
+### 分析合同
+
+**目标:** 提取义务、当事人和截止日期
+
+**推荐:** `legal/contract_obligation`
+
+```bash
+he parse contract.md -t legal/contract_obligation -l zh -o ./contract/
+```
+
+**提取内容:**
+- 当事人义务
+- 截止日期和里程碑
+- 条件和条款
+
+---
+
+### 追踪案例时序
+
+**目标:** 创建法律案例事件时间线
+
+**推荐:** `legal/case_fact_timeline`
+
+```bash
+he parse case.md -t legal/case_fact_timeline -l zh -o ./case/
+```
+
+---
+
+### 提取定义术语
+
+**目标:** 获取合同中所有定义的术语
+
+**推荐:** `legal/defined_term_set`
+
+```bash
+he parse contract.md -t legal/defined_term_set -l zh -o ./terms/
+```
+
+---
+
+## 医疗与健康
+
+### 患者时间线
+
+**目标:** 追踪住院或治疗时间线
+
+**推荐:** `medicine/hospital_timeline`
+
+```bash
+he parse record.md -t medicine/hospital_timeline -l zh -o ./patient/
+```
+
+---
+
+### 药物信息
+
+**目标:** 提取药物相互作用和属性
+
+**推荐:** `medicine/drug_interaction`
+
+```bash
+he parse drug_info.md -t medicine/drug_interaction -l zh -o ./drugs/
+```
+
+---
+
+### 出院摘要
+
+**目标:** 生成患者出院摘要
+
+**推荐:** `medicine/discharge_instruction`
+
+---
+
+## 中医药
+
+### 草药属性
+
+**目标:** 提取草药特性和用途
+
+**推荐:** `tcm/herb_property`
+
+---
+
+### 方剂分析
+
+**目标:** 分析中药方剂组成
+
+**推荐:** `tcm/formula_composition`
+
+---
+
+## 工业与制造
+
+### 设备文档
+
+**目标:** 映射设备拓扑和连接
+
+**推荐:** `industry/equipment_topology`
+
+---
+
+### 安全程序
+
+**目标:** 提取安全控制系统
+
+**推荐:** `industry/safety_control`
+
+---
+
+## 快速参考
+
+| 任务 | 模板 | 类型 |
+|------|------|------|
+| 研究论文概念 | `general/concept_graph` | graph |
+| 人物传记 | `general/biography_graph` | temporal_graph |
+| 财务摘要 | `finance/earnings_summary` | model |
+| 风险因素 | `finance/risk_factor_set` | set |
+| 合同义务 | `legal/contract_obligation` | list |
+| 案例时间线 | `legal/case_fact_timeline` | temporal_graph |
+| 住院时间线 | `medicine/hospital_timeline` | temporal_graph |
+| 药物相互作用 | `medicine/drug_interaction` | graph |
+
+---
+
+## 还不确定?
+
+→ [按输出类型选择](by-output.md)
+→ [如何选择](../how-to-choose.md)
+→ [模板概览](../reference/overview.md)
diff --git a/docs/zh/templates/examples/financial-report.md b/docs/zh/templates/examples/financial-report.md
new file mode 100644
index 0000000..5b315ba
--- /dev/null
+++ b/docs/zh/templates/examples/financial-report.md
@@ -0,0 +1,344 @@
+# 财务报告分析
+
+从收益报告和 SEC 文件中提取财务信息的完整指南。
+
+---
+
+## 场景
+
+您有一份财务文档,想要:
+- 提取收益指标(收入、EPS、增长)
+- 识别风险因素
+- 映射股权结构
+- 创建事件时间线
+
+---
+
+## 按任务推荐模板
+
+### 收益摘要
+
+**模板:** `finance/earnings_summary`
+
+最适合季度/年度收益报告、10-Q、10-K 文件。
+
+**提取内容:**
+- 收入和净利润
+- EPS(基本和稀释)
+- 同比和环比增长
+- 分部业绩
+- 前瞻指引
+
+---
+
+### 风险因素 {#risk-factors}
+
+**模板:** `finance/risk_factor_set`
+
+最适合 SEC 文件的风险评估部分。
+
+**提取内容:**
+- 风险类别
+- 风险描述
+- 影响评估
+
+---
+
+### 股权结构 {#ownership-structure}
+
+**模板:** `finance/ownership_graph`
+
+最适合映射子公司、投资和企业结构。
+
+**提取内容:**
+- 子公司关系
+- 股权百分比
+- 投资实体
+
+---
+
+## 完整工作流:收益分析
+
+### 第 1 步:提取收益数据
+
+=== "CLI"
+
+ ```bash
+ he parse earnings_10k.md -t finance/earnings_summary -l zh -o ./earnings/
+ ```
+
+=== "Python"
+
+ ```python
+ from hyperextract import Template
+
+ # 加载报告
+ with open("earnings_report.md", "r") as f:
+ report = f.read()
+
+ # 创建模板
+ ka = Template.create("finance/earnings_summary", "zh")
+
+ # 提取
+ result = ka.parse(report)
+
+ # 访问数据
+ print(f"收入:${result.data.revenue:,.0f}")
+ print(f"EPS:${result.data.eps:.2f}")
+ print(f"同比增长:{result.data.yoy_growth}%")
+ ```
+
+**示例输出:**
+```python
+{
+ "revenue": 1234567890,
+ "net_income": 98765432,
+ "eps": 2.45,
+ "eps_diluted": 2.40,
+ "yoy_growth": 15.3,
+ "qoq_growth": 3.2,
+ "segments": [
+ {"name": "云服务", "revenue": 500000000},
+ {"name": "硬件", "revenue": 734567890}
+ ],
+ "guidance": {
+ "next_quarter_revenue": "¥8.5B - ¥9.5B",
+ "full_year_eps": "¥70.00 - ¥77.00"
+ }
+}
+```
+
+---
+
+### 第 2 步:提取风险因素
+
+> **注意:** 以下步骤假设您在第 1 步使用了 Python 方式。如果使用了 CLI,请使用 `ka.load("./earnings/")` 加载结果。
+
+```python
+# 提取风险
+risk_ka = Template.create("finance/risk_factor_set", "zh")
+risk_result = risk_ka.parse(report)
+
+print(f"\n识别了 {len(risk_result.data.items)} 个风险因素:")
+for risk in risk_result.data.items:
+ print(f"\n[{risk.category}] {risk.description[:100]}...")
+```
+
+---
+
+### 第 3 步:保存和比较
+
+```python
+# 保存收益数据
+result.dump("./earnings_q3_2024/")
+
+# 稍后比较季度
+from pathlib import Path
+import json
+
+def compare_quarters(q1_path, q2_path):
+ """比较两个季度的收益。"""
+ q1_data = json.load(open(Path(q1_path) / "data.json"))
+ q2_data = json.load(open(Path(q2_path) / "data.json"))
+
+ revenue_change = ((q2_data["revenue"] - q1_data["revenue"])
+ / q1_data["revenue"] * 100)
+
+ print(f"收入变化:{revenue_change:+.1f}%")
+ print(f"Q1:${q1_data['revenue']:,.0f}")
+ print(f"Q2:${q2_data['revenue']:,.0f}")
+
+compare_quarters("./earnings_q2_2024/", "./earnings_q3_2024/")
+```
+
+---
+
+## 股权结构分析
+
+### 提取企业结构
+
+```python
+from hyperextract import Template
+
+# 分析股权
+ka = Template.create("finance/ownership_graph", "zh")
+result = ka.parse(ownership_report)
+
+# 可视化结构
+result.build_index()
+result.show()
+
+# 查询股权
+response = result.chat("公司拥有哪些 100% 控股的子公司?")
+print(response.content)
+```
+
+**示例输出:**
+```python
+# 实体
+[
+ {"name": "母公司", "type": "控股公司"},
+ {"name": "子公司 A", "type": "子公司"},
+ {"name": "合资企业 B", "type": "合资企业"}
+]
+
+# 关系
+[
+ {"source": "母公司", "target": "子公司 A",
+ "type": "控股", "percentage": 100},
+ {"source": "母公司", "target": "合资企业 B",
+ "type": "控股", "percentage": 51}
+]
+```
+
+---
+
+## 财务事件时间线
+
+### 追踪财务事件
+
+```python
+# 提取事件时间线
+ka = Template.create("finance/event_timeline", "zh")
+result = ka.parse(report)
+
+# 显示时间线
+for edge in result.edges:
+ if hasattr(edge, 'time'):
+ print(f"{edge.time}:{edge.source} - {edge.type} - {edge.target}")
+```
+
+**示例事件:**
+- 产品发布
+- 收购公告
+- 股息声明
+- 管理层变动
+
+---
+
+## 对比表
+
+| 模板 | 最佳场景 | 输出 |
+|------|---------|------|
+| `earnings_summary` | 财务指标 | 结构化模型 |
+| `risk_factor_set` | 风险评估 | 唯一风险项目 |
+| `ownership_graph` | 企业结构 | 实体网络 |
+| `event_timeline` | 财务事件 | 时间线图谱 |
+| `sentiment_model` | 市场情绪 | 情感分析 |
+
+---
+
+## 批量处理多份报告
+
+```python
+"""批量处理财务报告。"""
+
+from hyperextract import Template
+from pathlib import Path
+import pandas as pd
+
+def batch_extract_reports(report_dir, output_dir):
+ """从多份财务报告中提取数据。"""
+
+ ka = Template.create("finance/earnings_summary", "zh")
+ results = []
+
+ for report_file in Path(report_dir).glob("*.md"):
+ print(f"处理 {report_file.name}...")
+
+ text = report_file.read_text()
+ result = ka.parse(text)
+
+ # 保存单个
+ output_path = Path(output_dir) / report_file.stem
+ result.dump(output_path)
+
+ # 收集聚合
+ results.append({
+ "file": report_file.name,
+ "revenue": result.data.revenue,
+ "eps": result.data.eps,
+ "yoy_growth": result.data.yoy_growth
+ })
+
+ # 创建汇总表
+ df = pd.DataFrame(results)
+ df.to_csv(Path(output_dir) / "summary.csv", index=False)
+
+ print(f"\n处理了 {len(results)} 份报告")
+ print(f"汇总保存到:{output_dir}/summary.csv")
+
+ return df
+
+# 用法
+df = batch_extract_reports("./reports/", "./extracted/")
+```
+
+---
+
+## 最佳实践技巧
+
+### 1. 文档类型
+
+| 文档 | 推荐模板 |
+|------|---------|
+| 10-K 年报 | `earnings_summary` + `risk_factor_set` |
+| 10-Q 季报 | `earnings_summary` |
+| 代理声明 | `ownership_graph` |
+| 财报电话会议记录 | `sentiment_model` + `event_timeline` |
+| 投资者演示 | `earnings_summary` |
+
+### 2. 语言支持
+
+=== "CLI"
+
+ ```bash
+ # 中国公司(中文财报)
+ he parse report.md -t finance/earnings_summary -l zh
+
+ # 美国公司(英文)
+ he parse report.md -t finance/earnings_summary -l en
+ ```
+
+### 3. 组合模板
+
+```python
+from hyperextract import Template
+
+# 用多个模板解析报告
+text = open("10k_report.md").read()
+
+# 提取收益
+earnings = Template.create("finance/earnings_summary", "zh").parse(text)
+
+# 提取风险
+risks = Template.create("finance/risk_factor_set", "zh").parse(text)
+
+# 保存组合
+earnings.dump("./10k_earnings/")
+risks.dump("./10k_risks/")
+```
+
+### 4. 数据验证
+
+```python
+# 检查提取的数据
+result = ka.parse(report)
+
+def validate_earnings(data):
+ """验证收益数据。"""
+ assert data.revenue > 0, "收入必须为正数"
+ assert data.eps is not None, "EPS 是必需的"
+ assert -100 < data.yoy_growth < 1000, "增长率似乎不合理"
+ print("✓ 数据验证通过")
+
+validate_earnings(result.data)
+```
+
+---
+
+## 另请参见
+
+- [按任务选择](../choosing/by-task.md) — 其他财务分析模板
+- [金融模板](../reference/finance.md) — 所有金融模板
+- [自定义模板指南](../../python/guides/custom-templates.md) — 创建自定义财务模板
diff --git a/docs/zh/templates/examples/legal-contract.md b/docs/zh/templates/examples/legal-contract.md
new file mode 100644
index 0000000..d745c34
--- /dev/null
+++ b/docs/zh/templates/examples/legal-contract.md
@@ -0,0 +1,429 @@
+# 法律文档分析
+
+从法律合同和案例文档中提取信息的完整指南。
+
+---
+
+## 场景
+
+您有一份法律文档,想要:
+- 提取合同义务和截止日期
+- 识别定义术语
+- 创建案例年表
+- 映射先例关系
+
+---
+
+## 按任务推荐模板
+
+### 合同义务
+
+**模板:** `legal/contract_obligation`
+
+最适合服务协议、保密协议、雇佣合同、供应商协议。
+
+**提取内容:**
+- 当事人义务
+- 截止日期和里程碑
+- 交付物
+- 先决条件
+- 违约后果
+
+---
+
+### 定义术语 {#defined-terms}
+
+**模板:** `legal/defined_term_set`
+
+最适合从合同中提取所有大写的定义术语。
+
+**提取内容:**
+- 术语定义
+- 交叉引用
+- 定义位置
+
+---
+
+### 案例时间线 {#case-timeline}
+
+**模板:** `legal/case_fact_timeline`
+
+最适合诉讼年表、案例摘要。
+
+**提取内容:**
+- 时序事件
+- 当事人行为
+- 法院判决
+
+---
+
+## 完整工作流:合同分析
+
+### 第 1 步:提取义务
+
+=== "CLI"
+
+ ```bash
+ he parse contract.md -t legal/contract_obligation -l zh -o ./contract/
+ ```
+
+=== "Python"
+
+ ```python
+ from hyperextract import Template
+
+ # 加载合同
+ with open("service_agreement.md", "r") as f:
+ contract = f.read()
+
+ # 创建模板
+ ka = Template.create("legal/contract_obligation", "zh")
+
+ # 提取
+ result = ka.parse(contract)
+
+ print(f"找到 {len(result.data.items)} 个义务")
+ ```
+
+**示例输出:**
+```python
+{
+ "items": [
+ {
+ "party": "服务提供商",
+ "obligation": "30 天内交付软件模块",
+ "deadline": "2024-03-15",
+ "deliverable": "源代码和文档",
+ "conditions": "收到付款后"
+ },
+ {
+ "party": "客户",
+ "obligation": "支付里程碑款项",
+ "deadline": "2024-03-01",
+ "amount": "¥350,000",
+ "conditions": "交付物验收后"
+ }
+ ]
+}
+```
+
+---
+
+### 第 2 步:提取定义术语
+
+> **注意:** 以下步骤假设您在第 1 步使用了 Python 方式。如果使用了 CLI,请使用 `ka.load("./contract/")` 加载结果。
+
+```python
+# 提取定义术语
+terms_ka = Template.create("legal/defined_term_set", "zh")
+terms_result = terms_ka.parse(contract)
+
+print(f"\n找到 {len(terms_result.data.items)} 个定义术语:")
+for term in terms_result.data.items:
+ print(f"\n{term.term}:{term.definition}")
+```
+
+**示例:**
+```
+"保密信息":所有非公开、专有或机密信息...
+
+"交付物":要交付的软件、文档和材料...
+
+"生效日期":上方首次书写的日期...
+```
+
+---
+
+### 第 3 步:构建合同知识库
+
+```python
+# 构建查询索引
+result.build_index()
+
+# 保存供将来参考
+result.dump("./contract_analysis/")
+
+# 查询义务
+response = result.chat("服务提供商在数据安全方面有哪些义务?")
+print(response.content)
+
+response = result.chat("列出所有付款里程碑及其到期日")
+print(response.content)
+```
+
+---
+
+## 案例分析工作流
+
+### 提取案例时间线
+
+```python
+from hyperextract import Template
+
+# 加载案例文档
+with open("case_summary.md", "r") as f:
+ case = f.read()
+
+# 提取时间线
+ka = Template.create("legal/case_fact_timeline", "zh")
+result = ka.parse(case)
+
+# 显示年表
+print("案例时间线:")
+for edge in sorted(result.edges, key=lambda e: e.time if hasattr(e, 'time') else ''):
+ if hasattr(edge, 'time'):
+ print(f"\n{edge.time}:")
+ print(f" 事件:{edge.source}")
+ print(f" 行为:{edge.type}")
+ print(f" 当事人:{edge.target}")
+
+# 可视化
+result.build_index()
+result.show()
+```
+
+**示例输出:**
+```
+2023-01-15:
+ 事件:提起诉讼
+ 行为:发起
+ 当事人:原告
+
+2023-02-01:
+ 事件:驳回动议
+ 行为:提交
+ 当事人:被告
+
+2023-03-15:
+ 事件:证据开示阶段
+ 行为:开始
+ 当事人:双方
+```
+
+---
+
+## 案例先例分析
+
+### 映射先例关系
+
+```python
+# 提取案例引用
+ka = Template.create("legal/case_citation", "zh")
+result = ka.parse(legal_opinion)
+
+# 分析引用网络
+print("引用的案例:")
+for node in result.nodes:
+ if node.type == "案例":
+ print(f" - {node.name} ({node.citation})")
+ print(f" 原则:{node.principle[:100]}...")
+
+# 可视化先例网络
+result.build_index()
+result.show()
+```
+
+---
+
+## 对比表
+
+| 模板 | 最佳场景 | 输出 |
+|------|---------|------|
+| `contract_obligation` | 服务协议、保密协议 | 义务列表 |
+| `defined_term_set` | 定义术语提取 | 术语定义集合 |
+| `case_fact_timeline` | 诉讼年表 | 时间线图谱 |
+| `case_citation` | 先例分析 | 引用网络 |
+| `compliance_list` | 监管要求 | 合规清单 |
+
+---
+
+## 批量合同处理
+
+```python
+"""批量分析多个合同。"""
+
+from hyperextract import Template
+from pathlib import Path
+import pandas as pd
+
+def analyze_contract_folder(folder_path, output_dir):
+ """从文件夹中所有合同提取义务。"""
+
+ ka = Template.create("legal/contract_obligation", "zh")
+ all_obligations = []
+
+ for contract_file in Path(folder_path).glob("*.md"):
+ print(f"处理 {contract_file.name}...")
+
+ text = contract_file.read_text()
+ result = ka.parse(text)
+
+ # 保存单个
+ output_path = Path(output_dir) / contract_file.stem
+ result.dump(output_path)
+
+ # 收集义务
+ for obl in result.data.items:
+ all_obligations.append({
+ "contract": contract_file.name,
+ "party": obl.party,
+ "obligation": obl.obligation,
+ "deadline": getattr(obl, 'deadline', 'N/A'),
+ "deliverable": getattr(obl, 'deliverable', 'N/A')
+ })
+
+ # 创建汇总
+ df = pd.DataFrame(all_obligations)
+ df.to_csv(Path(output_dir) / "all_obligations.csv", index=False)
+
+ print(f"\n处理了 {len(list(Path(folder_path).glob('*.md')))} 个合同")
+ print(f"找到 {len(all_obligations)} 个总义务")
+
+ return df
+
+# 用法
+df = analyze_contract_folder("./contracts/", "./contract_analysis/")
+
+# 查找即将到期的截止日期
+from datetime import datetime
+df['deadline'] = pd.to_datetime(df['deadline'], errors='coerce')
+upcoming = df[df['deadline'] > datetime.now()].sort_values('deadline')
+print("\n即将到期的截止日期:")
+print(upcoming[['contract', 'party', 'deadline', 'obligation']].head(10))
+```
+
+---
+
+## 最佳实践技巧
+
+### 1. 文档准备
+
+- 将 PDF 转换为干净的 Markdown
+- 移除页眉/页脚/页码
+- 保留段落结构
+- 保留章节标题
+
+### 2. 合同类型
+
+| 合同类型 | 主要模板 | 次要模板 |
+|---------|---------|---------|
+| 服务协议 | `contract_obligation` | `defined_term_set` |
+| 保密协议 | `contract_obligation` | `defined_term_set` |
+| 雇佣合同 | `contract_obligation` | `defined_term_set` |
+| 许可协议 | `contract_obligation` | `defined_term_set` |
+| 诉讼摘要 | `case_fact_timeline` | `case_citation` |
+| 监管文档 | `compliance_list` | - |
+
+### 3. 多语言支持
+
+=== "CLI"
+
+ ```bash
+ # 中文合同
+ he parse contract.md -t legal/contract_obligation -l zh
+
+ # 英文合同
+ he parse contract.md -t legal/contract_obligation -l en
+ ```
+
+### 4. 组合模板
+
+```python
+# 全面合同分析
+text = open("contract.md").read()
+
+# 提取义务
+obligations = Template.create("legal/contract_obligation", "zh").parse(text)
+
+# 提取定义术语
+terms = Template.create("legal/defined_term_set", "zh").parse(text)
+
+# 保存两者
+obligations.dump("./contract_obligations/")
+terms.dump("./contract_terms/")
+
+# 交叉引用
+print("\n引用定义术语的义务:")
+for obl in obligations.data.items:
+ for term in terms.data.items:
+ if term.term.lower() in obl.obligation.lower():
+ print(f" '{term.term}' 在:{obl.obligation[:60]}...")
+```
+
+---
+
+## 示例:合同审查清单
+
+```python
+"""自动化合同审查清单。"""
+
+from hyperextract import Template
+from datetime import datetime
+
+def contract_review_checklist(contract_path):
+ """从合同生成审查清单。"""
+
+ text = open(contract_path).read()
+
+ # 提取义务
+ obl_ka = Template.create("legal/contract_obligation", "zh")
+ obl_result = obl_ka.parse(text)
+
+ # 提取术语
+ terms_ka = Template.create("legal/defined_term_set", "zh")
+ terms_result = terms_ka.parse(text)
+
+ print("=" * 60)
+ print("合同审查清单")
+ print("=" * 60)
+
+ # 义务摘要
+ print("\n## 义务摘要")
+ print(f"总义务数:{len(obl_result.data.items)}")
+
+ party_obligations = {}
+ for obl in obl_result.data.items:
+ party = obl.party
+ if party not in party_obligations:
+ party_obligations[party] = []
+ party_obligations[party].append(obl)
+
+ for party, obligations in party_obligations.items():
+ print(f"\n{party}:{len(obligations)} 个义务")
+ for obl in obligations[:3]: # 显示前 3 个
+ deadline = getattr(obl, 'deadline', '无截止日期')
+ print(f" - {obl.obligation[:50]}... (到期:{deadline})")
+
+ # 关键日期
+ print("\n## 关键日期")
+ deadlines = [obl.deadline for obl in obl_result.data.items
+ if hasattr(obl, 'deadline') and obl.deadline]
+ for deadline in sorted(deadlines)[:5]:
+ print(f" - {deadline}")
+
+ # 关键术语
+ print("\n## 关键定义术语")
+ for term in terms_result.data.items[:10]:
+ print(f" - {term.term}")
+
+ # 风险标记
+ print("\n## 需审查的风险标记")
+ risk_keywords = ['无限', '永久', '唯一酌情权', '放弃', '赔偿']
+ for obl in obl_result.data.items:
+ for keyword in risk_keywords:
+ if keyword in obl.obligation:
+ print(f" ⚠ 包含'{keyword}':{obl.obligation[:60]}...")
+
+ print("\n" + "=" * 60)
+
+# 用法
+contract_review_checklist("service_agreement.md")
+```
+
+---
+
+## 另请参见
+
+- [按任务选择](../choosing/by-task.md) — 其他法律分析模板
+- [法律模板](../reference/legal.md) — 所有法律模板
+- [自定义模板指南](../../python/guides/custom-templates.md) — 创建自定义法律模板
diff --git a/docs/zh/templates/examples/research-paper.md b/docs/zh/templates/examples/research-paper.md
new file mode 100644
index 0000000..0d9bc68
--- /dev/null
+++ b/docs/zh/templates/examples/research-paper.md
@@ -0,0 +1,332 @@
+# 研究论文分析
+
+从研究论文中提取知识的完整指南。
+
+---
+
+## 场景
+
+您有一篇研究论文,想要:
+- 提取关键概念及其定义
+- 映射概念之间的关系
+- 构建可查询的知识库
+- 可视化概念网络
+
+---
+
+## 推荐模板
+
+### `general/concept_graph`
+
+最适合从学术论文中提取概念、方法及其关系。
+
+**为什么选这个模板?**
+- 自动识别关键概念
+- 映射 "is-a"、"uses"、"relates-to" 关系
+- 支持层次结构
+- 针对学术语言优化
+
+---
+
+## 完整工作流
+
+### 第 1 步:提取知识
+
+=== "CLI"
+
+ ```bash
+ he parse paper.md -t general/concept_graph -l zh -o ./paper_kb/
+ ```
+
+=== "Python"
+
+ ```python
+ from hyperextract import Template
+
+ # 加载论文
+ with open("paper.md", "r") as f:
+ paper_text = f.read()
+
+ # 创建模板
+ ka = Template.create("general/concept_graph", "zh")
+
+ # 提取
+ result = ka.parse(paper_text)
+
+ print(f"提取了 {len(result.nodes)} 个概念")
+ print(f"提取了 {len(result.edges)} 个关系")
+ ```
+
+**示例输出:**
+```python
+{
+ "entities": [
+ {"name": "Transformer", "type": "模型"},
+ {"name": "注意力机制", "type": "概念"},
+ {"name": "BLEU 分数", "type": "指标"}
+ ],
+ "relations": [
+ {"source": "Transformer", "target": "注意力机制", "type": "使用"},
+ {"source": "Transformer", "target": "BLEU 分数", "type": "达成"}
+ ]
+}
+```
+
+---
+
+### 第 2 步:探索结果
+
+> **注意:** 以下步骤假设您在第 1 步使用了 Python 方式。如果使用了 CLI,请使用 `ka.load("./paper_kb/")` 加载结果。
+
+```python
+# 列出所有概念
+print("\n发现的概念:")
+for node in result.nodes:
+ print(f" - {node.name} ({node.type})")
+ if hasattr(node, 'description'):
+ print(f" {node.description[:100]}...")
+
+# 列出关系
+print("\n关系:")
+for edge in result.edges:
+ print(f" - {edge.source} → {edge.target}: {edge.type}")
+```
+
+**示例输出:**
+```
+发现的概念:
+ - Transformer (架构)
+ 基于自注意力机制的神经网络架构...
+ - 注意力机制 (方法)
+ 允许模型关注输入相关部分的技术...
+ - BERT (模型)
+ 双向编码器表示...
+
+关系:
+ - BERT → Transformer: 实现
+ - Transformer → 注意力机制: 使用
+ - BERT → NLP: 应用于
+```
+
+---
+
+### 第 3 步:构建可搜索索引
+
+```python
+# 为搜索和对话构建索引
+result.build_index()
+
+# 保存供以后使用
+result.dump("./paper_kb/")
+```
+
+---
+
+### 第 4 步:可视化
+
+```python
+# 打开交互式可视化
+result.show()
+```
+
+这将打开交互式浏览器视图,您可以在其中:
+- 可视化探索概念图
+- 搜索特定概念
+- 询问论文相关问题
+
+---
+
+### 第 5 步:查询
+
+```python
+# 语义搜索
+nodes, edges = result.search("注意力机制", top_k=5)
+
+print("相关概念:")
+for node in nodes:
+ print(f" - {node.name}")
+
+# 对话界面
+response = result.chat("这篇论文的主要贡献是什么?")
+print(response.content)
+
+response = result.chat("提出的方法与之前的方法相比如何?")
+print(response.content)
+```
+
+---
+
+## 替代模板
+
+### 文档结构 {#document-structure}
+
+如果您需要论文的大纲和结构:
+
+=== "CLI"
+
+ ```bash
+ he parse paper.md -t general/doc_structure -l zh -o ./structure/
+ ```
+
+**提取内容:**
+- 章节标题
+- 每节要点
+- 论文组织
+
+### 知识图谱 {#knowledge-graph}
+
+用于超越单纯概念的更广泛领域知识:
+
+=== "CLI"
+
+ ```bash
+ he parse paper.md -t general/graph -l zh -o ./knowledge/
+ ```
+
+**与 concept_graph 的区别:**
+- 更广泛的实体类型(人物、组织、方法)
+- 一般关系
+- 较少关注概念定义
+
+### 工作流图谱
+
+如果论文描述了一个过程或算法:
+
+=== "CLI"
+
+ ```bash
+ he parse paper.md -t general/workflow_graph -l zh -o ./workflow/
+ ```
+
+**提取内容:**
+- 过程步骤
+- 决策点
+- 流程关系
+
+---
+
+## 对比表
+
+| 模板 | 最佳场景 | 输出 |
+|------|---------|------|
+| `concept_graph` | 有概念/定义的研究论文 | 概念网络 |
+| `graph` | 更广泛的领域知识 | 通用实体网络 |
+| `doc_structure` | 文档大纲 | 层次结构 |
+| `workflow_graph` | 过程/方法描述 | 流程图 |
+
+---
+
+## 最佳实践技巧
+
+### 1. 文档准备
+
+- 移除页眉/页脚
+- 确保干净的 Markdown 或纯文本
+- 保持方程式为 LaTeX 或纯文本
+
+### 2. 语言选择
+
+=== "CLI"
+
+ ```bash
+ # 中文论文
+ he parse paper.md -t general/concept_graph -l zh
+
+ # 英文论文
+ he parse paper.md -t general/concept_graph -l en
+ ```
+
+### 3. 处理长论文
+
+对于超过 5000 词的论文:
+
+```python
+# 选项 1:使用 RAG 方法
+ka = Template.create("method/graph_rag")
+result = ka.parse(paper_text)
+
+# 选项 2:按章节处理
+sections = split_paper_into_sections(paper_text)
+ka = Template.create("general/concept_graph", "zh")
+result = ka.parse(sections[0])
+
+for section in sections[1:]:
+ result.feed_text(section)
+```
+
+### 4. 后处理
+
+```python
+# 按概念类型筛选
+concepts = [n for n in result.nodes if n.type == "概念"]
+methods = [n for n in result.nodes if n.type == "方法"]
+
+# 查找中心概念(连接最多的)
+from collections import Counter
+edge_counts = Counter([e.source for e in result.edges] +
+ [e.target for e in result.edges])
+top_concepts = edge_counts.most_common(5)
+```
+
+---
+
+## 示例:完整分析脚本
+
+```python
+"""完整的研究论文分析工作流。"""
+
+from hyperextract import Template
+from pathlib import Path
+
+def analyze_paper(paper_path, output_dir="./paper_analysis/"):
+ """分析研究论文并创建知识库。"""
+
+ # 加载论文
+ text = Path(paper_path).read_text()
+
+ # 提取概念
+ print("提取概念中...")
+ ka = Template.create("general/concept_graph", "zh")
+ result = ka.parse(text)
+
+ print(f"找到 {len(result.nodes)} 个概念")
+ print(f"找到 {len(result.edges)} 个关系")
+
+ # 构建索引
+ print("构建搜索索引...")
+ result.build_index()
+
+ # 保存
+ output_path = Path(output_dir)
+ output_path.mkdir(parents=True, exist_ok=True)
+ result.dump(output_path)
+
+ # 生成摘要
+ print("\n=== 论文摘要 ===")
+ response = result.chat("用三句话总结主要贡献")
+ print(response.content)
+
+ print("\n=== 关键概念 ===")
+ for node in result.nodes[:5]:
+ print(f"- {node.name}")
+
+ print(f"\n保存到:{output_path}")
+ print(f"\n要探索:result.show()")
+
+ return result
+
+# 用法
+if __name__ == "__main__":
+ result = analyze_paper("paper.md")
+
+ # 交互式探索
+ result.show()
+```
+
+---
+
+## 另请参见
+
+- [按任务选择](../choosing/by-task.md) — 其他任务模板
+- [概念图谱模板](../reference/general.md) — 模板详情
+- [Python 快速入门](../../python/quickstart.md) — Python SDK 入门
diff --git a/docs/zh/templates/how-to-choose.md b/docs/zh/templates/how-to-choose.md
index 7fa8498..a7f4766 100644
--- a/docs/zh/templates/how-to-choose.md
+++ b/docs/zh/templates/how-to-choose.md
@@ -33,12 +33,12 @@ graph TD
| 模板 | 输出 | 最适合 |
|------|------|--------|
-| `general/biography_graph` | 时序图谱 | 生平故事、个人简介 |
-| `general/base_model` | 模型 | 人物摘要 |
+| `general/biography_graph` | 图谱(时序) | 生平故事、个人简介 |
+| `general/model` | 模型 | 人物摘要 |
**示例:**
```bash
-he parse bio.md -t general/biography_graph -l en -o ./out/
+he parse bio.md -t general/biography_graph -l zh -o ./out/
```
### 研究与文档
@@ -46,7 +46,7 @@ he parse bio.md -t general/biography_graph -l en -o ./out/
| 模板 | 输出 | 最适合 |
|------|------|--------|
| `general/concept_graph` | 图谱 | 研究论文 |
-| `general/knowledge_graph` | 图谱 | 技术文档 |
+| `general/graph` | 图谱 | 技术文档 |
| `general/doc_structure` | 模型 | 文档大纲 |
### 金融
@@ -55,7 +55,7 @@ he parse bio.md -t general/biography_graph -l en -o ./out/
|------|------|--------|
| `finance/earnings_summary` | 模型 | 财报 |
| `finance/ownership_graph` | 图谱 | 公司结构 |
-| `finance/event_timeline` | 时序 | 金融事件 |
+| `finance/event_timeline` | 图谱(时序) | 金融事件 |
| `finance/risk_factor_set` | 集合 | 风险评估 |
### 法律
@@ -64,7 +64,7 @@ he parse bio.md -t general/biography_graph -l en -o ./out/
|------|------|--------|
| `legal/contract_obligation` | 列表 | 合同条款 |
| `legal/case_citation` | 图谱 | 法律先例 |
-| `legal/case_fact_timeline` | 时序 | 案件时间线 |
+| `legal/case_fact_timeline` | 图谱(时序) | 案件时间线 |
### 医疗
@@ -82,50 +82,50 @@ he parse bio.md -t general/biography_graph -l en -o ./out/
```python
# 财务摘要
-ka = Template.create("finance/earnings_summary", "en")
+ka = Template.create("finance/earnings_summary", "zh")
# 患者出院
-ka = Template.create("medicine/discharge_instruction", "en")
+ka = Template.create("medicine/discharge_instruction", "zh")
```
### 我需要列表 → AutoList
```python
# 合规清单
-ka = Template.create("legal/compliance_list", "en")
+ka = Template.create("legal/compliance_list", "zh")
# 症状
-ka = Template.create("medicine/symptom_list", "en")
+ka = Template.create("medicine/symptom_list", "zh")
```
### 我需要唯一项目 → AutoSet
```python
# 风险因素
-ka = Template.create("finance/risk_factor_set", "en")
+ka = Template.create("finance/risk_factor_set", "zh")
# 关键术语
-ka = Template.create("legal/defined_term_set", "en")
+ka = Template.create("legal/defined_term_set", "zh")
```
### 我需要网络 → AutoGraph
```python
# 通用知识
-ka = Template.create("general/knowledge_graph", "en")
+ka = Template.create("general/graph", "zh")
# 公司所有权
-ka = Template.create("finance/ownership_graph", "en")
+ka = Template.create("finance/ownership_graph", "zh")
```
### 我需要时间线 → AutoTemporalGraph
```python
# 传记
-ka = Template.create("general/biography_graph", "en")
+ka = Template.create("general/biography_graph", "zh")
# 事件序列
-ka = Template.create("finance/event_timeline", "en")
+ka = Template.create("finance/event_timeline", "zh")
```
---
@@ -137,7 +137,7 @@ ka = Template.create("finance/event_timeline", "en")
所有模板都支持英文:
```bash
-he parse doc.md -t general/biography_graph -l en
+he parse doc.md -t general/biography_graph -l zh
```
### 中文文档
@@ -183,7 +183,7 @@ he parse doc.md -t general/biography_graph -l zh
**解决方案:**
```bash
-he parse paper.md -t general/concept_graph -l en -o ./paper_kb/
+he parse paper.md -t general/concept_graph -l zh -o ./paper_kb/
```
### 场景 2:财务报告
@@ -192,7 +192,7 @@ he parse paper.md -t general/concept_graph -l en -o ./paper_kb/
**解决方案:**
```bash
-he parse 10k.md -t finance/earnings_summary -l en -o ./earnings/
+he parse 10k.md -t finance/earnings_summary -l zh -o ./earnings/
```
### 场景 3:法律合同
@@ -201,7 +201,7 @@ he parse 10k.md -t finance/earnings_summary -l en -o ./earnings/
**解决方案:**
```bash
-he parse contract.md -t legal/contract_obligation -l en -o ./contract/
+he parse contract.md -t legal/contract_obligation -l zh -o ./contract/
```
### 场景 4:医疗案例
@@ -210,7 +210,7 @@ he parse contract.md -t legal/contract_obligation -l en -o ./contract/
**解决方案:**
```bash
-he parse case.md -t medicine/hospital_timeline -l en -o ./case/
+he parse case.md -t medicine/hospital_timeline -l zh -o ./case/
```
---
@@ -227,7 +227,7 @@ ka = Template.create("method/graph_rag")
ka = Template.create("method/itext2kg")
```
-→ [选择方法](../python/guides/choosing-methods.md)
+→ [使用方法](../python/guides/using-methods.md)
---
@@ -259,6 +259,6 @@ print(cfg.description)
## 参见
-- [浏览所有模板](browse.md)
+- [模板概览](reference/overview.md)
- [模板库](index.md)
- [自定义模板](../python/guides/custom-templates.md)
diff --git a/docs/zh/templates/index.md b/docs/zh/templates/index.md
index 1560f79..c9936dd 100644
--- a/docs/zh/templates/index.md
+++ b/docs/zh/templates/index.md
@@ -1,211 +1,141 @@
# 模板库
-浏览并选择 80+ 个领域特定的提取模板。
+根据您的任务选择合适的模板。
---
-## 什么是模板?
-
-模板是预先配置的提取设置,包含:
-- **自动类型** — 输出数据结构
-- **提示词** — 针对特定领域优化
-- **模式** — 用例的字段定义
-- **指南** — 提取规则
-
----
-
-## 模板类别
+## 我要分析...
<div class="grid cards" markdown>
-- :material-folder:{ .lg .middle } __通用__
+- :material-file-document:{ .lg .middle } **研究论文**
---
- 基础类型和常见提取任务
-
- - 传记图谱
- - 知识图谱
- - 概念提取
-
- [:octicons-arrow-right-24: 浏览](general/index.md)
+ 提取概念、方法、结论及关系
+
+ - [概念图谱](examples/research-paper.md) — *推荐*
+ - [知识图谱](examples/research-paper.md#knowledge-graph)
+ - [文档结构](examples/research-paper.md#document-structure)
-- :material-chart-line:{ .lg .middle } __金融__
+- :material-account:{ .lg .middle } **人物传记**
---
- 金融文档分析
-
- - 财报摘要
- - 风险因素
- - 股权结构
-
- [:octicons-arrow-right-24: 浏览](finance.md)
+ 提取生平事件、关系和时间线
-- :material-scale-balance:{ .lg .middle } __法律__
+ - [传记图谱](reference/general.md) — *推荐*
+ - [人物摘要](reference/general.md)
+
+- :material-chart-line:{ .lg .middle } **财务报告**
---
- 法律文档处理
-
- - 合同义务
- - 案例引用
- - 合规清单
-
- [:octicons-arrow-right-24: 浏览](legal.md)
+ 提取财务指标、风险因素、股权结构
+
+ - [财报摘要](examples/financial-report.md) — *推荐*
+ - [风险因素](examples/financial-report.md#risk-factors)
+ - [股权图谱](examples/financial-report.md#ownership-structure)
-- :material-hospital:{ .lg .middle } __医疗__
+- :material-scale-balance:{ .lg .middle } **法律文档**
---
- 医学文本分析
-
- - 解剖图谱
- - 药物相互作用
- - 治疗方案
-
- [:octicons-arrow-right-24: 浏览](medicine.md)
+ 提取义务条款、案例、合规项
-- :material-leaf:{ .lg .middle } __中医__
+ - [合同义务](examples/legal-contract.md) — *推荐*
+ - [案例时间线](examples/legal-contract.md#case-timeline)
+ - [定义术语](examples/legal-contract.md#defined-terms)
+
+- :material-hospital:{ .lg .middle } **医疗记录**
---
- 中医药
-
- - 草药属性
- - 方剂组成
- - 经络图谱
-
- [:octicons-arrow-right-24: 浏览](tcm.md)
+ 提取症状、治疗方案和时间线
+
+ - [住院时间线](reference/medicine.md) — *推荐*
+ - [药物相互作用](reference/medicine.md)
+ - [出院摘要](reference/medicine.md)
-- :material-factory:{ .lg .middle } __工业__
+- :material-leaf:{ .lg .middle } **中医文献**
---
- 工业文档
-
- - 设备拓扑
- - 安全控制
- - 操作流程
-
- [:octicons-arrow-right-24: 浏览](industry.md)
+ 提取草药属性和方剂组成
-</div>
+ - [草药属性](reference/tcm.md) — *推荐*
+ - [方剂组成](reference/tcm.md)
+ - [经络图谱](reference/tcm.md)
----
+- :material-factory:{ .lg .middle } **工业文档**
-## 快速选择指南
+ ---
-| 我想提取... | 使用模板 |
-|------------|---------|
-| 人物生平 | `general/biography_graph` |
-| 研究论文概念 | `general/concept_graph` |
-| 公司财报 | `finance/earnings_summary` |
-| 合同条款 | `legal/contract_obligation` |
-| 医疗症状 | `medicine/symptom_list` |
-| 中草药 | `tcm/herb_property` |
-| 设备规格 | `industry/equipment_topology` |
+ 提取设备、安全和操作流程
+
+ - [设备拓扑](reference/industry.md) — *推荐*
+ - [安全控制](reference/industry.md)
+ - [操作流程](reference/industry.md)
+
+</div>
---
-## 如何选择
+## 不确定用什么?
-### 按文档类型
+**按任务类型:**
-| 文档 | 模板类别 |
+| 任务 | 推荐模板 |
|------|---------|
-| 传记、简介 | 通用 |
-| 财报、10-K | 金融 |
-| 合同、法律摘要 | 法律 |
-| 医疗记录、论文 | 医疗 |
-| 中医药文本、处方 | 中医 |
-| 手册、流程 | 工业 |
+| 文档摘要 | `general/model` |
+| 提取列表 | `general/list` |
+| 构建知识网络 | `general/graph` |
+| 创建时间线 | `general/base_temporal_graph` |
+
+→ [更多任务指南](choosing/by-task.md)
-### 按输出类型
+**按输出类型:**
-| 需求 | 自动类型 | 示例模板 |
+| 输出 | 自动类型 | 适用场景 |
|------|---------|---------|
-| 摘要报告 | AutoModel | `earnings_summary`, `discharge_instruction` |
-| 项目列表 | AutoList | `compliance_list`, `symptom_list` |
-| 唯一项目 | AutoSet | `risk_factor_set`, `defined_term_set` |
-| 网络/图谱 | AutoGraph | `knowledge_graph`, `ownership_graph` |
-| 时间线 | AutoTemporalGraph | `event_timeline`, `biography_graph` |
+| 结构化摘要 | AutoModel | 需要报告 |
+| 网络/图谱 | AutoGraph | 需要关系 |
+| 时间线 | AutoTemporalGraph | 需要时序 |
-→ [完整选择指南](how-to-choose.md)
+→ [更多输出类型指南](choosing/by-output.md)
---
-## 使用模板
-
-### CLI
+## 快速开始
```bash
-# 列出可用模板
+# 列出所有模板
he list template
# 使用模板
-he parse doc.md -t general/biography_graph -o ./out/ -l en
-```
-
-### Python
-
-```python
-from hyperextract import Template
-
-# 从预设创建
-ka = Template.create("general/biography_graph", "en")
-
-# 列出所有
-all_templates = Template.list()
-
-# 按领域筛选
-finance = Template.list(filter_by_tag="finance")
+he parse document.md -t general/biography_graph -l zh -o ./output/
```
----
-
-## 模板属性
-
-每个模板包含:
-
-- **名称** — 唯一标识符
-- **类型** — 自动类型(graph、list、model 等)
-- **标签** — 领域分类
-- **语言** — 支持的语言(zh、en)
-- **描述** — 提取内容的说明
-
-### 查看模板详情
-
```python
from hyperextract import Template
-# 获取模板信息
-cfg = Template.get("general/biography_graph")
+# 创建模板
+ka = Template.create("general/biography_graph", "zh")
-print(cfg.name) # biography_graph
-print(cfg.type) # temporal_graph
-print(cfg.tags) # ['general', 'biography']
-print(cfg.description) # 描述文本
+# 提取
+result = ka.parse(text)
```
---
## 浏览所有模板
-→ [完整模板浏览器](browse.md)
+→ [完整模板参考](reference/overview.md)
---
## 创建自定义模板
-需要特定的功能?创建您自己的模板:
-
-→ [自定义模板指南](../python/guides/custom-templates.md)
-
----
-
-## 模板格式参考
-
-了解 YAML 结构:
+需要特定功能?学习创建自己的模板:
-→ [模板格式](../concepts/templates-format.md)
+→ [自定义模板指南](../../python/guides/custom-templates.md)
diff --git a/docs/zh/templates/finance.md b/docs/zh/templates/reference/finance.md
similarity index 60%
rename from docs/zh/templates/finance.md
rename to docs/zh/templates/reference/finance.md
index ddc9b14..fbc2ac9 100644
--- a/docs/zh/templates/finance.md
+++ b/docs/zh/templates/reference/finance.md
@@ -24,6 +24,7 @@
- 财报电话会议记录
**字段**:
+
| 字段 | 类型 | 描述 |
|------|------|------|
| `company_name` | str | 公司名称 |
@@ -33,19 +34,21 @@
| `eps` | float | 每股收益 |
| `yoy_growth` | float | 同比增长率 |
-**示例:**
-```bash
-he parse 10q.md -t finance/earnings_summary -l en
-```
+=== "CLI"
-**Python:**
-```python
-ka = Template.create("finance/earnings_summary", "en")
-result = ka.parse(earnings_text)
+ ```bash
+ he parse 10q.md -t finance/earnings_summary -l zh
+ ```
-print(f"收入: ${result.data.revenue}B")
-print(f"EPS: ${result.data.eps}")
-```
+=== "Python"
+
+ ```python
+ ka = Template.create("finance/earnings_summary", "zh")
+ result = ka.parse(earnings_text)
+
+ print(f"收入: ${result.data.revenue}B")
+ print(f"EPS: ${result.data.eps}")
+ ```
---
@@ -70,18 +73,23 @@ print(f"EPS: ${result.data.eps}")
- `controls` — 控制关系
- `subsidiary_of` — 子公司关系
-**示例:**
-```bash
-he parse proxy.md -t finance/ownership_graph -l en
-```
+=== "CLI"
-**可视化:**
-```python
-# 构建索引以支持可视化中的交互式搜索/对话
-result.build_index()
+ ```bash
+ he parse proxy.md -t finance/ownership_graph -l zh
+ ```
-result.show() # 显示带有交互功能的所有权网络
-```
+=== "Python"
+
+ ```python
+ ka = Template.create("finance/ownership_graph", "zh")
+ result = ka.parse(proxy_statement)
+
+ # 构建索引以支持可视化中的交互式搜索/对话
+ result.build_index()
+
+ result.show() # 显示带有交互功能的所有权网络
+ ```
---
@@ -101,10 +109,22 @@ result.show() # 显示带有交互功能的所有权网络
- 事件类型(合并、收购、IPO 等)
- 相关实体
-**示例:**
-```bash
-he parse history.md -t finance/event_timeline -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse history.md -t finance/event_timeline -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("finance/event_timeline", "zh")
+ result = ka.parse(history_text)
+
+ print(f"事件数: {len(result.nodes)}")
+ for node in result.nodes:
+ print(f" - {node.name}")
+ ```
---
@@ -119,22 +139,22 @@ he parse history.md -t finance/event_timeline -l en
- 尽职调查报告
- 风险评估
-**示例:**
-```bash
-he parse 10k.md -t finance/risk_factor_set -l en
-```
+=== "CLI"
-**输出:**
-```python
-{
- "items": [
- "市场波动",
- "监管变化",
- "竞争",
- "供应链风险"
- ]
-}
-```
+ ```bash
+ he parse 10k.md -t finance/risk_factor_set -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("finance/risk_factor_set", "zh")
+ result = ka.parse(risk_section)
+
+ print(f"发现 {len(result.data.items)} 个风险因素")
+ for risk in result.data.items:
+ print(f" - {risk}")
+ ```
---
@@ -150,16 +170,30 @@ he parse 10k.md -t finance/risk_factor_set -l en
- 社交媒体情感
**字段**:
+
| 字段 | 类型 | 描述 |
|------|------|------|
| `sentiment` | str | 整体情感(正面/负面/中性) |
| `confidence` | float | 置信度分数 |
| `key_points` | list[str] | 关键情感指标 |
-**示例:**
-```bash
-he parse article.md -t finance/sentiment_model -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse article.md -t finance/sentiment_model -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("finance/sentiment_model", "zh")
+ result = ka.parse(article_text)
+
+ print(f"情感: {result.data.sentiment}")
+ print(f"置信度: {result.data.confidence}")
+ for point in result.data.key_points:
+ print(f" - {point}")
+ ```
---
@@ -171,7 +205,7 @@ he parse article.md -t finance/sentiment_model -l en
from hyperextract import Template
# 提取财报
-ka = Template.create("finance/earnings_summary", "en")
+ka = Template.create("finance/earnings_summary", "zh")
q1 = ka.parse(q1_report)
q2 = ka.parse(q2_report)
@@ -184,7 +218,7 @@ print(f"增长: {(q2.data.revenue - q1.data.revenue) / q1.data.revenue * 100:.1f
### 用例 2:股权结构
```python
-ka = Template.create("finance/ownership_graph", "en")
+ka = Template.create("finance/ownership_graph", "zh")
ownership = ka.parse(proxy_statement)
# 查找主要股东
@@ -200,7 +234,7 @@ for sh in sorted(shareholders, key=lambda x: x.stake, reverse=True)[:5]:
### 用例 3:风险评估
```python
-ka = Template.create("finance/risk_factor_set", "en")
+ka = Template.create("finance/risk_factor_set", "zh")
risk_factors = ka.parse(risk_section)
# 分类风险
@@ -235,6 +269,6 @@ for risk in risk_factors.data.items:
## 参见
-- [浏览所有模板](browse.md)
-- [如何选择](how-to-choose.md)
-- [通用模板](general/index.md)
+- [模板概览](overview.md)
+- [如何选择](../how-to-choose.md)
+- [通用模板](general.md)
diff --git a/docs/zh/templates/general/index.md b/docs/zh/templates/reference/general.md
similarity index 55%
rename from docs/zh/templates/general/index.md
rename to docs/zh/templates/reference/general.md
index 80c1778..1759c14 100644
--- a/docs/zh/templates/general/index.md
+++ b/docs/zh/templates/reference/general.md
@@ -20,10 +20,20 @@
**用于**:简单摘要、表单类数据
-**示例:**
-```bash
-he parse doc.md -t general/base_model -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse doc.md -t general/model -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/model", "zh")
+ result = ka.parse(doc_text)
+
+ print(result.data)
+ ```
**输出模式**:
```python
@@ -43,10 +53,21 @@ he parse doc.md -t general/base_model -l en
**用于**:序列、排名
-**示例:**
-```bash
-he parse doc.md -t general/base_list -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse doc.md -t general/list -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/list", "zh")
+ result = ka.parse(doc_text)
+
+ for item in result.data.items:
+ print(f"- {item}")
+ ```
**输出模式**:
```python
@@ -65,10 +86,21 @@ he parse doc.md -t general/base_list -l en
**用于**:标签、类别、关键词
-**示例:**
-```bash
-he parse doc.md -t general/base_set -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse doc.md -t general/set -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/set", "zh")
+ result = ka.parse(doc_text)
+
+ for item in result.data.items:
+ print(f"- {item}")
+ ```
**输出模式**:
```python
@@ -87,10 +119,21 @@ he parse doc.md -t general/base_set -l en
**用于**:知识图谱、网络
-**示例:**
-```bash
-he parse doc.md -t general/base_graph -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse doc.md -t general/graph -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/graph", "zh")
+ result = ka.parse(doc_text)
+
+ print(f"实体: {len(result.nodes)}")
+ print(f"关系: {len(result.edges)}")
+ ```
**输出模式**:
```python
@@ -117,10 +160,28 @@ he parse doc.md -t general/base_graph -l en
**最适合**:传记、简介、回忆录
-**示例使用:**
-```bash
-he parse sushi.md -t general/biography_graph -l zh
-```
+=== "CLI"
+
+ ```bash
+ he parse sushi.md -t general/biography_graph -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/biography_graph", "zh")
+ result = ka.parse(biography_text)
+
+ # 构建索引以支持交互功能
+ result.build_index()
+
+ # 可视化生平事件(支持搜索/对话功能)
+ result.show()
+
+ # 提问
+ response = result.chat("主要成就是什么?")
+ print(response.content)
+ ```
**特性**:
- 提取人物、地点、事件
@@ -155,10 +216,25 @@ he parse sushi.md -t general/biography_graph -l zh
**最适合**:研究论文、技术文档、文章
-**示例使用:**
-```bash
-he parse paper.md -t general/concept_graph -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse paper.md -t general/concept_graph -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/concept_graph", "zh")
+ result = ka.parse(paper_text)
+
+ # 获取概念图
+ for node in result.nodes:
+ print(f"概念: {node.name}")
+
+ for edge in result.edges:
+ print(f"{edge.source} → {edge.target}")
+ ```
**特性**:
- 概念识别
@@ -175,10 +251,24 @@ he parse paper.md -t general/concept_graph -l en
**最适合**:长文档、报告、书籍
-**示例使用:**
-```bash
-he parse report.md -t general/doc_structure -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse report.md -t general/doc_structure -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/doc_structure", "zh")
+ result = ka.parse(report_text)
+
+ print(f"标题: {result.data.title}")
+ print(f"章节: {len(result.data.sections)}")
+
+ for section in result.data.sections:
+ print(f"- {section.heading}")
+ ```
**特性**:
- 章节识别
@@ -195,10 +285,28 @@ he parse report.md -t general/doc_structure -l en
**最适合**:程序、流程、工作流
-**示例使用:**
-```bash
-he parse procedure.md -t general/workflow_graph -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse procedure.md -t general/workflow_graph -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("general/workflow_graph", "zh")
+ result = ka.parse(procedure_text)
+
+ # 构建索引用于可视化
+ result.build_index()
+
+ # 可视化工作流
+ result.show()
+
+ # 查询工作流
+ response = result.chat("第一步是什么?")
+ print(response.content)
+ ```
**特性**:
- 步骤识别
@@ -228,7 +336,7 @@ he parse procedure.md -t general/workflow_graph -l en
```python
from hyperextract import Template
-ka = Template.create("general/base_model", "en")
+ka = Template.create("general/model", "zh")
result = ka.parse("""
会议记录:
日期:2024年1月15日
@@ -243,7 +351,7 @@ print(result.data)
### 示例 2:传记分析
```python
-ka = Template.create("general/biography_graph", "en")
+ka = Template.create("general/biography_graph", "zh")
result = ka.parse(biography_text)
# 构建索引以支持交互功能
@@ -260,7 +368,7 @@ print(response.content)
### 示例 3:研究论文
```python
-ka = Template.create("general/concept_graph", "en")
+ka = Template.create("general/concept_graph", "zh")
result = ka.parse(paper_text)
# 获取概念图
@@ -275,6 +383,6 @@ for edge in result.edges:
## 参见
-- [浏览所有模板](../browse.md)
+- [模板概览](overview.md)
- [如何选择](../how-to-choose.md)
- [自动类型](../../concepts/autotypes.md)
diff --git a/docs/zh/templates/industry.md b/docs/zh/templates/reference/industry.md
similarity index 58%
rename from docs/zh/templates/industry.md
rename to docs/zh/templates/reference/industry.md
index cc102d1..9bac8eb 100644
--- a/docs/zh/templates/industry.md
+++ b/docs/zh/templates/reference/industry.md
@@ -34,18 +34,23 @@
- `controlled_by` — 控制关系
- `monitors` — 监控关系
-**示例:**
-```bash
-he parse system_diagram.md -t industry/equipment_topology -l en
-```
+=== "CLI"
-**可视化:**
-```python
-# 构建索引以支持可视化中的交互式搜索/对话
-result.build_index()
+ ```bash
+ he parse system_diagram.md -t industry/equipment_topology -l zh
+ ```
-result.show() # 显示带有交互功能的设备网络
-```
+=== "Python"
+
+ ```python
+ ka = Template.create("industry/equipment_topology", "zh")
+ result = ka.parse(pandid_description)
+
+ # 构建索引以支持可视化中的交互式搜索/对话
+ result.build_index()
+
+ result.show() # 显示带有交互功能的设备网络
+ ```
---
@@ -73,10 +78,25 @@ result.show() # 显示带有交互功能的设备网络
- `triggers` — 传感器与动作的关系
- `implements` — 系统与功能的关系
-**示例:**
-```bash
-he parse safety_manual.md -t industry/safety_control -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse safety_manual.md -t industry/safety_control -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("industry/safety_control", "zh")
+ result = ka.parse(safety_text)
+
+ print(f"安全功能数: {len(result.nodes)}")
+ print(f"保护措施数: {len(result.edges)}")
+
+ # 可视化安全系统
+ result.build_index()
+ result.show()
+ ```
---
@@ -98,10 +118,25 @@ he parse safety_manual.md -t industry/safety_control -l en
- 并行操作
- 依赖关系
-**示例:**
-```bash
-he parse sop.md -t industry/operation_flow -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse sop.md -t industry/operation_flow -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("industry/operation_flow", "zh")
+ result = ka.parse(sop_text)
+
+ print(f"步骤数: {len(result.nodes)}")
+ print(f"流程连接数: {len(result.edges)}")
+
+ # 可视化操作流程
+ result.build_index()
+ result.show()
+ ```
---
@@ -127,10 +162,25 @@ he parse sop.md -t industry/operation_flow -l en
- `requires` — 资源需求
- `notifies` — 通知链
-**示例:**
-```bash
-he parse emergency_plan.md -t industry/emergency_response -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse emergency_plan.md -t industry/emergency_response -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("industry/emergency_response", "zh")
+ result = ka.parse(emergency_text)
+
+ print(f"紧急情况类型数: {len(result.nodes)}")
+ print(f"响应动作数: {len(result.edges)}")
+
+ # 可视化应急响应计划
+ result.build_index()
+ result.show()
+ ```
---
@@ -151,10 +201,27 @@ he parse emergency_plan.md -t industry/emergency_response -l en
- 根本原因
- 纠正措施
-**示例:**
-```bash
-he parse incident_report.md -t industry/failure_case -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse incident_report.md -t industry/failure_case -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("industry/failure_case", "zh")
+ result = ka.parse(incident_text)
+
+ print(f"事件数: {len(result.nodes)}")
+ for edge in result.edges:
+ if hasattr(edge, 'time'):
+ print(f" {edge.time}: {edge.source} -> {edge.target}")
+
+ # 可视化故障时间线
+ result.build_index()
+ result.show()
+ ```
---
@@ -165,7 +232,7 @@ he parse incident_report.md -t industry/failure_case -l en
```python
from hyperextract import Template
-ka = Template.create("industry/equipment_topology", "en")
+ka = Template.create("industry/equipment_topology", "zh")
system = ka.parse(pandid_description)
# 查找所有泵
@@ -183,7 +250,7 @@ for pump in pumps:
### 安全分析
```python
-ka = Template.create("industry/safety_control", "en")
+ka = Template.create("industry/safety_control", "zh")
safety = ka.parse(hazop_report)
# 将危险映射到保护措施
@@ -202,7 +269,7 @@ for hazard in hazards:
### 程序文档
```python
-ka = Template.create("industry/operation_flow", "en")
+ka = Template.create("industry/operation_flow", "zh")
procedure = ka.parse(sop_document)
# 构建索引以支持交互式可视化
@@ -228,5 +295,5 @@ results = procedure.search("启动序列")
## 参见
-- [浏览所有模板](browse.md)
-- [通用模板](general/index.md)
+- [模板概览](overview.md)
+- [通用模板](general.md)
diff --git a/docs/zh/templates/legal.md b/docs/zh/templates/reference/legal.md
similarity index 56%
rename from docs/zh/templates/legal.md
rename to docs/zh/templates/reference/legal.md
index 52c9eb2..9280e64 100644
--- a/docs/zh/templates/legal.md
+++ b/docs/zh/templates/reference/legal.md
@@ -25,6 +25,7 @@
- 许可协议
**字段**:
+
| 字段 | 类型 | 描述 |
|------|------|------|
| `party` | str | 义务方 |
@@ -32,21 +33,23 @@
| `deadline` | str | 截止日期/时间线 |
| `conditions` | str | 条件或限制 |
-**示例:**
-```bash
-he parse contract.md -t legal/contract_obligation -l en
-```
+=== "CLI"
-**Python:**
-```python
-ka = Template.create("legal/contract_obligation", "en")
-result = ka.parse(contract_text)
+ ```bash
+ he parse contract.md -t legal/contract_obligation -l zh
+ ```
-for obl in result.data.items:
- print(f"{obl.party}: {obl.obligation}")
- if obl.deadline:
- print(f" 截止: {obl.deadline}")
-```
+=== "Python"
+
+ ```python
+ ka = Template.create("legal/contract_obligation", "zh")
+ result = ka.parse(contract_text)
+
+ for obl in result.data.items:
+ print(f"{obl.party}: {obl.obligation}")
+ if obl.deadline:
+ print(f" 截止: {obl.deadline}")
+ ```
---
@@ -73,10 +76,25 @@ for obl in result.data.items:
- `overruled` — 推翻关系
- `distinguished` — 区分关系
-**示例:**
-```bash
-he parse brief.md -t legal/case_citation -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse brief.md -t legal/case_citation -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("legal/case_citation", "zh")
+ result = ka.parse(brief_text)
+
+ print(f"实体数: {len(result.nodes)}")
+ print(f"关系数: {len(result.edges)}")
+
+ # 构建索引用于交互式可视化
+ result.build_index()
+ result.show()
+ ```
---
@@ -96,10 +114,27 @@ he parse brief.md -t legal/case_citation -l en
- 事实描述
- 相关方
-**示例:**
-```bash
-he parse case_summary.md -t legal/case_fact_timeline -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse case_summary.md -t legal/case_fact_timeline -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("legal/case_fact_timeline", "zh")
+ result = ka.parse(case_text)
+
+ print(f"事件数: {len(result.nodes)}")
+ for edge in result.edges:
+ if hasattr(edge, 'time'):
+ print(f" {edge.time}: {edge.source} -> {edge.target}")
+
+ # 可视化时间线
+ result.build_index()
+ result.show()
+ ```
---
@@ -115,16 +150,29 @@ he parse case_summary.md -t legal/case_fact_timeline -l en
- 政策文档
**字段**:
+
| 字段 | 类型 | 描述 |
|------|------|------|
| `requirement` | str | 合规要求 |
| `regulation` | str | 来源条例 |
| `priority` | str | 优先级 |
-**示例:**
-```bash
-he parse compliance.md -t legal/compliance_list -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse compliance.md -t legal/compliance_list -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("legal/compliance_list", "zh")
+ result = ka.parse(compliance_text)
+
+ for item in result.data.items:
+ print(f"[{item.priority}] {item.requirement}")
+ print(f" 法规: {item.regulation}")
+ ```
---
@@ -139,21 +187,21 @@ he parse compliance.md -t legal/compliance_list -l en
- 技术法律文档
- 词汇表提取
-**示例:**
-```bash
-he parse agreement.md -t legal/defined_term_set -l en
-```
+=== "CLI"
-**输出:**
-```python
-{
- "items": [
- "保密信息:指所有非公开的...",
- "生效日期:指签署日期...",
- "当事方:指任一签字方..."
- ]
-}
-```
+ ```bash
+ he parse agreement.md -t legal/defined_term_set -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("legal/defined_term_set", "zh")
+ result = ka.parse(agreement_text)
+
+ for term in result.data.items:
+ print(f"{term.term}: {term.definition}")
+ ```
---
@@ -164,7 +212,7 @@ he parse agreement.md -t legal/defined_term_set -l en
```python
from hyperextract import Template
-ka = Template.create("legal/contract_obligation", "en")
+ka = Template.create("legal/contract_obligation", "zh")
obligations = ka.parse(contract)
# 查找所有截止日期
@@ -176,7 +224,7 @@ for d in sorted(deadlines, key=lambda x: x.deadline):
### 案例分析
```python
-ka = Template.create("legal/case_citation", "en")
+ka = Template.create("legal/case_citation", "zh")
case_graph = ka.parse(brief)
# 查找引用最多的案例
@@ -192,11 +240,11 @@ top_cases = sorted(citations.items(), key=lambda x: x[1], reverse=True)
```python
# 提取义务
-ka = Template.create("legal/contract_obligation", "en")
+ka = Template.create("legal/contract_obligation", "zh")
obligations = ka.parse(agreement)
# 提取风险
-ka2 = Template.create("finance/risk_factor_set", "en")
+ka2 = Template.create("finance/risk_factor_set", "zh")
risks = ka2.parse(agreement)
# 分析
@@ -219,5 +267,5 @@ high_risk_obligations = [
## 参见
-- [浏览所有模板](browse.md)
+- [模板概览](overview.md)
- [金融模板](finance.md)
diff --git a/docs/zh/templates/medicine.md b/docs/zh/templates/reference/medicine.md
similarity index 59%
rename from docs/zh/templates/medicine.md
rename to docs/zh/templates/reference/medicine.md
index e012a15..9f761c2 100644
--- a/docs/zh/templates/medicine.md
+++ b/docs/zh/templates/reference/medicine.md
@@ -36,10 +36,25 @@
- `connected_to` — 结构连接
- `supplies` — 血液/神经供应
-**示例:**
-```bash
-he parse anatomy.md -t medicine/anatomy_graph -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse anatomy.md -t medicine/anatomy_graph -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("medicine/anatomy_graph", "zh")
+ result = ka.parse(anatomy_text)
+
+ print(f"结构数: {len(result.nodes)}")
+ print(f"关系数: {len(result.edges)}")
+
+ # 构建索引用于交互式探索
+ result.build_index()
+ result.show()
+ ```
---
@@ -55,6 +70,7 @@ he parse anatomy.md -t medicine/anatomy_graph -l en
- 就诊后总结
**字段**:
+
| 字段 | 类型 | 描述 |
|------|------|------|
| `diagnosis` | str | 主要诊断 |
@@ -63,19 +79,21 @@ he parse anatomy.md -t medicine/anatomy_graph -l en
| `follow_up` | str | 随访指导 |
| `warnings` | list[str] | 警告信号 |
-**示例:**
-```bash
-he parse discharge.md -t medicine/discharge_instruction -l en
-```
+=== "CLI"
-**Python:**
-```python
-ka = Template.create("medicine/discharge_instruction", "en")
-summary = ka.parse(discharge_text)
+ ```bash
+ he parse discharge.md -t medicine/discharge_instruction -l zh
+ ```
-print(f"诊断: {summary.data.diagnosis}")
-print(f"随访: {summary.data.follow_up}")
-```
+=== "Python"
+
+ ```python
+ ka = Template.create("medicine/discharge_instruction", "zh")
+ summary = ka.parse(discharge_text)
+
+ print(f"诊断: {summary.data.diagnosis}")
+ print(f"随访: {summary.data.follow_up}")
+ ```
---
@@ -100,10 +118,22 @@ print(f"随访: {summary.data.follow_up}")
- `contraindicated_with` — 禁忌
- `synergizes_with` — 协同作用
-**示例:**
-```bash
-he parse drug_ref.md -t medicine/drug_interaction -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse drug_ref.md -t medicine/drug_interaction -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("medicine/drug_interaction", "zh")
+ result = ka.parse(drug_text)
+
+ print(f"药物数: {len(result.nodes)}")
+ for relation in result.edges:
+ print(f"{relation.source} {relation.type} {relation.target}")
+ ```
---
@@ -123,10 +153,27 @@ he parse drug_ref.md -t medicine/drug_interaction -l en
- 程序和事件
- 时间线可视化
-**示例:**
-```bash
-he parse hospital_notes.md -t medicine/hospital_timeline -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse hospital_notes.md -t medicine/hospital_timeline -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("medicine/hospital_timeline", "zh")
+ result = ka.parse(notes_text)
+
+ print(f"事件数: {len(result.nodes)}")
+ for edge in result.edges:
+ if hasattr(edge, 'time'):
+ print(f" {edge.time}: {edge.source} -> {edge.target}")
+
+ # 可视化时间线
+ result.build_index()
+ result.show()
+ ```
---
@@ -141,10 +188,25 @@ he parse hospital_notes.md -t medicine/hospital_timeline -l en
- 护理路径
- 方案文档
-**示例:**
-```bash
-he parse protocol.md -t medicine/treatment_map -l en
-```
+=== "CLI"
+
+ ```bash
+ he parse protocol.md -t medicine/treatment_map -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("medicine/treatment_map", "zh")
+ result = ka.parse(protocol_text)
+
+ print(f"步骤数: {len(result.nodes)}")
+ print(f"流程关系: {len(result.edges)}")
+
+ # 可视化治疗路径
+ result.build_index()
+ result.show()
+ ```
---
@@ -155,7 +217,7 @@ he parse protocol.md -t medicine/treatment_map -l en
```python
from hyperextract import Template
-ka = Template.create("medicine/discharge_instruction", "en")
+ka = Template.create("medicine/discharge_instruction", "zh")
discharges = []
for file in discharge_files:
@@ -171,7 +233,7 @@ print(diagnoses.most_common(10))
### 药物相互作用网络
```python
-ka = Template.create("medicine/drug_interaction", "en")
+ka = Template.create("medicine/drug_interaction", "zh")
network = ka.parse(drug_database)
# 查找特定药物的相互作用
@@ -188,7 +250,7 @@ for i in interactions:
### 解剖学教育
```python
-ka = Template.create("medicine/anatomy_graph", "en")
+ka = Template.create("medicine/anatomy_graph", "zh")
anatomy = ka.parse(textbook_chapter)
# 构建索引以支持交互式可视化
@@ -224,5 +286,5 @@ results = anatomy.search("手部神经")
## 参见
-- [浏览所有模板](browse.md)
+- [模板概览](overview.md)
- [中医模板](tcm.md)
diff --git a/docs/zh/templates/reference/overview.md b/docs/zh/templates/reference/overview.md
new file mode 100644
index 0000000..b89e24d
--- /dev/null
+++ b/docs/zh/templates/reference/overview.md
@@ -0,0 +1,234 @@
+# 模板概览
+
+所有可用模板的完整概览。
+
+---
+
+## 统计
+
+- **模板总数**:80+
+- **类别**:6 个领域
+- **自动类型**:8 种类型
+- **语言**:中文、英文
+
+---
+
+## 按领域
+
+### 通用模板
+
+| 模板 | 类型 | 描述 |
+|------|------|------|
+| `general/model` | model | 基础结构化模型 |
+| `general/list` | list | 基础有序列表 |
+| `general/set` | set | 基础唯一集合 |
+| `general/graph` | graph | 基础知识图谱 |
+| `general/base_hypergraph` | hypergraph | 基础超图 |
+| `general/base_temporal_graph` | temporal_graph | 基础时间线图谱 |
+| `general/base_spatial_graph` | spatial_graph | 基础空间图谱 |
+| `general/base_spatio_temporal_graph` | spatio_temporal_graph | 基础时空图谱 |
+| `general/biography_graph` | temporal_graph | 人物生平时间线 |
+| `general/concept_graph` | graph | 研究概念提取 |
+| `general/graph` | graph | 通用知识提取 |
+| `general/doc_structure` | model | 文档大纲结构 |
+| `general/workflow_graph` | graph | 流程工作流 |
+
+### 金融模板
+
+| 模板 | 类型 | 描述 |
+|------|------|------|
+| `finance/earnings_summary` | model | 季度/年度财报 |
+| `finance/event_timeline` | temporal_graph | 财务事件 |
+| `finance/ownership_graph` | graph | 公司股权结构 |
+| `finance/risk_factor_set` | set | 风险因素 |
+| `finance/sentiment_model` | model | 情感分析 |
+
+### 法律模板
+
+| 模板 | 类型 | 描述 |
+|------|------|------|
+| `legal/case_citation` | graph | 法律案例引用 |
+| `legal/case_fact_timeline` | temporal_graph | 案例年表 |
+| `legal/compliance_list` | list | 合规要求 |
+| `legal/contract_obligation` | list | 合同义务 |
+| `legal/defined_term_set` | set | 定义术语 |
+
+### 医疗模板
+
+| 模板 | 类型 | 描述 |
+|------|------|------|
+| `medicine/anatomy_graph` | graph | 解剖结构 |
+| `medicine/discharge_instruction` | model | 患者出院摘要 |
+| `medicine/drug_interaction` | graph | 药物相互作用 |
+| `medicine/hospital_timeline` | temporal_graph | 住院时间线 |
+| `medicine/symptom_list` | list | 症状 |
+| `medicine/treatment_map` | graph | 治疗方案 |
+
+### 中医模板
+
+| 模板 | 类型 | 描述 |
+|------|------|------|
+| `tcm/formula_composition` | graph | 中药方剂组成 |
+| `tcm/herb_property` | model | 草药属性 |
+| `tcm/herb_relation` | graph | 草药关系 |
+| `tcm/meridian_graph` | graph | 经络路径 |
+| `tcm/syndrome_reasoning` | graph | 证候推理 |
+
+### 工业模板
+
+| 模板 | 类型 | 描述 |
+|------|------|------|
+| `industry/emergency_response` | graph | 应急程序 |
+| `industry/equipment_topology` | graph | 设备连接 |
+| `industry/failure_case` | temporal_graph | 故障分析 |
+| `industry/operation_flow` | graph | 操作工作流 |
+| `industry/safety_control` | graph | 安全控制系统 |
+
+---
+
+## 按自动类型
+
+### Model 模板
+
+| 模板 | 领域 | 描述 |
+|------|------|------|
+| `general/model` | general | 基础结构化模型 |
+| `finance/earnings_summary` | finance | 财务摘要 |
+| `finance/sentiment_model` | finance | 情感分析 |
+| `medicine/discharge_instruction` | medical | 出院摘要 |
+| `tcm/herb_property` | tcm | 草药属性 |
+
+### List 模板
+
+| 模板 | 领域 | 描述 |
+|------|------|------|
+| `general/list` | general | 基础列表 |
+| `legal/compliance_list` | legal | 合规要求 |
+| `legal/contract_obligation` | legal | 合同义务 |
+| `medicine/symptom_list` | medical | 症状 |
+
+### Set 模板
+
+| 模板 | 领域 | 描述 |
+|------|------|------|
+| `general/set` | general | 基础集合 |
+| `finance/risk_factor_set` | finance | 风险因素 |
+| `legal/defined_term_set` | legal | 定义术语 |
+
+### Graph 模板
+
+| 模板 | 领域 | 描述 |
+|------|------|------|
+| `general/graph` | general | 基础图谱 |
+| `general/graph` | general | 知识图谱 |
+| `general/concept_graph` | general | 概念图谱 |
+| `general/workflow_graph` | general | 流程工作流 |
+| `finance/ownership_graph` | finance | 股权结构 |
+| `legal/case_citation` | legal | 案例引用 |
+| `medicine/anatomy_graph` | medical | 解剖学 |
+| `medicine/drug_interaction` | medical | 药物相互作用 |
+| `medicine/treatment_map` | medical | 治疗方案 |
+| `tcm/herb_relation` | tcm | 草药关系 |
+| `tcm/meridian_graph` | tcm | 经络路径 |
+| `tcm/syndrome_reasoning` | tcm | 证候推理 |
+| `industry/equipment_topology` | industry | 设备连接 |
+| `industry/operation_flow` | industry | 操作工作流 |
+| `industry/safety_control` | industry | 安全控制系统 |
+
+### Temporal Graph 模板
+
+| 模板 | 领域 | 描述 |
+|------|------|------|
+| `general/base_temporal_graph` | general | 基础时间线图谱 |
+| `general/biography_graph` | general | 传记时间线 |
+| `finance/event_timeline` | finance | 财务事件 |
+| `legal/case_fact_timeline` | legal | 案例时间线 |
+| `medicine/hospital_timeline` | medical | 住院时间线 |
+| `industry/failure_case` | industry | 故障分析 |
+
+### Spatial Graph 模板
+
+| 模板 | 领域 | 描述 |
+|------|------|------|
+| `general/base_spatial_graph` | general | 基础空间图谱 |
+
+### Spatio-Temporal Graph 模板
+
+| 模板 | 领域 | 描述 |
+|------|------|------|
+| `general/base_spatio_temporal_graph` | general | 基础时空图谱 |
+
+### Hypergraph 模板
+
+| 模板 | 领域 | 描述 |
+|------|------|------|
+| `general/base_hypergraph` | general | 基础超图 |
+
+---
+
+## 方法(算法级访问)
+
+方法提供对提取算法的直接访问:
+
+| 方法 | 类型 | 最佳场景 |
+|------|------|---------|
+| `method/light_rag` | RAG | 通用,快速 |
+| `method/graph_rag` | RAG | 大型文档 |
+| `method/hyper_rag` | RAG | 复杂关系 |
+| `method/itext2kg` | 标准 | 高质量三元组 |
+| `method/itext2kg_star` | 标准 | 增强质量 |
+| `method/kg_gen` | 标准 | 灵活生成 |
+| `method/atom` | 标准 | 带证据的时间提取 |
+
+→ [何时使用方法](../../python/guides/using-methods.md)
+
+---
+
+## 使用本参考
+
+### CLI
+
+```bash
+# 列出所有模板
+he list template
+
+# 按领域筛选
+he list template | grep finance
+
+# 获取模板信息
+he info template general/biography_graph
+```
+
+### Python
+
+```python
+from hyperextract import Template
+
+# 获取所有模板
+templates = Template.list()
+
+# 按类型筛选
+graphs = Template.list(filter_by_type="graph")
+temporal = Template.list(filter_by_type="temporal_graph")
+
+# 按领域/标签筛选
+finance = Template.list(filter_by_tag="finance")
+medical = Template.list(filter_by_tag="medicine")
+
+# 获取模板详情
+cfg = Template.get("general/biography_graph")
+print(cfg.name) # biography_graph
+print(cfg.type) # temporal_graph
+print(cfg.description) # 描述文本
+print(cfg.tags) # ['general', 'biography']
+print(cfg.language) # ['zh', 'en']
+```
+
+---
+
+## 另请参见
+
+- [按任务选择](../choosing/by-task.md) — 基于任务的选择
+- [按输出类型选择](../choosing/by-output.md) — 基于输出的选择
+- [模板库首页](../index.md) — 返回主模板页面
+- [自定义模板指南](../../python/guides/custom-templates.md) — 创建您自己的模板
diff --git a/docs/zh/templates/tcm.md b/docs/zh/templates/reference/tcm.md
similarity index 63%
rename from docs/zh/templates/tcm.md
rename to docs/zh/templates/reference/tcm.md
index b6356e5..a71b93e 100644
--- a/docs/zh/templates/tcm.md
+++ b/docs/zh/templates/reference/tcm.md
@@ -24,6 +24,7 @@
- 处方参考
**字段**:
+
| 字段 | 类型 | 描述 |
|------|------|------|
| `name` | str | 草药名称(中文/拼音) |
@@ -33,20 +34,22 @@
| `functions` | list[str] | 主要功效 |
| `indications` | list[str] | 临床应用 |
-**示例:**
-```bash
-he parse herb_text.md -t tcm/herb_property -l zh
-```
+=== "CLI"
-**Python:**
-```python
-ka = Template.create("tcm/herb_property", "zh")
-herb = ka.parse(huang_qi_text)
+ ```bash
+ he parse herb_text.md -t tcm/herb_property -l zh
+ ```
-print(f"名称: {herb.data.name}")
-print(f"性质: {', '.join(herb.data.properties)}")
-print(f"功效: {', '.join(herb.data.functions)}")
-```
+=== "Python"
+
+ ```python
+ ka = Template.create("tcm/herb_property", "zh")
+ herb = ka.parse(huang_qi_text)
+
+ print(f"名称: {herb.data.name}")
+ print(f"性质: {', '.join(herb.data.properties)}")
+ print(f"功效: {', '.join(herb.data.functions)}")
+ ```
---
@@ -71,10 +74,26 @@ print(f"功效: {', '.join(herb.data.functions)}")
- `treats` — 方剂治疗病症
- `modifies` — 加减方关系
-**示例:**
-```bash
-he parse formula_book.md -t tcm/formula_composition -l zh
-```
+=== "CLI"
+
+ ```bash
+ he parse formula_book.md -t tcm/formula_composition -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("tcm/formula_composition", "zh")
+ result = ka.parse(formula_text)
+
+ print(f"实体数: {len(result.nodes)}")
+ print(f"关系数: {len(result.edges)}")
+
+ # 列方剂中的草药
+ for edge in result.edges:
+ if edge.type == "contains":
+ print(f" - {edge.target}")
+ ```
---
@@ -94,10 +113,22 @@ he parse formula_book.md -t tcm/formula_composition -l zh
- `synergizes_with` — 协同作用
- `incompatible_with` — 配伍禁忌
-**示例:**
-```bash
-he parse herb_pairs.md -t tcm/herb_relation -l zh
-```
+=== "CLI"
+
+ ```bash
+ he parse herb_pairs.md -t tcm/herb_relation -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("tcm/herb_relation", "zh")
+ result = ka.parse(herb_text)
+
+ print(f"草药数: {len(result.nodes)}")
+ for edge in result.edges:
+ print(f"{edge.source} {edge.type} {edge.target}")
+ ```
---
@@ -122,10 +153,25 @@ he parse herb_pairs.md -t tcm/herb_relation -l zh
- `belongs_to` — 穴位所属经络
- `influences` — 经络与脏腑关系
-**示例:**
-```bash
-he parse acupuncture.md -t tcm/meridian_graph -l zh
-```
+=== "CLI"
+
+ ```bash
+ he parse acupuncture.md -t tcm/meridian_graph -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("tcm/meridian_graph", "zh")
+ result = ka.parse(acupuncture_text)
+
+ print(f"经络数: {len(result.nodes)}")
+ print(f"连接数: {len(result.edges)}")
+
+ # 可视化经络路径
+ result.build_index()
+ result.show()
+ ```
---
@@ -150,10 +196,25 @@ he parse acupuncture.md -t tcm/meridian_graph -l zh
- `differentiates_from` — 鉴别诊断
- `leads_to` — 病机演变
-**示例:**
-```bash
-he parse diagnostics.md -t tcm/syndrome_reasoning -l zh
-```
+=== "CLI"
+
+ ```bash
+ he parse diagnostics.md -t tcm/syndrome_reasoning -l zh
+ ```
+
+=== "Python"
+
+ ```python
+ ka = Template.create("tcm/syndrome_reasoning", "zh")
+ result = ka.parse(diagnostics_text)
+
+ print(f"症状数: {len(result.nodes)}")
+ print(f"证型关联: {len(result.edges)}")
+
+ # 探索证型关系
+ result.build_index()
+ result.show()
+ ```
---
@@ -220,5 +281,5 @@ for r in related:
## 参见
-- [浏览所有模板](browse.md)
+- [模板概览](overview.md)
- [医疗模板](medicine.md)
diff --git a/docs/zh/tutorials/document-analysis/index.md b/docs/zh/tutorials/document-analysis/index.md
index e465a83..e877284 100644
--- a/docs/zh/tutorials/document-analysis/index.md
+++ b/docs/zh/tutorials/document-analysis/index.md
@@ -117,7 +117,7 @@ class BatchDocumentProcessor:
def __init__(
self,
- template: str = "general/knowledge_graph",
+ template: str = "general/graph",
language: str = "en",
batch_size: int = 10,
max_workers: int = 4
@@ -300,15 +300,15 @@ class BatchDocumentProcessor:
# 合并剩余结果
for output_dir in output_dirs[1:]:
- kb = Template.create(self.template, self.language)
- kb.load(str(output_dir))
+ ka = Template.create(self.template, self.language)
+ ka.load(str(output_dir))
# 合并实体和关系
- for entity in kb.data.entities:
+ for entity in ka.data.entities:
if entity not in combined.data.entities:
combined.data.entities.append(entity)
- for relation in kb.data.relations:
+ for relation in ka.data.relations:
if relation not in combined.data.relations:
combined.data.relations.append(relation)
@@ -326,7 +326,7 @@ if __name__ == "__main__":
import argparse
parser = argparse.ArgumentParser(description="批处理文档处理器")
- parser.add_argument("--template", default="general/knowledge_graph", help="使用的模板")
+ parser.add_argument("--template", default="general/graph", help="使用的模板")
parser.add_argument("--language", default="en", help="文档语言")
parser.add_argument("--batch-size", type=int, default=10, help="批次大小")
parser.add_argument("--parallel", action="store_true", help="启用并行处理")
diff --git a/docs/zh/tutorials/knowledge-base/index.md b/docs/zh/tutorials/knowledge-base/index.md
index 921f98c..55b7d99 100644
--- a/docs/zh/tutorials/knowledge-base/index.md
+++ b/docs/zh/tutorials/knowledge-base/index.md
@@ -55,7 +55,7 @@
knowledge-base/
├── config.yaml # 配置
├── documents/ # 源文档
-├── kb/ # 知识库存储
+├── ka/ # 知识库存储
│ ├── v1/ # 版本 1
│ ├── v2/ # 版本 2
│ └── current/ # 当前版本
diff --git a/docs/zh/tutorials/knowledge-base/step1-setup.md b/docs/zh/tutorials/knowledge-base/step1-setup.md
index 8cdfa26..8505f59 100644
--- a/docs/zh/tutorials/knowledge-base/step1-setup.md
+++ b/docs/zh/tutorials/knowledge-base/step1-setup.md
@@ -15,18 +15,18 @@
创建以下目录结构:
```bash
-mkdir -p my_knowledge_base/{documents,kb,backups,logs}
-cd my_knowledge_base
+mkdir -p my_ka/{documents,ka,backups,logs}
+cd my_ka
```
结构:
```
-my_knowledge_base/
+my_ka/
├── config.yaml # 项目配置
├── documents/ # 源文档
│ ├── raw/ # 原始文件
│ └── processed/ # 处理日志
-├── kb/ # 知识库版本
+├── ka/ # 知识库版本
│ └── current/ # 当前版本(符号链接)
├── backups/ # 版本备份
├── logs/ # 操作日志
@@ -41,7 +41,7 @@ my_knowledge_base/
```yaml
# 知识库配置
-name: "Company Knowledge Base"
+name: "Company Knowledge Abstract"
domain: "legal" # 或 finance、medical 等
# 模板设置
@@ -58,7 +58,7 @@ auto_backup: true
# 路径
documents_dir: "./documents/raw"
-kb_dir: "./kb"
+ka_dir: "./ka"
backup_dir: "./backups"
```
@@ -69,7 +69,7 @@ backup_dir: "./backups"
| 法律 | `legal/contract_obligation` | list |
| 金融 | `finance/earnings_summary` | model |
| 医疗 | `medicine/anatomy_graph` | graph |
-| 通用 | `general/knowledge_graph` | graph |
+| 通用 | `general/graph` | graph |
| 研究 | `general/concept_graph` | graph |
---
@@ -97,7 +97,7 @@ class KBConfig:
template: str
language: str
documents_dir: str
- kb_dir: str
+ ka_dir: str
backup_dir: str
class KnowledgeBaseManager:
@@ -163,12 +163,12 @@ if __name__ == "__main__":
```bash
cat > config.yaml << 'EOF'
-name: "My Knowledge Base"
+name: "My Knowledge Abstract"
domain: "general"
-template: "general/knowledge_graph"
+template: "general/graph"
language: "en"
documents_dir: "./documents/raw"
-kb_dir: "./kb"
+ka_dir: "./ka"
backup_dir: "./backups"
EOF
```
@@ -181,14 +181,14 @@ python kb_manager.py
预期输出:
```
-初始化: My Knowledge Base
+初始化: My Knowledge Abstract
✓ 初始化完成
```
### 3. 验证结构
```bash
-tree my_knowledge_base/
+tree my_ka/
```
---
diff --git a/docs/zh/tutorials/knowledge-base/step2-ingest.md b/docs/zh/tutorials/knowledge-base/step2-ingest.md
index 5b8feab..6f35047 100644
--- a/docs/zh/tutorials/knowledge-base/step2-ingest.md
+++ b/docs/zh/tutorials/knowledge-base/step2-ingest.md
@@ -55,20 +55,20 @@ def initial_ingest(self, documents_dir: str):
# 解析第一个文档
print(f"处理: {docs[0].name}")
text = docs[0].read_text(encoding="utf-8")
- kb = self.ka.parse(text)
+ ka = self.ka.parse(text)
# 添加剩余文档
for doc in docs[1:]:
print(f"添加: {doc.name}")
text = doc.read_text(encoding="utf-8")
- kb.feed_text(text)
+ ka.feed_text(text)
# 构建索引
print("构建搜索索引...")
- kb.build_index()
+ ka.build_index()
# 保存版本
- version_path = self.save_version(kb, "v1.0")
+ version_path = self.save_version(ka, "v1.0")
# 记录处理
self._log_processing(docs, version_path)
@@ -76,7 +76,7 @@ def initial_ingest(self, documents_dir: str):
print(f"✓ 已导入 {len(docs)} 个文档")
print(f"✓ 知识库: {version_path}")
- return kb
+ return ka
```
### 方法 2:增量更新
@@ -90,8 +90,8 @@ def add_documents(self, document_paths: list[str]):
# 加载当前版本
current_path = Path(self.config.kb_dir) / "current"
- kb = Template.create(self.config.template, self.config.language)
- kb.load(current_path)
+ ka = Template.create(self.config.template, self.config.language)
+ ka.load(current_path)
# 添加新文档
for path in document_paths:
@@ -99,20 +99,20 @@ def add_documents(self, document_paths: list[str]):
print(f"添加: {doc_path.name}")
text = doc_path.read_text(encoding="utf-8")
- kb.feed_text(text)
+ ka.feed_text(text)
# 重建索引
print("重建搜索索引...")
- kb.build_index()
+ ka.build_index()
# 保存新版本
version = self._get_next_version()
- version_path = self.save_version(kb, version)
+ version_path = self.save_version(ka, version)
print(f"✓ 已添加 {len(document_paths)} 个文档")
print(f"✓ 新版本: {version}")
- return kb
+ return ka
def _get_next_version(self) -> str:
"""生成下一个版本号。"""
@@ -158,20 +158,20 @@ def main():
if args.initial:
# 初始导入
- kb = manager.initial_ingest(args.dir)
+ ka = manager.initial_ingest(args.dir)
# 打印统计
print("\n知识库统计:")
- print(f" 实体: {len(kb.data.entities)}")
- print(f" 关系: {len(kb.data.relations)}")
+ print(f" 实体: {len(ka.data.entities)}")
+ print(f" 关系: {len(ka.data.relations)}")
elif args.add:
# 添加特定文档
- kb = manager.add_documents(args.add)
+ ka = manager.add_documents(args.add)
print("\n知识库统计:")
- print(f" 实体: {len(kb.data.entities)}")
- print(f" 关系: {len(kb.data.relations)}")
+ print(f" 实体: {len(ka.data.entities)}")
+ print(f" 关系: {len(ka.data.relations)}")
if __name__ == "__main__":
main()
@@ -227,11 +227,11 @@ BATCH_SIZE = 10
for i in range(0, len(docs), BATCH_SIZE):
batch = docs[i:i + BATCH_SIZE]
for doc in batch:
- kb.feed_text(doc.read_text())
+ ka.feed_text(doc.read_text())
# 保存检查点
if i % (BATCH_SIZE * 5) == 0:
- kb.dump(f"./kb/checkpoint_{i}/")
+ ka.dump(f"./ka/checkpoint_{i}/")
```
### 2. 错误处理
@@ -239,7 +239,7 @@ for i in range(0, len(docs), BATCH_SIZE):
```python
try:
text = doc.read_text(encoding="utf-8")
- kb.feed_text(text)
+ ka.feed_text(text)
except Exception as e:
print(f"处理 {doc} 时出错: {e}")
# 记录错误,继续下一个
@@ -249,14 +249,14 @@ except Exception as e:
### 3. 验证
```python
-def validate_ingestion(self, kb):
+def validate_ingestion(self, ka):
"""导入后验证知识库。"""
- assert not kb.empty(), "知识库为空"
- assert len(kb.data.entities) > 0, "未提取到实体"
+ assert not ka.empty(), "知识库为空"
+ assert len(ka.data.entities) > 0, "未提取到实体"
# 尝试构建索引
try:
- kb.build_index()
+ ka.build_index()
except Exception as e:
raise ValueError(f"构建索引失败: {e}")
```
diff --git a/docs/zh/tutorials/knowledge-base/step3-query.md b/docs/zh/tutorials/knowledge-base/step3-query.md
index 603574a..6e33cb7 100644
--- a/docs/zh/tutorials/knowledge-base/step3-query.md
+++ b/docs/zh/tutorials/knowledge-base/step3-query.md
@@ -19,10 +19,10 @@ def search(self, query: str, top_k: int = 5):
"""搜索知识库。"""
current_path = Path(self.config.kb_dir) / "current"
- kb = Template.create(self.config.template, self.config.language)
- kb.load(current_path)
+ ka = Template.create(self.config.template, self.config.language)
+ ka.load(current_path)
- results = kb.search(query, top_k=top_k)
+ results = ka.search(query, top_k=top_k)
return results
```
@@ -33,10 +33,10 @@ def ask(self, question: str, top_k: int = 5):
"""向知识库提问。"""
current_path = Path(self.config.kb_dir) / "current"
- kb = Template.create(self.config.template, self.config.language)
- kb.load(current_path)
+ ka = Template.create(self.config.template, self.config.language)
+ ka.load(current_path)
- response = kb.chat(question, top_k=top_k)
+ response = ka.chat(question, top_k=top_k)
return response.content
```
@@ -63,23 +63,23 @@ class KBQueryShell(cmd.Cmd):
versions - 列出版本
backup - 创建备份
"""
- prompt = "kb> "
+ prompt = "ka> "
def __init__(self):
super().__init__()
self.manager = KnowledgeBaseManager()
- self.kb = None
+ self.ka = None
self._load_kb()
def _load_kb(self):
"""加载当前知识库。"""
current_path = Path(self.manager.config.kb_dir) / "current"
if current_path.exists():
- self.kb = Template.create(
+ self.ka = Template.create(
self.manager.config.template,
self.manager.config.language
)
- self.kb.load(current_path)
+ self.ka.load(current_path)
print(f"已加载: {self.manager.config.name}")
else:
print("警告: 未找到知识库")
@@ -90,11 +90,11 @@ class KBQueryShell(cmd.Cmd):
print("用法: search <query>")
return
- if not self.kb:
+ if not self.ka:
print("未加载知识库")
return
- results = self.kb.search(arg, top_k=5)
+ results = self.ka.search(arg, top_k=5)
print(f"\n找到 {len(results)} 个结果:\n")
for i, item in enumerate(results, 1):
@@ -110,28 +110,28 @@ class KBQueryShell(cmd.Cmd):
print("用法: ask <question>")
return
- if not self.kb:
+ if not self.ka:
print("未加载知识库")
return
print("\n思考中...")
- answer = self.kb.chat(arg).content
+ answer = self.ka.chat(arg).content
print(f"\n{answer}\n")
def do_stats(self, arg):
"""显示知识库统计。"""
- if not self.kb:
+ if not self.ka:
print("未加载知识库")
return
print("\n知识库统计:")
- print(f" 实体: {len(self.kb.data.entities)}")
- print(f" 关系: {len(self.kb.data.relations)}")
+ print(f" 实体: {len(self.ka.data.entities)}")
+ print(f" 关系: {len(self.ka.data.relations)}")
print(f" 模板: {self.manager.config.template}")
# 实体类型
from collections import Counter
- types = Counter(e.type for e in self.kb.data.entities)
+ types = Counter(e.type for e in self.ka.data.entities)
print("\n实体类型:")
for t, count in types.most_common():
print(f" {t}: {count}")
@@ -293,8 +293,8 @@ def export_to_json(self, output_file: str = "kb_export.json"):
"template": self.config.template,
"language": self.config.language
},
- "data": self.kb.data.model_dump(),
- "metadata": self.kb.metadata
+ "data": self.ka.data.model_dump(),
+ "metadata": self.ka.metadata
}
with open(output_file, "w") as f:
@@ -315,11 +315,11 @@ def generate_report(self):
report.append(f"\n名称: {self.config.name}")
report.append(f"模板: {self.config.template}")
report.append(f"\n统计:")
- report.append(f"- 实体: {len(self.kb.data.entities)}")
- report.append(f"- 关系: {len(self.kb.data.relations)}")
+ report.append(f"- 实体: {len(self.ka.data.entities)}")
+ report.append(f"- 关系: {len(self.ka.data.relations)}")
# 实体类型
- types = Counter(e.type for e in self.kb.data.entities)
+ types = Counter(e.type for e in self.ka.data.entities)
report.append("\n## 实体类型")
for t, count in types.most_common():
report.append(f"- {t}: {count}")
diff --git a/docs/zh/tutorials/research-assistant/step1-extract.md b/docs/zh/tutorials/research-assistant/step1-extract.md
index 7bb1973..1de648d 100644
--- a/docs/zh/tutorials/research-assistant/step1-extract.md
+++ b/docs/zh/tutorials/research-assistant/step1-extract.md
@@ -36,7 +36,7 @@ pdftotext paper.pdf paper.md
### 基本提取
```bash
-he parse paper.md -t general/concept_graph -o ./paper_kb/ -l en
+he parse paper.md -t general/concept_graph -o ./paper_kb/ -l zh
```
**功能说明:**
@@ -90,7 +90,7 @@ OUTPUT_DIR = "./paper_kb/"
def main():
# 创建模板
print("创建概念提取模板...")
- ka = Template.create("general/concept_graph", language="en")
+ ka = Template.create("general/concept_graph", language="zh")
# 读取论文
print(f"读取: {PAPER_FILE}")
@@ -177,7 +177,7 @@ python step1_extract.py
### "未提取到实体"
- 检查论文不为空:`wc -l paper.md`
-- 尝试不同模板:`general/knowledge_graph`
+- 尝试不同模板:`general/graph`
- 检查语言设置与文档匹配
### "提取速度慢"
diff --git a/docs/zh/tutorials/research-assistant/step2-search.md b/docs/zh/tutorials/research-assistant/step2-search.md
index 71c0f64..d8bb892 100644
--- a/docs/zh/tutorials/research-assistant/step2-search.md
+++ b/docs/zh/tutorials/research-assistant/step2-search.md
@@ -24,19 +24,19 @@
### 基本搜索
```bash
-he search ./paper_kb/ "attention mechanism"
+he search ./paper_kb/ "注意力机制"
```
### 自然语言查询
```bash
-he search ./paper_kb/ "What are the main contributions?"
+he search ./paper_kb/ "主要贡献是什么?"
```
### 获取更多结果
```bash
-he search ./paper_kb/ "transformer architecture" -n 10
+he search ./paper_kb/ "Transformer 架构" -n 10
```
---
@@ -58,7 +58,7 @@ KB_DIR = "./paper_kb/"
def main():
# 加载知识库
print("加载知识库...")
- ka = Template.create("general/concept_graph", language="en")
+ ka = Template.create("general/concept_graph", language="zh")
ka.load(KB_DIR)
# 确保索引已构建
@@ -137,16 +137,16 @@ python step2_search.py
| 查询类型 | 示例 | 使用时机 |
|----------|------|---------|
-| 概念 | "attention mechanism" | 查找特定概念 |
-| 问题 | "What are the main contributions?" | 广泛探索 |
-| 比较 | "transformer vs rnn" | 查找比较 |
-| 结果 | "bleu score results" | 查找特定数据 |
+| 概念 | "注意力机制" | 查找特定概念 |
+| 问题 | "主要贡献是什么?" | 广泛探索 |
+| 比较 | "Transformer 与 RNN 的比较" | 查找比较 |
+| 结果 | "BLEU 分数结果" | 查找特定数据 |
### 改进结果
-1. **具体化**: "transformer encoder" vs "transformer"
-2. **使用自然语言**: "How does attention work?"
-3. **尝试同义词**: "attention" → "self-attention" → "query-key-value"
+1. **具体化**: "Transformer 编码器" vs "Transformer"
+2. **使用自然语言**: "注意力机制如何工作?"
+3. **尝试同义词**: "注意力" → "自注意力" → "查询-键-值"
4. **增加 top_k**: `top_k=10` 以获得更广泛的结果
---
@@ -155,9 +155,9 @@ python step2_search.py
```python
class ResearchSearch:
- def __init__(self, kb_path):
- self.ka = Template.create("general/concept_graph", "en")
- self.ka.load(kb_path)
+ def __init__(self, ka_path):
+ self.ka = Template.create("general/concept_graph", "zh")
+ self.ka.load(ka_path)
self.ka.build_index()
def find_concepts(self, query, n=5):
@@ -174,7 +174,7 @@ class ResearchSearch:
# 使用
search = ResearchSearch("./paper_kb/")
-concepts = search.find_concepts("attention", n=10)
+concepts = search.find_concepts("注意力", n=10)
```
---
diff --git a/docs/zh/tutorials/research-assistant/step3-chat.md b/docs/zh/tutorials/research-assistant/step3-chat.md
index f155dec..fd74fc2 100644
--- a/docs/zh/tutorials/research-assistant/step3-chat.md
+++ b/docs/zh/tutorials/research-assistant/step3-chat.md
@@ -24,7 +24,7 @@
### 单问题
```bash
-he talk ./paper_kb/ -q "What are the main contributions of this paper?"
+he talk ./paper_kb/ -q "这篇论文的主要贡献是什么?"
```
### 交互模式
@@ -37,17 +37,15 @@ he talk ./paper_kb/ -i
```
进入交互模式。输入 'exit' 或 'quit' 停止。
-> What is the Transformer architecture?
+> Transformer 架构是什么?
-The Transformer is a novel neural network architecture introduced in
-this paper that relies entirely on attention mechanisms, dispensing
-with recurrence and convolutions entirely...
+Transformer 是这篇论文提出的一种全新的神经网络架构,
+完全依赖注意力机制,彻底摒弃了循环和卷积结构...
-> How does it compare to RNNs?
+> 它与 RNN 相比有何优势?
-Unlike RNNs, which process sequences sequentially, the Transformer
-processes all positions in parallel, making it more efficient for
-training on large datasets...
+与按顺序处理序列的 RNN 不同,Transformer 可以并行处理所有位置,
+这使得它在大型数据集上的训练更加高效...
> exit
```
@@ -69,10 +67,10 @@ from hyperextract import Template
KB_DIR = "./paper_kb/"
class ResearchAssistant:
- def __init__(self, kb_path):
+ def __init__(self, ka_path):
print("加载研究助手...")
- self.ka = Template.create("general/concept_graph", "en")
- self.ka.load(kb_path)
+ self.ka = Template.create("general/concept_graph", "zh")
+ self.ka.load(ka_path)
self.ka.build_index()
print("✓ 准备就绪!\n")
@@ -175,10 +173,10 @@ def ask_with_citations(assistant, question):
def suggest_questions(assistant):
"""基于论文内容建议问题。"""
suggestions = [
- "What are the main contributions?",
- "What problem does this solve?",
- "What are the key results?",
- "How does this compare to prior work?",
+ "这篇论文的主要贡献是什么?",
+ "它解决了什么问题?",
+ "关键结果有哪些?",
+ "与之前的工作相比有何不同?",
]
return suggestions
```
@@ -208,7 +206,7 @@ from pathlib import Path
class ResearchAssistantApp:
def __init__(self, paper_path, kb_dir="./paper_kb/"):
self.paper_path = paper_path
- self.kb_dir = kb_dir
+ self.ka_dir = kb_dir
self.ka = None
# 加载或创建知识库
@@ -220,18 +218,18 @@ class ResearchAssistantApp:
def _create_kb(self):
"""从论文创建知识库。"""
print("创建知识库...")
- ka = Template.create("general/concept_graph", "en")
+ ka = Template.create("general/concept_graph", "zh")
text = Path(self.paper_path).read_text()
self.ka = ka.parse(text)
self.ka.build_index()
- self.ka.dump(self.kb_dir)
+ self.ka.dump(self.ka_dir)
print("✓ 知识库已创建\n")
def _load_kb(self):
"""加载现有知识库。"""
print("加载知识库...")
- self.ka = Template.create("general/concept_graph", "en")
- self.ka.load(self.kb_dir)
+ self.ka = Template.create("general/concept_graph", "zh")
+ self.ka.load(self.ka_dir)
print("✓ 知识库已加载\n")
def search(self, query):
@@ -245,7 +243,9 @@ class ResearchAssistantApp:
def visualize(self):
"""打开可视化。"""
self.ka.show()
-
+
+![交互式可视化](../../../../assets/zh_show.png)
+
def run(self):
"""运行交互式会话。"""
print("="*60)
diff --git a/docs_hooks.py b/docs_hooks.py
new file mode 100644
index 0000000..75c6407
--- /dev/null
+++ b/docs_hooks.py
@@ -0,0 +1,48 @@
+"""MkDocs hooks for documentation build adjustments."""
+
+import logging
+
+
+class SuppressDuplicatePrimaryURLFilter(logging.Filter):
+ """Silences mkdocstrings-autorefs "Multiple primary URLs found" warnings.
+
+ These warnings are expected in bilingual (i18n) builds because the same
+ Python identifier is documented in both the default and translated API
+ reference pages. The duplicate-primary-URL warning is noise in this
+ context and does not indicate a real cross-reference error.
+ """
+
+ def filter(self, record: logging.LogRecord) -> bool:
+ return "Multiple primary URLs found" not in record.getMessage()
+
+
+def _suppress_autorefs_duplicates():
+ """Apply logging filter to all mkdocs_autorefs loggers.
+
+ mkdocs_autorefs uses child loggers such as
+ ``mkdocs.plugins.mkdocs_autorefs._internal.references``. We must attach
+ the filter to every concrete logger that emits the warning.
+ """
+ target_prefix = "mkdocs.plugins.mkdocs_autorefs"
+ filter_obj = SuppressDuplicatePrimaryURLFilter()
+
+ for name, logger in logging.Logger.manager.loggerDict.items():
+ if name.startswith(target_prefix) and isinstance(logger, logging.Logger):
+ if not any(isinstance(f, SuppressDuplicatePrimaryURLFilter) for f in logger.filters):
+ logger.addFilter(filter_obj)
+
+ # Also cover the parent logger itself
+ parent = logging.getLogger(target_prefix)
+ if not any(isinstance(f, SuppressDuplicatePrimaryURLFilter) for f in parent.filters):
+ parent.addFilter(filter_obj)
+
+
+def on_config(config, **kwargs):
+ """Apply logging filters after configuration is loaded."""
+ _suppress_autorefs_duplicates()
+ return config
+
+
+def on_pre_build(config, **kwargs):
+ """Re-apply filter right before build starts (plugins may recreate loggers)."""
+ _suppress_autorefs_duplicates()
diff --git a/examples/en/templates/general_template.py b/examples/en/templates/general_template.py
index 204d35d..6fb2e85 100644
--- a/examples/en/templates/general_template.py
+++ b/examples/en/templates/general_template.py
@@ -20,7 +20,7 @@ dotenv.load_dotenv()
# // test for Base Knowledge Graph
test_data_file = "arbitrary_tech_news.md"
-template_name = "general/base_graph"
+template_name = "general/graph"
# // test for Base Hypergraph
# test_data_file = "encyclopedia_machine_learning.md"
@@ -28,7 +28,7 @@ template_name = "general/base_graph"
# // test for Base List
# test_data_file = "regulation_company_policy.md"
-# template_name = "general/base_list"
+# template_name = "general/list"
# // test for Biography Graph
# test_data_file = "biography_scientist.md"
diff --git a/examples/en/templates/list_templates.py b/examples/en/templates/list_templates.py
index e1f2c90..1df2639 100644
--- a/examples/en/templates/list_templates.py
+++ b/examples/en/templates/list_templates.py
@@ -45,7 +45,7 @@ def list_templates():
print(" python examples/en/templates/run_template.py -d <domain> -t <template_name>")
print("\nExamples:")
print(" python examples/en/templates/run_template.py -d finance -t earnings_summary")
- print(" python examples/en/templates/run_template.py -d general -t base_graph")
+ print(" python examples/en/templates/run_template.py -d general -t graph")
print("\n" + "=" * 80 + "\n")
diff --git a/examples/zh/templates/general_template.py b/examples/zh/templates/general_template.py
index 2584ac6..fb9cafd 100644
--- a/examples/zh/templates/general_template.py
+++ b/examples/zh/templates/general_template.py
@@ -20,7 +20,7 @@ dotenv.load_dotenv()
# // test for 基础知识图谱
test_data_file = "arbitrary_tech_news.md"
-template_name = "general/base_graph"
+template_name = "general/graph"
# // test for 基础超图
# test_data_file = "encyclopedia_machine_learning.md"
@@ -28,7 +28,7 @@ template_name = "general/base_graph"
# // test for 基础列表
# test_data_file = "regulation_company_policy.md"
-# template_name = "general/base_list"
+# template_name = "general/list"
# // test for 传记图谱
# test_data_file = "biography_scientist.md"
diff --git a/examples/zh/templates/list_templates.py b/examples/zh/templates/list_templates.py
index 02cf0c4..ded5c71 100644
--- a/examples/zh/templates/list_templates.py
+++ b/examples/zh/templates/list_templates.py
@@ -45,7 +45,7 @@ def list_templates():
print(" python examples/templates/run_template.py -d <domain> -t <template_name>")
print("\n示例:")
print(" python examples/templates/run_template.py -d finance -t earnings_summary")
- print(" python examples/templates/run_template.py -d general -t base_graph")
+ print(" python examples/templates/run_template.py -d general -t graph")
print("\n" + "=" * 80 + "\n")
diff --git a/hyperextract/__init__.py b/hyperextract/__init__.py
index 1926a15..399c5fa 100644
--- a/hyperextract/__init__.py
+++ b/hyperextract/__init__.py
@@ -10,13 +10,15 @@ Architecture:
Usage:
from hyperextract import Template
-
- # Search templates
+
+ # List available templates
Template.list()
- Template.search("知识图谱")
-
- # Create template (auto reads config from ~/.he/config.toml)
- template = Template.create("knowledge_graph")
+
+ # 1. Create knowledge template (auto reads config from ~/.he/config.toml)
+ template = Template.create("general/graph", language="zh")
+
+ # 2. Create method template (language always "en")
+ template = Template.create("method/light_rag")
"""
# Core AutoType primitives
diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.py
index 4a56129..d45f638 100644
--- a/hyperextract/cli/cli.py
+++ b/hyperextract/cli/cli.py
@@ -22,7 +22,7 @@ from .utils import (
get_template_from_ka,
)
from .config import (
- load_kb_metadata,
+ load_ka_metadata,
)
from .commands import list_app, config_app
@@ -246,7 +246,7 @@ def parse(
with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}"), console=console) as progress:
task = progress.add_task("Creating template instance...", total=None)
- kb = Template.create(template, lang)
+ ka = Template.create(template, lang)
if input_path.is_dir():
progress.update(task, description="Processing directory...")
@@ -265,14 +265,14 @@ def parse(
console.print(f"[dim]Total input: {len(combined_text)} characters[/dim]")
progress.update(task, description="Extracting knowledge...")
- kb.feed_text(combined_text)
+ ka.feed_text(combined_text)
else:
progress.update(task, description="Reading input...")
text = read_input(input)
console.print(f"[dim]Input text: {len(text)} characters[/dim]")
progress.update(task, description="Extracting knowledge...")
- kb.feed_text(text)
+ ka.feed_text(text)
progress.update(task, description="Saving data...")
@@ -282,26 +282,28 @@ def parse(
import shutil
filename = Path(template).name
shutil.copy(template, output_path / filename)
- console.print(f"[dim]Custom template '{filename}' saved to KB directory[/dim]")
+ console.print(f"[dim]Custom template '{filename}' saved to KA directory[/dim]")
- kb.dump(output_path)
+ ka.dump(output_path)
if not no_index:
progress.update(task, description="Building search index...")
- kb.build_index()
+ ka.build_index()
console.print("[dim]Index built successfully[/dim]")
progress.update(task, description="Saving index...")
- kb.dump(output_path)
+ ka.dump(output_path)
console.print()
console.print(f"[bold green]Success![/bold green] Knowledge extracted to {output_path}")
console.print()
if no_index:
console.print("[dim]Note: Index was not built.[/dim]")
- console.print(f"[dim] he build-index {output} # Build index to enable search/talk[/dim]")
+ console.print(f"[dim] he build-index {output} # Build index to enable search/talk[/dim]")
+ console.print(f"[dim] he feed {output} <new_document> # Append more documents[/dim]")
else:
console.print("[dim]What's next?[/dim]")
console.print(f"[dim] he show {output} # Visualize knowledge graph[/dim]")
+ console.print(f"[dim] he feed {output} <new_document> # Append more documents[/dim]")
console.print(f"[dim] he search {output} \"keyword\" # Semantic search[/dim]")
console.print(f"[dim] he talk {output} -i # Interactive chat[/dim]")
console.print(f"[dim] he talk {output} -q \"your question\" # Single query[/dim]")
@@ -322,8 +324,8 @@ def show(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory")
with console.status("[bold blue]Loading Knowledge Abstract..."):
try:
- kb = Template.create(template, lang)
- kb.load(path)
+ ka = Template.create(template, lang)
+ ka.load(path)
except Exception as e:
console.print(f"[red]Error loading Knowledge Abstract:[/red] {e}")
@@ -332,7 +334,7 @@ def show(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory")
console.print("[bold blue]Visualizing with OntoSight...[/bold blue]")
try:
- kb.show()
+ ka.show()
except Exception as e:
console.print(f"[red]Error during visualization:[/red] {e}")
raise typer.Exit(1)
@@ -350,7 +352,7 @@ def info(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory")
path = validate_ka_with_data(ka_path)
- metadata = load_kb_metadata(path)
+ metadata = load_ka_metadata(path)
data_file = path / "data.json"
with open(data_file, "r", encoding="utf-8") as f:
@@ -413,13 +415,13 @@ def search(
task = progress.add_task("Searching...", total=None)
try:
- kb = Template.create(template, lang)
+ ka = Template.create(template, lang)
progress.update(task, description="Loading Knowledge Abstract...")
- kb.load(path)
+ ka.load(path)
progress.update(task, description="Searching...")
- results = kb.search(query, top_k=top_k)
+ results = ka.search(query, top_k=top_k)
except Exception as e:
console.print(f"[red]Error:[/red] {e}")
@@ -448,7 +450,7 @@ def search(
console.print(f"[dim] he show {ka_path} # Visualize[/dim]")
-def chat_loop(kb, ka_path: str):
+def chat_loop(ka, ka_path: str):
"""Interactive chat loop."""
console.print("\n[bold green]Entering interactive mode. Type 'exit' or 'quit' to stop.[/bold green]\n")
while True:
@@ -464,7 +466,7 @@ def chat_loop(kb, ka_path: str):
break
if not query.strip():
continue
- response = kb.chat(query)
+ response = ka.chat(query)
console.print()
console.print(response.content)
console.print()
@@ -511,21 +513,21 @@ def talk(
task = progress.add_task("Loading...", total=None)
try:
- kb = Template.create(template, lang)
+ ka = Template.create(template, lang)
progress.update(task, description="Loading Knowledge Abstract...")
- kb.load(path)
+ ka.load(path)
except Exception as e:
console.print(f"[red]Error:[/red] {e}")
raise typer.Exit(1)
if interactive:
- chat_loop(kb, ka_path)
+ chat_loop(ka, ka_path)
else:
with console.status("[bold blue]Thinking..."):
try:
- response = kb.chat(query, top_k=top_k)
+ response = ka.chat(query, top_k=top_k)
console.print(response.content)
if response.additional_kwargs.get("retrieved_items"):
@@ -557,13 +559,13 @@ def feed(
output_path = validate_ka_path(ka_path)
- metadata = load_kb_metadata(output_path)
+ metadata = load_ka_metadata(output_path)
if not metadata:
console.print(f"[red]Error:[/red] Not a valid Knowledge Abstract directory: {ka_path}")
raise typer.Exit(1)
if template is None:
- template = metadata.get("template", "knowledge_graph")
+ template = metadata.get("template", "general/graph")
if lang is None:
lang = metadata.get("lang", "zh")
@@ -574,7 +576,7 @@ def feed(
console.print()
try:
- kb = Template.create(template, lang)
+ ka = Template.create(template, lang)
console.print(f"[green]Template loaded:[/green] {template}")
except ValueError as e:
console.print(f"[red]Error:[/red] {e}")
@@ -583,17 +585,17 @@ def feed(
with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}"), console=console) as progress:
task = progress.add_task("Loading existing knowledge...", total=None)
- kb.load(output_path)
+ ka.load(output_path)
progress.update(task, description="Reading input...")
text = read_input(input)
console.print(f"[dim]Input text: {len(text)} characters[/dim]")
progress.update(task, description="Appending knowledge...")
- kb.feed_text(text)
+ ka.feed_text(text)
progress.update(task, description="Saving data...")
- kb.dump(output_path)
+ ka.dump(output_path)
console.print()
console.print(f"[bold green]Success![/bold green] Knowledge appended to {output_path}")
@@ -629,20 +631,20 @@ def build_index(
task = progress.add_task("Initializing...", total=None)
try:
- kb = Template.create(template, lang)
+ ka = Template.create(template, lang)
progress.update(task, description="Loading Knowledge Abstract...")
- kb.load(path)
+ ka.load(path)
if force:
console.print("[dim]Force rebuild: clearing existing index...[/dim]")
- kb.clear_index()
+ ka.clear_index()
progress.update(task, description="Building index...")
- kb.build_index()
+ ka.build_index()
progress.update(task, description="Saving index...")
- kb.dump(path)
+ ka.dump(path)
except Exception as e:
console.print(f"[red]Error:[/red] {e}")
diff --git a/hyperextract/cli/config.py b/hyperextract/cli/config.py
index 819c1a9..13c001a 100644
--- a/hyperextract/cli/config.py
+++ b/hyperextract/cli/config.py
@@ -170,9 +170,9 @@ class ConfigManager:
return True, "Configuration is valid"
-def load_kb_metadata(kb_path: Path) -> Optional[Dict[str, Any]]:
- """Load knowledge base metadata from directory."""
- metadata_path = kb_path / "metadata.json"
+def load_ka_metadata(ka_path: Path) -> Optional[Dict[str, Any]]:
+ """Load knowledge abstract metadata from directory."""
+ metadata_path = ka_path / "metadata.json"
if not metadata_path.exists():
return None
diff --git a/hyperextract/methods/rag/cog_rag.py b/hyperextract/methods/rag/cog_rag.py
index 89c6a3c..408f3ef 100644
--- a/hyperextract/methods/rag/cog_rag.py
+++ b/hyperextract/methods/rag/cog_rag.py
@@ -437,7 +437,7 @@ class Cog_RAG:
context = "\n".join(context_parts)
prompt = ChatPromptTemplate.from_template(
- "You are an intelligent assistant using a Dual-Layer Hypergraph Knowledge Base.\n"
+ "You are an intelligent assistant using a Dual-Layer Hypergraph Knowledge Abstract.\n"
"Use the provided Themes (Macro) and Key Entities (Micro) to answer the user's question comprehensively.\n\n"
"{context}\n\n"
"Question: {question}\n\n"
diff --git a/hyperextract/templates/__init__.py b/hyperextract/templates/__init__.py
index cbd424a..4ce267a 100644
--- a/hyperextract/templates/__init__.py
+++ b/hyperextract/templates/__init__.py
@@ -10,7 +10,7 @@
>>> from hyperextract.utils.template_engine import Template
# 使用preset模板
- >>> template = Template.create("general/knowledge_graph", "zh", llm, embedder)
+ >>> template = Template.create("general/graph", "zh", llm, embedder)
# 使用自定义模板(文件路径)
>>> template = Template.create("/path/to/my_template.yaml", "zh", llm, embedder)
diff --git a/hyperextract/types/base.py b/hyperextract/types/base.py
index 7fa5a9a..1e1834c 100644
--- a/hyperextract/types/base.py
+++ b/hyperextract/types/base.py
@@ -14,11 +14,11 @@ from langchain_text_splitters import RecursiveCharacterTextSplitter
T = TypeVar("T", bound=BaseModel)
-# ===================== Knowledge Base Class =====================
+# ===================== Knowledge Abstract Class =====================
class BaseAutoType(ABC, Generic[T]):
- """Unified knowledge base class integrating extraction, storage, and aggregation.
+ """Unified knowledge abstract class integrating extraction, storage, and aggregation.
This abstract base class provides a complete framework for managing structured knowledge
extracted from text. It handles the full lifecycle from extraction to serialization.
@@ -145,7 +145,7 @@ class BaseAutoType(ABC, Generic[T]):
@abstractmethod
def empty(self) -> bool:
- """Checks if the knowledge base is currently empty.
+ """Checks if the knowledge abstract is currently empty.
Returns:
True if no data is stored, False otherwise.
@@ -261,7 +261,7 @@ class BaseAutoType(ABC, Generic[T]):
"""
Parses knowledge into a NEW instance without modifying the current one.
- Use this for previewing data or branching knowledge bases.
+ Use this for previewing data or branching knowledge abstracts.
Args:
text: Input text.
@@ -281,10 +281,10 @@ class BaseAutoType(ABC, Generic[T]):
def feed_text(self, text: str) -> "BaseAutoType[T]":
"""
- Ingests text into the CURRENT knowledge base instance.
+ Ingests text into the CURRENT knowledge abstract instance.
This modifies the internal state by merging new data with existing data.
- Supports method chaining (e.g., kb.feed_text(text1).feed_text(text2)).
+ Supports method chaining (e.g., ka.feed_text(text1).feed_text(text2)).
Args:
text: Input text.
@@ -336,7 +336,7 @@ class BaseAutoType(ABC, Generic[T]):
@abstractmethod
def search(self, query: str, top_k: int = 3) -> List[Any]:
- """Performs semantic search over the knowledge base.
+ """Performs semantic search over the knowledge abstract.
Standard search workflow:
1. Ensure index is built (call build_index if needed)
@@ -355,7 +355,7 @@ class BaseAutoType(ABC, Generic[T]):
pass
def chat(self, query: str, top_k: int = 3) -> AIMessage:
- """Performs a chat-like interaction with the knowledge base.
+ """Performs a chat-like interaction with the knowledge abstract.
This generic method retrieves relevant items and generates a response.
Subclasses with complex data structures (like graphs) should override this
@@ -368,14 +368,14 @@ class BaseAutoType(ABC, Generic[T]):
Returns:
An AIMessage object containing the LLM-generated response.
"""
- # Step 1: Retrieve relevant items from knowledge base
+ # Step 1: Retrieve relevant items from knowledge abstract
search_results = self.search(query, top_k)
# Step 2: Format context from retrieved items
formatted_context = []
if not search_results:
- context = "No relevant information found in the knowledge base."
+ context = "No relevant information found in the knowledge abstract."
else:
for item in search_results:
if isinstance(item, BaseModel):
@@ -394,7 +394,7 @@ class BaseAutoType(ABC, Generic[T]):
# Step 3: Create QA prompt template and invoke LLM
qa_prompt = ChatPromptTemplate.from_template(
- "Based on the following context from the knowledge base, answer the user's question.\n\n"
+ "Based on the following context from the knowledge abstract, answer the user's question.\n\n"
"Context:\n{context}\n\n"
"Question: {question}\n\n"
"Answer:"
@@ -415,7 +415,7 @@ class BaseAutoType(ABC, Generic[T]):
# ==================== Serialization: Orchestrator ====================
def dump(self, folder_path: str | Path) -> None:
- """Saves the entire knowledge base (data, metadata, index) to a directory.
+ """Saves the entire knowledge abstract (data, metadata, index) to a directory.
This is the main entry point for serialization. It creates a directory structure:
/folder_path
@@ -448,14 +448,14 @@ class BaseAutoType(ABC, Generic[T]):
print(f"Warning: Failed to save vector index: {e}")
def load(self, folder_path: str | Path) -> None:
- """Loads the entire knowledge base from a directory.
+ """Loads the entire knowledge abstract from a directory.
Args:
folder_path: Source directory path.
"""
root = Path(folder_path)
if not root.exists():
- raise FileNotFoundError(f"Knowledge base directory not found: {root}")
+ raise FileNotFoundError(f"Knowledge abstract directory not found: {root}")
# 1. Load Core Data (Critical)
self.load_data(root / "data.json")
diff --git a/hyperextract/types/graph.py b/hyperextract/types/graph.py
index bc9ecbb..234cbcb 100644
--- a/hyperextract/types/graph.py
+++ b/hyperextract/types/graph.py
@@ -790,7 +790,7 @@ class AutoGraph(
Example:
>>> # Chat using 5 nodes and 2 edges as context
- >>> response = kb.chat("What is X?", top_k_nodes=5, top_k_edges=2)
+ >>> response = ka.chat("What is X?", top_k_nodes=5, top_k_edges=2)
>>> print(response.content) # Print the generated answer
"""
if top_k is not None:
@@ -830,7 +830,7 @@ class AutoGraph(
# Step 4: Combine context or use fallback
if not context_parts:
- context = "No relevant information found in the knowledge base."
+ context = "No relevant information found in the knowledge abstract."
else:
context = "\n\n".join(context_parts)
diff --git a/hyperextract/types/hypergraph.py b/hyperextract/types/hypergraph.py
index b0aaa15..d758800 100644
--- a/hyperextract/types/hypergraph.py
+++ b/hyperextract/types/hypergraph.py
@@ -774,7 +774,7 @@ class AutoHypergraph(
# Step 4: Combine context or use fallback
if not context_parts:
- context = "No relevant information found in the knowledge base."
+ context = "No relevant information found in the knowledge abstract."
else:
context = "\n\n".join(context_parts)
diff --git a/hyperextract/types/model.py b/hyperextract/types/model.py
index f82835e..baa06a7 100644
--- a/hyperextract/types/model.py
+++ b/hyperextract/types/model.py
@@ -400,7 +400,7 @@ class AutoModel(BaseAutoType[T]):
)
# Create new AutoList
- list_kb = AutoList(
+ list_ka = AutoList(
item_schema=self._data_schema,
llm_client=self.llm_client,
embedder=self.embedder,
@@ -412,15 +412,15 @@ class AutoModel(BaseAutoType[T]):
)
# Set items from both units
- list_kb._data.items = [self._data, other._data]
+ list_ka._data.items = [self._data, other._data]
# Merge metadata
- list_kb.metadata["created_at"] = min(
+ list_ka.metadata["created_at"] = min(
self.metadata["created_at"], other.metadata["created_at"]
)
- list_kb.metadata["updated_at"] = datetime.now()
+ list_ka.metadata["updated_at"] = datetime.now()
- return list_kb
+ return list_ka
# Case 2: AutoModel + AutoList → AutoList (prepend model)
elif isinstance(other, AutoList):
diff --git a/hyperextract/utils/template_engine/factory.py b/hyperextract/utils/template_engine/factory.py
index 3d96a56..11e4251 100644
--- a/hyperextract/utils/template_engine/factory.py
+++ b/hyperextract/utils/template_engine/factory.py
@@ -388,12 +388,12 @@ class TemplateFactory:
"""Create template instance based on configuration.
Supports both knowledge templates and method templates:
- - Knowledge templates: "general/knowledge_graph", "/path/to/template.yaml"
+ - 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., "knowledge_graph", "method/light_rag") or file path
+ - 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
@@ -408,7 +408,7 @@ class TemplateFactory:
Examples:
# Knowledge template by name (language required)
- template = TemplateFactory.create("knowledge_graph", "zh", llm, embedder)
+ template = TemplateFactory.create("general/graph", "zh", llm, embedder)
# Method template (language ignored, always "en")
template = TemplateFactory.create("method/light_rag", llm=llm, embedder=embedder)
diff --git a/hyperextract/utils/template_engine/gallery.py b/hyperextract/utils/template_engine/gallery.py
index 4d827e7..5cd595c 100644
--- a/hyperextract/utils/template_engine/gallery.py
+++ b/hyperextract/utils/template_engine/gallery.py
@@ -16,7 +16,7 @@ class Gallery:
from hyperextract.utils.template_engine import Gallery
# Get template by path
- config = Gallery.get("general/knowledge_graph")
+ config = Gallery.get("general/graph")
# List all templates (returns Dict[str, TemplateCfg])
all_templates = Gallery.list()
@@ -37,10 +37,10 @@ class Gallery:
Args:
path: Template path
- If no domain is specified, "general/" is assumed.
+ If no domain is specified, "general/" is assumed.
Only templates in the "general/" domain are supported.
Other domains are not supported.
- (e.g., "general/knowledge_graph" or "knowledge_graph")
+ (e.g., "general/graph" or "graph")
Returns:
TemplateCfg or None if not found
diff --git a/hyperextract/utils/template_engine/template.py b/hyperextract/utils/template_engine/template.py
index 1e53323..2217788 100644
--- a/hyperextract/utils/template_engine/template.py
+++ b/hyperextract/utils/template_engine/template.py
@@ -21,11 +21,11 @@ class Template:
from hyperextract.utils.template_engine import Template
# Create template instance (2 ways)
- template = Template.create("general/knowledge_graph", llm, emb)
+ template = Template.create("general/graph", llm, emb)
template = Template.create("/path/to/template.yaml", llm, emb)
# Get template config by path
- config = Template.get("general/knowledge_graph")
+ config = Template.get("general/graph")
# List all templates (returns Dict[str, TemplateCfg])
all_templates = Template.list()
@@ -46,7 +46,7 @@ class Template:
"""Create template instance.
Args:
- source: Template path (e.g., "general/knowledge_graph", "method/light_rag") or file path
+ source: Template path (e.g., "general/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")
@@ -59,7 +59,7 @@ class Template:
Examples:
# Knowledge template (language required)
- template = Template.create("general/knowledge_graph", "zh", llm, emb)
+ template = Template.create("general/graph", "zh", llm, emb)
# Method template (language ignored, always "en")
template = Template.create("method/light_rag", llm_client=llm, embedder=embedder)
@@ -69,7 +69,7 @@ class Template:
# For temporal/spatial templates
template = Template.create(
- "finance/financial_data_temporal_graph",
+ "finance/event_timeline",
"zh",
llm,
emb,
@@ -92,7 +92,7 @@ class Template:
"""Get template configuration by path.
Args:
- path: Template path (e.g., "general/knowledge_graph" or "method/light_rag")
+ path: Template path (e.g., "general/graph" or "method/light_rag")
Returns:
TemplateCfg or None if not found
diff --git a/mkdocs.yml b/mkdocs.yml
index 8797727..6117e59 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -9,6 +9,9 @@ repo_name: yifanfeng97/hyper-extract
repo_url: https://github.com/yifanfeng97/hyper-extract
edit_uri: edit/main/docs/
+hooks:
+ - docs_hooks.py
+
theme:
name: material
language: en
@@ -38,7 +41,7 @@ plugins:
paths: [hyperextract]
options:
docstring_style: google
- show_source: true
+ show_source: false
show_root_heading: true
show_object_full_path: false
show_category_heading: true
@@ -47,7 +50,7 @@ plugins:
group_by_category: true
filters:
- "!^_" # Hide private methods
- merge_init_into_class: true
+ merge_init_into_class: false
show_signature_annotations: true
- i18n:
docs_structure: folder
@@ -69,12 +72,12 @@ plugins:
- cli/workflow.md
- Commands:
- cli/commands/parse.md
+ - cli/commands/feed.md
- cli/commands/show.md
+ - cli/commands/build-index.md
- cli/commands/search.md
- cli/commands/talk.md
- - cli/commands/feed.md
- cli/commands/info.md
- - cli/commands/build-index.md
- cli/commands/list.md
- cli/commands/config.md
- cli/configuration.md
@@ -84,16 +87,22 @@ plugins:
- python/core-concepts.md
- Guides:
- python/guides/using-templates.md
- - python/guides/choosing-methods.md
+ - python/guides/using-methods.md
- python/guides/working-with-autotypes.md
- python/guides/custom-templates.md
- python/guides/search-and-chat.md
- python/guides/incremental-updates.md
- python/guides/saving-loading.md
- API Reference:
- - python/api-reference/template.md
- - python/api-reference/autotypes.md
- - python/api-reference/methods.md
+ - Template API: python/api-reference/template.md
+ - Auto-Types:
+ - Base Type: python/api-reference/autotypes/base.md
+ - Record Types: python/api-reference/autotypes/structures.md
+ - Graph Types: python/api-reference/autotypes/graphs.md
+ - Methods:
+ - Registry: python/api-reference/methods/registry.md
+ - Typical Methods: python/api-reference/methods/typical.md
+ - RAG Methods: python/api-reference/methods/rag.md
- Concepts:
- concepts/index.md
- concepts/architecture.md
@@ -102,14 +111,22 @@ plugins:
- concepts/templates-format.md
- Templates:
- templates/index.md
- - templates/how-to-choose.md
- - templates/browse.md
- - General: templates/general/index.md
- - Finance: templates/finance.md
- - Legal: templates/legal.md
- - Medical: templates/medicine.md
- - TCM: templates/tcm.md
- - Industry: templates/industry.md
+ - Choosing:
+ - templates/how-to-choose.md
+ - templates/choosing/by-task.md
+ - templates/choosing/by-output.md
+ - Examples:
+ - templates/examples/research-paper.md
+ - templates/examples/financial-report.md
+ - templates/examples/legal-contract.md
+ - Reference:
+ - templates/reference/overview.md
+ - General: templates/reference/general.md
+ - Finance: templates/reference/finance.md
+ - Legal: templates/reference/legal.md
+ - Medical: templates/reference/medicine.md
+ - TCM: templates/reference/tcm.md
+ - Industry: templates/reference/industry.md
- Resources:
- resources/index.md
- resources/faq.md
@@ -143,12 +160,12 @@ plugins:
- zh/cli/workflow.md
- 命令详解:
- zh/cli/commands/parse.md
+ - zh/cli/commands/feed.md
- zh/cli/commands/show.md
+ - zh/cli/commands/build-index.md
- zh/cli/commands/search.md
- zh/cli/commands/talk.md
- - zh/cli/commands/feed.md
- zh/cli/commands/info.md
- - zh/cli/commands/build-index.md
- zh/cli/commands/list.md
- zh/cli/commands/config.md
- zh/cli/configuration.md
@@ -158,15 +175,22 @@ plugins:
- zh/python/core-concepts.md
- 使用指南:
- zh/python/guides/using-templates.md
- - zh/python/guides/choosing-methods.md
+ - zh/python/guides/using-methods.md
- zh/python/guides/working-with-autotypes.md
+ - zh/python/guides/custom-templates.md
- zh/python/guides/search-and-chat.md
- zh/python/guides/incremental-updates.md
- zh/python/guides/saving-loading.md
- API 参考:
- - zh/python/api-reference/template.md
- - zh/python/api-reference/autotypes.md
- - zh/python/api-reference/methods.md
+ - Template API: zh/python/api-reference/template.md
+ - 自动类型:
+ - 基础类型: zh/python/api-reference/autotypes/base.md
+ - 记录类型: zh/python/api-reference/autotypes/structures.md
+ - 图谱类型: zh/python/api-reference/autotypes/graphs.md
+ - 方法:
+ - 注册表: zh/python/api-reference/methods/registry.md
+ - 典型方法: zh/python/api-reference/methods/typical.md
+ - RAG 方法: zh/python/api-reference/methods/rag.md
- 核心概念:
- zh/concepts/index.md
- zh/concepts/architecture.md
@@ -175,14 +199,22 @@ plugins:
- zh/concepts/templates-format.md
- 模板库:
- zh/templates/index.md
- - zh/templates/how-to-choose.md
- - zh/templates/browse.md
- - 通用: zh/templates/general/index.md
- - 金融: zh/templates/finance.md
- - 法律: zh/templates/legal.md
- - 医学: zh/templates/medicine.md
- - 中医: zh/templates/tcm.md
- - 工业: zh/templates/industry.md
+ - 选择指南:
+ - 如何选择: zh/templates/how-to-choose.md
+ - 按任务选择: zh/templates/choosing/by-task.md
+ - 按输出类型选择: zh/templates/choosing/by-output.md
+ - 使用示例:
+ - 研究论文分析: zh/templates/examples/research-paper.md
+ - 财报分析: zh/templates/examples/financial-report.md
+ - 合同分析: zh/templates/examples/legal-contract.md
+ - 参考:
+ - 模板概览: zh/templates/reference/overview.md
+ - 通用: zh/templates/reference/general.md
+ - 金融: zh/templates/reference/finance.md
+ - 法律: zh/templates/reference/legal.md
+ - 医学: zh/templates/reference/medicine.md
+ - 中医: zh/templates/reference/tcm.md
+ - 工业: zh/templates/reference/industry.md
- 教程:
- zh/tutorials/index.md
- 研究助手: