Improve first-round diversity and sample reporting

apartsin · apartsin · commit 766e0c11c2ef · 2026-03-26T03:59:47.000+02:00
diff --git a/app/core/schema.py b/app/core/schema.py
@@ -59,7 +59,7 @@ class StrategyConfig(BaseModel):
     feedback_mode: FeedbackType = FeedbackType.scalar_rating
     seed_policy: str = "fixed-per-round"
     steering_mode: str = "low_dimensional"
-    candidate_count: int = 4
+    candidate_count: int = 5
     image_size: str = "512x512"
     trust_radius: float = 0.35
     anchor_strength: float = 0.15
diff --git a/app/core/tracing.py b/app/core/tracing.py
@@ -161,6 +161,12 @@ def _render_session_report(
             "    .events th, .events td { text-align: left; padding: 10px; border-top: 1px solid #e7ddcf; vertical-align: top; }",
             "    pre { margin: 0; white-space: pre-wrap; word-break: break-word; background: #f7f2ea; border-radius: 12px; padding: 12px; }",
             "    a { color: #7a3f13; }",
+            "    details.card { padding: 0; overflow: hidden; }",
+            "    details.card > summary { list-style: none; cursor: pointer; padding: 20px; font-weight: 700; }",
+            "    details.card > summary::-webkit-details-marker { display: none; }",
+            "    details.card > summary::after { content: '+'; float: right; color: #7a3f13; }",
+            "    details.card[open] > summary::after { content: '−'; }",
+            "    .card-body { padding: 0 20px 20px; }",
             "  </style>",
             "</head>",
             "<body>",
@@ -179,30 +185,37 @@ def _render_session_report(
             f'      <div class="metric"><h3>Active Device</h3><p>{self._escape(str(diagnostics.get("active_device") or diagnostics.get("configured_device") or "n/a"))}</p></div>',
             "    </div>",
             "  </section>",
-            '  <section class="card section">',
-            "    <h2>Artifacts</h2>",
+            '  <details class="card section" open>',
+            "    <summary>Artifacts</summary>",
+            '    <div class="card-body">',
             f"    <p>Backend event log: <code>{self._escape(str(backend_rel))}</code></p>",
             f"    <p>Frontend event log: <code>{self._escape(str(frontend_rel))}</code></p>",
-            "  </section>",
-            '  <section class="card section">',
-            "    <h2>Runtime Diagnostics</h2>",
+            "    </div>",
+            "  </details>",
+            '  <details class="card section" open>',
+            "    <summary>Runtime Diagnostics</summary>",
+            '    <div class="card-body">',
             f"    <pre>{self._escape(json.dumps(diagnostics, indent=2, sort_keys=True))}</pre>",
-            "  </section>",
-            '  <section class="card section">',
-            "    <h2>Run Summary</h2>",
+            "    </div>",
+            "  </details>",
+            '  <details class="card section" open>',
+            "    <summary>Run Summary</summary>",
+            '    <div class="card-body">',
             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>",
             f"    <p><strong>Sampler:</strong> <code>{self._escape(str(session.get('config', {}).get('sampler', 'unknown')))}</code></p>",
             f"    <p><strong>Updater:</strong> <code>{self._escape(str(session.get('config', {}).get('updater', 'unknown')))}</code></p>",
-            "  </section>",
+            "    </div>",
+            "  </details>",
         ]
 
         for round_obj in rounds:
             html_parts.extend(
                 [
-                    '  <section class="card section round">',
-                    f"    <h2>Round {round_obj.get('round_index')}</h2>",
+                    '  <details class="card section round">',
+                    f"    <summary>Round {round_obj.get('round_index')}</summary>",
+                    '    <div class="card-body">',
                     f'    <span class="pill">Round id: {self._escape(round_obj.get("id", ""))}</span>',
                     f'    <span class="pill">Render status: {self._escape(str(round_obj.get("render_status", "unknown")))}</span>',
                     f'    <span class="pill">Latency: {self._escape(str(round_obj.get("latency_ms", 0)))} ms</span>',
@@ -242,12 +255,13 @@ def _render_session_report(
                 html_parts.append(
                     f"    <pre>{self._escape(json.dumps(round_obj.get('update_summary', {}), indent=2, sort_keys=True))}</pre>"
                 )
-            html_parts.append("  </section>")
+            html_parts.extend(["    </div>", "  </details>"])
 
         html_parts.extend(
             [
-                '  <section class="card section">',
-                "    <h2>Event Timeline</h2>",
+                '  <details class="card section">',
+                "    <summary>Event Timeline</summary>",
+                '    <div class="card-body">',
                 '    <table class="events">',
                 "      <thead><tr><th>Time</th><th>Source</th><th>Event</th><th>Details</th></tr></thead>",
                 "      <tbody>",
@@ -270,7 +284,8 @@ def _render_session_report(
             [
                 "      </tbody>",
                 "    </table>",
-                "  </section>",
+                "    </div>",
+                "  </details>",
                 "</main>",
                 "</body>",
                 "</html>",
diff --git a/app/engine/orchestrator.py b/app/engine/orchestrator.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from copy import deepcopy
+import math
 
 from app.core.config import settings
 from app.core.schema import (
@@ -21,6 +22,7 @@
 from app.core.logging import logger
 from app.core.tracing import TraceRecorder
 from app.feedback.normalization import normalize_feedback
+from app.samplers.base import clamp_vector
 from app.samplers.exploit_orthogonal import ExploitOrthogonalSampler
 from app.samplers.random_local import RandomLocalSampler
 from app.samplers.uncertainty import UncertaintyGuidedSampler
@@ -139,6 +141,7 @@ 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)
+        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,
@@ -360,6 +363,35 @@ def _build_baseline_prompt_candidate(session: Session) -> Candidate | None:
             },
         )
 
+    @staticmethod
+    def _widen_first_round_candidates(session: Session, proposed_candidates: list[Candidate]) -> list[Candidate]:
+        """Slightly spread first-round exploratory candidates away from the prompt baseline."""
+
+        if session.current_round != 0:
+            return proposed_candidates
+
+        boosted_candidates: list[Candidate] = []
+        boost_radius = min(session.config.trust_radius * 1.35, 0.6)
+        min_radius = min(max(session.config.trust_radius * 0.85, 0.18), boost_radius)
+        for index, candidate in enumerate(proposed_candidates):
+            scale = 1.2 + (0.12 * index)
+            boosted_z = clamp_vector([value * scale for value in candidate.z], boost_radius)
+            length = math.sqrt(sum(value * value for value in boosted_z))
+            if 0.0 < length < min_radius:
+                normalization = min_radius / length
+                boosted_z = clamp_vector([value * normalization for value in boosted_z], boost_radius)
+                length = math.sqrt(sum(value * value for value in boosted_z))
+            if length == 0.0:
+                axis = index % max(1, len(session.current_z))
+                boosted_z = [0.0 for _ in session.current_z]
+                boosted_z[axis] = min_radius
+            candidate.z = boosted_z
+            candidate.generation_params["first_round_diversity_boost"] = True
+            candidate.generation_params["first_round_diversity_scale"] = round(scale, 3)
+            candidate.generation_params["first_round_min_radius"] = round(min_radius, 3)
+            boosted_candidates.append(candidate)
+        return boosted_candidates
+
     @staticmethod
     def _compose_round_candidates(
         *,
diff --git a/docs/configuration_manual.md b/docs/configuration_manual.md
@@ -103,7 +103,7 @@ updater: winner_average
 feedback_mode: scalar_rating
 seed_policy: fixed-per-round
 steering_mode: low_dimensional
-candidate_count: 4
+candidate_count: 5
 image_size: 512x512
 trust_radius: 0.35
 anchor_strength: 0.15
@@ -331,7 +331,7 @@ updater: winner_average
 feedback_mode: scalar_rating
 seed_policy: fixed-per-round
 steering_mode: low_dimensional
-candidate_count: 4
+candidate_count: 5
 image_size: 512x512
 trust_radius: 0.25
 anchor_strength: 0.15
diff --git a/scripts/create_real_e2e_example.py b/scripts/create_real_e2e_example.py
@@ -33,10 +33,13 @@ def _pick_feedback(round_payload: dict, round_index: int) -> tuple[dict[str, int
             candidate_ids[0]: 2,
             candidate_ids[1]: 5,
             candidate_ids[2]: 4,
+            candidate_ids[3]: 3,
+            candidate_ids[4]: 1,
         }
         critique = (
             "The unmodified prompt baseline is promising, but candidate 2 has the clearest silhouette, "
-            "the strongest sunrise rim light, and the most premium hero-shot composition."
+            "the strongest sunrise rim light, and the most premium hero-shot composition. "
+            "The extra alternatives are useful, but they do not beat the top two."
         )
         return ratings, critique
 
@@ -45,6 +48,8 @@ def _pick_feedback(round_payload: dict, round_index: int) -> tuple[dict[str, int
             candidate_ids[0]: 5,
             candidate_ids[1]: 4,
             candidate_ids[2]: 2,
+            candidate_ids[3]: 3,
+            candidate_ids[4]: 1,
         }
         critique = "Keep the carried-forward winner, but push harder toward cleaner panel detail and a stronger studio-product framing."
         return ratings, critique
@@ -54,6 +59,8 @@ def _pick_feedback(round_payload: dict, round_index: int) -> tuple[dict[str, int
             candidate_ids[0]: 4,
             candidate_ids[1]: 5,
             candidate_ids[2]: 3,
+            candidate_ids[3]: 2,
+            candidate_ids[4]: 1,
         }
         critique = "Candidate 2 improves the bodywork and surfacing. It feels more like a premium launch image while staying true to the concept."
         return ratings, critique
@@ -63,6 +70,8 @@ def _pick_feedback(round_payload: dict, round_index: int) -> tuple[dict[str, int
             candidate_ids[0]: 4,
             candidate_ids[1]: 5,
             candidate_ids[2]: 3,
+            candidate_ids[3]: 2,
+            candidate_ids[4]: 1,
         }
         critique = "Candidate 2 has the best balance of dramatic lighting and realistic product geometry. Keep that direction for the next phase."
         return ratings, critique
@@ -71,6 +80,8 @@ def _pick_feedback(round_payload: dict, round_index: int) -> tuple[dict[str, int
         candidate_ids[0]: 5,
         candidate_ids[1]: 4,
         candidate_ids[2]: 3,
+        candidate_ids[3]: 2,
+        candidate_ids[4]: 1,
     }
     critique = "The incumbent now reads like the strongest finished hero image, so preserve it as the final preferred direction."
     return ratings, critique
@@ -233,6 +244,12 @@ def _render_html(
         "    pre { white-space: pre-wrap; word-break: break-word; background: #f7f1e9; border-radius: 14px; padding: 14px; font-size: 0.88rem; }",
         "    table { width: 100%; border-collapse: collapse; }",
         "    th, td { text-align: left; vertical-align: top; padding: 10px; border-top: 1px solid #e7dbce; }",
+        "    details.card { padding: 0; overflow: hidden; }",
+        "    details.card > summary { list-style: none; cursor: pointer; padding: 22px 24px; font-family: 'Segoe UI', sans-serif; font-weight: 700; }",
+        "    details.card > summary::-webkit-details-marker { display: none; }",
+        "    details.card > summary::after { content: '+'; float: right; color: #87562a; }",
+        "    details.card[open] > summary::after { content: '−'; }",
+        "    .card-body { padding: 0 24px 24px; }",
         "  </style>",
         "</head>",
         "<body>",
@@ -251,12 +268,14 @@ def _render_html(
         f'      <div class="metric"><strong>Unique images</strong><span>{escape(str(visual_checks["summary"]["unique_image_count"]))}</span></div>',
         "    </div>",
         "  </section>",
-        '  <section class="card stack">',
-        '    <div class="callout">',
+        '  <details class="card" open>',
+        "    <summary>Demonstration Overview</summary>",
+        '    <div class="card-body stack">',
+        '      <div class="callout">',
         "      <h2>Demonstration Objective</h2>",
         f"      <p>{escape(objective)}</p>",
-        "    </div>",
-        '    <div class="columns">',
+        "      </div>",
+        '      <div class="columns">',
         "      <div>",
         "        <h3>Success Criteria</h3>",
         "        <ul>",
@@ -270,29 +289,35 @@ def _render_html(
         "        </ol>",
         "      </div>",
         "    </div>",
-        "  </section>",
-        '  <section class="card stack">',
-        "    <div>",
+        "    </div>",
+        "  </details>",
+        '  <details class="card" open>',
+        "    <summary>Run Setup</summary>",
+        '    <div class="card-body stack">',
+        "      <div>",
         "      <h2>Run Setup</h2>",
         f"      <p><strong>Prompt:</strong> {escape(session['prompt'])}</p>",
         f"      <p><strong>Negative prompt:</strong> {escape(session.get('negative_prompt') or '(none)')}</p>",
         f"      <p><strong>Sampler:</strong> <code>{escape(session['config']['sampler'])}</code> | <strong>Updater:</strong> <code>{escape(session['config']['updater'])}</code> | <strong>Feedback mode:</strong> <code>{escape(session['config']['feedback_mode'])}</code></p>",
         f"      <p><strong>Output file:</strong> <code>{escape(str(output_path))}</code></p>",
+        "      </div>",
+        f"      <pre>{escape(json.dumps(diagnostics, indent=2, sort_keys=True))}</pre>",
         "    </div>",
-        f"    <pre>{escape(json.dumps(diagnostics, indent=2, sort_keys=True))}</pre>",
-        "  </section>",
-        '  <section class="card stack">',
-        "    <div>",
+        "  </details>",
+        '  <details class="card" open>',
+        "    <summary>Automated Visual Checks</summary>",
+        '    <div class="card-body stack">',
+        "      <div>",
         "      <h2>Automated Visual Checks</h2>",
         "      <p>These checks do not prove semantic correctness, but they do catch common generation failures such as blank-looking outputs, unreadable files, low-detail artifacts, and accidental duplication.</p>",
-        "    </div>",
-        '    <div class="metrics">',
+        "      </div>",
+        '      <div class="metrics">',
         f'      <div class="metric"><strong>Unique image files</strong><span>{escape(str(visual_checks["summary"]["unique_image_count"]))}</span></div>',
         f'      <div class="metric"><strong>Reused candidates</strong><span>{escape(str(visual_checks["summary"]["reused_candidate_count"]))}</span></div>',
         f'      <div class="metric"><strong>Flagged images</strong><span>{escape(str(visual_checks["summary"]["failing_image_count"]))}</span></div>',
         f'      <div class="metric"><strong>Duplicate groups</strong><span>{escape(str(visual_checks["summary"]["duplicate_image_group_count"]))}</span></div>',
-        "    </div>",
-        "    <table>",
+        "      </div>",
+        "      <table>",
         "      <thead><tr><th>Image</th><th>Candidates</th><th>Size</th><th>Entropy</th><th>Contrast</th><th>Edges</th><th>Status</th></tr></thead>",
         "      <tbody>",
         *[
@@ -310,21 +335,23 @@ def _render_html(
         "      </tbody>",
         "    </table>",
         (
-            f"    <pre>{escape(json.dumps(visual_checks, indent=2, sort_keys=True))}</pre>"
+            f"      <pre>{escape(json.dumps(visual_checks, indent=2, sort_keys=True))}</pre>"
             if visual_checks["failing_images"] or visual_checks["duplicate_groups"]
-            else "    <p>All automated visual sanity checks passed for the unique generated images in this bundle.</p>"
+            else "      <p>All automated visual sanity checks passed for the unique generated images in this bundle.</p>"
         ),
-        "  </section>",
+        "    </div>",
+        "  </details>",
     ]
 
     for round_obj in rounds:
         feedback = round_obj["feedback_events"][0] if round_obj["feedback_events"] else None
         winner_id = round_obj.get("update_summary", {}).get("winner_candidate_id")
         sections.extend(
             [
-                '  <section class="card round">',
+                '  <details class="card round">',
+                f"    <summary>Phase {round_obj['round_index']}: propose, inspect, choose, update</summary>",
+                '    <div class="card-body">',
                 f"    <p class=\"eyebrow\">Round {round_obj['round_index']}</p>",
-                f"    <h2>Phase {round_obj['round_index']}: propose, inspect, choose, update</h2>",
                 f"    <p><span class=\"pill\">Round id: {escape(round_obj['id'])}</span><span class=\"pill\">Latency: {escape(str(round_obj.get('latency_ms', 0)))} ms</span><span class=\"pill\">Incumbent z before update: {escape(json.dumps(round_obj.get('incumbent_z', [])))}</span></p>",
                 '    <div class="candidate-grid">',
             ]
@@ -369,16 +396,19 @@ def _render_html(
                     f"    <pre>{escape(json.dumps(round_obj['update_summary'], indent=2, sort_keys=True))}</pre>",
                 ]
             )
-        sections.append("  </section>")
+        sections.extend(["    </div>", "  </details>"])
 
     sections.extend(
         [
-            '  <section class="card">',
+            '  <details class="card" open>',
+            "    <summary>Outcome</summary>",
+            '    <div class="card-body">',
             "    <h2>Outcome</h2>",
             f"    <p>The session ended at round <strong>{len(rounds)}</strong> with incumbent candidate <code>{escape(str(session.get('incumbent_candidate_id') or 'n/a'))}</code>.</p>",
             "    <p>This report demonstrates system value by showing that the workflow does not stop at one prompt and one image. It keeps the user in a controlled compare-select-update loop with visible evidence for what was proposed, what was preferred, and how the next state was chosen.</p>",
             f"    <p>Backend session traces and the auto-generated audit report also exist under <code>{escape(str((output_path.parent / 'data' / 'traces').resolve()))}</code>.</p>",
-            "  </section>",
+            "    </div>",
+            "  </details>",
             "</main>",
             "</body>",
             "</html>",
@@ -422,7 +452,7 @@ def main() -> int:
             name="Premium product hero image demo",
             description="A scripted user steering walkthrough that demonstrates creative refinement on the real Diffusers backend.",
             config=StrategyConfig(
-                candidate_count=3,
+                candidate_count=5,
                 image_size="512x512",
                 sampler="random_local",
                 updater="winner_average",
diff --git a/site/docs/configuration_manual.html b/site/docs/configuration_manual.html
@@ -111,7 +111,7 @@ <h2 id="yaml-template">YAML Template</h2>
 feedback_mode: scalar_rating
 seed_policy: fixed-per-round
 steering_mode: low_dimensional
-candidate_count: 4
+candidate_count: 5
 image_size: 512x512
 trust_radius: 0.35
 anchor_strength: 0.15
@@ -306,7 +306,7 @@ <h3 id="conservative-comparison-session">Conservative Comparison Session</h3>
 feedback_mode: scalar_rating
 seed_policy: fixed-per-round
 steering_mode: low_dimensional
-candidate_count: 4
+candidate_count: 5
 image_size: 512x512
 trust_radius: 0.25
 anchor_strength: 0.15
diff --git a/tests/e2e/app.spec.js b/tests/e2e/app.spec.js
diff --git a/tests/test_config_yaml.py b/tests/test_config_yaml.py
diff --git a/tests/test_session_lifecycle.py b/tests/test_session_lifecycle.py
