vera 0.3.2__py3-none-any.whl

vera-0.3.2.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: vera
+Version: 0.3.2
+Summary: Command-line interface for VERA documents
+Project-URL: Homepage, https://github.com/dkylewillis/vera
+Project-URL: Repository, https://github.com/dkylewillis/vera
+Project-URL: Documentation, https://dkylewillis.github.io/vera/packages/vera-cli/
+Author: Kyle Willis
+License: Apache-2.0
+Keywords: cli,document,semantic-search,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.10
+Requires-Dist: vera-doc>=0.3.2
+Requires-Dist: vera-embed-openai>=0.3.2
+Requires-Dist: vera-ingest-pymupdf>=0.3.2
+Requires-Dist: vera-ingest>=0.3.2
+Provides-Extra: docling
+Requires-Dist: vera-ingest-docling>=0.3.2; extra == 'docling'
+Provides-Extra: mcp
+Requires-Dist: vera-mcp>=0.3.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# vera
+
+`vera` provides the `vera` command-line interface over `vera-doc`,
+`vera-ingest`, `vera-ingest-pymupdf`, and `vera-embed-openai`. It owns command parsing, text and
+JSON output, exit codes, and retrieval evaluation. The Python import remains
+`vera_cli`.
+
+`vera convert` accepts repeatable `--pipeline-option KEY=VALUE` flags for
+provider-owned ingest settings. Legacy flags such as `--chunk-size`,
+`--overlap`, `--ocr`, `--ocr-language`, and `--ocr-dpi` remain compatibility
+aliases for pipelines that accept them (`--ocr-language`/`--ocr-dpi` are
+Tesseract/PyMuPDF); explicit `--pipeline-option` values win for the same key.
+
+## Install
+
+```bash
+python -m pip install "vera>=0.3.2"
+```
+
+Install the `mcp` extra to enable `vera mcp`, or the `docling` extra for
+Docling PDF layout conversion and search-only DOCX/PPTX/XLSX/HTML ingest:
+
+```bash
+python -m pip install "vera[mcp]>=0.3.2"
+python -m pip install "vera[docling]>=0.3.2"
+```
+
+`pip install vera-cli` remains a compatibility alias that depends on `vera`.
+
+See the [vera CLI documentation](https://dkylewillis.github.io/vera/packages/vera-cli/)
+for installation, recipes, evaluation, and command reference.
+
+See the [CLI reference](https://github.com/dkylewillis/vera/blob/main/docs/cli-reference.md).

vera-0.3.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+vera_cli/__init__.py,sha256=IqMxxpNCm1rDJr-Rrr_xHzwPFzNKPpQuLSj275eMSIA,122
+vera_cli/__main__.py,sha256=EwrK-u-Eg2JchXI165ldrOFBIaW6EO7Cx0ZMnwRRU6c,49
+vera_cli/commands.py,sha256=MVqJXhchP8oeXjU7ypAg9UiftizVcKw_MQLtoCHGpxQ,21337
+vera_cli/evaluate.py,sha256=uWeYdP9PoepsLyxLHL6d5cUK0-7GbowG5straIk3oIM,4990
+vera_cli/main.py,sha256=vywzuYin0FLArTOon-ycRt1bjVpZIwOxCCJBSFxm1HM,14627
+vera-0.3.2.dist-info/METADATA,sha256=pKL7iCnX6eUTI2Z9-yV9EJVScIzQu0PJZxS-8c8SsAs,2221
+vera-0.3.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+vera-0.3.2.dist-info/entry_points.txt,sha256=5_U6LyQcS-MRU9VE7mWzLEvzBLNlDtHDjm91So4wy4Q,39
+vera-0.3.2.dist-info/RECORD,,

vera-0.3.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vera-0.3.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vera = vera_cli:main

vera_cli/__init__.py

@@ -0,0 +1,4 @@
+from .commands import str_to_bool
+from .main import build_parser, main
+
+__all__ = ["str_to_bool", "build_parser", "main"]

vera_cli/__main__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+raise SystemExit(main())

vera_cli/commands.py

@@ -0,0 +1,626 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from vera_doc import Citation, UnknownEmbeddingModelError
+from vera_doc.collection import build_library_index, library_index_status, update_library_index
+from vera_doc.corpus import VeraCorpus
+from vera_doc.document import VeraDocument
+from vera_embed_openai import (
+    OpenAIEmbedderError,
+)
+from vera_embed_openai import (
+    ensure_registered as ensure_openai_embedder_registered,
+)
+from vera_ingest import (
+    ReservedMetadataKeyError,
+    UnknownIngestPipelineError,
+    batch_convert,
+    convert,
+)
+from vera_ingest.viewer import (
+    ensure_requested_figures,
+    export_figures,
+    export_source_document,
+    figures,
+    get_chunk_json,
+    get_source_document,
+    result_payload,
+)
+from vera_ingest_pymupdf import (
+    OCRLanguageDownloadError,
+    UnknownOCRLanguageError,
+    describe_ocr_languages,
+    download_ocr_language_data,
+)
+
+ensure_openai_embedder_registered()
+
+_TRUE_TOKENS = {"1", "true", "yes", "y", "on"}
+_FALSE_TOKENS = {"0", "false", "no", "n", "off", ""}
+
+
+def str_to_bool(value: str) -> bool:
+    lowered = str(value).strip().lower()
+    if lowered in _TRUE_TOKENS:
+        return True
+    if lowered in _FALSE_TOKENS:
+        return False
+    raise ValueError(f"invalid boolean value: {value!r}")
+
+
+def _document_for(target, result) -> VeraDocument:
+    if isinstance(target, VeraCorpus):
+        return target.document(result.file)
+    return target
+
+
+def _archive_locator(requested: str, document: VeraDocument) -> dict[str, str]:
+    return {"file": requested, "path": str(Path(document.path).resolve())}
+
+
+def _pipeline_options_from_args(args) -> dict[str, object]:
+    return _key_value_options_from_args(getattr(args, "pipeline_options", []) or [])
+
+
+def _embedder_options_from_args(args) -> dict[str, object]:
+    return _key_value_options_from_args(getattr(args, "embedder_options", []) or [])
+
+
+def _coerce_option_value(raw: str) -> object:
+    """Coerce a KEY=VALUE token without ``float()``.
+
+    Dotted tokens such as ``3.10`` or ``ocr_language=1.0`` stay strings.
+    Whole-digit tokens become ints; ``true``/``false``/``yes``/``no``/``on``/
+    ``off`` become bools.
+    """
+    text = str(raw).strip()
+    lowered = text.lower()
+    if lowered in {"true", "yes", "y", "on"}:
+        return True
+    if lowered in {"false", "no", "n", "off"}:
+        return False
+    if text.isdigit() or (text.startswith("-") and text[1:].isdigit()):
+        return int(text)
+    return text
+
+
+def _key_value_options_from_args(pairs) -> dict[str, object]:
+    options: dict[str, object] = {}
+    for key, raw in pairs:
+        options[key] = _coerce_option_value(raw)
+    return options
+
+
+def _metadata_from_args(args) -> dict[str, object] | None:
+    pairs = getattr(args, "metadata", None) or []
+    return _key_value_options_from_args(pairs) or None
+
+
+def _where_from_args(pairs) -> dict[str, object] | None:
+    """Parse ``--where KEY=VALUE`` pairs: AND across keys, comma IN, union repeats."""
+    if not pairs:
+        return None
+    where: dict[str, object] = {}
+    for key, raw in pairs:
+        parts = str(raw).split(",")
+        if any(not part.strip() for part in parts):
+            raise ValueError("where values must not be empty")
+        values = [_coerce_option_value(part.strip()) for part in parts]
+        existing = where.get(key)
+        if existing is None:
+            where[key] = values[0] if len(values) == 1 else values
+            continue
+        current = existing if isinstance(existing, list) else [existing]
+        for value in values:
+            if value not in current:
+                current.append(value)
+        where[key] = current[0] if len(current) == 1 else current
+    return where
+
+
+def cmd_convert(args) -> int:
+    input_path = Path(args.input)
+    pipeline_options = _pipeline_options_from_args(args)
+    embedder_options = _embedder_options_from_args(args)
+    metadata = _metadata_from_args(args)
+    try:
+        if input_path.is_dir():
+            if args.output:
+                message = (
+                    "Directory conversion creates each .vera beside its source file; "
+                    "do not provide an output path."
+                )
+                if args.json:
+                    print(json.dumps({"ok": False, "error": message}))
+                else:
+                    print(message, file=sys.stderr)
+                return 2
+            report = batch_convert(
+                args.input,
+                recursive=args.recursive,
+                overwrite=args.overwrite,
+                model=args.model,
+                parser=args.parser,
+                chunk_size=args.chunk_size,
+                overlap=args.overlap,
+                store_original=args.store_original,
+                ocr_mode=args.ocr_mode,
+                ocr_language=args.ocr_language,
+                ocr_dpi=args.ocr_dpi,
+                ocr_download=args.ocr_allow_download,
+                pipeline_options=pipeline_options or None,
+                embedder_options=embedder_options or None,
+                metadata=metadata,
+            )
+            unsuccessful = report["failed"] + report["malformed"]
+            if args.json:
+                print(json.dumps({"ok": unsuccessful == 0, **report}))
+            else:
+                print(
+                    f"Found {report['discovered']} files: {report['converted']} converted, "
+                    f"{report['skipped']} skipped, {report['malformed']} malformed, "
+                    f"{report['failed']} failed"
+                )
+                for entry in report["malformed_existing"]:
+                    issues = "; ".join(entry["issues"])
+                    print(f"Malformed {entry['output']}: {issues}", file=sys.stderr)
+                for entry in report["errors"]:
+                    print(f"Failed {entry['input']}: {entry['error']}", file=sys.stderr)
+            return 1 if unsuccessful else 0
+
+        output = args.output or str(input_path.with_suffix(".vera"))
+        path = convert(
+            args.input,
+            output,
+            model=args.model,
+            parser=args.parser,
+            chunk_size=args.chunk_size,
+            overlap=args.overlap,
+            store_original=args.store_original,
+            ocr_mode=args.ocr_mode,
+            ocr_language=args.ocr_language,
+            ocr_dpi=args.ocr_dpi,
+            ocr_download=args.ocr_allow_download,
+            pipeline_options=pipeline_options or None,
+            embedder_options=embedder_options or None,
+            metadata=metadata,
+        )
+    except (
+        UnknownIngestPipelineError,
+        UnknownEmbeddingModelError,
+        ReservedMetadataKeyError,
+    ) as exc:
+        if args.json:
+            print(json.dumps({"ok": False, "error": str(exc)}))
+        else:
+            print(str(exc), file=sys.stderr)
+        return 2
+    except (ValueError, FileNotFoundError, OpenAIEmbedderError) as exc:
+        if args.json:
+            print(json.dumps({"ok": False, "error": str(exc)}))
+        else:
+            print(str(exc), file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps({"ok": True, "output": str(path)}))
+    else:
+        print(f"Created {path}")
+    return 0
+
+
+def cmd_inspect(args) -> int:
+    doc = VeraDocument.open(args.file)
+    try:
+        info = doc.inspect()
+        if args.json:
+            print(json.dumps({**info, **_archive_locator(args.file, doc)}))
+            return 0
+        print(f"File: {args.file}")
+        print(f"Format: {info.get('format_name', 'VERA')} v{info.get('format_version')}")
+        print(f"Source: {info.get('source_file_name') or info.get('source')}")
+        print(f"Pages: {info.get('pages')}")
+        print(f"Chunks: {info.get('chunks')}")
+        print(f"Embedding model: {info.get('default_embedding_model')}")
+        print(f"Embedding dimensions: {info.get('default_embedding_dimension')}")
+        print(f"Embedding normalization: {info.get('default_embedding_normalization', 'unknown')}")
+        print(f"Parser: {info.get('parser_name')}")
+        print(f"Created: {info.get('created_at')}")
+    finally:
+        doc.close()
+    return 0
+
+
+def _chunk_not_found_message(chunk_id: str) -> str:
+    return f"chunk not found: {chunk_id}"
+
+
+def _emit_get_error(args, message: str) -> int:
+    if args.json:
+        print(json.dumps({"ok": False, "error": message}))
+    else:
+        print(message, file=sys.stderr)
+    return 1
+
+
+def cmd_get(args) -> int:
+    chunk_id = args.chunk_id
+    if not str(chunk_id).strip():
+        return _emit_get_error(args, _chunk_not_found_message(chunk_id))
+
+    doc = VeraDocument.open(args.file)
+    try:
+        try:
+            records = doc.get(ids=[chunk_id])
+            if not records:
+                return _emit_get_error(args, _chunk_not_found_message(chunk_id))
+            payload = get_chunk_json(
+                args.file,
+                doc,
+                records[0],
+                include_figures=args.figures,
+                include_regions=args.regions,
+            )
+        except ValueError as exc:
+            return _emit_get_error(args, str(exc))
+        if args.json:
+            print(json.dumps(payload))
+            return 0
+        citation = Citation.from_metadata(records[0].metadata)
+        print(f"Source: {citation.source_filename}")
+        page = (
+            citation.page_start
+            if citation.page_start == citation.page_end
+            else f"{citation.page_start}-{citation.page_end}"
+        )
+        print(f"Page: {page}")
+        print(f"Heading: {citation.heading_path or ''}")
+        print()
+        print(records[0].text)
+    finally:
+        doc.close()
+    return 0
+
+
+def _emit_cli_error(args, message: str, *, code: int = 1) -> int:
+    if getattr(args, "json", False):
+        print(json.dumps({"ok": False, "error": message}))
+    else:
+        print(message, file=sys.stderr)
+    return code
+
+
+def cmd_search(args) -> int:
+    target_path = Path(args.file)
+    includes = getattr(args, "include", None)
+    if includes and not target_path.is_dir():
+        return _emit_cli_error(args, "--include applies to directory search only", code=2)
+    try:
+        where = _where_from_args(getattr(args, "where", None) or [])
+    except ValueError as exc:
+        return _emit_cli_error(args, str(exc), code=2)
+    target = (
+        VeraCorpus.open(
+            args.file,
+            recursive=True if getattr(args, "recursive", False) else None,
+            excludes=getattr(args, "exclude", None),
+            includes=includes,
+        )
+        if target_path.is_dir()
+        else VeraDocument.open(args.file)
+    )
+    try:
+        try:
+            results = target.search(
+                text=args.query,
+                mode=args.mode,
+                top_k=args.top_k,
+                context_chunks=args.context_chunks,
+                where=where,
+            )
+        except OpenAIEmbedderError as exc:
+            return _emit_cli_error(args, str(exc), code=1)
+        if args.json:
+            payload = []
+            for result in results:
+                entry = result_payload(
+                    result,
+                    document=_document_for(target, result),
+                    include_figures=args.figures,
+                    include_regions=args.regions,
+                )
+                payload.append(entry)
+            response = {"query": args.query, "mode": args.mode, "results": payload}
+            if isinstance(target, VeraCorpus):
+                response["index"] = target.index_search_report()
+                response["skipped_files"] = target.invalid_files
+                response["skipped_semantic_model_groups"] = target.skipped_semantic_model_groups
+            print(json.dumps(response))
+            return 0
+        if isinstance(target, VeraCorpus):
+            report = target.index_search_report()
+            if report.get("used"):
+                print(f"Index: {report.get('index')} (active)")
+            elif report.get("exists"):
+                reasons = "; ".join(report.get("reasons", []))
+                print(f"Index: fallback ({reasons})")
+            for group in target.skipped_semantic_model_groups:
+                print(
+                    "Warning: skipped semantic model group "
+                    f"{group['model_name']} ({group['dimension']} dimensions): "
+                    f"{group['error']}"
+                )
+        for result in results:
+            print(f"Score: {result.score:.4f}")
+            file = getattr(result, "file", None)
+            if file:
+                print(f"File: {file}")
+            citation = result.citation
+            print(f"Source: {citation.source_filename}")
+            page = (
+                citation.page_start
+                if citation.page_start == citation.page_end
+                else f"{citation.page_start}-{citation.page_end}"
+            )
+            print(f"Page: {page}")
+            print(f"Heading: {citation.heading_path or ''}")
+            print()
+            print(result.record.text)
+            print("-" * 72)
+    finally:
+        target.close()
+    return 0
+
+
+def _print_index_report(report: dict) -> None:
+    print(f"Index: {report['index']}")
+    print(f"Directory: {report['directory']}")
+    if "fresh" in report:
+        print(f"Status: {'fresh' if report['fresh'] else 'stale'}")
+        for reason in report.get("reasons", []):
+            print(f"- {reason}")
+        return
+    print(f"Files: {report['indexed']}/{report['discovered']}")
+    print(f"Chunks: {report['chunks']}")
+    print(
+        "Changes: "
+        f"{report['added']} added, {report['changed']} changed, "
+        f"{report['moved']} moved, {report['removed']} removed"
+    )
+    for category in ("invalid", "incompatible"):
+        for item in report.get(category, []):
+            print(f"{category.title()}: {item['file']}: {item['reason']}")
+
+
+def cmd_index_build(args) -> int:
+    report = build_library_index(
+        args.directory,
+        recursive=args.recursive,
+        excludes=args.exclude or (),
+        includes=args.include or (),
+    )
+    if args.json:
+        print(json.dumps(report))
+    else:
+        _print_index_report(report)
+    return 0
+
+
+def cmd_index_update(args) -> int:
+    report = update_library_index(args.directory)
+    if args.json:
+        print(json.dumps(report))
+    else:
+        _print_index_report(report)
+    return 0
+
+
+def cmd_index_status(args) -> int:
+    report = library_index_status(args.directory)
+    if args.json:
+        print(json.dumps(report))
+    else:
+        _print_index_report(report)
+    return 0 if report.get("fresh") else 1
+
+
+def cmd_validate(args) -> int:
+    doc = VeraDocument.open(args.file)
+    try:
+        report = doc.validate()
+    finally:
+        doc.close()
+    if args.json:
+        print(json.dumps({**report, **_archive_locator(args.file, doc)}))
+        return 0 if report["ok"] else 1
+    print(f"VERA validation: {'PASS' if report['ok'] else 'FAIL'}")
+    print(f"File: {args.file}")
+    counts = report["counts"]
+    print(f"Chunks: {counts['chunks']}")
+    print(f"Embeddings: {counts['embeddings']}")
+    print(f"Attachments: {counts['attachments']}")
+    print(f"FTS rows: {counts['fts_rows']}")
+    print(
+        f"Original document: {'present' if report['checks']['original_document_present'] else 'missing'}"
+    )
+    print(f"Issues: {len(report['issues'])}")
+    for issue in report["issues"]:
+        print(f"- {issue}")
+    return 0 if report["ok"] else 1
+
+
+def cmd_export(args) -> int:
+    doc = VeraDocument.open(args.file)
+    try:
+        try:
+            path = export_source_document(doc, args.output)
+        except ValueError as exc:
+            if args.json:
+                print(json.dumps({"ok": False, "error": str(exc)}))
+            else:
+                print(f"Error: {exc}", file=sys.stderr)
+            return 1
+        source = get_source_document(doc)
+    finally:
+        doc.close()
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "ok": True,
+                    "output": path,
+                    "filename": source.filename,
+                    "mime_type": source.media_type,
+                    "hash": source.checksum,
+                }
+            )
+        )
+    else:
+        print(f"Exported {path}")
+    return 0
+
+
+def cmd_figures(args) -> int:
+    doc = VeraDocument.open(args.file)
+    try:
+        requested = list(args.asset_id) if args.asset_id else None
+        try:
+            if args.out_dir:
+                items = export_figures(
+                    doc,
+                    args.out_dir,
+                    asset_ids=requested,
+                    page_start=args.page_start,
+                    page_end=args.page_end,
+                )
+            else:
+                items = figures(
+                    doc,
+                    page_start=args.page_start,
+                    page_end=args.page_end,
+                    attachment_ids=requested,
+                )
+                ensure_requested_figures(requested, items)
+        except ValueError as exc:
+            if args.json:
+                print(json.dumps({"ok": False, "error": str(exc)}))
+            else:
+                print(f"Error: {exc}", file=sys.stderr)
+            return 1
+    finally:
+        doc.close()
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "ok": True,
+                    "file": args.file,
+                    "out_dir": args.out_dir,
+                    "figures": items,
+                }
+            )
+        )
+        return 0
+    if args.out_dir:
+        noun = "figure" if len(items) == 1 else "figures"
+        print(f"Wrote {len(items)} {noun} to {args.out_dir}")
+    elif not items:
+        print("No figures")
+        return 0
+    for item in items:
+        location = item.get("path") or item.get("asset_id")
+        page = item.get("page_number")
+        caption = item.get("caption") or ""
+        line = f"{location}  page {page}"
+        if caption:
+            line = f"{line}  {caption}"
+        print(line)
+    return 0
+
+
+def cmd_mcp(args) -> int:
+    try:
+        from vera_mcp import main as mcp_main
+    except ImportError:
+        print(
+            "vera mcp requires the optional MCP extra. "
+            "Install with: python -m pip install 'vera[mcp]>=0.3.2'",
+            file=sys.stderr,
+        )
+        return 2
+    return mcp_main()
+
+
+def cmd_ocr_languages_list(args) -> int:
+    entries = describe_ocr_languages(args.language)
+    if args.json:
+        print(json.dumps({"ok": True, "languages": entries}))
+        return 0
+    for entry in entries:
+        state = "bundled" if entry["bundled"] else ("cached" if entry["cached"] else "not cached")
+        size = entry.get("size_bytes")
+        size_note = f", {size / (1024 * 1024):.1f} MB" if isinstance(size, int) else ""
+        downloadable = "" if entry["downloadable"] else " (manual TESSDATA_PREFIX install required)"
+        print(f"{entry['code']:<8} {entry['name']:<24} {state}{size_note}{downloadable}")
+    return 0
+
+
+def cmd_ocr_languages_download(args) -> int:
+    downloaded: list[str] = []
+
+    def report_progress(code: str, downloaded_bytes: int, total_bytes: int) -> None:
+        if args.json or total_bytes <= 0:
+            return
+        percent = min(100, int(downloaded_bytes * 100 / total_bytes))
+        print(f"\r{code}: {percent}%", end="", file=sys.stderr, flush=True)
+
+    try:
+        cache_dir = download_ocr_language_data(args.language, progress=report_progress)
+    except (UnknownOCRLanguageError, OCRLanguageDownloadError) as exc:
+        if args.json:
+            print(json.dumps({"ok": False, "error": str(exc)}))
+        else:
+            print(str(exc), file=sys.stderr)
+        return 2
+    if not args.json:
+        print(file=sys.stderr)  # newline after the last progress line
+    downloaded = [part.strip() for part in args.language.split("+") if part.strip()]
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "ok": True,
+                    "language": args.language,
+                    "downloaded": downloaded,
+                    "cache_dir": cache_dir,
+                }
+            )
+        )
+    else:
+        print(f"Downloaded {', '.join(downloaded)} into {cache_dir}")
+    return 0
+
+
+def cmd_eval(args) -> int:
+    from vera_cli.evaluate import evaluate
+
+    summary = evaluate(args.file, args.queries, mode=args.mode, top_k=args.top_k)
+    all_ok = all(report["hits"] == report["total"] for report in summary["reports"])
+    if args.json:
+        print(json.dumps(summary))
+        return 0 if all_ok else 1
+    print(f"File: {summary['file']}")
+    print(f"Queries: {summary['queries_file']}")
+    for report in summary["reports"]:
+        print()
+        print(f"Mode: {report['mode']}  (top_k={report['top_k']})")
+        for entry in report["queries"]:
+            status = f"HIT rank={entry['rank']}" if entry["hit"] else "MISS"
+            note = f"  # {entry['note']}" if entry["note"] else ""
+            print(f"  [{status:>10}] {entry['query']}{note}")
+        print(
+            f"  Hits: {report['hits']}/{report['total']} ({report['hit_rate']:.0%})  MRR: {report['mrr']:.3f}"
+        )
+    return 0 if all_ok else 1

