querri 1.0.2__py3-none-any.whl

querri/cli/_image.py

@@ -0,0 +1,234 @@
+"""Terminal image rendering using Unicode half-block characters.
+
+Downloads images to ``~/.querri/cache/images/`` and renders them as colored
+ANSI art using the ``Pillow`` library and Unicode half-block characters (``\\u2580``
+upper, ``\\u2584`` lower). Each character cell encodes two vertical pixels,
+doubling the effective vertical resolution.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from pathlib import Path
+
+logger = logging.getLogger("querri")
+
+# ---------------------------------------------------------------------------
+# Cache directory
+# ---------------------------------------------------------------------------
+
+CACHE_DIR = Path.home() / ".querri" / "cache" / "images"
+
+# ANSI 256-color palette breakpoints for the 6x6x6 RGB cube (indices 16-231).
+_PALETTE = [0, 95, 135, 175, 215, 255]
+
+
+def _nearest_palette_index(value: int) -> int:
+    """Find the nearest index in the 6-level palette for a single channel."""
+    best = 0
+    best_dist = abs(value - _PALETTE[0])
+    for i in range(1, 6):
+        dist = abs(value - _PALETTE[i])
+        if dist < best_dist:
+            best_dist = dist
+            best = i
+    return best
+
+
+def _rgb_to_ansi256(r: int, g: int, b: int) -> int:
+    """Convert an RGB triplet to the nearest ANSI 256 color index."""
+    ri = _nearest_palette_index(r)
+    gi = _nearest_palette_index(g)
+    bi = _nearest_palette_index(b)
+    return 16 + ri * 36 + gi * 6 + bi
+
+
+# ---------------------------------------------------------------------------
+# Download + cache
+# ---------------------------------------------------------------------------
+
+
+def _cache_path(url: str) -> Path:
+    """Deterministic cache path for a URL."""
+    h = hashlib.sha256(url.encode()).hexdigest()[:16]
+    suffix = Path(url.split("?")[0]).suffix or ".png"
+    return CACHE_DIR / f"{h}{suffix}"
+
+
+def download_image(
+    url: str,
+    *,
+    headers: dict[str, str] | None = None,
+    retries: int = 2,
+) -> Path | None:
+    """Download an image to the local cache. Returns the path or None on error.
+
+    Retries on failure (useful when the file was just created and may
+    not be immediately available from the storage backend).
+
+    Args:
+        url: Image URL to download.
+        headers: Optional auth headers for authenticated endpoints.
+        retries: Number of retry attempts on failure.
+    """
+    import time
+
+    import httpx
+
+    cached = _cache_path(url)
+    if cached.exists():
+        return cached
+
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+    for attempt in range(retries + 1):
+        try:
+            resp = httpx.get(
+                url,
+                headers=headers or {},
+                follow_redirects=True,
+                timeout=15.0,
+            )
+            resp.raise_for_status()
+            cached.write_bytes(resp.content)
+            return cached
+        except Exception as exc:
+            logger.debug(
+                "Image download attempt %d/%d failed for %s: %s",
+                attempt + 1,
+                retries + 1,
+                url,
+                exc,
+            )
+            if attempt < retries:
+                time.sleep(1.0)
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Half-block renderer
+# ---------------------------------------------------------------------------
+
+
+def render_image(
+    path: Path,
+    *,
+    max_width: int = 60,
+    max_height: int = 30,
+) -> str | None:
+    """Render an image file as ANSI-colored Unicode half-block art.
+
+    Each character cell uses upper-half-block (``\\u2580``) with foreground for
+    the top pixel and background for the bottom pixel, giving 2x vertical
+    resolution.
+
+    Args:
+        path: Path to an image file (PNG, JPEG, etc.).
+        max_width: Maximum character width for the output.
+        max_height: Maximum character height (each char = 2 pixel rows).
+
+    Returns:
+        A string with ANSI escape codes, or None if rendering fails.
+    """
+    try:
+        from PIL import Image
+    except ImportError:
+        logger.debug("Pillow not installed — cannot render image")
+        return None
+
+    try:
+        img = Image.open(path).convert("RGB")
+    except Exception as exc:
+        logger.debug("Failed to open image %s: %s", path, exc)
+        return None
+
+    # Resize to fit terminal — height is doubled because each char = 2 rows
+    w, h = img.size
+    scale_w = max_width / w
+    scale_h = (max_height * 2) / h  # 2 pixel rows per char row
+    scale = min(scale_w, scale_h, 1.0)  # never upscale
+
+    new_w = max(1, int(w * scale))
+    new_h = max(2, int(h * scale))
+    # Ensure even height for half-block pairing
+    if new_h % 2 != 0:
+        new_h += 1
+
+    img = img.resize((new_w, new_h), Image.LANCZOS)  # type: ignore[attr-defined]
+    pixels = img.load()
+    assert pixels is not None
+
+    lines: list[str] = []
+    for y in range(0, new_h, 2):
+        line_parts: list[str] = []
+        for x in range(new_w):
+            # Top pixel = foreground, bottom pixel = background
+            r1, g1, b1 = pixels[x, y]  # type: ignore[misc]
+            if y + 1 < new_h:
+                r2, g2, b2 = pixels[x, y + 1]  # type: ignore[misc]
+            else:
+                r2, g2, b2 = r1, g1, b1
+
+            fg = _rgb_to_ansi256(r1, g1, b1)
+            bg = _rgb_to_ansi256(r2, g2, b2)
+            # \u2580 = upper half block — fg colors top, bg colors bottom
+            line_parts.append(f"\033[38;5;{fg}m\033[48;5;{bg}m\u2580")
+
+        lines.append("".join(line_parts) + "\033[0m")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Rich integration
+# ---------------------------------------------------------------------------
+
+
+def render_image_rich(
+    url: str,
+    *,
+    caption: str = "",
+    max_width: int = 60,
+    max_height: int = 24,
+    headers: dict[str, str] | None = None,
+) -> object:
+    """Download and render an image as a Rich Panel with ANSI art.
+
+    Falls back to a clickable link if rendering fails.
+
+    Args:
+        url: Image URL to download and render.
+        caption: Optional caption text to show below the image.
+        max_width: Maximum character width.
+        max_height: Maximum character height.
+
+    Returns:
+        A Rich renderable (Panel or Text).
+    """
+    from rich.text import Text
+
+    path = download_image(url, headers=headers)
+    ansi_art = (
+        render_image(path, max_width=max_width, max_height=max_height) if path else None
+    )
+
+    if ansi_art:
+        # Rich Text.from_ansi parses ANSI escape codes into styled text
+        art = Text.from_ansi(ansi_art)
+        parts = [art]
+        if caption:
+            parts.append(Text(f"\n{caption}", style="italic"))
+        # Clickable link hint below
+        parts.append(
+            Text.from_markup(f"\n[dim][link={url}]Open full image[/link][/dim]")
+        )
+        return Text("\n").join(parts)
+    else:
+        # Fallback: clickable link + hint
+        return Text.from_markup(
+            f"  [link={url}][bold #f15a24]View chart[/bold #f15a24][/link]"
+            f"  [dim]{url}[/dim]\n"
+            f"  [dim]Run [bold]querri chat show[/bold] to render inline[/dim]"
+        )

querri/cli/_output.py

@@ -0,0 +1,293 @@
+"""CLI output formatting — shared helpers for all commands.
+
+Governs all CLI output behavior: Rich tables for TTY, plain text for pipes,
+JSON for --json, IDs only for --quiet. Handles exit codes and error formatting.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+import typer
+
+# ---------------------------------------------------------------------------
+# Querri brand colors
+# ---------------------------------------------------------------------------
+
+QUERRI_ORANGE = "#f15a24"
+QUERRI_ORANGE_LIGHT = "#ff7a47"
+
+# ---------------------------------------------------------------------------
+# TTY auto-detection — single check, drives all output behavior
+# ---------------------------------------------------------------------------
+
+IS_INTERACTIVE = sys.stdout.isatty()
+
+
+# ---------------------------------------------------------------------------
+# Exit code helpers
+# ---------------------------------------------------------------------------
+
+EXIT_SUCCESS = 0
+EXIT_ERROR = 1
+EXIT_AUTH_ERROR = 2
+EXIT_NOT_FOUND = 3
+EXIT_RATE_LIMITED = 4
+
+
+def exit_success() -> None:
+    raise typer.Exit(code=EXIT_SUCCESS)
+
+
+def exit_error() -> None:
+    raise typer.Exit(code=EXIT_ERROR)
+
+
+def exit_auth_error() -> None:
+    raise typer.Exit(code=EXIT_AUTH_ERROR)
+
+
+def exit_not_found() -> None:
+    raise typer.Exit(code=EXIT_NOT_FOUND)
+
+
+def exit_rate_limited() -> None:
+    raise typer.Exit(code=EXIT_RATE_LIMITED)
+
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+
+
+def print_json(data: Any) -> None:
+    """Output pretty-printed JSON to stdout."""
+    if hasattr(data, "model_dump"):
+        data = data.model_dump(mode="json")
+    elif hasattr(data, "__dict__") and not isinstance(data, dict):
+        data = {k: v for k, v in data.__dict__.items() if not k.startswith("_")}
+    print(json.dumps(data, indent=2, default=str))
+
+
+def print_id(id_value: str) -> None:
+    """Output bare ID string (for --quiet mode)."""
+    print(id_value)
+
+
+def print_table(
+    data: Iterable[Any],
+    columns: list[tuple[str, str]],
+    *,
+    ctx: typer.Context | None = None,
+) -> None:
+    """Render data as a table.
+
+    In TTY mode, uses Rich tables. In non-TTY mode, outputs tab-delimited text.
+
+    Args:
+        data: Iterable of objects (dicts, Pydantic models, or cursor pages).
+        columns: List of (field_name, display_header) tuples.
+        ctx: Optional Typer context for checking --json/--quiet flags.
+    """
+    data = list(data)
+    obj = ctx.ensure_object(dict) if ctx else {}
+    is_interactive = obj.get("interactive", IS_INTERACTIVE)
+
+    if is_interactive:
+        _print_rich_table(data, columns)
+    else:
+        _print_plain_table(data, columns)
+
+
+def _get_field(item: Any, field: str) -> str:
+    """Extract a field from a dict or object, return as string."""
+    val = item.get(field, "") if isinstance(item, dict) else getattr(item, field, "")
+    if val is None:
+        return "—"
+    if isinstance(val, list):
+        return ", ".join(str(v) for v in val)
+    return str(val)
+
+
+def _print_rich_table(data: Sequence[Any], columns: list[tuple[str, str]]) -> None:
+    """Render a Rich table to stdout."""
+    from rich.console import Console
+    from rich.table import Table
+
+    table = Table(show_header=True, header_style=f"bold {QUERRI_ORANGE}")
+    for _, header in columns:
+        table.add_column(header)
+
+    for item in data:
+        row = [_get_field(item, field) for field, _ in columns]
+        table.add_row(*row)
+
+    console = Console()
+    console.print(table)
+
+
+def _print_plain_table(data: Sequence[Any], columns: list[tuple[str, str]]) -> None:
+    """Output tab-delimited text (for piping)."""
+    # Header
+    print("\t".join(header for _, header in columns))
+    # Rows
+    for item in data:
+        row = [_get_field(item, field) for field, _ in columns]
+        print("\t".join(row))
+
+
+def print_detail(data: Any, fields: list[tuple[str, str]]) -> None:
+    """Print a single object's details in a key-value format.
+
+    Args:
+        data: Dict or Pydantic model.
+        fields: List of (field_name, display_label) tuples.
+    """
+    if IS_INTERACTIVE:
+        from rich.console import Console
+        from rich.table import Table
+
+        table = Table(show_header=False, box=None, padding=(0, 2))
+        table.add_column("Field", style=f"bold {QUERRI_ORANGE}")
+        table.add_column("Value")
+
+        for field, label in fields:
+            table.add_row(label, _get_field(data, field))
+
+        console = Console()
+        console.print(table)
+    else:
+        for field, label in fields:
+            print(f"{label}: {_get_field(data, field)}")
+
+
+def print_success(message: str) -> None:
+    """Print a success message."""
+    if IS_INTERACTIVE:
+        from rich.console import Console
+
+        Console(stderr=True).print(f"[{QUERRI_ORANGE}]✓[/{QUERRI_ORANGE}] {message}")
+    else:
+        print(message, file=sys.stderr)
+
+
+def print_error(message: str) -> None:
+    """Print an error message to stderr (red in TTY mode)."""
+    if IS_INTERACTIVE:
+        from rich.console import Console
+
+        Console(stderr=True).print(f"[red]Error:[/red] {message}")
+    else:
+        print(f"Error: {message}", file=sys.stderr)
+
+
+def print_json_error(
+    error_type: str,
+    message: str,
+    exit_code: int,
+    *,
+    hint: str | None = None,
+) -> None:
+    """Print a JSON-formatted error to stderr."""
+    error_obj: dict[str, Any] = {
+        "error": error_type,
+        "message": message,
+        "code": exit_code,
+    }
+    if hint:
+        error_obj["hint"] = hint
+    print(json.dumps(error_obj))
+
+
+# ---------------------------------------------------------------------------
+# Error handler — maps SDK exceptions to CLI output + exit codes
+# ---------------------------------------------------------------------------
+
+
+EXIT_SERVER_ERROR = 5
+
+
+def handle_api_error(exc: Exception, *, is_json: bool | None = False) -> int:
+    """Handle an SDK exception, print appropriate output, return exit code.
+
+    Args:
+        exc: The exception from the SDK.
+        is_json: Whether --json mode is active. ``None`` is treated as ``False``.
+
+    Returns:
+        Exit code to use.
+    """
+    is_json = bool(is_json)
+    from querri._exceptions import (
+        APIError,
+        AuthenticationError,
+        NotFoundError,
+        RateLimitError,
+        ServerError,
+    )
+
+    if isinstance(exc, AuthenticationError):
+        exit_code = EXIT_AUTH_ERROR
+        error_type = "auth_failed"
+        message = (
+            "Authentication failed. Check your API key"
+            " or set QUERRI_API_KEY environment variable."
+        )
+    elif isinstance(exc, NotFoundError):
+        exit_code = EXIT_NOT_FOUND
+        error_type = "not_found"
+        message = str(exc)
+    elif isinstance(exc, RateLimitError):
+        exit_code = EXIT_RATE_LIMITED
+        error_type = "rate_limited"
+        retry_after = getattr(exc, "retry_after", None)
+        message = (
+            f"Rate limited. Retry after {retry_after}s."
+            if retry_after
+            else "Rate limited."
+        )
+    elif isinstance(exc, ServerError):
+        exit_code = EXIT_SERVER_ERROR
+        error_type = "server_error"
+        message = str(exc)
+    else:
+        exit_code = EXIT_ERROR
+        error_type = "api_error"
+        message = str(exc)
+
+    # Extract rich context from APIError subclasses
+    details: dict[str, str] = {}
+    if isinstance(exc, APIError):
+        if exc.status:
+            details["status"] = str(exc.status)
+        if exc.code:
+            details["code"] = exc.code
+        if exc.type:
+            details["type"] = exc.type
+        if exc.request_id:
+            details["request_id"] = exc.request_id
+        if exc.doc_url:
+            details["doc_url"] = exc.doc_url
+
+    if is_json:
+        error_obj: dict[str, object] = {
+            "error": error_type,
+            "message": message,
+            "code": exit_code,
+        }
+        error_obj.update(details)
+        print(json.dumps(error_obj))
+    else:
+        print_error(message)
+        # Show additional context for server errors and unexpected failures
+        if details.get("code"):
+            print_error(f"  Code: {details['code']}")
+        if details.get("request_id"):
+            print_error(f"  Request ID: {details['request_id']}")
+        if details.get("doc_url"):
+            print_error(f"  Docs: {details['doc_url']}")
+
+    return exit_code

