sepia-cli 0.1.0__py3-none-any.whl

sepia/director.py

@@ -0,0 +1,162 @@
+"""Ask Claude to turn a short request into a prompt for the local image model."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+from functools import cache
+from importlib.resources import files
+from string import Template
+from typing import Any
+
+import anthropic
+from anthropic.types.beta import BetaOutputConfigParam
+from pydantic import BaseModel, Field, ValidationError
+
+from sepia.config import Effort
+from sepia.scene import Scene
+
+MAX_TOKENS = 8_000
+"""Room for thinking plus a short JSON reply."""
+MAX_RETRIES = 3
+"""The SDK retries connection errors, 429 and 5xx with exponential backoff."""
+FALLBACK_BETA = "server-side-fallback-2026-07-01"
+"""Lets the API re-run a declined request on Anthropic's recommended fallback model."""
+FALLBACK_MODELS = frozenset(
+    {"claude-fable-5-1", "claude-opus-5-5", "claude-opus-5", "claude-sonnet-5-5"}
+)
+"""Models that accept `fallbacks: "default"`; Haiku has no server-side fallback."""
+
+REPLY_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "message": {
+            "type": "string",
+            "description": "One short sentence in the language of the latest request.",
+        },
+        "prompt": {"type": "string", "description": "The English image prompt."},
+        "edit": {
+            "type": "boolean",
+            "description": "True to repaint the previous picture, false for a new one.",
+        },
+    },
+    "required": ["message", "prompt", "edit"],
+    "additionalProperties": False,
+}
+
+
+class Failure(StrEnum):
+    """Why a request failed, so the prompt can explain it in the user's language."""
+
+    AUTH = "auth"
+    RATE_LIMIT = "rate_limit"
+    SERVER = "server"
+    CONNECTION = "connection"
+    REJECTED = "rejected"
+    REFUSED = "refused"
+    TRUNCATED = "truncated"
+    INVALID = "invalid"
+
+
+class DirectorError(Exception):
+    """The request failed. The scene is untouched, so the user can simply retry."""
+
+    def __init__(self, failure: Failure) -> None:
+        super().__init__(failure.value)
+        self.failure = failure
+
+
+class _Reply(BaseModel):
+    message: str = Field(min_length=1)
+    prompt: str = Field(min_length=1)
+    edit: bool
+
+
+@dataclass(frozen=True)
+class Direction:
+    message: str
+    prompt: str
+    edit: bool
+    input_tokens: int
+    output_tokens: int
+
+
+def create_client(api_key: str) -> anthropic.Anthropic:
+    return anthropic.Anthropic(api_key=api_key, max_retries=MAX_RETRIES)
+
+
+class Director:
+    def __init__(self, client: anthropic.Anthropic, model: str, effort: Effort) -> None:
+        self._client = client
+        self._model = model
+        self._effort = effort
+
+    def direct(self, request: str, scene: Scene) -> Direction:
+        """Turn `request`, in the context of `scene`, into an image prompt."""
+        output_config: BetaOutputConfigParam = {
+            "effort": self._effort,
+            "format": {"type": "json_schema", "schema": REPLY_SCHEMA},
+        }
+        fallback = self._model in FALLBACK_MODELS
+        try:
+            with self._client.beta.messages.stream(
+                model=self._model,
+                max_tokens=MAX_TOKENS,
+                betas=[FALLBACK_BETA] if fallback else anthropic.omit,
+                fallbacks="default" if fallback else anthropic.omit,
+                system=system_prompt(),
+                output_config=output_config,
+                messages=[{"role": "user", "content": build_request(request, scene)}],
+            ) as stream:
+                message = stream.get_final_message()
+        except (anthropic.AuthenticationError, anthropic.PermissionDeniedError) as exc:
+            raise DirectorError(Failure.AUTH) from exc
+        except anthropic.RateLimitError as exc:
+            raise DirectorError(Failure.RATE_LIMIT) from exc
+        except anthropic.BadRequestError as exc:
+            raise DirectorError(Failure.REJECTED) from exc
+        except anthropic.APIStatusError as exc:
+            raise DirectorError(Failure.SERVER) from exc
+        except anthropic.APIConnectionError as exc:
+            raise DirectorError(Failure.CONNECTION) from exc
+
+        if message.stop_reason == "refusal":
+            raise DirectorError(Failure.REFUSED)
+        if message.stop_reason == "max_tokens":
+            raise DirectorError(Failure.TRUNCATED)
+        text = "".join(block.text for block in message.content if block.type == "text")
+        try:
+            reply = _Reply.model_validate_json(text)
+        except ValidationError as exc:
+            raise DirectorError(Failure.INVALID) from exc
+        return Direction(
+            message=reply.message.strip(),
+            prompt=reply.prompt.strip(),
+            edit=reply.edit and not scene.is_empty,
+            input_tokens=message.usage.input_tokens,
+            output_tokens=message.usage.output_tokens,
+        )
+
+
+@cache
+def system_prompt() -> str:
+    return _prompt("director.md")
+
+
+def build_request(request: str, scene: Scene) -> str:
+    if scene.is_empty:
+        history = (
+            "<previous_requests>none: this is the first picture</previous_requests>"
+        )
+    else:
+        earlier = "\n".join(f"{i}. {text}" for i, text in enumerate(scene.requests, 1))
+        history = (
+            f"<previous_requests>\n{earlier}\n</previous_requests>\n"
+            f"<previous_prompt>{scene.prompts[-1]}</previous_prompt>"
+        )
+    return Template(_prompt("request.md")).substitute(
+        history=history, request=request.strip()
+    )
+
+
+@cache
+def _prompt(name: str) -> str:
+    return files("sepia").joinpath("prompts", name).read_text(encoding="utf-8")

