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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluxloop-cli
-Version: 0.2.25
+Version: 0.2.26
 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.26}/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.26}/fluxloop_cli/__init__.py

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

{fluxloop_cli-0.2.25 → fluxloop_cli-0.2.26}/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.26}/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.26}/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.26}/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.26/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.26}/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.26}/fluxloop_cli/runner.py

@@ -125,12 +125,17 @@ class ExperimentRunner:
         except ValueError as exc:
             raise RuntimeError(str(exc)) from exc
 
-    async def run_experiment(self, progress_callback: Optional[Callable] = None) -> Dict[str, Any]:
+    async def run_experiment(
+        self,
+        progress_callback: Optional[Callable] = None,
+        turn_progress_callback: Optional[Callable[[int, int, Optional[str]], None]] = None,
+    ) -> Dict[str, Any]:
         """
         Run the complete experiment.
         
         Args:
             progress_callback: Optional callback for progress updates
+            turn_progress_callback: Optional callback for multi-turn progress updates
             
         Returns:
             Experiment results summary
@@ -157,6 +162,7 @@ class ExperimentRunner:
                         entry,
                         persona,
                         iteration,
+                        turn_progress_callback=turn_progress_callback,
                     )
 
                     if progress_callback:
@@ -173,6 +179,7 @@ class ExperimentRunner:
                             entry,
                             persona,
                             iteration,
+                            turn_progress_callback=turn_progress_callback,
                         )
 
                         if progress_callback:
@@ -285,11 +292,19 @@ class ExperimentRunner:
         variation: Dict[str, Any],
         persona: Optional[PersonaConfig],
         iteration: int,
+        *,
+        turn_progress_callback: Optional[Callable[[int, int, Optional[str]], None]] = None,
     ) -> None:
         """Run a single execution."""
 
         if self._should_use_multi_turn():
-            await self._run_multi_turn(agent_func, variation, persona, iteration)
+            await self._run_multi_turn(
+                agent_func,
+                variation,
+                persona,
+                iteration,
+                turn_progress_callback=turn_progress_callback,
+            )
             return
 
         self.results["total_runs"] += 1
@@ -420,6 +435,8 @@ class ExperimentRunner:
         variation: Dict[str, Any],
         persona: Optional[PersonaConfig],
         iteration: int,
+        *,
+        turn_progress_callback: Optional[Callable[[int, int, Optional[str]], None]] = None,
     ) -> None:
         """Execute a multi-turn conversation using the supervisor loop."""
 
@@ -499,6 +516,18 @@ class ExperimentRunner:
                 turn_count = 0
 
                 while True:
+                    if turn_progress_callback:
+                        preview = (
+                            current_user_input
+                            if isinstance(current_user_input, str)
+                            else str(current_user_input)
+                        )
+                        turn_progress_callback(
+                            turn_count + 1,
+                            multi_cfg.max_turns or 1,
+                            preview,
+                        )
+
                     callback_messages: Dict[str, Any] = {}
 
                     logger.debug(
@@ -641,6 +670,13 @@ class ExperimentRunner:
                 trace_entry["supervisor_response"] = last_decision.raw_response
 
             self.results["traces"].append(trace_entry)
+        finally:
+            if turn_progress_callback:
+                turn_progress_callback(
+                    turn_count,
+                    multi_cfg.max_turns or max(turn_count, 1),
+                    None,
+                )
     
     def _resolve_entry_persona(
         self,

{fluxloop_cli-0.2.25 → fluxloop_cli-0.2.26}/fluxloop_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluxloop-cli
-Version: 0.2.25
+Version: 0.2.26
 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):