outputguard 0.2.0__py3-none-any.whl

outputguard/__init__.py

@@ -0,0 +1,53 @@
+from outputguard.exceptions import (
+    OutputGuardError,
+    ParseError,
+    RepairError,
+    SchemaValidationError,
+    StrategyError,
+)
+from outputguard.guard import OutputGuard
+from outputguard.models import RepairResult, ValidationError, ValidationResult
+from outputguard.report import RepairReport, StrategyApplication
+
+_default_guard = OutputGuard()
+
+
+def validate(text: str, schema: dict) -> ValidationResult:
+    return _default_guard.validate(text, schema)
+
+
+def repair(text: str) -> RepairResult:
+    return _default_guard.repair(text)  # type: ignore[return-value]
+
+
+def validate_and_repair(text: str, schema: dict) -> ValidationResult:
+    return _default_guard.validate_and_repair(text, schema)
+
+
+def parse(text: str, schema: dict) -> dict | list:
+    """Validate, repair, and return parsed data. Raises on failure."""
+    return _default_guard.parse(text, schema)
+
+
+def retry_prompt(text: str, schema: dict, errors: list[ValidationError]) -> str:
+    return _default_guard.retry_prompt(text, schema, errors)
+
+
+__all__ = [
+    "OutputGuard",
+    "OutputGuardError",
+    "ParseError",
+    "RepairError",
+    "RepairReport",
+    "RepairResult",
+    "SchemaValidationError",
+    "StrategyApplication",
+    "StrategyError",
+    "ValidationError",
+    "ValidationResult",
+    "parse",
+    "repair",
+    "retry_prompt",
+    "validate",
+    "validate_and_repair",
+]

outputguard/cli.py

