Skip to content

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

feat: add `he clean` to remove a KA's index or the whole KA

Oguz Vuruskaner283133ae975d
diff --git a/docs/en/cli/commands/clean.md b/docs/en/cli/commands/clean.md
new file mode 100644
index 0000000..3fb026b
--- /dev/null
+++ b/docs/en/cli/commands/clean.md
@@ -0,0 +1,79 @@
+# he clean
+
+Clean a knowledge abstract — remove its search index, or the entire KA with `--all`.
+
+---
+
+## Synopsis
+
+```bash
+he clean KA_PATH [OPTIONS]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `KA_PATH` | Path to the knowledge abstract directory |
+
+## Options
+
+| Option | Alias | Default | Description |
+|--------|-------|---------|-------------|
+| `--all` | `-a` | off | Remove the **entire** KA directory (data, metadata, and index) |
+| `--yes` | `-y` | off | Skip the confirmation prompt |
+
+---
+
+## Description
+
+`he clean` deletes parts of a knowledge abstract:
+
+- **Default** — removes only the vector index (the `index/` subdirectory). The extracted data (`data.json`) and metadata are kept; rebuild later with [`he build-index`](build-index.md).
+- **`--all`** — removes the entire KA directory.
+
+Deletion is **permanent**. The command asks for confirmation first; pass `--yes` to skip the prompt (e.g. in scripts).
+
+For safety, `he clean` only operates on a real knowledge abstract — a directory containing `data.json`. It refuses to delete an arbitrary directory, so a mistyped path cannot wipe unrelated files.
+
+---
+
+## Examples
+
+### Clean the index (keep data)
+
+```bash
+he clean ./tesla_kb/
+# → deletes ./tesla_kb/index/ after confirmation
+```
+
+### Remove the whole knowledge abstract
+
+```bash
+he clean ./tesla_kb/ --all
+```
+
+### Non-interactive (scripts / CI)
+
+```bash
+he clean ./tesla_kb/ --all --yes
+```
+
+---
+
+## What gets deleted
+
+| Mode | Deleted | Kept |
+|------|---------|------|
+| default | `index/` | `data.json`, `metadata.json` |
+| `--all` | the entire `KA_PATH` directory | — |
+
+> An Obsidian vault produced by [`he export obsidian`](export.md) is a separate folder and is **not** touched by `he clean`. Remove it with your shell (`rm -rf ./vault/`).
+
+---
+
+## See Also
+
+- [`he build-index`](build-index.md) — Rebuild the search index after cleaning it
+- [`he info`](info.md) — Inspect a knowledge abstract before cleaning
+- [`he parse`](parse.md) — Re-create a knowledge abstract
diff --git a/docs/en/cli/index.md b/docs/en/cli/index.md
index 88ec668..e8ef448 100644
--- a/docs/en/cli/index.md
+++ b/docs/en/cli/index.md
@@ -37,6 +37,7 @@ he --version
| `he feed` | Add documents incrementally | — |
| `he info` | Show knowledge abstract statistics | — |
| `he build-index` | Build/rebuild search index | `-f` force rebuild |
+| `he clean` | Remove a KA's index (or the whole KA) | `-a` all, `-y` yes |
| `he list` | List templates and methods | `template` or `method` |
| `he config` | Manage configuration | `init`, `show`, `set` |
@@ -152,6 +153,7 @@ he show ./output/
### Management
- **[`he build-index`](commands/build-index.md)** — Build search index
+- **[`he clean`](commands/clean.md)** — Remove a KA's index, or the whole KA
- **[`he list`](commands/list.md)** — List available templates/methods
- **[`he config`](commands/config.md)** — Configuration management
diff --git a/docs/zh/cli/commands/clean.md b/docs/zh/cli/commands/clean.md
new file mode 100644
index 0000000..5d64ca1
--- /dev/null
+++ b/docs/zh/cli/commands/clean.md
@@ -0,0 +1,79 @@
+# he clean
+
+清理知识摘要——删除其搜索索引,或使用 `--all` 删除整个 KA。
+
+---
+
+## 用法
+
+```bash
+he clean KA_PATH [选项]
+```
+
+## 参数
+
+| 参数 | 说明 |
+|----------|-------------|
+| `KA_PATH` | 知识摘要目录路径 |
+
+## 选项
+
+| 选项 | 别名 | 默认值 | 说明 |
+|--------|-------|---------|-------------|
+| `--all` | `-a` | 关闭 | 删除**整个** KA 目录(数据、元数据和索引) |
+| `--yes` | `-y` | 关闭 | 跳过确认提示 |
+
+---
+
+## 说明
+
+`he clean` 删除知识摘要的一部分:
+
+- **默认** — 仅删除向量索引(`index/` 子目录)。提取的数据(`data.json`)和元数据会保留;之后可用 [`he build-index`](build-index.md) 重新构建。
+- **`--all`** — 删除整个 KA 目录。
+
+删除是**不可恢复**的。命令会先要求确认;使用 `--yes` 可跳过提示(例如脚本中)。
+
+为安全起见,`he clean` 只对真正的知识摘要(包含 `data.json` 的目录)生效。它拒绝删除任意目录,因此输错路径不会误删无关文件。
+
+---
+
+## 示例
+
+### 清理索引(保留数据)
+
+```bash
+he clean ./tesla_kb/
+# → 确认后删除 ./tesla_kb/index/
+```
+
+### 删除整个知识摘要
+
+```bash
+he clean ./tesla_kb/ --all
+```
+
+### 非交互(脚本 / CI)
+
+```bash
+he clean ./tesla_kb/ --all --yes
+```
+
+---
+
+## 删除内容
+
+| 模式 | 删除 | 保留 |
+|------|---------|------|
+| 默认 | `index/` | `data.json`、`metadata.json` |
+| `--all` | 整个 `KA_PATH` 目录 | — |
+
+> 由 [`he export obsidian`](export.md) 生成的 Obsidian 知识库是独立文件夹,**不会**被 `he clean` 影响。请用 shell 删除(`rm -rf ./vault/`)。
+
+---
+
+## 另请参阅
+
+- [`he build-index`](build-index.md) — 清理索引后重新构建
+- [`he info`](info.md) — 清理前查看知识摘要
+- [`he parse`](parse.md) — 重新创建知识摘要
diff --git a/docs/zh/cli/index.md b/docs/zh/cli/index.md
index ec320f8..7f06324 100644
--- a/docs/zh/cli/index.md
+++ b/docs/zh/cli/index.md
@@ -37,6 +37,7 @@ he --version
| `he feed` | 增量添加文档 | — |
| `he info` | 显示知识库统计信息 | — |
| `he build-index` | 构建/重建搜索索引 | `-f` 强制重建 |
+| `he clean` | 删除 KA 的索引(或整个 KA) | `-a` all, `-y` yes |
| `he list` | 列出模板和方法 | `template` 或 `method` |
| `he config` | 管理配置 | `init`, `show`, `set` |
@@ -152,6 +153,7 @@ he show ./output/
### 管理
- **[`he build-index`](commands/build-index.md)** — 构建搜索索引
+- **[`he clean`](commands/clean.md)** — 删除 KA 的索引,或整个 KA
- **[`he list`](commands/list.md)** — 列出可用模板/方法
- **[`he config`](commands/config.md)** — 配置管理
diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.py
index fd68607..c0a2826 100644
--- a/hyperextract/cli/cli.py
+++ b/hyperextract/cli/cli.py
@@ -814,3 +814,52 @@ def build_index(
console.print("[dim]Now you can:[/dim]")
console.print(f'[dim] he search {ka_path} "keyword" # Semantic search[/dim]')
console.print(f"[dim] he talk {ka_path} -i # Interactive chat[/dim]")
+
+
[email protected](name="clean")
+def clean(
+ ka_path: str = typer.Argument(..., help="Knowledge Abstract directory"),
+ all_: bool = typer.Option(
+ False,
+ "--all",
+ "-a",
+ help="Remove the ENTIRE Knowledge Abstract (data, metadata, and index)",
+ ),
+ yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt"),
+):
+ """Clean a Knowledge Abstract: remove its search index, or the whole KA with --all."""
+ import shutil
+
+ logger.info("command=clean ka_path=%s all=%s", ka_path, all_)
+
+ # validate_ka_with_data ensures the target really is a KA (has data.json),
+ # so --all never rmtree's an arbitrary mistyped directory.
+ path = validate_ka_with_data(ka_path)
+
+ if all_:
+ target = path
+ what = f"the ENTIRE Knowledge Abstract '{path}' (data, metadata, index)"
+ else:
+ target = path / "index"
+ if not target.exists() or not any(target.iterdir()):
+ console.print("[yellow]Nothing to clean:[/yellow] no index found.")
+ console.print(
+ f"[dim]Tip: use --all to remove the whole KA at {path}.[/dim]"
+ )
+ raise typer.Exit(0)
+ what = f"the search index of '{path}'"
+
+ console.print(f"[yellow]This will permanently delete[/yellow] {what}.")
+ if not yes and not typer.confirm("Are you sure?"):
+ console.print("[dim]Aborted. Nothing was deleted.[/dim]")
+ raise typer.Exit(0)
+
+ try:
+ shutil.rmtree(target)
+ except Exception as e:
+ console.print(f"[red]Error:[/red] Failed to delete {target}: {e}")
+ raise typer.Exit(1)
+
+ console.print(f"[bold green]Cleaned![/bold green] Removed {target}")
+ if not all_:
+ console.print(f"[dim]Rebuild it with: he build-index {ka_path}[/dim]")
diff --git a/mkdocs.yml b/mkdocs.yml
index e1dfa42..4edb088 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -75,6 +75,7 @@ plugins:
- cli/commands/feed.md
- cli/commands/show.md
- cli/commands/build-index.md
+ - cli/commands/clean.md
- cli/commands/search.md
- cli/commands/talk.md
- cli/commands/info.md
@@ -165,6 +166,7 @@ plugins:
- zh/cli/commands/feed.md
- zh/cli/commands/show.md
- zh/cli/commands/build-index.md
+ - zh/cli/commands/clean.md
- zh/cli/commands/search.md
- zh/cli/commands/talk.md
- zh/cli/commands/info.md
diff --git a/tests/cli/test_clean.py b/tests/cli/test_clean.py
new file mode 100644
index 0000000..6c9447a
--- /dev/null
+++ b/tests/cli/test_clean.py
@@ -0,0 +1,73 @@
+"""Tests for the `he clean` command."""
+
+import json
+
+from typer.testing import CliRunner
+
+from hyperextract.cli.cli import app
+
+runner = CliRunner()
+
+
+def _make_ka(tmp_path, with_index=True):
+ """Create a minimal Knowledge Abstract directory on disk."""
+ ka = tmp_path / "ka"
+ ka.mkdir()
+ (ka / "data.json").write_text(
+ json.dumps({"nodes": [], "edges": []}), encoding="utf-8"
+ )
+ (ka / "metadata.json").write_text(json.dumps({"template": "x"}), encoding="utf-8")
+ if with_index:
+ index = ka / "index"
+ index.mkdir()
+ (index / "node_index").mkdir()
+ (index / "node_index" / "index.faiss").write_text("x", encoding="utf-8")
+ return ka
+
+
+class TestClean:
+ def test_clean_index_only(self, tmp_path):
+ ka = _make_ka(tmp_path)
+ result = runner.invoke(app, ["clean", str(ka), "--yes"])
+ assert result.exit_code == 0
+ assert not (ka / "index").exists()
+ # Data is preserved — only the index was cleaned.
+ assert (ka / "data.json").exists()
+
+ def test_clean_all_removes_whole_ka(self, tmp_path):
+ ka = _make_ka(tmp_path)
+ result = runner.invoke(app, ["clean", str(ka), "--all", "--yes"])
+ assert result.exit_code == 0
+ assert not ka.exists()
+
+ def test_clean_aborts_without_confirmation(self, tmp_path):
+ ka = _make_ka(tmp_path)
+ result = runner.invoke(app, ["clean", str(ka)], input="n\n")
+ assert result.exit_code == 0
+ assert (ka / "index").exists() # nothing deleted
+
+ def test_clean_confirms_with_yes_input(self, tmp_path):
+ ka = _make_ka(tmp_path)
+ result = runner.invoke(app, ["clean", str(ka)], input="y\n")
+ assert result.exit_code == 0
+ assert not (ka / "index").exists()
+
+ def test_clean_no_index(self, tmp_path):
+ ka = _make_ka(tmp_path, with_index=False)
+ result = runner.invoke(app, ["clean", str(ka), "--yes"])
+ assert result.exit_code == 0
+ assert "Nothing to clean" in result.output
+ assert ka.exists()
+
+ def test_clean_nonexistent_path(self, tmp_path):
+ result = runner.invoke(app, ["clean", str(tmp_path / "nope"), "--yes"])
+ assert result.exit_code == 1
+
+ def test_clean_refuses_non_ka_directory(self, tmp_path):
+ # A directory without data.json must not be deletable via clean.
+ plain = tmp_path / "plain"
+ plain.mkdir()
+ (plain / "important.txt").write_text("keep", encoding="utf-8")
+ result = runner.invoke(app, ["clean", str(plain), "--all", "--yes"])
+ assert result.exit_code == 1
+ assert plain.exists()