Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
feat(cli): add --verbose flag for execution stage logging
David Li6b8409e00629
diff --git a/hyperextract/cli/cli.py b/hyperextract/cli/cli.pyindex 401f267..3f2be56 100644--- a/hyperextract/cli/cli.py+++ b/hyperextract/cli/cli.py@@ -11,6 +11,7 @@ from rich.progress import Progress, SpinnerColumn, TextColumnfrom rich.prompt import Promptfrom hyperextract.utils.template_engine import Gallery, Template+from hyperextract.utils.logging import configure_logging, get_loggerfrom .utils import (LOGO,@@ -28,6 +29,7 @@ from .config import (from .commands import list_app, config_appconsole = Console()+logger = get_logger("he")app = typer.Typer(name="he",@@ -50,7 +52,16 @@ def main(help="Show version information",is_eager=True,),+ verbose: bool = typer.Option(+ False,+ "--verbose",+ help="Enable verbose logging of key processes and execution stages",+ is_eager=True,+ ),):+ if verbose:+ configure_logging(level="DEBUG")+ ctx.obj = {"verbose": True}"""Hyper-Extract CLI - Transform document into knowledge-abstract."""if version:from . import __version__@@ -232,7 +243,9 @@ def parse(),):"""Extract knowledge from text to a new directory."""+ logger.info("command=parse input=%s output=%s template=%s lang=%s", input, output, template or "auto", lang or "auto")validate_config()+ logger.info("stage=config_validated")if method:template = f"method/{method}"@@ -279,6 +292,7 @@ def parse(if template_config is None:raise ValueError(f"Template '{template}' not found")console.print(f"[green]Template resolved:[/green] {template_config.name}")+ logger.info("stage=template_resolved template=%s", template_config.name)except ValueError as e:console.print(f"[red]Error:[/red] {e}")raise typer.Exit(1)@@ -293,6 +307,7 @@ def parse(task = progress.add_task("Creating template instance...", total=None)ka = Template.create(template, lang)+ logger.info("stage=template_created")if input_path.is_dir():progress.update(task, description="Processing directory...")@@ -314,6 +329,7 @@ def parse(progress.update(task, description="Extracting knowledge...")ka.feed_text(combined_text)+ logger.info("stage=knowledge_extracted chars=%d", len(combined_text))else:progress.update(task, description="Reading input...")text = read_input(input)@@ -321,6 +337,7 @@ def parse(progress.update(task, description="Extracting knowledge...")ka.feed_text(text)+ logger.info("stage=knowledge_extracted chars=%d", len(text))progress.update(task, description="Saving data...")@@ -336,13 +353,16 @@ def parse()ka.dump(output_path)+ logger.info("stage=data_saved output=%s", output_path)if not no_index:progress.update(task, description="Building search index...")ka.build_index()console.print("[dim]Index built successfully[/dim]")+ logger.info("stage=index_built")progress.update(task, description="Saving index...")ka.dump(output_path)+ logger.info("stage=index_saved")console.print()console.print(@@ -379,6 +399,7 @@ def parse(@app.command(name="show")def show(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory")):"""Visualize Knowledge Abstract using OntoSight."""+ logger.info("command=show ka_path=%s", ka_path)path = validate_ka_with_data(ka_path)template, lang = get_template_from_ka(path)@@ -399,9 +420,11 @@ def show(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory")raise typer.Exit(1)console.print("[bold blue]Visualizing with OntoSight...[/bold blue]")+ logger.info("stage=visualizing")try:ka.show()+ logger.info("stage=visualization_complete")except Exception as e:console.print(f"[red]Error during visualization:[/red] {e}")raise typer.Exit(1)@@ -417,6 +440,7 @@ def show(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory")@app.command(name="info")def info(ka_path: str = typer.Argument(..., help="Knowledge Abstract directory")):"""View Knowledge Abstract information and statistics."""+ logger.info("command=info ka_path=%s", ka_path)import jsonpath = validate_ka_with_data(ka_path)@@ -470,6 +494,7 @@ def search(top_k: int = typer.Option(3, "--top-k", "-n", help="Number of results"),):"""Semantic search in Knowledge Abstract."""+ logger.info("command=search ka_path=%s query=%s top_k=%d", ka_path, query, top_k)import jsonvalidate_config()@@ -497,6 +522,7 @@ def search(progress.update(task, description="Searching...")results = ka.search(query, top_k=top_k)+ logger.info("stage=search_complete results=%d", len(results))except Exception as e:console.print(f"[red]Error:[/red] {e}")@@ -583,6 +609,7 @@ def talk(),):"""Chat with Knowledge Abstract."""+ logger.info("command=talk ka_path=%s query=%s interactive=%s", ka_path, query or "loop", interactive)validate_config()path = validate_ka_with_index(ka_path)@@ -656,6 +683,7 @@ def feed(lang: Optional[str] = typer.Option(None, "--lang", "-l", help="Language"),):"""Append knowledge to an existing Knowledge Abstract."""+ logger.info("command=feed ka_path=%s input=%s", ka_path, input)validate_config()output_path = validate_ka_path(ka_path)@@ -700,9 +728,11 @@ def feed(progress.update(task, description="Appending knowledge...")ka.feed_text(text)+ logger.info("stage=knowledge_appended chars=%d", len(text))progress.update(task, description="Saving data...")ka.dump(output_path)+ logger.info("stage=data_saved")console.print()console.print(@@ -722,6 +752,7 @@ def build_index(force: bool = typer.Option(False, "--force", "-f", help="Force rebuild"),):"""Build vector index for Knowledge Abstract."""+ logger.info("command=build-index ka_path=%s force=%s", ka_path, force)validate_config()path = validate_ka_with_data(ka_path)@@ -759,9 +790,11 @@ def build_index(progress.update(task, description="Building index...")ka.build_index()+ logger.info("stage=index_built")progress.update(task, description="Saving index...")ka.dump(path)+ logger.info("stage=index_saved")except Exception as e:console.print(f"[red]Error:[/red] {e}")diff --git a/hyperextract/cli/commands/config.py b/hyperextract/cli/commands/config.pyindex 5b65f9c..5dcac8f 100644--- a/hyperextract/cli/commands/config.py+++ b/hyperextract/cli/commands/config.py@@ -6,8 +6,10 @@ from rich.table import Tablefrom rich.text import Textfrom ..config import ConfigManager+from hyperextract.utils.logging import get_loggerimport typer+logger = get_logger("he.config")console = Console()app = typer.Typer(@@ -133,6 +135,7 @@ def show(show_all: bool = typer.Option(False, "--show", help="Show all configuration"),):"""Show current configuration."""+ logger.info("command=config-show")_show_config()@@ -160,6 +163,7 @@ def llm(unset: bool = typer.Option(False, "--unset", help="Unset LLM configuration"),):"""Configure LLM settings."""+ logger.info("command=config-llm show=%s unset=%s", show, unset)config = ConfigManager()if show:@@ -214,6 +218,7 @@ def embedder(unset: bool = typer.Option(False, "--unset", help="Unset Embedder configuration"),):"""Configure Embedder settings."""+ logger.info("command=config-embedder show=%s unset=%s", show, unset)config = ConfigManager()if show:@@ -258,6 +263,7 @@ def init(),):"""Initialize configuration interactively."""+ logger.info("command=config-init api_key_provided=%s", api_key is not None)config = ConfigManager()if api_key:diff --git a/hyperextract/cli/commands/list.py b/hyperextract/cli/commands/list.pyindex 823f070..ed24625 100644--- a/hyperextract/cli/commands/list.py+++ b/hyperextract/cli/commands/list.py@@ -7,7 +7,9 @@ from rich.text import Textimport typerfrom hyperextract.utils.template_engine import Gallery+from hyperextract.utils.logging import get_logger+logger = get_logger("he.list")console = Console()app = typer.Typer(@@ -40,6 +42,7 @@ def template(),):"""List all available templates with detailed information."""+ logger.info("command=list-template query=%s autotype=%s lang=%s", query, autotype, language)target_lang = language if language else "en"results = Gallery.list(@@ -113,6 +116,7 @@ def method(),):"""List all available extraction methods with detailed information."""+ logger.info("command=list-method query=%s", query)from hyperextract.methods import list_methodsitems = list_methods()diff --git a/tests/cli/__init__.py b/tests/cli/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/tests/cli/test_verbose.py b/tests/cli/test_verbose.pynew file mode 100644index 0000000..7d15d19--- /dev/null+++ b/tests/cli/test_verbose.py@@ -0,0 +1,93 @@+"""Tests for the --verbose CLI flag."""++import logging+from unittest.mock import patch, MagicMock++import pytest+from typer.testing import CliRunner++from hyperextract.cli.cli import app++runner = CliRunner()+++class TestVerboseFlag:+ """Test that --verbose enables logging."""++ def test_verbose_flag_shows_in_help(self):+ """--verbose appears in top-level help output."""+ result = runner.invoke(app, ["--help"])+ assert result.exit_code == 0+ assert "--verbose" in result.output++ def test_verbose_flag_default_false(self):+ """Without --verbose, logging stays at WARNING level (default)."""+ result = runner.invoke(app, ["--help"])+ assert result.exit_code == 0+ # No log output should appear in help mode+ assert result.output.count("INFO") == 0++ def test_verbose_flag_with_version(self):+ """--verbose combined with --version exits cleanly."""+ result = runner.invoke(app, ["--verbose", "--version"])+ assert result.exit_code == 0+ assert "Hyper-Extract CLI" in result.output++ def test_verbose_sets_debug_log_level(self):+ """When --verbose is passed, root logger level is set to DEBUG."""+ result = runner.invoke(app, ["--verbose", "--version"])+ assert result.exit_code == 0+ root_logger = logging.getLogger()+ # After --verbose, the root logger should be at DEBUG level+ assert root_logger.level == logging.DEBUG++ def test_verbose_before_subcommand(self):+ """--verbose works when placed before a subcommand: he --verbose info --help."""+ result = runner.invoke(app, ["--verbose", "info", "--help"])+ assert result.exit_code == 0++ def test_verbose_before_parse_help(self):+ """he --verbose parse --help exits cleanly."""+ result = runner.invoke(app, ["--verbose", "parse", "--help"])+ assert result.exit_code == 0++ def test_verbose_before_search_help(self):+ """he --verbose search --help exits cleanly."""+ result = runner.invoke(app, ["--verbose", "search", "--help"])+ assert result.exit_code == 0++ def test_verbose_before_talk_help(self):+ """he --verbose talk --help exits cleanly."""+ result = runner.invoke(app, ["--verbose", "talk", "--help"])+ assert result.exit_code == 0++ def test_verbose_before_feed_help(self):+ """he --verbose feed --help exits cleanly."""+ result = runner.invoke(app, ["--verbose", "feed", "--help"])+ assert result.exit_code == 0++ def test_verbose_before_build_index_help(self):+ """he --verbose build-index --help exits cleanly."""+ result = runner.invoke(app, ["--verbose", "build-index", "--help"])+ assert result.exit_code == 0++ def test_verbose_before_show_help(self):+ """he --verbose show --help exits cleanly."""+ result = runner.invoke(app, ["--verbose", "show", "--help"])+ assert result.exit_code == 0++ def test_verbose_before_list_template_help(self):+ """he --verbose list template --help exits cleanly."""+ result = runner.invoke(app, ["--verbose", "list", "template", "--help"])+ assert result.exit_code == 0++ def test_verbose_before_config_help(self):+ """he --verbose config --help exits cleanly."""+ result = runner.invoke(app, ["--verbose", "config", "--help"])+ assert result.exit_code == 0++ def test_verbose_info_missing_ka_exits_with_error(self):+ """he --verbose info <nonexistent> exits with error (verbose logging enabled)."""+ result = runner.invoke(app, ["--verbose", "info", "/nonexistent/path"])+ # Should exit with error code (path doesn't exist)+ assert result.exit_code != 0