devsper 2.1.6__py3-none-any.whl

devsper/workflow/conditions.py

@@ -0,0 +1,157 @@
+"""Evaluate if: expressions safely (no eval)."""
+
+import re
+from typing import Any
+
+from devsper.workflow.context import WorkflowContext
+
+
+class WorkflowConditionError(Exception):
+    """Raised when a condition expression cannot be parsed or is invalid."""
+
+    pass
+
+
+# Pattern: steps.<id>.<field> <op> <value>
+# id/field: word chars and underscore
+# op: ==, !=, >=, <=, >, <, in, not in
+# value: quoted string, int, float, true/false
+_EXPR_PATTERN = re.compile(
+    r"^\s*steps\.([a-zA-Z_][a-zA-Z0-9_]*)\.([a-zA-Z_][a-zA-Z0-9_]*)\s*"
+    r"(==|!=|>=|<=|>|<|in|not\s+in)\s*(.+)\s*$",
+    re.IGNORECASE,
+)
+
+
+def _parse_value(raw: str) -> Any:
+    raw = raw.strip()
+    if not raw:
+        raise WorkflowConditionError("Empty value in condition")
+    # List: [ ... ]
+    if raw.startswith("[") and raw.endswith("]"):
+        inner = raw[1:-1].strip()
+        if not inner:
+            return []
+        return [_parse_value(p.strip()) for p in _split_top_level(inner, ",")]
+    # Quoted string
+    if (raw.startswith("'") and raw.endswith("'")) or (
+        raw.startswith('"') and raw.endswith('"')
+    ):
+        return raw[1:-1].replace("\\'", "'").replace('\\"', '"')
+    # Bool
+    if raw.lower() == "true":
+        return True
+    if raw.lower() == "false":
+        return False
+    # Int
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    # Float
+    try:
+        return float(raw)
+    except ValueError:
+        pass
+    raise WorkflowConditionError(f"Cannot parse value: {raw!r}")
+
+
+def _split_top_level(s: str, sep: str) -> list[str]:
+    """Split by sep only at top level (ignore inside quotes/brackets)."""
+    parts: list[str] = []
+    current: list[str] = []
+    depth = 0
+    in_quote = None
+    i = 0
+    while i < len(s):
+        c = s[i]
+        if in_quote:
+            if c == in_quote and (i == 0 or s[i - 1] != "\\"):
+                in_quote = None
+            current.append(c)
+        elif c in ("'", '"'):
+            in_quote = c
+            current.append(c)
+        elif c in ("[", "(", "{"):
+            depth += 1
+            current.append(c)
+        elif c in ("]", ")", "}"):
+            depth -= 1
+            current.append(c)
+        elif depth == 0 and s[i : i + len(sep)] == sep:
+            parts.append("".join(current))
+            current = []
+            i += len(sep) - 1
+        else:
+            current.append(c)
+        i += 1
+    parts.append("".join(current))
+    return parts
+
+
+def evaluate_condition(expression: str, context: WorkflowContext) -> bool:
+    """
+    Parse expressions of the form: steps.<id>.<field> <op> <value>
+    Supported ops: ==, !=, >, <, >=, <=, in, not in
+    On missing step/field: return False (conservative — skip rather than crash).
+    On parse error: raise WorkflowConditionError.
+    """
+    expression = expression.strip()
+    if not expression:
+        raise WorkflowConditionError("Empty condition expression")
+
+    m = _EXPR_PATTERN.match(expression)
+    if not m:
+        raise WorkflowConditionError(
+            f"Condition must match: steps.<step_id>.<field> <op> <value>. Got: {expression!r}"
+        )
+
+    step_id, field, op, value_str = m.group(1), m.group(2), m.group(3), m.group(4)
+    op = op.lower().replace(" ", "")
+
+    left = context.get_field(step_id, field)
+    # Missing step or field → conservative False
+    if left is None:
+        return False
+
+    try:
+        right = _parse_value(value_str)
+    except WorkflowConditionError:
+        raise
+
+    # Type coercion for comparison: if right is int/float and left is str, try to coerce left
+    if isinstance(right, (int, float)) and isinstance(left, str):
+        try:
+            if isinstance(right, int):
+                left = int(left)
+            else:
+                left = float(left)
+        except (ValueError, TypeError):
+            pass
+    if isinstance(right, bool) and isinstance(left, str):
+        left = left.lower() in ("true", "1", "yes")
+
+    if op == "==":
+        return left == right
+    if op == "!=":
+        return left != right
+    if op == ">":
+        return left > right  # type: ignore[return-value]
+    if op == "<":
+        return left < right  # type: ignore[return-value]
+    if op == ">=":
+        return left >= right  # type: ignore[return-value]
+    if op == "<=":
+        return left <= right  # type: ignore[return-value]
+    if op == "in":
+        if not isinstance(right, (list, tuple, str)):
+            raise WorkflowConditionError(f"Right side of 'in' must be list or str, got {type(right)}")
+        return left in right  # type: ignore[operator]
+    if op == "notin":
+        if not isinstance(right, (list, tuple, str)):
+            raise WorkflowConditionError(
+                f"Right side of 'not in' must be list or str, got {type(right)}"
+            )
+        return left not in right  # type: ignore[operator]
+
+    raise WorkflowConditionError(f"Unsupported operator: {op!r}")

