Upload README.md with huggingface_hub

README.md

@@ -1,13 +1,126 @@
----
-title: Synlayers
-emoji: 🚀
-colorFrom: red
-colorTo: pink
-sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.13'
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# SynLayers Demo
+
+This folder now contains a unified real-world inference demo:
+
+1. `demo/infer` runs the fixed-prompt VLM caption + bbox detector.
+2. `infer/infer.py` runs SynLayers decomposition with `infer/infer.yaml`.
+3. `demo/real_world_pipeline.py` stitches the two stages together for one uploaded image.
+4. `demo/app.py` provides a Gradio interface that can be used locally or adapted for a Hugging Face Space.
+5. `demo/upload_used_bundle_to_hf.py` uploads only the Python/config files actually used by the demo, plus the selected runtime assets.
+
+## Local Run
+
+From the `SynLayers` root:
+
+```bash
+python demo/app.py
+```
+
+Or run the unified CLI directly:
+
+```bash
+python demo/real_world_pipeline.py \
+  --image "/path/to/your/image.png"
+```
+
+## Default Models
+
+The current local defaults are:
+
+- bbox-caption model:
+  `/project/llmsvgen/share/data/kmw_layered_checkpoint/Bbox-caption-8b`
+- SynLayers base checkpoints:
+  `/project/llmsvgen/share/data/kmw_layered_checkpoint/SynLayers_checkpoints`
+- SynLayers decomposition checkpoint:
+  `/project/llmsvgen/share/data/kmw_layered_checkpoint/SynLayers_ckpt/step_120000`
+- base config:
+  `infer/infer.yaml`
+
+## Hugging Face Space Notes
+
+The Gradio app is ready for a Hugging Face Space.
+After you upload the model/runtime bundle to `SynLayers/Bbox-caption-8b`, the Space can download
+those uploaded assets automatically and use them directly.
+
+The app supports overriding the local defaults with environment variables:
+
+- `SYNLAYERS_MODEL_REPO`
+- `SYNLAYERS_BBOX_MODEL`
+- `SYNLAYERS_BASE_MODEL`
+- `SYNLAYERS_ADAPTER_MODEL`
+- `SYNLAYERS_TRANSP_VAE`
+- `SYNLAYERS_PRETRAINED_LORA`
+- `SYNLAYERS_ARTPLUS_LORA`
+- `SYNLAYERS_DECOMP_CKPT_ROOT`
+- `SYNLAYERS_REAL_CONFIG`
+- `SYNLAYERS_DEMO_WORK_DIR`
+- `SYNLAYERS_EXAMPLE_DIR`
+
+In practice, for a real Hugging Face Space deployment you will want to:
+
+1. upload the required model/runtime assets to `SynLayers/Bbox-caption-8b`
+2. create a Gradio Space repo, for example `SynLayers/synlayers-real-world-demo`
+3. upload the Space scaffold with `demo/publish_space.py`
+4. set `SYNLAYERS_MODEL_REPO=SynLayers/Bbox-caption-8b` in the Space settings
+5. launch `app.py` as the Space entrypoint
+
+### Public interface flow
+
+1. Upload the model/runtime bundle:
+
+```bash
+python demo/upload_used_bundle_to_hf.py \
+  --repo-id SynLayers/Bbox-caption-8b
+```
+
+2. Create and upload the Space scaffold:
+
+```bash
+python demo/publish_space.py \
+  --repo-id SynLayers/synlayers-real-world-demo
+```
+
+3. In the Hugging Face Space settings, add:
+
+```text
+SYNLAYERS_MODEL_REPO=SynLayers/Bbox-caption-8b
+```
+
+Then the public Space interface will:
+
+- accept a user image upload
+- load the bbox-caption model from the uploaded model repo
+- download the SynLayers decomposition assets from that same repo
+- run the one-step decomposition pipeline
+- return the bbox visualization, merged output, per-layer outputs, and a downloadable archive
+
+## Upload Bundle
+
+To upload the minimal used demo bundle to a Hugging Face repo:
+
+```bash
+python demo/upload_used_bundle_to_hf.py \
+  --repo-id SynLayers/Bbox-caption-8b
+```
+
+This uploads:
+
+- the used `demo`, `infer`, `models`, and `tools` Python files
+- `demo/upload_used_bundle_to_hf.py`
+- `demo/publish_space.py`
+- `infer/infer.yaml`
+- `environment.yml`
+- `ckpt/trans_vae/0008000.pt`
+- `ckpt/pre_trained_LoRA/pytorch_lora_weights.safetensors`
+- `ckpt/prism_ft_LoRA/pytorch_lora_weights.safetensors`
+- `SynLayers_ckpt/step_120000`
+- `SynLayers_checkpoints/FLUX.1-dev`
+- `SynLayers_checkpoints/FLUX.1-dev-Controlnet-Inpainting-Alpha`
+
+## Fixed Prompt
+
+The bbox detector always uses the fixed prompt defined in:
+
+- `demo/infer/run_caption_bbox_infer.py`
+
+No extra user text prompt is required.