limn 0.1.0__py3-none-any.whl

limn/__init__.py

@@ -0,0 +1,3 @@
+"""Limn — a small, privacy-first text-to-image tool."""
+
+__version__ = "0.1.0"

limn/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m limn`."""
+
+from limn.cli import app
+
+if __name__ == "__main__":
+    app()

limn/cli.py

@@ -0,0 +1,150 @@
+"""Limn CLI: `limn "a red bicycle" -o bike.png`."""
+
+from __future__ import annotations
+
+import re
+
+import typer
+from rich.console import Console
+
+from limn import __version__
+from limn.config import ConfigurationError, load_config, resolve_settings
+from limn.config import save_example_config as _save_example_config
+from limn.core import generate, save_images
+from limn.providers import ProviderError
+
+console = Console()
+err_console = Console(stderr=True, style="bold red")
+
+app = typer.Typer(
+    add_completion=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+_SIZE_RE = re.compile(r"^(\d+)\s*[xX]\s*(\d+)$")
+
+
+def parse_size(value: str) -> tuple[int, int]:
+    """Parse '1024x1024' (or a bare '1024' meaning square) into (w, h)."""
+    value = value.strip()
+    if value.isdigit():
+        side = int(value)
+        return side, side
+    match = _SIZE_RE.match(value)
+    if not match:
+        raise typer.BadParameter(
+            f"Size must look like 1024x1024 (got {value!r})"
+        )
+    return int(match.group(1)), int(match.group(2))
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"limn {__version__}")
+        raise typer.Exit()
+
+
+@app.command()
+def main(
+    prompt: str = typer.Argument(
+        None,
+        help="Text description of the image to generate.",
+        show_default=False,
+    ),
+    provider: str = typer.Option(
+        None,
+        "--provider",
+        "-p",
+        help="Image provider: swarmui, openai-compatible, openai, gemini.",
+        show_default=False,
+    ),
+    model: str = typer.Option(
+        None, "--model", "-m", help="Model name (provider-specific).",
+        show_default=False,
+    ),
+    size: str = typer.Option(
+        None, "--size", "-s", help="Image size, e.g. 1024x1024.",
+        show_default=False,
+    ),
+    count: int = typer.Option(
+        None, "--count", "-n", min=1, max=10, help="Number of images.",
+        show_default=False,
+    ),
+    seed: int = typer.Option(
+        None, "--seed", help="Seed for reproducibility (if supported).",
+        show_default=False,
+    ),
+    negative: str = typer.Option(
+        None, "--negative", help="Negative prompt (if supported).",
+        show_default=False,
+    ),
+    out: str = typer.Option(
+        None, "--out", "-o", help="Output file (default: derived from prompt).",
+        show_default=False,
+    ),
+    config: str = typer.Option(
+        None, "--config", "-c", help="Config file (default: ./limn.yaml).",
+        show_default=False,
+    ),
+    init_config: bool = typer.Option(
+        False, "--init-config", help="Write an example ./limn.yaml and exit."
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Print version and exit.",
+    ),
+) -> None:
+    """Turn a text description into an image, with the provider you chose.
+
+    Configure once in ~/.limn.yaml (provider, server URL / API key), then:
+
+        limn "a red bicycle against a brick wall" -o bike.png
+    """
+    del version  # handled by the eager callback
+
+    try:
+        if init_config:
+            path = _save_example_config()
+            console.print(f"Wrote example config: [bold]{path}[/bold]")
+            raise typer.Exit()
+
+        if not prompt:
+            err_console.print("Give me a prompt, e.g.: limn \"a red bicycle\"")
+            raise typer.Exit(code=2)
+
+        cfg = load_config(config)
+        provider_name = provider or cfg.get("provider")
+        if not provider_name:
+            err_console.print(
+                "No provider configured. Set 'provider:' in ~/.limn.yaml "
+                "(limn --init-config writes a template) or pass --provider."
+            )
+            raise typer.Exit(code=2)
+
+        settings = resolve_settings(cfg, str(provider_name))
+        if model is not None:
+            settings["model"] = model
+        if size is not None:
+            settings["size"] = list(parse_size(size))
+        if count is not None:
+            settings["count"] = count
+        if seed is not None:
+            settings["seed"] = seed
+        if negative is not None:
+            settings["negative"] = negative
+
+        with console.status(
+            f"Generating with {provider_name}...", spinner="dots"
+        ):
+            images = generate(prompt, settings)
+        paths = save_images(images, prompt, out)
+        for path in paths:
+            console.print(f"Saved: [bold green]{path}[/bold green]")
+
+    except (ConfigurationError, ProviderError, ValueError) as e:
+        err_console.print(str(e))
+        raise typer.Exit(code=1) from None

limn/config.py

@@ -0,0 +1,199 @@
+"""Layered configuration for Limn.
+
+Layers, later wins:
+
+1. Built-in defaults
+2. ``~/.limn.yaml``  — personal provider + keys, set once
+3. ``./limn.yaml``   — per-directory overrides (or an explicit ``--config`` path)
+4. CLI flags         — applied by the CLI on top of the loaded config
+
+Secrets are referenced as ``${VAR}`` and expanded from the environment, so no
+plaintext keys need to live in config files.
+"""
+
+from __future__ import annotations
+
+import copy
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class ConfigurationError(Exception):
+    """Raised when configuration is invalid or missing."""
+
+
+# Flat on purpose: Limn does one thing. An optional ``providers:`` mapping
+# holds per-provider settings (base_url, model, api_key) so several providers
+# can stay configured at once and be swapped with ``provider:`` / --provider.
+DEFAULT_CONFIG: dict[str, Any] = {
+    "provider": None,
+    "base_url": None,
+    "model": None,
+    "api_key": None,
+    "size": [1024, 1024],
+    "count": 1,
+    "seed": None,
+    "negative": None,
+    "timeout": 180,
+    "providers": {},
+}
+
+_ENV_VAR_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def expand_env_vars(value: Any) -> Any:
+    """Recursively expand ``${VAR}`` references in configuration values."""
+    if isinstance(value, str):
+        return _ENV_VAR_RE.sub(lambda m: os.getenv(m.group(1), ""), value)
+    if isinstance(value, dict):
+        return {k: expand_env_vars(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [expand_env_vars(item) for item in value]
+    return value
+
+
+def _first_existing(*candidates: Path) -> Path | None:
+    for path in candidates:
+        if path.exists():
+            return path
+    return None
+
+
+def find_home_config() -> Path | None:
+    """The user-level config (~/.limn.yaml) — provider + keys, set once."""
+    return _first_existing(
+        Path.home() / ".limn.yaml",
+        Path.home() / ".limn.yml",
+    )
+
+
+def find_project_config() -> Path | None:
+    """The directory-level config (./limn.yaml)."""
+    return _first_existing(
+        Path("./limn.yaml"),
+        Path("./limn.yml"),
+    )
+
+
+def _read_config_file(config_file: Path) -> dict[str, Any] | None:
+    try:
+        with open(config_file, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise ConfigurationError(f"Invalid YAML in {config_file}: {e}") from e
+    except OSError as e:
+        raise ConfigurationError(f"Error reading {config_file}: {e}") from e
+    if data is None:
+        return None
+    if not isinstance(data, dict):
+        raise ConfigurationError(
+            f"Config file {config_file} must contain a YAML mapping"
+        )
+    return data
+
+
+def merge_configs(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Deep-merge two config dicts (override wins)."""
+    result = base.copy()
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = merge_configs(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def load_config(config_path: str | None = None) -> dict[str, Any]:
+    """Load configuration by layering defaults, home, and project files.
+
+    An explicit ``config_path`` replaces the auto-discovered ./limn.yaml but
+    still sits on top of ~/.limn.yaml.
+    """
+    config = copy.deepcopy(DEFAULT_CONFIG)
+
+    sources: list[Path] = []
+    if home_config := find_home_config():
+        sources.append(home_config)
+    if config_path:
+        explicit = Path(config_path)
+        if not explicit.exists():
+            raise ConfigurationError(f"Configuration file not found: {config_path}")
+        sources.append(explicit)
+    elif project_config := find_project_config():
+        sources.append(project_config)
+
+    for source in sources:
+        file_config = _read_config_file(source)
+        if file_config:
+            config = merge_configs(config, file_config)
+
+    return expand_env_vars(config)
+
+
+def resolve_settings(config: dict[str, Any], provider: str) -> dict[str, Any]:
+    """Effective flat settings for one provider.
+
+    Top-level keys are the base; an entry under ``providers.<name>`` overrides
+    them, so a config can keep swarmui, gemini, ... configured side by side.
+    """
+    settings = {k: v for k, v in config.items() if k != "providers"}
+    per_provider = config.get("providers") or {}
+    override = per_provider.get(provider)
+    if isinstance(override, dict):
+        settings = merge_configs(settings, override)
+    settings["provider"] = provider
+    return settings
+
+
+EXAMPLE_CONFIG = """\
+# Limn configuration
+#
+# Layered, later wins:
+#   1. built-in defaults
+#   2. ~/.limn.yaml   (personal: provider, server URL, API keys — set once)
+#   3. ./limn.yaml    (per-directory overrides; or pass --config FILE)
+#   4. CLI flags      (e.g. --provider, --size)
+#
+# Secrets: reference environment variables as ${VAR} — no plaintext keys.
+
+provider: swarmui          # swarmui | openai-compatible | openai | gemini
+
+# Settings shared by whichever provider is active:
+size: [1024, 1024]
+# count: 1
+# seed: 42
+# negative: "text, watermark"
+
+# Per-provider settings (only the active provider's block is used, so you can
+# keep several configured and swap with `provider:` or --provider):
+providers:
+  swarmui:
+    base_url: https://image.example.org
+    model: juggernautXL_v9
+    # api_key: "${SWARMUI_TOKEN}"     # only if fronted by auth
+
+  openai-compatible:                  # LocalAI, or any /v1/images endpoint
+    base_url: http://localhost:8080/v1
+    model: sdxl
+
+  openai:                             # cloud OpenAI Images
+    model: gpt-image-1                # or dall-e-3
+    # api_key: "${OPENAI_API_KEY}"    # defaults to the env var anyway
+
+  gemini:                             # Google Imagen (~$0.02/img on Fast)
+    model: imagen-4.0-fast-generate-001
+    # api_key: "${GEMINI_API_KEY}"    # defaults to the env var anyway
+"""
+
+
+def save_example_config(path: str = "limn.yaml") -> Path:
+    """Write an example configuration file and return its path."""
+    target = Path(path)
+    if target.exists():
+        raise ConfigurationError(f"Refusing to overwrite existing {target}")
+    target.write_text(EXAMPLE_CONFIG, encoding="utf-8")
+    return target

limn/core.py

@@ -0,0 +1,111 @@
+"""Core: turn settings + prompt into image files on disk."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from limn.providers import GeneratedImage, GenerateRequest, get_provider
+
+
+def build_request(prompt: str, settings: dict[str, Any]) -> GenerateRequest:
+    """Build a provider request from resolved settings."""
+    size = settings.get("size") or [1024, 1024]
+    if isinstance(size, (list, tuple)) and len(size) == 2:
+        width, height = int(size[0]), int(size[1])
+    else:
+        raise ValueError(f"size must be [width, height], got {size!r}")
+
+    seed = settings.get("seed")
+    return GenerateRequest(
+        prompt=prompt,
+        size=(width, height),
+        count=int(settings.get("count") or 1),
+        seed=int(seed) if seed is not None else None,
+        negative=settings.get("negative") or None,
+        model=settings.get("model") or None,
+        base_url=settings.get("base_url") or None,
+        api_key=settings.get("api_key") or None,
+        timeout=float(settings.get("timeout") or 180),
+    )
+
+
+def generate(prompt: str, settings: dict[str, Any]) -> list[GeneratedImage]:
+    """Generate images for a prompt using the provider named in settings."""
+    provider_name = settings.get("provider")
+    if not provider_name:
+        raise ValueError(
+            "No provider configured. Set 'provider:' in ~/.limn.yaml "
+            "(run 'limn --init-config' for a template) or pass --provider."
+        )
+    provider = get_provider(str(provider_name))
+    return provider.generate(build_request(prompt, settings))
+
+
+def image_extension(data: bytes) -> str:
+    """File extension from magic bytes (providers return raw image blobs)."""
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return ".png"
+    if data.startswith(b"\xff\xd8"):
+        return ".jpg"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return ".webp"
+    if data[:6] in (b"GIF87a", b"GIF89a"):
+        return ".gif"
+    return ".png"
+
+
+def slugify(text: str, max_length: int = 40) -> str:
+    """Filesystem-safe slug of a prompt for default output names."""
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    slug = slug[:max_length].rstrip("-")
+    return slug or "image"
+
+
+def _unique(path: Path) -> Path:
+    """Avoid clobbering existing files by appending -2, -3, ..."""
+    if not path.exists():
+        return path
+    for i in range(2, 1000):
+        candidate = path.with_name(f"{path.stem}-{i}{path.suffix}")
+        if not candidate.exists():
+            return candidate
+    raise FileExistsError(f"Could not find a free filename near {path}")
+
+
+def save_images(
+    images: list[GeneratedImage], prompt: str, out: str | None = None
+) -> list[Path]:
+    """Write image bytes to disk and return the saved paths.
+
+    - no --out: <prompt-slug>.png in the cwd (never overwrites; -2, -3, ...)
+    - --out with one image: exactly that path
+    - --out with several: stem-1.ext, stem-2.ext, ...
+    """
+    paths: list[Path] = []
+    if out is None:
+        base = Path(slugify(prompt))
+        for image in images:
+            target = _unique(base.with_suffix(image_extension(image.data)))
+            target.write_bytes(image.data)
+            paths.append(target)
+        return paths
+
+    out_path = Path(out)
+    if out_path.parent != Path("."):
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if len(images) == 1:
+        target = out_path if out_path.suffix else out_path.with_suffix(
+            image_extension(images[0].data)
+        )
+        target.write_bytes(images[0].data)
+        return [target]
+
+    for i, image in enumerate(images, start=1):
+        suffix = out_path.suffix or image_extension(image.data)
+        target = out_path.with_name(f"{out_path.stem}-{i}{suffix}")
+        target.write_bytes(image.data)
+        paths.append(target)
+    return paths

limn/providers/__init__.py

@@ -0,0 +1,47 @@
+"""Provider registry: name -> thin image-generation client."""
+
+from __future__ import annotations
+
+from limn.providers.base import (
+    GeneratedImage,
+    GenerateRequest,
+    ImageProvider,
+    ProviderError,
+)
+from limn.providers.gemini import GeminiProvider
+from limn.providers.openai_compat import OpenAICompatibleProvider, OpenAIProvider
+from limn.providers.swarmui import SwarmUIProvider
+
+__all__ = [
+    "GeneratedImage",
+    "GenerateRequest",
+    "ImageProvider",
+    "ProviderError",
+    "PROVIDERS",
+    "get_provider",
+    "SwarmUIProvider",
+    "OpenAIProvider",
+    "OpenAICompatibleProvider",
+    "GeminiProvider",
+]
+
+PROVIDERS: dict[str, type[ImageProvider]] = {
+    "swarmui": SwarmUIProvider,
+    "openai": OpenAIProvider,
+    "dalle": OpenAIProvider,
+    "openai-compatible": OpenAICompatibleProvider,
+    "gemini": GeminiProvider,
+    "imagen": GeminiProvider,
+}
+
+
+def get_provider(name: str) -> ImageProvider:
+    """Instantiate a provider by name (aliases: dalle -> openai, imagen -> gemini)."""
+    try:
+        provider_cls = PROVIDERS[name.lower()]
+    except KeyError:
+        known = ", ".join(sorted(set(PROVIDERS)))
+        raise ProviderError(
+            f"Unknown provider '{name}'. Choose from: {known}"
+        ) from None
+    return provider_cls()

limn/providers/base.py

@@ -0,0 +1,66 @@
+"""Provider abstraction: a prompt goes in, image bytes come out.
+
+Providers are thin clients over one backend each. They raise ProviderError on
+any failure — Limn is an image tool, so it fails loudly rather than degrading
+to a placeholder.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from rich.console import Console
+
+err_console = Console(stderr=True, style="yellow")
+
+
+class ProviderError(Exception):
+    """Raised when a provider cannot generate images."""
+
+
+@dataclass
+class GenerateRequest:
+    """Everything a provider needs for one generation."""
+
+    prompt: str
+    size: tuple[int, int] = (1024, 1024)
+    count: int = 1
+    seed: int | None = None
+    negative: str | None = None
+    model: str | None = None
+    base_url: str | None = None
+    api_key: str | None = None
+    timeout: float = 180.0
+
+
+@dataclass
+class GeneratedImage:
+    """One generated image plus whatever the backend reported about it."""
+
+    data: bytes
+    seed: int | None = None
+
+
+class ImageProvider(ABC):
+    """One backend: turn a GenerateRequest into image bytes."""
+
+    name: str = "base"
+
+    @abstractmethod
+    def generate(self, request: GenerateRequest) -> list[GeneratedImage]:
+        """Generate ``request.count`` images. Raises ProviderError on failure."""
+        raise NotImplementedError
+
+    def warn_unsupported(self, request: GenerateRequest) -> None:
+        """Tell the user (stderr) about request fields this backend ignores."""
+        for label, value in self.unsupported(request):
+            if value is not None:
+                err_console.print(
+                    f"Note: provider '{self.name}' does not support "
+                    f"{label}; ignoring."
+                )
+
+    def unsupported(self, request: GenerateRequest) -> list[tuple[str, object]]:
+        """(label, value) pairs of request fields this backend ignores."""
+        return []

limn/providers/gemini.py

@@ -0,0 +1,119 @@
+"""Google Imagen provider via the Gemini API's REST predict endpoint.
+
+Plain HTTP instead of the google-genai SDK keeps Limn dependency-light.
+Imagen takes an aspect ratio rather than exact pixels, so the requested size
+is mapped to the nearest supported ratio.
+"""
+
+from __future__ import annotations
+
+import base64
+import math
+import os
+from typing import Any
+
+import requests
+
+from limn.providers.base import (
+    GeneratedImage,
+    GenerateRequest,
+    ImageProvider,
+    ProviderError,
+)
+
+GEMINI_API_URL = "https://generativelanguage.googleapis.com/v1beta"
+DEFAULT_MODEL = "imagen-4.0-fast-generate-001"
+
+# Aspect ratios the Imagen API accepts.
+ASPECT_RATIOS = {
+    "1:1": 1 / 1,
+    "4:3": 4 / 3,
+    "3:4": 3 / 4,
+    "16:9": 16 / 9,
+    "9:16": 9 / 16,
+}
+
+
+def nearest_aspect_ratio(size: tuple[int, int]) -> str:
+    """Map an exact WxH to the closest ratio Imagen supports."""
+    width, height = size
+    if width <= 0 or height <= 0:
+        raise ProviderError(f"Invalid size {width}x{height}")
+    target = width / height
+    return min(
+        ASPECT_RATIOS,
+        key=lambda name: abs(math.log(ASPECT_RATIOS[name]) - math.log(target)),
+    )
+
+
+class GeminiProvider(ImageProvider):
+    name = "gemini"
+
+    def unsupported(self, request: GenerateRequest) -> list[tuple[str, object]]:
+        # The Gemini API's Imagen endpoint accepts neither seed nor negative
+        # prompt (both are Vertex-only features).
+        return [("--seed", request.seed), ("--negative", request.negative)]
+
+    def generate(self, request: GenerateRequest) -> list[GeneratedImage]:
+        self.warn_unsupported(request)
+
+        api_key = (
+            request.api_key
+            or os.getenv("GEMINI_API_KEY")
+            or os.getenv("GOOGLE_API_KEY")
+        )
+        if not api_key:
+            raise ProviderError(
+                "Gemini needs an API key (config 'api_key', GEMINI_API_KEY, "
+                "or GOOGLE_API_KEY)."
+            )
+
+        base_url = (request.base_url or GEMINI_API_URL).rstrip("/")
+        model = request.model or DEFAULT_MODEL
+
+        payload: dict[str, Any] = {
+            "instances": [{"prompt": request.prompt}],
+            "parameters": {
+                "sampleCount": request.count,
+                "aspectRatio": nearest_aspect_ratio(request.size),
+            },
+        }
+
+        try:
+            response = requests.post(
+                f"{base_url}/models/{model}:predict",
+                json=payload,
+                headers={
+                    "x-goog-api-key": api_key,
+                    "Content-Type": "application/json",
+                },
+                timeout=request.timeout,
+            )
+            if not response.ok:
+                detail = _error_detail(response)
+                raise ProviderError(
+                    f"Imagen returned {response.status_code}: {detail}"
+                )
+            predictions = response.json().get("predictions") or []
+            images = [
+                GeneratedImage(data=base64.b64decode(p["bytesBase64Encoded"]))
+                for p in predictions
+                if p.get("bytesBase64Encoded")
+            ]
+            if not images:
+                raise ProviderError("Imagen returned no images")
+            return images
+
+        except ProviderError:
+            raise
+        except (requests.RequestException, KeyError, ValueError) as e:
+            raise ProviderError(f"Imagen error: {e}") from e
+
+
+def _error_detail(response: requests.Response) -> str:
+    """Best-effort human-readable error from a Google API response."""
+    try:
+        body = response.json()
+        return body.get("error", {}).get("message") or str(body)
+    except ValueError:
+        return response.text[:300]

limn/providers/openai_compat.py

@@ -0,0 +1,134 @@
+"""OpenAI Images providers: the real API and any compatible /v1/images endpoint.
+
+Both talk plain HTTP to ``{base_url}/images/generations`` — no SDK needed.
+``openai`` defaults base_url to the real API and requires a key;
+``openai-compatible`` requires a base_url (LocalAI, a1111 shims, ...) and
+treats the key as optional, exactly the split slide-stream uses so a stray
+OPENAI_API_KEY never silently sends prompts to the wrong server.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+
+import requests
+
+from limn.providers.base import (
+    GeneratedImage,
+    GenerateRequest,
+    ImageProvider,
+    ProviderError,
+)
+
+OPENAI_API_URL = "https://api.openai.com/v1"
+
+
+class OpenAIProvider(ImageProvider):
+    name = "openai"
+
+    default_base_url: str | None = OPENAI_API_URL
+    default_model = "gpt-image-1"
+    require_api_key = True
+
+    def unsupported(self, request: GenerateRequest) -> list[tuple[str, object]]:
+        # The /v1/images API has no seed or negative-prompt parameters.
+        return [("--seed", request.seed), ("--negative", request.negative)]
+
+    def _base_url(self, request: GenerateRequest) -> str:
+        base_url = request.base_url or self.default_base_url
+        if not base_url:
+            raise ProviderError(
+                f"Provider '{self.name}' needs a base_url (config 'base_url', "
+                f"providers.{self.name}.base_url, or OPENAI_BASE_URL)."
+            )
+        return base_url.rstrip("/")
+
+    def _api_key(self, request: GenerateRequest) -> str | None:
+        api_key = request.api_key or os.getenv("OPENAI_API_KEY")
+        if not api_key and self.require_api_key:
+            raise ProviderError(
+                "OpenAI needs an API key (config 'api_key' or OPENAI_API_KEY)."
+            )
+        return api_key
+
+    def generate(self, request: GenerateRequest) -> list[GeneratedImage]:
+        self.warn_unsupported(request)
+        base_url = self._base_url(request)
+        api_key = self._api_key(request)
+
+        headers = {"Content-Type": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+
+        width, height = request.size
+        payload = {
+            "model": request.model or self.default_model,
+            "prompt": request.prompt,
+            "n": request.count,
+            "size": f"{width}x{height}",
+        }
+
+        try:
+            response = requests.post(
+                f"{base_url}/images/generations",
+                json=payload,
+                headers=headers,
+                timeout=request.timeout,
+            )
+            if not response.ok:
+                detail = _error_detail(response)
+                raise ProviderError(
+                    f"{self.name} returned {response.status_code}: {detail}"
+                )
+            items = response.json().get("data") or []
+            if not items:
+                raise ProviderError(f"{self.name} returned no image data")
+
+            images: list[GeneratedImage] = []
+            for item in items:
+                b64 = item.get("b64_json")
+                url = item.get("url")
+                if b64:
+                    images.append(GeneratedImage(data=base64.b64decode(b64)))
+                elif url:
+                    img = requests.get(url, timeout=request.timeout)
+                    img.raise_for_status()
+                    images.append(GeneratedImage(data=img.content))
+                else:
+                    raise ProviderError(
+                        f"{self.name} returned neither b64_json nor url"
+                    )
+            return images
+
+        except ProviderError:
+            raise
+        except (requests.RequestException, ValueError) as e:
+            raise ProviderError(f"{self.name} error: {e}") from e
+
+
+class OpenAICompatibleProvider(OpenAIProvider):
+    name = "openai-compatible"
+
+    default_base_url = None  # must be configured; never default to real OpenAI
+    default_model = "stable-diffusion"
+    require_api_key = False  # local servers usually don't check
+
+    def _base_url(self, request: GenerateRequest) -> str:
+        base_url = request.base_url or os.getenv("OPENAI_BASE_URL")
+        if not base_url:
+            raise ProviderError(
+                "openai-compatible needs a base_url (config 'base_url', "
+                "providers.openai-compatible.base_url, or OPENAI_BASE_URL). "
+                "For the real OpenAI API use provider 'openai'."
+            )
+        return base_url.rstrip("/")
+
+
+def _error_detail(response: requests.Response) -> str:
+    """Best-effort human-readable error from an OpenAI-style response."""
+    try:
+        body = response.json()
+        return body.get("error", {}).get("message") or str(body)
+    except ValueError:
+        return response.text[:300]

limn/providers/swarmui.py

@@ -0,0 +1,89 @@
+"""SwarmUI native-API provider (self-hosted).
+
+SwarmUI does not speak the OpenAI /v1/images shape, so this uses its
+GetNewSession -> GenerateText2Image -> fetch-path flow. Same approach as
+slide-stream's SwarmUI provider, reduced to prompt-in / bytes-out.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import requests
+
+from limn.providers.base import (
+    GeneratedImage,
+    GenerateRequest,
+    ImageProvider,
+    ProviderError,
+)
+
+
+class SwarmUIProvider(ImageProvider):
+    name = "swarmui"
+
+    def generate(self, request: GenerateRequest) -> list[GeneratedImage]:
+        base_url = request.base_url or os.getenv("SWARMUI_BASE_URL")
+        if not base_url:
+            raise ProviderError(
+                "SwarmUI needs a base_url (config 'base_url', "
+                "providers.swarmui.base_url, or SWARMUI_BASE_URL)."
+            )
+        base_url = base_url.rstrip("/")
+
+        api_key = request.api_key or os.getenv("SWARMUI_TOKEN")
+        headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+
+        try:
+            session = requests.post(
+                f"{base_url}/API/GetNewSession",
+                json={},
+                headers=headers,
+                timeout=30,
+            )
+            session.raise_for_status()
+            session_id = session.json()["session_id"]
+
+            width, height = request.size
+            payload: dict[str, Any] = {
+                "session_id": session_id,
+                "prompt": request.prompt,
+                "images": request.count,
+                "width": width,
+                "height": height,
+            }
+            if request.model:
+                payload["model"] = request.model
+            if request.seed is not None:
+                payload["seed"] = request.seed
+            if request.negative:
+                payload["negativeprompt"] = request.negative
+
+            gen = requests.post(
+                f"{base_url}/API/GenerateText2Image",
+                json=payload,
+                headers=headers,
+                timeout=request.timeout,
+            )
+            gen.raise_for_status()
+            data = gen.json()
+            paths = data.get("images")
+            if not paths:
+                raise ProviderError(f"SwarmUI returned no images ({data})")
+
+            images: list[GeneratedImage] = []
+            for path in paths:
+                img = requests.get(
+                    f"{base_url}/{str(path).lstrip('/')}",
+                    headers=headers,
+                    timeout=request.timeout,
+                )
+                img.raise_for_status()
+                images.append(GeneratedImage(data=img.content, seed=request.seed))
+            return images
+
+        except ProviderError:
+            raise
+        except (requests.RequestException, KeyError, ValueError) as e:
+            raise ProviderError(f"SwarmUI error: {e}") from e

limn-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: limn
+Version: 0.1.0
+Summary: A small, privacy-first text-to-image tool: type a prompt, get an image. Bring your own provider.
+Project-URL: Homepage, https://github.com/michael-borck/limn
+Project-URL: Repository, https://github.com/michael-borck/limn
+Project-URL: Issues, https://github.com/michael-borck/limn/issues
+Author-email: Michael Borck <michael.borck@curtin.edu.au>
+License: MIT
+Keywords: ai,cli,dall-e,image,imagen,swarmui,text-to-image
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.110.0; extra == 'serve'
+Requires-Dist: uvicorn>=0.29.0; extra == 'serve'
+Description-Content-Type: text/markdown
+
+# 🖼️ Limn
+
+> *to **limn**: to depict or describe; to paint.*
+
+A small, privacy-first tool that turns a text description into an image. Type a
+prompt, get a picture — no account, minimal options, bring your own provider.
+
+```bash
+pip install limn
+
+limn "a red bicycle against a brick wall" -o bike.png
+```
+
+- **Type a description → get an image.** That's the whole thing.
+- **No account, private by default.** Your prompts and images are yours. The
+  only network egress is the generation request to the provider *you* chose.
+- **Bring your own provider** — self-hosted (SwarmUI / any OpenAI-compatible
+  endpoint) or a cloud key (Google Imagen, OpenAI / DALL·E). Swap with one
+  setting.
+- **Minimal by design.** Prompt, size, count, seed. Want power? Install
+  something bigger — Limn stays lean.
+
+## Quick start
+
+Pick whichever provider you already have:
+
+```bash
+# Google Imagen (cheap, ~$0.02/image on the Fast tier)
+export GEMINI_API_KEY=...
+limn "watercolour fox" --provider gemini
+
+# OpenAI Images
+export OPENAI_API_KEY=...
+limn "watercolour fox" --provider openai
+
+# Self-hosted SwarmUI
+export SWARMUI_BASE_URL=https://image.example.org
+limn "watercolour fox" --provider swarmui
+
+# Any OpenAI-compatible /v1/images endpoint (LocalAI, ...)
+export OPENAI_BASE_URL=http://localhost:8080/v1
+limn "watercolour fox" --provider openai-compatible
+```
+
+Then set your provider once so you never pass `--provider` again:
+
+```bash
+limn --init-config        # writes a commented ./limn.yaml template
+mv limn.yaml ~/.limn.yaml # personal defaults, used everywhere
+```
+
+## Usage
+
+```
+limn "a red bicycle against a brick wall" -o bike.png
+limn "watercolour fox" --provider swarmui --size 1024x1024 --count 4 --seed 42
+```
+
+| Option | What |
+|---|---|
+| `-p, --provider` | `swarmui`, `openai-compatible`, `openai`, `gemini` |
+| `-m, --model` | Model name (provider-specific) |
+| `-s, --size` | e.g. `1024x1024` (Imagen maps to the nearest aspect ratio) |
+| `-n, --count` | Number of images (1–10) |
+| `--seed` | Reproducibility, where the backend supports it (SwarmUI) |
+| `--negative` | Negative prompt, where supported (SwarmUI) |
+| `-o, --out` | Output file; default is a slug of the prompt, never overwritten |
+| `-c, --config` | Explicit config file |
+
+## Config
+
+Layered, later wins: built-in defaults → `~/.limn.yaml` (your provider + keys,
+set once) → `./limn.yaml` → CLI flags. Secrets are referenced as `${VAR}` so no
+plaintext keys live in files:
+
+```yaml
+provider: swarmui
+size: [1024, 1024]
+
+providers:            # keep several configured; swap with `provider:`
+  swarmui:
+    base_url: https://image.example.org
+    model: juggernautXL_v9
+    api_key: "${SWARMUI_TOKEN}"
+  gemini:
+    model: imagen-4.0-fast-generate-001
+```
+
+## Roadmap
+
+A **CLI** (this release), then a simple **web UI** (`limn serve`: type →
+generate → view → save / delete / regenerate), then a **Tauri desktop app**
+with bring-your-own-provider, plus a rate-limited, non-storing **demo**.
+
+📄 See **[SPEC.md](SPEC.md)** for the full specification.
+
+Companion to [slide-stream](https://github.com/michael-borck/slide-stream),
+which shares the same image-provider approach.

limn-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+limn/__init__.py,sha256=hrlI8rNm4W2cufPykhpG0q7FxNO_7L8OPKextyewWEE,81
+limn/__main__.py,sha256=20im4P-aZuvqq6zGS8qkPDPpJZpnvJK-y2Ote0tzsiE,94
+limn/cli.py,sha256=X6rVBo1rtUQD3cMGM5IaAyRMTggfjggs8IYq0578jDk,4673
+limn/config.py,sha256=Nqfpje_pSuoOj0WUyBSecvuOlGpwJxfaKTCAdOJzd0Y,6393
+limn/core.py,sha256=4RUkdiS6xlevBa8XStv-jNuNqASu8LubQTjdMaHFEbA,3891
+limn/providers/__init__.py,sha256=DJ4PNz0DxHUSna1lg0H5MJpOf1AkX97vJ4IMW2VKK1Y,1286
+limn/providers/base.py,sha256=BKD7NSjRec3qhOqfJ82T1adIek2mPsKrOqwbYGUq1ok,1938
+limn/providers/gemini.py,sha256=dx2RqpYkPZ4ubyod_fFvh3xUeWyu2DpcCFvydKQl4h8,3731
+limn/providers/openai_compat.py,sha256=OG70WsqZ114GMKVjwKaTXGkmBAZDxQNorSEGwPbacjU,4789
+limn/providers/swarmui.py,sha256=_3_KDF3d1KSoY7Vo-uZgNp_G1JO48veT3MWJ0bp-tTg,2909
+limn-0.1.0.dist-info/METADATA,sha256=951QWs68XS6PZu9bjVngTP7AbUU10rViL9HKoiDE5gA,4523
+limn-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+limn-0.1.0.dist-info/entry_points.txt,sha256=qUtzSMDWyhzuK3-npRPNuckrEs37fmY3x2qieAdiMT0,38
+limn-0.1.0.dist-info/RECORD,,

limn-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

limn-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+limn = limn.cli:app