devsper/workflow/context.py

@@ -0,0 +1,108 @@
+"""WorkflowContext: typed output passing between steps."""
+
+import re
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class WorkflowTemplateError(Exception):
+    """Raised when a template reference cannot be resolved."""
+
+    pass
+
+
+class StepResult(BaseModel):
+    step_id: str
+    raw_result: str  # full agent output
+    structured: dict | None = None  # parsed output_schema result, if defined
+    skipped: bool = False
+    error: str | None = None
+    duration_seconds: float = 0.0
+
+
+class WorkflowContext:
+    def __init__(self, inputs: dict[str, Any]) -> None:
+        self.inputs = inputs
+        self.steps: dict[str, StepResult] = {}
+
+    def record(self, step_id: str, result: StepResult) -> None:
+        self.steps[step_id] = result
+
+    def resolve_template(self, template: str) -> str:
+        """
+        Replace {input.field} with self.inputs[field].
+        Replace {steps.step_id.result} with self.steps[step_id].raw_result.
+        Replace {steps.step_id.field} with self.steps[step_id].structured[field].
+        Raise WorkflowTemplateError if reference not found.
+        """
+        # Match {input.NAME} or {steps.STEP_ID.result} or {steps.STEP_ID.FIELD}
+        pattern = re.compile(
+            r"\{(\w+)\.([^}]+)\}"
+        )  # group 1: input|steps, group 2: rest
+
+        def repl(match: re.Match[str]) -> str:
+            prefix, rest = match.group(1), match.group(2)
+            if prefix == "input":
+                if rest not in self.inputs:
+                    raise WorkflowTemplateError(
+                        f"Template references input.{rest} but input {rest!r} is not provided. "
+                        f"Available: {list(self.inputs.keys())}"
+                    )
+                val = self.inputs[rest]
+                return str(val) if val is not None else ""
+            if prefix == "steps":
+                part = rest.split(".", 1)
+                if len(part) != 2:
+                    raise WorkflowTemplateError(
+                        f"Invalid steps reference: {match.group(0)}. "
+                        "Use steps.<step_id>.result or steps.<step_id>.<field>"
+                    )
+                step_id, field = part[0], part[1]
+                if step_id not in self.steps:
+                    raise WorkflowTemplateError(
+                        f"Template references steps.{step_id}.{field} but step {step_id!r} "
+                        f"has not run yet or does not exist. Available: {list(self.steps.keys())}"
+                    )
+                sr = self.steps[step_id]
+                if field == "result":
+                    return sr.raw_result or ""
+                if sr.structured is not None and field in sr.structured:
+                    val = sr.structured[field]
+                    return str(val) if val is not None else ""
+                raise WorkflowTemplateError(
+                    f"Template references steps.{step_id}.{field} but step {step_id!r} "
+                    f"has no structured field {field!r}. "
+                    f"Available: result, or {list(sr.structured.keys()) if sr.structured else []}"
+                )
+            raise WorkflowTemplateError(f"Unknown template prefix: {prefix!r}")
+
+        return pattern.sub(repl, template)
+
+    def get_field(self, step_id: str, field: str) -> Any:
+        """Used by condition evaluator. Returns None if step/field missing."""
+        if step_id not in self.steps:
+            return None
+        sr = self.steps[step_id]
+        if field == "result":
+            return sr.raw_result
+        if sr.structured is not None and field in sr.structured:
+            return sr.structured[field]
+        return None
+
+    def to_summary(self) -> dict[str, Any]:
+        """Serializable summary for output/replay."""
+        steps_summary: dict[str, dict[str, Any]] = {}
+        for sid, sr in self.steps.items():
+            steps_summary[sid] = {
+                "step_id": sr.step_id,
+                "skipped": sr.skipped,
+                "error": sr.error,
+                "duration_seconds": sr.duration_seconds,
+                "has_result": bool(sr.raw_result),
+                "has_structured": sr.structured is not None,
+            }
+        return {
+            "inputs": dict(self.inputs),
+            "steps": steps_summary,
+        }