sepia/ipc.py

@@ -0,0 +1,169 @@
+"""Authenticated JSON messages between the prompt window and the viewer window.
+
+The prompt listens on a random loopback port; the viewer connects with a one-time key
+read from a session file only the current user can read. `multiprocessing.connection`
+does the HMAC handshake. Messages travel as JSON bytes and are never unpickled, so a
+peer can send data but never code.
+"""
+
+import contextlib
+import json
+import secrets
+import stat
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from multiprocessing import AuthenticationError
+from multiprocessing.connection import Client, Listener
+from pathlib import Path
+from typing import Any, Protocol
+
+HOST = "127.0.0.1"
+
+Message = dict[str, Any]
+
+
+class _Connection(Protocol):
+    """The part of `multiprocessing.connection.Connection` sepia uses."""
+
+    def send_bytes(self, buf: bytes) -> None: ...
+    def recv_bytes(self) -> bytes: ...
+    def poll(self, timeout: float | None = ...) -> bool: ...
+    def close(self) -> None: ...
+
+
+@dataclass(frozen=True)
+class Session:
+    """Where the viewer finds the prompt and how it proves who it is."""
+
+    port: int
+    authkey: bytes
+
+    def save(self, path: Path) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        data = {"port": self.port, "authkey": self.authkey.hex()}
+        path.write_text(json.dumps(data), encoding="utf-8")
+        with contextlib.suppress(OSError):  # Windows ignores POSIX modes
+            path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+    @classmethod
+    def load(cls, path: Path) -> "Session":
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return cls(port=int(data["port"]), authkey=bytes.fromhex(data["authkey"]))
+
+
+class Channel:
+    """One end of an open link."""
+
+    def __init__(self, connection: _Connection) -> None:
+        self._connection = connection
+        self._send_lock = threading.Lock()
+
+    def send(self, message: Message) -> None:
+        """Send `message`; raises `OSError` or `EOFError` once the peer is gone."""
+        data = json.dumps(message).encode("utf-8")
+        with self._send_lock:
+            self._connection.send_bytes(data)
+
+    def poll(self, timeout: float = 0.0) -> bool:
+        return self._connection.poll(timeout)
+
+    def receive(self) -> Message:
+        """Next message; raises `EOFError` or `OSError` once the peer is gone."""
+        message = json.loads(self._connection.recv_bytes().decode("utf-8"))
+        if not isinstance(message, dict):
+            raise ValueError("expected a JSON object")
+        return message
+
+    def close(self) -> None:
+        with contextlib.suppress(OSError):
+            self._connection.close()
+
+
+def connect(session: Session) -> Channel:
+    """Viewer side: open the link described by `session`."""
+    return Channel(Client((HOST, session.port), authkey=session.authkey))
+
+
+class Host:
+    """Prompt side: waits for one viewer at a time and relays what it reports.
+
+    `on_message` runs on a background thread for every message the viewer sends.
+    """
+
+    def __init__(self, on_message: Callable[[Message], None]) -> None:
+        self._on_message = on_message
+        authkey = secrets.token_bytes(32)
+        self._listener = Listener((HOST, 0), authkey=authkey)
+        self.session = Session(port=int(self._listener.address[1]), authkey=authkey)
+        self._channel: Channel | None = None
+        self._connected = threading.Event()
+        self._lock = threading.Lock()
+        self._accepting = False
+
+    @property
+    def connected(self) -> bool:
+        return self._connected.is_set()
+
+    def accept_in_background(self) -> None:
+        """Start waiting for a viewer unless one is connected or already awaited."""
+        with self._lock:
+            if self._accepting or self.connected:
+                return
+            self._accepting = True
+        threading.Thread(target=self._accept, name="sepia-accept", daemon=True).start()
+
+    def wait_connected(self, timeout: float) -> bool:
+        return self._connected.wait(timeout)
+
+    def send(self, message: Message) -> bool:
+        """Deliver `message` to the viewer; False when no viewer is connected."""
+        channel = self._channel
+        if channel is None:
+            return False
+        try:
+            channel.send(message)
+        except (OSError, EOFError):
+            self._drop(channel)
+            return False
+        return True
+
+    def close(self) -> None:
+        if self._channel is not None:
+            self._channel.close()
+        with contextlib.suppress(OSError):
+            self._listener.close()
+
+    def _accept(self) -> None:
+        while True:
+            try:
+                channel = Channel(self._listener.accept())
+                break
+            except (AuthenticationError, EOFError):
+                continue  # a peer without the key; keep waiting for the real viewer
+            except OSError:  # the listener was closed
+                with self._lock:
+                    self._accepting = False
+                return
+        with self._lock:
+            self._channel = channel
+            self._accepting = False
+        self._connected.set()
+        self._read(channel)
+
+    def _read(self, channel: Channel) -> None:
+        while True:
+            try:
+                message = channel.receive()
+            except (OSError, EOFError, ValueError):
+                self._drop(channel)
+                return
+            self._on_message(message)
+
+    def _drop(self, channel: Channel) -> None:
+        with self._lock:
+            if self._channel is not channel:
+                return
+            self._channel = None
+            self._connected.clear()
+        channel.close()

