Add advanced steering docs and seed policies

Author: apartsin

RELEASE.md

@@ -15,7 +15,7 @@ A release should include:
 
 Current release notes:
 
-- [RELEASE_NOTES_v0.1.0.md](E:\Projects\StableSteering\RELEASE_NOTES_v0.1.0.md)
+- [RELEASE_NOTES_v0.1.0.md](RELEASE_NOTES_v0.1.0.md)
 
 ## Release Checklist
 
@@ -31,10 +31,10 @@ Current release notes:
 6. Rebuild the documentation site:
    `python scripts/build_pages_site.py`
 7. Review:
-   - [INSTALL.md](E:\Projects\StableSteering\INSTALL.md)
-   - [README.md](E:\Projects\StableSteering\README.md)
-   - [docs/student_tutorial.md](E:\Projects\StableSteering\docs\student_tutorial.md)
-   - [RELEASE_NOTES_v0.1.0.md](E:\Projects\StableSteering\RELEASE_NOTES_v0.1.0.md)
+   - [INSTALL.md](INSTALL.md)
+   - [README.md](README.md)
+   - [docs/student_tutorial.md](docs/student_tutorial.md)
+   - [RELEASE_NOTES_v0.1.0.md](RELEASE_NOTES_v0.1.0.md)
 8. Build a source zip if needed:
    `powershell -ExecutionPolicy Bypass -File scripts/build_release_zip.ps1 -Version v0.1.0`
 9. Create the Git tag.

RELEASE_NOTES_v0.1.0.md

@@ -22,13 +22,13 @@ Published HTML documentation:
 
 ## Included Documentation
 
-- [README.md](E:\Projects\StableSteering\README.md)
-- [INSTALL.md](E:\Projects\StableSteering\INSTALL.md)
-- [RELEASE.md](E:\Projects\StableSteering\RELEASE.md)
-- [student_tutorial.md](E:\Projects\StableSteering\docs\student_tutorial.md)
-- [quick_start.md](E:\Projects\StableSteering\docs\quick_start.md)
-- [developer_guide.md](E:\Projects\StableSteering\docs\developer_guide.md)
-- [user_guide.md](E:\Projects\StableSteering\docs\user_guide.md)
+- [README.md](README.md)
+- [INSTALL.md](INSTALL.md)
+- [RELEASE.md](RELEASE.md)
+- [student_tutorial.md](docs/student_tutorial.md)
+- [quick_start.md](docs/quick_start.md)
+- [developer_guide.md](docs/developer_guide.md)
+- [user_guide.md](docs/user_guide.md)
 
 ## Validation Snapshot
 

RELEASE_NOTES_v0.1.1.md

@@ -0,0 +1,61 @@
+# Release Notes v0.1.1
+
+## Summary
+
+This release expands the research MVP into a more configurable and inspectable system.
+
+Major themes in this release:
+
+- richer sampling and preference-mode support
+- stronger per-session YAML configuration
+- better runtime trace reporting and portable HTML artifacts
+- improved docs-site linking and roadmap detail
+- real seed-policy behavior in the orchestration layer
+
+## Highlights
+
+### Sampling and preference updates
+
+- added `axis_sweep` and `incumbent_mix` samplers
+- added `winner_only` and `approve_reject` feedback modes
+- documented the current sampler and preference-model behavior more clearly
+
+### Session and orchestration updates
+
+- first round always includes the unmodified prompt baseline
+- later rounds carry forward the previous winner as the incumbent
+- default candidate count is now `5`
+- implemented seed policies:
+  - `fixed-per-round`
+  - `fixed-per-candidate`
+  - `fixed-per-candidate-role`
+
+### Reporting and examples
+
+- improved HTML session trace reporting
+- ensured initial prompt visibility in generated HTML reports
+- regenerated the real end-to-end sample bundle
+- added a configuration-matrix sample generator
+
+### Documentation and publishing
+
+- fixed broken Markdown links that pointed at machine-local paths
+- regenerated the GitHub Pages site with corrected document and code links
+- expanded the roadmap docs with:
+  - why each item matters
+  - implementation notes
+  - success signals
+
+## Verification
+
+Validated before release with:
+
+- `python -m pytest -q`
+- `npm run test:e2e:chrome`
+- `python scripts/build_pages_site.py`
+
+## Known limitations
+
+- `multi-seed averaging` is still specified in docs but not yet implemented
+- mode-specific frontend controls are still incomplete for some preference modes
+- the real-backend Playwright smoke remains opt-in