@@ -0,0 +1,227 @@
+"""OutputGuard CLI — validate, repair, and inspect LLM JSON output."""
+
+import dataclasses
+import json
+import sys
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+import outputguard
+from outputguard.guard import OutputGuard
+from outputguard.models import RepairResult, ValidationResult
+from outputguard.repairer import repair as _repair
+from outputguard.strategies import ALL_STRATEGIES, STRATEGY_DESCRIPTIONS
+
+console = Console(stderr=True)
+
+
+def _read_input(input_path: str) -> str:
+    with click.open_file(input_path, "r") as f:
+        return f.read()
+
+
+def _load_schema(schema_path: str) -> dict:
+    with open(schema_path) as f:
+        return json.load(f)
+
+
+def _print_validation_text(result: ValidationResult) -> None:
+    if result.valid:
+        if result.repaired:
+            console.print(
+                "[yellow]⚠ Repaired and valid[/yellow]  "
+                f"strategies: {', '.join(result.strategies_applied)}"
+            )
+        else:
+            console.print("[green]✓ Valid[/green]")
+    else:
+        console.print("[red]✗ Invalid[/red]")
+        for err in result.errors:
+            console.print(f"  [red]{err.path}[/red]: {err.message}")
+
+
+def _result_to_dict(obj: ValidationResult | RepairResult) -> dict:
+    return dataclasses.asdict(obj)
+
+
+def _write_output(text: str, output_path: str | None) -> None:
+    if output_path:
+        with open(output_path, "w") as f:
+            f.write(text)
+    else:
+        click.echo(text)
+
+
+@click.group()
+def cli() -> None:
+    """OutputGuard — validate and repair LLM JSON output."""
+
+
+@cli.command()
+@click.argument("input_path", metavar="INPUT")
+@click.option("-s", "--schema", "schema_path", required=True, help="Path to JSON Schema file.")
+@click.option(
+    "-r", "--repair", "do_repair", is_flag=True, help="Attempt repair if validation fails."
+)
+@click.option(
+    "-f",
+    "--format",
+    "fmt",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    help="Output format.",
+)
+@click.option("-q", "--quiet", is_flag=True, help="Exit code only, no output.")
+@click.option("-o", "--output", "output_path", default=None, help="Write result to file.")
+@click.option("-d", "--diff", "show_diff", is_flag=True, help="Show diff of repairs.")
+@click.option("-v", "--verbose", is_flag=True, help="Show each strategy's effect.")
+def validate(
+    input_path: str,
+    schema_path: str,
+    do_repair: bool,
+    fmt: str,
+    quiet: bool,
+    output_path: str | None,
+    show_diff: bool,
+    verbose: bool,
+) -> None:
+    """Validate INPUT (file or - for stdin) against a JSON schema."""
+    text = _read_input(input_path)
+    schema = _load_schema(schema_path)
+
+    if do_repair:
+        result = outputguard.validate_and_repair(text, schema)
+    else:
+        result = outputguard.validate(text, schema)
+
+    if not quiet:
+        if fmt == "json":
+            _write_output(json.dumps(_result_to_dict(result), indent=2), output_path)
+        else:
+            _print_validation_text(result)
+            if result.valid and result.repaired:
+                if show_diff or verbose:
+                    _show_repair_details(text, result, verbose)
+                if result.repaired_text:
+                    _write_output(result.repaired_text, output_path)
+
+    sys.exit(0 if result.valid else 1)
+
+
+def _show_repair_details(original: str, result: ValidationResult, verbose: bool) -> None:
+    """Show diff/verbose output for a repair."""
+    if not result.repaired:
+        return
+    _result, report = _repair(original, report=True)
+    if verbose:
+        step_diffs = report.step_diffs()
+        if step_diffs:
+            console.print("\n[bold]Strategy details:[/bold]")
+            console.print(step_diffs)
+        console.print(f"[dim]Confidence: {report.confidence:.0%}[/dim]")
+    else:
+        diff = report.diff
+        if diff:
+            console.print("\n[bold]Diff:[/bold]")
+            console.print(diff)
+
+
+@cli.command()
+@click.argument("input_path", metavar="INPUT")
+@click.option(
+    "-f",
+    "--format",
+    "fmt",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    help="Output format.",
+)
+@click.option("-o", "--output", "output_path", default=None, help="Write result to file.")
+@click.option("--strategies", default=None, help="Comma-separated strategy names.")
+@click.option("-d", "--diff", "show_diff", is_flag=True, help="Show diff of repairs.")
+@click.option("-v", "--verbose", is_flag=True, help="Show each strategy's effect.")
+def repair(
+    input_path: str,
+    fmt: str,
+    output_path: str | None,
+    strategies: str | None,
+    show_diff: bool,
+    verbose: bool,
+) -> None:
+    """Repair malformed JSON from INPUT (file or - for stdin)."""
+    text = _read_input(input_path)
+    strategy_list = [s.strip() for s in strategies.split(",")] if strategies else None
+
+    guard = OutputGuard(strategies=strategy_list)
+    need_report = show_diff or verbose
+    if need_report:
+        result, report = guard.repair(text, report=True)
+    else:
+        result = guard.repair(text)
+        report = None
+
+    if fmt == "json":
+        _write_output(json.dumps(_result_to_dict(result), indent=2), output_path)
+    else:
+        if result.repaired:
+            console.print(
+                f"[yellow]⚠ Repaired[/yellow]  strategies: {', '.join(result.strategies_applied)}"
+            )
+            if report and verbose:
+                step_diffs = report.step_diffs()
+                if step_diffs:
+                    console.print("\n[bold]Strategy details:[/bold]")
+                    console.print(step_diffs)
+                console.print(f"[dim]Confidence: {report.confidence:.0%}[/dim]")
+            elif report and show_diff:
+                diff = report.diff
+                if diff:
+                    console.print("\n[bold]Diff:[/bold]")
+                    console.print(diff)
+            _write_output(result.text, output_path)
+        elif result.parse_error:
+            console.print(f"[red]✗ Could not repair[/red]: {result.parse_error}")
+        else:
+            console.print("[green]✓ Already valid JSON[/green]")
+            _write_output(result.text, output_path)
+
+    sys.exit(0 if result.repaired or result.parse_error is None else 1)
+
+
+@cli.command("retry-prompt")
+@click.argument("input_path", metavar="INPUT")
+@click.option("-s", "--schema", "schema_path", required=True, help="Path to JSON Schema file.")
+def retry_prompt(input_path: str, schema_path: str) -> None:
+    """Generate a retry prompt for invalid JSON from INPUT."""
+    text = _read_input(input_path)
+    schema = _load_schema(schema_path)
+
+    result = outputguard.validate(text, schema)
+    prompt = outputguard.retry_prompt(text, schema, result.errors)
+    click.echo(prompt)
+    sys.exit(0)
+
+
+@cli.command()
+def strategies() -> None:
+    """List all available repair strategies."""
+    table = Table(title="Repair Strategies")
+    table.add_column("#", style="dim", width=4)
+    table.add_column("Name", style="cyan")
+    table.add_column("Description")
+
+    for i, (name, _fn) in enumerate(ALL_STRATEGIES, 1):
+        table.add_row(str(i), name, STRATEGY_DESCRIPTIONS.get(name, ""))
+
+    console.print(table)
+    sys.exit(0)
+
+
+@cli.command()
+def version() -> None:
+    """Show outputguard version."""
+    from importlib.metadata import version as pkg_version
+
+    click.echo(f"outputguard {pkg_version('outputguard')}")

