fluxloop-cli 0.2.25__tar.gz → 0.2.27__tar.gz

{fluxloop_cli-0.2.25 → fluxloop_cli-0.2.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluxloop-cli
-Version: 0.2.25
+Version: 0.2.27
 Summary: FluxLoop CLI for running agent simulations
 Author-email: FluxLoop Team <team@fluxloop.dev>
 License: Apache-2.0
@@ -66,8 +66,8 @@ The legacy `setting.yaml` is still supported, but new projects created with
 - `fluxloop init project` – scaffold a new project (configs, `.env`, examples)
 - `fluxloop generate inputs` – produce input variations for the active project
 - `fluxloop run experiment` – execute an experiment using `configs/simulation.yaml`
-- `fluxloop parse experiment` – convert experiment outputs into readable artifacts
-- `fluxloop evaluate experiment` – score experiment outputs using rule-based and LLM evaluators, generate reports with success criteria, analysis, and customizable templates
+- `fluxloop parse experiment` – convert experiment outputs into readable artifacts and emit structured per-trace JSON at `per_trace_analysis/per_trace.jsonl`
+- `fluxloop evaluate experiment` – score experiment outputs using rule-based and LLM evaluators (requires `fluxloop parse` output or `--per-trace`), generate reports with success criteria, analysis, and customizable templates
 - `fluxloop config set-llm` – update LLM provider/model in `configs/input.yaml`
 - `fluxloop record enable|disable|status` – toggle recording mode across `.env` and simulation config
 - `fluxloop doctor` – summarize Python, FluxLoop CLI/MCP, and MCP index state for the active environment
@@ -88,6 +88,16 @@ These flags override the values in `configs/simulation.yaml` (`multi_turn` block
 
 Run `fluxloop --help` or `fluxloop <command> --help` for more detail.
 
+## Evaluation Workflow
+
+Evaluation now follows a two-step process so that multi-turn context is preserved:
+
+1. `fluxloop run experiment` – produce `trace_summary.jsonl` (and optionally `observations.jsonl`).
+2. `fluxloop parse experiment <experiment_dir>` – generate markdown summaries and a structured artifact at `per_trace_analysis/per_trace.jsonl`.
+3. `fluxloop evaluate experiment <experiment_dir>` – consume the structured file to calculate scores and reports.
+
+`fluxloop evaluate` exits early with guidance when the per-trace artifact is missing. If you relocate the file, supply an explicit path with `--per-trace /path/to/per_trace.jsonl`.
+
 ## Quick Setup Script
 
 To prepare a fresh checkout (create `.venv`, install dependencies, and run diagnostics):

{fluxloop_cli-0.2.25 → fluxloop_cli-0.2.27}/README.md

@@ -25,8 +25,8 @@ The legacy `setting.yaml` is still supported, but new projects created with
 - `fluxloop init project` – scaffold a new project (configs, `.env`, examples)
 - `fluxloop generate inputs` – produce input variations for the active project
 - `fluxloop run experiment` – execute an experiment using `configs/simulation.yaml`
-- `fluxloop parse experiment` – convert experiment outputs into readable artifacts
-- `fluxloop evaluate experiment` – score experiment outputs using rule-based and LLM evaluators, generate reports with success criteria, analysis, and customizable templates
+- `fluxloop parse experiment` – convert experiment outputs into readable artifacts and emit structured per-trace JSON at `per_trace_analysis/per_trace.jsonl`
+- `fluxloop evaluate experiment` – score experiment outputs using rule-based and LLM evaluators (requires `fluxloop parse` output or `--per-trace`), generate reports with success criteria, analysis, and customizable templates
 - `fluxloop config set-llm` – update LLM provider/model in `configs/input.yaml`
 - `fluxloop record enable|disable|status` – toggle recording mode across `.env` and simulation config
 - `fluxloop doctor` – summarize Python, FluxLoop CLI/MCP, and MCP index state for the active environment
@@ -47,6 +47,16 @@ These flags override the values in `configs/simulation.yaml` (`multi_turn` block
 
 Run `fluxloop --help` or `fluxloop <command> --help` for more detail.
 
+## Evaluation Workflow
+
+Evaluation now follows a two-step process so that multi-turn context is preserved:
+
+1. `fluxloop run experiment` – produce `trace_summary.jsonl` (and optionally `observations.jsonl`).
+2. `fluxloop parse experiment <experiment_dir>` – generate markdown summaries and a structured artifact at `per_trace_analysis/per_trace.jsonl`.
+3. `fluxloop evaluate experiment <experiment_dir>` – consume the structured file to calculate scores and reports.
+
+`fluxloop evaluate` exits early with guidance when the per-trace artifact is missing. If you relocate the file, supply an explicit path with `--per-trace /path/to/per_trace.jsonl`.
+
 ## Quick Setup Script
 
 To prepare a fresh checkout (create `.venv`, install dependencies, and run diagnostics):

{fluxloop_cli-0.2.25 → fluxloop_cli-0.2.27}/fluxloop_cli/__init__.py

@@ -2,7 +2,7 @@
 FluxLoop CLI - Command-line interface for running agent simulations.
 """
 
-__version__ = "0.2.25"
+__version__ = "0.2.27"
 
 from .main import app
 

{fluxloop_cli-0.2.25 → fluxloop_cli-0.2.27}/fluxloop_cli/commands/evaluate.py

@@ -81,6 +81,11 @@ def experiment(
         file_okay=True,
         dir_okay=False,
     ),
+    per_trace: Optional[Path] = typer.Option(
+        None,
+        "--per-trace",
+        help="Path to structured per-trace JSONL generated by `fluxloop parse`",
+    ),
     verbose: bool = typer.Option(
         False,
         "--verbose",
@@ -129,6 +134,19 @@ def experiment(
             resolved_baseline = (Path.cwd() / resolved_baseline).resolve()
         baseline_path = resolved_baseline
 
+    if per_trace is not None:
+        per_trace_path = per_trace
+        if not per_trace_path.is_absolute():
+            per_trace_path = (Path.cwd() / per_trace_path).resolve()
+    else:
+        per_trace_path = resolved_experiment_dir / "per_trace_analysis" / "per_trace.jsonl"
+
+    if not per_trace_path.exists():
+        raise typer.BadParameter(
+            f"Structured per-trace artifacts not found at {per_trace_path}. "
+            "Run `fluxloop parse` before evaluating or provide --per-trace."
+        )
+
     try:
         evaluation_config = load_evaluation_config(config_path)
     except FileNotFoundError as exc:
@@ -164,6 +182,7 @@ def experiment(
         report_format=report_format,  # type: ignore[arg-type]
         report_template=report_template_path,
         baseline_path=baseline_path,
+        per_trace_path=per_trace_path,
     )
 
     effective_report_format = report_format or evaluation_config.report.output
@@ -183,6 +202,7 @@ def experiment(
         f"⚙️  Config: [magenta]{config_path}[/magenta]",
         f"📁 Output: [green]{output_dir}[/green]",
         f"📝 Report: [yellow]{effective_report_format.upper()}[/yellow] (template: [cyan]{template_display}[/cyan])",
+        f"🧵 Per-trace data: [blue]{per_trace_path}[/blue]",
     ]
     if baseline_display:
         message_lines.append(f"📈 Baseline: [cyan]{baseline_display}[/cyan]")

{fluxloop_cli-0.2.25 → fluxloop_cli-0.2.27}/fluxloop_cli/commands/parse.py

@@ -7,7 +7,7 @@ from collections import defaultdict
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
-from typing import Dict, Iterable, List, Literal, Optional
+from typing import Any, Dict, Iterable, List, Literal, Optional
 
 import typer
 from rich.console import Console
@@ -44,6 +44,24 @@ class Observation:
         except ValueError:
             return None
 
+    def to_payload(self) -> dict:
+        """Return a JSON-serialisable representation of the observation."""
+
+        payload = {
+            "trace_id": self.trace_id,
+            "type": self.type,
+            "name": self.name,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "level": self.level,
+            "duration_ms": self.duration_ms,
+            "input": self.input,
+            "output": self.output,
+        }
+        # Preserve original record for downstream consumers that need full context.
+        payload["raw"] = self.raw
+        return payload
+
 
 @dataclass
 class TraceSummary:
@@ -58,6 +76,20 @@ class TraceSummary:
     success: bool
     raw: dict
 
+    def to_payload(self) -> dict:
+        """Return a JSON-serialisable representation of the summary entry."""
+
+        return {
+            "trace_id": self.trace_id,
+            "iteration": self.iteration,
+            "persona": self.persona,
+            "input": self.input_text,
+            "output": self.output_text,
+            "duration_ms": self.duration_ms,
+            "success": self.success,
+            "raw": self.raw,
+        }
+
 
 def _load_observations(path: Path) -> Dict[str, List[Observation]]:
     """Load observations grouped by trace_id."""
@@ -155,10 +187,7 @@ def _format_markdown(
 ) -> str:
     """Create markdown visualization for a single trace."""
 
-    observations_sorted = sorted(
-        observations,
-        key=lambda obs: (obs.start_time or "", obs.end_time or ""),
-    )
+    observations_sorted = _sort_observations(observations)
 
     header = (
         "---\n"
@@ -212,6 +241,65 @@ def _format_markdown(
     return header + summary_section + "".join(timeline_lines)
 
 
+def _sort_observations(
+    observations: List[Observation],
+) -> List[Observation]:
+    """Return observations sorted for timeline display."""
+
+    return sorted(
+        observations,
+        key=lambda obs: (obs.start_time or "", obs.end_time or ""),
+    )
+
+
+def _build_timeline_payload(observations: List[Observation]) -> List[dict]:
+    """Convert observations to structured timeline entries."""
+
+    return [item.to_payload() for item in _sort_observations(observations)]
+
+
+def _build_structured_record(
+    trace: TraceSummary,
+    observations: List[Observation],
+) -> Dict[str, Any]:
+    """Build structured per-trace data for downstream analysis."""
+
+    timeline = _build_timeline_payload(observations)
+    summary_payload = trace.to_payload()
+
+    record: Dict[str, Any] = {
+        "trace_id": summary_payload["trace_id"],
+        "iteration": summary_payload["iteration"],
+        "persona": summary_payload["persona"],
+        "input": summary_payload["input"],
+        "output": summary_payload["output"],
+        "final_output": summary_payload["output"],
+        "duration_ms": summary_payload["duration_ms"],
+        "success": summary_payload["success"],
+        "summary": summary_payload,
+        "timeline": timeline,
+    }
+
+    record["metrics"] = {
+        "observation_count": len(timeline),
+    }
+
+    return record
+
+
+def _write_structured_records(
+    output_dir: Path,
+    records: Iterable[Dict[str, Any]],
+) -> Path:
+    """Persist structured per-trace records as JSONL."""
+
+    target = output_dir / "per_trace.jsonl"
+    with target.open("w", encoding="utf-8") as handle:
+        for record in records:
+            handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+    return target
+
+
 def _slugify(name: str) -> str:
     """Create a filesystem-safe slug from a trace identifier."""
 
@@ -268,7 +356,13 @@ def experiment(
     observations_path = experiment_dir / "observations.jsonl"
     trace_summary_path = experiment_dir / "trace_summary.jsonl"
 
-    observations = _load_observations(observations_path)
+    try:
+        observations = _load_observations(observations_path)
+    except FileNotFoundError:
+        console.print(
+            "[yellow]No observations.jsonl found. Structured timelines will omit observation data.[/yellow]"
+        )
+        observations = defaultdict(list)
     summaries = list(_load_trace_summaries(trace_summary_path))
 
     if not summaries:
@@ -276,9 +370,11 @@ def experiment(
         raise typer.Exit(0)
 
     console.print(
-        f"📝 Found {len(summaries)} trace summaries. Generating markdown..."
+        f"📝 Found {len(summaries)} trace summaries. Generating markdown and structured data..."
     )
 
+    structured_records: List[Dict[str, Any]] = []
+
     for summary in summaries:
         trace_observations = observations.get(summary.trace_id, [])
         content = _format_markdown(summary, trace_observations)
@@ -286,8 +382,13 @@ def experiment(
         target_path = output_dir / file_name
         target_path.write_text(content, encoding="utf-8")
 
+        structured_records.append(_build_structured_record(summary, trace_observations))
+
+    jsonl_path = _write_structured_records(output_dir, structured_records)
+
     console.print(
         f"✅ Generated {len(summaries)} files in: [green]{output_dir.resolve()}[/green]"
     )
+    console.print(f"🗃️  Structured timeline saved to: [green]{jsonl_path}[/green]")
 
 

{fluxloop_cli-0.2.25 → fluxloop_cli-0.2.27}/fluxloop_cli/commands/run.py

@@ -264,15 +264,62 @@ def experiment(
             f"Running {config.name}",
             total=total_runs,
         )
+        multi_turn_total = (
+            config.multi_turn.max_turns
+            if config.multi_turn and config.multi_turn.max_turns
+            else None
+        )
+        turn_task = progress.add_task(
+            "[cyan]Turn 0/0",
+            total=multi_turn_total or 1,
+            visible=False,
+        )
 
         def _progress_callback():
             progress.advance(main_task)
 
+        def _turn_progress_callback(
+            current_turn: int,
+            total_turns: int,
+            message: Optional[str] = None,
+        ) -> None:
+            total = total_turns or 1
+            clamped_turn = max(0, current_turn)
+            if message is None:
+                completed = min(clamped_turn, total)
+                description = f"[cyan]Turn {min(clamped_turn, total)}/{total}: complete"
+                progress.update(
+                    turn_task,
+                    total=total,
+                    completed=completed,
+                    description=description,
+                    visible=False,
+                )
+                return
+
+            if not progress.tasks[turn_task].visible:
+                progress.update(turn_task, visible=True)
+
+            preview = message.replace("\n", " ")
+            if len(preview) > 40:
+                preview = preview[:37] + "..."
+
+            completed = max(0, min(clamped_turn - 1, total))
+            description = f"[cyan]Turn {min(clamped_turn, total)}/{total}: {preview}"
+
+            progress.update(
+                turn_task,
+                total=total,
+                completed=completed,
+                description=description,
+            )
+
         # Run experiment
         try:
             results = asyncio.run(
                 runner.run_experiment(
-                    progress_callback=_progress_callback
+                    progress_callback=_progress_callback,
+                    turn_progress_callback=_turn_progress_callback,
                 )
             )
         except KeyboardInterrupt:

{fluxloop_cli-0.2.25 → fluxloop_cli-0.2.27}/fluxloop_cli/conversation_supervisor.py

@@ -37,13 +37,31 @@ class SupervisorDecision:
         return self.decision == "continue"
 
 
+def _coerce_text(value: Any) -> str:
+    """Convert any value into a safe string representation."""
+
+    if value is None:
+        return ""
+
+    if isinstance(value, str):
+        return value
+
+    if isinstance(value, (dict, list, tuple, set)):
+        try:
+            return json.dumps(value, ensure_ascii=False)
+        except Exception:
+            return str(value)
+
+    return str(value)
+
+
 def format_transcript(turns: Sequence[Dict[str, Any]]) -> str:
     """Render a conversation transcript into a bullet list for supervisor prompts."""
 
     lines: List[str] = []
     for idx, turn in enumerate(turns, start=1):
         role = turn.get("role", "unknown").capitalize()
-        content = turn.get("content") or ""
+        content = _coerce_text(turn.get("content"))
         content = content.strip()
 
         if turn.get("tool_calls"):
@@ -53,7 +71,7 @@ def format_transcript(turns: Sequence[Dict[str, Any]]) -> str:
                 for call in tool_calls:
                     name = call.get("name") or call.get("tool") or "tool"
                     args = call.get("arguments") or call.get("args") or {}
-                    tool_summaries.append(f"{name}({json.dumps(args, ensure_ascii=False)})")
+                    tool_summaries.append(f"{name}({_coerce_text(args)})")
                 if tool_summaries:
                     content = f"{content}\n    [Tool Calls] " + "; ".join(tool_summaries)
         lines.append(f"{idx}. {role}: {content}")

fluxloop_cli-0.2.27/fluxloop_cli/evaluation/artifacts.py

@@ -0,0 +1,74 @@
+"""
+Utilities for working with structured per-trace artifacts produced by `fluxloop parse`.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+
+@dataclass
+class PerTraceRecord:
+    """Structured trace artifact consumed by the evaluation pipeline."""
+
+    data: Dict[str, Any]
+
+    @property
+    def trace(self) -> Dict[str, Any]:
+        """Return the trace payload used for scoring."""
+
+        return self.data
+
+    @property
+    def trace_id(self) -> Optional[str]:
+        return self.data.get("trace_id")
+
+
+def _default_per_trace_path(experiment_dir: Path) -> Path:
+    return experiment_dir / "per_trace_analysis" / "per_trace.jsonl"
+
+
+def load_per_trace_records(
+    experiment_dir: Path,
+    source_path: Optional[Path] = None,
+) -> List[PerTraceRecord]:
+    """
+    Load structured per-trace artifacts from disk.
+
+    Raises:
+        FileNotFoundError: When the per-trace file is missing.
+        ValueError: When the file contains invalid JSON or non-object entries.
+    """
+
+    path = source_path or _default_per_trace_path(experiment_dir)
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Structured per-trace artifacts not found at {path}. "
+            "Run `fluxloop parse` before evaluating."
+        )
+
+    records: List[PerTraceRecord] = []
+    with path.open("r", encoding="utf-8") as handle:
+        for line_no, line in enumerate(handle, start=1):
+            stripped = line.strip()
+            if not stripped:
+                continue
+            try:
+                payload = json.loads(stripped)
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"Invalid JSON in {path} at line {line_no}: {exc}") from exc
+            if not isinstance(payload, dict):
+                raise ValueError(
+                    f"Per-trace entry at line {line_no} must be a JSON object, "
+                    f"but got {type(payload).__name__}"
+                )
+            records.append(PerTraceRecord(data=payload))
+
+    return records
+
+
+__all__ = ["PerTraceRecord", "load_per_trace_records"]
+

{fluxloop_cli-0.2.25 → fluxloop_cli-0.2.27}/fluxloop_cli/evaluation/engine/core.py

@@ -21,6 +21,7 @@ from rich.progress import (
     TimeRemainingColumn,
 )
 
+from ..artifacts import PerTraceRecord, load_per_trace_records
 from ..config import AggregateConfig, EvaluationConfig, EvaluatorConfig
 from ..llm import LLMEvaluationManager, LLMResult
 from ..rules import RuleContext, RuleResult, evaluate_rule
@@ -44,6 +45,7 @@ class EvaluationOptions:
     report_format: Optional[Literal["md", "html", "both"]] = None
     report_template: Optional[Path] = None
     baseline_path: Optional[Path] = None
+    per_trace_path: Optional[Path] = None
 
 
 @dataclass
@@ -66,26 +68,6 @@ class TraceOutcome:
     passed: bool
 
 
-def _load_trace_summaries(path: Path) -> List[Dict[str, Any]]:
-    if not path.exists():
-        raise FileNotFoundError(f"trace_summary.jsonl not found: {path}")
-
-    traces: List[Dict[str, Any]] = []
-    with path.open("r", encoding="utf-8") as handle:
-        for line_no, line in enumerate(handle, start=1):
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                payload = json.loads(line)
-            except json.JSONDecodeError as exc:
-                raise ValueError(
-                    f"Invalid JSON in trace_summary.jsonl at line {line_no}: {exc}"
-                ) from exc
-            traces.append(payload)
-    return traces
-
-
 def _prepare_output_directory(path: Path, overwrite: bool) -> None:
     if path.exists():
         if not overwrite:
@@ -309,11 +291,16 @@ def run_evaluation(
     if not experiment_dir.is_dir():
         raise NotADirectoryError(f"Experiment directory not found: {experiment_dir}")
 
-    trace_summary_path = experiment_dir / "trace_summary.jsonl"
-    traces = _load_trace_summaries(trace_summary_path)
+    per_trace_records: List[PerTraceRecord] = load_per_trace_records(
+        experiment_dir,
+        options.per_trace_path,
+    )
+    traces = [record.trace for record in per_trace_records]
 
     if not traces:
-        raise ValueError("No trace summaries found. Run an experiment before evaluating.")
+        raise ValueError(
+            "No per-trace records available. Run `fluxloop parse` before evaluating."
+        )
 
     _prepare_output_directory(options.output_dir, options.overwrite)
 

{fluxloop_cli-0.2.25 → fluxloop_cli-0.2.27}/fluxloop_cli/evaluation/engine/reporting/html.py

@@ -40,6 +40,7 @@ DEFAULT_TEMPLATE = r"""<!DOCTYPE html>
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta name="report:generated_at" content="[[DATE]]" />
   <title>[[TITLE]]</title>
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css">
   <script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js"></script>
@@ -47,9 +48,19 @@ DEFAULT_TEMPLATE = r"""<!DOCTYPE html>
 <body class="bg-slate-950 text-slate-100">
   <main class="max-w-6xl mx-auto p-8 space-y-6">
     <header class="space-y-6">
-      <div>
-      <h1 class="text-3xl font-bold">[[TITLE]]</h1>
-      <p class="text-sm text-slate-300">Generated at [[DATE]]</p>
+      <div class="flex flex-col gap-4 md:flex-row md:items-center md:justify-between">
+        <div>
+          <h1 class="text-3xl font-bold">[[TITLE]]</h1>
+          <p class="text-sm text-slate-300">[[SUBTITLE]]</p>
+        </div>
+        <a
+          href="https://fluxloop.io/"
+          class="inline-flex items-center gap-2 self-start rounded-full border border-sky-400 px-4 py-2 text-sm font-semibold text-sky-200 transition hover:bg-sky-500/10 focus:outline-none focus:ring-2 focus:ring-sky-400 focus:ring-offset-2 focus:ring-offset-slate-950"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          <span>Built with FluxLoop</span>
+        </a>
       </div>
       <nav class="flex flex-wrap gap-2" role="tablist" aria-label="Report sections">
         <button class="tab-button px-4 py-2 rounded-full bg-sky-500/20 border border-sky-400 text-sky-200 font-semibold" data-tab-button="summary">Executive Summary</button>
@@ -62,6 +73,11 @@ DEFAULT_TEMPLATE = r"""<!DOCTYPE html>
     <section data-tab-panel="summary" class="tab-panel space-y-6">
       <div id="summaryCards" class="grid gap-4 md:grid-cols-2 xl:grid-cols-4"></div>
 
+      <section class="space-y-4">
+        <h2 class="text-xl font-semibold">Evaluation Goal</h2>
+        <div id="evaluationGoal" class="whitespace-pre-wrap rounded-xl border border-slate-800 bg-slate-900 p-4 text-sm text-slate-300"></div>
+      </section>
+
       <section class="space-y-4">
         <h2 class="text-xl font-semibold">Success Criteria</h2>
         <div id="criteriaList" class="space-y-3"></div>
@@ -214,6 +230,21 @@ DEFAULT_TEMPLATE = r"""<!DOCTYPE html>
         .join("");
     }
 
+    function renderEvaluationGoal() {
+      const container = document.getElementById("evaluationGoal");
+      if (!container) return;
+      const goal = summary?.evaluation_goal;
+      if (!goal) {
+        container.textContent = "No evaluation goal provided.";
+        container.classList.remove("text-slate-300");
+        container.classList.add("text-slate-400");
+        return;
+      }
+      container.classList.remove("text-slate-400");
+      container.classList.add("text-slate-300");
+      container.textContent = goal;
+    }
+
     function renderCriteria() {
       const container = document.getElementById("criteriaList");
       if (!container || !criteria || !Object.keys(criteria).length) {
@@ -458,6 +489,7 @@ DEFAULT_TEMPLATE = r"""<!DOCTYPE html>
 
     initTabs();
     renderSummaryCards();
+    renderEvaluationGoal();
     renderCriteria();
     renderRecommendations();
     renderScoreChart();
@@ -471,6 +503,45 @@ DEFAULT_TEMPLATE = r"""<!DOCTYPE html>
 """
 
 
+def _resolve_experiment_label(summary: Dict[str, Any], output_path: Path) -> Optional[str]:
+    def _stringify(value: Any) -> Optional[str]:
+        if value is None:
+            return None
+        if isinstance(value, (list, tuple, set)):
+            parts = [str(item) for item in value if item not in (None, "")]
+            if not parts:
+                return None
+            return ", ".join(parts)
+        if isinstance(value, str):
+            return value.strip() or None
+        return str(value)
+
+    for key in ("experiment_id", "experiment_name"):
+        candidate = _stringify(summary.get(key))
+        if candidate:
+            return candidate
+
+    experiment_meta = summary.get("experiment")
+    if isinstance(experiment_meta, dict):
+        for key in ("name", "id", "label"):
+            candidate = _stringify(experiment_meta.get(key))
+            if candidate:
+                return candidate
+
+    output_dir = output_path.parent
+    if output_dir != output_path:
+        experiment_dir = output_dir.parent
+        if experiment_dir and experiment_dir != output_dir:
+            candidate = _stringify(experiment_dir.name)
+            if candidate:
+                return candidate
+        candidate = _stringify(output_dir.name)
+        if candidate:
+            return candidate
+
+    return None
+
+
 def select_html_template(options: "EvaluationOptions", config: "EvaluationConfig") -> Tuple[str, Optional[str]]:
     if options.report_template:
         template_text = load_template_from_path(options.report_template)
@@ -497,9 +568,19 @@ def write_html_report(
     success_criteria = summary.get("success_criteria_results") or {}
     analysis = summary.get("analysis") or {}
 
+    generated_at = datetime.now(UTC)
+    generated_iso = generated_at.isoformat(timespec="seconds").replace("+00:00", "Z")
+    human_readable = generated_at.strftime("%Y-%m-%d %H:%M:%SZ")
+    experiment_label = _resolve_experiment_label(summary, output_path)
+    subtitle_parts = [f"Generated on {human_readable}"]
+    if experiment_label:
+        subtitle_parts.append(f"Experiment: {experiment_label}")
+    subtitle = " · ".join(subtitle_parts)
+
     replacements = {
-        "[[TITLE]]": summary.get("evaluation_goal") or "FluxLoop Evaluation Report",
-        "[[DATE]]": datetime.now(UTC).isoformat(timespec="seconds").replace("+00:00", "Z"),
+        "[[TITLE]]": "FluxLoop Evaluation Report",
+        "[[DATE]]": generated_iso,
+        "[[SUBTITLE]]": subtitle,
         "[[SUMMARY_JSON]]": json.dumps(summary, ensure_ascii=False),
         "[[PER_TRACE_JSON]]": json.dumps(per_trace_payload, ensure_ascii=False),
         "[[CRITERIA_JSON]]": json.dumps(success_criteria, ensure_ascii=False),