readyagentsdev 0.8.2__py3-none-any.whl

readyagents/workflow/conditions.py

@@ -0,0 +1,279 @@
+"""Boolean conditions over existing comparison atoms. No Python eval()."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Any
+
+from readyagents.errors import TemplateError, WorkflowError
+from readyagents.workflow.templates import interpolate, lookup
+
+_COMPARE = re.compile(
+    r"^\s*(.+?)\s*(==|!=|>=|<=|>|<|contains|startswith|endswith)\s*(.+?)\s*$",
+    re.DOTALL,
+)
+_BOOL_OPS = re.compile(r"\b(and|or|not)\b", re.IGNORECASE)
+
+
+def evaluate_condition(expr: str, mapping: Mapping[str, Any]) -> bool:
+    """Evaluate a small boolean of comparisons / truthy paths. No `eval()`."""
+    text = (expr or "").strip()
+    if not text:
+        return False
+    try:
+        return _eval_or(text, mapping)
+    except WorkflowError:
+        raise
+    except TemplateError:
+        raise
+
+
+def _split_top(expr: str, op: str) -> list[str] | None:
+    parts: list[str] = []
+    buf: list[str] = []
+    depth = 0
+    quote: str | None = None
+    i = 0
+    token = f" {op} "
+    lower = expr
+    while i < len(lower):
+        ch = expr[i]
+        if quote:
+            buf.append(ch)
+            if ch == quote:
+                quote = None
+            i += 1
+            continue
+        if ch in {'"', "'"}:
+            quote = ch
+            buf.append(ch)
+            i += 1
+            continue
+        if ch == "(":
+            depth += 1
+            buf.append(ch)
+            i += 1
+            continue
+        if ch == ")":
+            depth -= 1
+            if depth < 0:
+                raise WorkflowError("Unbalanced ')' in condition")
+            buf.append(ch)
+            i += 1
+            continue
+        if depth == 0 and expr[i : i + len(token)].lower() == token:
+            piece = "".join(buf).strip()
+            if not piece:
+                raise WorkflowError(f"Empty operand for '{op}'")
+            parts.append(piece)
+            buf = []
+            i += len(token)
+            continue
+        buf.append(ch)
+        i += 1
+    if quote:
+        raise WorkflowError("Unterminated quote in condition")
+    if depth != 0:
+        raise WorkflowError("Unbalanced '(' in condition")
+    tail = "".join(buf).strip()
+    if parts:
+        if not tail:
+            raise WorkflowError(f"Empty operand for '{op}'")
+        parts.append(tail)
+        return parts
+    return None
+
+
+def _eval_or(expr: str, mapping: Mapping[str, Any]) -> bool:
+    parts = _split_top(expr, "or")
+    if parts is None:
+        return _eval_and(expr, mapping)
+    return any(_eval_and(part, mapping) for part in parts)
+
+
+def _eval_and(expr: str, mapping: Mapping[str, Any]) -> bool:
+    parts = _split_top(expr, "and")
+    if parts is None:
+        return _eval_not(expr, mapping)
+    return all(_eval_not(part, mapping) for part in parts)
+
+
+def _eval_not(expr: str, mapping: Mapping[str, Any]) -> bool:
+    text = expr.strip()
+    if text.lower().startswith("not ") or text.lower() == "not":
+        rest = text[3:].strip()
+        if not rest:
+            raise WorkflowError("Empty operand for 'not'")
+        return not _eval_not(rest, mapping)
+    if text.startswith("(") and text.endswith(")"):
+        inner = text[1:-1].strip()
+        if _balanced_outer_parens(text):
+            return _eval_or(inner, mapping)
+    return _eval_atom(text, mapping)
+
+
+def _balanced_outer_parens(text: str) -> bool:
+    if not (text.startswith("(") and text.endswith(")")):
+        return False
+    depth = 0
+    quote: str | None = None
+    for i, ch in enumerate(text):
+        if quote:
+            if ch == quote:
+                quote = None
+            continue
+        if ch in {'"', "'"}:
+            quote = ch
+            continue
+        if ch == "(":
+            depth += 1
+        elif ch == ")":
+            depth -= 1
+            if depth == 0 and i != len(text) - 1:
+                return False
+    return depth == 0
+
+
+def _eval_atom(expr: str, mapping: Mapping[str, Any]) -> bool:
+    text = expr.strip()
+    if _BOOL_OPS.search(text) and not _quoted_only_ops(text):
+        raise WorkflowError(f"Could not parse condition '{expr}'")
+    match = _COMPARE.match(text)
+    if match:
+        left_raw, op, right_raw = match.group(1), match.group(2), match.group(3)
+        if not _is_single_operand(left_raw) or not _is_single_operand(right_raw):
+            raise WorkflowError(f"Could not parse condition '{expr}'")
+        if _BOOL_OPS.search(left_raw) or _BOOL_OPS.search(right_raw):
+            if not (_quoted_only_ops(left_raw) and _quoted_only_ops(right_raw)):
+                raise WorkflowError(f"Could not parse condition '{expr}'")
+        left = _atom(left_raw, mapping)
+        right = _atom(right_raw, mapping)
+        return _compare(left, op, right)
+    interpolated = interpolate(text, mapping) if "{{" in text else text
+    try:
+        value: Any = (
+            lookup(mapping, interpolated)
+            if interpolated.isidentifier() or "." in interpolated
+            else interpolated
+        )
+    except TemplateError:
+        value = interpolated
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in {"true", "yes", "1"}:
+            return True
+        if lowered in {"false", "no", "0", ""}:
+            return False
+    return bool(value)
+
+
+def _is_single_operand(raw: str) -> bool:
+    text = raw.strip()
+    if not text:
+        return False
+    if (text.startswith('"') and text.endswith('"')) or (
+        text.startswith("'") and text.endswith("'")
+    ):
+        return True
+    if "{{" in text:
+        return text.count("{{") == 1 and text.count("}}") == 1
+    if text.lower() in {"true", "false", "null", "none"}:
+        return True
+    if text.replace("_", "").replace(".", "").replace("-", "").isalnum():
+        return True
+    try:
+        float(text)
+        return True
+    except ValueError:
+        return False
+
+
+def _quoted_only_ops(text: str) -> bool:
+    """True if any and/or/not tokens sit only inside quotes."""
+    quote: str | None = None
+    i = 0
+    lower = text.lower()
+    while i < len(text):
+        ch = text[i]
+        if quote:
+            if ch == quote:
+                quote = None
+            i += 1
+            continue
+        if ch in {'"', "'"}:
+            quote = ch
+            i += 1
+            continue
+        for word in ("and", "or", "not"):
+            n = len(word)
+            if lower[i : i + n] == word:
+                before = text[i - 1] if i else " "
+                after = text[i + n] if i + n < len(text) else " "
+                if not before.isalnum() and before != "_" and not after.isalnum() and after != "_":
+                    return False
+        i += 1
+    return True
+
+
+def _atom(raw: str, mapping: Mapping[str, Any]) -> Any:
+    text = raw.strip()
+    quoted = (text.startswith('"') and text.endswith('"')) or (
+        text.startswith("'") and text.endswith("'")
+    )
+    if quoted:
+        return interpolate(text[1:-1], mapping)
+    if "{{" in text:
+        return interpolate(text, mapping)
+    lowered = text.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    if lowered in {"null", "none"}:
+        return None
+    try:
+        if text.isdigit() or (text.startswith("-") and text[1:].isdigit()):
+            return int(text)
+        return float(text)
+    except ValueError:
+        pass
+    try:
+        return lookup(mapping, text)
+    except TemplateError:
+        return interpolate(text, mapping) if "{{" in text else text
+
+
+def _compare(left: Any, op: str, right: Any) -> bool:
+    if op == "==":
+        return _norm(left) == _norm(right)
+    if op == "!=":
+        return _norm(left) != _norm(right)
+    if op in {">", "<", ">=", "<="}:
+        try:
+            lf, rf = float(left), float(right)
+        except (TypeError, ValueError):
+            lf, rf = str(left), str(right)
+        if op == ">":
+            return lf > rf
+        if op == "<":
+            return lf < rf
+        if op == ">=":
+            return lf >= rf
+        return lf <= rf
+    left_s, right_s = str(left), str(right)
+    if op == "contains":
+        return right_s in left_s
+    if op == "startswith":
+        return left_s.startswith(right_s)
+    if op == "endswith":
+        return left_s.endswith(right_s)
+    return False
+
+
+def _norm(value: Any) -> Any:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip()
+    return value

readyagents/workflow/engine.py

@@ -0,0 +1,354 @@
+"""Execute a workflow graph with retries, timeouts, and branching."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from readyagents.errors import (
+    ApprovalRequired,
+    AuthorizationError,
+    BudgetExceeded,
+    CancellationRequested,
+    CircuitOpen,
+    ReadyAgentsError,
+    WorkflowError,
+)
+from readyagents.logging import get_logger, log_event
+from readyagents.workflow.nodes import (
+    ExecutionContext,
+    evaluate_condition,
+    execute_node_with_policy,
+)
+from readyagents.workflow.schema import NodeSpec, NodeType, WorkflowSpec
+from readyagents.workflow.state import RunState, utc_now
+
+log = get_logger("engine")
+
+_MAX_STEPS = 500
+_TERMINAL_STATUSES = frozenset({"cancelled", "succeeded", "failed", "paused"})
+
+
+def run_workflow(
+    workflow: WorkflowSpec,
+    inputs: Mapping[str, Any],
+    ctx: ExecutionContext,
+    *,
+    metadata: Mapping[str, Any] | None = None,
+    state: RunState | None = None,
+    run_id: str | None = None,
+) -> RunState:
+    nodes = workflow.node_map()
+    if state is None:
+        state = RunState.start(workflow.name, inputs, metadata=metadata, run_id=run_id)
+        current = workflow.start or workflow.nodes[0].id
+        seen: set[str] = set()
+    elif _is_fresh_start(state):
+        current = workflow.start or workflow.nodes[0].id
+        seen = set()
+        state.status = "running"
+        state.finished_at = None
+        if inputs:
+            state.inputs.update(dict(inputs))
+        if metadata:
+            state.metadata.update(dict(metadata))
+    else:
+        current, seen = _resume_cursor(workflow, state)
+        if inputs:
+            state.inputs.update(dict(inputs))
+        if metadata:
+            state.metadata.update(dict(metadata))
+
+    if ctx.usage_state is None:
+        ctx.usage_state = state
+    _arm_cancellation_persist(ctx, state)
+    _persist(ctx, state)
+    log_event(
+        log,
+        "run_start",
+        "run %s status=%s",
+        state.run_id,
+        state.status,
+        run_id=state.run_id,
+        node_id="-",
+        status=state.status,
+    )
+    if ctx.auditor is not None:
+        ctx.auditor("run_started", run_id=state.run_id, workflow=workflow.name, actor=ctx.actor)
+
+    steps = 0
+    try:
+        _raise_if_cancelled(ctx, state)
+        while current:
+            steps += 1
+            if steps > _MAX_STEPS:
+                raise WorkflowError(f"Workflow exceeded {_MAX_STEPS} steps (possible cycle)")
+            if current in seen:
+                raise WorkflowError(f"Cycle detected at node '{current}'")
+            if current not in nodes:
+                raise WorkflowError(f"Unknown node '{current}'")
+            node = nodes[current]
+            seen.add(current)
+            log_event(
+                log,
+                "node_start",
+                "node %s (%s)",
+                node.id,
+                node.type,
+                run_id=state.run_id,
+                node_id=node.id,
+            )
+            _raise_if_cancelled(ctx, state)
+            try:
+                _execute_with_policy(node, state, ctx)
+            except CancellationRequested:
+                raise
+            except ApprovalRequired:
+                raise
+            except ReadyAgentsError:
+                _raise_if_cancelled(ctx, state)
+                raise
+            _raise_if_cancelled(ctx, state)
+            state.pending_node = None
+            _persist(ctx, state)
+            if ctx.auditor is not None:
+                ctx.auditor(
+                    "node_ok",
+                    run_id=state.run_id,
+                    node_id=node.id,
+                    node_type=str(node.type),
+                    actor=ctx.actor,
+                )
+            current = _next_node(workflow, node, state)
+        _raise_if_cancelled(ctx, state)
+        state.pending_node = None
+        state.pending = None
+        state.finish("succeeded")
+        _persist(ctx, state)
+        if ctx.auditor is not None:
+            ctx.auditor("run_finished", run_id=state.run_id, status="succeeded", actor=ctx.actor)
+    except KeyboardInterrupt:
+        state.pending_node = current
+        state.pending = {
+            "node_id": current,
+            "type": str(nodes[current].type) if current in nodes else "?",
+            "error": "cancelled",
+        }
+        state.finish("cancelled")
+        _persist(ctx, state)
+        raise
+    except CancellationRequested as exc:
+        _finalize_cancelled(ctx, state, current, nodes)
+        exc.state = state
+        if not exc.run_id:
+            exc.run_id = state.run_id
+        raise
+    except ApprovalRequired as exc:
+        state.pending_node = current
+        paused = nodes.get(current) if current else None
+        state.pending = {
+            "node_id": exc.node_id,
+            "type": "approval",
+            "prompt": exc.prompt,
+            "then": getattr(paused, "then", None),
+            "else": getattr(paused, "else_", None),
+            "resume": f"readyagents resume {state.run_id} --approve {exc.node_id}",
+            "decide": (
+                f"readyagents decide {state.run_id} --node {exc.node_id} --decision approve"
+            ),
+        }
+        state.finish("paused")
+        _persist(ctx, state)
+        exc.state = state
+        if ctx.auditor is not None:
+            ctx.auditor(
+                "paused",
+                run_id=state.run_id,
+                node_id=exc.node_id,
+                actor=ctx.actor,
+            )
+        _notify_pause(ctx, exc, state)
+        raise
+    except ReadyAgentsError as exc:
+        state.take_node_usage()
+        state.pending_node = current
+        state.record_error(
+            current or "?",
+            str(nodes[current].type) if current in nodes else "?",
+            str(exc),
+        )
+        state.pending = {
+            "node_id": current,
+            "type": str(nodes[current].type) if current in nodes else "?",
+            "error": str(exc),
+        }
+        state.finish("failed")
+        _persist(ctx, state)
+        exc.state = state
+        if not exc.run_id:
+            exc.run_id = state.run_id
+        if ctx.auditor is not None:
+            ctx.auditor(
+                "run_finished",
+                run_id=state.run_id,
+                status="failed",
+                node_id=current,
+                actor=ctx.actor,
+            )
+        raise
+    return state
+
+
+def _resume_cursor(workflow: WorkflowSpec, state: RunState) -> tuple[str | None, set[str]]:
+    if state.status == "succeeded":
+        raise WorkflowError(
+            f"Run {state.run_id} already succeeded. "
+            f"Use 'readyagents runs replay {state.run_id}' to start a new run."
+        )
+    completed = {r.node_id for r in state.results if r.status == "ok"}
+    current = state.pending_node
+    if not current:
+        for result in reversed(state.results):
+            if result.status == "error":
+                current = result.node_id
+                break
+        if not current and state.results:
+            last_ok = next((r for r in reversed(state.results) if r.status == "ok"), None)
+            if last_ok and last_ok.node_id in workflow.node_map():
+                current = _next_node(workflow, workflow.node_map()[last_ok.node_id], state)
+    if current:
+        state.results = [
+            r for r in state.results if not (r.node_id == current and r.status == "error")
+        ]
+        if current not in completed:
+            state.node_outputs.pop(current, None)
+    state.pending_node = None
+    state.pending = None
+    state.status = "running"
+    state.finished_at = None
+    return current, completed
+
+
+def _is_fresh_start(state: RunState) -> bool:
+    return state.status in {"queued", "running"} and not state.results and not state.pending_node
+
+
+def _raise_if_cancelled(ctx: ExecutionContext, state: RunState) -> None:
+    if ctx.cancellation is None:
+        return
+    ctx.cancellation.raise_if_requested(run_id=state.run_id)
+
+
+def _arm_cancellation_persist(ctx: ExecutionContext, state: RunState) -> None:
+    token = ctx.cancellation
+    if token is None:
+        return
+    token.clear_listeners()
+    token.add_listener(lambda: _persist(ctx, state))
+
+
+def _finalize_cancelled(
+    ctx: ExecutionContext,
+    state: RunState,
+    current: str | None,
+    nodes: Mapping[str, NodeSpec],
+) -> None:
+    with ctx._persist_lock:
+        already = state.status == "cancelled"
+        if not already:
+            state.pending_node = current
+            state.pending = {
+                "node_id": current,
+                "type": str(nodes[current].type) if current in nodes else "?",
+                "error": "cancelled",
+            }
+            state.finish("cancelled")
+    if already:
+        return
+    _persist(ctx, state)
+    if ctx.auditor is not None:
+        ctx.auditor("run_finished", run_id=state.run_id, status="cancelled", actor=ctx.actor)
+
+
+def _persist(ctx: ExecutionContext, state: RunState) -> None:
+    token = ctx.cancellation
+    with ctx._persist_lock:
+        if token is not None and token.is_requested() and state.status not in _TERMINAL_STATUSES:
+            state.status = "cancel_requested"
+    if ctx.on_persist is None:
+        return
+    ctx.on_persist(state)
+
+
+def _notify_pause(ctx: ExecutionContext, exc: ApprovalRequired, state: RunState) -> None:
+    if ctx.on_pause is None:
+        return
+    try:
+        ctx.on_pause(exc, state)
+    except Exception as notify_exc:  # noqa: BLE001
+        log.warning(
+            "pause notify failed: %s",
+            notify_exc,
+            extra={"run_id": state.run_id, "node_id": exc.node_id, "event": "pause_notify_error"},
+        )
+
+
+def _execute_with_policy(node: NodeSpec, state: RunState, ctx: ExecutionContext) -> None:
+    started = utc_now()
+    try:
+        output, attempt = execute_node_with_policy(node, state, ctx)
+    except (BudgetExceeded, AuthorizationError, CircuitOpen):
+        state.take_node_usage()
+        raise
+    usage = state.take_node_usage()
+    rounds = list(ctx.last_tool_rounds or [])
+    ctx.last_tool_rounds = []
+    state.record(
+        node.id,
+        output,
+        node_type=str(node.type),
+        output_key=node.output_key,
+        attempts=attempt,
+        started_at=started,
+        finished_at=utc_now(),
+        usage=usage,
+        tool_rounds=rounds,
+    )
+
+
+def _uses_explicit_routing(workflow: WorkflowSpec) -> bool:
+    if workflow.edges:
+        return True
+    return any(n.next or n.then or n.else_ for n in workflow.nodes)
+
+
+def _next_node(workflow: WorkflowSpec, node: NodeSpec, state: RunState) -> str | None:
+    if str(node.type) in {NodeType.condition.value, NodeType.approval.value}:
+        output = state.node_outputs.get(node.id) or {}
+        nxt = output.get("next") if isinstance(output, dict) else None
+        return nxt
+
+    edges = [e for e in workflow.edges if e.from_ == node.id]
+    if edges:
+        default = None
+        ns = state.mapping()
+        for edge in edges:
+            if edge.when is None:
+                default = edge.to
+                continue
+            if evaluate_condition(edge.when, ns):
+                return edge.to
+        return default
+
+    if node.next:
+        return node.next
+
+    # List order only for purely sequential workflows (no next/edges/branches).
+    if _uses_explicit_routing(workflow):
+        return None
+
+    ids = [n.id for n in workflow.nodes]
+    idx = ids.index(node.id)
+    if idx + 1 < len(ids):
+        return ids[idx + 1]
+    return None