fix: synchronize the complete application runtime

src/compliment_forest/config.py

@@ -5,20 +5,32 @@ from pathlib import Path
 from typing import Literal
 from urllib.parse import urlparse
 
-from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator
+
+from .schema import ForestStyle
 
 
 class AppConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
-    text_backend: Literal["demo", "llama_cpp"] = "demo"
-    image_backend: Literal["demo", "flux"] = "demo"
+    text_backend: Literal["demo", "hf_inference", "llama_cpp", "transformers", "modal"] = "demo"
+    image_backend: Literal["demo", "flux", "hf_inference", "modal", "zerogpu"] = "demo"
+    music_backend: Literal["none", "modal"] = "none"
+    hf_text_model: str = "openbmb/MiniCPM4.1-8B"
+    transformers_text_model: str = "openbmb/MiniCPM4.1-8B"
+    hf_image_model: str = "black-forest-labs/FLUX.1-schnell"
     llama_base_url: str = "http://127.0.0.1:8080"
     llama_model: str = "compliment-forest-minicpm5-1b"
     flux_model_id: str = "black-forest-labs/FLUX.1-dev"
     flux_lora_id: str = "build-small-hackathon/compliment-forest-flux-lora"
+    modal_text_endpoint: str | None = None
+    modal_image_endpoint: str | None = None
+    modal_music_endpoint: str | None = None
+    modal_signing_key: SecretStr | None = None
+    upstream_space_url: str | None = None
     local_files_only: bool = False
     default_seed: int = Field(default=3407, ge=0, le=2_147_483_647)
+    default_style: ForestStyle = "surprise"
     trace_path: Path | None = None
 
     @model_validator(mode="after")
@@ -27,14 +39,54 @@ class AppConfig(BaseModel):
             hostname = urlparse(self.llama_base_url).hostname
             if hostname not in {"127.0.0.1", "localhost", "::1"}:
                 raise ValueError("llama.cpp model server must be local")
+        if self.text_backend == "modal":
+            if not self.modal_text_endpoint or not self.modal_signing_key:
+                raise ValueError("modal text backend requires endpoint credentials")
+            if urlparse(self.modal_text_endpoint).scheme != "https":
+                raise ValueError("modal text endpoint must use HTTPS")
+        if self.image_backend == "modal":
+            if not self.modal_image_endpoint or not self.modal_signing_key:
+                raise ValueError("modal image backend requires endpoint credentials")
+            if urlparse(self.modal_image_endpoint).scheme != "https":
+                raise ValueError("modal image endpoint must use HTTPS")
+        if self.music_backend == "modal":
+            if not self.modal_music_endpoint or not self.modal_signing_key:
+                raise ValueError("modal music backend requires endpoint credentials")
+            if urlparse(self.modal_music_endpoint).scheme != "https":
+                raise ValueError("modal music endpoint must use HTTPS")
+        if self.upstream_space_url:
+            parsed_upstream = urlparse(self.upstream_space_url)
+            if parsed_upstream.scheme != "https" or not parsed_upstream.netloc:
+                raise ValueError("upstream Space URL must use HTTPS")
         return self
 
     @classmethod
     def from_env(cls) -> AppConfig:
         trace_path = os.getenv("CF_TRACE_PATH")
