agents.md

# Visual Lineage — Agent Instructions

## What this is
Blend FLUX.2 klein instrument LoRAs, generate hybrid instrument images with full provenance tracking, and convert to 3D meshes for printing.

Built for the Build Small hackathon (June 2026). Track: Backyard AI.

## Published Components

### HF Space (Gradio UI)
- **URL:** https://build-small-hackathon-visual-lineage.hf.space
- **SDK:** Gradio 6.x
- **GPU:** zero-a10g (ZeroGPU, 60s duration), @spaces.GPU decorator required
- **App file:** `app/app.py`
- **API endpoint:** `POST /gradio_api/call/generate`

### Published LoRAs (HF Hub under build-small-hackathon org)

| LoRA | Trigger | HF Repo | Training |
|------|---------|---------|----------|
| Eritrean krar | ERTRN_KRAR | visual-lineage-eritrean_krar_v1 | 30 images, step 1500 |
| Korean gayageum | KR_GAYAGEUM | visual-lineage-korean_gayageum_v1 | 30 images, step 2000 |
| Berimbau (capoeira) | BR_BERIMBAU | visual-lineage-berimbau_v1 | 30 images, step 2000 |

### 3D Conversion Workflows (ComfyUI)
Located in `comfy_workflows/`:
- `tripo_api_image_to_3d.json` — Tripo cloud API. LoadImage → TripoImageToModelNode → Preview3DAdvanced. **Bring your own Tripo API key.**
- `triposr_image_to_3d.json` — Local TripoSR (experimental). Requires full TripoSR VAE (encoder + decoder). Not all hardware supported.

### How to call the Gradio API
```
POST /gradio_api/call/generate
{"data": ["eritrean_krar_v1", "korean_gayageum_v1", 60, "prompt describing hybrid instrument", 42, 768]}

→ returns {"event_id": "..."}
→ poll with POST /gradio_api/call/{event_id} for SSE result
```

## Dataset Pipeline (for training new LoRAs)

1. Wikimedia harvest: `python harvest/wikimedia_harvest.py --config harvest/configs/{lora_id}.yaml --download`
2. Openverse supplement: `python harvest/openverse_harvest_generic.py --config harvest/configs/{lora_id}.yaml`
3. Build dataset: `python harvest/build_dataset.py --config harvest/configs/{lora_id}.yaml --target 30`
4. Train on Modal: `VL_LORA_ID={lora_id} VL_RUN_ID={lora_id} modal run -m train.modal_train`
5. Publish: `python train/publish_to_hf.py ...`

## Project Structure
```
visual-lineage/
├── app/app.py                 # Gradio UI with lineage panel
├── compose/
│   ├── merge.py               # FLUX + LoRA inference (24 steps, guidance 2.0)
│   └── provenance.py          # Provenance builder with recursive ancestry
├── registry/loras.json        # Published LoRA metadata
├── comfy_workflows/           # 3D conversion workflows
│   ├── tripo_api_image_to_3d.json
│   ├── triposr_image_to_3d.json
│   └── README.md
├── harvest/                   # Dataset curation
│   ├── wikimedia_harvest.py
│   ├── openverse_harvest_generic.py
│   ├── build_dataset.py
│   └── configs/
├── train/
│   ├── modal_train.py         # Modal A10G training
│   ├── publish_to_hf.py       # HF Hub publishing
│   └── configs/
├── requirements.txt
├── README.md
└── agents.md
```

## Requirements
- Python 3.11+
- Modal account + HF_TOKEN for training
- Openverse API credentials for expanded dataset sourcing
- Tripo API key for cloud-based 3D conversion
- ComfyUI Desktop for local 3D workflows