Upload folder using huggingface_hub

README.md

@@ -1,13 +1,48 @@
 ---
 title: Visual Lineage
-emoji: 📚
-colorFrom: yellow
+emoji: 🧬
+colorFrom: green
 colorTo: yellow
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: 5.0.0
 app_file: app.py
 pinned: false
+license: mit
+short_description: LoRA provenance for imagined instruments.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Visual Lineage
+
+*A 23andMe for imagined instruments.*
+
+Visual Lineage trains culturally specific LoRAs for niche instruments that general image models barely know, then traces every generated image back through its visual ancestry.
+
+This hackathon prototype starts with:
+
+- **LoRA:** [`eritrean_krar_v1`](https://huggingface.co/build-small-hackathon/visual-lineage-eritrean_krar_v1)
+- **Subject:** Eritrean krar / Horn of Africa bowl lyre
+- **Base inference model:** `black-forest-labs/FLUX.2-klein-4B`
+- **Training target:** `black-forest-labs/FLUX.2-klein-base-4B`
+- **Dataset:** 38 openly licensed images, with source/license manifest in the LoRA repo
+
+## What the app does
+
+1. Select one or more LoRA lineage roots.
+2. Generate an imagined instrument image with FLUX.2 klein.
+3. Show the ancestry breakdown, trigger words, Hugging Face source links, and raw provenance JSON.
+
+## Model size / Build Small compliance
+
+Every model used is below the 32B parameter cap. The live image model is FLUX.2 [klein] 4B.
+
+## Notes
+
+Live generation requires GPU and Hugging Face access to the FLUX.2 klein model. If the Space is asleep/cold, the first generation can take a while.
+
+## Demo video
+
+TODO: add demo video link.
+
+## Social post
+
+TODO: add social post link.

app.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import html
+import json
+import sys
+import traceback
+from pathlib import Path
+
+import gradio as gr
+
+ROOT = Path(__file__).resolve().parent
+sys.path.insert(0, str(ROOT))
+
+from compose.merge import compose
+from compose.provenance import provenance_sentence
+from registry import lora_choices
+
+SAGE = "#5f6f52"
+CREAM = "#f6f1e8"
+TERRACOTTA = "#b7653c"
+
+
+def render_node(node: dict, depth: int = 0) -> str:
+    margin = depth * 22
+    children = "".join(render_node(child, depth + 1) for child in node.get("children", []))
+    status = node.get("status", "unknown")
+    checkpoint = node.get("checkpoint_step") or "not selected yet"
+    cycle = "<div class='warn'>Cycle detected — recursion stopped.</div>" if node.get("cycle_detected") else ""
+    return f"""
+    <div class="lineage-card" style="margin-left:{margin}px">
+      <div class="card-top">
+        <strong>{html.escape(node.get('cultural_source') or node['lora_id'])}</strong>
+        <span class="pill">{node['weight_pct']:g}%</span>
+      </div>
+      <div class="muted">{html.escape(node['lora_id'])} · {html.escape(str(node.get('type')))} · {html.escape(str(status))}</div>
+      <div class="muted">checkpoint: {html.escape(str(checkpoint))}</div>
+      <a href="https://huggingface.co/{html.escape(node.get('hf_repo') or '')}" target="_blank">{html.escape(node.get('hf_repo') or '')}</a>
+      {cycle}
+    </div>
+    {children}
+    """
+
+
+def render_lineage(provenance: dict) -> str:
+    ancestry = provenance.get("ancestry", [])
+    bars = []
+    colors = [SAGE, TERRACOTTA, "#3f5f8f", "#9a7b33", "#72517e"]
+    for i, node in enumerate(ancestry):
+        bars.append(
+            f"<div title='{html.escape(node['lora_id'])}' style='width:{node['weight_pct']}%;background:{colors[i % len(colors)]}'>{node['weight_pct']:g}%</div>"
+        )
+    cards = "".join(render_node(node) for node in ancestry)
+    raw = html.escape(json.dumps(provenance, indent=2))
+    sentence = html.escape(provenance_sentence(provenance))
+    full_prompt = html.escape(provenance.get("full_prompt", ""))
+    model = html.escape(provenance.get("inference_model", provenance.get("base_model", "")))
+    return f"""
+    <style>
+      .vl-wrap {{ background:{CREAM}; border:1px solid #d9cfbd; border-radius:18px; padding:18px; color:#263322; }}
+      .stack {{ display:flex; height:38px; overflow:hidden; border-radius:999px; box-shadow: inset 0 0 0 1px rgba(0,0,0,.12); margin:12px 0 18px; }}
+      .stack div {{ color:white; font-weight:700; display:flex; align-items:center; justify-content:center; min-width:48px; }}
+      .lineage-card {{ background:white; border:1px solid #ddd2c0; border-radius:14px; padding:12px; margin-top:10px; }}
+      .card-top {{ display:flex; justify-content:space-between; gap:12px; }}
+      .pill {{ background:{SAGE}; color:white; padding:3px 10px; border-radius:999px; font-size:12px; }}
+      .muted {{ color:#66705f; font-size:13px; margin-top:3px; }}
+      .warn {{ color:#9b341f; font-weight:700; margin-top:6px; }}
+      details {{ margin-top:16px; }}
+      pre {{ white-space:pre-wrap; font-size:12px; background:#fff; padding:12px; border-radius:10px; }}
+    </style>
+    <div class="vl-wrap">
+      <h3>Visual lineage</h3>
+      <p>{sentence}</p>
+      <div class="muted">Model: {model}</div>
+      <div class="muted">Full prompt: {full_prompt}</div>
+      <div class="stack">{''.join(bars)}</div>
+      {cards}
+      <details><summary>Raw provenance JSON</summary><pre>{raw}</pre></details>
+    </div>
+    """
+
+
+def generate(lora_a: str, lora_b: str, blend_a: int, prompt: str, seed: int, size: int):
+    if not prompt.strip():
+        raise gr.Error("Give the image a prompt first.")
+    weight_a = blend_a / 100
+    weight_b = 1 - weight_a
+    try:
+        result = compose(
+            lora_ids=[lora_a, lora_b],
+            weights=[weight_a, weight_b],
+            prompt=prompt,
+            seed=int(seed),
+            registry_path=str(ROOT / "registry/loras.json"),
+            output_dir=str(ROOT / "outputs"),
+            width=int(size),
+            height=int(size),
+        )
+        return result["image"], render_lineage(result["provenance"])
+    except Exception as e:
+        traceback.print_exc()
+        raise gr.Error(f"Generation failed: {type(e).__name__}: {e}")
+
+
+def build_demo():
+    choices = lora_choices(ROOT / "registry/loras.json")
+    default_a = "eritrean_krar_v1" if any(v == "eritrean_krar_v1" for _, v in choices) else choices[0][1]
+    default_b = default_a
+    with gr.Blocks(title="Visual Lineage", theme=gr.themes.Soft(primary_hue="green")) as demo:
+        gr.Markdown(
+            "# Visual Lineage\n"
+            "*A 23andMe for imagined instruments.*\n\n"
+            "Live FLUX.2 [klein] inference with published LoRA provenance. "
+            "The first root node is `eritrean_krar_v1`, trained from openly licensed krar / bowl-lyre imagery."
+        )
+        with gr.Row():
+            with gr.Column(scale=1):
+                lora_a = gr.Dropdown(label="Instrument/source A", choices=choices, value=default_a)
+                lora_b = gr.Dropdown(label="Instrument/source B", choices=choices, value=default_b)
+                blend = gr.Slider(0, 100, value=100, step=1, label="Blend: A % / B %")
+                prompt = gr.Textbox(label="Describe the imagined instrument image", value="a musician holding a newly invented bowl-shaped string instrument in a small warm room", lines=3)
+                seed = gr.Number(label="Seed", value=42, precision=0)
+                size = gr.Dropdown(label="Image size", choices=[512, 768, 1024], value=768)
+                btn = gr.Button("Generate with live LoRA", variant="primary")
+            with gr.Column(scale=2):
+                output_image = gr.Image(label="Generated image", type="pil")
+                lineage_panel = gr.HTML(label="Visual lineage")
+        btn.click(generate, [lora_a, lora_b, blend, prompt, seed, size], [output_image, lineage_panel], show_progress="full")
+    return demo
+
+
+if __name__ == "__main__":
+    build_demo().launch()

compose/merge.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from compose.provenance import build_provenance, load_registry, lora_map, normalize_weights
+
+BASE_INFERENCE_MODEL = "black-forest-labs/FLUX.2-klein-4B"
+
+_PIPE = None
+_LOADED_ADAPTERS: set[str] = set()
+
+
+def _device():
+    import torch
+
+    if torch.cuda.is_available():
+        return "cuda", torch.bfloat16
+    if getattr(torch.backends, "mps", None) and torch.backends.mps.is_available():
+        return "mps", torch.float16
+    return "cpu", torch.float32
+
+
+def _load_pipe():
+    global _PIPE
+    if _PIPE is not None:
+        return _PIPE
+
+    import torch
+    from diffusers import Flux2KleinPipeline
+
+    device, dtype = _device()
+    pipe = Flux2KleinPipeline.from_pretrained(
+        BASE_INFERENCE_MODEL,
+        torch_dtype=dtype,
+        token=None,
+    )
+    pipe = pipe.to(device)
+    _PIPE = pipe
+    return pipe
+
+
+def _load_adapters(pipe, lora_ids: list[str], registry_by_id: dict[str, dict[str, Any]]) -> None:
+    for lora_id in lora_ids:
+        if lora_id in _LOADED_ADAPTERS:
+            continue
+        repo = registry_by_id[lora_id]["hf_repo"]
+        pipe.load_lora_weights(repo, adapter_name=lora_id)
+        _LOADED_ADAPTERS.add(lora_id)
+
+
+def compose(
+    lora_ids: list[str],
+    weights: list[float],
+    prompt: str,
+    registry_path: str = "registry/loras.json",
+    seed: int = 42,
+    output_dir: str = "outputs",
+    mode: str = "live",
+    width: int = 768,
+    height: int = 768,
+    num_inference_steps: int = 4,
+    guidance_scale: float = 1.0,
+) -> dict[str, Any]:
+    """Generate with FLUX.2 klein + LoRA adapters and return image/provenance.
+
+    `mode="live"` is the real path. `mode="mock"` was removed from the UI, but
+    kept as an explicit developer escape hatch only through NotImplementedError
+    so accidental demo mocks fail loudly.
+    """
+    if mode != "live":
+        raise NotImplementedError("Mock generation is disabled. Use mode='live'.")
+
+    import torch
+
+    if len(lora_ids) != len(weights):
+        raise ValueError("lora_ids and weights must be the same length")
+    if not prompt.strip():
+        raise ValueError("Prompt is required")
+
+    registry = load_registry(registry_path)
+    by_id = lora_map(registry)
+    missing = [lid for lid in lora_ids if lid not in by_id]
+    if missing:
+        raise KeyError(f"Unknown LoRA ids: {missing}")
+
+    weights = normalize_weights(weights)
+    pipe = _load_pipe()
+    _load_adapters(pipe, lora_ids, by_id)
+    pipe.set_adapters(lora_ids, adapter_weights=weights)
+
+    triggers = " ".join(by_id[lid]["trigger"] for lid in lora_ids)
+    full_prompt = f"{triggers}. {prompt.strip()}"
+
+    device, _ = _device()
+    generator = torch.Generator(device=device if device == "cuda" else "cpu").manual_seed(int(seed))
+    result = pipe(
+        prompt=full_prompt,
+        num_inference_steps=int(num_inference_steps),
+        guidance_scale=float(guidance_scale),
+        height=int(height),
+        width=int(width),
+        generator=generator,
+    )
+    image = result.images[0]
+
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+    generation_id = f"{seed}_{'_'.join(lora_ids)}"
+    output_path = Path(output_dir) / f"{generation_id}.png"
+    image.save(output_path)
+
+    provenance = build_provenance(lora_ids, weights, registry, prompt, seed, str(output_path))
+    provenance["full_prompt"] = full_prompt
+    provenance["inference_model"] = BASE_INFERENCE_MODEL
+    provenance["mode"] = "live"
+    return {"image": image, "provenance": provenance, "output_path": str(output_path)}

compose/provenance.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+BASE_MODEL = "black-forest-labs/FLUX.2-klein-base-4B"
+
+
+def load_registry(registry_path: str | Path = "registry/loras.json") -> dict[str, Any]:
+    with open(registry_path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def lora_map(registry: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    return {entry["id"]: entry for entry in registry.get("loras", [])}
+
+
+def expand_ancestry(
+    lora_id: str,
+    weight: float,
+    registry_by_id: dict[str, dict[str, Any]],
+    *,
+    max_depth: int = 8,
+    _depth: int = 0,
+    _seen: set[str] | None = None,
+) -> dict[str, Any]:
+    """Expand a LoRA node into a provenance tree.
+
+    Defaults to 8 levels: effectively complete for the hackathon, but bounded.
+    Circular references are marked instead of recursing forever.
+    """
+    seen = set() if _seen is None else set(_seen)
+    if lora_id not in registry_by_id:
+        raise KeyError(f"Unknown LoRA id: {lora_id}")
+
+    lora = registry_by_id[lora_id]
+    node = {
+        "lora_id": lora["id"],
+        "weight": round(float(weight), 4),
+        "weight_pct": round(float(weight) * 100, 2),
+        "creator": lora.get("creator"),
+        "cultural_source": lora.get("cultural_source"),
+        "hf_repo": lora.get("hf_repo"),
+        "checkpoint_step": lora.get("checkpoint_step"),
+        "type": lora.get("type"),
+        "parent_ids": lora.get("parent_ids", []),
+        "status": lora.get("status", "unknown"),
+        "children": [],
+    }
+
+    if lora_id in seen:
+        node["cycle_detected"] = True
+        return node
+    if _depth >= max_depth:
+        node["max_depth_reached"] = True
+        return node
+
+    seen.add(lora_id)
+    parent_ids = lora.get("parent_ids", [])
+    if parent_ids:
+        parent_weight = float(weight) / len(parent_ids)
+        node["children"] = [
+            expand_ancestry(
+                parent_id,
+                parent_weight,
+                registry_by_id,
+                max_depth=max_depth,
+                _depth=_depth + 1,
+                _seen=seen,
+            )
+            for parent_id in parent_ids
+            if parent_id in registry_by_id
+        ]
+    return node
+
+
+def normalize_weights(weights: list[float]) -> list[float]:
+    total = sum(weights)
+    if total <= 0:
+        raise ValueError("Blend weights must sum to a positive number")
+    return [w / total for w in weights]
+
+
+def file_sha256(path: str | Path | None) -> str | None:
+    if path is None:
+        return None
+    p = Path(path)
+    if not p.exists() or not p.is_file():
+        return None
+    h = hashlib.sha256()
+    with p.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return "sha256:" + h.hexdigest()
+
+
+def build_provenance(
+    lora_ids: list[str],
+    weights: list[float],
+    registry: dict[str, Any],
+    prompt: str,
+    seed: int,
+    output_path: str | None = None,
+    *,
+    max_depth: int = 8,
+) -> dict[str, Any]:
+    if len(lora_ids) != len(weights):
+        raise ValueError("lora_ids and weights must be the same length")
+
+    weights = normalize_weights(weights)
+    by_id = lora_map(registry)
+    ancestry = [
+        expand_ancestry(lora_id, weight, by_id, max_depth=max_depth)
+        for lora_id, weight in zip(lora_ids, weights)
+    ]
+
+    return {
+        "generation_id": str(uuid.uuid4()),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "prompt": prompt,
+        "seed": seed,
+        "base_model": BASE_MODEL,
+        "ancestry": ancestry,
+        "image_hash": file_sha256(output_path),
+        "output_path": output_path,
+    }
+
+
+def provenance_sentence(provenance: dict[str, Any]) -> str:
+    parts = [
+        f"{node['weight_pct']:g}% {node['cultural_source']}"
+        for node in provenance.get("ancestry", [])
+    ]
+    if not parts:
+        return "No lineage data available yet."
+    return "This image blends " + " and ".join(parts) + "."

registry/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def registry_path() -> Path:
+    return Path(__file__).with_name("loras.json")
+
+
+def load_registry(path: str | Path | None = None) -> dict[str, Any]:
+    p = Path(path) if path else registry_path()
+    return json.loads(p.read_text(encoding="utf-8"))
+
+
+def lora_choices(path: str | Path | None = None) -> list[tuple[str, str]]:
+    registry = load_registry(path)
+    choices = []
+    for lora in registry.get("loras", []):
+        label = f"{lora['cultural_source']} · {lora['id']} ({lora.get('status', 'unknown')})"
+        choices.append((label, lora["id"]))
+    return choices

registry/loras.json

@@ -0,0 +1,67 @@
+{
+  "loras": [
+    {
+      "id": "eritrean_krar_v1",
+      "trigger": "ERTRN_KRAR",
+      "hf_repo": "build-small-hackathon/visual-lineage-eritrean_krar_v1",
+      "checkpoint_step": 1500,
+      "type": "instrument",
+      "cultural_source": "Eritrean krar / Horn of Africa bowl lyre",
+      "creator": "projectmehari",
+      "parent_ids": [],
+      "status": "published",
+      "sensitivity": {
+        "requires_review": false
+      },
+      "local_artifact": "train/output/eritrean_krar_v1_fresh_20260614-111947/eritrean_krar_v1/eritrean_krar_v1.safetensors",
+      "sample_review": "Only valid generated samples downloaded for steps 1250/1500; final selected provisionally due deadline."
+    },
+    {
+      "id": "eritrean_heritage_v1",
+      "trigger": "ERTRN_HRTG",
+      "hf_repo": "projectmehari/visual-lineage-eritrean_heritage_v1",
+      "checkpoint_step": null,
+      "type": "heritage",
+      "cultural_source": "Eritrean visual heritage",
+      "creator": "projectmehari",
+      "parent_ids": [],
+      "status": "planned"
+    },
+    {
+      "id": "mtl_514_v1",
+      "trigger": "MTL_514",
+      "hf_repo": "projectmehari/visual-lineage-mtl_514_v1",
+      "checkpoint_step": null,
+      "type": "meme",
+      "cultural_source": "Montr\u00e9al 514 street culture",
+      "creator": "projectmehari",
+      "parent_ids": [],
+      "status": "planned"
+    },
+    {
+      "id": "knicks_in_4_v1",
+      "trigger": "KNKS_N4",
+      "hf_repo": "projectmehari/visual-lineage-knicks_in_4_v1",
+      "checkpoint_step": null,
+      "type": "meme",
+      "cultural_source": "Knicks playoff fan culture",
+      "creator": "projectmehari",
+      "parent_ids": [],
+      "status": "planned"
+    },
+    {
+      "id": "habesha_diaspora_v1",
+      "trigger": "HBSH_DSPR",
+      "hf_repo": "projectmehari/visual-lineage-habesha_diaspora_v1",
+      "checkpoint_step": null,
+      "type": "heritage",
+      "cultural_source": "Habesha diaspora visual culture",
+      "creator": "projectmehari",
+      "parent_ids": [],
+      "status": "planned",
+      "sensitivity": {
+        "requires_review": true
+      }
+    }
+  ]
+}

requirements.txt

@@ -0,0 +1,14 @@
+gradio>=5.0
+pydantic>=2.0
+PyYAML>=6.0
+Pillow>=10.0
+requests>=2.31
+huggingface_hub>=0.26
+peft>=0.14
+accelerate>=1.0
+torch
+diffusers @ git+https://github.com/huggingface/diffusers.git
+transformers
+sentencepiece
+protobuf
+safetensors