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: document he export graphml/csv

Frankie-Xuff946f9905da
diff --git a/docs/en/cli/commands/export.md b/docs/en/cli/commands/export.md
index 15d9fe2..874eba1 100644
--- a/docs/en/cli/commands/export.md
+++ b/docs/en/cli/commands/export.md
@@ -2,7 +2,7 @@
Export a knowledge abstract to an [Obsidian](https://obsidian.md) vault — a folder of Markdown notes linked by `[[wikilinks]]`.
-`export` is a command group; `obsidian` is the format. (More formats may be added later.)
+`export` is a command group. Formats: `obsidian`, `graphml`, `csv`.
---
@@ -123,12 +123,120 @@ Non-graph types (`AutoList`, `AutoSet`, `AutoModel`) are not supported; the comm
---
+## he export graphml
+
+Export a pairwise knowledge graph to [GraphML](http://graphml.graphdrawing.org/) — an XML graph format that Gephi, yEd, and other desktop tools can open.
+
+Hypergraphs have no single GraphML encoding for N-ary edges. `he export graphml` reports a clear error for hypergraph KAs and suggests [`he export csv`](#he-export-csv).
+
+### Synopsis
+
+```bash
+he export graphml KA_PATH -o FILE.graphml
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `KA_PATH` | Path to the knowledge abstract directory (created by `he parse`) |
+
+### Options
+
+| Option | Alias | Default | Description |
+|--------|-------|---------|-------------|
+| `--output` | `-o` | *(required)* | Output GraphML file |
+
+### Description
+
+- **Directed.** The document uses `graph edgedefault="directed"`. An edge `B → A` is written as `source="B"` `target="A"`; endpoints are never sorted.
+- **Attributes.** Scalar fields from each node's / edge's `model_dump()` (`str` / `int` / `float` / `bool`) become GraphML `<data>` keys. Nested values are stringified. XML special characters (`& < > " '`) are escaped.
+- **Dangling edges.** An edge whose source or target node is missing is skipped (with a warning), not treated as a crash.
+
+Supported Auto-Types: `AutoGraph` and its temporal/spatial subclasses. `AutoHypergraph` is rejected. Non-graph types (`AutoList`, `AutoSet`, `AutoModel`) are not supported.
+
+### Examples
+
+```bash
+he parse tesla.md -t general/biography_graph -o ./tesla_kb/ -l en
+he export graphml ./tesla_kb/ -o ./tesla.graphml
+```
+
+---
+
+## he export csv
+
+Export nodes and edges as CSV tables for spreadsheets and graph tools that ingest edge lists.
+
+### Synopsis
+
+```bash
+he export csv KA_PATH -o OUT_DIR [OPTIONS]
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `KA_PATH` | Path to the knowledge abstract directory (created by `he parse`) |
+
+### Options
+
+| Option | Alias | Default | Description |
+|--------|-------|---------|-------------|
+| `--output` | `-o` | *(required)* | Output directory |
+| `--force` | `-f` | off | Write into an existing, non-empty directory |
+
+### Description
+
+**Pairwise graphs** write:
+
+```
+OUT_DIR/
+├── nodes.csv # id + schema scalar fields
+└── edges.csv # source, target + edge scalar fields
+```
+
+Endpoint order is preserved (`B → A` stays `B,A`). Fields that contain commas, quotes, or newlines are quoted by the stdlib `csv` module.
+
+**Hypergraphs** write `nodes.csv` plus `hyperedges.csv` instead of `edges.csv`. The `members` column joins participant ids with `|` and **sorts them lexicographically** so the file is deterministic. (Binary `edges.csv` does not sort endpoints.)
+
+A missing endpoint skips that edge (with a warning). Non-empty output directories require `--force`.
+
+### Examples
+
+```bash
+he export csv ./tesla_kb/ -o ./tesla_csv/
+he export csv ./tesla_kb/ -o ./tesla_csv/ --force
+```
+
+---
+
## Python API
-The same capability is available on graph Auto-Types:
+The same capability is available on graph Auto-Types for Obsidian, and as standalone functions for GraphML / CSV (they are not methods on AutoType):
```python
ka.export_obsidian("./tesla_vault/", vault_name="Tesla KB", overwrite=True)
+
+from hyperextract.utils.exporters import export_to_graphml, export_to_csv
+
+export_to_graphml(
+ ka.nodes,
+ ka.edges,
+ node_id_extractor=ka.node_key_extractor,
+ incident_nodes_extractor=ka.nodes_in_edge_extractor,
+ file_path="./tesla.graphml",
+)
+
+export_to_csv(
+ ka.nodes,
+ ka.edges,
+ node_id_extractor=ka.node_key_extractor,
+ incident_nodes_extractor=ka.nodes_in_edge_extractor,
+ folder_path="./tesla_csv/",
+ overwrite=True,
+)
```
---
diff --git a/docs/en/cli/index.md b/docs/en/cli/index.md
index 32c08f0..503c86f 100644
--- a/docs/en/cli/index.md
+++ b/docs/en/cli/index.md
@@ -33,6 +33,8 @@ he --version
| `he parse` | Extract knowledge from documents | `-t` template, `-o` output, `-l` language |
| `he show` | Visualize knowledge graph | — |
| `he export obsidian` | Export to an Obsidian vault | `-o` output, `--name`, `-f` force |
+| `he export graphml` | Export a pairwise graph to GraphML | `-o` output file |
+| `he export csv` | Export nodes/edges as CSV tables | `-o` directory, `-f` force |
| `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 | — |
@@ -168,6 +170,8 @@ he show ./output/
- **[`he talk`](commands/talk.md)** — Chat with knowledge abstract
- **[`he info`](commands/info.md)** — View knowledge abstract statistics
- **[`he export obsidian`](commands/export.md)** — Export to an Obsidian vault
+- **[`he export graphml`](commands/export.md#he-export-graphml)** — Export a pairwise graph to GraphML
+- **[`he export csv`](commands/export.md#he-export-csv)** — Export nodes/edges as CSV tables
### Management
diff --git a/docs/zh/cli/commands/export.md b/docs/zh/cli/commands/export.md
index 8abd9f8..e33eebb 100644
--- a/docs/zh/cli/commands/export.md
+++ b/docs/zh/cli/commands/export.md
@@ -2,7 +2,7 @@
将知识摘要导出为 [Obsidian](https://obsidian.md) 知识库——一个由 `[[双向链接]]` 关联的 Markdown 笔记文件夹。
-`export` 是一个命令组,`obsidian` 是格式(后续可能会增加更多格式)。
+`export` 是一个命令组。目前支持的格式:`obsidian`、`graphml`、`csv`。
---
@@ -123,12 +123,120 @@ Serbian-American inventor and electrical engineer
---
+## he export graphml
+
+将二元知识图谱导出为 [GraphML](http://graphml.graphdrawing.org/)——Gephi、yEd 等桌面工具可打开的 XML 图谱格式。
+
+超图的 N 元边没有单一的 GraphML 编码。对超图 KA 运行 `he export graphml` 会给出明确错误,并建议使用 [`he export csv`](#he-export-csv)。
+
+### 用法
+
+```bash
+he export graphml KA_PATH -o FILE.graphml
+```
+
+### 参数
+
+| 参数 | 说明 |
+|----------|-------------|
+| `KA_PATH` | 知识摘要目录路径(由 `he parse` 生成) |
+
+### 选项
+
+| 选项 | 别名 | 默认值 | 说明 |
+|--------|-------|---------|-------------|
+| `--output` | `-o` | *(必填)* | 输出 GraphML 文件 |
+
+### 说明
+
+- **有向。** 文档使用 `graph edgedefault="directed"`。边 `B → A` 写作 `source="B"` `target="A"`;端点不会被排序。
+- **属性。** 节点 / 边 `model_dump()` 中的标量字段(`str` / `int` / `float` / `bool`)成为 GraphML `<data>` 键。嵌套值转为字符串。XML 特殊字符(`& < > " '`)会被转义。
+- **悬空边。** 源或目标节点缺失的边会被跳过(并记录 warning),不会导致崩溃。
+
+支持的 Auto-Type:`AutoGraph` 及其时空子类。`AutoHypergraph` 会被拒绝。非图谱类型(`AutoList`、`AutoSet`、`AutoModel`)不支持。
+
+### 示例
+
+```bash
+he parse tesla.md -t general/biography_graph -o ./tesla_kb/ -l zh
+he export graphml ./tesla_kb/ -o ./tesla.graphml
+```
+
+---
+
+## he export csv
+
+将节点和边导出为 CSV 表,便于电子表格以及读取边列表的图谱工具使用。
+
+### 用法
+
+```bash
+he export csv KA_PATH -o OUT_DIR [选项]
+```
+
+### 参数
+
+| 参数 | 说明 |
+|----------|-------------|
+| `KA_PATH` | 知识摘要目录路径(由 `he parse` 生成) |
+
+### 选项
+
+| 选项 | 别名 | 默认值 | 说明 |
+|--------|-------|---------|-------------|
+| `--output` | `-o` | *(必填)* | 输出目录 |
+| `--force` | `-f` | 关闭 | 写入已存在且非空的目录 |
+
+### 说明
+
+**二元图** 会写出:
+
+```
+OUT_DIR/
+├── nodes.csv # id + schema 标量字段
+└── edges.csv # source, target + 边标量字段
+```
+
+端点顺序被保留(`B → A` 仍是 `B,A`)。含逗号、引号或换行的字段由标准库 `csv` 模块正确加引号。
+
+**超图** 写出 `nodes.csv` 和 `hyperedges.csv`(而不是 `edges.csv`)。`members` 列用 `|` 连接参与者 id,并按字典序**排序**以保证输出稳定。(二元 `edges.csv` 不会对端点排序。)
+
+缺失端点的边会被跳过(并记录 warning)。非空输出目录需要 `--force`。
+
+### 示例
+
+```bash
+he export csv ./tesla_kb/ -o ./tesla_csv/
+he export csv ./tesla_kb/ -o ./tesla_csv/ --force
+```
+
+---
+
## Python API
-图谱类 Auto-Type 也提供同样的能力:
+Obsidian 导出是图谱 Auto-Type 上的方法;GraphML / CSV 是独立纯函数(不会加到 AutoType 上):
```python
ka.export_obsidian("./tesla_vault/", vault_name="Tesla KB", overwrite=True)
+
+from hyperextract.utils.exporters import export_to_graphml, export_to_csv
+
+export_to_graphml(
+ ka.nodes,
+ ka.edges,
+ node_id_extractor=ka.node_key_extractor,
+ incident_nodes_extractor=ka.nodes_in_edge_extractor,
+ file_path="./tesla.graphml",
+)
+
+export_to_csv(
+ ka.nodes,
+ ka.edges,
+ node_id_extractor=ka.node_key_extractor,
+ incident_nodes_extractor=ka.nodes_in_edge_extractor,
+ folder_path="./tesla_csv/",
+ overwrite=True,
+)
```
---
diff --git a/docs/zh/cli/index.md b/docs/zh/cli/index.md
index 2d42a75..380d923 100644
--- a/docs/zh/cli/index.md
+++ b/docs/zh/cli/index.md
@@ -33,6 +33,8 @@ he --version
| `he parse` | 从文档提取知识 | `-t` 模板, `-o` 输出, `-l` 语言 |
| `he show` | 可视化知识图谱 | — |
| `he export obsidian` | 导出为 Obsidian 知识库 | `-o` 输出, `--name`, `-f` 强制 |
+| `he export graphml` | 将二元图导出为 GraphML | `-o` 输出文件 |
+| `he export csv` | 将节点/边导出为 CSV 表 | `-o` 目录, `-f` 强制 |
| `he search` | 知识库语义搜索 | `-n` top-k 结果数 |
| `he talk` | 与知识库对话 | `-i` 交互模式, `-q` 查询 |
| `he feed` | 增量添加文档 | — |
@@ -168,6 +170,8 @@ he show ./output/
- **[`he talk`](commands/talk.md)** — 与知识库对话
- **[`he info`](commands/info.md)** — 查看知识库统计信息
- **[`he export obsidian`](commands/export.md)** — 导出为 Obsidian 知识库
+- **[`he export graphml`](commands/export.md#he-export-graphml)** — 将二元图导出为 GraphML
+- **[`he export csv`](commands/export.md#he-export-csv)** — 将节点/边导出为 CSV 表
### 管理