contractguardian 0.1.0__py3-none-any.whl

contractguard/__init__.py

@@ -0,0 +1,3 @@
+"""contractguard - AI agent that reads the fine print so you don't have to."""
+
+__version__ = "0.1.0"

contractguard/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running contractguard as a module: python -m contractguard"""
+
+from contractguard.cli import main
+
+main()

contractguard/analyzer.py

@@ -0,0 +1,97 @@
+"""Core contract analysis engine powered by LLM."""
+
+from __future__ import annotations
+
+import json
+import os
+
+from openai import OpenAI
+from pydantic import ValidationError
+
+from contractguard.models import AnalysisResult
+from contractguard.prompts import get_prompts
+
+DEFAULT_MODEL = "anthropic/claude-sonnet-4"
+MAX_CONTRACT_CHARS = 120_000  # ~30K tokens
+
+
+def get_client(
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> OpenAI:
+    """Create an OpenAI-compatible client."""
+    api_key = api_key or os.environ.get("OPENAI_API_KEY") or os.environ.get("OPENROUTER_API_KEY")
+    base_url = base_url or os.environ.get("OPENAI_BASE_URL") or os.environ.get(
+        "OPENROUTER_BASE_URL", "https://openrouter.ai/api/v1"
+    )
+
+    if not api_key:
+        raise ValueError(
+            "No API key found. Set one of:\n"
+            "  export OPENROUTER_API_KEY=sk-or-...\n"
+            "  export OPENAI_API_KEY=sk-...\n"
+            "Or pass --api-key to the CLI."
+        )
+
+    return OpenAI(api_key=api_key, base_url=base_url)
+
+
+def analyze_contract(
+    contract_text: str,
+    model: str = DEFAULT_MODEL,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    lang: str = "en",
+) -> AnalysisResult:
+    """Analyze a contract and return structured results.
+
+    Args:
+        contract_text: The full text of the contract.
+        model: The LLM model to use (OpenRouter model ID).
+        api_key: API key for the LLM provider.
+        base_url: Base URL for the LLM API.
+
+    Returns:
+        AnalysisResult with red flags, warnings, and fairness score.
+    """
+    if len(contract_text.strip()) < 50:
+        raise ValueError("Contract text is too short. Please provide a complete document.")
+
+    # Truncate if too long
+    if len(contract_text) > MAX_CONTRACT_CHARS:
+        contract_text = contract_text[:MAX_CONTRACT_CHARS] + "\n\n[... document truncated ...]"
+
+    client = get_client(api_key=api_key, base_url=base_url)
+    system_prompt, analysis_prompt = get_prompts(lang)
+
+    response = client.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": analysis_prompt.format(contract_text=contract_text)},
+        ],
+        temperature=0.1,
+        max_tokens=4096,
+    )
+
+    content = response.choices[0].message.content.strip()
+
+    # Strip markdown code block if present
+    if content.startswith("```"):
+        lines = content.split("\n")
+        # Remove first and last lines (```json and ```)
+        lines = [line for line in lines if not line.strip().startswith("```")]
+        content = "\n".join(lines)
+
+    try:
+        data = json.loads(content)
+    except json.JSONDecodeError as e:
+        raise RuntimeError(
+            f"Failed to parse LLM response as JSON: {e}\n"
+            f"Raw response:\n{content[:500]}"
+        )
+
+    try:
+        return AnalysisResult(**data)
+    except ValidationError as e:
+        raise RuntimeError(f"LLM response did not match expected schema: {e}")

contractguard/batch.py

@@ -0,0 +1,100 @@
+"""Batch scanning: analyze several contracts in one run and aggregate the results."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from contractguard.models import AnalysisResult
+
+# The document types parser.extract_text knows how to read.
+SUPPORTED_EXTENSIONS: frozenset[str] = frozenset({".pdf", ".docx", ".txt", ".md", ".rtf"})
+
+
+@dataclass
+class BatchItem:
+    """One contract's place in a batch run: its result, or the error that stopped it."""
+
+    path: str
+    result: AnalysisResult | None = None
+    error: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None and self.result is not None
+
+
+@dataclass
+class BatchSummary:
+    """Aggregate view across a batch run."""
+
+    total: int
+    succeeded: int
+    failed: int
+    total_red_flags: int
+    total_warnings: int
+    grades: dict[str, int] = field(default_factory=dict)  # fairness grade -> count
+
+
+def discover_contracts(path: str | Path) -> list[Path]:
+    """Find the contract files to scan.
+
+    A directory is searched recursively for files whose extension is supported;
+    a single file path is returned as-is (so an explicit, oddly-named file is
+    still honoured). Results are sorted for deterministic ordering.
+    """
+    p = Path(path)
+    if p.is_dir():
+        return sorted(
+            f for f in p.rglob("*") if f.is_file() and f.suffix.lower() in SUPPORTED_EXTENSIONS
+        )
+    return [p]
+
+
+def analyze_paths(
+    paths: Iterable[Path],
+    analyze_fn: Callable[[Path], AnalysisResult],
+    on_result: Callable[[BatchItem], None] | None = None,
+) -> list[BatchItem]:
+    """Run ``analyze_fn`` on each path, isolating per-file failures.
+
+    A failure on one contract (unreadable file, API error, ...) is captured on
+    that ``BatchItem`` and does not abort the rest of the batch — the whole point
+    of batch scanning is that one bad file doesn't sink the run. ``on_result`` is
+    an optional callback invoked after each item, e.g. to print progress.
+    """
+    items: list[BatchItem] = []
+    for path in paths:
+        try:
+            item = BatchItem(path=str(path), result=analyze_fn(path))
+        except Exception as exc:  # noqa: BLE001 - per-file isolation is intentional
+            item = BatchItem(path=str(path), error=str(exc))
+        items.append(item)
+        if on_result is not None:
+            on_result(item)
+    return items
+
+
+def summarize_batch(items: list[BatchItem]) -> BatchSummary:
+    """Aggregate stats (counts, fairness grades, total issues) across a batch run."""
+    grades: dict[str, int] = {}
+    total_red_flags = 0
+    total_warnings = 0
+    succeeded = 0
+    for item in items:
+        if not item.ok or item.result is None:
+            continue
+        succeeded += 1
+        grade = item.result.fairness_grade
+        grades[grade] = grades.get(grade, 0) + 1
+        total_red_flags += len(item.result.red_flags)
+        total_warnings += len(item.result.warnings)
+    return BatchSummary(
+        total=len(items),
+        succeeded=succeeded,
+        failed=len(items) - succeeded,
+        total_red_flags=total_red_flags,
+        total_warnings=total_warnings,
+        grades=grades,
+    )