sepia/launcher.py

@@ -0,0 +1,141 @@
+"""Open the picture window in a new terminal window."""
+
+import contextlib
+import json
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+VIEWER_COLS = 110
+VIEWER_ROWS = 36
+"""Window size in cells of the default font; the small profile font fits about
+1.8x as many in each direction."""
+VIEWER_FONT_SIZE = 6
+"""Points. More, smaller cells give the picture more detail."""
+LAUNCH_TIMEOUT_SECONDS = 15
+PROFILE_NAME = "sepia"
+PROFILE_GUID = "{6f1c2b9e-3a57-4d0e-9c84-5e2f7a1d3b60}"
+
+
+class LaunchError(RuntimeError):
+    """The picture window could not be opened."""
+
+
+def viewer_command(session_file: Path) -> list[str]:
+    """The command the new window runs; same interpreter, so it works in any venv."""
+    return [sys.executable, "-m", "sepia", "--viewer", str(session_file)]
+
+
+def open_viewer(session_file: Path) -> None:
+    command = viewer_command(session_file)
+    try:
+        if sys.platform == "win32":
+            _open_windows(command)
+        elif sys.platform == "darwin":
+            _open_macos(command)
+        else:
+            raise LaunchError("the picture window opens on Windows and macOS only")
+    except (OSError, subprocess.SubprocessError) as exc:
+        raise LaunchError(f"could not open the picture window: {exc}") from exc
+
+
+def windows_terminal_command(wt: str, command: list[str]) -> list[str]:
+    """A new Windows Terminal window in focus mode: no tab bar and no title bar."""
+    return [
+        wt,
+        "--window",
+        "new",
+        "--focus",
+        "--size",
+        f"{VIEWER_COLS},{VIEWER_ROWS}",
+        "new-tab",
+        "--profile",
+        PROFILE_NAME,
+        "--title",
+        "sepia",
+        "--suppressApplicationTitle",
+        "--",
+        *command,
+    ]
+
+
+def macos_script(command: list[str]) -> str:
+    """AppleScript that runs `command` in a new Terminal.app window.
+
+    `exec` replaces the shell, so the window closes when the viewer exits.
+    """
+    shell_line = "exec " + shlex.join(command)
+    quoted = shell_line.replace("\\", "\\\\").replace('"', '\\"')
+    return f'tell application "Terminal"\n  do script "{quoted}"\n  activate\nend tell'
+
+
+def windows_profile() -> dict[str, object]:
+    """A Windows Terminal profile for the picture: tiny font, black, no padding."""
+    return {
+        "guid": PROFILE_GUID,
+        "name": PROFILE_NAME,
+        "commandline": "cmd.exe",
+        "font": {"face": "Cascadia Mono", "size": VIEWER_FONT_SIZE},
+        "padding": "0",
+        "background": "#000000",
+        "scrollbarState": "hidden",
+        "closeOnExit": "always",
+        "bellStyle": "none",
+    }
+
+
+def install_windows_profile(local_app_data: Path | None = None) -> Path | None:
+    """Write sepia's profile as a Windows Terminal fragment; None when not possible.
+
+    Fragments live in their own folder, so the user's settings.json is never touched,
+    and deleting the folder removes the profile again.
+    """
+    base = local_app_data or Path(os.environ.get("LOCALAPPDATA", ""))
+    if not base.is_dir():
+        return None
+    target = (
+        base / "Microsoft" / "Windows Terminal" / "Fragments" / "sepia" / "sepia.json"
+    )
+    content = json.dumps({"profiles": [windows_profile()]}, indent=2)
+    with contextlib.suppress(OSError):
+        if not target.exists() or target.read_text(encoding="utf-8") != content:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+        return target
+    return None
+
+
+def find_windows_terminal(local_app_data: Path | None = None) -> str | None:
+    """wt.exe from PATH, or from its app alias folder, which PATH may not include."""
+    found = shutil.which("wt")
+    if found is not None:
+        return found
+    base = local_app_data or Path(os.environ.get("LOCALAPPDATA", ""))
+    alias = base / "Microsoft" / "WindowsApps" / "wt.exe"
+    return str(alias) if alias.is_file() else None
+
+
+def _open_windows(command: list[str]) -> None:
+    wt = find_windows_terminal()
+    if wt is not None:
+        install_windows_profile()
+        subprocess.run(
+            windows_terminal_command(wt, command),
+            check=True,
+            timeout=LAUNCH_TIMEOUT_SECONDS,
+        )
+        return
+    if sys.platform == "win32":  # narrows the type for the console flag
+        subprocess.Popen(command, creationflags=subprocess.CREATE_NEW_CONSOLE)
+
+
+def _open_macos(command: list[str]) -> None:
+    subprocess.run(
+        ["osascript", "-e", macos_script(command)],
+        check=True,
+        capture_output=True,
+        timeout=LAUNCH_TIMEOUT_SECONDS,
+    )