# CLAUDE.md — SYSTMS Action (HuggingFace Space)

## What
Image-to-image AI transformation on HuggingFace Spaces. Applies the custom SYSTMS ACTION LoRA (trained by Ingi on Qwen Image Edit 2511) to an uploaded image with a fixed prompt ("action the scene"). Same HF-hosted pattern as the INFL8 Space — different LoRA, no user-facing prompt input.

## Status
**Scaffold COMPLETE.** Ready to test. Requires:
1. `HF_TOKEN` secret set on the HF Space (read access to private repo `systms/SYSTMS-ACTION-LoRA-Qwen-Image-Edit-2511`)
2. HF Space created at `systms/ACTION-HF` (or similar — not yet deployed)

## Stack
- **Backend:** `gradio.Server` (Python) — `app.py`
- **Inference:** `QwenImageEditPlusPipeline` (local patched copy in `qwenimage/`) + 2 LoRAs:
  - `systms/SYSTMS-ACTION-LoRA-Qwen-Image-Edit-2511` → `QWEN_EDIT_ACTION_V1.safetensors` (custom, private)
  - `lightx2v/Qwen-Image-Edit-2511-Lightning` → 8-step Lightning fp32
- **GPU:** ZeroGPU via `@spaces.GPU(duration=90)`
- **Frontend:** Vanilla HTML/CSS/JS matching FLDS design system (glass panels, JetBrains Mono, #FE0000 red, before/after slider)
- **Deploy:** HuggingFace Spaces

## Key Files
| File | Purpose |
|------|---------|
| `app.py` | Gradio Server backend — action endpoint + static file serving |
| `qwenimage/` | Local patched `QwenImageEditPlusPipeline` + FA3 processor + transformer (cloned from INFL8 Space) |
| `static/index.html` | Branded frontend — upload → processing → result states |
| `static/style.css` | FLDS design system in vanilla CSS |
| `static/app.js` | Frontend logic — file handling, Gradio client, before/after slider |
| `requirements.txt` | Python deps (diffusers/accelerate/peft from git + spaces + gradio) |
| `README.md` | HF Spaces config |

## Origin Pattern
- **Inference code** adapted from the INFL8 HF Space (`systms/INFL8`) — same Qwen Image Edit 2511 base, same pipeline layout, swapped LoRA + fixed prompt.
- **Frontend** copied from `systms_upscaler_hf/` (FLDS-branded vanilla HTML/CSS/JS). INFL8 uses Gradio Blocks + SteelBlue theme — we don't.

## Running Locally (mock mode)
```bash
pip install -r requirements.txt
MOCK_MODE=true python app.py
```
Mock mode returns input unchanged after a 2s delay — useful for frontend iteration without loading the full model.

## Deploying to HF Spaces
1. Create a new HF Space (SDK: gradio, hardware: ZeroGPU)
2. Set secret `HF_TOKEN` with read access to `systms/SYSTMS-ACTION-LoRA-Qwen-Image-Edit-2511`
3. Push this folder to the Space's git remote
4. First boot will take ~5–10 min (downloading base model + LoRAs)

## Customising
- **Fixed prompt:** `FIXED_PROMPT` in `app.py` (currently `"action the scene"`)
- **Steps:** `DEFAULT_STEPS` (8 — Lightning LoRA optimised for 8 steps)
- **Guidance:** `DEFAULT_GUIDANCE` (1.0 — standard for Lightning LoRAs)
- **Output resolution:** longest edge scales to 1024, rounded to multiple of 8

## Known TODOs
- Rotate `HF_TOKEN` after initial deploy (exposed in build-session chat history)
- Replace the `SAMPLE_IMAGES/` folder (not yet created — INFL8 has one for Gradio examples; we don't need it since the frontend isn't Gradio Blocks)