sepia-cli 0.1.0__py3-none-any.whl

sepia/__init__.py

@@ -0,0 +1,3 @@
+"""sepia: prompts become colored symbol paintings in your terminal."""
+
+__version__ = "0.1.0"

sepia/__main__.py

@@ -0,0 +1,3 @@
+from sepia.cli import main
+
+raise SystemExit(main())

sepia/ascii_art.py

@@ -0,0 +1,368 @@
+"""Turn RGB images into colored symbol art."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+import numpy.typing as npt
+from rich.style import Style
+from rich.text import Text
+
+from sepia.raster import RGBImage
+
+CELL_WIDTH = 8
+CELL_HEIGHT = 16
+"""Pixels rendered per terminal cell. Terminal cells are about twice as tall as wide."""
+
+ArtStyle = Literal["ink", "fill"]
+"""`ink` colors the symbols on the terminal's own background (made for dark themes).
+`fill` also paints each cell's background, which shows the picture on any theme."""
+
+FloatArray = npt.NDArray[np.float32]
+
+Charset = Literal["classic", "symbols"]
+"""`classic` is the full ASCII-art alphabet (letters, digits, symbols), which gives the
+finest shading for photographs. `symbols` uses punctuation only."""
+
+# Characters with the share of a cell their ink covers, averaged over Cascadia Mono
+# (the Windows Terminal default) and Consolas, each spaced at least 0.015 apart so that
+# neighbors in a ramp look different.
+_CLASSIC: tuple[tuple[str, float], ...] = (
+    (" ", 0.000),
+    ("`", 0.076),
+    ("'", 0.133),
+    ("-", 0.157),
+    (",", 0.177),
+    ("_", 0.200),
+    ("^", 0.246),
+    ('"', 0.262),
+    ("!", 0.290),
+    ("<", 0.347),
+    ("+", 0.365),
+    ("?", 0.410),
+    ("|", 0.427),
+    ("c", 0.443),
+    ("(", 0.475),
+    ("i", 0.491),
+    ("}", 0.507),
+    ("n", 0.529),
+    ("f", 0.545),
+    ("o", 0.575),
+    ("a", 0.600),
+    ("X", 0.622),
+    ("w", 0.651),
+    ("b", 0.695),
+    ("O", 0.734),
+    ("%", 0.763),
+    ("8", 0.792),
+    ("0", 0.812),
+    ("W", 0.839),
+    ("Q", 0.875),
+    ("@", 1.000),
+)
+# Punctuation only, measured the same way. Directional glyphs stay out so that a
+# texture never reads as an outline.
+_SYMBOLS: tuple[tuple[str, float], ...] = (
+    (" ", 0.00),
+    (".", 0.08),
+    ("'", 0.15),
+    (":", 0.16),
+    (";", 0.24),
+    ("^", 0.27),
+    ("!", 0.29),
+    ("~", 0.30),
+    ("+", 0.39),
+    ("*", 0.45),
+    ("(", 0.55),
+    ("%", 0.80),
+    ("#", 0.81),
+    ("&", 0.87),
+    ("@", 1.00),
+)
+RAMPS: dict[Charset, tuple[tuple[str, float], ...]] = {
+    "classic": _CLASSIC,
+    "symbols": _SYMBOLS,
+}
+_RAMP_ARRAYS = {
+    name: (np.array([c for c, _ in ramp]), np.array([d for _, d in ramp]))
+    for name, ramp in RAMPS.items()
+}
+
+EDGE_STRENGTH = 0.35
+"""Sobel magnitude (blurred luma) above which a pixel counts as part of an edge."""
+EDGE_MIN_PIXELS = 5
+"""Thinned edge pixels a cell needs before it is drawn as an outline."""
+CONTRAST_STRETCH = 0.6
+"""How far luminance is stretched toward the full ramp (0 keeps, 1 stretches fully)."""
+SATURATION_BOOST = 1.2
+"""Thin glyphs show less color than a filled cell, so ink colors are pushed a little."""
+INK_FLOOR = 0.55
+"""Lowest brightness of an ink color (its strongest channel, 0..1). Symbol density
+already shows how bright a cell is, so the color only has to carry its hue; without a
+floor, dark surfaces print as nearly invisible symbols."""
+DENSITY_GAMMA = 0.5
+"""Curve from luminance to symbol density. Below 1 it lifts dark surfaces off the
+background so they read as texture instead of empty space."""
+FILL_BACKGROUND = 0.55
+"""Brightness of the painted background in `fill` style, relative to the cell color."""
+FILL_HIGHLIGHT = 0.35
+"""How far `fill` symbols are mixed toward white so they stand out on their own cell."""
+DITHER = 0.05
+"""Ordered-dither amplitude added to mid-tone luminance before a symbol is picked. It
+turns smooth gradients into mixed symbols instead of one-symbol bands."""
+
+# 4x4 Bayer matrix, centered on zero so dithering does not shift overall brightness.
+_BAYER = (
+    np.array([[0, 8, 2, 10], [12, 4, 14, 6], [3, 11, 1, 9], [15, 7, 13, 5]], np.float32)
+    + 0.5
+) / 16 - 0.5
+
+
+@dataclass(frozen=True, eq=False)
+class SymbolArt:
+    """A grid of symbols with a foreground (and optional background) color per cell."""
+
+    chars: npt.NDArray[np.str_]
+    fg: RGBImage
+    bg: RGBImage | None
+
+    @property
+    def rows(self) -> int:
+        return int(self.chars.shape[0])
+
+    @property
+    def cols(self) -> int:
+        return int(self.chars.shape[1])
+
+    def lines(self) -> list[str]:
+        return ["".join(row) for row in self.chars]
+
+
+def image_to_art(
+    pixels: RGBImage,
+    cols: int,
+    rows: int,
+    style: ArtStyle = "ink",
+    charset: Charset = "classic",
+    edges: bool = False,
+) -> SymbolArt:
+    """Convert `pixels` into `cols` x `rows` cells of colored symbols.
+
+    Each cell averages the pixels under it, so `pixels` should be rendered larger than
+    the grid (see `CELL_WIDTH` and `CELL_HEIGHT`). Leftover pixels at the right and
+    bottom edges are dropped.
+    """
+    if cols <= 0 or rows <= 0:
+        raise ValueError(f"grid must be positive, got {cols}x{rows}")
+    height, width = pixels.shape[:2]
+    cell_h, cell_w = height // rows, width // cols
+    if cell_h == 0 or cell_w == 0:
+        raise ValueError(
+            f"image {width}x{height} is smaller than the {cols}x{rows} grid"
+        )
+    srgb = pixels[: rows * cell_h, : cols * cell_w].astype(np.float32) / 255.0
+
+    linear = _srgb_to_linear(srgb)
+    cell_color = _linear_to_srgb(_cell_mean(linear, rows, cell_h, cols, cell_w))
+    glow = _linear_to_srgb(_bright_mean(linear, rows, cell_h, cols, cell_w))
+    density = _stretch(_luma(cell_color)) ** DENSITY_GAMMA
+    ramp_chars, ramp_density = _RAMP_ARRAYS[charset]
+    chars = ramp_chars[_ramp_index(_dither(density), ramp_density)]
+    if edges:
+        edge_chars = _edge_chars(_luma(srgb), rows, cell_h, cols, cell_w)
+        chars = np.where(edge_chars != "", edge_chars, chars)
+
+    if style == "fill":
+        fg = glow + (1.0 - glow) * FILL_HIGHLIGHT
+        return SymbolArt(chars, _to_bytes(fg), _to_bytes(cell_color * FILL_BACKGROUND))
+    return SymbolArt(chars, _to_bytes(_ink(glow)), None)
+
+
+def to_text(art: SymbolArt) -> Text:
+    """Build a rich `Text` that prints the art, one terminal line per row."""
+    text = Text(no_wrap=True, overflow="crop", end="")
+    styles: dict[tuple[int, ...], Style] = {}
+    for row in range(art.rows):
+        for col in range(art.cols):
+            fg = tuple(int(v) for v in art.fg[row, col])
+            bg = () if art.bg is None else tuple(int(v) for v in art.bg[row, col])
+            key = fg + bg
+            style = styles.get(key)
+            if style is None:
+                style = Style(color=_hex(fg), bgcolor=_hex(bg) if bg else None)
+                styles[key] = style
+            text.append(str(art.chars[row, col]), style)
+        if row < art.rows - 1:
+            text.append("\n")
+    return text
+
+
+def _srgb_to_linear(c: FloatArray) -> FloatArray:
+    return np.where(c <= 0.04045, c / 12.92, ((c + 0.055) / 1.055) ** 2.4)
+
+
+def _linear_to_srgb(c: FloatArray) -> FloatArray:
+    c = np.clip(c, 0.0, 1.0)
+    return np.where(c <= 0.0031308, c * 12.92, 1.055 * c ** (1 / 2.4) - 0.055)
+
+
+def _luma(srgb: FloatArray) -> FloatArray:
+    weights = np.array([0.2126, 0.7152, 0.0722], dtype=np.float32)
+    result: FloatArray = srgb @ weights
+    return result
+
+
+def _cell_mean(
+    values: FloatArray, rows: int, cell_h: int, cols: int, cell_w: int
+) -> FloatArray:
+    shaped = values.reshape(rows, cell_h, cols, cell_w, *values.shape[2:])
+    result: FloatArray = shaped.mean(axis=(1, 3))
+    return result
+
+
+def _bright_mean(
+    linear: FloatArray, rows: int, cell_h: int, cols: int, cell_w: int
+) -> FloatArray:
+    """Cell color weighted toward its brightest pixels.
+
+    A symbol's ink stands for the light in its cell, so a small lit window or star
+    should give the symbol its color instead of being averaged into the dark around
+    it. Weighting by squared luminance does that and leaves flat cells unchanged.
+    """
+    weight = (_luma(linear) ** 2 + 1e-6)[..., None]
+    total = _cell_mean(linear * weight, rows, cell_h, cols, cell_w)
+    result: FloatArray = total / _cell_mean(weight, rows, cell_h, cols, cell_w)
+    return result
+
+
+def _stretch(luma: FloatArray) -> FloatArray:
+    low, high = (float(v) for v in np.percentile(luma, [2, 98]))
+    if high - low < 1e-3:
+        return luma
+    stretched = np.clip((luma - low) / (high - low), 0.0, 1.0)
+    result: FloatArray = luma + (stretched - luma) * CONTRAST_STRETCH
+    return result
+
+
+def _dither(luma: FloatArray) -> FloatArray:
+    """Add the Bayer pattern, fading it out toward pure black and pure white."""
+    rows, cols = luma.shape
+    pattern = np.tile(_BAYER, (rows // 4 + 1, cols // 4 + 1))[:rows, :cols]
+    midtone = 4.0 * luma * (1.0 - luma)
+    result: FloatArray = (luma + pattern * 2.0 * DITHER * midtone).astype(np.float32)
+    return result
+
+
+def _ramp_index(
+    target: FloatArray, density: npt.NDArray[np.float64]
+) -> npt.NDArray[np.intp]:
+    """Index of the ramp character whose ink density is closest to each target."""
+    index: npt.NDArray[np.intp] = np.abs(target[..., None] - density).argmin(axis=-1)
+    return index
+
+
+def _edge_chars(
+    luma: FloatArray, rows: int, cell_h: int, cols: int, cell_w: int
+) -> npt.NDArray[np.str_]:
+    """Outline glyph per cell (`| / - _ \\`), or "" for cells without a strong edge."""
+    blurred = _blur(luma)
+    gx, gy = _sobel(blurred)
+    magnitude = np.hypot(gx, gy)
+    # Gradient angle folded into [0, 180): 0 means brightness changes left to right, so
+    # the edge itself runs vertically. Image rows grow downward.
+    angle = np.degrees(np.arctan2(gy, gx)) % 180.0
+    bins = ((angle + 22.5) // 45.0).astype(np.intp) % 4  # 0: |  1: /  2: -  3: \
+    strong = (magnitude > EDGE_STRENGTH) & _ridge(magnitude, bins)
+
+    def per_cell(mask: npt.NDArray[np.bool_]) -> FloatArray:
+        return _cell_mean(mask.astype(np.float64), rows, cell_h, cols, cell_w)
+
+    coverage = np.stack([per_cell(strong & (bins == b)) for b in range(4)], axis=-1)
+    best = coverage.argmax(axis=-1)
+    is_edge = coverage.sum(axis=-1) * cell_h * cell_w >= EDGE_MIN_PIXELS
+
+    # A horizontal edge in the lower part of its cell reads better as "_" than "-".
+    row_pos = np.broadcast_to(
+        np.arange(luma.shape[0], dtype=np.float64)[:, None], luma.shape
+    )
+    row_in_cell = (row_pos % cell_h) / max(cell_h - 1, 1)
+    horizontal = strong & (bins == 2)
+    count = per_cell(horizontal)
+    weighted = _cell_mean(row_in_cell * horizontal, rows, cell_h, cols, cell_w)
+    mean_pos = np.divide(weighted, count, out=np.zeros_like(count), where=count > 0)
+    glyphs = np.array(["|", "/", "-", "\\"])[best]
+    glyphs = np.where((best == 2) & (mean_pos > 0.7), "_", glyphs)
+    return np.where(is_edge, glyphs, "")
+
+
+def _ridge(magnitude: FloatArray, bins: npt.NDArray[np.intp]) -> npt.NDArray[np.bool_]:
+    """Keep only pixels that peak across their edge (non-maximum suppression).
+
+    Blurring smears an edge over several pixels, which would mark the cells on both
+    sides of it. Thinning to a one-pixel ridge puts each edge in exactly one cell; the
+    `>=` / `>` pair breaks ties the same way every time.
+    """
+    height, width = magnitude.shape
+    padded = np.pad(magnitude, 1)
+
+    def neighbor(dy: int, dx: int) -> FloatArray:
+        result: FloatArray = padded[1 + dy : 1 + dy + height, 1 + dx : 1 + dx + width]
+        return result
+
+    # Neighbors along the gradient, i.e. across the edge, for each direction bin.
+    across = {
+        0: ((0, -1), (0, 1)),
+        1: ((-1, -1), (1, 1)),
+        2: ((-1, 0), (1, 0)),
+        3: ((-1, 1), (1, -1)),
+    }
+    keep = np.zeros(magnitude.shape, dtype=bool)
+    for direction, (before, after) in across.items():
+        peak = (magnitude >= neighbor(*before)) & (magnitude > neighbor(*after))
+        keep |= (bins == direction) & peak
+    return keep
+
+
+def _blur(image: FloatArray, sigma: float = 1.5) -> FloatArray:
+    radius = int(3 * sigma)
+    offsets = np.arange(-radius, radius + 1)
+    kernel = np.exp(-(offsets**2) / (2 * sigma**2)).astype(np.float32)
+    kernel /= kernel.sum()
+    for axis in (0, 1):
+        pad = [(radius, radius) if a == axis else (0, 0) for a in (0, 1)]
+        padded = np.pad(image, pad, "edge")
+        length = image.shape[axis]
+        blurred = np.zeros_like(image)
+        for i, weight in enumerate(kernel):
+            blurred += weight * np.take(padded, np.arange(i, i + length), axis=axis)
+        image = blurred
+    return image
+
+
+def _sobel(image: FloatArray) -> tuple[FloatArray, FloatArray]:
+    p = np.pad(image, 1, "edge")
+    top_left, top, top_right = p[:-2, :-2], p[:-2, 1:-1], p[:-2, 2:]
+    left, right = p[1:-1, :-2], p[1:-1, 2:]
+    bottom_left, bottom, bottom_right = p[2:, :-2], p[2:, 1:-1], p[2:, 2:]
+    gx = (top_right + 2 * right + bottom_right) - (top_left + 2 * left + bottom_left)
+    gy = (bottom_left + 2 * bottom + bottom_right) - (top_left + 2 * top + top_right)
+    return gx, gy
+
+
+def _ink(color: FloatArray) -> FloatArray:
+    gray = _luma(color)[..., None]
+    saturated = np.clip(gray + (color - gray) * SATURATION_BOOST, 0.0, 1.0)
+    value = saturated.max(axis=-1, keepdims=True)
+    lifted = INK_FLOOR + (1.0 - INK_FLOOR) * value
+    scale = np.divide(lifted, value, out=np.ones_like(value), where=value > 0.02)
+    result: FloatArray = np.clip(saturated * scale, 0.0, 1.0).astype(np.float32)
+    return result
+
+
+def _to_bytes(color: FloatArray) -> RGBImage:
+    return np.clip(np.rint(color * 255.0), 0, 255).astype(np.uint8)
+
+
+def _hex(rgb: tuple[int, ...]) -> str:
+    red, green, blue = rgb
+    return f"#{red:02x}{green:02x}{blue:02x}"

sepia/cli.py

@@ -0,0 +1,58 @@
+"""Command-line entry point for `sepia`."""
+
+import argparse
+import contextlib
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from sepia import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sepia",
+        description=(
+            "Describe a picture and watch it appear as colored text in a second "
+            "terminal window."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"sepia {__version__}")
+    parser.add_argument(
+        "--download",
+        action="store_true",
+        help="download the local image model (about 16 GB) used when the API fails",
+    )
+    # Internal: the picture window runs `sepia --viewer <session file>`.
+    parser.add_argument("--viewer", type=Path, help=argparse.SUPPRESS)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    _use_utf8()
+    args = build_parser().parse_args(argv)
+    if args.viewer is not None:
+        from sepia.viewer import run_viewer
+
+        return run_viewer(args.viewer)
+    if args.download:
+        from sepia.painter import PainterError, download_local_model
+
+        try:
+            print(f"downloaded to {download_local_model()}")
+        except PainterError as exc:
+            print(exc, file=sys.stderr)
+            return 1
+        return 0
+    from sepia.repl import run_repl
+
+    return run_repl()
+
+
+def _use_utf8() -> None:
+    """Block and box glyphs need UTF-8 even where the console code page is not."""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            with contextlib.suppress(OSError, ValueError):
+                reconfigure(encoding="utf-8")

sepia/config.py

@@ -0,0 +1,105 @@
+"""Settings and API key lookup."""
+
+import contextlib
+import os
+import stat
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, cast, get_args
+
+from dotenv import load_dotenv
+from platformdirs import user_config_path
+
+from sepia.ascii_art import ArtStyle, Charset
+from sepia.painter import DEFAULT_IMAGE_MODEL
+
+Effort = Literal["low", "medium", "high", "xhigh", "max"]
+
+DEFAULT_MODEL = "claude-haiku-5-5"
+DEFAULT_EFFORT: Effort = "low"
+DEFAULT_STYLE: ArtStyle = "ink"
+DEFAULT_CHARSET: Charset = "classic"
+API_KEY_VAR = "ANTHROPIC_API_KEY"
+
+
+class ConfigError(ValueError):
+    """A setting has a value sepia cannot use."""
+
+
+@dataclass(frozen=True)
+class Settings:
+    model: str = DEFAULT_MODEL
+    effort: Effort = DEFAULT_EFFORT
+    style: ArtStyle = DEFAULT_STYLE
+    charset: Charset = DEFAULT_CHARSET
+    image_model: str = DEFAULT_IMAGE_MODEL
+
+
+def config_dir() -> Path:
+    """Per-user directory for sepia's key file, history and session files."""
+    return user_config_path("sepia", appauthor=False)
+
+
+def user_env_file() -> Path:
+    return config_dir() / ".env"
+
+
+def load_environment(cwd: Path | None = None) -> None:
+    """Fill `os.environ` from `.env` files without overriding what is already set.
+
+    Lookup order: the real environment, then `.env` in the working directory (handy
+    while developing), then the `.env` in the user config directory.
+    """
+    load_dotenv((cwd or Path.cwd()) / ".env", override=False)
+    load_dotenv(user_env_file(), override=False)
+
+
+def load_settings(environ: Mapping[str, str] = os.environ) -> Settings:
+    model = environ.get("SEPIA_MODEL", "").strip() or DEFAULT_MODEL
+    image_model = environ.get("SEPIA_IMAGE_MODEL", "").strip() or DEFAULT_IMAGE_MODEL
+    effort = _choice(environ, "SEPIA_EFFORT", get_args(Effort), DEFAULT_EFFORT)
+    style = _choice(environ, "SEPIA_STYLE", get_args(ArtStyle), DEFAULT_STYLE)
+    charset = _choice(environ, "SEPIA_CHARSET", get_args(Charset), DEFAULT_CHARSET)
+    return Settings(
+        model=model,
+        effort=cast(Effort, effort),
+        style=cast(ArtStyle, style),
+        charset=cast(Charset, charset),
+        image_model=image_model,
+    )
+
+
+def api_key(environ: Mapping[str, str] = os.environ) -> str | None:
+    return environ.get(API_KEY_VAR, "").strip() or None
+
+
+def pollinations_key(environ: Mapping[str, str] = os.environ) -> str | None:
+    """Optional key from enter.pollinations.ai: no logo and better models."""
+    return environ.get("POLLINATIONS_KEY", "").strip() or None
+
+
+def save_api_key(key: str, path: Path | None = None) -> Path:
+    """Store `key` in the user config `.env`, readable only by its owner."""
+    target = path or user_env_file()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    kept: list[str] = []
+    if target.exists():
+        kept = [
+            line
+            for line in target.read_text(encoding="utf-8").splitlines()
+            if not line.startswith(f"{API_KEY_VAR}=")
+        ]
+    target.write_text("\n".join([*kept, f"{API_KEY_VAR}={key.strip()}"]) + "\n")
+    with contextlib.suppress(OSError):  # Windows ignores POSIX modes
+        target.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    return target
+
+
+def _choice(
+    environ: Mapping[str, str], name: str, allowed: tuple[str, ...], default: str
+) -> str:
+    value = environ.get(name, "").strip().lower() or default
+    if value not in allowed:
+        raise ConfigError(f"{name} must be one of {', '.join(allowed)}; got {value!r}")
+    return value