Creo Generator

Ad-creative generator for affiliate marketers. Swappable AI providers, Telegram delivery, web config dashboard.

Status: v0.31.0 — deployed and running in production since 2026-05-27. Web dashboard + Telegram bot + CLI all working; 100 tests green.

New to this project? Start with HANDOFF.md — setup, architecture tour, production topology, and the roadmap.

What it does

Given a brief — vertical × angle × traffic_source × geo — Creo generates ad creatives by:

1. Generating a background image (Fal.ai Flux) via a provider abstraction.
2. Generating ad copy (OpenRouter → DeepSeek-V3) primed with few-shot examples from the dataset.
3. Compositing copy onto the image per a per-traffic-source layout preset (Pillow).

Phase 1 wraps this in a Telegram bot + HTMX web dashboard. See UI_UX.md.

Architecture

Concern	Doc
Roadmap, phases, generation pipeline	PLAN.md
Provider matrix + trainability tiers	PROVIDERS.md
Dashboard + bot UX	UI_UX.md

src/creo/
  briefs/        # CreativeBrief, VisualBrief, CopyVariant — the contract
  providers/     # TextProvider/ImageProvider protocols, registry, adapters
  presets/       # LayoutTemplate + YAML loader
  examples/      # few-shot retriever over data/examples
  composition/   # PillowCompositor — overlay copy onto background
  pipeline.py    # orchestrates the hybrid pipeline
  cli.py         # `creo generate`
data/
  examples/{vertical}/{angle}/{traffic_source}/*.yml   # training data (primary IP)
  presets/*.yml

Quickstart

uv venv --python 3.12
uv pip install -e ".[dev]"
cp .env.example .env          # leave keys blank for mock mode

# Generate in mock mode (no API calls, placeholder images + copy):
creo generate --brief examples/brief.taboola.yml -n 5

# With live keys, fill .env then run the same command.

Output PNGs land in out/.

Web dashboard (Phase 1)

# Local MVP — dev-login, mock providers, SQLite. No keys or bot token needed.
CREO_MOCK=1 CREO_DEV_AUTH=1 uvicorn apps.web.main:app --reload --port 8000
# open http://localhost:8000 → "Start (dev login)" → Generate

The Telegram bot (apps/bot/bot.py) runs only when BOT_TOKEN is set — bot wiring is intentionally post-MVP. With live keys, set OPENROUTER_API_KEY + FAL_API_KEY in .env and drop CREO_MOCK.

License

UNLICENSED — Copyright (c) 2026 Sergey Dyo. All Rights Reserved. See LICENSE.md.