querri/cli/audit.py

@@ -0,0 +1,68 @@
+"""querri audit — view audit log events."""
+
+from __future__ import annotations
+
+import typer
+
+from querri.cli._context import get_client
+from querri.cli._output import (
+    handle_api_error,
+    print_json,
+    print_table,
+)
+
+audit_app = typer.Typer(
+    name="audit",
+    help="View audit log events.",
+    no_args_is_help=True,
+)
+
+
+@audit_app.command("list")
+def list_events(
+    ctx: typer.Context,
+    actor_id: str | None = typer.Option(None, "--actor-id", help="Filter by actor ID."),
+    target_id: str | None = typer.Option(
+        None, "--target-id", help="Filter by target ID."
+    ),
+    action: str | None = typer.Option(None, "--action", help="Filter by action type."),
+    start_date: str | None = typer.Option(
+        None, "--start-date", help="Start date (ISO 8601)."
+    ),
+    end_date: str | None = typer.Option(
+        None, "--end-date", help="End date (ISO 8601)."
+    ),
+    limit: int = typer.Option(25, "--limit", "-l", help="Max results to return."),
+    after: str | None = typer.Option(None, "--after", help="Cursor for pagination."),
+) -> None:
+    """List audit log events."""
+    obj = ctx.ensure_object(dict)
+    client = get_client(ctx)
+    try:
+        items = client.audit.list(
+            actor_id=actor_id,
+            target_id=target_id,
+            action=action,
+            start_date=start_date,
+            end_date=end_date,
+            limit=limit,
+            after=after,
+        )
+    except Exception as exc:
+        raise typer.Exit(code=handle_api_error(exc, is_json=obj.get("json"))) from None
+
+    if obj.get("json"):
+        print_json([e.model_dump(mode="json") for e in items])
+    else:
+        print_table(
+            items,
+            [
+                ("id", "ID"),
+                ("action", "Action"),
+                ("actor_id", "Actor"),
+                ("target_type", "Target Type"),
+                ("target_id", "Target ID"),
+                ("timestamp", "Timestamp"),
+            ],
+            ctx=ctx,
+        )