README.md

---
title: Visual Lineage
emoji: 🧬
colorFrom: green
colorTo: gray
sdk: gradio
sdk_version: 6.18.0
app_file: app/app.py
python_version: '3.11'
pinned: false
license: openrail++
tags:
  - backyard-ai
  - modal
  - flux
  - lora
  - 3d-printing
  - hackathon
  - track:backyard
  - achievement:welltuned
  - achievement:sharing
short_description: Blend FLUX.2 LoRAs, trace provenance, generate 3D meshes.
models:
  - black-forest-labs/FLUX.2-klein-4B
  - black-forest-labs/FLUX.2-klein-base-4B
datasets: []
---

# Visual Lineage

*A 23andMe for imagined instruments.*

Blend culturally-sourced instrument LoRAs trained on **FLUX.2 klein (4B)**, generate hybrid instrument images with full provenance tracking, and convert them to 3D meshes for printing.

## How it works

1. **Harvest** — We source legally-clear (CC0/CC-BY/Public domain) images of culturally specific instruments from Wikimedia Commons and Openverse.
2. **Train LoRAs** — Each instrument gets its own LoRA (350MB) trained on FLUX.2 klein via **Modal** (A10G GPU).
3. **Compose** — In this Gradio app, pick any two instruments, set a blend ratio, and describe your imagined hybrid.
4. **Prove ancestry** — Every generation shows a provenance record: which LoRAs were blended, at what weights, with what prompt and seed.
5. **Convert to 3D** — Download the image and use the included ComfyUI workflows (Tripo API / TripoSR) to generate a 3D mesh for CAD → 3D printing.

## Published LoRAs

| Instrument | Trigger | HF Hub |
|-----------|---------|--------|
| Eritrean krar (bowl lyre) | `ERTRN_KRAR` | [build-small-hackathon/visual-lineage-eritrean_krar_v1](https://huggingface.co/build-small-hackathon/visual-lineage-eritrean_krar_v1) |
| Korean gayageum (zither) | `KR_GAYAGEUM` | [build-small-hackathon/visual-lineage-korean_gayageum_v1](https://huggingface.co/build-small-hackathon/visual-lineage-korean_gayageum_v1) |
| Berimbau (capoeira bow) | `BR_BERIMBAU` | [build-small-hackathon/visual-lineage-berimbau_v1](https://huggingface.co/build-small-hackathon/visual-lineage-berimbau_v1) |

## Tech Stack

| Layer | Tool | Notes |
|-------|------|-------|
| Base model | FLUX.2 klein (4B) | Under 32B cap |
| LoRA training | [ai-toolkit](https://github.com/ostris/ai-toolkit) on **Modal** | A10G GPU, ~2h per LoRA |
| Dataset curation | Wikimedia Commons + Openverse APIs | Automated harvest pipeline |
| Inference | HF Spaces (zero-a10g) + diffusers | Live generation |
| UI | Gradio 6 | Sage/cream design |
| 3D conversion | ComfyUI + Tripo API / TripoSR | Workflows included in repo |
| Code repo | [github.com/projectmehari/visual-lineage](https://github.com/projectmehari/visual-lineage) | Private |
| Demo video | [youtu.be/N_8F6Zqfll0](https://youtu.be/N_8F6Zqfll0) | |
| Social post | [x.com/verymehari/status/2066638252161859695](https://x.com/verymehari/status/2066638252161859695?s=20) | |
| Agent instructions | `curl https://huggingface.co/spaces/build-small-hackathon/visual-lineage/raw/main/agents.md` | |

## ComfyUI 3D Workflows

Located in `comfy_workflows/` of the repo:
- `tripo_api_image_to_3d.json` — Tripo cloud API (bring your own API key)
- `triposr_image_to_3d.json` — Local TripoSR (experimental, requires full VAE)

## Build Small Hackathon

This project was built for the [Build Small](https://build-small-hackathon-field-guide.hf.space) hackathon (June 2026).

**Track:** Backyard AI — practical, problem-solving apps built to improve daily life.

**What it does:** Allows musicians, instrument makers, and tinkerers to visually explore hybrid instrument designs by blending the visual DNA of culturally significant instruments, then export those designs toward 3D printing — bridging AI generation with physical fabrication.

**Sustainability:** Each LoRA is only 350MB. The base model (FLUX.2 klein at 4B parameters) runs well on consumer GPUs. The entire pipeline from dataset harvest to training to inference uses open-source tools and runs on accessible hardware.