Lightnote

A creative AI toolkit for working with images. Built by Page Nineteen.

Lightnote lets you analyse, generate, edit, and search images from the command line. It combines multiple AI models into one Python package with a simple CLI.

What Can It Do?

Understand Images

Analyse any image to extract colours, tags, descriptions, and visual fingerprints — all locally on your machine.

lightnote process photo.jpg
# → output/processing/photo-20260304-120000/
#   output.json: tags, description, dominant colour, 8-colour palette
#   embedding.json: visual fingerprint (for similarity search)

You can also run each step individually:

lightnote embed photo.jpg       # Visual fingerprint (CLIP embedding)
lightnote tag photo.jpg         # AI-generated tags and description
lightnote colors photo.jpg      # Dominant colour + palette

Generate Images from Text

Create images using three different AI models, each with different strengths:

# Stability Core — fast, with 17 built-in art styles
lightnote stability generate --prompt "a cat on a velvet sofa" --style cinematic

# Stable Diffusion 3 — newer model with multiple variants
lightnote stability sd3 --prompt "a cat on a velvet sofa" --model sd3-large-turbo

# Stability Ultra — highest quality output
lightnote stability ultra --prompt "a cat on a velvet sofa"

# Flux — high quality with custom style support (LoRA)
lightnote flux-generate --prompt "a watercolor landscape" --lora my_style.safetensors

# SDXL — fast local generation with 11 art styles (needs GPU)
lightnote sdxl-generate --prompt "a mountain scene" --style watercolor

Edit Images with AI

Transform, remix, and modify existing images:

# Restyle an image (image-to-image)
lightnote stability img2img --image photo.png --prompt "watercolor painting" --strength 0.7

# Generate from a sketch
lightnote stability sketch --image sketch.png --prompt "a detailed house"

# Keep the composition, change the style
lightnote stability structure --image photo.png --prompt "anime style"

# Find and replace objects
lightnote stability search-replace --image photo.png --prompt "flowers" --search "trees"

# Fill in a masked area
lightnote stability inpaint --image photo.png --mask mask.png --prompt "a garden"

# Extend an image outward
lightnote stability outpaint --image photo.png --right 200 --down 200

# Upscale to higher resolution
lightnote stability upscale --image photo.png

# Remove the background
lightnote stability remove-bg --image https://example.com/photo.png

Ask Questions About Documents

A built-in AI agent that reads your documents and answers questions:

lightnote agent --query "what is lightnote?"
lightnote agent    # interactive chat mode

Train Custom Styles

Fine-tune image generation on your own images, then generate with the result:

# Train and wait for the result
lightnote train submit --images img1.jpg img2.jpg img3.jpg --trigger "TOK" --name "my-style" --wait
# → LoRA URL: https://v3.fal.media/.../lora.safetensors

# Generate with your trained style
lightnote flux-generate --prompt "a landscape in TOK style" --lora <lora-url>

# Or submit async and check later
lightnote train submit --images img1.jpg img2.jpg img3.jpg --trigger "TOK" --name "my-style"
lightnote train status      # checks most recent job
lightnote train result      # gets most recent result

API Server

Expose processing and generation as REST endpoints:

lightnote serve                          # Start on 0.0.0.0:8000
lightnote serve --port 3000 --reload     # Custom port with auto-reload

Or use programmatically:

from lightnote.api import create_app
app = create_app()  # Returns a FastAPI instance

Quick Start

git clone https://github.com/pagenineteen/lightnote.git
cd lightnote
cp .env.example .env
# Add your API keys (see below)

make install

# Try it out
lightnote colors data/images/sample.png
lightnote agent --query "what can lightnote do?"

Installation

Lightnote uses Poetry with extras so you only install what you need:

poetry install                    # Core only
poetry install -E processing      # Image analysis (runs locally)
poetry install -E agent           # Document Q&A agent
poetry install -E stability       # Stability AI generation + editing
poetry install -E flux            # Flux generation
poetry install -E sdxl            # SDXL generation (needs GPU)
poetry install -E training        # LoRA training
poetry install -E api             # FastAPI service layer
poetry install -E all             # Everything

API Keys

Copy .env.example and add the keys you need:

Command Reference

Output

Every command that produces images saves to output/<module>/<label>-<timestamp>/:

output/stability/core-a-cat-on-a-velvet-sofa-20260304-120000/
├── generate.jpeg    # The generated image
└── output.json      # Metadata (prompt, seed, parameters)

Architecture

src/lightnote/
├── cli.py              # Unified CLI entry point
├── api/                # FastAPI service layer
├── processing/         # CLIP embeddings, Claude tagging, colour extraction
├── agent/              # Document Q&A with hybrid search
├── stability/          # Stability AI (generate, edit, control, upscale)
├── flux/               # Flux generation (FAL.ai)
├── sdxl/               # SDXL with 11 style LoRAs
└── training/           # LoRA fine-tuning (FAL.ai)

Development

poetry install --with dev
poetry run pytest tests/
poetry run ruff check src/