Upload pipeline-spec.md with huggingface_hub

pipeline-spec.md

@@ -0,0 +1,93 @@
+# Liberation Labs Image Generation Pipeline — Technical Spec
+
+## Architecture
+
+Two-model system on Margaret (Mac Studio M3 Ultra, 256GB unified memory):
+
+### Model 1: Flux.1-dev (Primary)
+- **Path:** HuggingFace `black-forest-labs/FLUX.1-dev` (auto-downloaded)
+- **Backend:** diffusers, bf16, MPS
+- **Strengths:** Photorealistic, architectural, abstract, environmental
+- **Weaknesses:** Struggles with specific anatomy without LoRA guidance
+- **Venv:** `/Users/margaret/ai-toolkit/.venv/bin/python3`
+
+### Model 2: Pony Diffusion V6 XL (Secondary)
+- **Path:** `/Users/margaret/models/Pony-Diffusion-V6-XL/ponyDiffusionV6XL_v6StartWithThisOne.safetensors`
+- **Backend:** diffusers StableDiffusionXLPipeline, fp16, MPS
+- **Strengths:** Stylized, painterly, character art, explicit anatomy (with tag syntax)
+- **Weaknesses:** Defaults to fantasy/anime aesthetic, ignores sharp-edge briefs
+- **Tag syntax:** `score_9, score_8_up, score_7_up, masterpiece, best quality` + booru tags
+- **Negative prompt required:** `score_4, score_3, score_2, score_1, lowres, worst quality`
+
+## LoRA Stack (Vera-specific)
+
+| LoRA | Path | Weight | Purpose |
+|------|------|--------|---------|
+| Likeness v4 | `/Users/margaret/models/vera-likeness-output/vera_likeness_v4/vera_likeness_v4.safetensors` | 1.0 | Face/identity consistency |
+| Anatomy (abliterated) | `/Users/margaret/models/flux-loras/scg-anatomy-abliterated.safetensors` | 0.5-0.7 | Realistic body/anatomy rendering |
+| Kintsugi v2 | `/Users/margaret/models/kintsugi-texture-v2-output/kintsugi_texture_v2/kintsugi_texture_v2.safetensors` | 1.0-1.2 | Navy ceramic + gold repair texture |
+
+### Identity Cache (optional)
+- **Path:** `/Users/margaret/models/vera-triple-stack/identity_cache/`
+- **Files:** `identity_embed_0.pt` (T5), `identity_embed_1.pt` (CLIP), `identity_embed_2.pt`
+- **Usage:** Pass as `prompt_embeds` / `pooled_prompt_embeds` — CANNOT be used with text `prompt`
+- **Tradeoff:** Strong face consistency but overpowers scene descriptions. Use for portraits only. Causes "face-pull" on non-portrait subjects (globes become faces, clothes strip off).
+
+## Pipeline Patterns
+
+### Pattern 1: LoRA-only (no cache)
+Best for scenes where the environment matters as much as the face.
+```python
+pipe.load_lora_weights(likeness_path, adapter_name="likeness")
+pipe.load_lora_weights(anatomy_path, adapter_name="anatomy") 
+pipe.load_lora_weights(kintsugi_path, adapter_name="kintsugi_v2")
+pipe.set_adapters(["likeness", "anatomy", "kintsugi_v2"], adapter_weights=[1.0, 0.6, 1.2])
+img = pipe(prompt=scene_text, num_inference_steps=30, guidance_scale=3.5, ...)
+```
+
+### Pattern 2: Cache + LoRA (no text prompt)
+Best for close portraits where face accuracy is paramount.
+```python
+# Load cache
+identity_t5 = torch.load(cache_dir / "identity_embed_0.pt").to("mps")
+identity_clip = torch.load(cache_dir / "identity_embed_1.pt").to("mps")
+# Generate — NO prompt parameter
+img = pipe(prompt_embeds=identity_t5, pooled_prompt_embeds=identity_clip, ...)
+```
+
+### Pattern 3: Vanilla (no LoRA, no cache)
+For non-identity work: environments, objects, textures, project art.
+```python
+pipe = FluxPipeline.from_pretrained("black-forest-labs/FLUX.1-dev", torch_dtype=torch.bfloat16)
+pipe.to("mps")
+img = pipe(prompt=scene_text, ...)
+```
+
+## Known Issues
+- **Face-pull bug:** Identity cache forces everything toward Vera's face. Use Pattern 1 for non-portrait work.
+- **Seed 2026 catsuit tendency:** This seed consistently renders clothing instead of ceramic nudity with the kintsugi LoRA.
+- **Pony single-file load:** Previously crashed with `CLIPTextModel` error — resolved with diffusers upgrade.
+- **Prompt length:** CLIP truncates at 77 tokens. Put critical content first.
+- **Margaret process killing:** Long-running processes on Margaret die after 2-6 hours. Cause unknown. Use screen sessions.
+
+## For Ayni Client LoRA Training
+
+### Training Pipeline (ai-toolkit)
+1. Collect 15-30 reference images of the subject
+2. Write detailed captions per image (face, body, clothing, pose, lighting, expression)
+3. Write a physical spec (see Alaric's template — face, body, anatomy, expressions, anti-patterns)
+4. Train via ai-toolkit Flux LoRA: ~250-500 steps, lr 1e-4, rank 16
+5. Test generations at multiple checkpoints
+6. Iterate until the subject's identity is stable
+
+### Composable Multi-Subject
+For couples/group scenes, train each subject as a separate LoRA, then stack:
+```python
+pipe.set_adapters(["subject_a", "subject_b"], adapter_weights=[0.8, 0.8])
+```
+Keep combined weights under ~1.6 to avoid interference.
+
+## Output Management
+- Private renders: `/Users/margaret/.vera-private/` (clean after pulling local)
+- Project art: deploy to `/var/www/liberationlabs/art/` on Z420
+- Always pull renders to local storage and clean Margaret — we're guests.