app/core/schema.py

@@ -49,6 +49,14 @@ class FeedbackType(str, Enum):
     scalar_rating = "scalar_rating"
     pairwise = "pairwise"
     top_k = "top_k"
+    winner_only = "winner_only"
+    approve_reject = "approve_reject"
+
+
+class SeedPolicy(str, Enum):
+    fixed_per_round = "fixed-per-round"
+    fixed_per_candidate = "fixed-per-candidate"
+    fixed_per_candidate_role = "fixed-per-candidate-role"
 
 
 class StrategyConfig(BaseModel):
@@ -57,7 +65,7 @@ class StrategyConfig(BaseModel):
     sampler: str = "random_local"
     updater: str = "winner_average"
     feedback_mode: FeedbackType = FeedbackType.scalar_rating
-    seed_policy: str = "fixed-per-round"
+    seed_policy: SeedPolicy = SeedPolicy.fixed_per_round
     steering_mode: str = "low_dimensional"
     candidate_count: int = 5
     image_size: str = "512x512"

app/core/tracing.py

@@ -201,6 +201,7 @@ def _render_session_report(
             '  <details class="card section" open>',
             "    <summary>Run Summary</summary>",
             '    <div class="card-body">',
+            f"    <p><strong>Initial prompt:</strong> {self._escape(session.get('prompt') or '(none)')}</p>",
             f"    <p><strong>Negative prompt:</strong> {self._escape(session.get('negative_prompt') or '(none)')}</p>",
             f"    <p><strong>Model:</strong> <code>{self._escape(session.get('model_name', 'unknown'))}</code></p>",
             f"    <p><strong>Feedback mode:</strong> <code>{self._escape(str(session.get('config', {}).get('feedback_mode', 'unknown')))}</code></p>",

app/engine/orchestrator.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from copy import deepcopy
+import hashlib
 import math
 
 from app.core.config import settings
@@ -14,6 +15,7 @@
     RenderStatus,
     Round,
     RoundResponse,
+    SeedPolicy,
     Session,
     SessionCreate,
     SessionStatus,
@@ -22,8 +24,10 @@
 from app.core.logging import logger
 from app.core.tracing import TraceRecorder
 from app.feedback.normalization import normalize_feedback
+from app.samplers.axis_sweep import AxisSweepSampler
 from app.samplers.base import clamp_vector
 from app.samplers.exploit_orthogonal import ExploitOrthogonalSampler
+from app.samplers.incumbent_mix import IncumbentMixSampler
 from app.samplers.random_local import RandomLocalSampler
 from app.samplers.uncertainty import UncertaintyGuidedSampler
 from app.storage.repository import JsonRepository
@@ -49,6 +53,8 @@ def __init__(
             "random_local": RandomLocalSampler(),
             "exploit_orthogonal": ExploitOrthogonalSampler(),
             "uncertainty_guided": UncertaintyGuidedSampler(),
+            "axis_sweep": AxisSweepSampler(),
+            "incumbent_mix": IncumbentMixSampler(),
         }
         self.updaters = {
             "winner_copy": WinnerCopyUpdater(),
@@ -123,7 +129,6 @@ def generate_round(self, session_id: str) -> RoundResponse:
         session = self._require_session(session_id)
         if session.status == SessionStatus.awaiting_feedback:
             raise RuntimeError("Cannot generate a new round while feedback for the current round is still pending")
-        seed = 1000 + session.current_round
         sampler = self.samplers[session.config.sampler]
         round_index = session.current_round + 1
         round_obj = Round(
@@ -140,21 +145,22 @@ def generate_round(self, session_id: str) -> RoundResponse:
         )
         carried_forward = self._build_carried_forward_candidate(session)
         baseline_candidate = self._build_baseline_prompt_candidate(session)
-        proposed_candidates = sampler.propose(session, seed)
+        sampler_seed = self._seed_token(session.id, round_index, "sampler")
+        proposed_candidates = sampler.propose(session, sampler_seed)
         proposed_candidates = self._widen_first_round_candidates(session, proposed_candidates)
         candidates = self._compose_round_candidates(
             pinned_candidate=carried_forward or baseline_candidate,
             proposed_candidates=proposed_candidates,
             candidate_count=session.config.candidate_count,
         )
+        self._assign_candidate_seeds(session, round_index, candidates)
         # Render each candidate independently so future versions can tolerate
         # partial round failures without changing the orchestration contract.
         for candidate in candidates:
             candidate.round_id = round_obj.id
             if candidate.generation_params.get("carried_forward") and candidate.image_path:
                 candidate.render_status = RenderStatus.succeeded
                 continue
-            candidate.seed = seed
             candidate = self.generator.render_candidate(session, candidate)
             candidate.render_status = RenderStatus.succeeded
         round_obj.candidates = candidates
@@ -281,6 +287,16 @@ def _validate_feedback_against_round(self, round_obj: Round, feedback) -> None:
         if unknown_ranked:
             raise ValueError(f"Feedback ranking references unknown candidates: {', '.join(unknown_ranked)}")
 
+        approved = feedback.normalized_payload.get("approved_candidate_ids", [])
+        unknown_approved = [candidate_id for candidate_id in approved if candidate_id not in candidate_ids]
+        if unknown_approved:
+            raise ValueError(f"Feedback approvals reference unknown candidates: {', '.join(unknown_approved)}")
+
+        rejected = feedback.normalized_payload.get("rejected_candidate_ids", [])
+        unknown_rejected = [candidate_id for candidate_id in rejected if candidate_id not in candidate_ids]
+        if unknown_rejected:
+            raise ValueError(f"Feedback rejections reference unknown candidates: {', '.join(unknown_rejected)}")
+
     @staticmethod
     def _candidate_trace_payload(candidate) -> dict:
         """Return a compact trace payload for one proposed image candidate."""
@@ -294,6 +310,8 @@ def _candidate_trace_payload(candidate) -> dict:
             "z": candidate.z,
             "predicted_score": candidate.predicted_score,
             "predicted_uncertainty": candidate.predicted_uncertainty,
+            "seed_policy": candidate.generation_params.get("seed_policy"),
+            "seed_group": candidate.generation_params.get("seed_group"),
         }
 
     def _build_carried_forward_candidate(self, session: Session) -> Candidate | None:
@@ -409,3 +427,40 @@ def _compose_round_candidates(
         for index, candidate in enumerate(selected):
             candidate.candidate_index = index
         return selected
+
+    def _assign_candidate_seeds(self, session: Session, round_index: int, candidates: list[Candidate]) -> None:
+        """Assign deterministic candidate seeds according to the configured policy."""
+
+        policy = session.config.seed_policy
+        round_seed = self._seed_token(session.id, round_index, "round")
+        for candidate in candidates:
+            if candidate.generation_params.get("carried_forward"):
+                candidate.generation_params["seed_policy"] = policy.value
+                candidate.generation_params["seed_group"] = "carried_forward"
+                candidate.generation_params["seed_preserved"] = True
+                continue
+
+            if policy == SeedPolicy.fixed_per_round:
+                candidate.seed = round_seed
+                seed_group = "round_shared"
+            elif policy == SeedPolicy.fixed_per_candidate:
+                candidate.seed = self._seed_token(session.id, round_index, "candidate", str(candidate.candidate_index))
+                seed_group = f"candidate:{candidate.candidate_index}"
+            elif policy == SeedPolicy.fixed_per_candidate_role:
+                role = candidate.sampler_role or "candidate"
+                candidate.seed = self._seed_token(session.id, round_index, "role", role)
+                seed_group = f"role:{role}"
+            else:
+                raise ValueError(f"Unsupported seed policy: {policy}")
+
+            candidate.generation_params["seed_policy"] = policy.value
+            candidate.generation_params["seed_group"] = seed_group
+            candidate.generation_params["round_seed"] = round_seed
+
+    @staticmethod
+    def _seed_token(*parts: object) -> int:
+        """Create one stable positive seed from arbitrary deterministic inputs."""
+
+        joined = "|".join(str(part) for part in parts)
+        digest = hashlib.blake2b(joined.encode("utf-8"), digest_size=4).digest()
+        return int.from_bytes(digest, byteorder="big", signed=False)

app/feedback/normalization.py

@@ -25,6 +25,25 @@ def normalize_feedback(round_id: str, request: FeedbackRequest) -> FeedbackEvent
             "winner_candidate_id": payload["winner_candidate_id"],
             "loser_candidate_id": payload.get("loser_candidate_id"),
         }
+    elif request.feedback_type == FeedbackType.winner_only:
+        winner_candidate_id = payload.get("winner_candidate_id")
+        if not winner_candidate_id:
+            raise ValueError("winner_only feedback requires winner_candidate_id")
+        normalized = {"winner_candidate_id": winner_candidate_id}
+    elif request.feedback_type == FeedbackType.approve_reject:
+        approvals = payload.get("approvals", {})
+        if not approvals:
+            raise ValueError("approve_reject feedback requires at least one approval decision")
+        approved_candidate_ids = [candidate_id for candidate_id, approved in approvals.items() if approved]
+        if not approved_candidate_ids:
+            raise ValueError("approve_reject feedback requires at least one approved candidate")
+        winner_candidate_id = payload.get("winner_candidate_id") or approved_candidate_ids[0]
+        normalized = {
+            "winner_candidate_id": winner_candidate_id,
+            "approved_candidate_ids": approved_candidate_ids,
+            "rejected_candidate_ids": [candidate_id for candidate_id, approved in approvals.items() if not approved],
+            "approvals": approvals,
+        }
     else:
         ranking = payload.get("ranking", [])
         if not ranking:

app/frontend/static/app.js

@@ -146,6 +146,32 @@ function buildFeedbackPayload(feedbackMode, ratingEntries) {
     };
   }
 
