One‑sentence idea ➜ contest‑topping prompt ➜ (optional) generated media — autonomously.

Full‑resolution PNGs are in /examples, each named community‑challenge‑<id>.png.

• 🥇 Whirl Daily Art Competition – first place (“Only This and Nothing More”).
• 🥈 Whirl Discord Art Challenge – second place (“A Victorian Chrononaut”).

Whirl images live in /examples (Only this...jpeg, 2nd_A Victorian Chrononaut...png).

1. Quick Start
2. Installation   •  Configuration
3. Usage
4. Concept → Prompt Pipeline
5. Style Axes   •  Personality
6. Panels   •  Modes
7. Model Coverage
8. Ethics & Provenance
9. FAQ   •  Contributing   •  License

# 1 · Clone
git clone https://github.com/LocalSymmetry/lofn.git && cd lofn

# 2 · Create config & add API keys
cp config.yaml.example config.yaml          # then edit

# 3 · Docker (up‑to‑date CUDA & ffmpeg baked in)
docker build -t lofn .
docker run -p 8501:8501 \
  -v $(pwd)/images:/images \
  -v $(pwd)/videos:/videos \
  -v $(pwd)/music:/music \
  -v $(pwd)/metadata:/metadata \
  lofn

# 4 · Open
open http://localhost:8501

• Docker 24+ (or native Python 3.11 / Poetry if you prefer)
• GPU with 8 GB+ VRAM recommended for on‑device Stable Diffusion / video renders
• API keys for at least one text model (OpenAI, Claude, Gemini…) or a local LLM endpoint

poetry install --with=dev
export OPENAI_API_KEY=...
streamlit run app.py        # identical UI to Docker image

Only keys & endpoints live in config.yaml:

OPENAI_API_KEY:      ""
ANTHROPIC_API_KEY:   ""
GOOGLE_API_KEY:      ""    # Gemini / Imagen 3
OPEN_ROUTER_API_KEY: ""
POE_API_KEY:         ""
FAL_API_KEY:         ""    # Flux 1 / SDXL
RUNWAY_API_KEY:      ""    # Gen‑3 Alpha
DISCORD_WEBHOOK_URL: ""
LOCAL_LLM_API_BASE:  ""    # e.g. http://localhost:11434/v1
LOCAL_LLM_API_KEY:   ""
GCP_PROJECT_ID:      ""
GCP_LOCATION:        ""

LLM start-up priorities live in lofn/model_defaults.yaml. Each mode (art, video, music) defines a preferred list for concept/medium generation and for final prompt synthesis. Lofn will attempt to use the first available model from each list when a mode is selected, falling back to the built-in order if none of the preferred models are accessible. These preferred models also appear at the top of the model selectors when present.

All behavioural constants sit in lofn/constants.py (tree widths, critic weights, etc.).

1. Choose Mode (Art, Music, Video)
2. Toggle Competition (optional)
3. Generate Personality → then Select / Generate Panel
4. Enter Idea — one sentence is enough
5. Generate → Review concepts → Pick or iterate
6. Copy Prompt or let Lofn call the generator API automatically

Raw prompts, images, audio and video are auto‑saved in /images, /music, /videos, with human‑readable JSON metadata for provenance.

flowchart TD
    A[User Idea] --> B[Panel & Personality Injection]
    B --> C[Meta‑Prompt]
    C --> D[Tree‑of‑Thoughts Expansion]
    D --> E[Artist Embellishment]
    E --> F[Critic Compression]
    F --> G[Synthesis & Ranking]
    G --> H[Ethics / Provenance Filter]
    H --> I[Competition Shrink]
    I --> J[Final Prompt]
    J --> K[Optional Render]

Each node including intermediate drafts is stored in /metadata with RFC‑3339 timestamps for auditability.

Change them in the sidebar or let Lofn auto‑infer from your concept.

A thematic setting that provides a consistent creator persona that lasts between generations.

Leave empty for LLM‑generated defaults or curate for brand consistency.

Custom personas can also be loaded from lofn/prompts/custom_personalities.yaml. Copy the provided custom_personalities.yaml.example file to this location and add your own entries to have them appear in the sidebar.

Groups of 5 experts + 1 devil’s advocate simulate a live debate on every branch.

Any OpenAI‑compatible local LLM (Ollama, llama.cpp) works by setting LOCAL_LLM_API_BASE.

• OpenAI policy & Google Imagen safety filters enforced by default
• Custom block‑lists for hateful or harassing content
• Prompt hardening against copyright infringement
• All prompts and generations logged locally for transparency

1. Open an Issue — bug, feature, or prompt tweak
2. Fork → Branch (feat/xyz)
3. Code & Test (pytest, examples/cli_smoke_test.sh)
4. PR — use Conventional Commits, fill template
5. 🎉 Celebrate — we squash‑merge weekly

Apache 2.0 — free for personal & commercial use, attribution appreciated.