maskflow-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{maskflow_cli-0.6.0 → maskflow_cli-0.7.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: maskflow-cli
-Version: 0.6.0
+Version: 0.7.0
 Summary: Command-line interface for MaskFlow: .maskflowrc config validation and inspection
 License: MIT
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
-Requires-Dist: maskflow-core[yaml]<0.7,>=0.6.0
+Requires-Dist: maskflow-core[yaml]<0.8,>=0.6.0
 Requires-Dist: maskflow-pack-india<0.6,>=0.1.0
 Requires-Dist: maskflow-pack-intl<0.4,>=0.3.0
 Requires-Dist: rich>=13.0
@@ -13,6 +13,8 @@ Requires-Dist: tomli-w>=1.0
 Requires-Dist: typer>=0.12
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: evidence
+Requires-Dist: maskflow-evidence<0.2,>=0.1.0; extra == 'evidence'
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
 Provides-Extra: s3

{maskflow_cli-0.6.0 → maskflow_cli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "maskflow-cli"
-version = "0.6.0"
+version = "0.7.0"
 description = "Command-line interface for MaskFlow: .maskflowrc config validation and inspection"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -14,7 +14,7 @@ dependencies = [
     # -- pack-intl/pack-india now require it, so the floor moves with theirs
     # even though this package doesn't import maskflow_core.recognizer
     # directly.
-    "maskflow-core[yaml]>=0.6.0,<0.7",
+    "maskflow-core[yaml]>=0.6.0,<0.8",
     # maskflow_pack_intl is imported (side-effect only, to populate the
     # PIIType registry) for `maskflow config validate`'s soft entity-name
     # cross-check -- see app.py. pack-intl 0.1.0 itself requires core<0.3,
@@ -53,6 +53,14 @@ maskflow = "maskflow_cli.app:main"
 dev = [
     "pytest>=8.0",
 ]
+# `maskflow explain --evidence` / `--evidence-file`: metadata-only evidence
+# events (issue #41). Opt-in so a bare CLI install (and the standalone
+# PyInstaller binary) doesn't require it; `maskflow_cli.evidence` imports it
+# lazily and every other command runs without it. Base pull is the
+# stdlib-only sinks; [webhook]/[otlp] stay opt-in on maskflow-evidence.
+evidence = [
+    "maskflow-evidence>=0.1.0,<0.2",
+]
 # `maskflow scan s3://...` -- only pulled by an explicit
 # `pip install 'maskflow-cli[s3]'`, so boto3 (large) never taxes the common
 # jsonl/csv/dir scan or the rest of the CLI.
@@ -68,6 +76,7 @@ postgres = [
 maskflow-core = { workspace = true }
 maskflow-pack-intl = { workspace = true }
 maskflow-pack-india = { workspace = true }
+maskflow-evidence = { workspace = true }
 
 [tool.uv]
 package = true

{maskflow_cli-0.6.0 → maskflow_cli-0.7.0}/src/maskflow_cli/commands/explain_cmd.py

@@ -7,7 +7,8 @@ from pathlib import Path
 import typer
 from maskflow_core.config.resolve import ConfigResolutionError, resolve_config
 
-from ..explain import run_explain
+from ..evidence import EvidenceExtraMissing, emit_explain_evidence
+from ..explain import build_explain_result, detect_for_explain
 from ..explain_render import make_console, render_explain
 
 _CONFIG_OPTION = typer.Option(
@@ -19,6 +20,17 @@ _SET_OPTION = typer.Option(
 _FULL_OPTION = typer.Option(
     False, "--full", help="Show the entire matched value instead of truncating to 8 chars."
 )
+_EVIDENCE_OPTION = typer.Option(
+    None,
+    "--evidence/--no-evidence",
+    help="Emit metadata-only evidence events for this run (default: the "
+    "[evidence] section of your .maskflowrc). Never contains a detected value.",
+)
+_EVIDENCE_FILE_OPTION = typer.Option(
+    None,
+    "--evidence-file",
+    help="Write evidence events (one JSON object per line) to this file. Implies --evidence.",
+)
 
 
 def explain(
@@ -26,6 +38,8 @@ def explain(
     full: bool = _FULL_OPTION,
     config: Path | None = _CONFIG_OPTION,
     set_: list[str] = _SET_OPTION,
+    evidence: bool | None = _EVIDENCE_OPTION,
+    evidence_file: Path | None = _EVIDENCE_FILE_OPTION,
 ) -> None:
     """Show, span by span, why each piece of text was (or wasn't) detected
     as PII: the pattern/NER hit, checksum result, context boost, and the
@@ -39,5 +53,21 @@ def explain(
             typer.echo(line, err=True)
         raise typer.Exit(code=1) from exc
 
-    result = run_explain(text, resolved.config, full=full)
+    accepted, rejected = detect_for_explain(text, resolved.config)
+    result = build_explain_result(text, accepted, rejected, resolved.config, full=full)
     render_explain(make_console(), result)
+
+    enabled = resolved.config.evidence.enabled if evidence is None else evidence
+    try:
+        emitted = emit_explain_evidence(
+            accepted,
+            rejected,
+            resolved.config,
+            enabled=enabled,
+            evidence_file=evidence_file,
+        )
+    except EvidenceExtraMissing as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+    if emitted and evidence_file is not None:
+        typer.echo(f"\n{emitted} evidence event(s) written to {evidence_file}", err=True)

{maskflow_cli-0.6.0 → maskflow_cli-0.7.0}/src/maskflow_cli/doctor.py

@@ -127,6 +127,16 @@ def _check_config() -> tuple[ComponentCheck, ResolvedConfig | None]:
     return ComponentCheck(".maskflowrc", None, status, detail), resolved
 
 
+def _check_evidence(resolved: ResolvedConfig | None) -> ComponentCheck:
+    """Reports whether the metadata-only evidence layer is on, and to where.
+    Off by default -- an informational line, never an error."""
+    section = resolved.config.evidence if resolved is not None else None
+    if section is None or not section.enabled:
+        return ComponentCheck("evidence", None, "ok", "disabled (default) -- no events emitted")
+    where = section.path if section.sink == "file" else (section.url or section.sink)
+    return ComponentCheck("evidence", None, "ok", f"enabled -- sink: {section.sink} ({where})")
+
+
 def _check_redis() -> ComponentCheck:
     # RedisMappingStore (maskflow_core.mapping_store) is an interface-only
     # stub -- every method raises NotImplementedError regardless of whether
@@ -177,6 +187,7 @@ def run_checks() -> DoctorReport:
     config_check, resolved = _check_config()
     components.append(config_check)
 
+    components.append(_check_evidence(resolved))
     components.append(_check_redis())
 
     entities = _entity_checks(resolved, spacy_ready=model_check.status == "ok")

maskflow_cli-0.7.0/src/maskflow_cli/evidence.py

@@ -0,0 +1,83 @@
+"""`maskflow explain --evidence`: emit one metadata-only evidence event per
+detected (or near-miss) entity type for this run.
+
+Thin glue over ``maskflow_evidence``, which is an **optional** dependency
+(``pip install maskflow-cli[evidence]``) -- imported lazily so a bare CLI
+install without it still runs every other command.
+"""
+
+from __future__ import annotations
+
+import secrets
+from collections.abc import Sequence
+from pathlib import Path
+
+from maskflow_core.config.schema import RootConfig
+from maskflow_core.entities import Span
+
+_MISSING = (
+    "the --evidence / --evidence-file flags need the evidence extra -- "
+    "install it with:  pip install 'maskflow-cli[evidence]'"
+)
+
+
+class EvidenceExtraMissing(RuntimeError):
+    """Raised when --evidence is requested but maskflow-evidence isn't installed."""
+
+    def __init__(self) -> None:
+        super().__init__(_MISSING)
+
+
+def emit_explain_evidence(
+    accepted: Sequence[Span],
+    rejected: Sequence[Span],
+    root_config: RootConfig,
+    *,
+    enabled: bool,
+    evidence_file: Path | None,
+) -> int:
+    """Emit events for one `explain` run. Returns the count emitted.
+
+    ``enabled`` is the resolved on/off (``--evidence`` / ``[evidence]
+    enabled``); ``evidence_file`` forces a file sink at that path. Returns 0
+    without importing anything when evidence is off.
+    """
+    want = evidence_file is not None or enabled
+    if not want and not root_config.evidence.enabled:
+        return 0
+
+    try:
+        from dataclasses import replace
+
+        from maskflow_evidence import (
+            EventContext,
+            EvidenceConfig,
+            build_emitter,
+            events_from_spans,
+        )
+    except ModuleNotFoundError as exc:
+        if evidence_file is not None or enabled:
+            raise EvidenceExtraMissing() from exc
+        return 0  # [evidence] enabled in config but the extra isn't installed
+
+    config = EvidenceConfig.from_rootconfig(root_config)
+    if evidence_file is not None:
+        config = replace(config, enabled=True, sink="file", path=str(evidence_file))
+    elif enabled:
+        config = replace(config, enabled=True)
+    if not config.enabled:
+        return 0
+
+    ctx = EventContext(
+        session_id="cli_" + secrets.token_hex(8),
+        service=config.service,
+        environment=config.environment,
+    )
+    emitter = build_emitter(config)
+    try:
+        events = events_from_spans(accepted, ctx, dropped=rejected)
+        for event in events:
+            emitter.emit(event)
+        return len(events)
+    finally:
+        emitter.close()

{maskflow_cli-0.6.0 → maskflow_cli-0.7.0}/src/maskflow_cli/explain.py

@@ -70,16 +70,29 @@ def suggested_threshold(score: float) -> float:
     return math.floor(score * 20) / 20
 
 
-def run_explain(text: str, root_config: RootConfig, *, full: bool = False) -> ExplainResult:
+def detect_for_explain(text: str, root_config: RootConfig) -> tuple[list[Span], list[Span]]:
+    """The `(accepted, rejected)` span split `explain` is built on. Exposed
+    so the command can reuse the same spans for `--evidence` without a
+    second detect() pass."""
     compiled = compile_config(root_config)
-
     accepted, rejected = detect(
         text,
         min_confidence=DEFAULT_MIN_CONFIDENCE,
         return_rejected=True,
         **compiled.detect_kwargs(),
     )
+    return list(accepted), list(rejected)
 
+
+def build_explain_result(
+    text: str,
+    accepted: list[Span],
+    rejected: list[Span],
+    root_config: RootConfig,
+    *,
+    full: bool = False,
+) -> ExplainResult:
+    compiled = compile_config(root_config)
     masked = [_view(s, full=full, threshold=None) for s in accepted]
     near_misses = [
         _view(
@@ -90,3 +103,8 @@ def run_explain(text: str, root_config: RootConfig, *, full: bool = False) -> Ex
         for s in rejected
     ]
     return ExplainResult(text_length=len(text), masked=masked, near_misses=near_misses)
+
+
+def run_explain(text: str, root_config: RootConfig, *, full: bool = False) -> ExplainResult:
+    accepted, rejected = detect_for_explain(text, root_config)
+    return build_explain_result(text, accepted, rejected, root_config, full=full)

{maskflow_cli-0.6.0 → maskflow_cli-0.7.0}/tests/test_cli_explain.py

@@ -69,3 +69,44 @@ def test_explain_bad_config_exits_nonzero(fixtures_dir: Path) -> None:
     result = runner.invoke(app, ["explain", "--config", str(fixtures_dir / "typo.toml"), "hello"])
     assert result.exit_code == 1
     assert "did you mean 'threshold'?" in result.stderr
+
+
+# --- --evidence -------------------------------------------------------
+
+
+def test_explain_evidence_file_writes_metadata_only(tmp_path: Path) -> None:
+    import json
+
+    out = tmp_path / "evidence.log"
+    result = runner.invoke(
+        app,
+        ["explain", "--evidence-file", str(out), "Email me at john.doe@example.com please"],
+    )
+    assert result.exit_code == 0
+    lines = out.read_text().strip().splitlines()
+    assert lines
+    record = json.loads(lines[0])
+    assert record["entity_type"] == "EMAIL"
+    assert record["action"] == "masked"
+    assert record["recognizer"] == "pattern:EMAIL"
+    # the value itself never appears
+    assert "john.doe@example.com" not in out.read_text()
+
+
+def test_explain_no_evidence_by_default(tmp_path: Path) -> None:
+    # no --evidence, no [evidence] config -> nothing written anywhere
+    result = runner.invoke(app, ["explain", "Email me at john.doe@example.com please"])
+    assert result.exit_code == 0
+    assert not (tmp_path / "evidence.log").exists()
+
+
+def test_explain_evidence_reports_near_misses_as_passed(tmp_path: Path) -> None:
+    import json
+
+    out = tmp_path / "e.log"
+    text = "Random unrelated text with a number 123456789 in it, nothing special."
+    result = runner.invoke(app, ["explain", "--evidence-file", str(out), text])
+    assert result.exit_code == 0
+    actions = {json.loads(line)["action"] for line in out.read_text().strip().splitlines()}
+    assert "passed" in actions
+    assert "123456789" not in out.read_text()