+        hosted_space = bool(os.getenv("SPACE_ID"))
+        submission_upstream = (
+            "https://thangvip-compliment-forest.hf.space"
+            if os.getenv("SPACE_ID") == "build-small-hackathon/compliment-forest"
+            else None
+        )
+        default_text_backend = "transformers" if hosted_space else "demo"
+        default_image_backend = "zerogpu" if hosted_space else "demo"
         return cls(
-            text_backend=os.getenv("CF_TEXT_BACKEND", "demo"),
-            image_backend=os.getenv("CF_IMAGE_BACKEND", "demo"),
+            text_backend=os.getenv("CF_TEXT_BACKEND", default_text_backend),
+            image_backend=os.getenv("CF_IMAGE_BACKEND", default_image_backend),
+            music_backend=os.getenv("CF_MUSIC_BACKEND", "none"),
+            hf_text_model=os.getenv(
+                "CF_HF_TEXT_MODEL",
+                "openbmb/MiniCPM4.1-8B",
+            ),
+            transformers_text_model=os.getenv(
+                "CF_TRANSFORMERS_TEXT_MODEL",
+                "openbmb/MiniCPM4.1-8B",
+            ),
+            hf_image_model=os.getenv(
+                "CF_HF_IMAGE_MODEL",
+                "black-forest-labs/FLUX.1-schnell",
+            ),
             llama_base_url=os.getenv("CF_LLAMA_BASE_URL", "http://127.0.0.1:8080"),
             llama_model=os.getenv(
                 "CF_LLAMA_MODEL",
@@ -48,7 +100,13 @@ class AppConfig(BaseModel):
                 "CF_FLUX_LORA_ID",
                 "build-small-hackathon/compliment-forest-flux-lora",
             ),
+            modal_text_endpoint=os.getenv("CF_MODAL_TEXT_ENDPOINT"),
+            modal_image_endpoint=os.getenv("CF_MODAL_IMAGE_ENDPOINT"),
+            modal_music_endpoint=os.getenv("CF_MODAL_MUSIC_ENDPOINT"),
+            modal_signing_key=(os.getenv("CF_MODAL_SIGNING_KEY") or os.getenv("HF_TOKEN")),
+            upstream_space_url=os.getenv("CF_UPSTREAM_SPACE_URL") or submission_upstream,
             local_files_only=os.getenv("CF_LOCAL_FILES_ONLY", "0") == "1",
             default_seed=int(os.getenv("CF_DEFAULT_SEED", "3407")),
+            default_style=os.getenv("CF_DEFAULT_STYLE", "surprise"),
             trace_path=Path(trace_path) if trace_path else None,
         )

src/compliment_forest/data_builder.py

@@ -169,7 +169,21 @@ def validate_synthetic_example(example: dict[str, Any]) -> dict[str, Any] | None
 
 def build_sft_record(example: dict[str, Any]) -> dict[str, Any]:
     user_content = json.dumps(
-        {"name": example["name"], "situation": example["situation"]},
+        {
+            "name": example["name"],
+            "situation": example["situation"],
+            "validated_fact_plan": {
+                "faithful_summary": example["situation"],
+                "fact_anchors": [
+                    {
+                        "source_phrase": example["situation"],
+                        "meaning": example["situation"],
+                    }
+                ],
+                "central_uncertainty": "What will happen next",
+                "desired_direction": "Move with clarity and care",
+            },
+        },
         ensure_ascii=False,
     )
     assistant_content = json.dumps(example["forest"], ensure_ascii=False)
@@ -223,11 +237,14 @@ def template_forest(name: str, situation: str, variant: int) -> dict[str, Any]:
         CREATURES[: variant % len(CREATURES)]
     )
     selected = rotated[:5]
