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.mdnew file mode 100644index 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 removaldiff --git a/docs/en/cli/index.md b/docs/en/cli/index.mdindex 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 managementdiff --git a/docs/zh/cli/commands/remove.md b/docs/zh/cli/commands/remove.mdnew file mode 100644index 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.mdindex 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.pyindex 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.pyindex 52711fb..6ab8023 100644--- a/hyperextract/types/base.py+++ b/hyperextract/types/base.py@@ -1,5 +1,6 @@import jsonfrom abc import ABC, abstractmethod+from collections.abc import Callablefrom datetime import datetimefrom pathlib import Pathfrom 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.pyindex 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.pyindex 959a665..bd5084e 100644--- a/hyperextract/types/hypergraph.py+++ b/hyperextract/types/hypergraph.py@@ -26,6 +26,7 @@ from pydantic import BaseModel, Field, create_modelfrom hyperextract.utils.logging import get_loggerfrom .base import BaseAutoType+from .graph import DEFAULT_EDIT_PROMPT, GraphEditMixinlogger = 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.ymlindex 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.mddiff --git a/pyproject.toml b/pyproject.tomlindex 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.pynew file mode 100644index 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.outputdiff --git a/tests/types/test_graph_removal.py b/tests/types/test_graph_removal.pynew file mode 100644index 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")