kiwimatecoder 0.1.0__py3-none-any.whl

kiwimatecoder/diagnostics.py

@@ -0,0 +1,295 @@
+"""Environment, config, and provider diagnostics for ``/doctor``."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import os
+import platform
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+from kiwimatecoder import __version__, audit, catalog, config
+from kiwimatecoder.providers import ProviderConfig
+from kiwimatecoder.session import Session
+
+OK = "ok"
+WARN = "warn"
+FAIL = "fail"
+
+
+@dataclass(frozen=True)
+class Check:
+    """One diagnostic result."""
+
+    name: str
+    status: str
+    detail: str
+
+
+def _git_branch(root: Path) -> str | None:
+    head = root / ".git" / "HEAD"
+    if not head.is_file():
+        return None
+    try:
+        ref = head.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    if ref.startswith("ref: refs/heads/"):
+        return ref.split("/")[-1]
+    return ref[:7] or None
+
+
+def _package_version(name: str) -> str:
+    try:
+        return importlib.metadata.version(name)
+    except importlib.metadata.PackageNotFoundError:
+        return "not installed"
+
+
+def _config_checks() -> list[Check]:
+    checks: list[Check] = []
+    try:
+        config_dir = config.ensure_config_dir()
+    except OSError as exc:
+        return [Check("Config dir", FAIL, f"cannot create {config.CONFIG_DIR}: {exc}")]
+
+    writable = os.access(config_dir, os.W_OK)
+    checks.append(
+        Check(
+            "Config dir",
+            OK if writable else FAIL,
+            f"{config_dir}" + ("" if writable else " (not writable)"),
+        )
+    )
+
+    if config.CONFIG_FILE.is_file():
+        checks.append(Check("Global config", OK, str(config.CONFIG_FILE)))
+    else:
+        checks.append(Check("Global config", WARN, "not created yet (defaults in use)"))
+
+    project_path = config.project_config_path()
+    if project_path is not None:
+        checks.append(Check("Project config", OK, str(project_path)))
+    else:
+        candidate = Path.cwd() / config.PROJECT_CONFIG_NAME
+        checks.append(Check("Project config", OK, f"none (optional; {candidate} not found)"))
+
+    from kiwimatecoder import team as team_module
+
+    team_settings = config.get_team()
+    if not team_settings["policy_path"]:
+        checks.append(Check("Team policy", OK, "none (optional)"))
+    else:
+        issues = team_module.policy_issues()
+        errors = [issue for issue in issues if issue["level"] == "error"]
+        detail = (
+            f"{team_settings['policy_path']} "
+            f"({'enforced' if team_settings['enforce'] else 'advisory'})"
+        )
+        if errors:
+            status = FAIL
+            detail += f" — {errors[0]['message']}"
+        elif issues:
+            status = WARN
+            detail += f" — {issues[0]['message']}"
+        else:
+            status = OK
+        checks.append(Check("Team policy", status, detail))
+
+    sessions = config.ensure_config_dir() / "sessions"
+    count = len(list(sessions.glob("*.json"))) if sessions.is_dir() else 0
+    checks.append(Check("Saved sessions", OK, f"{count} in {sessions}"))
+
+    audit_path = audit.audit_log_path()
+    if audit_path.exists():
+        try:
+            size = audit_path.stat().st_size
+        except OSError:
+            size = 0
+        checks.append(Check("Audit log", OK, f"{audit_path} ({size} bytes)"))
+    else:
+        checks.append(Check("Audit log", OK, f"{audit_path} (not created yet)"))
+
+    from kiwimatecoder import telemetry as telemetry_module
+
+    telemetry_settings = config.get_telemetry()
+    crash_count = len(telemetry_module.crash_report_paths())
+    checks.append(
+        Check(
+            "Telemetry",
+            OK,
+            f"level {telemetry_settings['level']} "
+            f"({'on' if telemetry_settings['enabled'] else 'off'}) — "
+            f"log {telemetry_module.current_log_path()}; "
+            f"{crash_count} crash report(s)",
+        )
+    )
+    return checks
+
+
+def _provider_checks(session: Session) -> list[Check]:
+    checks: list[Check] = []
+    provider: ProviderConfig = session.provider
+    checks.append(
+        Check("Provider", OK, f"{provider.id} ({provider.name}) — {provider.base_url}")
+    )
+    key_source = config.key_source(provider.id)
+    if provider.needs_key and key_source["origin"] == "missing":
+        checks.append(
+            Check(
+                "API key",
+                WARN,
+                f"missing — export {provider.key_env} or run "
+                f"`kiwimatecoder setup --provider {provider.id}`",
+            )
+        )
+    else:
+        checks.append(Check("API key", OK, config.describe_key(provider.id)))
+
+    if provider.is_local:
+        running = catalog.probe(provider, api_key=config.get_key(provider.id))
+        checks.append(
+            Check(
+                "Local server",
+                OK if running else WARN,
+                f"{provider.base_url} " + ("is responding" if running else "did not answer"),
+            )
+        )
+
+    try:
+        model_catalog = config.get_model_catalog(provider.id)
+        detail = f"{len(model_catalog.models)} models ({model_catalog.source})"
+        if model_catalog.error:
+            detail += f" — {model_catalog.error}"
+        checks.append(
+            Check(
+                "Model catalog",
+                WARN if model_catalog.error else OK,
+                detail,
+            )
+        )
+        if not session.model:
+            checks.append(
+                Check(
+                    "Current model",
+                    WARN,
+                    "none chosen — pick one with /model or "
+                    f"`kiwimatecoder config model set <model> --provider {provider.id}`",
+                )
+            )
+        elif model_catalog.models:
+            if session.model in model_catalog.models:
+                checks.append(Check("Current model", OK, session.model))
+            else:
+                checks.append(
+                    Check(
+                        "Current model",
+                        WARN,
+                        f"{session.model} is not in the current catalog (still usable by name)",
+                    )
+                )
+    except Exception as exc:  # pragma: no cover - defensive
+        checks.append(Check("Model catalog", FAIL, str(exc)))
+
+    for fallback in session.active_providers[1:]:
+        if not session.model_for(fallback.id):
+            checks.append(
+                Check(
+                    "Fallback model",
+                    WARN,
+                    f"none chosen for {fallback.id}, so failover skips it — run "
+                    f"`kiwimatecoder config model set <model> --provider {fallback.id}`",
+                )
+            )
+    return checks
+
+
+def _workspace_checks(session: Session) -> list[Check]:
+    root = session.workspace_root
+    checks: list[Check] = []
+    if not root.exists():
+        return [Check("Workspace", FAIL, f"{root} does not exist")]
+    writable = os.access(root, os.W_OK)
+    branch = _git_branch(root)
+    detail = str(root) + (f" (git:{branch})" if branch else "")
+    checks.append(Check("Workspace", OK if writable else WARN, detail))
+    checks.append(
+        Check(
+            "Permission mode",
+            OK,
+            f"{session.mode.value}; always-allowed: "
+            + (", ".join(sorted(session.always_allowed)) or "none"),
+        )
+    )
+    style = session.output_style
+    custom = "custom prompt set" if session.custom_system_prompt else "no custom prompt"
+    checks.append(Check("Output style", OK, f"{style} ({custom})"))
+    sampling = config.get_sampling()
+    checks.append(
+        Check(
+            "Sampling",
+            OK,
+            ", ".join(f"{key}={value}" for key, value in sampling.items())
+            or "provider defaults",
+        )
+    )
+    return checks
+
+
+def run_checks(session: Session) -> list[Check]:
+    """Collect all diagnostic checks, never raising."""
+    checks: list[Check] = [
+        Check(
+            "Version",
+            OK,
+            f"kiwimatecoder {__version__} (Python {platform.python_version()}, "
+            f"{sys.platform})",
+        ),
+        Check(
+            "Dependencies",
+            OK,
+            "httpx " + _package_version("httpx")
+            + ", rich " + _package_version("rich")
+            + ", prompt_toolkit " + _package_version("prompt_toolkit")
+            + ", typer " + _package_version("typer"),
+        ),
+    ]
+    checks.extend(_config_checks())
+    try:
+        checks.extend(_provider_checks(session))
+    except Exception as exc:  # pragma: no cover - defensive
+        checks.append(Check("Provider", FAIL, str(exc)))
+    checks.extend(_workspace_checks(session))
+    return checks
+
+
+_STATUS_STYLE = {OK: "green", WARN: "yellow", FAIL: "red"}
+
+
+def render(checks: list[Check], console: Console) -> None:
+    """Print checks as a table and a one-line summary."""
+    table = Table(title="KiwiMateCoder diagnostics", show_header=True)
+    table.add_column("Check", style="cyan", no_wrap=True)
+    table.add_column("Status")
+    table.add_column("Details")
+    for check in checks:
+        style = _STATUS_STYLE.get(check.status, "white")
+        table.add_row(
+            escape(check.name),
+            f"[{style}]{check.status}[/{style}]",
+            escape(check.detail),
+        )
+    console.print(table)
+    failures = sum(1 for check in checks if check.status == FAIL)
+    warnings = sum(1 for check in checks if check.status == WARN)
+    if failures:
+        console.print(f"[red]{failures} check(s) failed.[/red]")
+    elif warnings:
+        console.print(f"[yellow]{warnings} warning(s); nothing critical.[/yellow]")
+    else:
+        console.print("[green]All checks passed.[/green]")

kiwimatecoder/documents.py

@@ -0,0 +1,299 @@
+"""Pure extractors for notebooks, PDFs, and docx files.
+
+``read_file`` delegates to :func:`extract_document` before its binary check so
+structured documents are surfaced as text instead of being rejected. Every
+extractor is best-effort and never raises: failures come back as a clear,
+model-readable string. Output is capped at :data:`MAX_CHARS` with a truncation
+note.
+
+PDF support degrades gracefully: the ``pdftotext`` CLI (poppler) is used when
+available, otherwise a conservative stdlib fallback decompresses FlateDecode
+streams and pulls text out of ``BT``/``ET`` blocks. If neither yields text, the
+result explains how to install poppler.
+"""
+
+from __future__ import annotations
+
+import base64
+import html
+import json
+import re
+import shutil
+import subprocess
+import zipfile
+import zlib
+from pathlib import Path
+from typing import Any
+
+MAX_CHARS = 200_000
+DOCUMENT_SUFFIXES = (".ipynb", ".pdf", ".docx")
+PDFTOTEXT_TIMEOUT = 30
+
+PDF_INSTALL_HINT = (
+    "Error: no extractable text found in this PDF. Install pdftotext (poppler) "
+    "for reliable PDF text extraction, or convert the pages to images and "
+    "attach them with view_image."
+)
+
+
+def _truncate(text: str, source: str) -> str:
+    if len(text) <= MAX_CHARS:
+        return text
+    return (
+        text[:MAX_CHARS]
+        + f"\n... [truncated: {source} exceeds {MAX_CHARS:,} characters]"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Jupyter notebooks (.ipynb)
+# ---------------------------------------------------------------------------
+
+
+def _join_text(value: Any) -> str:
+    if isinstance(value, list):
+        return "".join(str(part) for part in value)
+    return str(value or "")
+
+
+def _image_payload_size(value: Any) -> int:
+    if isinstance(value, (bytes, bytearray)):
+        return len(value)
+    text = str(value)
+    try:
+        return len(base64.b64decode(text, validate=False))
+    except ValueError:
+        return len(text)
+
+
+def _format_notebook_output(output: dict[str, Any]) -> list[str]:
+    output_type = str(output.get("output_type") or "")
+    if output_type == "stream":
+        text = _join_text(output.get("text")).rstrip("\n")
+        return ["Output:", text] if text else []
+    if output_type == "error":
+        name = str(output.get("ename") or "Error")
+        value = str(output.get("evalue") or "")
+        return [f"Output error: {name}: {value}".rstrip(": ")]
+    data = output.get("data")
+    if not isinstance(data, dict):
+        return []
+    rendered: list[str] = []
+    text_plain = data.get("text/plain")
+    if text_plain:
+        rendered.append(_join_text(text_plain).rstrip("\n"))
+    for mime, value in data.items():
+        if not isinstance(mime, str) or not mime.startswith("image/"):
+            continue
+        rendered.append(f"[{mime} output, {_image_payload_size(value)} bytes]")
+    return ["Output:", *rendered] if rendered else []
+
+
+def extract_notebook(path: str | Path) -> str:
+    """Render a ``.ipynb`` file as Markdown-ish text with cell outputs."""
+    notebook_path = Path(path)
+    try:
+        raw = notebook_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return f"Error: could not read notebook '{notebook_path}': {exc}"
+    except UnicodeDecodeError as exc:
+        return f"Error: '{notebook_path.name}' is not readable UTF-8 text: {exc}"
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        return f"Error: '{notebook_path.name}' is not valid notebook JSON: {exc}"
+    if not isinstance(data, dict):
+        return (
+            f"Error: '{notebook_path.name}' is not a notebook "
+            "(expected a JSON object)."
+        )
+    cells = data.get("cells")
+    if not isinstance(cells, list):
+        return f"Error: '{notebook_path.name}' has no 'cells' list."
+
+    lines: list[str] = []
+    for index, cell in enumerate(cells, 1):
+        if not isinstance(cell, dict):
+            continue
+        cell_type = str(cell.get("cell_type") or "unknown")
+        lines.append(f"## Cell {index} ({cell_type})")
+        source = _join_text(cell.get("source")).rstrip("\n")
+        if source:
+            lines.append(source)
+        for output in cell.get("outputs") or []:
+            if isinstance(output, dict):
+                lines.extend(_format_notebook_output(output))
+    body = "\n".join(lines).rstrip() + "\n" if lines else ""
+    return _truncate(body, notebook_path.name)
+
+
+# ---------------------------------------------------------------------------
+# Word documents (.docx)
+# ---------------------------------------------------------------------------
+
+
+def extract_docx(path: str | Path) -> str:
+    """Extract text from ``word/document.xml`` inside a ``.docx`` archive."""
+    docx_path = Path(path)
+    try:
+        with zipfile.ZipFile(docx_path) as archive:
+            try:
+                xml_bytes = archive.read("word/document.xml")
+            except KeyError:
+                return (
+                    f"Error: '{docx_path.name}' is not a valid docx file "
+                    "(missing word/document.xml)."
+                )
+    except zipfile.BadZipFile:
+        return f"Error: '{docx_path.name}' is not a valid docx file (not a zip)."
+    except OSError as exc:
+        return f"Error: could not read docx '{docx_path.name}': {exc}"
+    try:
+        xml_text = xml_bytes.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        return f"Error: '{docx_path.name}' has unreadable document.xml: {exc}"
+
+    # Preserve structure before stripping tags: paragraphs and line breaks
+    # become newlines, tabs become tabs. Entities are decoded last so text like
+    # ``&lt;w:p&gt;`` cannot turn into a fake tag.
+    xml_text = re.sub(r"</w:p\s*>", "\n", xml_text)
+    xml_text = re.sub(r"<w:br\s*/?>", "\n", xml_text)
+    xml_text = re.sub(r"<w:tab\s*/?>", "\t", xml_text)
+    text = re.sub(r"<[^>]+>", "", xml_text)
+    text = html.unescape(text)
+    lines = [line.rstrip() for line in text.splitlines()]
+    body = "\n".join(lines).strip()
+    return _truncate(body + "\n" if body else "", docx_path.name)
+
+
+# ---------------------------------------------------------------------------
+# PDFs
+# ---------------------------------------------------------------------------
+
+_PDF_STREAM_RE = re.compile(rb"stream\r?\n(.*?)\r?\nendstream", re.DOTALL)
+_PDF_STRING_RE = re.compile(r"\((?:\\.|[^\\()])*\)", re.DOTALL)
+_PDF_ESCAPES = {"n": "\n", "r": "\r", "t": "\t", "b": "\b", "f": "\f"}
+
+
+def _inflate(data: bytes) -> bytes | None:
+    for wbits in (zlib.MAX_WBITS, -zlib.MAX_WBITS):
+        try:
+            return zlib.decompress(data, wbits)
+        except zlib.error:
+            continue
+    return None
+
+
+def _unescape_pdf_string(value: str) -> str:
+    result: list[str] = []
+    index = 0
+    length = len(value)
+    while index < length:
+        char = value[index]
+        if char != "\\" or index + 1 >= length:
+            result.append(char)
+            index += 1
+            continue
+        nxt = value[index + 1]
+        if nxt in "\\()":
+            result.append(nxt)
+            index += 2
+        elif nxt in _PDF_ESCAPES:
+            result.append(_PDF_ESCAPES[nxt])
+            index += 2
+        elif nxt.isdigit():
+            digits = nxt
+            index += 2
+            while index < length and len(digits) < 3 and value[index].isdigit():
+                digits += value[index]
+                index += 1
+            result.append(chr(int(digits, 8) & 0xFF))
+        else:
+            index += 2
+    return "".join(result)
+
+
+def _extract_pdf_text(stream: bytes) -> str:
+    """Pull literal strings out of ``BT``/``ET`` blocks of a content stream."""
+    text = stream.decode("latin-1", "replace")
+    lines: list[str] = []
+    for block in re.findall(r"BT(.*?)ET", text, flags=re.DOTALL):
+        pieces = [
+            _unescape_pdf_string(match.group(0)[1:-1])
+            for match in _PDF_STRING_RE.finditer(block)
+        ]
+        joined = " ".join(piece for piece in pieces if piece)
+        if joined:
+            lines.append(joined)
+    return "\n".join(lines)
+
+
+def _pdf_fallback(data: bytes) -> str:
+    """Conservative stdlib extraction: inflate streams, then read BT/ET text."""
+    chunks: list[str] = []
+    for match in _PDF_STREAM_RE.finditer(data):
+        raw = match.group(1)
+        decoded = _inflate(raw)
+        if decoded is None:
+            decoded = raw
+        chunk = _extract_pdf_text(decoded)
+        if chunk:
+            chunks.append(chunk)
+    return "\n".join(chunks).strip()
+
+
+def extract_pdf(path: str | Path) -> str:
+    """Extract PDF text via ``pdftotext`` when present, else the fallback.
+
+    Never raises; returns :data:`PDF_INSTALL_HINT` when nothing parseable is
+    found.
+    """
+    pdf_path = Path(path)
+    executable = shutil.which("pdftotext")
+    if executable:
+        try:
+            completed = subprocess.run(
+                # PDF first, "-" as the output file means stdout. (Reversing
+                # these would make pdftotext read stdin and overwrite the PDF.)
+                [executable, str(pdf_path), "-"],
+                capture_output=True,
+                timeout=PDFTOTEXT_TIMEOUT,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            return f"Error: pdftotext failed: {exc}"
+        if completed.returncode == 0:
+            stdout = completed.stdout.decode("utf-8", "replace")
+            if stdout.strip():
+                return _truncate(stdout, pdf_path.name)
+
+    try:
+        data = pdf_path.read_bytes()
+    except OSError as exc:
+        return f"Error: could not read PDF '{pdf_path.name}': {exc}"
+    text = _pdf_fallback(data)
+    if text.strip():
+        return _truncate(text + "\n", pdf_path.name)
+    return PDF_INSTALL_HINT
+
+
+# ---------------------------------------------------------------------------
+# Dispatch
+# ---------------------------------------------------------------------------
+
+
+def extract_document(path: str | Path) -> tuple[str, str] | None:
+    """Dispatch by suffix, returning ``(content, kind)`` or None.
+
+    ``kind`` is one of ``"notebook"``, ``"pdf"``, or ``"docx"``. Content may be
+    an error string when the file is malformed; callers surface it as-is.
+    """
+    document_path = Path(path)
+    suffix = document_path.suffix.lower()
+    if suffix == ".ipynb":
+        return extract_notebook(document_path), "notebook"
+    if suffix == ".pdf":
+        return extract_pdf(document_path), "pdf"
+    if suffix == ".docx":
+        return extract_docx(document_path), "docx"
+    return None

kiwimatecoder/evals/__init__.py

@@ -0,0 +1,39 @@
+"""Declarative eval harness for prompt/tool regressions."""
+
+from kiwimatecoder.evals.cases import (
+    DEFAULT_CASES_DIR,
+    CaseError,
+    EvalCase,
+    Expectation,
+    discover_cases,
+    load_case,
+    parse_case,
+    resolve_cases_dir,
+)
+from kiwimatecoder.evals.runner import (
+    EvalReport,
+    EvalResult,
+    EvalTimeout,
+    evaluate_case,
+    materialize_case,
+    run_case,
+    run_suite,
+)
+
+__all__ = [
+    "DEFAULT_CASES_DIR",
+    "CaseError",
+    "EvalCase",
+    "EvalReport",
+    "EvalResult",
+    "EvalTimeout",
+    "Expectation",
+    "discover_cases",
+    "evaluate_case",
+    "load_case",
+    "materialize_case",
+    "parse_case",
+    "resolve_cases_dir",
+    "run_case",
+    "run_suite",
+]