repl api for parsers; moved parser-specific stuff to plugins

Author: telmomenezes

CHANGELOG.md

@@ -12,6 +12,7 @@
 - unified parameter interface for parsers.
 - method `Parser.accepted_params`.
 - maximum depth protection for parsers.
+- repl api for parsers.
 
 ### Changed
 

docs/installation.md

@@ -124,18 +124,18 @@ uv run hyperbase parsers
 Once installed, parsers can be used from the interactive REPL:
 
 ```bash
-hyperbase repl --parser alphabeta --language en
+hyperbase repl --parser alphabeta --lang en
 ```
 
 ```bash
-uv run hyperbase repl --parser alphabeta --language en
+uv run hyperbase repl --parser alphabeta --lang en
 ```
 
 Or programmatically:
 
 ```python
 from hyperbase.parsers import get_parser
 
-parser = get_parser("alphabeta", language="en")
+parser = get_parser("alphabeta", lang="en")
 result = parser.parse_text("The sky is blue.")
 ```

docs/manual/parsers.md

@@ -20,10 +20,10 @@ Parsers are obtained by name with `get_parser()`:
 ```python
 from hyperbase import get_parser
 
-parser = get_parser("alphabeta", language="en")
+parser = get_parser("alphabeta", lang="en")
 ```
 
-The keyword arguments are forwarded to the parser constructor. Each parser plugin defines its own parameters -- for example, `alphabeta` takes a `language` code, while `generative` accepts `model_path`, `device`, `max_length`, and others.
+The keyword arguments are forwarded to the parser constructor. Each parser plugin defines its own parameters -- for example, `alphabeta` takes a `lang` code, while `generative` accepts `model_path`, `device`, `max_length`, and others. Run `hyperbase repl --parser <name> --help` (or `hyperbase read --parser <name> --help`) to see the full set of CLI flags injected by the active plugin.
 
 To see which parsers are installed:
 
@@ -125,42 +125,7 @@ This is what `read_source_to_jsonl()` uses internally -- each line in the output
 
 ## Quality checking
 
