readyagentsdev 0.8.2__py3-none-any.whl

readyagents/workflow/state.py

@@ -0,0 +1,472 @@
+"""Immutable-ish run state and persisted run records."""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from readyagents.errors import ConfigError, WorkflowError
+
+
+def utc_now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+@dataclass(frozen=True)
+class NodeResult:
+    node_id: str
+    type: str
+    status: str
+    output: Any = None
+    error: str | None = None
+    attempts: int = 1
+    started_at: str = ""
+    finished_at: str = ""
+    usage: dict[str, int] = field(default_factory=dict)
+    tool_rounds: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class RunState:
+    """Inputs + per-node outputs. Treat as append-only during a run."""
+
+    run_id: str
+    workflow_name: str
+    inputs: dict[str, Any]
+    node_outputs: dict[str, Any] = field(default_factory=dict)
+    output_keys: dict[str, Any] = field(default_factory=dict)
+    results: list[NodeResult] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+    status: str = "running"
+    pending_node: str | None = None
+    pending: dict[str, Any] | None = None
+    usage: dict[str, int] = field(default_factory=dict)
+    started_at: str = field(default_factory=utc_now)
+    finished_at: str | None = None
+    _last_node_usage: dict[str, int] = field(default_factory=dict, repr=False, compare=False)
+    _usage_lock: threading.Lock = field(default_factory=threading.Lock, repr=False, compare=False)
+
+    @classmethod
+    def start(
+        cls,
+        workflow_name: str,
+        inputs: Mapping[str, Any],
+        *,
+        metadata: Mapping[str, Any] | None = None,
+        run_id: str | None = None,
+    ) -> RunState:
+        return cls(
+            run_id=run_id or uuid4().hex,
+            workflow_name=workflow_name,
+            inputs=dict(inputs),
+            metadata=dict(metadata or {}),
+        )
+
+    def mapping(self) -> dict[str, Any]:
+        """Template namespace: inputs, node ids, output keys, metadata."""
+        ns: dict[str, Any] = {}
+        ns.update(self.metadata)
+        ns.update(self.inputs)
+        ns.update(self.node_outputs)
+        ns.update(self.output_keys)
+        ns["inputs"] = self.inputs
+        ns["outputs"] = self.node_outputs
+        ns["run_id"] = self.run_id
+        return ns
+
+    def record(
+        self,
+        node_id: str,
+        output: Any,
+        *,
+        node_type: str,
+        output_key: str | None = None,
+        attempts: int = 1,
+        started_at: str = "",
+        finished_at: str = "",
+        usage: Mapping[str, int] | None = None,
+        tool_rounds: list[dict[str, Any]] | None = None,
+    ) -> None:
+        self.node_outputs[node_id] = output
+        if output_key:
+            self.output_keys[output_key] = output
+        self.results.append(
+            NodeResult(
+                node_id=node_id,
+                type=node_type,
+                status="ok",
+                output=_jsonable(output),
+                attempts=attempts,
+                started_at=started_at,
+                finished_at=finished_at,
+                usage={str(k): int(v) for k, v in dict(usage or {}).items()},
+                tool_rounds=[dict(row) for row in (tool_rounds or [])],
+            )
+        )
+
+    def record_error(
+        self, node_id: str, node_type: str, message: str, *, attempts: int = 1
+    ) -> None:
+        self.errors.append(message)
+        self.results.append(
+            NodeResult(
+                node_id=node_id,
+                type=node_type,
+                status="error",
+                error=message,
+                attempts=attempts,
+                finished_at=utc_now(),
+            )
+        )
+
+    def finish(self, status: str) -> None:
+        self.status = status
+        self.finished_at = utc_now()
+
+    def add_usage(self, **amounts: Any) -> None:
+        cleaned = _clean_usage(amounts)
+        if not cleaned:
+            return
+        with self._usage_lock:
+            _add_usage_into(self.usage, cleaned)
+
+    def note_node_usage(self, amounts: Mapping[str, Any], *, rollup: bool = True) -> None:
+        """Attach usage to the current node. Accumulates so parallel branches merge."""
+        cleaned = _clean_usage(amounts)
+        if not cleaned:
+            return
+        with self._usage_lock:
+            _add_usage_into(self._last_node_usage, cleaned)
+            if rollup:
+                _add_usage_into(self.usage, cleaned)
+
+    def take_node_usage(self) -> dict[str, int]:
+        with self._usage_lock:
+            usage = dict(self._last_node_usage)
+            self._last_node_usage = {}
+            return usage
+
+    def node_usage_map(self) -> dict[str, dict[str, int]]:
+        return {r.node_id: dict(r.usage) for r in self.results if r.usage}
+
+    def to_record(self) -> dict[str, Any]:
+        return {
+            "run_id": self.run_id,
+            "workflow": self.workflow_name,
+            "status": self.status,
+            "started_at": self.started_at,
+            "finished_at": self.finished_at,
+            "pending_node": self.pending_node,
+            "pending": _jsonable(self.pending) if self.pending else None,
+            "inputs": _jsonable(self.inputs),
+            "outputs": _jsonable(self.output_keys or self.node_outputs),
+            "output_keys": _jsonable(self.output_keys),
+            "node_outputs": _jsonable(self.node_outputs),
+            "node_results": [
+                {
+                    "node_id": r.node_id,
+                    "type": r.type,
+                    "status": r.status,
+                    "output": r.output,
+                    "error": r.error,
+                    "attempts": r.attempts,
+                    "started_at": r.started_at,
+                    "finished_at": r.finished_at,
+                    "usage": dict(r.usage),
+                    "tool_rounds": list(r.tool_rounds),
+                }
+                for r in self.results
+            ],
+            "metadata": _jsonable(self.metadata),
+            "errors": list(self.errors),
+            "usage": dict(self.usage),
+        }
+
+    @classmethod
+    def from_record(cls, data: Mapping[str, Any]) -> RunState:
+        results = [
+            NodeResult(
+                node_id=str(row.get("node_id", "")),
+                type=str(row.get("type", "")),
+                status=str(row.get("status", "")),
+                output=row.get("output"),
+                error=row.get("error"),
+                attempts=int(row.get("attempts") or 1),
+                started_at=str(row.get("started_at") or ""),
+                finished_at=str(row.get("finished_at") or ""),
+                usage={
+                    str(k): int(v)
+                    for k, v in dict(row.get("usage") or {}).items()
+                    if _is_intlike(v)
+                },
+                tool_rounds=[
+                    dict(item)
+                    for item in (row.get("tool_rounds") or [])
+                    if isinstance(item, Mapping)
+                ],
+            )
+            for row in data.get("node_results") or []
+            if isinstance(row, Mapping)
+        ]
+        pending_raw = data.get("pending")
+        pending = dict(pending_raw) if isinstance(pending_raw, Mapping) else None
+        return cls(
+            run_id=str(data.get("run_id") or ""),
+            workflow_name=str(data.get("workflow") or data.get("workflow_name") or ""),
+            inputs=dict(data.get("inputs") or {}),
+            node_outputs=dict(data.get("node_outputs") or {}),
+            output_keys=dict(data.get("output_keys") or data.get("outputs") or {}),
+            results=results,
+            metadata=dict(data.get("metadata") or {}),
+            errors=list(data.get("errors") or []),
+            status=str(data.get("status") or "running"),
+            pending_node=data.get("pending_node"),
+            pending=pending,
+            usage={str(k): int(v) for k, v in dict(data.get("usage") or {}).items()},
+            started_at=str(data.get("started_at") or utc_now()),
+            finished_at=data.get("finished_at"),
+        )
+
+
+def persist_run(state: RunState, runs_dir: Path, *, redactor: Any | None = None) -> Path:
+    """Atomically write `<run_id>.json` (temp file + os.replace)."""
+    runs_dir.mkdir(parents=True, exist_ok=True)
+    path = runs_dir / f"{state.run_id}.json"
+    tmp = runs_dir / f".{state.run_id}.{uuid4().hex}.json.tmp"
+    record_obj: Any = state.to_record()
+    if redactor is not None:
+        record_obj = redactor.redact(record_obj)
+    record = json.dumps(record_obj, indent=2, ensure_ascii=False) + "\n"
+    try:
+        tmp.write_text(record, encoding="utf-8")
+        os.replace(tmp, path)
+    finally:
+        if tmp.exists():
+            tmp.unlink(missing_ok=True)
+    return path
+
+
+def delete_run(runs_dir: Path, run_id: str) -> Path:
+    """Remove one run JSON file. ``run_id`` may be a unique prefix."""
+    state = load_run(runs_dir, run_id)
+    path = Path(runs_dir) / f"{state.run_id}.json"
+    if not path.is_file():
+        raise ConfigError(f"Run not found: {run_id}")
+    path.unlink()
+    return path
+
+
+def gc_runs(
+    runs_dir: Path,
+    *,
+    statuses: list[str] | None = None,
+    include_paused: bool = False,
+    keep: int = 0,
+) -> list[str]:
+    """Delete local run files. Never deletes ``paused`` unless ``include_paused``."""
+    wanted = {s.strip().lower() for s in (statuses or ["succeeded", "failed", "cancelled"])}
+    if include_paused:
+        wanted.add("paused")
+    found = list_runs(runs_dir)
+    if keep and keep > 0:
+        found = found[keep:]
+    deleted: list[str] = []
+    for state in found:
+        if state.status == "paused" and not include_paused:
+            continue
+        if state.status not in wanted:
+            continue
+        path = Path(runs_dir) / f"{state.run_id}.json"
+        if path.is_file():
+            path.unlink()
+            deleted.append(state.run_id)
+    return deleted
+
+
+def mark_cancelled(state: RunState) -> RunState:
+    """Mark a run cancelled. Does not persist."""
+    state.finish("cancelled")
+    return state
+
+
+def load_run(runs_dir: Path, run_id: str) -> RunState:
+    """Load a persisted run. `run_id` may be a unique prefix."""
+    runs_dir = Path(runs_dir)
+    exact = runs_dir / f"{run_id}.json"
+    if exact.is_file():
+        return _read_run(exact)
+    matches = sorted(runs_dir.glob(f"{run_id}*.json")) if runs_dir.is_dir() else []
+    if len(matches) == 1:
+        return _read_run(matches[0])
+    if len(matches) > 1:
+        ids = ", ".join(p.stem for p in matches[:8])
+        raise ConfigError(f"Run id '{run_id}' is ambiguous. Matches: {ids}")
+    raise ConfigError(f"Run not found: {run_id}")
+
+
+def list_runs(
+    runs_dir: Path,
+    *,
+    status: str | None = None,
+    workflow: str | None = None,
+    limit: int = 0,
+) -> list[RunState]:
+    runs_dir = Path(runs_dir)
+    if not runs_dir.is_dir():
+        return []
+    states: list[RunState] = []
+    for path in runs_dir.glob("*.json"):
+        if path.name.startswith("."):
+            continue
+        try:
+            states.append(_read_run(path))
+        except (OSError, json.JSONDecodeError, ConfigError, TypeError, ValueError):
+            continue
+    states.sort(key=lambda s: s.started_at, reverse=True)
+    if status:
+        wanted = status.strip().lower()
+        states = [s for s in states if s.status == wanted]
+    if workflow:
+        wanted_wf = workflow.strip()
+        states = [s for s in states if s.workflow_name == wanted_wf]
+    if limit and limit > 0:
+        states = states[:limit]
+    return states
+
+
+def _read_run(path: Path) -> RunState:
+    try:
+        text = path.read_text(encoding="utf-8")
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"Corrupt run record {path}: {exc}") from exc
+    except OSError as exc:
+        raise ConfigError(f"Cannot read run record {path}: {exc}") from exc
+    if not isinstance(data, dict) or not data.get("run_id"):
+        raise ConfigError(f"Invalid run record: {path}")
+    return RunState.from_record(data)
+
+
+def build_decisions(approve: list[str], reject: list[str]) -> dict[str, str]:
+    decisions: dict[str, str] = {}
+    for node_id in approve:
+        decisions[node_id] = "approve"
+    for node_id in reject:
+        decisions[node_id] = "reject"
+    return decisions
+
+
+def parse_decision_payload(data: Any) -> dict[str, str]:
+    """Accept a few JSON shapes used by external decision injection."""
+    if data is None:
+        return {}
+    if isinstance(data, Mapping):
+        if "decisions" in data and isinstance(data["decisions"], Mapping):
+            return {str(k): str(v).strip().lower() for k, v in data["decisions"].items()}
+        if "decisions" in data and isinstance(data["decisions"], list):
+            return parse_decision_payload(data["decisions"])
+        node = data.get("node_id") or data.get("node") or data.get("id")
+        decision = data.get("decision") or data.get("value")
+        if node and decision is not None:
+            return {str(node): str(decision).strip().lower()}
+        return {str(k): str(v).strip().lower() for k, v in data.items() if v is not None}
+    if isinstance(data, list):
+        merged: dict[str, str] = {}
+        for item in data:
+            merged.update(parse_decision_payload(item))
+        return merged
+    raise WorkflowError("Decision payload must be a JSON object or list")
+
+
+def load_decision_file(path: Path | str) -> dict[str, str]:
+    file = Path(path)
+    if not file.is_file():
+        from readyagents.errors import ConfigError
+
+        raise ConfigError(f"Decision file not found: {file}")
+    try:
+        data = json.loads(file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise WorkflowError(f"Decision file {file} is not valid JSON: {exc}") from exc
+    return parse_decision_payload(data)
+
+
+def _clean_usage(amounts: Mapping[str, Any] | None) -> dict[str, int]:
+    cleaned: dict[str, int] = {}
+    for key, raw in dict(amounts or {}).items():
+        if raw is None:
+            continue
+        try:
+            cleaned[str(key)] = int(raw)
+        except (TypeError, ValueError):
+            continue
+    return cleaned
+
+
+def _add_usage_into(target: dict[str, int], amounts: Mapping[str, int]) -> None:
+    for key, value in amounts.items():
+        target[key] = int(target.get(key, 0)) + int(value)
+
+
+def _is_intlike(value: Any) -> bool:
+    try:
+        int(value)
+        return True
+    except (TypeError, ValueError):
+        return False
+
+
+def _jsonable(value: Any) -> Any:
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {str(k): _jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(v) for v in value]
+    try:
+        json.dumps(value)
+        return value
+    except TypeError:
+        return str(value)
+
+
+def parse_input_pairs(pairs: list[str]) -> dict[str, Any]:
+    """Parse CLI `--input KEY=VALUE` pairs."""
+    result: dict[str, Any] = {}
+    for raw in pairs:
+        if "=" not in raw:
+            raise WorkflowError(f"Invalid --input '{raw}' (expected KEY=VALUE)")
+        key, value = raw.split("=", 1)
+        key = key.strip()
+        if not key:
+            raise WorkflowError(f"Invalid --input '{raw}' (empty key)")
+        result[key] = _coerce_scalar(value)
+    return result
+
+
+def _coerce_scalar(value: str) -> Any:
+    lowered = value.strip().lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    if lowered == "null" or lowered == "none":
+        return None
+    try:
+        if value.strip().isdigit() or (
+            value.strip().startswith("-") and value.strip()[1:].isdigit()
+        ):
+            return int(value.strip())
+        return float(value) if "." in value.strip() else value
+    except ValueError:
+        return value

readyagents/workflow/structured.py

@@ -0,0 +1,103 @@
+"""Strict structured output validation for agent nodes (Pydantic)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, create_model
+
+from readyagents.errors import StructuredOutputError
+
+_JSON_TYPES: dict[str, Any] = {
+    "string": str,
+    "number": float,
+    "integer": int,
+    "boolean": bool,
+    "array": list,
+    "object": dict,
+    "null": type(None),
+}
+
+
+def parse_json_payload(text: str) -> Any:
+    stripped = (text or "").strip()
+    if not stripped:
+        raise ValueError("empty LLM output")
+    try:
+        return json.loads(stripped)
+    except json.JSONDecodeError:
+        pass
+    start = stripped.find("{")
+    end = stripped.rfind("}")
+    if start != -1 and end != -1 and end > start:
+        try:
+            return json.loads(stripped[start : end + 1])
+        except json.JSONDecodeError:
+            pass
+    start = stripped.find("[")
+    end = stripped.rfind("]")
+    if start != -1 and end != -1 and end > start:
+        return json.loads(stripped[start : end + 1])
+    raise ValueError("LLM output is not JSON")
+
+
+def _annotation(spec: Any) -> Any:
+    if not isinstance(spec, dict):
+        return Any
+    raw_type = spec.get("type")
+    if isinstance(raw_type, list):
+        parts = [_simple(t) for t in raw_type]
+        out: Any = parts[0] if parts else Any
+        for part in parts[1:]:
+            out = out | part
+        return out
+    return _simple(raw_type or "string")
+
+
+def _simple(raw: Any) -> Any:
+    if not isinstance(raw, str):
+        return Any
+    return _JSON_TYPES.get(raw, Any)
+
+
+def model_from_schema(schema: dict[str, Any]) -> type[BaseModel]:
+    """Build a one-off Pydantic model from a JSON Schema object."""
+    extra_flag = schema.get("additionalProperties", True)
+    extra = "allow" if extra_flag else "forbid"
+
+    class _Base(BaseModel):
+        model_config = ConfigDict(extra=extra)
+
+    props = schema.get("properties")
+    if not isinstance(props, dict):
+        # Whole-payload type, e.g. {"type": "object"} with no properties.
+        return create_model("AgentStructured", __base__=_Base)
+
+    required = {str(item) for item in (schema.get("required") or []) if item}
+    fields: dict[str, Any] = {}
+    for name, spec in props.items():
+        annotation = _annotation(spec if isinstance(spec, dict) else {})
+        if name in required:
+            fields[name] = (annotation, Field(...))
+        else:
+            fields[name] = (annotation | None, None)
+    return create_model("AgentStructured", __base__=_Base, **fields)
+
+
+def validate_structured_output(text: str, schema: dict[str, Any], *, node_id: str) -> Any:
+    """Parse JSON and validate against ``schema``. Raises StructuredOutputError."""
+    try:
+        data = parse_json_payload(text)
+    except (ValueError, json.JSONDecodeError) as exc:
+        raise StructuredOutputError(node_id, f"structured output is not JSON: {exc}") from exc
+    if not isinstance(schema, dict) or not schema:
+        raise StructuredOutputError(node_id, "output_schema must be a JSON Schema object")
+    model = model_from_schema(schema)
+    try:
+        parsed = model.model_validate(data)
+    except ValidationError as exc:
+        raise StructuredOutputError(
+            node_id, f"structured output failed schema validation: {exc}"
+        ) from exc
+    return parsed.model_dump()

readyagents/workflow/templates.py

@@ -0,0 +1,125 @@
+"""Safe `{{dotted.path}}` interpolation against run state."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from typing import Any
+
+from readyagents.errors import TemplateError
+
+_VAR = re.compile(
+    r"\{\{\s*([a-zA-Z_][a-zA-Z0-9_\.]*)"
+    r"(?:\s*\|\s*(default|len|join)(?:\s+([^}]+?))?)?"
+    r"\s*\}\}"
+)
+_FILTERS = frozenset({"default", "len", "join"})
+
+
+def resolve_path(data: Any, path: str) -> Any:
+    """Resolve a dotted path (`a.b.0.c`) against dicts/lists."""
+    current = data
+    for part in path.split("."):
+        current = _step(current, part, path)
+    return current
+
+
+def _step(current: Any, part: str, full: str) -> Any:
+    if current is None:
+        raise TemplateError(f"Missing template variable: {full}")
+    if isinstance(current, Mapping):
+        if part in current:
+            return current[part]
+        raise TemplateError(f"Missing template variable: {full}")
+    if isinstance(current, (list, tuple)):
+        try:
+            idx = int(part)
+        except ValueError as exc:
+            raise TemplateError(f"Missing template variable: {full}") from exc
+        try:
+            return current[idx]
+        except IndexError as exc:
+            raise TemplateError(f"Missing template variable: {full}") from exc
+    raise TemplateError(f"Missing template variable: {full}")
+
+
+def lookup(mapping: Mapping[str, Any], path: str) -> Any:
+    if path in mapping and "." not in path:
+        return mapping[path]
+    head, _, rest = path.partition(".")
+    if head not in mapping:
+        raise TemplateError(f"Missing template variable: {path}")
+    if not rest:
+        return mapping[head]
+    return resolve_path(mapping[head], rest)
+
+
+def interpolate(template: str, mapping: Mapping[str, Any]) -> str:
+    """Replace `{{var}}` tokens. Missing names raise TemplateError unless `| default`."""
+
+    def repl(match: re.Match[str]) -> str:
+        path = match.group(1)
+        filt = match.group(2)
+        arg = (match.group(3) or "").strip()
+        try:
+            value = lookup(mapping, path)
+        except TemplateError:
+            if filt == "default":
+                return _unquote(arg)
+            raise
+        if filt:
+            value = _apply_filter(filt, value, arg)
+        return _stringify(value)
+
+    return _VAR.sub(repl, template)
+
+
+def _unquote(text: str) -> str:
+    if len(text) >= 2 and text[0] == text[-1] and text[0] in {"'", '"'}:
+        return text[1:-1]
+    return text
+
+
+def _apply_filter(name: str, value: Any, arg: str) -> Any:
+    if name == "default":
+        if value is None or value == "":
+            return _unquote(arg)
+        return value
+    if name == "len":
+        try:
+            return len(value)
+        except TypeError as exc:
+            raise TemplateError("filter len requires a sized value") from exc
+    if name == "join":
+        sep = _unquote(arg) if arg else ""
+        if isinstance(value, str):
+            return sep.join(value)
+        try:
+            return sep.join(_stringify(item) for item in value)
+        except TypeError as exc:
+            raise TemplateError("filter join requires an iterable") from exc
+    raise TemplateError(f"unknown filter '{name}'")
+
+
+def interpolate_value(value: Any, mapping: Mapping[str, Any]) -> Any:
+    """Recursively interpolate strings inside dicts/lists."""
+    if isinstance(value, str):
+        return interpolate(value, mapping)
+    if isinstance(value, Mapping):
+        return {k: interpolate_value(v, mapping) for k, v in value.items()}
+    if isinstance(value, list):
+        return [interpolate_value(v, mapping) for v in value]
+    if isinstance(value, tuple):
+        return tuple(interpolate_value(v, mapping) for v in value)
+    return value
+
+
+def _stringify(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (dict, list, tuple, bool)):
+        return json.dumps(value, ensure_ascii=False)
+    return str(value)