outputguard/exceptions.py

@@ -0,0 +1,38 @@
+class OutputGuardError(Exception):
+    """Base exception for all outputguard errors."""
+
+
+class ParseError(OutputGuardError):
+    """JSON could not be parsed even after repair attempts."""
+
+    def __init__(self, message: str, original_text: str, parse_error: str | None = None):
+        self.original_text = original_text
+        self.parse_error = parse_error
+        super().__init__(message)
+
+
+class SchemaValidationError(OutputGuardError):
+    """JSON parsed but doesn't match the schema, even after repair."""
+
+    def __init__(self, message: str, data: dict | list, errors: list, schema: dict):
+        self.data = data
+        self.validation_errors = errors
+        self.schema = schema
+        super().__init__(message)
+
+
+class RepairError(OutputGuardError):
+    """Repair was attempted but failed."""
+
+    def __init__(self, message: str, strategies_tried: list[str], original_text: str):
+        self.strategies_tried = strategies_tried
+        self.original_text = original_text
+        super().__init__(message)
+
+
+class StrategyError(OutputGuardError):
+    """A specific repair strategy encountered an error."""
+
+    def __init__(self, message: str, strategy_name: str):
+        self.strategy_name = strategy_name
+        super().__init__(message)

outputguard/guard.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import Literal, overload
+
+from outputguard import repairer as _repairer
+from outputguard import retry as _retry
+from outputguard import validator as _validator
+from outputguard.exceptions import ParseError, SchemaValidationError
+from outputguard.models import RepairResult, ValidationError, ValidationResult
+from outputguard.report import RepairReport
+
+
+class OutputGuard:
+    def __init__(
+        self,
+        strategies: list[str] | None = None,
+        max_repair_attempts: int = 3,
+    ):
+        self.strategies = strategies
+        self.max_repair_attempts = max_repair_attempts
+
+    def validate(self, text: str, schema: dict) -> ValidationResult:
+        return _validator.validate(text, schema)
+
+    @overload
+    def repair(self, text: str) -> RepairResult: ...
+
+    @overload
+    def repair(self, text: str, *, report: Literal[True]) -> tuple[RepairResult, RepairReport]: ...
+
+    def repair(
+        self, text: str, *, report: bool = False
+    ) -> RepairResult | tuple[RepairResult, RepairReport]:
+        if report:
+            return _repairer.repair(text, self.strategies, report=True)
+        return _repairer.repair(text, self.strategies)
+
+    def validate_and_repair(self, text: str, schema: dict) -> ValidationResult:
+        """Validate, and if invalid, attempt repair then re-validate."""
+        result = self.validate(text, schema)
+        if result.valid:
+            return result
+
+        current_text = text
+        for _attempt in range(self.max_repair_attempts):
+            repair_result = _repairer.repair(current_text, self.strategies)
+            if not repair_result.repaired:
+                continue
+
+            revalidation = self.validate(repair_result.text, schema)
+            if revalidation.valid:
+                revalidation.repaired = True
+                revalidation.strategies_applied = repair_result.strategies_applied
+                revalidation.original_text = text
+                revalidation.repaired_text = repair_result.text
+                return revalidation
+            current_text = repair_result.text
+
+        result.original_text = text
+        return result
+
+    def parse(self, text: str, schema: dict) -> dict | list:
+        """Validate, repair, and return parsed data. Raises on failure.
+
+        This is the simplest API: give it text and a schema, get back
+        parsed data or an exception.
+
+        Raises:
+            ParseError: If the text cannot be parsed as JSON even after repair.
+            SchemaValidationError: If the parsed JSON doesn't match the schema.
+        """
+        result = self.validate_and_repair(text, schema)
+        if result.valid:
+            assert result.data is not None
+            return result.data
+
+        if result.data is None:
+            raise ParseError(
+                "Could not parse JSON from LLM output",
+                original_text=text,
+                parse_error=result.errors[0].message if result.errors else None,
+            )
+        raise SchemaValidationError(
+            f"JSON does not match schema: {len(result.errors)} error(s)",
+            data=result.data,
+            errors=result.errors,
+            schema=schema,
+        )
+
+    def retry_prompt(self, text: str, schema: dict, errors: list[ValidationError]) -> str:
+        return _retry.retry_prompt(text, schema, errors)

