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 key-level hard delete and LLM-assisted soft delete (#84)

yifanfeng974d4871d25cb3
diff --git a/docs/en/cli/commands/remove.md b/docs/en/cli/commands/remove.md
new file mode 100644
index 0000000..9adc7d8
--- /dev/null
+++ b/docs/en/cli/commands/remove.md
@@ -0,0 +1,111 @@
+# he remove
+
+Delete knowledge from an existing knowledge abstract: hard-delete nodes/edges by key, or soft-remove a single fact with LLM assistance.
+
+---
+
+## Synopsis
+
+```bash
+he remove KA_PATH [OPTIONS]
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--node TEXT` | — | Node key(s) to **hard-delete**; edges anchored by a removed node are removed too |
+| `--edge TEXT` | — | Edge key(s) to **hard-delete** |
+| `--edit-node TEXT` | — | Node key to **soft-edit** (LLM rewrites it minus `--fact`) |
+| `--edit-edge TEXT` | — | Edge key to **soft-edit** |
+| `--fact TEXT` | — | The fact to remove from the `--edit-node` / `--edit-edge` item |
+| `--instruction TEXT` | — | Free-form edit instruction (alternative to `--fact`) |
+| `--dry-run` | off | Preview the change without persisting it |
+| `--backup / --no-backup` | on | Back up `data.json` as `data.json.bak.<timestamp>` before writing |
+| `--yes` | `-y` | Skip the confirmation prompt |
+
+Hard delete (`--node` / `--edge`) and soft delete (`--edit-node` / `--edit-edge`) are mutually exclusive.
+
+---
+
+## Hard Delete: by Key
+
+Remove whole items. Keys are the values produced by the template's `identifiers` (typically the entity name for nodes, `"{source}|{type}|{target}"`-style keys for edges). Use [`he show`](show.md) or read `data.json` to find them.
+
+```bash
+# Remove two nodes; any edge touching them is removed as well
+he remove ./ka/ --node Apple --node Nokia
+
+# Remove one edge by its exact key
+he remove ./ka/ --edge "Apple-partner-Google"
+```
+
+The command prints a removal report (removed items, keys not found, orphaned edges pruned).
+
+!!! warning
+ Hard delete is **permanent** for the deleted items. A `data.json.bak.<timestamp>` backup is written next to the KA before writing unless `--no-backup` is passed.
+
+---
+
+## Soft Delete: remove a single fact (LLM-assisted)
+
+Sometimes a node should stay, but one claim inside it is wrong or obsolete:
+
+```bash
+# Preview first (nothing is written)
+he remove ./ka/ --edit-node Apple \
+ --fact "founded by Steve Jobs" --dry-run
+
+# Apply
+he remove ./ka/ --edit-node Apple \
+ --fact "founded by Steve Jobs" -y
+```
+
+The LLM rewrites the item under the **same schema**, removing the fact while keeping every other field unchanged. Guardrails:
+
+- **Key invariance** — a rewrite that changes the item's key is rejected (renaming is not an edit; delete the old item and add the new one instead).
+- **Dry run** — `--dry-run` prints the old and proposed items and writes nothing.
+- **No-op detection** — if the fact was not found, the command reports `No change` and writes nothing.
+- **Backup** — `data.json.bak.<timestamp>` is written before the edit unless `--no-backup`.
+
+For edges, remember that fields used by the edge key (e.g. `relation_type`) cannot be changed by a soft edit — the rewrite would be rejected; hard-delete the edge instead.
+
+```bash
+he remove ./ka/ --edit-edge "Apple-acquired-Beats" \
+ --instruction "Remove the price from the description"
+```
+
+---
+
+## After removal
+
+Removal invalidates the search index (the stale `index/` directory is deleted). Rebuild it before searching or chatting again:
+
+```bash
+he build-index ./ka/
+```
+
+---
+
+## Python API
+
+```python
+ka.remove_nodes("Apple", "Nokia") # -> {"removed_nodes": [...], "not_found_nodes": [...], "removed_orphan_edges": [...]}
+ka.remove_edges("Apple-partner-Google")
+
+report = ka.edit_node("Apple", remove_fact="founded by Steve Jobs", dry_run=True)
+# report: {"changed": bool, "applied": bool, "old": <item>, "new": <item>}
+ka.edit_node("Apple", remove_fact="founded by Steve Jobs") # applies
+
+ka.dump("./ka/") # persist
+```
+
+Works for graph, hypergraph, and temporal/spatial graph knowledge abstracts.
+
+---
+
+## See Also
+
+- [`he clean`](clean.md) — remove the search index or the whole KA
+- [`he show`](show.md) — inspect keys before deleting
+- [`he build-index`](build-index.md) — rebuild the search index after removal
diff --git a/docs/en/cli/index.md b/docs/en/cli/index.md
index 32c08f0..2a7cf4d 100644
--- a/docs/en/cli/index.md
+++ b/docs/en/cli/index.md
@@ -39,6 +39,7 @@ he --version
| `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 remove` | Delete nodes/edges by key, or soft-remove a single fact | `--node`, `--edge`, `--edit-node`, `--fact`, `--dry-run` |
| `he list` | List templates and methods | `template` or `method` |
| `he template validate` | Validate a template YAML file | `--json`, `--all` |
| `he config` | Manage configuration | `init`, `show`, `llm`, `embedder` |
@@ -173,6 +174,7 @@ he show ./output/
- **[`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 remove`](commands/remove.md)** — Delete nodes/edges by key, or soft-remove a single fact
- **[`he list`](commands/list.md)** — List available templates/methods
- **[`he template validate`](commands/template.md)** — Validate a template YAML file
- **[`he config`](commands/config.md)** — Configuration management
diff --git a/docs/zh/cli/commands/remove.md b/docs/zh/cli/commands/remove.md
new file mode 100644
index 0000000..f264435
--- /dev/null
+++ b/docs/zh/cli/commands/remove.md
@@ -0,0 +1,111 @@
+# he remove
+
+从已有知识摘要中删除知识:按键硬删除节点/边,或借助大模型软删除单条事实。
+
+---
+
+## 用法
+
+```bash
+he remove KA_PATH [选项]
+```
+
+## 选项
+
+| 选项 | 默认值 | 说明 |
+|--------|---------|-------------|
+| `--node TEXT` | — | **硬删除**指定节点;以被删节点为端点的边会一并删除 |
+| `--edge TEXT` | — | **硬删除**指定边 |
+| `--edit-node TEXT` | — | **软编辑**指定节点(大模型重写,移除 `--fact`) |
+| `--edit-edge TEXT` | — | **软编辑**指定边 |
+| `--fact TEXT` | — | 要从 `--edit-node` / `--edit-edge` 条目中移除的事实 |
+| `--instruction TEXT` | — | 自由格式的编辑指令(替代 `--fact`) |
+| `--dry-run` | 关闭 | 仅预览变更,不落盘 |
+| `--backup / --no-backup` | 开启 | 写入前将 `data.json` 备份为 `data.json.bak.<时间戳>` |
+| `--yes` | `-y` | 跳过确认提示 |
+
+硬删除(`--node` / `--edge`)与软删除(`--edit-node` / `--edit-edge`)互斥。
+
+---
+
+## 硬删除:按键删除
+
+删除整个条目。key 由模板的 `identifiers` 生成(节点通常为实体名,边通常为 `"{source}|{type}|{target}"` 风格)。可用 [`he show`](show.md) 或直接查看 `data.json` 找到它们。
+
+```bash
+# 删除两个节点;以它们为端点的边会被一并删除
+he remove ./ka/ --node Apple --node Nokia
+
+# 按精确 key 删除一条边
+he remove ./ka/ --edge "Apple-partner-Google"
+```
+
+命令会输出删除报告(已删除项、未命中的 key、被清理的孤儿边)。
+
+!!! warning
+ 对被删除的条目而言,硬删除是**永久的**。除非传入 `--no-backup`,否则写入前会在 KA 目录旁生成 `data.json.bak.<时间戳>` 备份。
+
+---
+
+## 软删除:移除单条事实(大模型辅助)
+
+有时节点需要保留,但其中的某条描述是错误的或已过时:
+
+```bash
+# 先预览(不落盘)
+he remove ./ka/ --edit-node Apple \
+ --fact "founded by Steve Jobs" --dry-run
+
+# 应用
+he remove ./ka/ --edit-node Apple \
+ --fact "founded by Steve Jobs" -y
+```
+
+大模型会在**相同 schema** 下重写该条目,只移除目标事实,其余字段保持不变。安全护栏:
+
+- **key 不变性** — 重写若改变了条目的 key 会被拒绝(改名不属于编辑;应显式删除旧条目再添加新条目)。
+- **预览** — `--dry-run` 打印旧条目与拟定条目,不写入任何内容。
+- **无变化检测** — 若未找到目标事实,命令报告 `No change` 且不写入。
+- **备份** — 除非传入 `--no-backup`,编辑前会生成 `data.json.bak.<时间戳>`。
+
+对边进行软编辑时请注意:构成边 key 的字段(如 `relation_type`)无法通过软编辑修改——重写会被拒绝;此时请改用硬删除。
+
+```bash
+he remove ./ka/ --edit-edge "Apple-acquired-Beats" \
+ --instruction "Remove the price from the description"
+```
+
+---
+
+## 删除之后
+
+删除会使搜索索引失效(过期的 `index/` 目录会被删除)。再次搜索或对话前请先重建:
+
+```bash
+he build-index ./ka/
+```
+
+---
+
+## Python API
+
+```python
+ka.remove_nodes("Apple", "Nokia") # -> {"removed_nodes": [...], "not_found_nodes": [...], "removed_orphan_edges": [...]}
+ka.remove_edges("Apple-partner-Google")
+
+report = ka.edit_node("Apple", remove_fact="founded by Steve Jobs", dry_run=True)
+# report: {"changed": bool, "applied": bool, "old": <item>, "new": <item>}
+ka.edit_node("Apple", remove_fact="founded by Steve Jobs") # 应用
+
+ka.dump("./ka/") # 持久化
+```
+
+适用于 graph、hypergraph 以及时序/空间图谱知识摘要。
+
+---
+
+## 另请参阅
+
+- [`he clean`](clean.md) — 删除搜索索引或整个 KA
+- [`he show`](show.md) — 删除前查看 key
+- [`he build-index`](build-index.md) — 删除后重建搜索索引
diff --git a/docs/zh/cli/index.md b/docs/zh/cli/index.md
index 2d42a75..a84831c 100644
--- a/docs/zh/cli/index.md
+++ b/docs/zh/cli/index.md
@@ -39,6 +39,7 @@ he --version
| `he info` | 显示知识库统计信息 | — |
| `he build-index` | 构建/重建搜索索引 | `-f` 强制重建 |
| `he clean` | 删除 KA 的索引(或整个 KA) | `-a` all, `-y` yes |
+| `he remove` | 按键删除节点/边,或软删除单条事实 | `--node`、`--edge`、`--edit-node`、`--fact`、`--dry-run` |
| `he list` | 列出模板和方法 | `template` 或 `method` |
| `he template validate` | 校验模板 YAML | `--json`、`--all` |
| `he config` | 管理配置 | `init`, `show`, `llm`, `embedder` |
@@ -173,6 +174,7 @@ he show ./output/
- **[`he build-index`](commands/build-index.md)** — 构建搜索索引
- **[`he clean`](commands/clean.md)** — 删除 KA 的索引,或整个 KA
+- **[`he remove`](commands/remove.md)** — 按键删除节点/边,或软删除单条事实
- **[`he list`](commands/list.md)** — 列出可用模板/方法
- **[`he template validate`](commands/template.md)** — 校验模板 YAML 文件
- **[`he config`](commands/config.md)** — 配置管理
diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.py
index fe84b82..8849eb5 100644
--- a/hyperextract/cli/cli.py
+++ b/hyperextract/cli/cli.py
@@ -949,3 +949,158 @@ def clean(
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]")
+
+
[email protected](name="remove")
+def remove_items(
+ ka_path: str = typer.Argument(..., help="Knowledge Abstract directory"),
+ node: list[str] = typer.Option(
+ None, "--node", help="Node key(s) to delete (hard delete, removes orphan edges)"
+ ),
+ edge: list[str] = typer.Option(
+ None, "--edge", help="Edge key(s) to delete (hard delete)"
+ ),
+ edit_node_key: str = typer.Option(
+ None, "--edit-node", help="Node key to soft-edit (LLM rewrites it minus --fact)"
+ ),
+ edit_edge_key: str = typer.Option(
+ None, "--edit-edge", help="Edge key to soft-edit (LLM rewrites it minus --fact)"
+ ),
+ fact: str = typer.Option(
+ None, "--fact", help="Fact to remove from the --edit-node/--edit-edge item"
+ ),
+ instruction: str = typer.Option(
+ None, "--instruction", help="Free-form edit instruction (instead of --fact)"
+ ),
+ dry_run: bool = typer.Option(
+ False, "--dry-run", help="Preview changes without persisting them"
+ ),
+ backup: bool = typer.Option(
+ True, "--backup/--no-backup", help="Back up data.json before writing"
+ ),
+ yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt"),
+):
+ """Delete nodes/edges by key, or soft-remove a single fact (LLM-assisted).
+
+ Hard delete: he remove ./ka --node Apple --edge "Apple-partner-Google"
+ Soft delete: he remove ./ka --edit-node Apple --fact "founded by Steve Jobs"
+ """
+ import shutil
+ from datetime import datetime
+
+ logger.info("command=remove ka_path=%s dry_run=%s", ka_path, dry_run)
+
+ hard_targets = list(node or []) + list(edge or [])
+ soft_target = edit_node_key or edit_edge_key
+ if hard_targets and soft_target:
+ console.print(
+ "[red]Error:[/red] Combine either --node/--edge (hard delete) "
+ "or --edit-node/--edit-edge (soft delete), not both."
+ )
+ raise typer.Exit(1)
+ if soft_target and not fact and not instruction:
+ console.print("[red]Error:[/red] Soft delete needs --fact or --instruction.")
+ raise typer.Exit(1)
+ if not hard_targets and not soft_target:
+ console.print(
+ "[yellow]Nothing to do.[/yellow] "
+ "Use --node/--edge to delete items, or --edit-node/--edit-edge "
+ "with --fact to remove a single fact."
+ )
+ raise typer.Exit(0)
+
+ path = validate_ka_with_data(ka_path)
+ template, lang = get_template_from_ka(path)
+ ka = Template.create(template, lang)
+ ka.load(path)
+
+ try:
+ if hard_targets:
+ report = {}
+ if node:
+ report.update(ka.remove_nodes(*node))
+ if edge:
+ report.update(ka.remove_edges(*edge))
+ else:
+ if not yes and not dry_run:
+ console.print(
+ "[yellow]Soft delete rewrites the item with an LLM.[/yellow] "
+ "Use --dry-run to preview, -y to skip this prompt."
+ )
+ if not typer.confirm("Apply the edit?"):
+ console.print("[dim]Aborted. Nothing was changed.[/dim]")
+ raise typer.Exit(0)
+ if edit_node_key:
+ report = ka.edit_node(
+ edit_node_key,
+ remove_fact=fact,
+ instruction=instruction,
+ dry_run=dry_run,
+ )
+ else:
+ report = ka.edit_edge(
+ edit_edge_key,
+ remove_fact=fact,
+ instruction=instruction,
+ dry_run=dry_run,
+ )
+ except KeyError as e:
+ console.print(f"[red]Error:[/red] {e}")
+ raise typer.Exit(1)
+ except ValueError as e:
+ console.print(f"[red]Rejected:[/red] {e}")
+ raise typer.Exit(1)
+
+ console.print()
+ if hard_targets:
+ table = Table(title="Removal Report")
+ table.add_column("Field")
+ table.add_column("Items")
+ for field, items in report.items():
+ table.add_row(field, "\n".join(items) if items else "—")
+ console.print(table)
+ removed_any = any(
+ report.get(key)
+ for key in ("removed_nodes", "removed_edges", "removed_orphan_edges")
+ )
+ if not removed_any:
+ console.print("[yellow]Nothing matched — no changes made.[/yellow]")
+ raise typer.Exit(0)
+ else:
+ changed = report["changed"]
+ if not changed:
+ console.print(
+ "[yellow]No change:[/yellow] the fact was not found in the item "
+ "(the LLM returned it unchanged). Nothing was written."
+ )
+ raise typer.Exit(0)
+ console.print(
+ f"[bold]Old item:[/bold]\n{report['old'].model_dump_json(indent=2)}"
+ )
+ console.print()
+ console.print(f"[bold]{'Proposed' if dry_run else 'New'} item:[/bold]")
+ console.print(report["new"].model_dump_json(indent=2))
+
+ if dry_run:
+ console.print(
+ "\n[dim]Dry run — nothing was persisted. "
+ "Re-run without --dry-run to apply.[/dim]"
+ )
+ raise typer.Exit(0)
+
+ if backup:
+ stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+ backup_path = path / f"data.json.bak.{stamp}"
+ shutil.copy2(path / "data.json", backup_path)
+ console.print(f"[dim]Backup written: {backup_path}[/dim]")
+
+ ka.dump(path)
+
+ # The in-memory index was invalidated by the mutation; drop the stale
+ # on-disk index so search never serves deleted knowledge.
+ index_dir = path / "index"
+ if index_dir.exists():
+ shutil.rmtree(index_dir)
+
+ console.print(f"[bold green]Done![/bold green] Knowledge Abstract updated: {path}")
+ console.print(f"[dim]Rebuild the search index with: he build-index {ka_path}[/dim]")
diff --git a/hyperextract/types/base.py b/hyperextract/types/base.py
index 52711fb..6ab8023 100644
--- a/hyperextract/types/base.py
+++ b/hyperextract/types/base.py
@@ -1,5 +1,6 @@
import json
from abc import ABC, abstractmethod
+from collections.abc import Callable
from datetime import datetime
from pathlib import Path
from typing import Any, Generic, TypeVar
@@ -377,6 +378,70 @@ class BaseAutoType(ABC, Generic[T]):
results.append(r)
return results
+ def _edit_item(
+ self,
+ memory,
+ editor,
+ key_extractor: Callable,
+ schema_name: str,
+ key: str,
+ remove_fact: str | None,
+ instruction: str | None,
+ dry_run: bool,
+ ) -> dict:
+ """Shared soft-delete engine: LLM-rewrite one stored item minus a fact.
+
+ The rewrite is validated before it is applied: the item key must be
+ unchanged (a changed key is a rename, i.e. delete + create, not an
+ edit) and the item must actually differ from the stored one.
+
+ Args:
+ memory: The OMem instance holding the item.
+ editor: Runnable producing a rewritten item (prompt | structured LLM).
+ key_extractor: Key function used to validate the rewrite.
+ schema_name: "node" or "edge" (for reports/logs).
+ key: Key of the item to edit.
+ remove_fact: Fact to remove (exclusive with `instruction`).
+ instruction: Free-form edit instruction (exclusive with `remove_fact`).
+ dry_run: Return the proposed rewrite without applying it.
+
+ Returns:
+ Report dict with `changed`, `applied`, `old`, and `new`.
+
+ Raises:
+ KeyError: If `key` is not present.
+ ValueError: If the target arguments are invalid or the rewrite
+ changed the item's key.
+ """
+ if (remove_fact is None) == (instruction is None):
+ raise ValueError("Provide exactly one of remove_fact= or instruction=.")
+ target = remove_fact if remove_fact is not None else instruction
+
+ old = memory.get(key)
+ if old is None:
+ raise KeyError(f"No {schema_name} with key: {key!r}")
+
+ new = editor.invoke(
+ {"item_json": old.model_dump_json(), "key": key, "target": target}
+ )
+ new_key = key_extractor(new)
+ if new_key != key:
+ raise ValueError(
+ f"Rejected rewrite: the {schema_name} key changed "
+ f"({key!r} -> {new_key!r}). Renaming is not an edit; "
+ "delete the old item and add the new one explicitly."
+ )
+ if new == old:
+ return {"changed": False, "applied": False, "old": old, "new": new}
+
+ if dry_run:
+ return {"changed": True, "applied": False, "old": old, "new": new}
+
+ memory.remove(key)
+ memory.add(new)
+ logger.info("stage=edit_item schema=%s key=%s applied=True", schema_name, key)
+ return {"changed": True, "applied": True, "old": old, "new": new}
+
def _summarize_extracted(self, data: T) -> str:
"""Return a concise summary of extracted data for debug logging."""
try:
diff --git a/hyperextract/types/graph.py b/hyperextract/types/graph.py
index 7697068..ae839e2 100644
--- a/hyperextract/types/graph.py
+++ b/hyperextract/types/graph.py
@@ -73,6 +73,166 @@ DEFAULT_EDGE_PROMPT = (
"{source_text}"
)
+DEFAULT_EDIT_PROMPT = (
+ "You are a precise knowledge-base editor. You receive one stored item as JSON "
+ "and a removal target (a fact or an editing instruction).\n\n"
+ "RULES:\n"
+ "1. Rewrite the item so that the target fact (and only that fact) is removed.\n"
+ "2. Keep every other field, value, and wording EXACTLY unchanged.\n"
+ "3. NEVER change the item's identifier — its key must stay: {key}\n"
+ "4. If the fact does not appear in the item, return it unchanged.\n"
+ "5. Do not add new information.\n\n"
+ "# Current item\n"
+ "{item_json}\n\n"
+ "# Removal target\n"
+ "{target}"
+)
+
+
+class GraphEditMixin:
+ """Hard-delete and LLM-assisted soft-delete for graph-family AutoTypes.
+
+ Requires on `self`: `_node_memory` / `_edge_memory` (OMem), the
+ `node_key_extractor` / `edge_key_extractor` / `nodes_in_edge_extractor`
+ callables, and the `node_editor` / `edge_editor` runnables wired in
+ `__init__`.
+ """
+
+ # ==================== Removal ====================
+
+ def remove_nodes(self, *keys: str) -> dict:
+ """Hard-delete nodes by key, together with any edges they anchor.
+
+ Edges touching a removed node would dangle, so every such edge is
+ removed as well. The search index is invalidated; the next search or
+ `build_index` rebuilds it.
+
+ Args:
+ keys: Node keys (as produced by `node_key_extractor`).
+
+ Returns:
+ Report dict with `removed_nodes`, `not_found_nodes`, and
+ `removed_orphan_edges`.
+ """
+ removed: list[str] = []
+ not_found: list[str] = []
+ removed_node_keys = set()
+ for key in keys:
+ if self._node_memory.remove(key):
+ removed.append(key)
+ removed_node_keys.add(key)
+ else:
+ not_found.append(key)
+
+ orphaned: list = []
+ if removed_node_keys:
+ for edge in list(self._edge_memory.items):
+ endpoints = set(self.nodes_in_edge_extractor(edge))
+ if endpoints & removed_node_keys:
+ edge_key = self.edge_key_extractor(edge)
+ if self._edge_memory.remove(edge_key):
+ orphaned.append(edge_key)
+
+ logger.info(
+ "stage=remove_nodes removed=%d not_found=%d orphan_edges=%d",
+ len(removed),
+ len(not_found),
+ len(orphaned),
+ )
+ return {
+ "removed_nodes": removed,
+ "not_found_nodes": not_found,
+ "removed_orphan_edges": orphaned,
+ }
+
+ def remove_edges(self, *keys: str) -> dict:
+ """Hard-delete edges by key.
+
+ Args:
+ keys: Edge keys (as produced by `edge_key_extractor`).
+
+ Returns:
+ Report dict with `removed_edges` and `not_found_edges`.
+ """
+ removed: list[str] = []
+ not_found: list[str] = []
+ for key in keys:
+ if self._edge_memory.remove(key):
+ removed.append(key)
+ else:
+ not_found.append(key)
+
+ logger.info(
+ "stage=remove_edges removed=%d not_found=%d", len(removed), len(not_found)
+ )
+ return {"removed_edges": removed, "not_found_edges": not_found}
+
+ # ==================== Soft Delete (LLM-assisted) ====================
+
+ def edit_node(
+ self,
+ key: str,
+ *,
+ remove_fact: str | None = None,
+ instruction: str | None = None,
+ dry_run: bool = False,
+ ) -> dict:
+ """Soft-delete a fact from a node via LLM-assisted rewrite.
+
+ Args:
+ key: Node key to edit.
+ remove_fact: Fact to remove from the node (exclusive with
+ `instruction`).
+ instruction: Free-form edit instruction (exclusive with
+ `remove_fact`).
+ dry_run: Return the proposed rewrite without applying it.
+
+ Returns:
+ Report dict with `changed`, `applied`, `old`, and `new`.
+ """
+ return self._edit_item(
+ self._node_memory,
+ self.node_editor,
+ self.node_key_extractor,
+ "node",
+ key,
+ remove_fact,
+ instruction,
+ dry_run,
+ )
+
+ def edit_edge(
+ self,
+ key: str,
+ *,
+ remove_fact: str | None = None,
+ instruction: str | None = None,
+ dry_run: bool = False,
+ ) -> dict:
+ """Soft-delete a fact from an edge via LLM-assisted rewrite.
+
+ Args:
+ key: Edge key to edit.
+ remove_fact: Fact to remove from the edge (exclusive with
+ `instruction`).
+ instruction: Free-form edit instruction (exclusive with
+ `remove_fact`).
+ dry_run: Return the proposed rewrite without applying it.
+
+ Returns:
+ Report dict with `changed`, `applied`, `old`, and `new`.
+ """
+ return self._edit_item(
+ self._edge_memory,
+ self.edge_editor,
+ self.edge_key_extractor,
+ "edge",
+ key,
+ remove_fact,
+ instruction,
+ dry_run,
+ )
+
class AutoGraphSchema(BaseModel, Generic[NodeSchema, EdgeSchema]):
"""Generic schema container for graph-based knowledge patterns."""
@@ -105,6 +265,7 @@ class EdgeListSchema(BaseModel, Generic[EdgeSchema]):
class AutoGraph(
BaseAutoType[AutoGraphSchema[NodeSchema, EdgeSchema]],
+ GraphEditMixin,
Generic[NodeSchema, EdgeSchema],
):
"""AutoGraph - extracts knowledge graphs with nodes and edges from text.
@@ -328,6 +489,21 @@ class AutoGraph(
)
)
+ # LLM-assisted editing (soft delete): rewrite one stored item minus a
+ # given fact, under the same schema. Tests may stub these runnables.
+ edit_template = ChatPromptTemplate.from_messages(
+ [
+ ("system", DEFAULT_EDIT_PROMPT),
+ ("human", "Remove it from the item now."),
+ ]
+ )
+ self.node_editor = edit_template | self.llm_client.with_structured_output(
+ self.node_schema, method="function_calling"
+ )
+ self.edge_editor = edit_template | self.llm_client.with_structured_output(
+ self.edge_schema, method="function_calling"
+ )
+
def _default_prompt(self) -> str:
"""Returns the default prompt for one-stage graph extraction."""
return DEFAULT_GRAPH_PROMPT
@@ -687,6 +863,28 @@ class AutoGraph(
return self.graph_schema(nodes=valid_nodes, edges=refined_edges)
+ def remove_edges(self, *keys: str) -> dict:
+ """Hard-delete edges by key.
+
+ Args:
+ keys: Edge keys (as produced by `edge_key_extractor`).
+
+ Returns:
+ Report dict with `removed_edges` and `not_found_edges`.
+ """
+ removed: list[str] = []
+ not_found: list[str] = []
+ for key in keys:
+ if self._edge_memory.remove(key):
+ removed.append(key)
+ else:
+ not_found.append(key)
+
+ logger.info(
+ "stage=remove_edges removed=%d not_found=%d", len(removed), len(not_found)
+ )
+ return {"removed_edges": removed, "not_found_edges": not_found}
+
# ==================== Merge Logic ====================
def merge_batch_data(
diff --git a/hyperextract/types/hypergraph.py b/hyperextract/types/hypergraph.py
index 959a665..bd5084e 100644
--- a/hyperextract/types/hypergraph.py
+++ b/hyperextract/types/hypergraph.py
@@ -26,6 +26,7 @@ from pydantic import BaseModel, Field, create_model
from hyperextract.utils.logging import get_logger
from .base import BaseAutoType
+from .graph import DEFAULT_EDIT_PROMPT, GraphEditMixin
logger = get_logger(__name__)
@@ -107,6 +108,7 @@ class EdgeListSchema(BaseModel, Generic[EdgeSchema]):
class AutoHypergraph(
BaseAutoType[AutoHypergraphSchema[NodeSchema, EdgeSchema]],
+ GraphEditMixin,
Generic[NodeSchema, EdgeSchema],
):
"""AutoHypergraph - Node-First extraction: Extract entities first, then relationships.
@@ -333,6 +335,20 @@ class AutoHypergraph(
)
)
+ # LLM-assisted editing (soft delete); shares the prompt with AutoGraph.
+ edit_template = ChatPromptTemplate.from_messages(
+ [
+ ("system", DEFAULT_EDIT_PROMPT),
+ ("human", "Remove it from the item now."),
+ ]
+ )
+ self.node_editor = edit_template | self.llm_client.with_structured_output(
+ self.node_schema, method="function_calling"
+ )
+ self.edge_editor = edit_template | self.llm_client.with_structured_output(
+ self.edge_schema, method="function_calling"
+ )
+
# ==================== Prompts ====================
def _default_prompt(self) -> str:
diff --git a/mkdocs.yml b/mkdocs.yml
index 4591d5e..c39f95c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -77,6 +77,7 @@ plugins:
- cli/commands/export.md
- cli/commands/build-index.md
- cli/commands/clean.md
+ - cli/commands/remove.md
- cli/commands/search.md
- cli/commands/talk.md
- cli/commands/info.md
@@ -172,6 +173,7 @@ plugins:
- zh/cli/commands/export.md
- zh/cli/commands/build-index.md
- zh/cli/commands/clean.md
+ - zh/cli/commands/remove.md
- zh/cli/commands/search.md
- zh/cli/commands/talk.md
- zh/cli/commands/info.md
diff --git a/pyproject.toml b/pyproject.toml
index 1d2345b..90b63d9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -104,3 +104,6 @@ ignore = [
"S110", # try/except/pass — intentional in some places
"TC010", # String forward-ref in X | Y union — needed for recursive types
]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["typer.Option", "typer.Argument"]
diff --git a/tests/cli/test_remove.py b/tests/cli/test_remove.py
new file mode 100644
index 0000000..97774d4
--- /dev/null
+++ b/tests/cli/test_remove.py
@@ -0,0 +1,203 @@
+"""Tests for the `he remove` command (hard delete + LLM-assisted soft delete)."""
+
+import json
+
+import pytest
+from pydantic import BaseModel
+from typer.testing import CliRunner
+
+import hyperextract.cli.cli as climod
+from hyperextract.cli.cli import app
+from hyperextract.types import AutoGraph
+from tests.mocks import MockChatModel, MockEmbeddings
+
+runner = CliRunner()
+
+
+class E(BaseModel):
+ name: str
+ type: str = "ENTITY"
+ description: str = ""
+
+
+class R(BaseModel):
+ source: str
+ target: str
+ relation_type: str
+ description: str = ""
+
+
+class FakeEditor:
+ """Stub for node_editor/edge_editor runnables."""
+
+ def __init__(self, rewritten):
+ self.rewritten = rewritten
+ self.calls = []
+
+ def invoke(self, inp):
+ self.calls.append(inp)
+ return self.rewritten
+
+
+def _real_ka():
+ g = AutoGraph(
+ node_schema=E,
+ edge_schema=R,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.source}-{x.relation_type}-{x.target}",
+ nodes_in_edge_extractor=lambda x: (x.source, x.target),
+ llm_client=MockChatModel(),
+ embedder=MockEmbeddings(),
+ )
+ g._node_memory.add(
+ [
+ E(
+ name="Apple",
+ description="Apple was founded by Steve Jobs. Apple makes iPhones.",
+ ),
+ E(name="Google"),
+ ]
+ )
+ g._edge_memory.add(
+ [R(source="Apple", target="Google", relation_type="partner")]
+ )
+ return g
+
+
+def ka_env(tmp_path, monkeypatch):
+ """A real AutoGraph dumped to disk; Template.create returns it in tests."""
+ g = _real_ka()
+ g.metadata["template"] = "general/graph"
+ g.metadata["lang"] = "en"
+ ka = tmp_path / "ka"
+ g.dump(ka)
+ # A stale index dir, like a KA that was searched before.
+ (ka / "index" / "node_index").mkdir(parents=True, exist_ok=True)
+ (ka / "index" / "node_index" / "index.faiss").write_text("x")
+
+ monkeypatch.setattr(climod.Template, "create", staticmethod(lambda *a, **k: g))
+ return ka, g
+
+
+def _data(ka):
+ return json.loads((ka / "data.json").read_text())
+
+
+class TestHardDeleteCli:
+ def test_remove_node_updates_data_and_writes_backup(self, ka_env):
+ ka, _ = ka_env
+ result = runner.invoke(app, ["remove", str(ka), "--node", "Apple", "-y"])
+
+ assert result.exit_code == 0, result.output
+ names = [n["name"] for n in _data(ka)["nodes"]]
+ assert names == ["Google"]
+ # Orphan edge pruned in the persisted data too.
+ assert _data(ka)["edges"] == []
+ # Backup + stale index handling.
+ assert list(ka.glob("data.json.bak.*"))
+ assert not (ka / "index").exists()
+
+ def test_dry_run_persists_nothing(self, ka_env):
+ ka, _ = ka_env
+ result = runner.invoke(
+ app, ["remove", str(ka), "--node", "Apple", "--dry-run"]
+ )
+
+ assert result.exit_code == 0, result.output
+ assert [n["name"] for n in _data(ka)["nodes"]] == ["Apple", "Google"]
+ assert not list(ka.glob("data.json.bak.*"))
+
+ def test_no_match_reports_and_writes_nothing(self, ka_env):
+ ka, _ = ka_env
+ result = runner.invoke(app, ["remove", str(ka), "--node", "Ghost", "-y"])
+
+ assert result.exit_code == 0
+ assert "Nothing matched" in result.output
+ assert [n["name"] for n in _data(ka)["nodes"]] == ["Apple", "Google"]
+ assert not list(ka.glob("data.json.bak.*"))
+
+
+class TestSoftDeleteCli:
+ def test_soft_delete_applies_with_backup(self, ka_env):
+ ka, g = ka_env
+ g.node_editor = FakeEditor(
+ E(name="Apple", description="Apple makes iPhones.")
+ )
+
+ result = runner.invoke(
+ app,
+ [
+ "remove",
+ str(ka),
+ "--edit-node",
+ "Apple",
+ "--fact",
+ "founded by Steve Jobs",
+ "-y",
+ ],
+ )
+
+ assert result.exit_code == 0, result.output
+ apple = next(n for n in _data(ka)["nodes"] if n["name"] == "Apple")
+ assert apple["description"] == "Apple makes iPhones."
+ assert list(ka.glob("data.json.bak.*"))
+
+ def test_soft_delete_dry_run_shows_proposal_only(self, ka_env):
+ ka, g = ka_env
+ g.node_editor = FakeEditor(
+ E(name="Apple", description="Apple makes iPhones.")
+ )
+
+ result = runner.invoke(
+ app,
+ [
+ "remove",
+ str(ka),
+ "--edit-node",
+ "Apple",
+ "--fact",
+ "founded by Steve Jobs",
+ "--dry-run",
+ ],
+ )
+
+ assert result.exit_code == 0, result.output
+ assert "Proposed" in result.output
+ apple = next(n for n in _data(ka)["nodes"] if n["name"] == "Apple")
+ assert "founded by Steve Jobs" in apple["description"]
+ assert not list(ka.glob("data.json.bak.*"))
+
+ def test_soft_delete_key_change_rejected(self, ka_env):
+ ka, g = ka_env
+ g.node_editor = FakeEditor(E(name="Renamed"))
+
+ result = runner.invoke(
+ app,
+ ["remove", str(ka), "--edit-node", "Apple", "--fact", "x", "-y"],
+ )
+
+ assert result.exit_code == 1
+ assert "key changed" in result.output
+ assert [n["name"] for n in _data(ka)["nodes"]] == ["Apple", "Google"]
+
+
+class TestArgumentValidation:
+ def test_hard_and_soft_delete_are_mutually_exclusive(self, ka_env):
+ ka, _ = ka_env
+ result = runner.invoke(
+ app,
+ ["remove", str(ka), "--node", "Apple", "--edit-node", "Apple", "--fact", "x"],
+ )
+ assert result.exit_code == 1
+
+ def test_soft_delete_requires_fact_or_instruction(self, ka_env):
+ ka, _ = ka_env
+ result = runner.invoke(app, ["remove", str(ka), "--edit-node", "Apple"])
+ assert result.exit_code == 1
+
+ def test_no_action_prints_hint(self, ka_env):
+ ka, _ = ka_env
+ result = runner.invoke(app, ["remove", str(ka)])
+ assert result.exit_code == 0
+ assert "Nothing to do" in result.output
diff --git a/tests/types/test_graph_removal.py b/tests/types/test_graph_removal.py
new file mode 100644
index 0000000..18c6cb3
--- /dev/null
+++ b/tests/types/test_graph_removal.py
@@ -0,0 +1,278 @@
+"""Hard delete (remove_nodes / remove_edges) and soft delete (edit_*) for
+graph-family AutoTypes (issue #84)."""
+
+
+import pytest
+from pydantic import BaseModel, Field
+
+from hyperextract.types import AutoGraph, AutoHypergraph
+from tests.mocks import MockChatModel, MockEmbeddings
+
+
+class Entity(BaseModel):
+ name: str
+ type: str = "ENTITY"
+ description: str = ""
+
+
+class Relation(BaseModel):
+ source: str
+ target: str
+ relation_type: str
+ description: str = ""
+
+
+class HyperRelation(BaseModel):
+ participants: list[str] = Field(default_factory=list)
+ relation_type: str = "related"
+
+
+def _graph():
+ return AutoGraph(
+ node_schema=Entity,
+ edge_schema=Relation,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.source}-{x.relation_type}-{x.target}",
+ nodes_in_edge_extractor=lambda x: (x.source, x.target),
+ llm_client=MockChatModel(),
+ embedder=MockEmbeddings(),
+ )
+
+
+def _hypergraph():
+ return AutoHypergraph(
+ node_schema=Entity,
+ edge_schema=HyperRelation,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.relation_type}_{sorted(x.participants)}",
+ nodes_in_edge_extractor=lambda x: tuple(x.participants),
+ llm_client=MockChatModel(),
+ embedder=MockEmbeddings(),
+ )
+
+
+class TestHardDelete:
+ """remove_nodes / remove_edges: key-level deletion with orphan pruning."""
+
+ def test_remove_node_drops_orphan_edges(self):
+ g = _graph()
+ g._node_memory.add(
+ [Entity(name="Apple"), Entity(name="Google"), Entity(name="Meta")]
+ )
+ g._edge_memory.add(
+ [
+ Relation(source="Apple", target="Google", relation_type="partner"),
+ Relation(source="Meta", target="Google", relation_type="partner"),
+ ]
+ )
+
+ report = g.remove_nodes("Apple")
+
+ assert report["removed_nodes"] == ["Apple"]
+ assert report["not_found_nodes"] == []
+ # The Apple-Google edge dangles (Apple gone) and must be pruned;
+ # the Meta-Google edge survives.
+ assert report["removed_orphan_edges"] == ["Apple-partner-Google"]
+ assert {n.name for n in g.nodes} == {"Google", "Meta"}
+ assert {e.source for e in g.edges} == {"Meta"}
+
+ def test_remove_missing_node_is_reported_not_raised(self):
+ g = _graph()
+ report = g.remove_nodes("Nope")
+ assert report["removed_nodes"] == []
+ assert report["not_found_nodes"] == ["Nope"]
+
+ def test_remove_edges(self):
+ g = _graph()
+ g._node_memory.add([Entity(name="A"), Entity(name="B"), Entity(name="C")])
+ g._edge_memory.add(
+ [
+ Relation(source="A", target="B", relation_type="r1"),
+ Relation(source="B", target="C", relation_type="r2"),
+ ]
+ )
+
+ report = g.remove_edges("A-r1-B", "missing")
+
+ assert report["removed_edges"] == ["A-r1-B"]
+ assert report["not_found_edges"] == ["missing"]
+ assert {e.relation_type for e in g.edges} == {"r2"}
+ assert {n.name for n in g.nodes} == {"A", "B", "C"} # nodes untouched
+
+ def test_removal_survives_dump_load_roundtrip(self, tmp_path):
+ g = _graph()
+ g._node_memory.add([Entity(name="A"), Entity(name="B")])
+ g._edge_memory.add([Relation(source="A", target="B", relation_type="r")])
+ g.remove_nodes("A")
+ g.dump(tmp_path)
+
+ reloaded = _graph()
+ reloaded.load(tmp_path)
+
+ assert [n.name for n in reloaded.nodes] == ["B"]
+ assert reloaded.edges == []
+
+ def test_hypergraph_remove_node_drops_touching_hyperedges(self):
+ h = _hypergraph()
+ h._node_memory.add([Entity(name="A"), Entity(name="B"), Entity(name="C")])
+ h._edge_memory.add(
+ [
+ HyperRelation(participants=["A", "B"], relation_type="group"),
+ HyperRelation(participants=["C"], relation_type="solo"),
+ ]
+ )
+
+ report = h.remove_nodes("A")
+
+ assert report["removed_nodes"] == ["A"]
+ keys_removed = report["removed_orphan_edges"]
+ assert len(keys_removed) == 1 and "group_" in keys_removed[0]
+ assert {e.relation_type for e in h.edges} == {"solo"}
+
+ def test_spatiotemporal_subclass_inherits_removal(self):
+ from hyperextract.types import AutoTemporalGraph
+
+ g = AutoTemporalGraph(
+ node_schema=Entity,
+ edge_schema=Relation,
+ node_key_extractor=lambda x: x.name,
+ edge_key_extractor=lambda x: f"{x.source}-{x.relation_type}-{x.target}",
+ time_in_edge_extractor=lambda x: "",
+ nodes_in_edge_extractor=lambda x: (x.source, x.target),
+ llm_client=MockChatModel(),
+ embedder=MockEmbeddings(),
+ )
+ g._node_memory.add([Entity(name="A"), Entity(name="B")])
+
+ report = g.remove_nodes("A", "B", "C")
+ assert report["removed_nodes"] == ["A", "B"]
+ assert report["not_found_nodes"] == ["C"]
+
+
+class FakeEditor:
+ """Stub for the node_editor/edge_editor runnables."""
+
+ def __init__(self, rewritten):
+ self.rewritten = rewritten
+ self.calls = []
+
+ def invoke(self, inp):
+ self.calls.append(inp)
+ return self.rewritten
+
+
+class TestSoftDelete:
+ """edit_node / edit_edge: LLM-assisted fact removal with guardrails."""
+
+ def test_edit_dry_run_does_not_apply(self):
+ g = _graph()
+ g._node_memory.add(
+ [Entity(name="A", description="A was founded by X. A is in Y.")]
+ )
+ g.node_editor = FakeEditor(Entity(name="A", description="A is in Y."))
+
+ report = g.edit_node("A", remove_fact="founded by X", dry_run=True)
+
+ assert report["changed"] is True
+ assert report["applied"] is False
+ # stored item untouched
+ assert "founded by X" in g._node_memory.get("A").description
+
+ def test_edit_applies_rewrite(self):
+ g = _graph()
+ g._node_memory.add(
+ [Entity(name="A", description="A was founded by X. A is in Y.")]
+ )
+ g.node_editor = FakeEditor(Entity(name="A", description="A is in Y."))
+
+ report = g.edit_node("A", remove_fact="founded by X")
+
+ assert report["changed"] is True
+ assert report["applied"] is True
+ assert g._node_memory.get("A").description == "A is in Y."
+
+ def test_editor_receives_item_json_key_and_target(self):
+ g = _graph()
+ g._node_memory.add([Entity(name="A", description="hello")])
+ editor = FakeEditor(Entity(name="A", description="hello"))
+ g.node_editor = editor
+
+ g.edit_node("A", instruction="drop everything about X")
+
+ assert editor.calls[0]["key"] == "A"
+ assert "hello" in editor.calls[0]["item_json"]
+ assert editor.calls[0]["target"] == "drop everything about X"
+
+ def test_key_change_is_rejected(self):
+ g = _graph()
+ g._node_memory.add([Entity(name="A")])
+ g.node_editor = FakeEditor(Entity(name="Renamed")) # identity break
+
+ with pytest.raises(ValueError, match="key changed"):
+ g.edit_node("A", remove_fact="whatever")
+ # nothing was mutated
+ assert g._node_memory.get("A").name == "A"
+
+ def test_unchanged_rewrite_reports_no_change(self):
+ g = _graph()
+ g._node_memory.add([Entity(name="A", description="same")])
+ g.node_editor = FakeEditor(Entity(name="A", description="same"))
+
+ report = g.edit_node("A", remove_fact="not present anyway")
+
+ assert report["changed"] is False
+ assert g._node_memory.get("A").description == "same"
+
+ def test_missing_key_raises(self):
+ g = _graph()
+ with pytest.raises(KeyError):
+ g.edit_node("Nope", remove_fact="x")
+
+ def test_remove_fact_and_instruction_are_exclusive(self):
+ g = _graph()
+ with pytest.raises(ValueError, match="exactly one"):
+ g.edit_node("A", remove_fact="a", instruction="b")
+ with pytest.raises(ValueError, match="exactly one"):
+ g.edit_node("A")
+
+ def test_edit_edge(self):
+ g = _graph()
+ g._node_memory.add([Entity(name="A"), Entity(name="B")])
+ g._edge_memory.add(
+ [
+ Relation(
+ source="A",
+ target="B",
+ relation_type="acquired",
+ description="Acquired by Apple in 2016, first announced in March.",
+ )
+ ]
+ )
+ # relation_type is part of the edge key, so the rewrite keeps it and
+ # only changes the description — a key-changing rewrite is rejected.
+ g.edge_editor = FakeEditor(
+ Relation(
+ source="A",
+ target="B",
+ relation_type="acquired",
+ description="Acquired by Apple in 2016.",
+ )
+ )
+
+ report = g.edit_edge(
+ "A-acquired-B", remove_fact="first announced in March"
+ )
+
+ assert report["applied"] is True
+ assert "announced in March" not in g.edges[0].description
+
+ def test_edit_edge_key_change_is_rejected(self):
+ g = _graph()
+ g._node_memory.add([Entity(name="A"), Entity(name="B")])
+ g._edge_memory.add([Relation(source="A", target="B", relation_type="r")])
+ g.edge_editor = FakeEditor(
+ Relation(source="A", target="B", relation_type="partner")
+ )
+
+ with pytest.raises(ValueError, match="key changed"):
+ g.edit_edge("A-r-B", remove_fact="whatever")