Skip to content

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

fix: reject non-txt/md CLI inputs and warn on skipped directory files

Frankie-Xu7ebdb41c9347
diff --git a/docs/en/cli/commands/feed.md b/docs/en/cli/commands/feed.md
index 93caf2f..1de567a 100644
--- a/docs/en/cli/commands/feed.md
+++ b/docs/en/cli/commands/feed.md
@@ -15,7 +15,9 @@ he feed KA_PATH INPUT [OPTIONS]
| Argument | Description |
|----------|-------------|
| `KA_PATH` | Path to existing knowledge abstract directory |
-| `INPUT` | Input file path or `-` for stdin |
+| `INPUT` | Input file path (`.txt` or `.md`) or `-` for stdin |
+
+Supported suffixes are `.txt` and `.md` (case-insensitive, including `.TXT` and `.MD`). This CLI does not parse PDF or Office files and does not perform OCR — convert those documents to `.txt` or `.md` first. Stdin (`-`) is not suffix-checked.
## Options
diff --git a/docs/en/cli/commands/parse.md b/docs/en/cli/commands/parse.md
index 1cb19ba..15e4ef1 100644
--- a/docs/en/cli/commands/parse.md
+++ b/docs/en/cli/commands/parse.md
@@ -14,7 +14,9 @@ he parse INPUT [OPTIONS]
| Argument | Description |
|----------|-------------|
-| `INPUT` | Input file path, directory, or `-` for stdin |
+| `INPUT` | Input file path (`.txt` or `.md`), directory, or `-` for stdin |
+
+Supported suffixes are `.txt` and `.md` (case-insensitive, including `.TXT` and `.MD`). This CLI does not parse PDF or Office files and does not perform OCR — convert those documents to `.txt` or `.md` first. Directory mode is non-recursive: only `.txt`/`.md` files in that folder are read; other regular files are skipped with a warning. Stdin (`-`) is not suffix-checked.
## Options
diff --git a/docs/zh/cli/commands/feed.md b/docs/zh/cli/commands/feed.md
index 276ec41..30bb379 100644
--- a/docs/zh/cli/commands/feed.md
+++ b/docs/zh/cli/commands/feed.md
@@ -15,7 +15,9 @@ he feed KA_PATH INPUT [OPTIONS]
| 参数 | 描述 |
|----------|-------------|
| `KA_PATH` | 现有知识库目录的路径 |
-| `INPUT` | 输入文件路径或 `-` 表示标准输入 |
+| `INPUT` | 输入文件路径(`.txt` 或 `.md`)或 `-` 表示标准输入 |
+
+支持的后缀为 `.txt` 与 `.md`(大小写不敏感,含 `.TXT`、`.MD`)。本 CLI 不解析 PDF / Office,也不做 OCR — 请先转为 `.txt` 或 `.md`。标准输入(`-`)不检查后缀。
## 选项
diff --git a/docs/zh/cli/commands/parse.md b/docs/zh/cli/commands/parse.md
index 42d20e0..ea373eb 100644
--- a/docs/zh/cli/commands/parse.md
+++ b/docs/zh/cli/commands/parse.md
@@ -14,7 +14,9 @@ he parse INPUT [OPTIONS]
| 参数 | 描述 |
|----------|-------------|
-| `INPUT` | 输入文件路径、目录或 `-` 表示标准输入 |
+| `INPUT` | 输入文件路径(`.txt` 或 `.md`)、目录或 `-` 表示标准输入 |
+
+支持的后缀为 `.txt` 与 `.md`(大小写不敏感,含 `.TXT`、`.MD`)。本 CLI 不解析 PDF / Office,也不做 OCR — 请先转为 `.txt` 或 `.md`。目录模式非递归:只读取该目录下的 `.txt`/`.md`;同层其它常规文件会 warning 并跳过。标准输入(`-`)不检查后缀。
## 选项
diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.py
index 5425010..bfe25d0 100644
--- a/hyperextract/cli/cli.py
+++ b/hyperextract/cli/cli.py
@@ -18,8 +18,10 @@ from .config import (
)
from .utils import (
LOGO,
+ collect_directory_text_inputs,
get_template_from_ka,
read_input,
+ require_supported_text_input,
validate_config,
validate_ka_path,
validate_ka_with_data,
@@ -328,12 +330,7 @@ def parse(
if input_path.is_dir():
progress.update(task, description="Processing directory...")
- text_files = list(input_path.glob("*.txt")) + list(input_path.glob("*.md"))
- if not text_files:
- console.print(
- f"[red]Error:[/red] No .txt or .md files found in {input}"
- )
- raise typer.Exit(1)
+ text_files = collect_directory_text_inputs(input_path)
all_text = []
for file_path in text_files:
@@ -350,6 +347,7 @@ def parse(
logger.info("stage=knowledge_extracted chars=%d", len(combined_text))
else:
progress.update(task, description="Reading input...")
+ require_supported_text_input(input)
text = read_input(input)
console.print(f"[dim]Input text: {len(text)} characters[/dim]")
@@ -982,6 +980,7 @@ def feed(
ka.load(output_path)
progress.update(task, description="Reading input...")
+ require_supported_text_input(input)
text = read_input(input)
console.print(f"[dim]Input text: {len(text)} characters[/dim]")
diff --git a/hyperextract/cli/utils.py b/hyperextract/cli/utils.py
index 1c24366..94e2dc8 100644
--- a/hyperextract/cli/utils.py
+++ b/hyperextract/cli/utils.py
@@ -10,6 +10,10 @@ from .config import ConfigManager
console = Console()
+TEXT_INPUT_SUFFIXES = {".txt", ".md"}
+_SKIPPED_FILE_PREVIEW_LIMIT = 10
+_DS_STORE = ".DS_Store"
+
LOGO = r"""
▄▄▄ ▄▄▄ ▄▄▄▄▄▄▄
@@ -22,6 +26,76 @@ LOGO = r"""
"""
+def _is_supported_text_suffix(path: Path) -> bool:
+ """Return True when the path suffix is .txt or .md (case-insensitive)."""
+ return path.suffix.lower() in TEXT_INPUT_SUFFIXES
+
+
+def require_supported_text_input(input_path: str) -> None:
+ """Reject a single-file input whose suffix is not .txt/.md.
+
+ Stdin (``-``) is not suffix-checked. Directories are left to
+ :func:`collect_directory_text_inputs`.
+ """
+ if input_path == "-":
+ return
+ path = Path(input_path)
+ if path.is_dir():
+ return
+ if _is_supported_text_suffix(path):
+ return
+ console.print(
+ f"[red]Error:[/red] Unsupported input type: {path.name or input_path}"
+ )
+ console.print(
+ "This CLI does not parse PDF/Office files. Please convert the file to .txt or .md."
+ )
+ raise typer.Exit(1)
+
+
+def collect_directory_text_inputs(directory: Path) -> list[Path]:
+ """Return non-recursive .txt/.md files in ``directory``.
+
+ Raises:
+ typer.Exit: If the directory contains no .txt or .md files.
+
+ Other regular files at the same level produce a warning (up to 10 names
+ plus a remaining count) and are skipped. ``.DS_Store`` is ignored.
+ """
+ text_files = sorted(
+ (
+ path
+ for path in directory.glob("*")
+ if path.is_file() and _is_supported_text_suffix(path)
+ ),
+ key=lambda path: path.name.lower(),
+ )
+ if not text_files:
+ console.print(f"[red]Error:[/red] No .txt or .md files found in {directory}")
+ raise typer.Exit(1)
+
+ skipped = sorted(
+ (
+ path
+ for path in directory.iterdir()
+ if path.is_file()
+ and path.name != _DS_STORE
+ and not _is_supported_text_suffix(path)
+ ),
+ key=lambda path: path.name.lower(),
+ )
+ if skipped:
+ preview = skipped[:_SKIPPED_FILE_PREVIEW_LIMIT]
+ listed = ", ".join(path.name for path in preview)
+ remaining = len(skipped) - len(preview)
+ extra = f" (+{remaining} more)" if remaining else ""
+ console.print(
+ f"[yellow]Warning:[/yellow] skipped unsupported file(s): {listed}{extra}"
+ )
+
+ return text_files
+
+
def read_input(input_path: str) -> str:
"""Read input from file or stdin."""
if input_path == "-":
diff --git a/tests/cli/test_parse_input_types.py b/tests/cli/test_parse_input_types.py
new file mode 100644
index 0000000..b088840
--- /dev/null
+++ b/tests/cli/test_parse_input_types.py
@@ -0,0 +1,180 @@
+"""CLI input suffix checks for `he parse` and `he feed`.
+
+LLM calls are mocked: Template.create, feed_text, and dump are never real.
+"""
+
+import json
+from contextlib import contextmanager
+from unittest.mock import MagicMock, patch
+
+from typer.testing import CliRunner
+
+from hyperextract.cli.cli import app
+
+runner = CliRunner()
+
+
+def _mock_ka():
+ ka = MagicMock()
+ ka.feed_text = MagicMock(return_value=ka)
+ ka.dump = MagicMock()
+ ka.load = MagicMock()
+ ka.build_index = MagicMock()
+ return ka
+
+
+def _mock_template_config():
+ cfg = MagicMock()
+ cfg.name = "general/graph"
+ return cfg
+
+
+@contextmanager
+def _mock_parse(ka=None):
+ ka = ka or _mock_ka()
+ with (
+ patch("hyperextract.cli.cli.validate_config"),
+ patch(
+ "hyperextract.cli.cli.Template.get",
+ return_value=_mock_template_config(),
+ ),
+ patch("hyperextract.cli.cli.Template.create", return_value=ka),
+ ):
+ yield ka
+
+
+@contextmanager
+def _mock_feed(ka=None):
+ ka = ka or _mock_ka()
+ with (
+ patch("hyperextract.cli.cli.validate_config"),
+ patch("hyperextract.cli.cli.Template.create", return_value=ka),
+ ):
+ yield ka
+
+
+def _invoke_parse(path, output, input_text=None):
+ args = [
+ "parse",
+ str(path),
+ "-o",
+ str(output),
+ "-t",
+ "general/graph",
+ "-l",
+ "en",
+ "--no-index",
+ ]
+ return runner.invoke(app, args, input=input_text)
+
+
+def _make_ka(tmp_path):
+ ka = tmp_path / "ka"
+ ka.mkdir()
+ (ka / "data.json").write_text("{}", encoding="utf-8")
+ (ka / "metadata.json").write_text(
+ json.dumps({"template": "general/graph", "lang": "en"}),
+ encoding="utf-8",
+ )
+ return ka
+
+
+class TestParseInputTypes:
+ def test_single_pdf_exits_and_mentions_txt_md(self, tmp_path):
+ pdf = tmp_path / "notes.pdf"
+ pdf.write_bytes(b"%PDF-1.4 fake")
+ out = tmp_path / "out"
+ with _mock_parse() as ka:
+ result = _invoke_parse(pdf, out)
+
+ assert result.exit_code == 1
+ combined = result.output.lower()
+ assert "txt" in combined
+ assert "md" in combined
+ ka.feed_text.assert_not_called()
+ ka.dump.assert_not_called()
+
+ def test_directory_only_pdf_exits(self, tmp_path):
+ folder = tmp_path / "docs"
+ folder.mkdir()
+ (folder / "only.pdf").write_bytes(b"%PDF-1.4 fake")
+ out = tmp_path / "out"
+ with _mock_parse() as ka:
+ result = _invoke_parse(folder, out)
+
+ assert result.exit_code == 1
+ ka.feed_text.assert_not_called()
+ ka.dump.assert_not_called()
+
+ def test_directory_md_and_pdf_warns_and_reads_md(self, tmp_path):
+ folder = tmp_path / "docs"
+ folder.mkdir()
+ (folder / "a.md").write_text("markdown body", encoding="utf-8")
+ (folder / "b.pdf").write_bytes(b"%PDF-1.4 fake")
+ out = tmp_path / "out"
+ with _mock_parse() as ka:
+ result = _invoke_parse(folder, out)
+
+ assert result.exit_code == 0
+ assert "Warning" in result.output
+ assert "b.pdf" in result.output
+ ka.feed_text.assert_called_once()
+ assert ka.feed_text.call_args[0][0] == "markdown body"
+ ka.dump.assert_called()
+
+ def test_uppercase_txt_and_md_are_accepted(self, tmp_path):
+ notes = tmp_path / "NOTES.TXT"
+ notes.write_text("upper txt", encoding="utf-8")
+ out = tmp_path / "out"
+ with _mock_parse() as ka:
+ result = _invoke_parse(notes, out)
+
+ assert result.exit_code == 0
+ ka.feed_text.assert_called_once_with("upper txt")
+
+ folder = tmp_path / "mixed"
+ folder.mkdir()
+ (folder / "README.MD").write_text("upper md", encoding="utf-8")
+ out2 = tmp_path / "out2"
+ with _mock_parse() as ka2:
+ result2 = _invoke_parse(folder, out2)
+
+ assert result2.exit_code == 0
+ ka2.feed_text.assert_called_once_with("upper md")
+
+ def test_stdin_is_not_suffix_checked(self, tmp_path):
+ out = tmp_path / "out"
+ with _mock_parse() as ka:
+ result = _invoke_parse("-", out, input_text="hello from stdin")
+
+ assert result.exit_code == 0
+ ka.feed_text.assert_called_once_with("hello from stdin")
+
+
+class TestFeedInputTypes:
+ def test_feed_docx_exits(self, tmp_path):
+ ka_dir = _make_ka(tmp_path)
+ docx = tmp_path / "notes.docx"
+ docx.write_bytes(b"PK fake docx")
+ with _mock_feed() as ka:
+ result = runner.invoke(app, ["feed", str(ka_dir), str(docx)])
+
+ assert result.exit_code == 1
+ combined = result.output.lower()
+ assert "txt" in combined
+ assert "md" in combined
+ ka.feed_text.assert_not_called()
+ ka.dump.assert_not_called()
+
+ def test_feed_stdin_is_not_suffix_checked(self, tmp_path):
+ ka_dir = _make_ka(tmp_path)
+ with _mock_feed() as ka:
+ result = runner.invoke(
+ app,
+ ["feed", str(ka_dir), "-"],
+ input="feed stdin text",
+ )
+
+ assert result.exit_code == 0
+ ka.feed_text.assert_called_once_with("feed stdin text")
+ ka.dump.assert_called()