Sync docs, sample bundle, and audit fixes

Author: apartsin

.gitignore

@@ -52,6 +52,15 @@ models/*
 node_modules/
 output/*
 !output/README.md
+!output/examples/
+output/examples/*
+!output/examples/real_e2e_example_run/
+!output/examples/real_e2e_example_run/manifest.json
+!output/examples/real_e2e_example_run/real_e2e_example_run.html
+!output/examples/real_e2e_example_run/session_trace_report.html
+!output/examples/real_e2e_example_run/images/
+!output/examples/real_e2e_example_run/images/*.png
+output/examples/real_e2e_example_run/data/
 tmp/
 temp/
 tmp_real_smoke/

README.md

@@ -59,26 +59,34 @@ The current system includes:
 - browser and backend test coverage
 - a real GPU-backed example-run generator with standalone HTML output
 
+Example artifacts checked into the repo:
+
+- [Sample HTML walkthrough](./output/examples/real_e2e_example_run/real_e2e_example_run.html)
+- [Sample trace report](./output/examples/real_e2e_example_run/session_trace_report.html)
+- [Sample manifest](./output/examples/real_e2e_example_run/manifest.json)
+
 ## User Flow
 
 The main workflow is prompt-first:
 
 1. the user opens `/setup`
 2. enters a text prompt
-3. creates a session
-4. generates a round of candidate images
-5. submits ratings or preferences
-6. waits for the async update job to finish
-7. inspects replay and the saved trace report
+3. optionally edits the per-session YAML configuration
+4. creates a session
+5. generates a round of candidate images
+6. submits explicit feedback for the active mode
+7. waits for the async update job to finish
+8. inspects replay and the saved trace report
 
 The normal runtime is GPU-only and uses the real Diffusers backend. If CUDA is unavailable, the app refuses to start instead of silently falling back.
 
+![Runtime architecture diagram](./docs/assets/illustrations/runtime_flow.svg)
+
 ## Getting Started
 
 Install the project:
 
 ```bash
-python -m pip install -e .[dev]
 python -m pip install -e .[dev,inference]
 ```
 
@@ -163,6 +171,11 @@ Real end-to-end example bundle:
 python scripts/create_real_e2e_example.py
 ```
 
+Checked-in sample bundle:
+
+- [real_e2e_example_run.html](./output/examples/real_e2e_example_run/real_e2e_example_run.html)
+- [session_trace_report.html](./output/examples/real_e2e_example_run/session_trace_report.html)
+
 ## Repo Guides
 
 Per-folder documentation is available in:
@@ -197,6 +210,10 @@ Current visual assets include:
 - [docs/assets/illustrations/steering_loop.png](./docs/assets/illustrations/steering_loop.png)
 - [docs/assets/illustrations/system_architecture.png](./docs/assets/illustrations/system_architecture.png)
 - [docs/assets/illustrations/trace_report.png](./docs/assets/illustrations/trace_report.png)
+- [docs/assets/illustrations/runtime_flow.svg](./docs/assets/illustrations/runtime_flow.svg)
+- [docs/assets/illustrations/session_lifecycle.svg](./docs/assets/illustrations/session_lifecycle.svg)
+- [docs/assets/illustrations/feedback_modes.svg](./docs/assets/illustrations/feedback_modes.svg)
+- [docs/assets/illustrations/config_to_generation.svg](./docs/assets/illustrations/config_to_generation.svg)
 
 They can be regenerated with:
 

app/README.md

@@ -37,7 +37,8 @@ This folder contains the running StableSteering application.
 ## Runtime flow
 
 1. `main.py` creates the FastAPI app and runtime services.
-2. `engine/orchestrator.py` coordinates experiment, session, round, and feedback lifecycle.
-3. `engine/generation.py` resolves the active generation backend.
-4. `storage/repository.py` persists experiments, sessions, rounds, artifacts, and trace data references.
-5. `frontend/` renders the UI, submits async jobs, shows progress, and posts browser events back to the backend.
+2. `frontend/` renders the prompt-first setup page, including the editable per-session YAML block.
+3. `engine/orchestrator.py` coordinates experiment, session, round, baseline or incumbent carry-forward, and feedback lifecycle.
+4. `engine/generation.py` resolves the active generation backend and applies the per-session generation settings.
+5. `storage/repository.py` persists experiments, sessions, rounds, artifacts, and trace data references.
+6. `frontend/` submits async jobs, shows progress, and posts browser events back to the backend.

app/core/config_yaml.py

@@ -14,10 +14,13 @@
     # Edit any of these values before creating a new session.
     # This YAML is reloaded fresh for each setup page visit or reset action.
     #
-    # sampler: random_local | exploit_orthogonal | uncertainty_guided
+    # sampler: random_local | exploit_orthogonal | uncertainty_guided | axis_sweep | incumbent_mix
     # updater: winner_average | winner_copy | linear_preference
-    # feedback_mode: scalar_rating | pairwise | top_k
+    # feedback_mode: scalar_rating | pairwise | top_k | winner_only | approve_reject
+    # seed_policy: fixed-per-round | fixed-per-candidate | fixed-per-candidate-role
     # image_size: WIDTHxHEIGHT, for example 512x512
+    # guidance_scale: classifier-free guidance strength, for example 7.5
+    # num_inference_steps: diffusion denoising steps, for example 15 or 30
     """
 )
 

app/core/jobs.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
-import asyncio
+from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime
 from enum import Enum
-from threading import Lock, Thread
+from threading import Lock
 from typing import Any, Callable
 from uuid import uuid4
 
@@ -36,17 +36,20 @@ class JobRecord(BaseModel):
 class AsyncJobManager:
     """Small in-memory async job manager for long-running user operations."""
 
-    def __init__(self) -> None:
+    def __init__(self, *, max_workers: int = 4, max_jobs: int = 200) -> None:
         self._jobs: dict[str, JobRecord] = {}
         self._lock = Lock()
+        self._executor = ThreadPoolExecutor(max_workers=max_workers, thread_name_prefix="stable-steering-job")
+        self._max_jobs = max_jobs
 
     async def submit(self, operation: str, fn: Callable[[], Any]) -> JobRecord:
         """Create a job record and execute the callable in a worker thread."""
 
         job = JobRecord(operation=operation)
         with self._lock:
+            self._prune_locked()
             self._jobs[job.id] = job
-        Thread(target=self._run_sync, args=(job.id, fn), daemon=True).start()
+        self._executor.submit(self._run_sync, job.id, fn)
         return job.model_copy(deep=True)
 
     async def get(self, job_id: str) -> JobRecord | None:
@@ -90,3 +93,18 @@ def _update(self, job_id: str, **changes: Any) -> None:
             for key, value in changes.items():
                 setattr(job, key, value)
             job.updated_at = utc_now()
+            self._prune_locked()
+
+    def _prune_locked(self) -> None:
+        """Drop old completed jobs so the in-memory registry remains bounded."""
+
+        overflow = len(self._jobs) - self._max_jobs
+        if overflow <= 0:
+            return
+        completed_ids = [
+            job.id
+            for job in sorted(self._jobs.values(), key=lambda record: (record.updated_at, record.created_at))
+            if job.state in {JobState.succeeded, JobState.failed}
+        ]
+        for job_id in completed_ids[:overflow]:
+            self._jobs.pop(job_id, None)

app/core/schema.py

@@ -59,18 +59,38 @@ class SeedPolicy(str, Enum):
     fixed_per_candidate_role = "fixed-per-candidate-role"
 
 
+class SamplerType(str, Enum):
+    random_local = "random_local"
+    exploit_orthogonal = "exploit_orthogonal"
+    uncertainty_guided = "uncertainty_guided"
+    axis_sweep = "axis_sweep"
+    incumbent_mix = "incumbent_mix"
+
+
+class UpdaterType(str, Enum):
+    winner_average = "winner_average"
+    winner_copy = "winner_copy"
+    linear_preference = "linear_preference"
+
+
+class SteeringMode(str, Enum):
+    low_dimensional = "low_dimensional"
+
+
 class StrategyConfig(BaseModel):
     """Experiment-level strategy choices and tunable parameters."""
 
-    sampler: str = "random_local"
-    updater: str = "winner_average"
+    sampler: SamplerType = SamplerType.random_local
+    updater: UpdaterType = UpdaterType.winner_average
     feedback_mode: FeedbackType = FeedbackType.scalar_rating
     seed_policy: SeedPolicy = SeedPolicy.fixed_per_round
-    steering_mode: str = "low_dimensional"
-    candidate_count: int = 5
+    steering_mode: SteeringMode = SteeringMode.low_dimensional
+    candidate_count: int = Field(default=5, ge=1, le=12)
     image_size: str = "512x512"
-    trust_radius: float = 0.35
-    anchor_strength: float = 0.15
+    trust_radius: float = Field(default=0.35, gt=0.0, le=1.0)
+    anchor_strength: float = Field(default=0.35, ge=0.0, le=2.0)
+    guidance_scale: float = Field(default=7.5, gt=0.0, le=20.0)
+    num_inference_steps: int = Field(default=15, ge=1, le=100)
     model_name: str = "runwayml/stable-diffusion-v1-5"