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.mdindex 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.mdindex 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.mdnew file mode 100644index 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 statisticsdiff --git a/docs/en/cli/index.md b/docs/en/cli/index.mdindex 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### Managementdiff --git a/docs/zh/cli/commands/export.md b/docs/zh/cli/commands/export.mdnew file mode 100644index 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.mdindex 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.pyindex 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.ymlindex 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