Attune

Attune is an artist-facing style similarity app for reviewing whether generated images echo a reference portfolio. The product entry point is a polished Next.js UI on localhost:3000, backed by a Python FastAPI/CSD engine.

Current Phase

Attune now has the core production-demo loop:

• CSD embeddings through tomg-group-umd/CSD-ViT-L
• Direct style match scoring plus a context-aware second opinion
• Portfolio-level aggregation
• Reliability flags for agreement, disagreement, and weak evidence
• Patch-level heatmaps with grid, sliding, and multiscale modes
• HTML/JSON report generation
• Markdown evidence summary and downloadable ZIP evidence package
• Saved run history, storage usage, and old-run cleanup
• Full-screen side-by-side comparison
• Heatmap opacity controls
• Drag-and-drop image and folder upload
• Plain-language validation page
• Optional model selection for CSD, CLIP, and DINO-style embedding backends
• Queue-backed analysis jobs for longer runs
• Submission-ready HTML and PNG snapshot exports
• SHA-256 export hashes and an integrity manifest
• FastAPI backend and a polished Next.js local web UI
• Repeatable tests and API smoke check

The CSD model adapter is included as an optional layer. It requires torch, transformers, and Pillow, and will download tomg-group-umd/CSD-ViT-L when first used.

Quick Start

Install the optional model stack:

pip install -e .[model]

Install the local web app and smoke-test dependencies:

pip install -e .[api,dev]

Install the Next.js UI dependencies:

cd app-next
pnpm install --node-linker=hoisted
cd ..

Start the full product:

C:\Users\janar\AppData\Local\Programs\Python\Python310\python.exe scripts/run_product.py

Open the app:

http://127.0.0.1:3000

Open the built-in sample review:

http://127.0.0.1:3000/?job=ff9a6e7829fb

The launcher starts the Python API on 127.0.0.1:8001 and the Next.js UI on 127.0.0.1:3000. The Next app proxies /api and /runs to the Python engine.

Run the tests:

python scripts/run_tests.py

Run the API smoke test while the server is running:

C:\Users\janar\AppData\Local\Programs\Python\Python310\python.exe scripts/smoke_api_upload.py

Refresh the built-in sample report and evidence package after report changes:

C:\Users\janar\AppData\Local\Programs\Python\Python310\python.exe scripts/refresh_demo_artifacts.py

Compare two embedding JSON files:

python scripts/attune_cli.py compare --source examples/source_embeddings.json --target examples/target_embeddings.json --output outputs/comparison.json

Embed images with the CSD adapter, if optional dependencies are installed:

python scripts/attune_cli.py embed --images path\to\image1.png path\to\image2.jpg --output outputs/embeddings.json

Generate and compare the built-in sample images:

python scripts/generate_sample_images.py
python scripts/attune_cli.py embed --images data\sample_images\portfolio\portfolio_ink_01.png data\sample_images\portfolio\portfolio_ink_02.png --output outputs\portfolio_embeddings.json
python scripts/attune_cli.py embed --images data\sample_images\comparison\comparison_ink_like.png data\sample_images\comparison\comparison_geometric.png --output outputs\comparison_embeddings.json
python scripts/attune_cli.py compare --source outputs\portfolio_embeddings.json --target outputs\comparison_embeddings.json --output outputs\real_csd_comparison.json --model-id tomg-group-umd/CSD-ViT-L

Download and validate a balanced WikiArt subset:

C:\Users\janar\AppData\Local\Programs\Python\Python310\python.exe scripts/attune_cli.py download-wikiart --output data\validation_wikiart --artists 10 --images-per-artist 10 --shards 8
python scripts/attune_cli.py embed-folder --input data\validation_wikiart --output outputs\validation_embeddings.json
python scripts/attune_cli.py validate --embeddings outputs\validation_embeddings.json --output outputs\validation_report.json
python scripts/attune_cli.py validate-sweep --embeddings outputs\validation_embeddings.json --output outputs\validation_sweep.json --k-values 1 3 5 10 20 50

Run the full artist workflow with heatmaps and an HTML report:

python scripts/attune_cli.py analyze-portfolio --portfolio-folder data\sample_images\portfolio --comparison-folder data\sample_images\comparison --output-dir outputs\attune_demo_v2 --heatmap-mode multiscale --patch-size 224 --stride 112 --heatmaps 2 --normalization percentile --clip-percentile 95

On this Windows machine, the model dependencies are installed under Python 3.10. If plain python points at a different interpreter, use:

C:\Users\janar\AppData\Local\Programs\Python\Python310\python.exe scripts/attune_cli.py --help

Next Product Hardening

1. Add account/auth and durable multi-user storage.
2. Run CLIP/DINO-style comparison jobs on a GPU worker for faster side-by-side model sweeps.
3. Add reviewer comments and annotation layers inside reports.
4. Add signed timestamps from an external timestamping service for stronger evidence provenance.

Competition Brief

See docs/COMPETITION_FULL_BRIEF.md for the full explanation of the product, engine, workflow, reliability logic, demo, evidence package, and recommended next upgrades.