outputguard/models.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ValidationError:
+    message: str
+    path: str  # JSON path, e.g. "$.items[0].name"
+    schema_path: str  # Schema path that was violated
+    value: Any = None
+
+
+@dataclass
+class ValidationResult:
+    valid: bool
+    data: dict | list | None = None
+    errors: list[ValidationError] = field(default_factory=list)
+    repaired: bool = False
+    strategies_applied: list[str] = field(default_factory=list)
+    original_text: str = ""
+    repaired_text: str = ""
+
+
+@dataclass
+class RepairResult:
+    repaired: bool
+    text: str
+    strategies_applied: list[str] = field(default_factory=list)
+    parse_error: str | None = None

outputguard/repairer.py

@@ -0,0 +1,102 @@
+"""JSON repair engine — applies strategies in sequence to fix malformed JSON."""
+
+from __future__ import annotations
+
+import json
+from typing import Literal, overload
+
+from outputguard.models import RepairResult
+from outputguard.report import RepairReport, StrategyApplication
+from outputguard.strategies import get_strategies
+
+
+@overload
+def repair(text: str, strategies: list[str] | None = ...) -> RepairResult: ...
+
+
+@overload
+def repair(
+    text: str, strategies: list[str] | None = ..., *, report: Literal[True]
+) -> tuple[RepairResult, RepairReport]: ...
+
+
+def repair(
+    text: str, strategies: list[str] | None = None, *, report: bool = False
+) -> RepairResult | tuple[RepairResult, RepairReport]:
+    """Apply repair strategies in order, try to parse after each one.
+
+    If report=True, returns a (RepairResult, RepairReport) tuple.
+    """
+    try:
+        json.loads(text)
+        result = RepairResult(repaired=False, text=text)
+        if report:
+            return result, RepairReport(original_text=text, final_text=text, success=True)
+        return result
+    except json.JSONDecodeError:
+        pass
+
+    strategy_list = get_strategies(strategies)
+    last_error: str = ""
+    steps: list[StrategyApplication] = []
+
+    # First pass: apply ALL strategies in sequence, then try parsing
+    current = text
+    applied: list[str] = []
+    for name, fn in strategy_list:
+        before = current
+        try:
+            current = fn(current)
+        except Exception:
+            current = before
+        changed = current != before
+        steps.append(
+            StrategyApplication(name=name, changed=changed, input_text=before, output_text=current)
+        )
+        if changed:
+            applied.append(name)
+
+    try:
+        json.loads(current)
+        result = RepairResult(repaired=True, text=current, strategies_applied=applied)
+        if report:
+            return result, RepairReport(
+                original_text=text, final_text=current, success=True, steps=steps
+            )
+        return result
+    except json.JSONDecodeError as e:
+        last_error = str(e)
+
+    # Second pass: apply one at a time with parse attempts between each
+    current = text
+    applied = []
+    steps = []
+    for name, fn in strategy_list:
+        before = current
+        try:
+            current = fn(current)
+        except Exception:
+            current = before
+        changed = current != before
+        steps.append(
+            StrategyApplication(name=name, changed=changed, input_text=before, output_text=current)
+        )
+        if changed:
+            applied.append(name)
+        try:
+            json.loads(current)
+            result = RepairResult(repaired=True, text=current, strategies_applied=applied)
+            if report:
+                return result, RepairReport(
+                    original_text=text, final_text=current, success=True, steps=steps
+                )
+            return result
+        except json.JSONDecodeError as e:
+            last_error = str(e)
+
+    result = RepairResult(repaired=False, text=text, parse_error=last_error)
+    if report:
+        return result, RepairReport(
+            original_text=text, final_text=text, success=False, steps=steps, parse_error=last_error
+        )
+    return result

