Improve session UX and first-round diversity

Author: apartsin

app/engine/orchestrator.py

@@ -176,11 +176,25 @@ def generate_round(
         self._report_progress(progress_callback, 52, "Rendering candidate images on the model backend")
         # Render each candidate independently so future versions can tolerate
         # partial round failures without changing the orchestration contract.
-        for candidate in candidates:
+        render_progress_start = 52
+        render_progress_end = 74
+        total_candidates = max(1, len(candidates))
+        for index, candidate in enumerate(candidates, start=1):
+            progress = render_progress_start + int((render_progress_end - render_progress_start) * ((index - 1) / total_candidates))
             candidate.round_id = round_obj.id
             if candidate.generation_params.get("carried_forward") and candidate.image_path:
+                self._report_progress(
+                    progress_callback,
+                    progress,
+                    f"Using saved image {index} of {total_candidates} from the previous winning round",
+                )
                 candidate.render_status = RenderStatus.succeeded
                 continue
+            self._report_progress(
+                progress_callback,
+                progress,
+                f"Generating image {index} of {total_candidates} on the model backend",
+            )
             candidate = self.generator.render_candidate(session, candidate)
             candidate.render_status = RenderStatus.succeeded
         round_obj.candidates = candidates
@@ -447,27 +461,61 @@ def _widen_first_round_candidates(session: Session, proposed_candidates: list[Ca
             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)
+        dimensions = max(1, len(session.current_z))
+        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):
-            scale = 1.2 + (0.12 * index)
-            boosted_z = clamp_vector([value * scale for value in candidate.z], boost_radius)
+            spread_direction = Orchestrator._first_round_spread_direction(index, dimensions)
+            scale = 1.15 + (0.1 * index)
+            blended = [
+                (original * 0.35) + (spread * boost_radius)
+                for original, spread in zip(candidate.z, spread_direction, strict=False)
+            ]
+            boosted_z = clamp_vector(blended, 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))
+                axis = index % dimensions
                 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)
+            candidate.generation_params["first_round_spread_direction"] = [round(value, 4) for value in spread_direction]
             boosted_candidates.append(candidate)
         return boosted_candidates
 
+    @staticmethod
+    def _first_round_spread_direction(index: int, dimensions: int) -> list[float]:
+        """Build a deliberately separated first-round direction for visible diversity."""
+
+        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.55 * secondary_sign
+        if dimensions > 2:
+            vector[tertiary_axis] += 0.3 * tertiary_sign
+        if dimensions > 3:
+            extra_axis = (index + 3) % dimensions
+            vector[extra_axis] += 0.22 if index % 2 == 0 else -0.22
+
+        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]
+
     @staticmethod
     def _compose_round_candidates(
         *,

app/frontend/static/app.js

@@ -68,11 +68,18 @@ function traceFrontend(event, details = {}) {
 
 async function postJson(url, body) {
   traceFrontend("http.request.started", { url, body_keys: Object.keys(body || {}) });
-  const response = await fetch(url, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body),
-  });
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+  } catch (error) {
+    const message = "Could not reach the server. Make sure the app is still running, then try again.";
+    traceFrontend("http.request.failed", { url, detail: message, error_name: error?.name || "network_error" });
+    throw new Error(message);
+  }
   if (!response.ok) {
     const text = await response.text();
     let message = text || `Request failed: ${response.status}`;
@@ -118,6 +125,18 @@ async function pollJob(statusUrl, { onProgress } = {}) {
   }
 }
 
