sepia-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{sepia_cli-0.1.0 → sepia_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sepia-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Describe a picture and watch it appear as colored text in a second terminal window.
 Keywords: ascii-art,cli,terminal,claude,image-generation,flux
 Author: Yiğit Erdoğan
@@ -50,7 +50,7 @@ Type a short request in your terminal and get a photograph painted in colored te
    pollinations · 5.8s
 ```
 
-Follow-up requests build on the same picture: "mountains" after "waterfall" gives the same waterfall with mountains behind it. `/new` starts over. sepia only makes pictures; it is not a chat assistant.
+Every request starts a new picture. To build on the current one, use `/add`: "waterfall", then `/add mountains`, gives the same waterfall with mountains behind it. sepia only makes pictures; it is not a chat assistant.
 
 ## How it works
 
@@ -70,7 +70,7 @@ Pollinations web API ---- fails or rate limited ----> FLUX.2 [klein] 4B on your
                                     +--- path over a loopback socket --->  photo -> colored characters
 ```
 
-1. **Direct.** Claude (`claude-haiku-5-5` at low effort by default) turns the request and the scene so far into a detailed English photo prompt written for symbol rendering: one clear subject, strong light, saturated color, no text. It also decides whether the request edits the current picture or starts a new one, and writes a one-sentence reply in the language you typed in. The reply comes back as structured output (JSON with a fixed schema).
+1. **Direct.** Claude (`claude-haiku-5-5` at low effort by default) turns the request and the scene so far into a detailed English photo prompt written for symbol rendering: one clear subject, strong light, saturated color, no text. It also decides whether the request edits the current picture or starts a new one, and writes a one-sentence reply. The reply comes back as structured output (JSON with a fixed schema). The image models know no names, so when a request names a specific character, creature, product or landmark ("yunara lol"), Claude searches the web and links the subject's wiki page; sepia takes that page's preview picture and the image model paints from it, so the subject keeps its real look. Reference pictures work with a Pollinations key and with the local model; the keyless API ignores them.
 2. **Paint.** The prompt goes to [Pollinations](https://pollinations.ai) first. If the API fails or rate limits, sepia paints the picture locally with [FLUX.2 [klein] 4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) (Apache 2.0), if you installed the local extra. The picture is painted at the viewer window's aspect ratio.
 3. **Show.** The picture is saved as a PNG, and the viewer window is told where it is. The viewer stretches contrast, boosts saturation, crops the picture to the window, and draws every cell as one character whose density matches the brightness, in 24-bit color where the terminal supports it (256 colors otherwise). Resizing the window redraws the picture without new API calls.
 
@@ -112,13 +112,17 @@ On the first run sepia asks for your Anthropic API key (hidden input) and saves
 
 | Command | What it does |
 | --- | --- |
-| `/new` | Start a fresh picture. The next request does not build on the old one. |
-| `/style [ink\|fill]` | `ink` colors the characters on the terminal's own background (made for dark backgrounds); `fill` also paints each cell's background, which works on any theme. Without an argument it switches to the other style. |
-| `/charset [classic\|symbols]` | `classic` uses 31 density levels of the ASCII-art alphabet (letters, digits, punctuation); `symbols` uses punctuation only. Without an argument it switches to the other set. |
+| `/add <text>` | Add to the current picture instead of starting a new one. |
+| `/clear` | Clear the screen and start a fresh picture. |
+| `/style [ink\|fill]` | `ink` colors the characters on the terminal's own background (made for dark backgrounds); `fill` also paints each cell's background, which works on any theme. Without an argument it opens a menu: arrow keys and Enter (or the option's number) pick, Esc cancels. |
+| `/charset [classic\|symbols]` | `classic` uses 31 density levels of the ASCII-art alphabet (letters, digits, punctuation); `symbols` uses punctuation only. Without an argument it opens a menu, like `/style`. |
+| `/usage` | Show what this session used: Claude's tokens, web searches and estimated cost, and the pictures painted per source. |
 | `/help` | List the commands. |
 | `/exit` | Close sepia and the viewer window. `/quit`, `/q` and Ctrl+D do the same. |
 
-Up and down arrows walk the request history, and typing `/` completes commands. The bottom bar shows the model, the current style and charset, and whether the viewer window is connected (`●`) or not (`○`). If you close the viewer, the next request opens it again.
+Move the mouse over the picture window to glitch the picture around the pointer. It heals when the pointer stops. Windows Terminal and iTerm2 report pointer movement; macOS Terminal.app may not.
+
+Up and down arrows walk the request history, and typing `/` completes commands; Enter on a partial command runs the suggested one (`/us` opens `/usage`). The bottom bar shows the model, the current style and charset, and whether the viewer window is connected (`●`) or not (`○`). If you close the viewer, the next request opens it again.
 
 Command-line flags:
 
@@ -128,8 +132,6 @@ Command-line flags:
 | `--version` | Print the version. |
 | `--help` | Print usage. |
 
-The interface speaks English and Turkish. It follows the system language unless `SEPIA_LANG` is set.
-
 ## Configuration
 
 sepia reads settings from the environment, then from `.env` in the current directory, then from `.env` in the user config folder. A value that is already set is never overridden by a later source. See [.env.example](.env.example).
@@ -143,7 +145,6 @@ sepia reads settings from the environment, then from `.env` in the current direc
 | `SEPIA_STYLE` | `ink` | Starting style: `ink` or `fill`. |
 | `SEPIA_CHARSET` | `classic` | Starting character set: `classic` or `symbols`. |
 | `SEPIA_IMAGE_MODEL` | `black-forest-labs/FLUX.2-klein-4B` | Hugging Face id of the local model. |
-| `SEPIA_LANG` | system language | Interface language: `en` or `tr`. Set it in the shell environment; it is read before the `.env` files load. |
 
 An invalid value for `SEPIA_EFFORT`, `SEPIA_STYLE` or `SEPIA_CHARSET` stops sepia at startup.
 
@@ -179,7 +180,7 @@ The model loads on the first local picture, so that picture takes longer. Edits
 
 ## Platform notes
 
-**Windows.** The viewer opens as a new Windows Terminal window in focus mode, so there is no tab bar or title bar. It uses a `sepia` profile (6 pt Cascadia Mono, black background, no padding) that sepia writes as a Windows Terminal fragment to `%LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\sepia\sepia.json`. Your own `settings.json` is not touched; delete that folder to remove the profile. The small font fits several times more cells into the window, which gives the picture more detail. Without Windows Terminal, the viewer falls back to a plain console window.
+**Windows.** The viewer opens as a new Windows Terminal window with a tab named `sepia` in the theme's pinkish purple; drag the tab row to move the window. It uses a `sepia` profile (6 pt Cascadia Mono, black background, no padding) that sepia writes as a Windows Terminal fragment to `%LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\sepia\sepia.json`. Your own `settings.json` is not touched; delete that folder to remove the profile. The small font fits several times more cells into the window, which gives the picture more detail. Without Windows Terminal, the viewer falls back to a plain console window.
 
 **macOS.** The viewer opens in a new Terminal.app window through `osascript`. The first time, macOS asks whether your terminal may control Terminal.app (Automation permission); allow it. Terminal.app cannot hide its title bar. Press ⌘- in the viewer window to shrink the font: the picture redraws with more cells and more detail.
 

{sepia_cli-0.1.0 → sepia_cli-0.2.0}/README.md

@@ -13,7 +13,7 @@ Type a short request in your terminal and get a photograph painted in colored te
    pollinations · 5.8s
 ```
 
-Follow-up requests build on the same picture: "mountains" after "waterfall" gives the same waterfall with mountains behind it. `/new` starts over. sepia only makes pictures; it is not a chat assistant.
+Every request starts a new picture. To build on the current one, use `/add`: "waterfall", then `/add mountains`, gives the same waterfall with mountains behind it. sepia only makes pictures; it is not a chat assistant.
 
 ## How it works
 
@@ -33,7 +33,7 @@ Pollinations web API ---- fails or rate limited ----> FLUX.2 [klein] 4B on your
                                     +--- path over a loopback socket --->  photo -> colored characters
 ```
 
-1. **Direct.** Claude (`claude-haiku-5-5` at low effort by default) turns the request and the scene so far into a detailed English photo prompt written for symbol rendering: one clear subject, strong light, saturated color, no text. It also decides whether the request edits the current picture or starts a new one, and writes a one-sentence reply in the language you typed in. The reply comes back as structured output (JSON with a fixed schema).
+1. **Direct.** Claude (`claude-haiku-5-5` at low effort by default) turns the request and the scene so far into a detailed English photo prompt written for symbol rendering: one clear subject, strong light, saturated color, no text. It also decides whether the request edits the current picture or starts a new one, and writes a one-sentence reply. The reply comes back as structured output (JSON with a fixed schema). The image models know no names, so when a request names a specific character, creature, product or landmark ("yunara lol"), Claude searches the web and links the subject's wiki page; sepia takes that page's preview picture and the image model paints from it, so the subject keeps its real look. Reference pictures work with a Pollinations key and with the local model; the keyless API ignores them.
 2. **Paint.** The prompt goes to [Pollinations](https://pollinations.ai) first. If the API fails or rate limits, sepia paints the picture locally with [FLUX.2 [klein] 4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) (Apache 2.0), if you installed the local extra. The picture is painted at the viewer window's aspect ratio.
 3. **Show.** The picture is saved as a PNG, and the viewer window is told where it is. The viewer stretches contrast, boosts saturation, crops the picture to the window, and draws every cell as one character whose density matches the brightness, in 24-bit color where the terminal supports it (256 colors otherwise). Resizing the window redraws the picture without new API calls.
 
@@ -75,13 +75,17 @@ On the first run sepia asks for your Anthropic API key (hidden input) and saves
 
 | Command | What it does |
 | --- | --- |
-| `/new` | Start a fresh picture. The next request does not build on the old one. |
-| `/style [ink\|fill]` | `ink` colors the characters on the terminal's own background (made for dark backgrounds); `fill` also paints each cell's background, which works on any theme. Without an argument it switches to the other style. |
-| `/charset [classic\|symbols]` | `classic` uses 31 density levels of the ASCII-art alphabet (letters, digits, punctuation); `symbols` uses punctuation only. Without an argument it switches to the other set. |
+| `/add <text>` | Add to the current picture instead of starting a new one. |
+| `/clear` | Clear the screen and start a fresh picture. |
+| `/style [ink\|fill]` | `ink` colors the characters on the terminal's own background (made for dark backgrounds); `fill` also paints each cell's background, which works on any theme. Without an argument it opens a menu: arrow keys and Enter (or the option's number) pick, Esc cancels. |
+| `/charset [classic\|symbols]` | `classic` uses 31 density levels of the ASCII-art alphabet (letters, digits, punctuation); `symbols` uses punctuation only. Without an argument it opens a menu, like `/style`. |
+| `/usage` | Show what this session used: Claude's tokens, web searches and estimated cost, and the pictures painted per source. |
 | `/help` | List the commands. |
 | `/exit` | Close sepia and the viewer window. `/quit`, `/q` and Ctrl+D do the same. |
 
-Up and down arrows walk the request history, and typing `/` completes commands. The bottom bar shows the model, the current style and charset, and whether the viewer window is connected (`●`) or not (`○`). If you close the viewer, the next request opens it again.
+Move the mouse over the picture window to glitch the picture around the pointer. It heals when the pointer stops. Windows Terminal and iTerm2 report pointer movement; macOS Terminal.app may not.
+
+Up and down arrows walk the request history, and typing `/` completes commands; Enter on a partial command runs the suggested one (`/us` opens `/usage`). The bottom bar shows the model, the current style and charset, and whether the viewer window is connected (`●`) or not (`○`). If you close the viewer, the next request opens it again.
 
 Command-line flags:
 
@@ -91,8 +95,6 @@ Command-line flags:
 | `--version` | Print the version. |
 | `--help` | Print usage. |
 
-The interface speaks English and Turkish. It follows the system language unless `SEPIA_LANG` is set.
-
 ## Configuration
 
 sepia reads settings from the environment, then from `.env` in the current directory, then from `.env` in the user config folder. A value that is already set is never overridden by a later source. See [.env.example](.env.example).
@@ -106,7 +108,6 @@ sepia reads settings from the environment, then from `.env` in the current direc
 | `SEPIA_STYLE` | `ink` | Starting style: `ink` or `fill`. |
 | `SEPIA_CHARSET` | `classic` | Starting character set: `classic` or `symbols`. |
 | `SEPIA_IMAGE_MODEL` | `black-forest-labs/FLUX.2-klein-4B` | Hugging Face id of the local model. |
-| `SEPIA_LANG` | system language | Interface language: `en` or `tr`. Set it in the shell environment; it is read before the `.env` files load. |
 
 An invalid value for `SEPIA_EFFORT`, `SEPIA_STYLE` or `SEPIA_CHARSET` stops sepia at startup.
 
@@ -142,7 +143,7 @@ The model loads on the first local picture, so that picture takes longer. Edits
 
 ## Platform notes
 
-**Windows.** The viewer opens as a new Windows Terminal window in focus mode, so there is no tab bar or title bar. It uses a `sepia` profile (6 pt Cascadia Mono, black background, no padding) that sepia writes as a Windows Terminal fragment to `%LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\sepia\sepia.json`. Your own `settings.json` is not touched; delete that folder to remove the profile. The small font fits several times more cells into the window, which gives the picture more detail. Without Windows Terminal, the viewer falls back to a plain console window.
+**Windows.** The viewer opens as a new Windows Terminal window with a tab named `sepia` in the theme's pinkish purple; drag the tab row to move the window. It uses a `sepia` profile (6 pt Cascadia Mono, black background, no padding) that sepia writes as a Windows Terminal fragment to `%LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\sepia\sepia.json`. Your own `settings.json` is not touched; delete that folder to remove the profile. The small font fits several times more cells into the window, which gives the picture more detail. Without Windows Terminal, the viewer falls back to a plain console window.
 
 **macOS.** The viewer opens in a new Terminal.app window through `osascript`. The first time, macOS asks whether your terminal may control Terminal.app (Automation permission); allow it. Terminal.app cannot hide its title bar. Press ⌘- in the viewer window to shrink the font: the picture redraws with more cells and more detail.
 

{sepia_cli-0.1.0 → sepia_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sepia-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Describe a picture and watch it appear as colored text in a second terminal window."
 readme = "README.md"
 license = "MIT"

{sepia_cli-0.1.0 → sepia_cli-0.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sepia-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Describe a picture and watch it appear as colored text in a second terminal window."
 readme = "README.md"
 license = "MIT"

{sepia_cli-0.1.0 → sepia_cli-0.2.0}/src/sepia/__init__.py

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

sepia_cli-0.2.0/src/sepia/chatbar.py

@@ -0,0 +1,247 @@
+"""The chat bar: an input line between two rules, pinned to the bottom rows.
+
+`ChatBar` draws the whole bar as one block: top rule, the input, bottom rule and a
+status line. (A `PromptSession` puts its bottom toolbar on the screen's last row,
+which split the block in two.)
+
+`BottomBar` keeps that block on the window's last rows. A terminal scroll region
+covers every row above it, so the transcript starts under the welcome box and, once
+it reaches the bar, scrolls the welcome box out of view while the bar never moves.
+"""
+
+import io
+import shutil
+from collections.abc import Callable, Sequence
+
+from prompt_toolkit.application import Application
+from prompt_toolkit.application.current import get_app_session
+from prompt_toolkit.auto_suggest import AutoSuggest, Suggestion
+from prompt_toolkit.buffer import Buffer
+from prompt_toolkit.data_structures import Size
+from prompt_toolkit.document import Document
+from prompt_toolkit.filters import Condition
+from prompt_toolkit.formatted_text import (
+    FormattedText,
+    StyleAndTextTuples,
+    fragment_list_width,
+)
+from prompt_toolkit.history import History
+from prompt_toolkit.key_binding import KeyBindings, KeyPressEvent
+from prompt_toolkit.layout import FormattedTextControl, HSplit, Layout, Window
+from prompt_toolkit.layout.controls import BufferControl
+from prompt_toolkit.layout.processors import (
+    AfterInput,
+    AppendAutoSuggestion,
+    BeforeInput,
+    ConditionalProcessor,
+)
+from prompt_toolkit.output.vt100 import Vt100_Output
+from prompt_toolkit.shortcuts import print_formatted_text
+from prompt_toolkit.styles import Style
+
+from sepia import ui
+
+BAR_ROWS = 4
+"""Top rule, input line, bottom rule, status line."""
+
+STYLE = Style.from_dict(
+    {
+        "frame": ui.FRAME,
+        "prompt": f"bold {ui.ACCENT}",
+        "placeholder": ui.MUTED,
+        "auto-suggestion": ui.MUTED,
+        "status": ui.MUTED,
+    }
+)
+
+
+class BottomBar:
+    """Keeps the chat bar on the bottom rows while the transcript scrolls above it."""
+
+    SAVE, RESTORE, RESET = "\x1b7", "\x1b8", "\x1b[r"
+
+    def __init__(self, write: Callable[[str], None], rows: Callable[[], int]) -> None:
+        self._write = write
+        self._rows = rows
+
+    def start(self) -> None:
+        """Set the region; this also homes the cursor, where the transcript begins."""
+        self._write(self._region())
+
+    def to_bar(self) -> None:
+        """Remember the transcript position and move to the bar's first row."""
+        # Re-applying the region follows window resizes; it homes the cursor, so
+        # the transcript position is saved first and put back afterwards.
+        self._write(self.SAVE + self._region() + self.RESTORE + self.SAVE)
+        self._write(f"\x1b[{self._top()};1H")
+
+    def hold(self, rows: Sequence[str]) -> None:
+        """Draw a still copy of the bar on its rows, one finished row at a time."""
+        top = self._top()
+        for offset, row in enumerate(rows):
+            self._write(f"\x1b[{top + offset};1H\x1b[2K{row}")
+
+    def to_transcript(self) -> None:
+        self._write(self.RESTORE)
+
+    def stop(self) -> None:
+        """Give the whole screen back and clear the bar, leaving the cursor there."""
+        self._write(f"{self.RESET}\x1b[{self._top()};1H\x1b[J")
+
+    def _top(self) -> int:
+        return max(self._rows() - BAR_ROWS + 1, 1)
+
+    def _region(self) -> str:
+        return f"\x1b[1;{max(self._rows() - BAR_ROWS, 1)}r"
+
+
+class CommandSuggest(AutoSuggest):
+    """Completes a slash command in grey as it is typed; Tab or → accepts it.
+
+    An inline hint instead of a menu, because the bar sits on the last rows and a
+    menu below it would fall off the screen.
+    """
+
+    def __init__(self, names: Sequence[str]) -> None:
+        self._names = names
+
+    def get_suggestion(self, buffer: Buffer, document: Document) -> Suggestion | None:
+        text = document.text
+        if not text.startswith("/") or " " in text:
+            return None
+        for name in self._names:
+            if name.startswith(text) and name != text:
+                return Suggestion(name[len(text) :])
+        return None
+
+
+class ChatBar:
+    """Reads one line at a time inside the framed box."""
+
+    def __init__(
+        self,
+        history: History,
+        commands: Sequence[tuple[str, str]],
+        placeholder: str,
+        status: Callable[[], str],
+    ) -> None:
+        self._history = history
+        self._suggest = CommandSuggest([usage.split()[0] for usage, _ in commands])
+        self._placeholder = placeholder
+        self._status = status
+
+    def read(self) -> str:
+        """The submitted line. Raises KeyboardInterrupt on Ctrl+C and EOFError on
+        Ctrl+D in an empty bar, like `input()`."""
+        result: str = self._application().run()
+        return result
+
+    def still(self, width: int) -> list[str]:
+        """The empty bar as rows of text with escape codes, `width` columns wide.
+
+        The live bar erases itself when a line is submitted; drawing this copy in
+        its place keeps the bar on screen while sepia works on the request.
+        """
+        room = max(width - len(ui.PROMPT), 0)
+        rows: list[StyleAndTextTuples] = [
+            [("class:frame", ui.bar_rule(width))],
+            [
+                ("class:prompt", ui.PROMPT),
+                ("class:placeholder", self._placeholder[:room]),
+            ],
+            [("class:frame", ui.bar_rule(width))],
+            [("class:status", self._status()[:width])],
+        ]
+        return [_escaped(row) for row in rows]
+
+    def _application(self) -> Application[str]:
+        buffer = Buffer(
+            history=self._history,
+            auto_suggest=self._suggest,
+            multiline=False,
+            accept_handler=lambda buf: _accept(buf),
+        )
+        empty = Condition(lambda: not buffer.text)
+        field = Window(
+            BufferControl(
+                buffer,
+                input_processors=[
+                    BeforeInput(ui.PROMPT, style="class:prompt"),
+                    AppendAutoSuggestion(),
+                    ConditionalProcessor(
+                        AfterInput(self._placeholder, style="class:placeholder"),
+                        empty,
+                    ),
+                ],
+            ),
+            height=1,
+            dont_extend_height=True,
+        )
+        body = HSplit(
+            [
+                _line(ui.bar_rule, "class:frame"),
+                field,
+                _line(ui.bar_rule, "class:frame"),
+                _line(lambda _: self._status(), "class:status"),
+            ]
+        )
+
+        def _accept(buf: Buffer) -> bool:
+            # Enter on a partial command runs the one suggested for it: /us -> /usage.
+            suggestion = self._suggest.get_suggestion(buf, buf.document)
+            if suggestion is not None:
+                buf.text += suggestion.text
+            app.exit(result=buf.text)
+            return True  # keep the text out of the buffer reset; history still saves
+
+        keys = KeyBindings()
+
+        @keys.add("c-c")
+        def _interrupt(event: KeyPressEvent) -> None:
+            event.app.exit(exception=KeyboardInterrupt())
+
+        @keys.add("c-d", filter=empty)
+        def _end(event: KeyPressEvent) -> None:
+            event.app.exit(exception=EOFError())
+
+        @keys.add("tab")
+        def _complete(event: KeyPressEvent) -> None:
+            # Computed here rather than read from buffer.suggestion, which is
+            # filled in the background and can lag behind fast typing.
+            current = event.current_buffer
+            suggestion = self._suggest.get_suggestion(current, current.document)
+            if suggestion is not None:
+                current.insert_text(suggestion.text)
+
+        app: Application[str] = Application(
+            layout=Layout(body, focused_element=field),
+            key_bindings=keys,
+            style=STYLE,
+            full_screen=False,
+            erase_when_done=True,
+            mouse_support=False,
+        )
+        return app
+
+
+def _line(text: Callable[[int], str], style: str) -> Window:
+    """A one-row window whose text is rebuilt for the current width on every draw."""
+
+    def render() -> FormattedText:
+        return FormattedText([(style, text(shutil.get_terminal_size().columns))])
+
+    return Window(FormattedTextControl(render), height=1, dont_extend_height=True)
+
+
+def _escaped(fragments: StyleAndTextTuples) -> str:
+    """Styled fragments as text with escape codes, in the live bar's colors."""
+    text = io.StringIO()
+    width = fragment_list_width(fragments)
+    print_formatted_text(
+        FormattedText(fragments),
+        end="",
+        style=STYLE,
+        output=Vt100_Output(text, lambda: Size(rows=1, columns=width)),
+        color_depth=get_app_session().output.get_default_color_depth(),
+    )
+    return text.getvalue()

{sepia_cli-0.1.0 → sepia_cli-0.2.0}/src/sepia/director.py

@@ -8,7 +8,11 @@ from string import Template
 from typing import Any
 
 import anthropic
-from anthropic.types.beta import BetaOutputConfigParam
+from anthropic.types.beta import (
+    BetaOutputConfigParam,
+    BetaUsage,
+    BetaWebSearchTool20260209Param,
+)
 from pydantic import BaseModel, Field, ValidationError
 
 from sepia.config import Effort
@@ -24,21 +28,35 @@ 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."""
+WEB_SEARCH: BetaWebSearchTool20260209Param = {
+    "type": "web_search_20260209",
+    "name": "web_search",
+    "max_uses": 2,
+}
+"""Lets Claude look up what an unfamiliar name looks like; about $0.01 a search."""
+MAX_REFERENCES = 3
+"""Links tried for a reference picture; the first usable one wins."""
 
 REPLY_SCHEMA: dict[str, Any] = {
     "type": "object",
     "properties": {
         "message": {
             "type": "string",
-            "description": "One short sentence in the language of the latest request.",
+            "description": "One short sentence in English.",
         },
         "prompt": {"type": "string", "description": "The English image prompt."},
         "edit": {
             "type": "boolean",
             "description": "True to repaint the previous picture, false for a new one.",
         },
+        "references": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Up to three links that show the named subject, best "
+            "first; empty when the request names nothing specific.",
+        },
     },
-    "required": ["message", "prompt", "edit"],
+    "required": ["message", "prompt", "edit", "references"],
     "additionalProperties": False,
 }
 
@@ -68,6 +86,7 @@ class _Reply(BaseModel):
     message: str = Field(min_length=1)
     prompt: str = Field(min_length=1)
     edit: bool
+    references: list[str] = Field(default_factory=list)
 
 
 @dataclass(frozen=True)
@@ -75,6 +94,11 @@ class Direction:
     message: str
     prompt: str
     edit: bool
+    references: tuple[str, ...]
+    """Links to a picture of the subject, for `reference.find_reference`."""
+    model: str
+    """The model that answered; a server-side fallback can differ from the one asked."""
+    searches: int
     input_tokens: int
     output_tokens: int
 
@@ -103,6 +127,7 @@ class Director:
                 betas=[FALLBACK_BETA] if fallback else anthropic.omit,
                 fallbacks="default" if fallback else anthropic.omit,
                 system=system_prompt(),
+                tools=[WEB_SEARCH],
                 output_config=output_config,
                 messages=[{"role": "user", "content": build_request(request, scene)}],
             ) as stream:
@@ -122,7 +147,9 @@ class Director:
             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")
+        # The JSON is the last text block; a search can put remarks before it.
+        texts = [block.text for block in message.content if block.type == "text"]
+        text = texts[-1] if texts else ""
         try:
             reply = _Reply.model_validate_json(text)
         except ValidationError as exc:
@@ -131,11 +158,27 @@ class Director:
             message=reply.message.strip(),
             prompt=reply.prompt.strip(),
             edit=reply.edit and not scene.is_empty,
+            references=_links(reply.references),
+            model=message.model,
+            searches=_searches(message.usage),
             input_tokens=message.usage.input_tokens,
             output_tokens=message.usage.output_tokens,
         )
 
 
+def _searches(usage: BetaUsage) -> int:
+    """Web searches the request ran; None when it ran no server tool at all."""
+    server = usage.server_tool_use
+    return server.web_search_requests if server is not None else 0
+
+
+def _links(raw: list[str]) -> tuple[str, ...]:
+    """The first few https links, trimmed; anything else is dropped."""
+    links = [link.strip() for link in raw]
+    web = [link for link in links if link.startswith("https://")]
+    return tuple(web[:MAX_REFERENCES])
+
+
 @cache
 def system_prompt() -> str:
     return _prompt("director.md")

sepia_cli-0.2.0/src/sepia/glitch.py

@@ -0,0 +1,117 @@
+"""A glitch around the mouse pointer: torn rows, corrupted glyphs, split colors.
+
+Only the cells around the pointer are redrawn, straight as ANSI escapes, so the
+effect can run at 30 frames a second on a picture of tens of thousands of cells.
+"""
+
+import random
+
+from sepia.ascii_art import SymbolArt
+
+RADIUS_X = 13
+RADIUS_Y = 6
+"""Half-size of the glitched area in cells; cells are about twice as tall as wide,
+so this reads as roughly round."""
+DURATION = 0.9
+"""Seconds the glitch lingers and fades after the pointer stops."""
+FRAME_SECONDS = 1 / 30
+MAX_SHIFT = 5
+"""How far, in cells, a torn row segment slides sideways."""
+RIM_JITTER = 0.2
+"""How ragged the round edge is, as a share of the radius."""
+
+# How often each kind of damage happens at full strength, per row or per cell.
+TEAR_RATE = 0.85
+"""A row segment slides sideways."""
+JUMP_RATE = 0.3
+"""A row shows its neighbor above or below instead, so the area judders."""
+NOISE_RATE = 0.7
+"""A glyph turns into noise."""
+SPLIT_RATE = 0.8
+"""A cell's color splits: red from the left neighbor, green and blue from the right."""
+FLASH_RATE = 0.25
+"""A cell flashes magenta, cyan or white."""
+
+NOISE = "░▒▓█▚▞#@%&$!?/\\|<>"
+SPLIT_COLORS = ((255, 0, 170), (0, 255, 255), (255, 255, 255))
+"""Magenta, cyan and white flashes, the usual colors of a broken signal."""
+
+Cell = tuple[str, tuple[int, int, int], tuple[int, int, int] | None]
+
+
+def area(art: SymbolArt, col: int, row: int) -> tuple[int, int, int, int]:
+    """Rows [top, bottom) and columns [left, right) the glitch touches."""
+    top, bottom = max(row - RADIUS_Y, 0), min(row + RADIUS_Y + 1, art.rows)
+    left, right = max(col - RADIUS_X, 0), min(col + RADIUS_X + 1, art.cols)
+    return top, bottom, left, right
+
+
+def glitch_ansi(
+    art: SymbolArt, col: int, row: int, strength: float, rng: random.Random
+) -> str:
+    """One frame of the glitch centered on (col, row); `strength` runs 1 -> 0."""
+    top, bottom, left, right = area(art, col, row)
+    out: list[str] = []
+    for y in range(top, bottom):
+        dy = (y - row) / RADIUS_Y
+        shift = 0
+        if rng.random() < TEAR_RATE * strength:
+            shift = rng.randint(-MAX_SHIFT, MAX_SHIFT)
+        source_row = y
+        if rng.random() < JUMP_RATE * strength:
+            source_row = min(max(y + rng.choice((-1, 1)), 0), art.rows - 1)
+        cells: list[Cell] = []
+        for x in range(left, right):
+            dx = (x - col) / RADIUS_X
+            distance = dx * dx + dy * dy
+            if distance > 1.0 + rng.uniform(-RIM_JITTER, RIM_JITTER):
+                # Outside the circle: the untouched cell, so the corners of the
+                # redrawn box never show and the glitch reads as round.
+                cells.append(_cell(art, y, x))
+                continue
+            # Strongest at the pointer, fading toward the rim.
+            chance = max(0.0, 1.0 - distance) ** 0.6 * strength
+            source = min(max(x - shift, 0), art.cols - 1)
+            char, fg, bg = _cell(art, source_row, source)
+            if rng.random() < chance * NOISE_RATE:
+                char = rng.choice(NOISE)
+            if rng.random() < chance * SPLIT_RATE:
+                red = _cell(art, source_row, max(source - 1, 0))[1][0]
+                right_fg = _cell(art, source_row, min(source + 1, art.cols - 1))[1]
+                fg = (red, right_fg[1], right_fg[2])
+            if rng.random() < chance * FLASH_RATE:
+                fg = rng.choice(SPLIT_COLORS)
+            cells.append((char, fg, bg))
+        out.append(_row_ansi(y, left, cells))
+    return "".join(out) + "\x1b[0m"
+
+
+def restore_ansi(art: SymbolArt, col: int, row: int) -> str:
+    """The untouched cells of the area around (col, row)."""
+    top, bottom, left, right = area(art, col, row)
+    out = [
+        _row_ansi(y, left, [_cell(art, y, x) for x in range(left, right)])
+        for y in range(top, bottom)
+    ]
+    return "".join(out) + "\x1b[0m"
+
+
+def _cell(art: SymbolArt, y: int, x: int) -> Cell:
+    red, green, blue = (int(v) for v in art.fg[y, x])
+    bg = None
+    if art.bg is not None:
+        bg_red, bg_green, bg_blue = (int(v) for v in art.bg[y, x])
+        bg = (bg_red, bg_green, bg_blue)
+    return str(art.chars[y, x]), (red, green, blue), bg
+
+
+def _row_ansi(y: int, left: int, cells: list[Cell]) -> str:
+    parts = [f"\x1b[{y + 1};{left + 1}H"]
+    for char, (red, green, blue), bg in cells:
+        parts.append(f"\x1b[38;2;{red};{green};{blue}m")
+        if bg is not None:
+            parts.append(f"\x1b[48;2;{bg[0]};{bg[1]};{bg[2]}m")
+        else:
+            parts.append("\x1b[49m")
+        parts.append(char)
+    return "".join(parts)