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.mdindex 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):```pythonka.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.mdindex 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### Managementdiff --git a/docs/zh/cli/commands/export.md b/docs/zh/cli/commands/export.mdindex 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 上):```pythonka.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.mdindex 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 表### 管理