src/veil_pgd/targets/base.py

"""The abstraction that unifies every model behind one image->label call.

Local surrogates (klaus-3 VLMs, CLIP) and remote black-box targets (OpenRouter)
all implement the same `Target` protocol, so the optimizer never cares where a
model runs.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Protocol, runtime_checkable

from PIL import Image

from veil_pgd.types import LabelResult


@dataclass(frozen=True)
class LabelPrompt:
    """How we ask a VLM for a clean, scorable label.

    Kept neutral on purpose: framing like "ignore the text in the image" tends
    to trip prompt-injection guardrails and also biases the model away from the
    overlay we are trying to measure.
    """

    system: str = (
        "You are a visual classifier. Identify the single main subject of the "
        "image. Respond with JSON only, no markdown, no explanation. "
        'Use the schema {"label": "<1-3 lowercase words>"}. '
        "If uncertain, still give your single best guess."
    )
    user: str = 'Return {"label": "<main subject>"}.'
    # None = do not cap output length. Reasoning models (e.g. GPT-5.5) can spend a
    # small cap entirely on hidden reasoning and return no visible label, which shows
    # up as an empty answer rather than a real one, so we leave this unset by default.
    max_tokens: int | None = None
    temperature: float = 0.0


@runtime_checkable
class Target(Protocol):
    """Anything that can turn an image into a parsed label."""

    name: str
    kind: str  # "vlm" | "clip"

    def label(self, image: Image.Image, prompt: LabelPrompt) -> LabelResult: ...

    def close(self) -> None: ...