devsper/workflow/loader.py

@@ -0,0 +1,156 @@
+"""Load workflow definitions from workflow.devsper.toml or devsper.toml."""
+
+import secrets
+from pathlib import Path
+from typing import Any
+
+import tomllib
+
+from devsper.workflow.schema import (
+    OutputField,
+    StepCondition,
+    WorkflowDefinition,
+    WorkflowStep,
+)
+
+
+def _find_workflow_file() -> Path | None:
+    cwd = Path.cwd()
+    for base in (cwd, cwd.parent):
+        for name in ("workflow.devsper.toml", "devsper.toml"):
+            p = base / name
+            if p.is_file():
+                return p
+    return None
+
+
+def _load_toml(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except Exception:
+        return {}
+
+
+def _workflow_from_legacy_steps(steps: list[str]) -> WorkflowDefinition:
+    """Wrap a list of task strings into a WorkflowDefinition with auto-generated step ids."""
+    workflow_steps = []
+    for i, task in enumerate(steps):
+        step_id = f"step_{secrets.token_hex(3)}"
+        workflow_steps.append(
+            WorkflowStep(
+                id=step_id,
+                task=task,
+                depends_on=[workflow_steps[-1].id] if workflow_steps else [],
+            )
+        )
+    return WorkflowDefinition(
+        name="legacy",
+        description="Legacy workflow from list of steps",
+        version="1.0",
+        steps=workflow_steps,
+        inputs=[],
+    )
+
+
+def _step_dict_to_model(d: dict[str, Any]) -> WorkflowStep:
+    """Convert a raw step dict (from TOML) to WorkflowStep."""
+    # TOML may have "if" as key; Pydantic expects alias "if" -> if_
+    raw = dict(d)
+    if "if" in raw and isinstance(raw["if"], dict):
+        raw["if"] = StepCondition(expression=raw["if"].get("expression", ""))
+    elif "if" in raw and isinstance(raw["if"], str):
+        raw["if"] = StepCondition(expression=raw["if"])
+    if "output_schema" in raw and isinstance(raw["output_schema"], list):
+        raw["output_schema"] = [
+            OutputField(**f) if isinstance(f, dict) else f for f in raw["output_schema"]
+        ]
+    return WorkflowStep(**raw)
+
+
+def _workflow_dict_to_definition(name: str, raw: dict[str, Any]) -> WorkflowDefinition:
+    """Convert raw workflow dict to WorkflowDefinition."""
+    steps_raw = raw.get("steps") or []
+    if not steps_raw:
+        return WorkflowDefinition(
+            name=name,
+            description=raw.get("description"),
+            version=str(raw.get("version", "1.0")),
+            steps=[],
+            inputs=raw.get("inputs") or [],
+        )
+    # Legacy: list of strings
+    if all(isinstance(s, str) for s in steps_raw):
+        wf = _workflow_from_legacy_steps(steps_raw)
+        wf = WorkflowDefinition(
+            name=name,
+            description=raw.get("description") or wf.description,
+            version=str(raw.get("version", "1.0")),
+            steps=wf.steps,
+            inputs=raw.get("inputs") or [],
+        )
+        return wf
+    # New format: list of step dicts
+    steps = []
+    for s in steps_raw:
+        if isinstance(s, dict):
+            steps.append(_step_dict_to_model(s))
+        else:
+            steps.append(s)
+    inputs_raw = raw.get("inputs") or []
+    inputs = [OutputField(**f) if isinstance(f, dict) else f for f in inputs_raw]
+    return WorkflowDefinition(
+        name=name,
+        description=raw.get("description"),
+        version=str(raw.get("version", "1.0")),
+        steps=steps,
+        inputs=inputs,
+    )
+
+
+def load_workflow(name: str, config_path: Path | None = None) -> WorkflowDefinition | None:
+    """
+    Load workflow by name. Returns WorkflowDefinition (Pydantic model).
+    If config_path is given, read that file; else discover workflow.devsper.toml / devsper.toml.
+    Legacy: if steps are a list of strings, they are wrapped in a WorkflowDefinition with
+    auto-generated step ids and sequential dependencies.
+    """
+    path = config_path or _find_workflow_file()
+    if not path:
+        return None
+    data = _load_toml(path)
+    raw: dict[str, Any] | None = None
+    # Single [workflow] section
+    wf = data.get("workflow")
+    if isinstance(wf, dict) and wf.get("name") == name:
+        raw = {"name": name, **wf}
+    if raw is None:
+        for key, val in data.items():
+            if key.startswith("workflow.") and isinstance(val, dict):
+                if val.get("name") == name or key == f"workflow.{name}":
+                    raw = {"name": name, **val}
+                    break
+    if not raw:
+        return None
+    return _workflow_dict_to_definition(name, raw)
+
+
+def list_workflows(config_path: Path | None = None) -> list[str]:
+    """Return list of workflow identifiers (name or key suffix) that load_workflow() accepts."""
+    path = config_path or _find_workflow_file()
+    if not path:
+        return []
+    data = _load_toml(path)
+    names: list[str] = []
+    wf = data.get("workflow")
+    if isinstance(wf, dict) and wf.get("name"):
+        names.append(str(wf["name"]))
+    for key, val in data.items():
+        if key.startswith("workflow.") and isinstance(val, dict):
+            # Use key suffix so load_workflow(key_suffix) works
+            key_suffix = key.removeprefix("workflow.")
+            if key_suffix and key_suffix not in names:
+                names.append(key_suffix)
+    return list(dict.fromkeys(names))

devsper/workflow/resolver.py

@@ -0,0 +1,109 @@
+"""Resolve step dependencies into execution order (waves)."""
+
+from collections import deque
+
+from devsper.workflow.schema import WorkflowStep
+
+
+class WorkflowCycleError(Exception):
+    """Raised when depends_on forms a cycle."""
+
+    def __init__(self, cycle: list[str]) -> None:
+        self.cycle = cycle
+        super().__init__(f"Dependency cycle: {' -> '.join(cycle)}")
+
+
+def build_execution_order(steps: list[WorkflowStep]) -> list[list[WorkflowStep]]:
+    """
+    Topological sort of steps using depends_on edges.
+    Returns list of "waves"; steps in the same wave can run in parallel.
+    Steps with no depends_on are in wave 0.
+    Raises WorkflowCycleError with the cycle path if a cycle is detected.
+    """
+    step_map = {s.id: s for s in steps}
+    # in_degree[s] = number of dependencies of s (steps s waits for)
+    in_degree = {s.id: len(s.depends_on) for s in steps}
+    # dependants[dep] = list of step ids that depend on dep
+    dependants: dict[str, list[str]] = {s.id: [] for s in steps}
+    for s in steps:
+        for dep in s.depends_on:
+            dependants[dep].append(s.id)
+
+    waves: list[list[WorkflowStep]] = []
+    queue: deque[str] = deque(sid for sid, d in in_degree.items() if d == 0)
+    remaining = set(step_map.keys())
+
+    while queue:
+        wave_ids: list[str] = list(queue)
+        queue.clear()
+        for sid in wave_ids:
+            remaining.discard(sid)
+            for nxt in dependants[sid]:
+                in_degree[nxt] -= 1
+                if in_degree[nxt] == 0:
+                    queue.append(nxt)
+        waves.append([step_map[sid] for sid in wave_ids])
+
+    if remaining:
+        # Cycle: find one
+        cycle = _find_cycle(steps)
+        raise WorkflowCycleError(cycle)
+
+    return waves
+
+
+def _find_cycle(steps: list[WorkflowStep]) -> list[str]:
+    """Return one cycle as list of step ids."""
+    step_map = {s.id: s for s in steps}
+    visited: set[str] = set()
+    path: list[str] = []
+    path_set: set[str] = set()
+    cycle_start: str | None = None
+
+    def dfs(sid: str) -> bool:
+        nonlocal cycle_start
+        visited.add(sid)
+        path.append(sid)
+        path_set.add(sid)
+        step = step_map.get(sid)
+        if step:
+            for dep in step.depends_on:
+                if dep not in visited:
+                    if dfs(dep):
+                        return True
+                elif dep in path_set:
+                    cycle_start = dep
+                    return True
+        path.pop()
+        path_set.discard(sid)
+        return False
+
+    for sid in step_map:
+        if sid not in visited and dfs(sid):
+            # Build cycle from path: from cycle_start to end of path
+            try:
+                idx = path.index(cycle_start)
+                return path[idx:] + [cycle_start]
+            except (ValueError, TypeError):
+                return path + [path[0]] if path else list(step_map.keys())[:1]
+
+    return list(step_map.keys())[:1]
+
+
+def validate_dag(steps: list[WorkflowStep]) -> list[str]:
+    """Return list of error strings (used by validator)."""
+    errors: list[str] = []
+    step_ids = {s.id for s in steps}
+
+    for s in steps:
+        for dep in s.depends_on:
+            if dep not in step_ids:
+                errors.append(f"Step {s.id!r} depends_on unknown step {dep!r}")
+
+    if not errors:
+        try:
+            build_execution_order(steps)
+        except WorkflowCycleError as e:
+            errors.append(str(e))
+
+    return errors