Refresh sample bundle and tighten config runtime behavior

Author: apartsin

app/core/config_yaml.py

@@ -18,10 +18,15 @@
     # updater: winner_average | winner_copy | linear_preference
     # feedback_mode: scalar_rating | pairwise | top_k | winner_only | approve_reject
     # seed_policy: fixed-per-round | fixed-per-candidate | fixed-per-candidate-role
+    # steering_mode: currently low_dimensional
     # steering_dimension: low-dimensional steering vector size, for example 3 or 5
+    # candidate_count: visible candidates per round
     # image_size: WIDTHxHEIGHT, for example 512x512
+    # trust_radius: steering search radius around the current state
+    # anchor_strength: strength of the steering offset applied to prompt embeddings
     # guidance_scale: classifier-free guidance strength, for example 7.5
     # num_inference_steps: diffusion denoising steps, for example 15 or 30
+    # model_name: prepared local model id or Hugging Face model id
     """
 )
 

app/engine/generation.py

@@ -6,7 +6,7 @@
 
 from app.bootstrap.huggingface import model_slug
 from app.core.config import settings
-from app.core.schema import Candidate, Session
+from app.core.schema import Candidate, Session, SteeringMode
 
 
 def _color_from_candidate(candidate: Candidate) -> tuple[str, str]:
@@ -30,6 +30,15 @@ def parse_image_size(value: str) -> tuple[int, int]:
         raise ValueError(f"Invalid image size: {value!r}. Expected format WIDTHxHEIGHT.") from exc
 
 
+def resolve_steering_mode(session: Session) -> SteeringMode:
+    """Resolve and validate the session steering mode used at generation time."""
+
+    mode = session.config.steering_mode
+    if mode == SteeringMode.low_dimensional:
+        return mode
+    raise ValueError(f"Unsupported steering mode: {mode}")
+
+
 class GenerationEngine(Protocol):
     """Protocol shared by generation backends used by the orchestrator."""
 
@@ -55,6 +64,7 @@ def __init__(self, artifacts_dir: Path | None = None) -> None:
     def render_candidate(self, session: Session, candidate: Candidate) -> Candidate:
         """Render one candidate to an SVG artifact and attach its public path."""
 
+        steering_mode = resolve_steering_mode(session)
         primary, secondary = _color_from_candidate(candidate)
         width, height = parse_image_size(session.config.image_size)
         path = self.artifacts_dir / f"{candidate.id}.svg"
@@ -77,6 +87,7 @@ def render_candidate(self, session: Session, candidate: Candidate) -> Candidate:
 <text x="40" y="330" fill="white" font-size="18" font-family="Arial">CFG: {session.config.guidance_scale:.2f}</text>
 <text x="40" y="365" fill="white" font-size="18" font-family="Arial">Steps: {session.config.num_inference_steps}</text>
 <text x="40" y="400" fill="white" font-size="18" font-family="Arial">Anchor strength: {session.config.anchor_strength:.2f}</text>
+<text x="40" y="435" fill="white" font-size="18" font-family="Arial">Steering mode: {escape(steering_mode.value)}</text>
 </svg>"""
         path.write_text(svg, encoding="utf-8")
         candidate.image_path = f"/artifacts/{path.name}"
@@ -88,6 +99,7 @@ def render_candidate(self, session: Session, candidate: Candidate) -> Candidate:
                 "num_inference_steps": session.config.num_inference_steps,
                 "model_source": session.config.model_name,
                 "anchor_strength": session.config.anchor_strength,
+                "steering_mode": steering_mode.value,
             }
         )
         return candidate
@@ -265,6 +277,7 @@ def _steering_offset(self, prompt_embeds, z, anchor_strength: float):
     def _encode_steered_embeddings(self, session: Session, candidate: Candidate):
         """Encode prompt text, then apply a deterministic steering offset."""
 
+        steering_mode = resolve_steering_mode(session)
         pipe = self._load_pipeline(self._resolve_model_source(session))
         prompt_embeds, negative_prompt_embeds = pipe.encode_prompt(
             prompt=session.prompt,
@@ -273,7 +286,14 @@ def _encode_steered_embeddings(self, session: Session, candidate: Candidate):
             do_classifier_free_guidance=True,
             negative_prompt=session.negative_prompt or "",
         )
-        steered_prompt_embeds = prompt_embeds + self._steering_offset(prompt_embeds, candidate.z, session.config.anchor_strength)
+        if steering_mode == SteeringMode.low_dimensional:
+            steered_prompt_embeds = prompt_embeds + self._steering_offset(
+                prompt_embeds,
+                candidate.z,
+                session.config.anchor_strength,
+            )
+        else:
+            raise ValueError(f"Unsupported steering mode: {steering_mode}")
         return steered_prompt_embeds, negative_prompt_embeds
 
     def render_candidate(self, session: Session, candidate: Candidate) -> Candidate:
@@ -309,7 +329,7 @@ def render_candidate(self, session: Session, candidate: Candidate) -> Candidate:
                 "num_inference_steps": num_inference_steps,
                 "model_source": model_source,
                 "anchor_strength": session.config.anchor_strength,
-                "steering_mode": session.config.steering_mode,
+                "steering_mode": resolve_steering_mode(session).value,
             }
         )
         return candidate

app/engine/orchestrator.py