vera_cli/evaluate.py

@@ -0,0 +1,149 @@
+"""Retrieval quality evaluation for VERA files.
+
+Runs a set of expected-answer queries against a VERA document and reports
+hit rate and mean reciprocal rank (MRR) so chunking/embedding/search changes
+can be compared objectively.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from vera_doc import QueryResult, VeraDocument
+
+MODES = ("semantic", "keyword", "hybrid")
+
+
+@dataclass
+class QueryCase:
+    query: str
+    expected_pages: list[int] = field(default_factory=list)
+    expected_terms: list[str] = field(default_factory=list)
+    note: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.query or not str(self.query).strip():
+            raise ValueError("Query case is missing 'query' text")
+        if not self.expected_pages and not self.expected_terms:
+            raise ValueError(
+                f"Query case {self.query!r} needs expected_pages and/or expected_terms"
+            )
+
+    def matches(self, result: QueryResult) -> bool:
+        if self.expected_pages:
+            citation = result.citation
+            pages = {p for p in (citation.page_start, citation.page_end) if isinstance(p, int)}
+            if isinstance(citation.page_start, int) and isinstance(citation.page_end, int):
+                pages.update(range(citation.page_start, citation.page_end + 1))
+            if not pages.intersection(self.expected_pages):
+                return False
+        if self.expected_terms:
+            text = result.record.text.lower()
+            if not all(term.lower() in text for term in self.expected_terms):
+                return False
+        return True
+
+
+def _normalize_case(raw: dict[str, Any]) -> QueryCase:
+    pages = raw.get("expected_pages") or []
+    if "expected_page" in raw and raw["expected_page"] is not None:
+        pages = list(pages) + [raw["expected_page"]]
+    return QueryCase(
+        query=str(raw.get("query", "")).strip(),
+        expected_pages=[int(p) for p in pages],
+        expected_terms=[str(t) for t in (raw.get("expected_terms") or [])],
+        note=str(raw.get("note", "")),
+    )
+
+
+def load_queries(path: str) -> list[QueryCase]:
+    """Load query cases from a JSON (or YAML, if pyyaml is installed) file."""
+    file = Path(path)
+    if not file.exists():
+        raise FileNotFoundError(path)
+    text = file.read_text(encoding="utf-8")
+    if file.suffix.lower() in {".yaml", ".yml"}:
+        try:
+            import yaml
+        except ImportError as exc:
+            raise RuntimeError(
+                "YAML query files require pyyaml: pip install pyyaml (or use a .json file)"
+            ) from exc
+        data = yaml.safe_load(text)
+    else:
+        data = json.loads(text)
+    if not isinstance(data, list) or not data:
+        raise ValueError("Query file must contain a non-empty list of query cases")
+    return [_normalize_case(item) for item in data]
+
+
+def evaluate_document(
+    doc: VeraDocument,
+    cases: list[QueryCase],
+    mode: str = "hybrid",
+    top_k: int = 5,
+) -> dict[str, Any]:
+    """Evaluate one search mode against all query cases."""
+    per_query = []
+    reciprocal_ranks = []
+    hits = 0
+    for case in cases:
+        results = doc.search(text=case.query, mode=mode, top_k=top_k)  # type: ignore[arg-type]
+        rank = None
+        for idx, result in enumerate(results, start=1):
+            if case.matches(result):
+                rank = idx
+                break
+        hit = rank is not None
+        hits += int(hit)
+        reciprocal_ranks.append(1.0 / rank if rank else 0.0)
+        per_query.append(
+            {
+                "query": case.query,
+                "note": case.note,
+                "hit": hit,
+                "rank": rank,
+                "top_score": results[0].score if results else None,
+                "top_page": (results[0].citation.page_start if results else None),
+            }
+        )
+    total = len(cases)
+    return {
+        "mode": mode,
+        "top_k": top_k,
+        "total": total,
+        "hits": hits,
+        "hit_rate": hits / total if total else 0.0,
+        "mrr": sum(reciprocal_ranks) / total if total else 0.0,
+        "queries": per_query,
+    }
+
+
+def evaluate(
+    vera_path: str,
+    queries_path: str,
+    mode: str = "hybrid",
+    top_k: int = 5,
+) -> dict[str, Any]:
+    """Evaluate a VERA file against a query file.
+
+    mode may be one of semantic/keyword/hybrid, or "all" to compare every mode.
+    """
+    cases = load_queries(queries_path)
+    modes = list(MODES) if mode == "all" else [mode]
+    for m in modes:
+        if m not in MODES:
+            raise ValueError(f"mode must be one of {', '.join(MODES)}, or 'all'")
+    doc = VeraDocument.open(vera_path)
+    try:
+        reports = [evaluate_document(doc, cases, mode=m, top_k=top_k) for m in modes]
+    finally:
+        doc.close()
+    return {
+        "file": vera_path,
+        "queries_file": queries_path,
+        "reports": reports,
+    }

vera_cli/main.py

@@ -0,0 +1,405 @@
+from __future__ import annotations
+
+import argparse
+
+from .commands import (
+    cmd_convert,
+    cmd_eval,
+    cmd_export,
+    cmd_figures,
+    cmd_get,
+    cmd_index_build,
+    cmd_index_status,
+    cmd_index_update,
+    cmd_inspect,
+    cmd_mcp,
+    cmd_ocr_languages_download,
+    cmd_ocr_languages_list,
+    cmd_search,
+    cmd_validate,
+    str_to_bool,
+)
+
+
+def non_negative_int(value: str) -> int:
+    parsed = int(value)
+    if parsed < 0:
+        raise argparse.ArgumentTypeError("must be non-negative")
+    return parsed
+
+
+def positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("must be positive")
+    return parsed
+
+
+def pipeline_option(value: str) -> tuple[str, str]:
+    """Parse ``KEY=VALUE`` pairs for ``--pipeline-option`` / ``--embedder-option``."""
+    if "=" not in value:
+        raise argparse.ArgumentTypeError("must be KEY=VALUE")
+    key, raw = value.split("=", 1)
+    key = key.strip()
+    if not key:
+        raise argparse.ArgumentTypeError("option key must be non-empty")
+    return key, raw
+
+
+embedder_option = pipeline_option
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the ``vera`` command-line argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="vera", description="Vector-Embedded Retrieval Archive CLI"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    convert_p = sub.add_parser(
+        "convert",
+        help="Convert a PDF, Markdown, Office/HTML (Docling extra), or a directory of sources to VERA files",
+    )
+    convert_p.add_argument(
+        "input",
+        help="PDF, Markdown, Office/HTML (with Docling), or directory containing supported source files",
+    )
+    convert_p.add_argument(
+        "output", nargs="?", default=None, help="Output .vera path for a single source file"
+    )
+    convert_p.add_argument(
+        "--model",
+        default="hashing",
+        help=(
+            "Embedding model spec: provider:model-id "
+            "(e.g. hashing, hashing:vera-hashing-384, "
+            "sentence-transformers:all-MiniLM-L6-v2, "
+            "openai:text-embedding-3-small). "
+            "Unknown providers exit with an error."
+        ),
+    )
+    convert_p.add_argument(
+        "--parser",
+        default=None,
+        help=(
+            "Ingest pipeline spec: provider[:variant] "
+            "(omitted: choose from the file extension; PDF -> pymupdf, "
+            "Markdown -> markdown, DOCX/PPTX/XLSX/HTML -> docling when "
+            "vera-ingest-docling is installed; optional docling or docling:hybrid). "
+            "Unknown providers exit with an error."
+        ),
+    )
+    convert_p.add_argument(
+        "--chunk-size",
+        type=int,
+        default=None,
+        help=(
+            "Compatibility alias for pipeline chunk_size (PyMuPDF: whitespace-split "
+            "words; Docling: whitespace tokens). Omitted uses the selected "
+            "pipeline's default."
+        ),
+    )
+    convert_p.add_argument(
+        "--overlap",
+        type=int,
+        default=None,
+        help=(
+            "Compatibility alias for pipeline overlap (PyMuPDF: whitespace-split "
+            "words; not forwarded to Docling). Omitted uses the selected "
+            "pipeline's default."
+        ),
+    )
+    convert_p.add_argument("--store-original", type=str_to_bool, default=True)
+    convert_p.add_argument(
+        "--ocr",
+        dest="ocr_mode",
+        choices=["auto", "off", "force"],
+        default=None,
+        help=(
+            "OCR mode: auto scans image-based pages, off disables OCR, force OCRs "
+            "every page. Compatibility alias; omitted uses the selected pipeline's default."
+        ),
+    )
+    convert_p.add_argument(
+        "--ocr-language",
+        default=None,
+        help=(
+            "Tesseract language code (PyMuPDF compatibility alias; not "
+            "forwarded to Docling/RapidOCR). Omitted uses the selected "
+            "pipeline's default."
+        ),
+    )
+    convert_p.add_argument(
+        "--ocr-dpi",
+        type=positive_int,
+        default=None,
+        help=(
+            "OCR render resolution (compatibility alias). Omitted uses the "
+            "selected pipeline's default."
+        ),
+    )
+    convert_p.add_argument(
+        "--ocr-allow-download",
+        action="store_true",
+        help=(
+            "Fetch missing --ocr-language Tesseract data from VERA's curated, "
+            "checksum-verified registry and cache it locally (PyMuPDF only; "
+            "compatibility alias). See 'vera ocr-languages list'."
+        ),
+    )
+    convert_p.add_argument(
+        "--pipeline-option",
+        dest="pipeline_options",
+        action="append",
+        type=pipeline_option,
+        default=[],
+        metavar="KEY=VALUE",
+        help=(
+            "Provider-owned ingest option (repeatable). Overrides compatibility "
+            "aliases for the same key when the selected pipeline accepts it."
+        ),
+    )
+    convert_p.add_argument(
+        "--embedder-option",
+        dest="embedder_options",
+        action="append",
+        type=embedder_option,
+        default=[],
+        metavar="KEY=VALUE",
+        help=(
+            "Provider-owned embedding option (repeatable). Forwarded to the "
+            "selected embedding provider (for example --embedder-option "
+            "batch_size=64 or --embedder-option dimension=256)."
+        ),
+    )
+    convert_p.add_argument(
+        "--metadata",
+        dest="metadata",
+        action="append",
+        type=pipeline_option,
+        default=[],
+        metavar="KEY=VALUE",
+        help=(
+            "Caller metadata stamped onto the archive and every chunk "
+            "(repeatable). Reserved ingest, citation, and format keys are rejected."
+        ),
+    )
+    convert_p.add_argument(
+        "--recursive",
+        action="store_true",
+        help="Discover supported source files recursively when input is a directory",
+    )
+    convert_p.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="Overwrite existing .vera files during directory conversion",
+    )
+    convert_p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    convert_p.set_defaults(func=cmd_convert)
+
+    inspect_p = sub.add_parser("inspect", help="Inspect a VERA file")
+    inspect_p.add_argument("file")
+    inspect_p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    inspect_p.set_defaults(func=cmd_inspect)
+
+    get_p = sub.add_parser("get", help="Fetch one chunk by id from a VERA file")
+    get_p.add_argument("file", help="Path to a .vera file")
+    get_p.add_argument("chunk_id", help="Exact chunk id (case-sensitive)")
+    get_p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    get_p.add_argument(
+        "--figures", action="store_true", help="Include figure metadata/captions in --json output"
+    )
+    get_p.add_argument(
+        "--regions",
+        action="store_true",
+        help="Include page/bbox highlight regions in --json output",
+    )
+    get_p.set_defaults(func=cmd_get)
+
+    search_p = sub.add_parser(
+        "search", help="Search a VERA file, or a directory of VERA files as one corpus"
+    )
+    search_p.add_argument("file", help="Path to a .vera file or a directory containing .vera files")
+    search_p.add_argument("query")
+    search_p.add_argument("--mode", choices=["semantic", "keyword", "hybrid"], default="hybrid")
+    search_p.add_argument("--top-k", type=non_negative_int, default=10)
+    search_p.add_argument(
+        "--context-chunks",
+        type=non_negative_int,
+        default=0,
+        help="Include N chunks before and after each search result in JSON output",
+    )
+    search_p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    search_p.add_argument(
+        "--figures", action="store_true", help="Include figure metadata/captions in --json output"
+    )
+    search_p.add_argument(
+        "--recursive",
+        action="store_true",
+        help="Search nested .vera files when the target is an unindexed directory",
+    )
+    search_p.add_argument(
+        "--exclude",
+        action="append",
+        default=None,
+        help="Exclude a relative path or name pattern (repeatable)",
+    )
+    search_p.add_argument(
+        "--include",
+        action="append",
+        default=None,
+        help="Include only relative paths matching this pattern (repeatable; directory search)",
+    )
+    search_p.add_argument(
+        "--where",
+        dest="where",
+        action="append",
+        type=pipeline_option,
+        default=[],
+        metavar="KEY=VALUE",
+        help=(
+            "Filter stored metadata before top_k (repeatable). Distinct keys are AND; "
+            "comma-separated values are IN."
+        ),
+    )
+    search_p.add_argument(
+        "--regions",
+        action="store_true",
+        help="Include page/bbox highlight regions for each result in --json output",
+    )
+    search_p.set_defaults(func=cmd_search)
+
+    index_p = sub.add_parser("index", help="Build and manage a local VERA library index")
+    index_sub = index_p.add_subparsers(dest="index_command", required=True)
+
+    index_build_p = index_sub.add_parser("build", help="Build a library index")
+    index_build_p.add_argument("directory", help="Root directory containing .vera files")
+    index_build_p.add_argument(
+        "--recursive", action="store_true", help="Discover .vera files recursively"
+    )
+    index_build_p.add_argument(
+        "--exclude",
+        action="append",
+        default=None,
+        help="Exclude a relative path or name pattern (repeatable)",
+    )
+    index_build_p.add_argument(
+        "--include",
+        action="append",
+        default=None,
+        help="Include only relative paths matching this pattern (repeatable)",
+    )
+    index_build_p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    index_build_p.set_defaults(func=cmd_index_build)
+
+    index_update_p = index_sub.add_parser("update", help="Update an existing library index")
+    index_update_p.add_argument("directory", help="Indexed library root")
+    index_update_p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    index_update_p.set_defaults(func=cmd_index_update)
+
+    index_status_p = index_sub.add_parser("status", help="Show library index freshness")
+    index_status_p.add_argument("directory", help="Indexed library root")
+    index_status_p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    index_status_p.set_defaults(func=cmd_index_status)
+
+    validate_p = sub.add_parser("validate", help="Validate a VERA file")
+    validate_p.add_argument("file")
+    validate_p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    validate_p.set_defaults(func=cmd_validate)
+
+    export_p = sub.add_parser("export", help="Export the original source document from a VERA file")
+    export_p.add_argument("file")
+    export_p.add_argument(
+        "output",
+        nargs="?",
+        default=None,
+        help="Output path or directory (default: stored filename)",
+    )
+    export_p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    export_p.set_defaults(func=cmd_export)
+
+    figures_p = sub.add_parser("figures", help="List or export figure attachments from a VERA file")
+    figures_p.add_argument("file", help="Path to a .vera file")
+    figures_p.add_argument(
+        "--out-dir",
+        default=None,
+        help="Write figure image files to this directory and include paths in JSON",
+    )
+    figures_p.add_argument(
+        "--asset-id",
+        action="append",
+        default=None,
+        help="Limit to one figure attachment id (repeatable)",
+    )
+    figures_p.add_argument(
+        "--page-start",
+        type=int,
+        default=None,
+        help="Include figures on or after this 1-based page number",
+    )
+    figures_p.add_argument(
+        "--page-end",
+        type=int,
+        default=None,
+        help="Include figures on or before this 1-based page number",
+    )
+    figures_p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    figures_p.set_defaults(func=cmd_figures)
+
+    mcp_p = sub.add_parser(
+        "mcp", help="Run the MCP server (stdio) exposing VERA tools to AI agents"
+    )
+    mcp_p.set_defaults(func=cmd_mcp)
+
+    ocr_languages_p = sub.add_parser(
+        "ocr-languages",
+        help="List or download Tesseract OCR language data used by the pymupdf parser",
+    )
+    ocr_languages_sub = ocr_languages_p.add_subparsers(dest="ocr_languages_command", required=True)
+
+    ocr_languages_list_p = ocr_languages_sub.add_parser(
+        "list", help="List bundled, cached, and downloadable OCR language codes"
+    )
+    ocr_languages_list_p.add_argument(
+        "language",
+        nargs="?",
+        default=None,
+        help="Limit to specific '+'-joined codes (e.g. eng+fra); defaults to every known code",
+    )
+    ocr_languages_list_p.add_argument(
+        "--json", action="store_true", help="Emit machine-readable JSON"
+    )
+    ocr_languages_list_p.set_defaults(func=cmd_ocr_languages_list)
+
+    ocr_languages_download_p = ocr_languages_sub.add_parser(
+        "download", help="Download one or more Tesseract language codes into the local cache"
+    )
+    ocr_languages_download_p.add_argument(
+        "language", help="'+'-joined Tesseract language code(s) to fetch, e.g. fra or fra+deu"
+    )
+    ocr_languages_download_p.add_argument(
+        "--json", action="store_true", help="Emit machine-readable JSON"
+    )
+    ocr_languages_download_p.set_defaults(func=cmd_ocr_languages_download)
+
+    eval_p = sub.add_parser("eval", help="Evaluate retrieval quality against a query file")
+    eval_p.add_argument("file")
+    eval_p.add_argument("queries", help="JSON or YAML file with query cases")
+    eval_p.add_argument("--mode", choices=["semantic", "keyword", "hybrid", "all"], default="all")
+    eval_p.add_argument("--top-k", type=non_negative_int, default=5)
+    eval_p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    eval_p.set_defaults(func=cmd_eval)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the ``vera`` CLI and return a process exit code.
+
+    Args:
+        argv: Optional argument list. Defaults to ``sys.argv[1:]``.
+
+    Returns:
+        Integer exit code (0 on success).
+    """
+    args = build_parser().parse_args(argv)
+    return args.func(args)