+async function runNextRoundJob(sessionId, { queuedLabel, runningFallbackLabel } = {}) {
+  const job = await postJson(`/sessions/${sessionId}/rounds/next/async`, {});
+  setStatus(queuedLabel || "Queueing round generation...");
+  setProgress(55, queuedLabel || "Queueing next round");
+  await pollJob(job.status_url, {
+    onProgress: (snapshot) => {
+      setStatus(snapshot.status_message);
+      setProgress(snapshot.progress, snapshot.status_message || runningFallbackLabel || "Generating next round");
+    },
+  });
+}
+
 function collectRatings() {
   return Array.from(document.querySelectorAll(".rating-input")).map((input) => ({
     candidateId: input.dataset.candidateId,
@@ -308,12 +327,9 @@ if (nextRoundButton) {
     setStatus("Queueing round generation...");
     setProgress(5, "Queueing next round");
     try {
-      const job = await postJson(`/sessions/${sessionId}/rounds/next/async`, {});
-      await pollJob(job.status_url, {
-        onProgress: (snapshot) => {
-          setStatus(snapshot.status_message);
-          setProgress(snapshot.progress, snapshot.status_message || "Generating next round");
-        },
+      await runNextRoundJob(sessionId, {
+        queuedLabel: "Queueing round generation...",
+        runningFallbackLabel: "Generating next round",
       });
       setStatus("Round generated. Refreshing session view...");
       setProgress(100, "Round completed");
@@ -342,6 +358,7 @@ if (submitFeedbackButton) {
   submitFeedbackButton.addEventListener("click", async () => {
     if (submitFeedbackButton.disabled) return;
     const feedbackMode = submitFeedbackButton.dataset.feedbackMode || "scalar_rating";
+    const sessionId = submitFeedbackButton.dataset.sessionId;
     try {
       const request = buildFeedbackPayload(feedbackMode);
       traceFrontend("feedback.submit.clicked", {
@@ -361,8 +378,18 @@ if (submitFeedbackButton) {
           setProgress(snapshot.progress, snapshot.status_message || "Applying feedback");
         },
       });
-      setStatus("Feedback submitted. Refreshing session view...");
-      setProgress(100, "Feedback applied");
+      traceFrontend("feedback.submit.completed", {
+        round_id: submitFeedbackButton.dataset.roundId,
+        session_id: sessionId,
+      });
+      setStatus("Feedback applied. Starting the next round...");
+      setProgress(50, "Preparing next round");
+      await runNextRoundJob(sessionId, {
+        queuedLabel: "Queueing next round after feedback...",
+        runningFallbackLabel: "Generating the next round",
+      });
+      setStatus("Next round ready. Refreshing session view...");
+      setProgress(100, "Next round completed");
       window.location.reload();
     } catch (error) {
       setStatus(error.message, true);

app/frontend/templates/index.html

@@ -36,8 +36,8 @@ <h2>Resume sessions</h2>
             {% for session in sessions %}
               <tr>
                 <td>{{ session.prompt }}</td>
-                <td>{{ session.status }}</td>
-                <td>{{ session.current_round }}</td>
+                <td>{{ humanize_session_status(session.status) }}</td>
+                <td>{% if session.current_round == 0 %}Not started yet{% else %}Round {{ session.current_round }}{% endif %}</td>
                 <td>
                   <div class="actions inline-actions">
                     <a class="button secondary" href="/sessions/{{ session.id }}/view">Resume session</a>
@@ -55,7 +55,7 @@ <h2>Resume sessions</h2>
       <section class="card">
         <div class="section-head">
           <h2>Experiments</h2>
-          <span>{{ experiments|length }} total</span>
+          <span>{{ experiments|length }} shown · {{ experiment_count }} total</span>
         </div>
         {% if experiments %}
           <table class="table">
@@ -71,9 +71,9 @@ <h2>Experiments</h2>
             {% for experiment in experiments %}
               <tr>
                 <td>{{ experiment.name }}</td>
-                <td>{{ experiment.config.sampler }}</td>
-                <td>{{ experiment.config.updater }}</td>
-                <td>{{ experiment.config.feedback_mode }}</td>
+                <td>{{ humanize_token(experiment.config.sampler) }}</td>
+                <td>{{ humanize_token(experiment.config.updater) }}</td>
+                <td>{{ humanize_feedback_mode(experiment.config.feedback_mode) }}</td>
               </tr>
             {% endfor %}
             </tbody>

app/frontend/templates/replay.html

@@ -21,7 +21,7 @@ <h1>{{ session.prompt }}</h1>
         <section class="card">
           <div class="section-head">
             <h2>Round {{ round.round_index }}</h2>
-            <span>{{ round.render_status }} · {{ round.candidates|length }} candidates</span>
+            <span>{{ humanize_token(round.render_status) }} · {{ round.candidates|length }} candidates</span>
           </div>
           <div class="summary-grid">
             <div class="summary-item">
@@ -34,7 +34,7 @@ <h2>Round {{ round.round_index }}</h2>
             </div>
             <div class="summary-item">
               <span class="summary-label">Seed policy</span>
-              <strong>{{ round.seed_policy }}</strong>
+              <strong>{{ humanize_token(round.seed_policy) }}</strong>
             </div>
           </div>
           <div class="image-grid">
@@ -43,7 +43,7 @@ <h2>Round {{ round.round_index }}</h2>
                 <img src="{{ candidate.image_path }}" alt="Candidate {{ candidate.candidate_index }}">
                 <h3>Candidate {{ candidate.candidate_index + 1 }}</h3>
                 <p class="candidate-subtitle">{{ candidate.id }}</p>
-                <p><strong>{{ candidate.sampler_role }}</strong></p>
+                <p><strong>{{ humanize_token(candidate.sampler_role) }}</strong></p>
               </article>
             {% endfor %}
           </div>

app/frontend/templates/session.html

@@ -11,7 +11,7 @@
       <section class="hero compact">
         <p class="eyebrow">Session</p>
         <h1>{{ session.prompt }}</h1>
-        <p class="lede">Sampler: {{ session.config.sampler.value }} | Updater: {{ session.config.updater.value }} | Feedback: {{ session.config.feedback_mode.value }}</p>
+        <p class="lede">Sampler: {{ humanize_token(session.config.sampler) }} | Updater: {{ humanize_token(session.config.updater) }} | Feedback: {{ humanize_feedback_mode(session.config.feedback_mode) }}</p>
         <div class="badge-row">
           <span class="status-badge" title="The resolved generation backend for this session.">Backend: {{ runtime_diagnostics.backend }}</span>
           <span class="status-badge" title="The device currently used for inference.">Device: {{ runtime_diagnostics.active_device or runtime_diagnostics.configured_device or "n/a" }}</span>
@@ -27,7 +27,7 @@ <h1>{{ session.prompt }}</h1>
       <section class="card">
         <div class="section-head">
           <h2>Current state</h2>
-          <span>Round {{ session.current_round }}</span>
+          <span>{% if session.current_round == 0 %}Not started yet{% else %}Round {{ session.current_round }}{% endif %}</span>
         </div>
         <p id="page-status" class="status-message" role="status" aria-live="polite" hidden></p>
         <div id="progress-panel" class="progress-panel" hidden>
@@ -46,11 +46,7 @@ <h2>Current state</h2>
           </div>
           <div class="summary-item">
             <span class="summary-label">Feedback mode <span class="help-tip inline" tabindex="0" role="note" aria-label="Feedback mode help" data-tooltip="This controls which feedback widget appears on each candidate card and how your selection is interpreted.">?</span></span>
-            <strong>{{ session.config.feedback_mode.value }}</strong>
-          </div>
-          <div class="summary-item">
-            <span class="summary-label">Steering vector <span class="help-tip inline" tabindex="0" role="note" aria-label="Steering vector help" data-tooltip="This is the current low-dimensional steering state that the updater moves after each round of feedback.">?</span></span>
-            <code>{{ session.current_z }}</code>
+            <strong>{{ humanize_feedback_mode(session.config.feedback_mode) }}</strong>
           </div>
         </div>
         <p class="hint">{% if session.current_round == 0 %}Start by generating the first round. You will see one raw prompt baseline plus additional sampled variants.{% elif session.status == "awaiting_feedback" %}Review this round and submit feedback to unlock the next one.{% else %}Feedback is complete for the current round. You can continue exploring or open replay to review the history.{% endif %}</p>
@@ -78,7 +74,6 @@ <h3>Candidate {{ candidate.candidate_index + 1 }}</h3>
                       <p class="candidate-subtitle">{{ candidate.id }}</p>
                       <div class="candidate-meta">
                         <p>Role <span class="help-tip inline" tabindex="0" role="note" aria-label="Candidate role help" data-tooltip="Baseline is the raw prompt, incumbent is the previous winner, and sampler roles describe how other candidates were proposed.">?</span>: <strong>{{ candidate.sampler_role }}</strong></p>
-                        <p>Steering <span class="help-tip inline" tabindex="0" role="note" aria-label="Candidate steering vector help" data-tooltip="This candidate's proposed steering coordinates for the current round.">?</span>: <code>{{ candidate.z }}</code></p>
                       </div>
                       {% if is_current_round and not round.feedback_events %}
                         <div class="candidate-controls" data-feedback-mode="{{ session.config.feedback_mode.value }}">
@@ -148,7 +143,7 @@ <h3>Candidate {{ candidate.candidate_index + 1 }}</h3>
                     {% endif %}
                   </p>
                   <div class="actions">
-                    <button class="button" id="submit-feedback-button" data-round-id="{{ round.id }}" data-feedback-mode="{{ session.config.feedback_mode.value }}" title="Submit your current preference selections and update the session model.">Submit feedback</button>
+                    <button class="button" id="submit-feedback-button" data-round-id="{{ round.id }}" data-feedback-mode="{{ session.config.feedback_mode.value }}" data-session-id="{{ session.id }}" title="Apply your current preference selections and immediately generate the next round.">Submit feedback and generate next round</button>
                   </div>
                 {% elif round.feedback_events %}
                   <div class="soft-callout">

app/main.py

@@ -25,6 +25,46 @@
 templates = Jinja2Templates(directory=str(Path("app/frontend/templates")))
 
 
+def humanize_token(value: object) -> str:
+    """Turn enum values and slugs into readable UI labels."""
+
+    if value is None:
+        return ""
+    raw = getattr(value, "value", str(value))
+    return raw.replace("_", " ").replace("-", " ").strip().title()
+
+
+def humanize_feedback_mode(value: object) -> str:
+    mapping = {
+        "scalar_rating": "Star ratings",
+        "pairwise": "Pairwise winner vs loser",
+        "top_k": "Top-k ranking",
+        "winner_only": "Single winner",
+        "approve_reject": "Approve / reject",
+    }
+    raw = getattr(value, "value", str(value))
+    return mapping.get(raw, humanize_token(raw))
+
+
+def humanize_session_status(value: object) -> str:
+    mapping = {
+        "created": "Created",
+        "ready": "Ready for the next round",
+        "awaiting_feedback": "Waiting for feedback",
+        "updating": "Applying feedback",
+        "completed": "Completed",
+        "failed": "Needs attention",
+        "paused": "Paused",
+    }
+    raw = getattr(value, "value", str(value))
+    return mapping.get(raw, humanize_token(raw))
+
+
+templates.env.globals["humanize_token"] = humanize_token
+templates.env.globals["humanize_feedback_mode"] = humanize_feedback_mode
+templates.env.globals["humanize_session_status"] = humanize_session_status
+
+
 def initialize_app_state(application: FastAPI) -> None:
     """Build the runtime services for the web app.
 
@@ -129,7 +169,15 @@ def index(request: Request) -> HTMLResponse:
 
     experiments = request.app.state.orchestrator.list_experiments()
     sessions = request.app.state.orchestrator.list_sessions()
-    return templates.TemplateResponse("index.html", {"request": request, "experiments": experiments, "sessions": sessions[:10]})
+    return templates.TemplateResponse(
+        "index.html",
+        {
+            "request": request,
+            "experiments": experiments[:20],
+            "experiment_count": len(experiments),
+            "sessions": sessions[:10],
+        },
+    )
 
 
 @app.get("/diagnostics")
@@ -292,6 +340,13 @@ def create_session_from_setup(request: SetupSessionRequest):
         return api_error_response(400, "invalid_input", str(exc))
     except KeyError as exc:
         return api_error_response(404, "not_found", str(exc))
+    except Exception:
+        logger.exception("Unexpected failure while creating a session from setup YAML")
+        return api_error_response(
+            500,
+            "internal_error",
+            "The session could not be created from this YAML configuration due to an unexpected server error.",
+        )
     return {
         "experiment": experiment.model_dump(mode="json"),
         "session": session.model_dump(mode="json"),