contractguard/cli.py

@@ -0,0 +1,210 @@
+"""Command-line interface for contractguard."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from contractguard import __version__
+
+console = Console()
+
+
+@click.group()
+@click.version_option(__version__, prog_name="contractguard")
+def main():
+    """AI agent that reads the fine print so you don't have to.
+
+    Upload any contract and get instant analysis of red flags,
+    unfair terms, and missing protections.
+    """
+    pass
+
+
+@main.command()
+@click.argument("file", type=click.Path(exists=True))
+@click.option("--model", "-m", default=None, help="LLM model to use (default: anthropic/claude-sonnet-4)")
+@click.option("--api-key", "-k", envvar="OPENROUTER_API_KEY", help="API key (or set OPENROUTER_API_KEY)")
+@click.option("--base-url", "-u", envvar="OPENROUTER_BASE_URL", help="API base URL")
+@click.option("--output", "-o", type=click.Path(), help="Save report to file. Uses JSON when --json is set.")
+@click.option("--json", "json_output", is_flag=True, help="Output raw JSON instead of formatted report")
+@click.option("--lang", "-l", type=click.Choice(["en", "zh"]), default="en", help="Analysis language (en or zh)")
+def scan(file: str, model: str | None, api_key: str | None, base_url: str | None,
+         output: str | None, json_output: bool, lang: str):
+    """Scan a contract for red flags and unfair terms.
+
+    Supports PDF, DOCX, and TXT files.
+
+    \b
+    Examples:
+        contractguard scan lease.pdf
+        contractguard scan contract.docx --model openai/gpt-4o
+        contractguard scan nda.txt -o report.md
+    """
+    from contractguard.analyzer import DEFAULT_MODEL, analyze_contract
+    from contractguard.parser import extract_text
+    from contractguard.report import print_report
+
+    model = model or DEFAULT_MODEL
+
+    # Step 1: Parse document
+    with console.status("[bold blue]Parsing document...[/bold blue]"):
+        try:
+            text = extract_text(file)
+        except Exception as e:
+            console.print(f"[bold red]Error:[/bold red] {e}")
+            sys.exit(1)
+
+    console.print(f"[green]\u2714[/green] Parsed {Path(file).name} ({len(text):,} characters)")
+
+    # Step 2: Analyze with LLM
+    with console.status(f"[bold blue]Analyzing contract with {model}...[/bold blue]"):
+        try:
+            result = analyze_contract(
+                contract_text=text,
+                model=model,
+                api_key=api_key,
+                base_url=base_url,
+                lang=lang,
+            )
+        except Exception as e:
+            console.print(f"[bold red]Error:[/bold red] {e}")
+            sys.exit(1)
+
+    # Step 3: Output results
+    if json_output:
+        console.print(result.model_dump_json(indent=2))
+    else:
+        print_report(result)
+
+    # Step 4: Save report if requested
+    if output:
+        _write_report(result, output, json_output=json_output)
+        console.print(f"\n[green]\u2714[/green] Report saved to {output}")
+
+
+@main.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--model", "-m", default=None, help="LLM model to use (default: anthropic/claude-sonnet-4)")
+@click.option("--api-key", "-k", envvar="OPENROUTER_API_KEY", help="API key (or set OPENROUTER_API_KEY)")
+@click.option("--base-url", "-u", envvar="OPENROUTER_BASE_URL", help="API base URL")
+@click.option("--lang", "-l", type=click.Choice(["en", "zh"]), default="en", help="Analysis language (en or zh)")
+@click.option("--output-dir", "-o", type=click.Path(), help="Save a markdown report per contract into this directory.")
+def batch(path: str, model: str | None, api_key: str | None, base_url: str | None,
+          lang: str, output_dir: str | None):
+    """Scan multiple contracts at once: a folder (searched recursively) or a single file.
+
+    \b
+    Examples:
+        contractguard batch ./contracts/
+        contractguard batch ./contracts/ -o reports/
+    """
+    from contractguard.analyzer import DEFAULT_MODEL, analyze_contract
+    from contractguard.batch import BatchItem, analyze_paths, discover_contracts
+    from contractguard.parser import extract_text
+    from contractguard.report import generate_markdown_report, print_batch_summary
+
+    model = model or DEFAULT_MODEL
+    paths = discover_contracts(path)
+    if not paths:
+        console.print("[yellow]No supported contract files found.[/yellow]")
+        return
+
+    console.print(f"[bold blue]Scanning {len(paths)} contract(s)...[/bold blue]")
+
+    def _analyze(p: Path) -> object:
+        return analyze_contract(
+            contract_text=extract_text(p),
+            model=model,
+            api_key=api_key,
+            base_url=base_url,
+            lang=lang,
+        )
+
+    def _progress(item: BatchItem) -> None:
+        name = Path(item.path).name
+        if item.ok:
+            console.print(f"[green]✔[/green] {name}")
+        else:
+            console.print(f"[red]✘[/red] {name}: {item.error}")
+
+    items = analyze_paths(paths, _analyze, on_result=_progress)
+    print_batch_summary(items)
+
+    if output_dir:
+        out = Path(output_dir)
+        out.mkdir(parents=True, exist_ok=True)
+        for item in items:
+            if item.result is None:
+                continue
+            (out / (Path(item.path).stem + ".md")).write_text(
+                generate_markdown_report(item.result), encoding="utf-8"
+            )
+        console.print(f"\n[green]✔[/green] Reports saved to {output_dir}")
+
+
+@main.command()
+@click.argument("before", type=click.Path(exists=True))
+@click.argument("after", type=click.Path(exists=True))
+@click.option("--model", "-m", default=None, help="LLM model to use (default: anthropic/claude-sonnet-4)")
+@click.option("--api-key", "-k", envvar="OPENROUTER_API_KEY", help="API key (or set OPENROUTER_API_KEY)")
+@click.option("--base-url", "-u", envvar="OPENROUTER_BASE_URL", help="API base URL")
+@click.option("--lang", "-l", type=click.Choice(["en", "zh"]), default="en", help="Analysis language (en or zh)")
+def compare(before: str, after: str, model: str | None, api_key: str | None,
+            base_url: str | None, lang: str):
+    """Compare two versions of a contract and show what changed.
+
+    \b
+    Examples:
+        contractguard compare lease-v1.pdf lease-v2.pdf
+    """
+    from contractguard.analyzer import DEFAULT_MODEL, analyze_contract
+    from contractguard.compare import compare_results
+    from contractguard.parser import extract_text
+    from contractguard.report import print_comparison
+
+    model = model or DEFAULT_MODEL
+
+    def _analyze(path: str, label: str) -> object:
+        with console.status(f"[bold blue]Analyzing {label}...[/bold blue]"):
+            try:
+                return analyze_contract(
+                    contract_text=extract_text(path),
+                    model=model,
+                    api_key=api_key,
+                    base_url=base_url,
+                    lang=lang,
+                )
+            except Exception as e:
+                console.print(f"[bold red]Error analyzing {label}:[/bold red] {e}")
+                sys.exit(1)
+
+    before_result = _analyze(before, Path(before).name)
+    after_result = _analyze(after, Path(after).name)
+    print_comparison(compare_results(before_result, after_result))
+
+
+@main.command()
+def web():
+    """Launch the web UI (requires: pip install contractguard[web])."""
+    try:
+        from contractguard.web import main as launch
+    except ImportError:
+        console.print("[red]Gradio not installed.[/red] Run: pip install contractguard[web]")
+        return
+    launch()
+
+
+def _write_report(result, output: str, json_output: bool = False) -> None:
+    from contractguard.report import generate_markdown_report
+
+    if json_output:
+        content = result.model_dump_json(indent=2) + "\n"
+    else:
+        content = generate_markdown_report(result)
+    output_path = Path(output)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(content, encoding="utf-8")

contractguard/compare.py

@@ -0,0 +1,56 @@
+"""Contract comparison: diff two analyzed versions of the same contract."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from contractguard.models import AnalysisResult, Issue
+
+
+@dataclass
+class ContractComparison:
+    """What changed between an earlier and a later version of a contract."""
+
+    score_before: int
+    score_after: int
+    grade_before: str
+    grade_after: str
+    added_red_flags: list[Issue] = field(default_factory=list)
+    resolved_red_flags: list[Issue] = field(default_factory=list)
+    added_warnings: list[Issue] = field(default_factory=list)
+    resolved_warnings: list[Issue] = field(default_factory=list)
+
+    @property
+    def score_delta(self) -> int:
+        """Positive when the later version is fairer."""
+        return self.score_after - self.score_before
+
+
+def _diff_by_title(before: list[Issue], after: list[Issue]) -> tuple[list[Issue], list[Issue]]:
+    """Match issues by title and return ``(added, resolved)``.
+
+    Added = present in *after* but not *before*; resolved = present in *before*
+    but not *after*. Issues carried over unchanged appear in neither list.
+    """
+    before_titles = {issue.title for issue in before}
+    after_titles = {issue.title for issue in after}
+    added = [issue for issue in after if issue.title not in before_titles]
+    resolved = [issue for issue in before if issue.title not in after_titles]
+    return added, resolved
+
+
+def compare_results(before: AnalysisResult, after: AnalysisResult) -> ContractComparison:
+    """Diff two analysis results: which issues were added or resolved, and how the
+    fairness score moved between the two versions."""
+    added_red, resolved_red = _diff_by_title(before.red_flags, after.red_flags)
+    added_warn, resolved_warn = _diff_by_title(before.warnings, after.warnings)
+    return ContractComparison(
+        score_before=before.fairness_score,
+        score_after=after.fairness_score,
+        grade_before=before.fairness_grade,
+        grade_after=after.fairness_grade,
+        added_red_flags=added_red,
+        resolved_red_flags=resolved_red,
+        added_warnings=added_warn,
+        resolved_warnings=resolved_warn,
+    )

