devsper 2.1.6__py3-none-any.whl

devsper/intelligence/analysis/run_report.py

@@ -0,0 +1,402 @@
+"""
+RunReport and TaskSummary dataclasses; build from event log and DAG.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from devsper.types.event import Event, events
+from devsper.types.task import TaskStatus
+
+
+@dataclass
+class TaskSummary:
+    task_id: str
+    description: str
+    role: str | None
+    status: TaskStatus
+    duration_seconds: float
+    tools_used: list[str]
+    tool_failures: list[str]
+    tokens_used: int | None
+    retry_count: int
+    error: str | None
+
+
+@dataclass
+class RunReport:
+    run_id: str
+    root_task: str
+    strategy: str
+    started_at: str
+    finished_at: str
+    total_duration_seconds: float
+    total_tasks: int
+    completed_tasks: int
+    failed_tasks: int
+    skipped_tasks: int
+    tasks: list[TaskSummary]
+    critical_path: list[str]
+    bottleneck_task_id: str | None
+    tools_called: int
+    tool_success_rate: float
+    estimated_cost_usd: float | None
+    models_used: list[str]
+    peak_parallelism: int
+    plain_english_analysis: str | None
+    # v1.6
+    model_tier_breakdown: dict[str, int] | None = None  # simple/medium/complex counts
+    estimated_cost_without_routing: float | None = None
+    theoretical_sequential_duration: float | None = None
+    actual_duration: float | None = None
+    parallelism_efficiency: float | None = None
+    # v1.7
+    tasks_critiqued: int = 0
+    tasks_retried_by_critic: int = 0
+    avg_critique_score: float | None = None
+    prefetch_hit_rate: float | None = None
+
+
+def _find_log_path(events_dir: str | Path, run_id: str) -> str | None:
+    """Find events JSONL file for run_id. Returns path or None."""
+    path = Path(events_dir)
+    if not path.is_dir():
+        return None
+    candidate = path / f"{run_id}.jsonl"
+    if candidate.is_file():
+        return str(candidate)
+    for f in path.glob("*.jsonl"):
+        if f.stem == run_id:
+            return str(f)
+    return None
+
+
+def _load_events(log_path: str) -> list[Event]:
+    if not os.path.isfile(log_path):
+        return []
+    out = []
+    with open(log_path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(Event.model_validate_json(line))
+            except Exception:
+                continue
+    return out
+
+
+def _load_dag(events_dir: str | Path, run_id: str) -> tuple[list[dict], list[tuple[str, str]]]:
+    """Load DAG from events_dir / {run_id}_dag.json. Returns (nodes, edges)."""
+    path = Path(events_dir) / f"{run_id}_dag.json"
+    if not path.is_file():
+        return [], []
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    nodes = data.get("nodes", [])
+    edges = [tuple(e) for e in data.get("edges", [])]
+    return nodes, edges
+
+
+def _critical_path_and_bottleneck(
+    task_ids: list[str],
+    edges: list[tuple[str, str]],
+    duration_by_task: dict[str, float],
+) -> tuple[list[str], str | None]:
+    """
+    Compute critical path (longest dependency chain by duration) and bottleneck task.
+    edges: (from_id, to_id) meaning from is dependency of to.
+    """
+    if not task_ids:
+        return [], None
+    pred = {tid: [] for tid in task_ids}
+    succ = {tid: [] for tid in task_ids}
+    for a, b in edges:
+        if a in pred and b in succ:
+            pred[b].append(a)
+            succ[a].append(b)
+    # Topological order (roots first)
+    in_degree = {tid: len(pred[tid]) for tid in task_ids}
+    order = []
+    stack = [tid for tid in task_ids if in_degree[tid] == 0]
+    while stack:
+        n = stack.pop()
+        order.append(n)
+        for s in succ[n]:
+            in_degree[s] -= 1
+            if in_degree[s] == 0:
+                stack.append(s)
+    # Longest path from any root to each node (earliest finish)
+    dist = {tid: duration_by_task.get(tid, 0.0) for tid in task_ids}
+    for n in order:
+        for p in pred[n]:
+            dist[n] = max(dist[n], dist[p] + duration_by_task.get(n, 0.0))
+    # Longest path value and a leaf on that path
+    max_dist = max(dist.values()) if dist else 0.0
+    leaf = next((tid for tid in order if dist[tid] == max_dist), None)
+    if not leaf:
+        return list(order), None
+    # Backtrack to get critical path (path from root to leaf with max total duration)
+    path = []
+    cur = leaf
+    while cur is not None:
+        path.append(cur)
+        best_pred = None
+        best_val = -1.0
+        for p in pred[cur]:
+            v = dist.get(p, 0.0)
+            if v >= best_val:
+                best_val = v
+                best_pred = p
+        cur = best_pred
+    path.reverse()
+    # Bottleneck: task on critical path with highest single-task duration
+    bottleneck = None
+    bottleneck_dur = -1.0
+    for tid in path:
+        d = duration_by_task.get(tid, 0.0)
+        if d > bottleneck_dur:
+            bottleneck_dur = d
+            bottleneck = tid
+    return path, bottleneck
+
+
+def build_report_from_events(run_id: str, events_dir: str | Path) -> RunReport:
+    """
+    Load events from {events_dir}/{run_id}.jsonl (or matching .jsonl), reconstruct
+    timeline, compute critical path and bottleneck, peak parallelism, and cost estimate.
+    """
+    events_dir = Path(events_dir)
+    log_path = _find_log_path(events_dir, run_id)
+    if not log_path:
+        raise FileNotFoundError(f"No event log found for run_id: {run_id!r} (looked in {events_dir})")
+    evs = _load_events(log_path)
+    if not evs:
+        raise ValueError(f"Empty event log for run_id: {run_id!r}")
+
+    evs.sort(key=lambda e: e.timestamp)
+    nodes, edges = _load_dag(events_dir, run_id)
+    node_by_id = {n["id"]: n for n in nodes}
+    # Timeline: TASK_STARTED -> TASK_COMPLETED / TASK_FAILED
+    task_started: dict[str, float] = {}
+    task_ended: dict[str, float] = {}
+    task_status: dict[str, str] = {}
+    task_error: dict[str, str] = {}
+    tools_by_task: dict[str, list[str]] = {}
+    tool_failures_by_task: dict[str, list[str]] = {}
+    task_tier: dict[str, str] = {}  # v1.6: task_id -> simple|medium|complex
+    root_task = ""
+    started_ts: str | None = None
+    finished_ts: str | None = None
+    strategy = ""
+    # v1.7
+    tasks_critiqued = 0
+    tasks_retried_by_critic = 0
+    critique_scores: list[float] = []
+    prefetch_hits = 0
+    prefetch_misses = 0
+
+    for e in evs:
+        typ = e.type.value if hasattr(e.type, "value") else str(e.type)
+        payload = e.payload or {}
+        task_id = (payload.get("task_id") or "").strip()
+        ts = e.timestamp
+        ts_str = ts.isoformat() if hasattr(ts, "isoformat") else str(ts)
+
+        if typ == "swarm_started":
+            root_task = (payload.get("user_task") or "")[:500]
+            if not started_ts:
+                started_ts = ts_str
+        elif typ == "task_started" and task_id:
+            task_started[task_id] = ts.timestamp() if hasattr(ts, "timestamp") else 0.0
+        elif typ == "task_completed" and task_id:
+            task_ended[task_id] = ts.timestamp() if hasattr(ts, "timestamp") else 0.0
+            task_status[task_id] = "completed"
+        elif typ == "task_failed" and task_id:
+            task_ended[task_id] = ts.timestamp() if hasattr(ts, "timestamp") else 0.0
+            task_status[task_id] = "failed"
+            task_error[task_id] = payload.get("error") or "Unknown error"
+        elif typ == "tool_called" and task_id:
+            tool = payload.get("tool") or "unknown"
+            tools_by_task.setdefault(task_id, []).append(tool)
+        elif typ == "task_model_selected" and task_id:
+            task_tier[task_id] = payload.get("tier") or "medium"
+        elif typ == "task_critiqued" and task_id:
+            tasks_critiqued += 1
+            score = payload.get("score")
+            if score is not None:
+                critique_scores.append(float(score))
+            if payload.get("retry_requested"):
+                tasks_retried_by_critic += 1
+        elif typ == "prefetch_hit":
+            prefetch_hits += 1
+        elif typ == "prefetch_miss":
+            prefetch_misses += 1
+        elif typ == "swarm_finished":
+            finished_ts = ts_str
+
+    if not started_ts:
+        started_ts = evs[0].timestamp.isoformat() if evs else ""
+    if not finished_ts:
+        finished_ts = evs[-1].timestamp.isoformat() if evs else ""
+
+    # All task ids from DAG + any from events not in DAG
+    all_task_ids = set(node_by_id.keys()) | set(task_started.keys()) | set(task_ended.keys())
+    duration_by_task: dict[str, float] = {}
+    for tid in all_task_ids:
+        start = task_started.get(tid)
+        end = task_ended.get(tid)
+        if start is not None and end is not None:
+            duration_by_task[tid] = max(0.0, end - start)
+        else:
+            duration_by_task[tid] = 0.0
+
+    critical_path, bottleneck_task_id = _critical_path_and_bottleneck(
+        list(all_task_ids), edges, duration_by_task
+    )
+
+    # Peak parallelism: max overlapping RUNNING windows
+    intervals: list[tuple[float, float]] = []
+    for tid in all_task_ids:
+        s = task_started.get(tid)
+        e = task_ended.get(tid)
+        if s is not None and e is not None:
+            intervals.append((s, e))
+    peak_parallelism = 0
+    if intervals:
+        points = []
+        for a, b in intervals:
+            points.append((a, 1))
+            points.append((b, -1))
+        points.sort(key=lambda x: (x[0], -x[1]))
+        cur = 0
+        for _t, delta in points:
+            cur += delta
+            peak_parallelism = max(peak_parallelism, cur)
+
+    # Build TaskSummary list (order: by first appearance in events / DAG)
+    seen = set()
+    task_order = []
+    for e in evs:
+        p = e.payload or {}
+        tid = (p.get("task_id") or "").strip()
+        if tid and tid not in seen and (tid in node_by_id or tid in task_status):
+            seen.add(tid)
+            task_order.append(tid)
+    for nid in node_by_id:
+        if nid not in seen:
+            task_order.append(nid)
+            seen.add(nid)
+
+    status_enum = {
+        "completed": TaskStatus.COMPLETED,
+        "failed": TaskStatus.FAILED,
+        "running": TaskStatus.RUNNING,
+        "pending": TaskStatus.PENDING,
+    }
+    tasks_list: list[TaskSummary] = []
+    for tid in task_order:
+        desc = (node_by_id.get(tid) or {}).get("description") or tid
+        st = task_status.get(tid, "pending")
+        if tid not in task_started and tid not in task_ended and tid in node_by_id:
+            st = "skipped"
+        status = status_enum.get(st, TaskStatus.PENDING)
+        dur = duration_by_task.get(tid, 0.0)
+        tools = list(tools_by_task.get(tid, []))
+        tool_failures = list(tool_failures_by_task.get(tid, []))
+        tasks_list.append(
+            TaskSummary(
+                task_id=tid,
+                description=desc,
+                role=None,
+                status=status,
+                duration_seconds=dur,
+                tools_used=tools,
+                tool_failures=tool_failures,
+                tokens_used=None,
+                retry_count=0,
+                error=task_error.get(tid),
+            )
+        )
+
+    completed_tasks = sum(1 for t in tasks_list if t.status == TaskStatus.COMPLETED)
+    failed_tasks = sum(1 for t in tasks_list if t.status == TaskStatus.FAILED)
+    total_tasks = len(tasks_list)
+    skipped_tasks = max(0, total_tasks - completed_tasks - failed_tasks)
+
+    tools_called = sum(len(t.tools_used) for t in tasks_list)
+    tool_fail_count = sum(len(t.tool_failures) for t in tasks_list)
+    tool_success_rate = (
+        (100.0 * (tools_called - tool_fail_count) / tools_called)
+        if tools_called else 100.0
+    )
+
+    total_duration_seconds = 0.0
+    if evs:
+        t0 = evs[0].timestamp
+        t1 = evs[-1].timestamp
+        total_duration_seconds = (t1 - t0).total_seconds() if hasattr(t0, "__sub__") else 0.0
+
+    # Cost estimate
+    from devsper.intelligence.analysis.cost_estimator import CostEstimator
+    estimated_cost_usd = CostEstimator.estimate(tasks_list, [])
+
+    # v1.6: model tier breakdown
+    model_tier_breakdown: dict[str, int] = {}
+    for tid in task_tier:
+        t = task_tier[tid]
+        model_tier_breakdown[t] = model_tier_breakdown.get(t, 0) + 1
+
+    # v1.6: theoretical sequential duration and parallelism efficiency
+    theoretical_sequential_duration = sum(duration_by_task.values())
+    actual_duration = total_duration_seconds
+    parallelism_efficiency = (
+        (actual_duration / theoretical_sequential_duration)
+        if theoretical_sequential_duration and theoretical_sequential_duration > 0
+        else None
+    )
+
+    # v1.6: estimated cost without routing (placeholder; full impl would need per-task model)
+    estimated_cost_without_routing = None
+
+    return RunReport(
+        run_id=run_id,
+        root_task=root_task or "unknown",
+        strategy=strategy or "unknown",
+        started_at=started_ts or "",
+        finished_at=finished_ts or "",
+        total_duration_seconds=max(0.0, total_duration_seconds),
+        total_tasks=total_tasks,
+        completed_tasks=completed_tasks,
+        failed_tasks=failed_tasks,
+        skipped_tasks=skipped_tasks,
+        tasks=tasks_list,
+        critical_path=critical_path,
+        bottleneck_task_id=bottleneck_task_id,
+        tools_called=tools_called,
+        tool_success_rate=tool_success_rate,
+        estimated_cost_usd=estimated_cost_usd,
+        models_used=[],
+        peak_parallelism=peak_parallelism,
+        plain_english_analysis=None,
+        model_tier_breakdown=model_tier_breakdown or None,
+        estimated_cost_without_routing=estimated_cost_without_routing,
+        theoretical_sequential_duration=theoretical_sequential_duration if theoretical_sequential_duration else None,
+        actual_duration=actual_duration,
+        parallelism_efficiency=parallelism_efficiency,
+        tasks_critiqued=tasks_critiqued,
+        tasks_retried_by_critic=tasks_retried_by_critic,
+        avg_critique_score=(
+            sum(critique_scores) / len(critique_scores) if critique_scores else None
+        ),
+        prefetch_hit_rate=(
+            prefetch_hits / (prefetch_hits + prefetch_misses)
+            if (prefetch_hits + prefetch_misses) > 0
+            else None
+        ),
+    )

devsper/intelligence/learning_engine.py

@@ -0,0 +1,92 @@
+"""
+Learning engine: analyze previous swarm runs (telemetry + memory) to improve planning.
+
+Detects: which tasks fail, slow tools, patterns. Can adjust planner prompts or suggest optimizations.
+"""
+
+import os
+from pathlib import Path
+
+from devsper.runtime.telemetry import collect_telemetry
+from devsper.memory.memory_store import get_default_store
+from devsper.memory.memory_types import MemoryType
+
+
+class LearningEngine:
+    """
+    Analyze past runs via telemetry and memory to suggest improvements:
+    failing tasks, slow tools, planner prompt adjustments.
+    """
+
+    def __init__(self, events_folder: str = ".devsper/events", memory_store=None) -> None:
+        self.events_folder = events_folder
+        self.memory_store = memory_store or get_default_store()
+
+    def analyze_telemetry(self, log_path: str | None = None) -> dict:
+        """
+        Collect telemetry from an event log. If log_path is None, use latest from events_folder.
+        Returns dict with tasks_completed, tasks_failed, avg_task_duration_seconds, etc.
+        """
+        if log_path is None:
+            log_path = self._latest_log_path()
+        if not log_path or not os.path.exists(log_path):
+            return {
+                "tasks_completed": 0,
+                "tasks_failed": 0,
+                "avg_task_duration_seconds": 0.0,
+                "avg_agent_latency_seconds": 0.0,
+                "max_concurrency": 0,
+                "task_success_rate": 0.0,
+            }
+        return collect_telemetry(log_path)
+
+    def _latest_log_path(self) -> str | None:
+        """Return path to most recent events jsonl in events_folder."""
+        if not os.path.isdir(self.events_folder):
+            return None
+        files = list(Path(self.events_folder).glob("events_*.jsonl"))
+        if not files:
+            return None
+        files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+        return str(files[0])
+
+    def get_failure_patterns(self, log_path: str | None = None) -> list[str]:
+        """
+        Return list of suggested failure patterns (e.g. "high failure rate", "slow tasks").
+        """
+        tele = self.analyze_telemetry(log_path)
+        patterns = []
+        if tele.get("tasks_failed", 0) > 0 and tele.get("task_success_rate", 1) < 0.8:
+            patterns.append("high_failure_rate")
+        if tele.get("avg_task_duration_seconds", 0) > 60:
+            patterns.append("slow_tasks")
+        if tele.get("avg_agent_latency_seconds", 0) > 30:
+            patterns.append("slow_agent_latency")
+        return patterns
+
+    def get_planner_suggestions(self, log_path: str | None = None) -> str:
+        """
+        Return a string of suggestions to add to planner context (e.g. "Avoid very long tasks").
+        """
+        patterns = self.get_failure_patterns(log_path)
+        if not patterns:
+            return ""
+        suggestions = []
+        if "high_failure_rate" in patterns:
+            suggestions.append("Consider breaking tasks into smaller steps to reduce failures.")
+        if "slow_tasks" in patterns:
+            suggestions.append("Previous runs had long-running tasks; consider shorter subtasks.")
+        if "slow_agent_latency" in patterns:
+            suggestions.append("Agent latency was high; consider fewer tool-heavy steps.")
+        return " ".join(suggestions)
+
+    def summarize_memory_for_learning(self, limit: int = 50) -> dict[str, int]:
+        """
+        Summarize stored memory by type (for learning dashboard).
+        """
+        records = self.memory_store.list_memory(limit=limit)
+        by_type: dict[str, int] = {}
+        for r in records:
+            k = r.memory_type.value
+            by_type[k] = by_type.get(k, 0) + 1
+        return by_type

devsper/intelligence/strategies/__init__.py

@@ -0,0 +1,23 @@
+"""Strategy-based planning: map ExecutionStrategy to DAG-producing strategies."""
+
+from devsper.intelligence.strategy_selector import ExecutionStrategy
+from devsper.intelligence.strategies.base import Strategy
+from devsper.intelligence.strategies.code_analysis_strategy import CodeAnalysisStrategy
+from devsper.intelligence.strategies.data_science_strategy import DataScienceStrategy
+from devsper.intelligence.strategies.document_pipeline_strategy import DocumentPipelineStrategy
+from devsper.intelligence.strategies.experiment_strategy import ExperimentStrategy
+from devsper.intelligence.strategies.research_strategy import ResearchStrategy
+
+STRATEGY_REGISTRY: dict[ExecutionStrategy, type[Strategy]] = {
+    ExecutionStrategy.RESEARCH: ResearchStrategy,
+    ExecutionStrategy.CODE_ANALYSIS: CodeAnalysisStrategy,
+    ExecutionStrategy.DATA_ANALYSIS: DataScienceStrategy,
+    ExecutionStrategy.DOCUMENT: DocumentPipelineStrategy,
+    ExecutionStrategy.EXPERIMENT: ExperimentStrategy,
+}
+
+
+def get_strategy_for(strategy_enum: ExecutionStrategy) -> Strategy | None:
+    """Return a strategy instance for the given enum, or None for GENERAL."""
+    cls = STRATEGY_REGISTRY.get(strategy_enum)
+    return cls() if cls else None

devsper/intelligence/strategies/base.py

@@ -0,0 +1,14 @@
+"""Base strategy: produce a DAG of tasks from a root task."""
+
+from abc import ABC, abstractmethod
+
+from devsper.types.task import Task
+
+
+class Strategy(ABC):
+    """Strategy produces a list of tasks with dependencies (DAG) for the scheduler."""
+
+    @abstractmethod
+    def plan(self, root_task: Task) -> list[Task]:
+        """Return subtasks with dependencies. Empty list means fall back to LLM planner."""
+        ...

devsper/intelligence/strategies/code_analysis_strategy.py

@@ -0,0 +1,33 @@
+"""Code analysis strategy: DAG for repository analysis."""
+
+import secrets
+
+from devsper.types.task import Task
+
+from devsper.intelligence.strategies.base import Strategy
+
+
+def _short_id() -> str:
+    return secrets.token_hex(4)
+
+
+class CodeAnalysisStrategy(Strategy):
+    """Code/repo pipeline: index -> structure -> dependencies -> report."""
+
+    def plan(self, root_task: Task) -> list[Task]:
+        steps = [
+            ("index", "Index the codebase and identify main modules and entry points."),
+            ("structure", "Analyze project structure and layout."),
+            ("dependencies", "Map dependencies and external imports."),
+            ("report", "Produce an architecture and code analysis report."),
+        ]
+        task_ids: list[str] = []
+        tasks: list[Task] = []
+        for i, (_, desc) in enumerate(steps):
+            tid = _short_id()
+            task_ids.append(tid)
+            deps = [task_ids[i - 1]] if i > 0 else []
+            description = f"{root_task.description}\n\nStep: {desc}" if i == 0 else desc
+            t = Task(id=tid, description=description, dependencies=deps)
+            tasks.append(t)
+        return tasks

devsper/intelligence/strategies/data_science_strategy.py

@@ -0,0 +1,33 @@
+"""Data science strategy: DAG for dataset workflow."""
+
+import secrets
+
+from devsper.types.task import Task
+
+from devsper.intelligence.strategies.base import Strategy
+
+
+def _short_id() -> str:
+    return secrets.token_hex(4)
+
+
+class DataScienceStrategy(Strategy):
+    """Data science pipeline: load -> profile -> analyze -> visualize."""
+
+    def plan(self, root_task: Task) -> list[Task]:
+        steps = [
+            ("load", "Load and validate the dataset."),
+            ("profile", "Generate data profile and basic statistics."),
+            ("analyze", "Run analysis and identify patterns or models."),
+            ("visualize", "Create visualizations and summary reports."),
+        ]
+        task_ids: list[str] = []
+        tasks: list[Task] = []
+        for i, (_, desc) in enumerate(steps):
+            tid = _short_id()
+            task_ids.append(tid)
+            deps = [task_ids[i - 1]] if i > 0 else []
+            description = f"{root_task.description}\n\nStep: {desc}" if i == 0 else desc
+            t = Task(id=tid, description=description, dependencies=deps)
+            tasks.append(t)
+        return tasks

devsper/intelligence/strategies/document_pipeline_strategy.py

@@ -0,0 +1,33 @@
+"""Document pipeline strategy: DAG for document processing."""
+
+import secrets
+
+from devsper.types.task import Task
+
+from devsper.intelligence.strategies.base import Strategy
+
+
+def _short_id() -> str:
+    return secrets.token_hex(4)
+
+
+class DocumentPipelineStrategy(Strategy):
+    """Document pipeline: ingest -> extract -> link -> report."""
+
+    def plan(self, root_task: Task) -> list[Task]:
+        steps = [
+            ("ingest", "Ingest documents and extract raw text/metadata."),
+            ("extract", "Extract entities, topics, and structure from documents."),
+            ("link", "Link entities and build cross-document references."),
+            ("report", "Produce a document intelligence report."),
+        ]
+        task_ids: list[str] = []
+        tasks: list[Task] = []
+        for i, (_, desc) in enumerate(steps):
+            tid = _short_id()
+            task_ids.append(tid)
+            deps = [task_ids[i - 1]] if i > 0 else []
+            description = f"{root_task.description}\n\nStep: {desc}" if i == 0 else desc
+            t = Task(id=tid, description=description, dependencies=deps)
+            tasks.append(t)
+        return tasks

devsper/intelligence/strategies/experiment_strategy.py

@@ -0,0 +1,33 @@
+"""Experiment strategy: DAG for experiments (setup -> run -> compare -> report)."""
+
+import secrets
+
+from devsper.types.task import Task
+
+from devsper.intelligence.strategies.base import Strategy
+
+
+def _short_id() -> str:
+    return secrets.token_hex(4)
+
+
+class ExperimentStrategy(Strategy):
+    """Experiment pipeline: setup -> run -> compare -> report."""
+
+    def plan(self, root_task: Task) -> list[Task]:
+        steps = [
+            ("setup", "Set up experiment parameters and environment."),
+            ("run", "Run the experiment or parameter sweep."),
+            ("compare", "Compare results and run statistical checks."),
+            ("report", "Generate experiment report and recommendations."),
+        ]
+        task_ids: list[str] = []
+        tasks: list[Task] = []
+        for i, (_, desc) in enumerate(steps):
+            tid = _short_id()
+            task_ids.append(tid)
+            deps = [task_ids[i - 1]] if i > 0 else []
+            description = f"{root_task.description}\n\nStep: {desc}" if i == 0 else desc
+            t = Task(id=tid, description=description, dependencies=deps)
+            tasks.append(t)
+        return tasks