outputguard/report.py

@@ -0,0 +1,110 @@
+from dataclasses import dataclass, field
+from difflib import unified_diff
+
+
+@dataclass
+class StrategyApplication:
+    """Record of a single strategy being applied."""
+
+    name: str
+    changed: bool
+    input_text: str
+    output_text: str
+
+    @property
+    def diff(self) -> str:
+        """Unified diff of this strategy's changes."""
+        if not self.changed:
+            return ""
+        return "\n".join(
+            unified_diff(
+                self.input_text.splitlines(keepends=True),
+                self.output_text.splitlines(keepends=True),
+                fromfile=f"before_{self.name}",
+                tofile=f"after_{self.name}",
+                lineterm="",
+            )
+        )
+
+
+@dataclass
+class RepairReport:
+    """Detailed report of a repair operation."""
+
+    original_text: str
+    final_text: str
+    success: bool
+    steps: list[StrategyApplication] = field(default_factory=list)
+    parse_error: str | None = None
+
+    @property
+    def strategies_applied(self) -> list[str]:
+        """Names of strategies that actually changed the text."""
+        return [s.name for s in self.steps if s.changed]
+
+    @property
+    def strategies_tried(self) -> list[str]:
+        """Names of all strategies that were tried."""
+        return [s.name for s in self.steps]
+
+    @property
+    def diff(self) -> str:
+        """Unified diff from original to final text."""
+        if self.original_text == self.final_text:
+            return ""
+        return "\n".join(
+            unified_diff(
+                self.original_text.splitlines(keepends=True),
+                self.final_text.splitlines(keepends=True),
+                fromfile="original",
+                tofile="repaired",
+                lineterm="",
+            )
+        )
+
+    @property
+    def confidence(self) -> float:
+        """Heuristic confidence score (0.0 to 1.0) for the repair.
+
+        Higher when fewer strategies were needed and the change was minimal.
+        """
+        if not self.success:
+            return 0.0
+
+        len(self.steps)
+        applied_count = len(self.strategies_applied)
+
+        if applied_count == 0:
+            return 1.0  # No repair needed, already valid
+
+        # Start at 1.0, reduce by:
+        # - Number of strategies needed (more = less confident)
+        # - Ratio of text changed (more change = less confident)
+        strategy_penalty = min(applied_count * 0.1, 0.5)
+
+        orig_len = max(len(self.original_text), 1)
+        final_len = max(len(self.final_text), 1)
+        change_ratio = abs(orig_len - final_len) / max(orig_len, final_len)
+        change_penalty = min(change_ratio * 0.5, 0.3)
+
+        return max(round(1.0 - strategy_penalty - change_penalty, 2), 0.1)
+
+    @property
+    def summary(self) -> str:
+        """One-line summary of the repair."""
+        if not self.success:
+            return f"Repair failed after trying {len(self.steps)} strategies"
+        applied = self.strategies_applied
+        if not applied:
+            return "No repair needed — JSON was already valid"
+        return f"Repaired using {len(applied)} strategy(ies): {', '.join(applied)}"
+
+    def step_diffs(self) -> str:
+        """Show diff for each strategy that made changes, useful for --verbose."""
+        parts = []
+        for step in self.steps:
+            if step.changed:
+                parts.append(f"=== {step.name} ===")
+                parts.append(step.diff)
+                parts.append("")
+        return "\n".join(parts)