+  if (feedbackMode === "winner_only") {
+    return {
+      feedback_type: "winner_only",
+      payload: {
+        winner_candidate_id: sorted[0].candidateId,
+      },
+    };
+  }
+
+  if (feedbackMode === "approve_reject") {
+    const approvals = Object.fromEntries(
+      ratingEntries.map((entry) => [entry.candidateId, entry.rating >= 4])
+    );
+    const approvedEntries = sorted.filter((entry) => approvals[entry.candidateId]);
+    if (!approvedEntries.length) {
+      throw new Error("Approve/reject feedback requires at least one candidate rated 4 or 5.");
+    }
+    return {
+      feedback_type: "approve_reject",
+      payload: {
+        winner_candidate_id: approvedEntries[0].candidateId,
+        approvals,
+      },
+    };
+  }
+
   if (feedbackMode === "top_k") {
     return {
       feedback_type: "top_k",

app/samplers/axis_sweep.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from app.core.schema import Candidate, Session
+from app.samplers.base import clamp_vector, make_rng
+
+
+class AxisSweepSampler:
+    """Sampler that probes positive and negative movement along steering axes."""
+
+    name = "axis_sweep"
+
+    def propose(self, session: Session, seed: int) -> list[Candidate]:
+        """Generate a batch that systematically sweeps the steering basis directions."""
+
+        rng = make_rng(seed + 211)
+        base = session.current_z
+        dimensions = max(1, len(base))
+        candidates: list[Candidate] = []
+        for index in range(session.config.candidate_count):
+            axis = index % dimensions
+            direction = 1.0 if (index // dimensions) % 2 == 0 else -1.0
+            magnitude = 0.18 + (0.04 * (index // (dimensions * 2)))
+            offset = [0.0 for _ in base]
+            offset[axis] = direction * magnitude
+            jitter = [rng.uniform(-0.025, 0.025) for _ in base]
+            z = clamp_vector(
+                [current + delta + noise for current, delta, noise in zip(base, offset, jitter, strict=False)],
+                session.config.trust_radius,
+            )
+            role = "axis_positive" if direction > 0 else "axis_negative"
+            candidates.append(
+                Candidate(
+                    round_id="",
+                    candidate_index=index,
+                    z=z,
+                    sampler_role=role,
+                    predicted_score=sum(z),
+                    predicted_uncertainty=0.1 + (0.02 * index),
+                    seed=seed,
+                    generation_params={"image_size": session.config.image_size, "axis_index": axis},
+                )
+            )
+        return candidates