limn 0.1.0__tar.gz

limn-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Config / secrets
+limn.yaml
+.env
+
+# Generated images / scratch
+outputs/
+*.png
+*.jpg
+*.jpeg
+*.webp
+!docs/**/*.png
+
+# macOS
+.DS_Store
+._*
+
+# Editors
+.vscode/
+.idea/

limn-0.1.0/CLAUDE.md

@@ -0,0 +1,70 @@
+# Limn — agent handover / working notes
+
+This file is auto-loaded when you open a Claude Code session in this repo. It
+tells you what Limn is, where things stand, and how to start. **`SPEC.md` is the
+source of truth** — read it before writing any code.
+
+## What Limn is
+
+A small, privacy-first **text-to-image** tool: type a prompt, get an image. No
+account, minimal options, bring your own provider. Surfaces (in order): a CLI, a
+simple web UI (generate / view / save / delete / regenerate), then a Tauri
+desktop app with bring-your-own-provider, plus a rate-limited, non-storing demo.
+
+## Current status
+
+**M1 (CLI) built and published to PyPI as `limn` 0.1.0.** The package lives in
+`src/limn/`: `config.py` (layered ~/.limn.yaml < ./limn.yaml < flags, `${VAR}`
+expansion, per-provider `providers:` overlays), `providers/` (swarmui,
+openai, openai-compatible, gemini/imagen — all plain `requests`, no SDKs),
+`core.py` (generate + save with slug naming / no-overwrite), `cli.py` (Typer,
+single command). Tests in `tests/` (45, all green), basedpyright zero errors,
+ruff clean. Verified end-to-end against the real Imagen API.
+
+Design choices made during M1 (beyond SPEC):
+- Providers raise `ProviderError` and the CLI exits non-zero — **no** silent
+  text-image fallback like slide-stream (that only makes sense in a video
+  pipeline).
+- `openai`/`dalle` and `openai-compatible` share one class; the compatible
+  variant *requires* `base_url` so a stray OPENAI_API_KEY never sends prompts
+  to the wrong server.
+- Imagen (Gemini API) gets nearest-aspect-ratio mapping from `--size`;
+  seed/negative are warn-and-ignore on backends that lack them (OpenAI,
+  Gemini API).
+
+## Machine gotcha (this repo lives on an exFAT drive)
+
+`uv sync` with a local `.venv` fails here: macOS writes AppleDouble `._*`
+files (SIP-protected `com.apple.provenance` xattr) into binary wheels (ruff,
+basedpyright) and uv's RECORD validation rejects them. Workaround used:
+
+```bash
+export UV_PROJECT_ENVIRONMENT="$HOME/.venvs/limn"   # venv on internal disk
+uv sync --all-groups
+uv run --no-sync ruff check src tests && uv run --no-sync basedpyright && uv run --no-sync pytest
+```
+
+## Next milestones
+
+M2 (web UI, `limn serve` behind a `[serve]` extra, like `slide-stream serve`),
+M3 (hosted demo), M4 (Tauri desktop). Release flow: bump version in
+`pyproject.toml` + `src/limn/__init__.py`, `uv build`, `twine upload dist/*`.
+
+## Key decisions already made
+
+- **Standalone**, not a slide-stream dependency (slide-stream is a video tool).
+  Reuse the *pattern*, not the package. Extract a shared image-providers lib
+  later only if it clearly pays off.
+- **Generative providers only** (Limn *makes* images) — no Pexels/Unsplash stock
+  unless the user asks.
+- **Minimal knobs** on purpose: prompt, size, count, seed. Advanced params live
+  in the provider. Don't add options without a reason.
+- **Privacy-first:** no account, no telemetry, no server-side storage of prompts
+  or images; the demo is rate-limited and ephemeral.
+
+## Reference
+
+- Companion project: `../slide-stream` (on this machine) —
+  https://github.com/michael-borck/slide-stream, published on PyPI. Its image
+  providers, layered config, and `serve` web UI are the templates to adapt.
+- Repo: https://github.com/michael-borck/limn (public).

limn-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,98 @@
+# 🖼️ 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/SPEC.md

