Skip to content

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

refactor: make Obsidian export the `he export obsidian` subcommand + docs

Oguz Vuruskaner08e087c5583c
diff --git a/README.md b/README.md
index aca224d..a38e175 100644
--- a/README.md
+++ b/README.md
@@ -125,7 +125,7 @@ he search ./output/ "What are Tesla's major achievements?"
he show ./output/
# Export to an Obsidian vault (Markdown notes + [[wikilinks]])
-he export ./output/ -o ./vault/
+he export obsidian ./output/ -o ./vault/
```
<details>
diff --git a/README_ZH.md b/README_ZH.md
index 9d86928..f7698fa 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -125,7 +125,7 @@ he search ./output/ "苏轼有哪些重要的作品?"
he show ./output/
# 导出为 Obsidian 知识库(Markdown 笔记 + [[双向链接]])
-he export ./output/ -o ./vault/
+he export obsidian ./output/ -o ./vault/
```
<details>
diff --git a/docs/en/cli/commands/export.md b/docs/en/cli/commands/export.md
new file mode 100644
index 0000000..15d9fe2
--- /dev/null
+++ b/docs/en/cli/commands/export.md
@@ -0,0 +1,140 @@
+# he export obsidian
+
+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.)
+
+---
+
+## Synopsis
+
+```bash
+he export obsidian KA_PATH -o VAULT_PATH [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 vault directory |
+| `--name` | | output dir name | Vault name used for the index note |
+| `--no-index` | | off | Skip writing the index / map-of-content note |
+| `--force` | `-f` | off | Write into an existing, non-empty directory |
+
+---
+
+## Description
+
+`he export obsidian` turns an extracted knowledge graph into an Obsidian vault you can open and browse in Obsidian's interactive graph view:
+
+- **Each node → a Markdown note.** The node's fields are stored as YAML front-matter, followed by a `# Title` heading and (when present) a description.
+- **Each edge → a `[[wikilink]]`.** Relationships are rendered under the source note's `## Relationships` section, with the relationship label and description.
+- **An index note** (named after `--name`) lists every note grouped by type — a map-of-content for the vault.
+
+The exporter is dependency-free and writes plain Markdown, so the result is a normal Obsidian vault: open the folder via **"Open folder as vault"** in Obsidian, or re-ingest it later with [`he parse`](parse.md).
+
+---
+
+## Examples
+
+### Basic Usage
+
+```bash
+# Extract, then export
+he parse tesla.md -t general/biography_graph -o ./tesla_kb/ -l en
+he export obsidian ./tesla_kb/ -o ./tesla_vault/
+```
+
+### Custom Vault Name
+
+```bash
+he export obsidian ./tesla_kb/ -o ./tesla_vault/ --name "Tesla Knowledge Base"
+```
+
+### Overwrite an Existing Directory
+
+```bash
+he export obsidian ./tesla_kb/ -o ./tesla_vault/ --force
+```
+
+### Without the Index Note
+
+```bash
+he export obsidian ./tesla_kb/ -o ./tesla_vault/ --no-index
+```
+
+---
+
+## Output Structure
+
+```
+tesla_vault/
+├── Tesla Knowledge Base.md # index (grouped by type)
+├── Nikola Tesla.md
+├── Alternating Current.md
+└── ...
+```
+
+A note looks like:
+
+```markdown
+---
+name: Nikola Tesla
+type: Person
+description: "Serbian-American inventor and electrical engineer"
+---
+
+# Nikola Tesla
+
+Serbian-American inventor and electrical engineer
+
+## Relationships
+
+- **developed** → [[Alternating Current]] — Pioneered the AC system.
+- **rivaled** → [[Thomas Edison]] — The War of the Currents.
+```
+
+Notes:
+
+- Filenames are sanitized for Obsidian/the filesystem; the original id/title is preserved as a front-matter `alias`, and wikilinks use a `[[stem|display]]` form so links always resolve.
+- Name collisions are de-duplicated (e.g. `Tesla coil (2)`).
+
+---
+
+## Supported Auto-Types
+
+Export works with the graph family:
+
+| Auto-Type | Export |
+|-----------|--------|
+| `AutoGraph` | ✓ one note per node, edges as wikilinks |
+| `AutoHypergraph` | ✓ N-ary edges link all members |
+| `AutoTemporalGraph` | ✓ (inherits `AutoGraph`) |
+| `AutoSpatialGraph` | ✓ (inherits `AutoGraph`) |
+| `AutoSpatioTemporalGraph` | ✓ (inherits `AutoGraph`) |
+
+Non-graph types (`AutoList`, `AutoSet`, `AutoModel`) are not supported; the command reports a clear error.
+
+---
+
+## Python API
+
+The same capability is available on graph Auto-Types:
+
+```python
+ka.export_obsidian("./tesla_vault/", vault_name="Tesla KB", overwrite=True)
+```
+
+---
+
+## See Also
+
+- [`he parse`](parse.md) — Extract knowledge (and ingest an existing vault folder)
+- [`he show`](show.md) — Visualize the graph with OntoSight
+- [`he info`](info.md) — View knowledge abstract statistics
diff --git a/docs/en/cli/index.md b/docs/en/cli/index.md
index 88ec668..e760470 100644
--- a/docs/en/cli/index.md
+++ b/docs/en/cli/index.md
@@ -32,6 +32,7 @@ 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 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 | — |
@@ -148,6 +149,7 @@ he show ./output/
- **[`he search`](commands/search.md)** — Semantic search
- **[`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
### Management
diff --git a/docs/zh/cli/commands/export.md b/docs/zh/cli/commands/export.md
new file mode 100644
index 0000000..8abd9f8
--- /dev/null
+++ b/docs/zh/cli/commands/export.md
@@ -0,0 +1,140 @@
+# he export obsidian
+
+将知识摘要导出为 [Obsidian](https://obsidian.md) 知识库——一个由 `[[双向链接]]` 关联的 Markdown 笔记文件夹。
+
+`export` 是一个命令组,`obsidian` 是格式(后续可能会增加更多格式)。
+
+---
+
+## 用法
+
+```bash
+he export obsidian KA_PATH -o VAULT_PATH [选项]
+```
+
+## 参数
+
+| 参数 | 说明 |
+|----------|-------------|
+| `KA_PATH` | 知识摘要目录路径(由 `he parse` 生成) |
+
+## 选项
+
+| 选项 | 别名 | 默认值 | 说明 |
+|--------|-------|---------|-------------|
+| `--output` | `-o` | *(必填)* | 输出知识库目录 |
+| `--name` | | 输出目录名 | 索引笔记使用的知识库名称 |
+| `--no-index` | | 关闭 | 跳过生成索引 / 目录笔记 |
+| `--force` | `-f` | 关闭 | 写入已存在且非空的目录 |
+
+---
+
+## 说明
+
+`he export obsidian` 将提取出的知识图谱转换为一个可在 Obsidian 图谱视图中浏览的知识库:
+
+- **每个节点 → 一篇 Markdown 笔记。** 节点字段写入 YAML front-matter,随后是 `# 标题` 以及(如有)描述。
+- **每条边 → 一个 `[[双向链接]]`。** 关系渲染在源笔记的 `## Relationships` 区块中,包含关系标签与描述。
+- **索引笔记**(以 `--name` 命名)按类型分组列出所有笔记,作为知识库目录。
+
+导出器无额外依赖,生成的是纯 Markdown,因此结果是一个标准 Obsidian 知识库:在 Obsidian 中用 **"Open folder as vault"** 打开该文件夹,或之后用 [`he parse`](parse.md) 重新导入。
+
+---
+
+## 示例
+
+### 基本用法
+
+```bash
+# 先提取,再导出
+he parse tesla.md -t general/biography_graph -o ./tesla_kb/ -l zh
+he export obsidian ./tesla_kb/ -o ./tesla_vault/
+```
+
+### 自定义知识库名称
+
+```bash
+he export obsidian ./tesla_kb/ -o ./tesla_vault/ --name "Tesla 知识库"
+```
+
+### 覆盖已存在目录
+
+```bash
+he export obsidian ./tesla_kb/ -o ./tesla_vault/ --force
+```
+
+### 不生成索引笔记
+
+```bash
+he export obsidian ./tesla_kb/ -o ./tesla_vault/ --no-index
+```
+
+---
+
+## 输出结构
+
+```
+tesla_vault/
+├── Tesla 知识库.md # 索引(按类型分组)
+├── Nikola Tesla.md
+├── Alternating Current.md
+└── ...
+```
+
+一篇笔记的样子:
+
+```markdown
+---
+name: Nikola Tesla
+type: Person
+description: "Serbian-American inventor and electrical engineer"
+---
+
+# Nikola Tesla
+
+Serbian-American inventor and electrical engineer
+
+## Relationships
+
+- **developed** → [[Alternating Current]] — Pioneered the AC system.
+- **rivaled** → [[Thomas Edison]] — The War of the Currents.
+```
+
+说明:
+
+- 文件名会针对 Obsidian / 文件系统做净化;原始 id/标题保留为 front-matter 的 `alias`,双向链接使用 `[[stem|display]]` 形式以确保始终可解析。
+- 同名冲突会自动去重(例如 `Tesla coil (2)`)。
+
+---
+
+## 支持的 Auto-Type
+
+导出支持图谱家族:
+
+| Auto-Type | 导出 |
+|-----------|--------|
+| `AutoGraph` | ✓ 每个节点一篇笔记,边为双向链接 |
+| `AutoHypergraph` | ✓ N 元边链接所有成员 |
+| `AutoTemporalGraph` | ✓(继承自 `AutoGraph`) |
+| `AutoSpatialGraph` | ✓(继承自 `AutoGraph`) |
+| `AutoSpatioTemporalGraph` | ✓(继承自 `AutoGraph`) |
+
+非图谱类型(`AutoList`、`AutoSet`、`AutoModel`)不支持;命令会给出明确的错误提示。
+
+---
+
+## Python API
+
+图谱类 Auto-Type 也提供同样的能力:
+
+```python
+ka.export_obsidian("./tesla_vault/", vault_name="Tesla KB", overwrite=True)
+```
+
+---
+
+## 另请参阅
+
+- [`he parse`](parse.md) — 提取知识(也可导入已有的知识库文件夹)
+- [`he show`](show.md) — 使用 OntoSight 可视化图谱
+- [`he info`](info.md) — 查看知识摘要统计
diff --git a/docs/zh/cli/index.md b/docs/zh/cli/index.md
index ec320f8..1f0fe29 100644
--- a/docs/zh/cli/index.md
+++ b/docs/zh/cli/index.md
@@ -32,6 +32,7 @@ he --version
|---------|---------|--------------|
| `he parse` | 从文档提取知识 | `-t` 模板, `-o` 输出, `-l` 语言 |
| `he show` | 可视化知识图谱 | — |
+| `he export obsidian` | 导出为 Obsidian 知识库 | `-o` 输出, `--name`, `-f` 强制 |
| `he search` | 知识库语义搜索 | `-n` top-k 结果数 |
| `he talk` | 与知识库对话 | `-i` 交互模式, `-q` 查询 |
| `he feed` | 增量添加文档 | — |
@@ -148,6 +149,7 @@ he show ./output/
- **[`he search`](commands/search.md)** — 语义搜索
- **[`he talk`](commands/talk.md)** — 与知识库对话
- **[`he info`](commands/info.md)** — 查看知识库统计信息
+- **[`he export obsidian`](commands/export.md)** — 导出为 Obsidian 知识库
### 管理
diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.py
index e460d7e..1814384 100644
--- a/hyperextract/cli/cli.py
+++ b/hyperextract/cli/cli.py
@@ -136,7 +136,10 @@ def main(
("he talk <ka_path> [-i]", "Chat with KA"),
("he search <ka_path> <query>", "Semantic search"),
("he show <ka_path>", "Visualize KA"),
- ("he export <ka_path> -o <vault>", "Export to Obsidian vault"),
+ (
+ "he export obsidian <ka_path> -o <vault>",
+ "Export to Obsidian vault",
+ ),
],
),
]
@@ -440,13 +443,17 @@ def show(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory")
console.print(f"[dim] he talk {ka_path} -i # Interactive chat[/dim]")
[email protected](name="export")
-def export(
+export_app = typer.Typer(
+ name="export",
+ help="Export a Knowledge Abstract to other formats",
+ no_args_is_help=True,
+)
+
+
+@export_app.command(name="obsidian")
+def export_obsidian_cmd(
ka_path: str = typer.Argument(..., help="Knowledge Abstract directory"),
output: str = typer.Option(..., "--output", "-o", help="Output vault directory"),
- fmt: str = typer.Option(
- "obsidian", "--format", "-F", help="Export format (obsidian)"
- ),
name: Optional[str] = typer.Option(
None, "--name", help="Vault name used for the index note"
),
@@ -458,13 +465,7 @@ def export(
),
):
"""Export a Knowledge Abstract to an Obsidian vault (Markdown + wikilinks)."""
- logger.info("command=export ka_path=%s output=%s format=%s", ka_path, output, fmt)
-
- if fmt != "obsidian":
- console.print(
- f"[red]Error:[/red] Unsupported format '{fmt}'. Supported: obsidian."
- )
- raise typer.Exit(1)
+ logger.info("command=export-obsidian ka_path=%s output=%s", ka_path, output)
path = validate_ka_with_data(ka_path)
template, lang = get_template_from_ka(path)
@@ -522,6 +523,9 @@ def export(
console.print("[dim]Open the folder as a vault in Obsidian to explore it.[/dim]")
+app.add_typer(export_app, name="export")
+
+
@app.command(name="info")
def info(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory")):
"""View Knowledge Abstract information and statistics."""
diff --git a/mkdocs.yml b/mkdocs.yml
index e1dfa42..bfdfe8a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -74,6 +74,7 @@ plugins:
- cli/commands/parse.md
- cli/commands/feed.md
- cli/commands/show.md
+ - cli/commands/export.md
- cli/commands/build-index.md
- cli/commands/search.md
- cli/commands/talk.md
@@ -164,6 +165,7 @@ plugins:
- zh/cli/commands/parse.md
- zh/cli/commands/feed.md
- zh/cli/commands/show.md
+ - zh/cli/commands/export.md
- zh/cli/commands/build-index.md
- zh/cli/commands/search.md
- zh/cli/commands/talk.md