+    roles = ("arrive", "steady", "widen", "step", "carry")
     clearings = []
     for clearing_index, (creature, strength, spell) in enumerate(selected):
         line_template = LINE_TEMPLATES[(variant + clearing_index) % len(LINE_TEMPLATES)]
         clearings.append(
             {
+                "arc_role": roles[clearing_index],
+                "source_phrase": situation,
                 "creature": creature,
                 "strength": strength,
                 "line": line_template.format(
@@ -289,6 +306,8 @@ def forest_batch_json_schema() -> dict[str, Any]:
         "type": "object",
         "additionalProperties": False,
         "required": [
+            "arc_role",
+            "source_phrase",
             "creature",
             "strength",
             "line",
@@ -297,6 +316,8 @@ def forest_batch_json_schema() -> dict[str, Any]:
             "image_prompt",
         ],
         "properties": {
+            "arc_role": {"type": "string"},
+            "source_phrase": {"type": "string"},
             "creature": {"type": "string"},
             "strength": {"type": "string"},
             "line": {"type": "string"},
@@ -368,7 +389,9 @@ class CohereForestGenerator:
                 "clearings. Every line must repeat at least one concrete noun or phrase from "
                 "its situation. Acknowledge difficulty without diagnosis, guarantees, hollow "
                 "praise, or toxic positivity. Spells begin with 'I' and use at most 12 words. "
-                "Image prompts describe one creature only and contain no style words."
+                "Use arrive, steady, widen, step, and optional carry in order. Each "
+                "source_phrase must copy exact text from the situation. Image prompts "
+                "describe one coherent scene and contain no style words or text."
             ),
             "requests": list(requests),
             "voice_hints": list(source_hints)[:8],

src/compliment_forest/schema.py

@@ -4,15 +4,39 @@ from typing import Literal
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
+ForestStyle = Literal[
+    "surprise",
+    "watercolor",
+    "paper_cut",
+    "moonlit_gouache",
+    "botanical_ink",
+]
+ArcRole = Literal["arrive", "steady", "widen", "step", "carry"]
+
 
 class StrictModel(BaseModel):
     model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
 
 
+class FactAnchor(StrictModel):
+    source_phrase: str = Field(min_length=1, max_length=240)
+    meaning: str = Field(min_length=3, max_length=300)
+
+
+class SituationPlan(StrictModel):
+    faithful_summary: str = Field(min_length=12, max_length=500)
+    fact_anchors: list[FactAnchor] = Field(min_length=1, max_length=4)
+    central_uncertainty: str = Field(min_length=3, max_length=300)
+    desired_direction: str = Field(min_length=3, max_length=300)
+
+
 class Clearing(StrictModel):
-    creature: str = Field(min_length=3, max_length=80)
+    arc_role: ArcRole
+    source_phrase: str = Field(min_length=1, max_length=240)
+    scene_title: str = Field(min_length=3, max_length=80)
+    scene_intro: str = Field(min_length=12, max_length=240)
+    narration: str = Field(min_length=80, max_length=720)
     strength: str = Field(min_length=3, max_length=100)
-    line: str = Field(min_length=12, max_length=360)
     reflection: str = Field(min_length=12, max_length=260)
     spell: str = Field(min_length=3, max_length=80)
     image_prompt: str = Field(min_length=8, max_length=300)
@@ -27,6 +51,25 @@ class Clearing(StrictModel):
         return value
 
 
+class IntakeTurn(StrictModel):
+    question: str = Field(min_length=4, max_length=240)
+    answer: str = Field(min_length=1, max_length=240)
+
+
+class IntakeQuestion(StrictModel):
+    question: str = Field(min_length=4, max_length=240)
+    options: list[str] = Field(min_length=3, max_length=4)
+    rationale: str = Field(default="", max_length=2000)
+
+    @field_validator("options")
+    @classmethod
+    def validate_unique_options(cls, values: list[str]) -> list[str]:
+        normalized = {value.casefold() for value in values}
+        if len(normalized) != len(values):
+            raise ValueError("options must be unique")
+        return values
+
+
 class ForestDraft(StrictModel):
     forest_title: str = Field(min_length=3, max_length=120)
     proposed_strengths: list[str] = Field(min_length=3, max_length=6)
@@ -73,7 +116,14 @@ class GuardResult(StrictModel):
 
 
 class StreamEvent(StrictModel):
-    type: Literal["status", "support", "forest", "clearing", "complete", "error"]
+    type: Literal[
+        "status",
+        "support",
+        "forest",
+        "clearing",
+        "soundscape",
+        "complete",
+        "error",
+    ]
     message: str = ""
     data: dict[str, object] = Field(default_factory=dict)
-

src/compliment_forest/server.py

@@ -1,18 +1,35 @@
 from __future__ import annotations
 
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
 import gradio as gr
+import httpx
+from fastapi import HTTPException
 from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel, ConfigDict, Field
 from starlette.responses import StreamingResponse
 
-from .backends.image import DemoImageBackend, FluxImageBackend
-from .backends.text import DemoTextBackend, LlamaCppTextBackend
+from .backends.image import (
+    DemoImageBackend,
+    FluxImageBackend,
+    HfInferenceImageBackend,
+    ModalImageBackend,
+    ZeroGpuImageBackend,
+)
+from .backends.music import ModalMusicBackend, NoMusicBackend
+from .backends.text import (
+    DemoTextBackend,
+    HfInferenceTextBackend,
+    LlamaCppTextBackend,
+    ModalTextBackend,
+    TransformersTextBackend,
+)
 from .config import AppConfig
-from .orchestrator import ForestOrchestrator
+from .orchestrator import ForestOrchestrator, build_guided_situation
+from .schema import ForestStyle, IntakeQuestion, IntakeTurn, StreamEvent
 from .trace import TraceRecorder
 
 
@@ -22,18 +39,67 @@ class ForestRequest(BaseModel):
     name: str = Field(min_length=1, max_length=80)
     situation: str = Field(min_length=1, max_length=1200)
     seed: int | None = Field(default=None, ge=0, le=2_147_483_647)
+    style: ForestStyle | None = None
+    intake: list[IntakeTurn] = Field(default_factory=list, max_length=5)
 
 
-def build_orchestrator(config: AppConfig) -> ForestOrchestrator:
+class IntakeNextRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    name: str = Field(min_length=1, max_length=80)
+    situation: str = Field(min_length=1, max_length=1200)
+    history: list[IntakeTurn] = Field(default_factory=list, max_length=5)
+    seed: int | None = Field(default=None, ge=0, le=2_147_483_647)
+
+
+def build_orchestrator(
+    config: AppConfig,
+    *,
+    gpu_image_generator: Callable[[str, int, str], str] | None = None,
+    gpu_text_generator: Callable[[list[dict[str, str]], dict[str, object]], str] | None = None,
+) -> ForestOrchestrator:
     if config.text_backend == "llama_cpp":
         text_backend = LlamaCppTextBackend(
             base_url=config.llama_base_url,
             model=config.llama_model,
         )
+    elif config.text_backend == "hf_inference":
+        text_backend = HfInferenceTextBackend(model=config.hf_text_model)
+    elif config.text_backend == "transformers":
+        if gpu_text_generator is None:
+            raise ValueError("transformers text backend requires a GPU text generator")
+        text_backend = TransformersTextBackend(
+            model=config.transformers_text_model,
+            generator=gpu_text_generator,
+        )
+    elif config.text_backend == "modal":
+        assert config.modal_text_endpoint is not None
+        assert config.modal_signing_key is not None
+        text_backend = ModalTextBackend(
+            endpoint=config.modal_text_endpoint,
+            signing_key=config.modal_signing_key.get_secret_value(),
+        )
     else:
         text_backend = DemoTextBackend()
 
-    if config.image_backend == "flux":
+    if config.image_backend == "modal":
+        assert config.modal_image_endpoint is not None
+        assert config.modal_signing_key is not None
+        image_backend = ModalImageBackend(
+            endpoint=config.modal_image_endpoint,
+            signing_key=config.modal_signing_key.get_secret_value(),
+            fallback=HfInferenceImageBackend(model=config.hf_image_model),
+        )
+    elif config.image_backend == "zerogpu":
+        if gpu_image_generator is None:
+            raise ValueError("zerogpu image backend requires a GPU image generator")
+        image_backend = ZeroGpuImageBackend(
+            gpu_image_generator,
+            fallback=HfInferenceImageBackend(model=config.hf_image_model),
+        )
+    elif config.image_backend == "hf_inference":
+        image_backend = HfInferenceImageBackend(model=config.hf_image_model)
+    elif config.image_backend == "flux":
         image_backend = FluxImageBackend(
             model_id=config.flux_model_id,
             lora_id=config.flux_lora_id,
@@ -41,10 +107,21 @@ def build_orchestrator(config: AppConfig) -> ForestOrchestrator:
         )
     else:
         image_backend = DemoImageBackend()
+
+    if config.music_backend == "modal":
+        assert config.modal_music_endpoint is not None
+        assert config.modal_signing_key is not None
+        music_backend = ModalMusicBackend(
+            endpoint=config.modal_music_endpoint,
+            signing_key=config.modal_signing_key.get_secret_value(),
+        )
+    else:
+        music_backend = NoMusicBackend()
     trace_recorder = TraceRecorder(config.trace_path) if config.trace_path else None
     return ForestOrchestrator(
         text_backend=text_backend,
         image_backend=image_backend,
+        music_backend=music_backend,
         trace_recorder=trace_recorder,
     )
 
@@ -54,9 +131,24 @@ def create_app(
     config: AppConfig | None = None,
     orchestrator: Any | None = None,
     frontend_dir: str | Path | None = None,
+    gpu_image_generator: Callable[[str, int, str], str] | None = None,
+    gpu_text_generator: Callable[[list[dict[str, str]], dict[str, object]], str] | None = None,
+    upstream_client: httpx.Client | None = None,
 ) -> gr.Server:
     runtime = config or AppConfig.from_env()
-    forest = orchestrator or build_orchestrator(runtime)
+    forest = None
+    if runtime.upstream_space_url is None:
+        forest = orchestrator or build_orchestrator(
+            runtime,
+            gpu_image_generator=gpu_image_generator,
+            gpu_text_generator=gpu_text_generator,
+        )
+    proxy = upstream_client
+    if runtime.upstream_space_url and proxy is None:
+        proxy = httpx.Client(
+            timeout=httpx.Timeout(600, connect=30),
+            follow_redirects=True,
+        )
     frontend = (
         Path(frontend_dir)
         if frontend_dir is not None
@@ -69,17 +161,31 @@ def create_app(
         redoc_url=None,
     )
 
+    # Browsers will heuristically cache static files for hours when no
+    # Cache-Control header is present, and HF Spaces does not set one for
+    # FastAPI-served files. Force revalidation so each Space rebuild is
+    # immediately visible without a cache wipe on the user's side.
+    _NO_CACHE = {"Cache-Control": "no-cache, must-revalidate"}
+
     @app.get("/")
     def index() -> FileResponse:
-        return FileResponse(frontend / "index.html")
+        return FileResponse(frontend / "index.html", headers=_NO_CACHE)
 
     @app.get("/styles.css")
     def styles() -> FileResponse:
-        return FileResponse(frontend / "styles.css", media_type="text/css")
+        return FileResponse(
+            frontend / "styles.css",
+            media_type="text/css",
+            headers=_NO_CACHE,
+        )
 
     @app.get("/app.js")
     def javascript() -> FileResponse:
-        return FileResponse(frontend / "app.js", media_type="text/javascript")
+        return FileResponse(
+            frontend / "app.js",
+            media_type="text/javascript",
+            headers=_NO_CACHE,
+        )
 
     assets = frontend / "assets"
     if assets.exists():
@@ -87,20 +193,146 @@ def create_app(
 
     @app.get("/health")
     def health() -> dict[str, object]:
+        if runtime.upstream_space_url:
+            return {
+                "status": "ok",
+                "runtime_mode": "upstream_proxy",
+                "upstream_space_url": runtime.upstream_space_url,
+                "off_grid": False,
+                "fresh_images": True,
+                "default_style": runtime.default_style,
+                "model_parameter_budget_billions": 25,
+                "phase1_model_parameter_budget_billions": 18,
+            }
+        hosted = bool(
+            {"hf_inference", "modal", "zerogpu", "transformers"}
+            & {runtime.text_backend, runtime.image_backend}
+        )
+        runtime_text_model = {
+            "demo": "demo",
+            "hf_inference": runtime.hf_text_model,
+            "llama_cpp": runtime.llama_model,
+            "transformers": runtime.transformers_text_model,
+            "modal": "openbmb/MiniCPM4.1-8B (Modal)",
+        }[runtime.text_backend]
+        phase1_budget = (
+            18 if runtime.text_backend == "llama_cpp" and runtime.image_backend == "flux" else None
+        )
+        active_budget = phase1_budget
+        uses_minicpm = (
+            runtime.text_backend == "modal"
+            or (
+                runtime.text_backend == "transformers"
+                and runtime.transformers_text_model.endswith("MiniCPM4.1-8B")
+            )
+            or (
+                runtime.text_backend == "hf_inference"
+                and runtime.hf_text_model.endswith("MiniCPM4.1-8B")
+            )
+        )
+        if uses_minicpm:
+            active_budget = 25
         return {
             "status": "ok",
             "text_backend": runtime.text_backend,
+            "runtime_text_model": runtime_text_model,
             "image_backend": runtime.image_backend,
-            "off_grid": True,
-            "model_parameter_budget_billions": 18,
+            "music_backend": runtime.music_backend,
+            "off_grid": not hosted,
+            "fresh_images": runtime.image_backend != "demo",
+            "default_style": runtime.default_style,
+            "model_parameter_budget_billions": active_budget,
+            "phase1_model_parameter_budget_billions": 18,
         }
 
+    @app.post("/api/intake/next")
+    def next_intake(request: IntakeNextRequest) -> IntakeQuestion:
+        if runtime.upstream_space_url:
+            assert proxy is not None
+            try:
+                response = proxy.post(
+                    f"{runtime.upstream_space_url}/api/intake/next",
+                    json=request.model_dump(mode="json"),
+                )
+                response.raise_for_status()
+                return IntakeQuestion.model_validate(response.json())
+            except (httpx.HTTPError, ValueError) as error:
+                raise HTTPException(
+                    status_code=502,
+                    detail=f"The forest could not reach its generation service: {error}",
+                ) from error
+
+        from .safety import guard_input
+
+        assert forest is not None
+        guard = guard_input(request.name, request.situation)
+        if not guard.allowed:
+            raise HTTPException(status_code=400, detail=guard.message)
+        if len(request.history) >= 5:
+            raise HTTPException(status_code=400, detail="intake already complete")
+        seed = (request.seed if request.seed is not None else runtime.default_seed) + len(
+            request.history
+        )
+        try:
+            return forest.next_intake_question(
+                request.name,
+                request.situation,
+                request.history,
+                seed=seed,
+            )
+        except ValueError as error:
+            raise HTTPException(
+                status_code=502,
+                detail=f"The forest could not produce a question: {error}",
+            ) from error
+
     @app.post("/api/forest")
     def generate_forest(request: ForestRequest) -> StreamingResponse:
+        if runtime.upstream_space_url:
+
+            def proxy_stream():
+                assert proxy is not None
+                try:
+                    with proxy.stream(
+                        "POST",
+                        f"{runtime.upstream_space_url}/api/forest",
+                        json=request.model_dump(mode="json"),
+                    ) as response:
+                        response.raise_for_status()
+                        yield from response.iter_bytes()
+                except httpx.HTTPError as error:
+                    yield (
+                        StreamEvent(
+                            type="error",
+                            message=(
+                                "The forest could not reach its generation service: "
+                                f"{error}"
+                            ),
+                        ).model_dump_json()
+                        + "\n"
+                    )
+
+            return StreamingResponse(proxy_stream(), media_type="application/x-ndjson")
+
         def stream():
+            assert forest is not None
             seed = request.seed if request.seed is not None else runtime.default_seed
-            for event in forest.generate(request.name, request.situation, seed):
-                yield event.model_dump_json() + "\n"
+            style = request.style or runtime.default_style
+            model_situation = build_guided_situation(request.situation, request.intake)
+            try:
+                for event in forest.generate(
+                    request.name,
+                    request.situation,
+                    seed,
+                    style,
+                    model_situation=model_situation,
+                ):
+                    yield event.model_dump_json() + "\n"
+            except Exception as error:
+                yield StreamEvent(
+                    type="error",
+                    message=f"The forest could not grow: {error}",
+                ).model_dump_json() + "\n"
 
         return StreamingResponse(stream(), media_type="application/x-ndjson")
 

src/compliment_forest/style_data.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from .backends.image import STYLE_PROFILES, compose_flux_prompt
+
+SceneCategory = Literal["animal", "human", "object", "environment"]
+
+
+@dataclass(frozen=True)
+class ForestScene:
+    slug: str
+    category: SceneCategory
+    prompt: str
+
+
+FOREST_SCENES = (
+    ForestScene(
+        "fox-threshold",
+        "animal",
+        "a gentle red fox pausing at the edge of a fern-lined path",
+    ),
+    ForestScene(
+        "listening-owl",
+        "animal",
+        "a round barn owl listening from a low mossy branch",
+    ),
+    ForestScene(
+        "steady-deer",
+        "animal",
+        "a young deer standing calmly between silver birch trees",
+    ),
+    ForestScene(
+        "brave-snail",
+        "animal",
+        "a tiny snail crossing a dew-covered fern at dawn",
+    ),
+    ForestScene(
+        "singing-wren",
+        "animal",
+        "a small wren singing beside loose woodland flowers",
+    ),
+    ForestScene(
+        "river-otter",
+        "animal",
+        "a river otter holding one smooth stone beside quiet reeds",
+    ),
+    ForestScene(
+        "thoughtful-badger",
+        "animal",
+        "a thoughtful badger beside a lantern-shaped mushroom",
+    ),
+    ForestScene(
+        "patient-hare",
+        "animal",
+        "a patient brown hare resting beneath arching grasses",
+    ),
+    ForestScene(
+        "moonlit-moth",
+        "animal",
+        "a luna moth hovering near moonlit foxgloves",
+    ),
+    ForestScene(
+        "walking-turtle",
+        "animal",
+        "a small woodland turtle moving between clover and stones",
+    ),
+    ForestScene(
+        "person-open-window",
+        "human",
+        "an adult seen from behind opening a window to pale morning light",
+    ),
+    ForestScene(
+        "person-blank-notebook",
+        "human",
+        "an adult seated at a wooden desk with an open blank notebook",
+    ),
+    ForestScene(
+        "person-forked-path",
+        "human",
+        "a small human figure viewed from behind at a gentle fork in a path",
+    ),
+    ForestScene(
+        "person-train-platform",
+        "human",
+        "a quiet adult figure waiting on a misty train platform with one bag",
+    ),
+    ForestScene(
+        "person-moving-box",
+        "human",
+        "an adult carrying one moving box toward a sunlit doorway",
+    ),
+    ForestScene(
+        "person-footbridge",
+        "human",
+        "a side-view figure taking one step across a narrow wooden footbridge",
+    ),
+    ForestScene(
+        "person-doorway",
+        "human",
+        "a calm adult silhouette standing in an open doorway between two rooms",
+    ),
+    ForestScene(
+        "person-seedling",
+        "human",
+        "hands gently watering a small seedling on a windowsill",
+    ),
+    ForestScene(
+        "person-rain-shelter",
+        "human",
+        "an adult seen from the side resting on a bench beneath a rain shelter",
+    ),
+    ForestScene(
+        "person-dawn-hill",
+        "human",
+        "a distant human figure standing on a low hillside at dawn",
+    ),
+    ForestScene(
+        "lantern-crossroads",
+        "object",
+        "a small glowing lantern placed where two woodland paths meet",
+    ),
+    ForestScene(
+        "map-compass",
+        "object",
+        "an unfolded map and simple compass resting on a wooden table",
+    ),
+    ForestScene(
+        "open-notebook",
+        "object",
+        "an open blank notebook beside a pencil and one pressed leaf",
+    ),
+    ForestScene(
+        "stepping-stones",
+        "object",
+        "four smooth stepping stones crossing a narrow stream",
+    ),
+    ForestScene(
+        "warm-cup",
+        "object",
+        "a warm ceramic cup sending a thin curl of steam into morning light",
+    ),
+    ForestScene(
+        "woven-thread",
+        "object",
+        "loose green and gold threads gradually woven into one calm pattern",
+    ),
+    ForestScene(
+        "key-and-door",
+        "object",
+        "a simple brass key resting beside a small unopened wooden door",
+    ),
+    ForestScene(
+        "paper-boat",
+        "object",
+        "a single paper boat floating on still water beneath willow reflections",
+    ),
+    ForestScene(
+        "balanced-stones",
+        "object",
+        "three imperfect river stones balanced beside soft grasses",
+    ),
+    ForestScene(
+        "empty-chair-light",
+        "object",
+        "an empty wooden chair in a quiet patch of warm window light",
+    ),
+    ForestScene(
+        "winding-path",
+        "environment",
+        "a winding path disappearing gently through tall ferns and morning mist",
+    ),
+    ForestScene(
+        "river-crossing",
+        "environment",
+        "a shallow river crossing with stones visible beneath clear water",
+    ),
+    ForestScene(
+        "room-at-dawn",
+        "environment",
+        "a quiet room at dawn with curtains moving beside an open window",
+    ),
+    ForestScene(
+        "city-garden",
+        "environment",
+        "a small green garden between quiet city buildings after rain",
+    ),
+    ForestScene(
+        "misty-platform",
+        "environment",
+        "an empty train platform fading softly into early morning mist",
+    ),
+    ForestScene(
+        "clearing-after-rain",
+        "environment",
+        "a forest clearing just after rain with one bright opening in the clouds",
+    ),
+    ForestScene(
+        "hillside-trail",
+        "environment",
+        "a gradual hillside trail curving toward a pale open horizon",
+    ),
+    ForestScene(
+        "staircase-light",
+        "environment",
+        "a simple staircase with warm light falling across the next three steps",
+    ),
+    ForestScene(
+        "canopy-opening",
+        "environment",
+        "a dark green canopy opening into a circle of soft sky",
+    ),
+    ForestScene(
+        "shoreline-horizon",
+        "environment",
+        "a calm shoreline where fading clouds meet a wide quiet horizon",
+    ),
+)
+
+# Compatibility alias for callers that used the v1 name.
+FOREST_SUBJECTS = FOREST_SCENES
+
+TRAINED_STYLE_IDS = (
+    "watercolor",
+    "paper_cut",
+    "moonlit_gouache",
+    "botanical_ink",
+)
+
+
+def build_style_records(
+    *,
+    samples_per_style: int = 40,
+    base_seed: int = 9000,
+) -> list[dict[str, str | int]]:
+    if not 1 <= samples_per_style <= len(FOREST_SCENES):
+        raise ValueError(f"samples_per_style must be between 1 and {len(FOREST_SCENES)}")
+
+    records: list[dict[str, str | int]] = []
+    for style_offset, style in enumerate(TRAINED_STYLE_IDS):
+        profile = STYLE_PROFILES[style]
+        for scene_index, scene in enumerate(FOREST_SCENES[:samples_per_style]):
+            seed = base_seed + style_offset * 1000 + scene_index
+            prompt = compose_flux_prompt(
+                scene.prompt,
+                style=style,  # type: ignore[arg-type]
+                seed=seed,
+            )
+            records.append(
+                {
+                    "style": style,
+                    "trigger": profile.trigger,
+                    "category": scene.category,
+                    "subject": scene.slug,
+                    "seed": seed,
+                    "prompt": prompt,
+                    "text": (
+                        f"{profile.trigger}, {scene.prompt}, "
+                        f"{profile.label.lower()} storybook scene"
+                    ),
+                    "file_name": (
+                        f"{scene_index:03d}-{scene.category}-{scene.slug}.png"
+                    ),
+                }
+            )
+    return records

src/compliment_forest/training.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any, Protocol
+from typing import Any, Literal, Protocol
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -89,6 +89,82 @@ class FluxTrainingConfig(BaseModel):
         )
 
 
+TrainedForestStyle = Literal[
+    "watercolor",
+    "paper_cut",
+    "moonlit_gouache",
+    "botanical_ink",
+]
+
+_STYLE_TRAINING = {
+    "watercolor": {
+        "trigger": "cmprst_watercolor",
+        "repo_suffix": "watercolor",
+        "validation": "a gentle fox pausing beside ferns at dawn",
+    },
+    "paper_cut": {
+        "trigger": "cmprst_papercut",
+        "repo_suffix": "paper-cut",
+        "validation": "a thoughtful badger beside layered woodland leaves",
+    },
+    "moonlit_gouache": {
+        "trigger": "cmprst_moonlit",
+        "repo_suffix": "moonlit-gouache",
+        "validation": "a small owl resting in a moonlit pine clearing",
+    },
+    "botanical_ink": {
+        "trigger": "cmprst_inkwash",
+        "repo_suffix": "botanical-ink",
+        "validation": "a patient hare beneath sparse woodland flowers",
+    },
+}
+
+
+class FluxStyleTrainingConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    style: TrainedForestStyle
+    base_model: str = "black-forest-labs/FLUX.1-schnell"
+    dataset_id: str = "thangvip/compliment-forest-multistyle-v2"
+    dataset_config_name: str
+    model_id: str
+    trigger_token: str
+    output_dir: str
+    resolution: int = 512
+    max_train_steps: int = 300
+    train_batch_size: int = 1
+    gradient_accumulation_steps: int = 1
+    learning_rate: float = 1e-4
+    rank: int = 16
+    lora_alpha: int = 16
+    repeats: int = 3
+    seed: int = 3407
+    guidance_scale: float = 0
+    validation_prompt: str
+
+    @classmethod
+    def for_style(
+        cls,
+        style: TrainedForestStyle,
+        *,
+        smoke: bool = False,
+    ) -> FluxStyleTrainingConfig:
+        spec = _STYLE_TRAINING[style]
+        config = cls(
+            style=style,
+            dataset_config_name=style,
+            model_id=(
+                f"thangvip/compliment-forest-{spec['repo_suffix']}-flux-lora-v2"
+            ),
+            trigger_token=spec["trigger"],
+            output_dir=f"/training/compliment-forest-{spec['repo_suffix']}-flux",
+            validation_prompt=f"{spec['trigger']}, {spec['validation']}",
+        )
+        if smoke:
+            return config.model_copy(update={"max_train_steps": 2, "repeats": 1})
+        return config
+
+
 def format_training_example(
     example: dict[str, Any],
     tokenizer: ChatTemplateTokenizer,