-The `hyperbase.parsers.correctness` module provides functions to assess the quality of a parse result.
-
-### Badness check
-
-`badness_check()` runs a comprehensive quality check on a parsed edge, combining structural validation with token-to-atom matching:
-
-```python
-from hyperbase.parsers.correctness import badness_check
-
-errors = badness_check(result.edge, result.tokens)
-if errors:
-    for key, error_list in errors.items():
-        for code, message, severity in error_list:
-            print(f"[{code}] {message} (severity: {severity})")
-else:
-    print("No errors found.")
-```
-
-The function returns a dictionary mapping edge fragments (or the string `'token-matching'`) to lists of `(code, message, severity)` tuples. An empty dictionary means no errors were found.
-
-The checks include:
-
-- **Structural correctness** -- validates the hyperedge against the SH specification (via `Hyperedge.check_correctness()`).
-- **Argument role validation** -- checks that argument roles are drawn from the valid set (`m`, `s`, `p`, `a`, `o`, `i`, `x`, `t`, `j`, `r`, `c`) and that roles like `s`, `p`, `o` are not duplicated.
-- **Junction consistency** -- verifies that junction arguments are consistently typed (all relations or all concepts).
-- **Token matching** -- ensures that every token in the original sentence maps to an atom root in the edge, and vice versa. Handles multi-token atoms, contractions and other non-trivial correspondences.
-
-### Structural quality only
-
-For a lighter check that skips token matching:
-
-```python
-from hyperbase.parsers.correctness import check_structural_quality
-
-errors = check_structural_quality(result.edge)
-```
+Badness/correctness checking lives in the parser plugin that needs it. The generative parser ships [`hyperbase_parser_gen.correctness.badness_check`](https://github.com/telmomenezes/hyperbase-parser-gen) for combined structural + token-matching validation; see that package's docs for usage.
 
 ## CLI
 
@@ -177,7 +142,7 @@ Shows all installed parser plugins and their entry point values.
 The REPL lets you parse sentences interactively:
 
 ```bash
-hyperbase repl --parser alphabeta --language en
+hyperbase repl --parser alphabeta --lang en
 ```
 
 Inside the REPL, type a sentence to parse it. Use `/help` to see available commands, `/settings` to view current configuration, and `/set` to change settings on the fly (e.g. `/set parser generative`). The REPL caches parser instances, so switching between parsers is fast after the first load.
@@ -186,7 +151,7 @@ Inside the REPL, type a sentence to parse it. Use `/help` to see available comma
 
 ```bash
 # Parse a file to JSONL
-hyperbase read article.txt -o output.jsonl --parser alphabeta --language en
+hyperbase read article.txt -o output.jsonl --parser alphabeta --lang en
 
 # Parse a Wikipedia article
 hyperbase read https://en.wikipedia.org/wiki/Hypergraph -o output.jsonl

docs/manual/readers.md

@@ -70,7 +70,7 @@ hyperbase read article.txt -o output.txt
 hyperbase read https://en.wikipedia.org/wiki/Hypergraph -o output.jsonl
 
 # Specify reader and parser explicitly
-hyperbase read source.txt -o output.jsonl --reader plain_text --parser alphabeta --language en
+hyperbase read source.txt -o output.jsonl --reader plain_text --parser alphabeta --lang en
 ```
 
 ## Built-in readers

src/hyperbase/cli/__init__.py

@@ -1,6 +1,101 @@
 import argparse
 import sys
 
+from hyperbase.parsers import Parser, list_parsers
+
+
+def _add_parser_args(
+    subparser: argparse.ArgumentParser, parser_cls: type[Parser]
+) -> None:
+    """Inject *parser_cls*-specific CLI arguments into *subparser*.
+
+    The arguments are derived from ``parser_cls.accepted_params()``: each
+    accepted parameter becomes ``--<name>``. Boolean parameters become
+    ``store_true`` flags. ``max_depth`` (declared on the base
+    :class:`Parser`) is added once globally, not per plugin.
+    """
+    for name, info in parser_cls.accepted_params().items():
+        flag = f"--{name}"
+        # Avoid clobbering an arg that's already been added (e.g. when
+        # the same name appears on multiple subparsers, or when both base
+        # and subclass declare it).
+        if any(
+            flag in (action.option_strings or [])
+            for action in subparser._actions  # type: ignore[attr-defined]
+        ):
+            continue
+        type_: type = info.get("type", str)
+        help_str: str = info.get("description", "") or ""
+        if type_ is bool:
+            subparser.add_argument(
+                flag,
+                action="store_true",
+                default=None,
+                help=help_str,
+            )
+        else:
+            subparser.add_argument(
+                flag,
+                type=type_,
+                default=None,
+                help=help_str,
+            )
+
+
+def _resolve_parser_name(
+    argv: list[str], subcommand: str, default: str | None
+) -> str | None:
+    """Look ahead in *argv* for ``--parser <name>`` under *subcommand*.
+
+    Returns the parser name to use for dynamically injecting parser-specific
+    args, or *default* if not specified. Falls back to the saved REPL
+    settings if no value is on the command line and *default* is ``None``.
+    """
+    pre = argparse.ArgumentParser(add_help=False)
+    pre.add_argument("--parser", default=None)
+
+    # Strip everything before the subcommand so the pre-parser only
+    # sees flags for the right subcommand. ``parse_known_args`` ignores
+    # the rest.
+    try:
+        idx = argv.index(subcommand)
+        rest = argv[idx + 1 :]
+    except ValueError:
+        rest = argv
+
+    pre_args, _ = pre.parse_known_args(rest)
+    if pre_args.parser:
+        return pre_args.parser
+    if default is not None:
+        return default
+
+    # Fall back to whatever the REPL last saved.
+    try:
+        from hyperbase.cli.repl import load_saved_settings
+
+        saved = load_saved_settings()
+        if saved.get("parser"):
+            return str(saved["parser"])
+    except Exception:
+        pass
+    return None
+
+
+def _maybe_load_parser_class(name: str | None) -> type[Parser] | None:
+    if not name:
+        return None
+    parsers = list_parsers()
+    if name not in parsers:
+        return None
+    try:
+        return parsers[name].load()  # type: ignore[no-any-return]
+    except Exception as e:
+        print(
+            f"Warning: failed to load parser {name!r}: {e}",
+            file=sys.stderr,
+        )
+        return None
+
 
 def main() -> None:
     parser = argparse.ArgumentParser(
@@ -35,7 +130,7 @@ def main() -> None:
     read_parser.add_argument(
         "--parser",
         type=str,
-        default="generative",
+        default=None,
         help="Parser plugin name (default: generative)",
     )
     read_parser.add_argument(
@@ -44,24 +139,6 @@ def main() -> None:
         default="auto",
         help="Reader name or 'auto' (default: auto)",
     )
-    read_parser.add_argument(
-        "--model_path",
-        type=str,
-        default=None,
-        help="Path to trained model (generative parser)",
-    )
-    read_parser.add_argument(
-        "--language",
-        type=str,
-        default=None,
-        help="Language for alphabeta parser",
-    )
-    read_parser.add_argument(
-        "--device",
-        type=str,
-        default=None,
-        help="Device to use (cuda/cpu/mps)",
-    )
     read_parser.add_argument(
         "--batch_size",
         type=int,
@@ -75,68 +152,32 @@ def main() -> None:
         help="Interactive REPL for SH parsers",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-
     repl_parser.add_argument(
         "--parser",
         type=str,
         default=None,
-        help="Parser plugin name (e.g. generative, alphabeta)",
-    )
-    repl_parser.add_argument(
-        "--model_path",
-        type=str,
-        default=None,
-        help="Path to trained model (generative parser)",
-    )
-    repl_parser.add_argument(
-        "--language",
-        type=str,
-        default=None,
-        help="Language for alphabeta parser (de, en, es, fr, pt, etc.)",
-    )
-    repl_parser.add_argument(
-        "--max_length",
-        type=int,
-        default=None,
-        help="Maximum sequence length (generative parser)",
-    )
-    repl_parser.add_argument(
-        "--num_beams",
-        type=int,
-        default=None,
-        help="Number of beams for beam search (generative parser)",
-    )
-    repl_parser.add_argument(
-        "--num_candidates",
-        type=int,
-        default=None,
-        help="Number of candidates for beam search (generative parser)",
-    )
-    repl_parser.add_argument(
-        "--use_constraints",
-        action="store_true",
-        default=None,
-        help="Enable post-generation SH constraint validation (generative parser)",
-    )
-    repl_parser.add_argument(
-        "--check_badness",
-        action="store_true",
-        default=None,
-        help="Enable badness check after parsing",
+        help="Parser plugin name",
     )
     repl_parser.add_argument(
         "--statistics",
         action="store_true",
         default=None,
-        help="Show parse statistics",
-    )
-    repl_parser.add_argument(
-        "--device",
-        type=str,
-        default=None,
-        help="Device to use (cuda/cpu/mps)",
+        help="Show parse statistics after each parse",
     )
 
+    # Dynamically inject parser-specific args, derived from the active
+    # parser's ``accepted_params()``. We do this in two passes so that
+    # plugin packages stay the source of truth for their CLI surface.
+    argv = sys.argv[1:]
+    for sub_name, sub_parser, default_parser in (
+        ("read", read_parser, "generative"),
+        ("repl", repl_parser, None),
+    ):
+        active = _resolve_parser_name(argv, sub_name, default_parser)
+        cls = _maybe_load_parser_class(active)
+        if cls is not None:
+            _add_parser_args(sub_parser, cls)
+
     args = parser.parse_args()
 
     if args.command is None:

src/hyperbase/cli/read.py

@@ -2,9 +2,11 @@
 import os
 import sys
 
-from hyperbase.parsers import get_parser
+from hyperbase.parsers import get_parser, list_parsers
 from hyperbase.readers import get_reader
 
+DEFAULT_PARSER = "generative"
+
 
 def run_read(args: argparse.Namespace) -> None:
     ext = os.path.splitext(args.output)[1].lower()
@@ -27,24 +29,34 @@ def run_read(args: argparse.Namespace) -> None:
         )
         sys.exit(1)
 
-    # Build parser kwargs
-    kwargs = {}
-    if args.parser == "generative":
-        if args.model_path:
-            kwargs["model_path"] = args.model_path
-        if args.device:
-            kwargs["device"] = args.device
-    elif args.parser == "alphabeta":
-        if args.language:
-            kwargs["lang"] = args.language
+    parser_name: str = getattr(args, "parser", None) or DEFAULT_PARSER
+
+    parsers = list_parsers()
+    if parser_name not in parsers:
+        avail = ", ".join(sorted(parsers)) or "(none)"
+        print(
+            f"Error: parser {parser_name!r} is not installed. Available: {avail}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    parser_cls = parsers[parser_name].load()
+
+    # Build kwargs from the parser's own ``accepted_params``: every
+    # parser-specific CLI flag was injected by ``hyperbase.cli`` based on
+    # the same dict, so this is just the inverse mapping.
+    kwargs: dict[str, object] = {}
+    for name in parser_cls.accepted_params():
+        value = getattr(args, name, None)
+        if value is not None:
+            kwargs[name] = value
 
     try:
-        parser = get_parser(args.parser, **kwargs)
+        parser = get_parser(parser_name, **kwargs)
     except ValueError as e:
         print(f"Error: {e}", file=sys.stderr)
         sys.exit(1)
 
-    print(f"Parser: {args.parser}", file=sys.stderr)
+    print(f"Parser: {parser_name}", file=sys.stderr)
 
     sentences = 0
     edges = 0