contractguard/models.py

@@ -0,0 +1,70 @@
+"""Data models for contract analysis results."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class Severity(str, Enum):
+    """Severity level of an identified issue."""
+
+    RED = "red"
+    YELLOW = "yellow"
+    GREEN = "green"
+
+
+class ContractType(str, Enum):
+    """Supported contract types."""
+
+    LEASE = "lease"
+    NDA = "nda"
+    EMPLOYMENT = "employment"
+    FREELANCE = "freelance"
+    SaaS = "saas_tos"
+    LOAN = "loan"
+    PURCHASE = "purchase"
+    UNKNOWN = "unknown"
+
+
+class Issue(BaseModel):
+    """A single identified issue in the contract."""
+
+    title: str = Field(description="Short title of the issue")
+    severity: Severity = Field(description="Severity: red (danger), yellow (warning), green (ok)")
+    clause: str = Field(description="The relevant clause or section reference")
+    quote: str = Field(description="Direct quote from the contract")
+    explanation: str = Field(description="Plain-language explanation of the issue")
+    suggestion: str = Field(description="Suggested modification or action")
+
+
+class Protection(BaseModel):
+    """A positive protection found in the contract."""
+
+    title: str = Field(description="What is protected")
+    clause: str = Field(description="The relevant clause or section")
+    explanation: str = Field(description="Why this protection matters")
+
+
+class AnalysisResult(BaseModel):
+    """Complete analysis result for a contract."""
+
+    contract_type: ContractType = Field(description="Detected type of contract")
+    summary: str = Field(description="2-3 sentence plain-language summary of the contract")
+    parties: list[str] = Field(default_factory=list, description="Parties involved")
+    key_terms: list[str] = Field(
+        default_factory=list, description="Key terms (duration, payment, etc.)"
+    )
+    red_flags: list[Issue] = Field(default_factory=list, description="Serious issues found")
+    warnings: list[Issue] = Field(default_factory=list, description="Moderate concerns")
+    good_clauses: list[Protection] = Field(
+        default_factory=list, description="Positive protections found"
+    )
+    missing_protections: list[str] = Field(
+        default_factory=list, description="Important protections not found in the contract"
+    )
+    fairness_score: int = Field(
+        ge=0, le=100, description="Overall fairness score from 0 (terrible) to 100 (excellent)"
+    )
+    fairness_grade: str = Field(description="Letter grade: A+, A, B+, B, C+, C, D, F")

contractguard/parser.py

@@ -0,0 +1,65 @@
+"""Document parsing: extract text from PDF, DOCX, TXT, and image files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def extract_text(file_path: str | Path) -> str:
+    """Extract text content from a document file.
+
+    Supports: .pdf, .docx, .txt, .md, .rtf
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    suffix = path.suffix.lower()
+
+    if suffix == ".pdf":
+        return _extract_pdf(path)
+    elif suffix == ".docx":
+        return _extract_docx(path)
+    elif suffix in (".txt", ".md", ".rtf"):
+        return path.read_text(encoding="utf-8", errors="replace")
+    else:
+        raise ValueError(
+            f"Unsupported file type: {suffix}. "
+            f"Supported: .pdf, .docx, .txt, .md, .rtf"
+        )
+
+
+def _extract_pdf(path: Path) -> str:
+    """Extract text from a PDF file."""
+    try:
+        import pdfplumber
+    except ImportError:
+        raise ImportError("pdfplumber is required for PDF files: pip install pdfplumber")
+
+    text_parts = []
+    with pdfplumber.open(path) as pdf:
+        for page in pdf.pages:
+            page_text = page.extract_text()
+            if page_text:
+                text_parts.append(page_text)
+
+    if not text_parts:
+        raise ValueError(
+            f"Could not extract text from PDF: {path}. "
+            "The PDF may be scanned or image-based. OCR support is not available yet; "
+            "please use a text-based PDF, DOCX, TXT, MD, or RTF file."
+        )
+
+    return "\n\n".join(text_parts)
+
+
+def _extract_docx(path: Path) -> str:
+    """Extract text from a DOCX file."""
+    try:
+        from docx import Document
+    except ImportError:
+        raise ImportError("python-docx is required for DOCX files: pip install python-docx")
+
+    doc = Document(str(path))
+    paragraphs = [p.text for p in doc.paragraphs if p.text.strip()]
+    return "\n\n".join(paragraphs)