@@ -0,0 +1,152 @@
+# Limn — specification
+
+> *to **limn** (verb): 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.
+
+---
+
+## 1. Vision
+
+Most image tools are either a single locked-in web app (an account, your data on
+their servers) or a full studio (ComfyUI/SwarmUI — powerful but heavy). **Limn
+sits deliberately in between:** the simplest possible "text → image" surface,
+that you own.
+
+- **Type a description → get an image.** That's the whole interaction.
+- **No account, no lock-in, privacy by default.** Your prompts and images are
+  yours. On the desktop, nothing leaves your machine except the generation
+  request to *your* chosen provider.
+- **Bring your own provider.** Point Limn at a self-hosted server (SwarmUI /
+  any OpenAI-compatible endpoint) or a cloud key (Google Imagen, OpenAI /
+  DALL·E). Swap it with one setting.
+- **Minimal by design.** A handful of knobs (prompt, size, count, seed). If you
+  want inpainting, ControlNet, and node graphs, install something bigger —
+  Limn stays lean.
+
+Think "Black Forest Labs playground, but standalone, private, and yours."
+
+## 2. Principles
+
+1. **Simple beats powerful.** One prompt in, one image out. Advanced parameters
+   live in the provider, not in Limn.
+2. **Local-first & private.** No account, no telemetry, no server-side storage
+   of prompts or images (desktop is fully local). The hosted demo is
+   rate-limited and stores nothing.
+3. **Provider-agnostic.** The same thin provider abstraction as `slide-stream`'s
+   image layer — self-hosted or cloud, chosen by config.
+4. **Progressive surfaces.** The same core powers a CLI, a web UI, and a desktop
+   app; each is optional.
+
+## 3. Surfaces (roadmap)
+
+### v1 — CLI
+```
+limn "a red bicycle against a brick wall" -o bike.png
+limn "watercolour fox" --provider swarmui --size 1024x1024 --count 4 --seed 42
+```
+Options: `--provider`, `--model`, `--size`, `--count`, `--seed`, `--negative`,
+`--out`. Provider selection + API keys from a config file and/or environment
+variables. Prints the saved path(s).
+
+### v2 — Web UI (`limn serve`)
+A single page: type a prompt → **Generate** → the image appears in-app →
+**Save** (to disk), **Delete** (from the session gallery), or **Generate
+another**. A running gallery of the session's images (prompt, thumbnail, seed).
+FastAPI + a self-contained HTML page (same shape as `slide-stream serve`).
+Local-first (binds `127.0.0.1`, auto-opens the browser); optional token when
+hosted.
+
+### v3 — Desktop (Tauri + Python sidecar)
+A native, installable app. Users set **their own image provider** in Settings
+(server URL or API key). Images are saved locally; the app stores nothing
+remotely. Tauri (Rust) shell wrapping the Python core as a sidecar, with the
+runtime bootstrapped on first run via `uv` (thin installer, not a 1GB bundle) —
+the pattern explored for slide-stream. Not on the Mac App Store (runtime
+download rules); distributed as a signed `.dmg` / installer.
+
+### Demo — "try before install"
+A hosted instance (`app.limn.<domain>`) that is **rate-limited and
+non-storing**: generate a few images to try it, nothing saved server-side, with
+a banner inviting users to install locally for full control and privacy. Same
+`--demo` flag idea as slide-stream.
+
+## 4. Providers (v1 set)
+
+Generative backends only (Limn *makes* images; it is not a stock-photo
+browser):
+
+| Provider | What | Config |
+|---|---|---|
+| `swarmui` | Self-hosted SwarmUI native API | `base_url`, `model`, optional Bearer `api_key` |
+| `openai-compatible` | Any `/v1/images` endpoint (LocalAI, …) | `base_url`, `model`, `api_key` |
+| `openai` / `dalle` | OpenAI Images (DALL·E) | `OPENAI_API_KEY`, `model` |
+| `gemini` / `imagen` | Google Imagen (cheap, ~$0.02/img) | `GEMINI_API_KEY`, `model` |
+| `local` *(later)* | Bundled local diffusion (optional heavy extra) | — |
+
+Each provider is a thin client: prompt (+ size/count/seed/negative) → image
+bytes. Modeled on `slide-stream`'s image providers, but **standalone** — Limn
+does not depend on slide-stream (a video tool). If code-sharing becomes
+worthwhile, extract a small shared `image-providers` library later.
+
+## 5. Architecture
+
+```
+limn/                      Python package
+  providers/               thin per-backend clients (swarmui, openai, gemini, …)
+  core.py                  generate(prompt, opts) -> image bytes / files
+  config.py                layered config (~/.limn.yaml + ./limn.yaml + env)
+  cli.py                   Typer CLI
+  serve.py                 FastAPI web UI (optional [serve] extra)
+desktop/                   Tauri shell + Python sidecar (later)
+```
+
+- **Python 3.10+**, `typer`, `requests`/`httpx`, `pillow`.
+- **Web:** `fastapi` + `uvicorn` behind a `[serve]` extra.
+- **Desktop:** Tauri (Rust) + Python sidecar, `uv`-bootstrapped runtime.
+- **Packaging:** `uv` / hatchling; publish to PyPI (`pip install limn`).
+
+## 6. Config
+
+Layered, later wins (mirrors slide-stream): built-in defaults →
+`~/.limn.yaml` (your provider + keys, set once) → `./limn.yaml` → CLI flags.
+Secrets referenced as `${VAR}` so no plaintext keys in files.
+
+```yaml
+provider: swarmui
+base_url: https://image.example.org
+model: juggernautXL_v9
+api_key: "${SWARMUI_TOKEN}"
+size: [1024, 1024]
+```
+
+## 7. Privacy & governance
+
+- **No account. No telemetry.** Nothing is required to run it.
+- **No server-side storage** of prompts or images. Desktop = fully local;
+  the demo is ephemeral and rate-limited.
+- **Your provider, your data.** The only network egress is the generation
+  request to the provider *you* configured.
+- Clear, short docs on what leaves the machine and when.
+
+## 8. Non-goals
+
+- Not a full editing studio (no inpainting / ControlNet / node graphs — use
+  ComfyUI/SwarmUI).
+- Not a model host — Limn calls a provider you point it at.
+- Not a prompt-engineering IDE — minimal knobs on purpose.
+
+## 9. Milestones
+
+1. **M1 — CLI:** `limn "prompt" -o out.png`, provider layer (swarmui + one
+   cloud), layered config. Publish to PyPI.
+2. **M2 — Web UI:** `limn serve` with generate / view / save / delete /
+   regenerate + session gallery.
+3. **M3 — Demo:** hosted, rate-limited, non-storing instance + landing page.
+4. **M4 — Desktop:** Tauri app with BYO-provider settings, local saves.
+
+---
+
+*Companion project to [slide-stream](https://github.com/michael-borck/slide-stream),
+which shares the same image-provider approach.*

limn-0.1.0/pyproject.toml

@@ -0,0 +1,119 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "limn"
+version = "0.1.0"
+description = "A small, privacy-first text-to-image tool: type a prompt, get an image. Bring your own provider."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Michael Borck", email = "michael.borck@curtin.edu.au" },
+]
+keywords = ["ai", "image", "text-to-image", "cli", "swarmui", "imagen", "dall-e"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "requests>=2.31.0",
+    "pyyaml>=6.0.0",
+]
+
+[project.optional-dependencies]
+# Web UI (limn serve) — M2
+serve = [
+    "fastapi>=0.110.0",
+    "uvicorn>=0.29.0",
+]
+
+[project.scripts]
+limn = "limn.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/michael-borck/limn"
+Repository = "https://github.com/michael-borck/limn"
+Issues = "https://github.com/michael-borck/limn/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/limn"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "UP", # pyupgrade
+]
+ignore = [
+    "E501",  # line too long
+    "B008",  # function calls in argument defaults (Typer idiom)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["limn"]
+
+[tool.basedpyright]
+include = ["src", "tests"]
+exclude = ["**/__pycache__", "**/._*"]
+venvPath = "."
+venv = ".venv"
+pythonVersion = "3.10"
+pythonPlatform = "All"
+typeCheckingMode = "basic"
+reportMissingImports = true
+reportMissingTypeStubs = false
+reportUnusedImport = true
+reportUnusedClass = true
+reportUnusedFunction = true
+reportUnusedVariable = true
+reportDuplicateImport = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "--cov=limn",
+    "--cov-report=term-missing",
+]
+
+[tool.coverage.run]
+source = ["limn"]
+branch = true
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.29.4",
+    "build>=1.2.2",
+    "pytest>=8.4.0",
+    "pytest-cov>=6.0.0",
+    "pytest-mock>=3.14.0",
+    "ruff>=0.12.0",
+    "twine>=6.1.0",
+]

limn-0.1.0/src/limn/__init__.py

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

limn-0.1.0/src/limn/__main__.py

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