@@ -465,6 +465,16 @@ def _widen_first_round_candidates(session: Session, proposed_candidates: list[Ca
         boost_radius = min(max(session.config.trust_radius * 1.55, 0.34), 0.72)
         min_radius = min(max(session.config.trust_radius * 0.95, 0.24), boost_radius)
         for index, candidate in enumerate(proposed_candidates):
+            if candidate.sampler_role == "exploit":
+                exploit_radius = min(max(session.config.trust_radius * 0.35, 0.12), 0.24)
+                boosted_z = clamp_vector(list(candidate.z), exploit_radius)
+                candidate.z = boosted_z
+                candidate.generation_params["first_round_diversity_boost"] = True
+                candidate.generation_params["first_round_diversity_scale"] = 0.6
+                candidate.generation_params["first_round_role_behavior"] = "keep_exploit_close"
+                boosted_candidates.append(candidate)
+                continue
+
             spread_direction = Orchestrator._first_round_spread_direction(index, dimensions)
             scale = 1.15 + (0.1 * index)
             blended = [

app/frontend/templates/setup.html

@@ -47,7 +47,7 @@ <h1>Start from your text prompt</h1>
             <input name="description" value="Initial real generation workflow">
           </label>
           <label>
-            <span class="field-label">Session configuration (YAML) <span class="help-tip" tabindex="0" role="note" aria-label="YAML configuration help" data-tooltip="This YAML controls sampler, updater, feedback mode, seeds, candidate count, and generation settings for this one session.">?</span></span>
+            <span class="field-label">Session configuration (YAML) <span class="help-tip" tabindex="0" role="note" aria-label="YAML configuration help" data-tooltip="This YAML controls sampler, updater, feedback mode, seeds, candidate count, and generation settings for this one session.">?</span> <a href="https://apartsinprojects.github.io/StableSteering/docs/configuration_manual.html" target="_blank" rel="noopener noreferrer">Open configuration manual</a></span>
             <textarea name="config_yaml" id="config-yaml-editor" class="yaml-editor" spellcheck="false">{{ config_yaml }}</textarea>
           </label>
           <p class="hint">All per-session strategy values live in this YAML document. Edit it before creating a session, or reload the default template.</p>

app/samplers/random_local.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import math
+
 from app.core.schema import Candidate, Session
 from app.samplers.base import clamp_vector, make_rng
 
@@ -14,22 +16,74 @@ def propose(self, session: Session, seed: int) -> list[Candidate]:
 
         rng = make_rng(seed)
         candidates = []
+        dimensions = max(1, len(session.current_z))
+        exploit_radius = min(session.config.trust_radius * 0.28, 0.18)
+        explore_radius = min(max(session.config.trust_radius * 0.9, 0.28), session.config.trust_radius)
         for index in range(session.config.candidate_count):
-            offset = [rng.uniform(-0.35, 0.35) for _ in session.current_z]
-            z = clamp_vector(
-                [current + delta for current, delta in zip(session.current_z, offset, strict=False)],
-                session.config.trust_radius,
-            )
+            if index == 0:
+                role = "exploit"
+                offset = [rng.uniform(-0.12, 0.12) for _ in session.current_z]
+                z = clamp_vector(
+                    [current + delta for current, delta in zip(session.current_z, offset, strict=False)],
+                    exploit_radius,
+                )
+            else:
+                role = "explore"
+                direction = self._explore_direction(index - 1, dimensions)
+                jitter = [rng.uniform(-0.08, 0.08) for _ in session.current_z]
+                target_radius = min(explore_radius, max(explore_radius * (0.82 + (0.06 * ((index - 1) % 3))), 0.24))
+                z = clamp_vector(
+                    [
+                        current + (axis * target_radius) + noise
+                        for current, axis, noise in zip(session.current_z, direction, jitter, strict=False)
+                    ],
+                    session.config.trust_radius,
+                )
+                length = math.sqrt(sum(value * value for value in z))
+                minimum_radius = min(max(session.config.trust_radius * 0.58, 0.22), session.config.trust_radius)
+                if 0.0 < length < minimum_radius:
+                    z = clamp_vector([value * (minimum_radius / length) for value in z], session.config.trust_radius)
+
             candidates.append(
                 Candidate(
                     round_id="",
                     candidate_index=index,
                     z=z,
-                    sampler_role="explore" if index else "exploit",
+                    sampler_role=role,
                     predicted_score=sum(z),
                     predicted_uncertainty=max(0.05, 0.3 - (0.03 * index)),
                     seed=seed,
-                    generation_params={"image_size": session.config.image_size},
+                    generation_params={
+                        "image_size": session.config.image_size,
+                        "proposal_role_radius": exploit_radius if role == "exploit" else explore_radius,
+                    },
                 )
             )
         return candidates
+
+    @staticmethod
+    def _explore_direction(index: int, dimensions: int) -> list[float]:
+        """Return a separated exploratory direction for one candidate slot."""
+
+        vector = [0.0 for _ in range(dimensions)]
+        primary_axis = index % dimensions
+        secondary_axis = (index + 1) % dimensions
+        tertiary_axis = (index + 2) % dimensions
+        primary_sign = 1.0 if index % 2 == 0 else -1.0
+        secondary_sign = -1.0 if index % 3 == 1 else 1.0
+        tertiary_sign = -1.0 if index % 4 >= 2 else 1.0
+
+        vector[primary_axis] = 1.0 * primary_sign
+        if dimensions > 1:
+            vector[secondary_axis] += 0.45 * secondary_sign
+        if dimensions > 2:
+            vector[tertiary_axis] += 0.22 * tertiary_sign
+        if dimensions > 3:
+            extra_axis = (index + 3) % dimensions
+            vector[extra_axis] += 0.16 if index % 2 == 0 else -0.16
+
+        length = math.sqrt(sum(value * value for value in vector))
+        if length == 0.0:
+            vector[0] = 1.0
+            return vector
+        return [value / length for value in vector]