abstractflow 0.1.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

abstractflow/visual/models.py

@@ -0,0 +1,277 @@
+"""Pydantic models for the AbstractFlow visual workflow JSON format.
+
+These models are intentionally kept in the `abstractflow` package so workflows
+authored in the visual editor can be loaded and executed from any host (CLI,
+AbstractCode, servers), not only the web backend.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from datetime import datetime, timezone
+import uuid
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class PinType(str, Enum):
+    """Types of pins with their colors."""
+
+    EXECUTION = "execution"  # White #FFFFFF - Flow control
+    STRING = "string"  # Magenta #FF00FF - Text data
+    NUMBER = "number"  # Green #00FF00 - Integer/Float
+    BOOLEAN = "boolean"  # Red #FF0000 - True/False
+    OBJECT = "object"  # Cyan #00FFFF - JSON objects
+    MEMORY = "memory"  # Mint - Memory configuration object (KG/span/session controls)
+    ASSERTION = "assertion"  # Teal - KG assertion object (subject/predicate/object + metadata)
+    ASSERTIONS = "assertions"  # Teal - List of KG assertion objects (assertion[])
+    ARRAY = "array"  # Orange #FF8800 - Collections
+    TOOLS = "tools"  # Orange - Tool allowlist (string[])
+    PROVIDER = "provider"  # Cyan-blue - LLM provider id/name (string-like)
+    MODEL = "model"  # Purple - LLM model id/name (string-like)
+    AGENT = "agent"  # Blue #4488FF - Agent reference
+    ANY = "any"  # Gray #888888 - Accepts any type
+
+
+class NodeType(str, Enum):
+    """Types of nodes in the visual editor."""
+
+    # Event/Trigger nodes (entry points)
+    ON_FLOW_START = "on_flow_start"
+    ON_USER_REQUEST = "on_user_request"
+    ON_AGENT_MESSAGE = "on_agent_message"
+    ON_SCHEDULE = "on_schedule"
+    ON_EVENT = "on_event"
+    # Flow IO nodes
+    ON_FLOW_END = "on_flow_end"
+    # Core execution nodes
+    AGENT = "agent"
+    FUNCTION = "function"
+    CODE = "code"
+    SUBFLOW = "subflow"
+    # Math
+    ADD = "add"
+    SUBTRACT = "subtract"
+    MULTIPLY = "multiply"
+    DIVIDE = "divide"
+    MODULO = "modulo"
+    POWER = "power"
+    ABS = "abs"
+    ROUND = "round"
+    RANDOM_INT = "random_int"
+    RANDOM_FLOAT = "random_float"
+    # String
+    CONCAT = "concat"
+    SPLIT = "split"
+    JOIN = "join"
+    FORMAT = "format"
+    STRING_TEMPLATE = "string_template"
+    UPPERCASE = "uppercase"
+    LOWERCASE = "lowercase"
+    TRIM = "trim"
+    SUBSTRING = "substring"
+    LENGTH = "length"
+    CONTAINS = "contains"
+    REPLACE = "replace"
+    # Control
+    IF = "if"
+    SWITCH = "switch"
+    LOOP = "loop"
+    WHILE = "while"
+    FOR = "for"
+    SEQUENCE = "sequence"
+    PARALLEL = "parallel"
+    COMPARE = "compare"
+    NOT = "not"
+    AND = "and"
+    OR = "or"
+    COALESCE = "coalesce"
+    # Data
+    GET = "get"
+    SET = "set"
+    MERGE = "merge"
+    MAKE_ARRAY = "make_array"
+    MAKE_OBJECT = "make_object"
+    MAKE_CONTEXT = "make_context"
+    MAKE_META = "make_meta"
+    MAKE_SCRATCHPAD = "make_scratchpad"
+    GET_ELEMENT = "get_element"
+    GET_RANDOM_ELEMENT = "get_random_element"
+    ARRAY_MAP = "array_map"
+    ARRAY_FILTER = "array_filter"
+    ARRAY_CONCAT = "array_concat"
+    ARRAY_LENGTH = "array_length"
+    ARRAY_APPEND = "array_append"
+    ARRAY_DEDUP = "array_dedup"
+    HAS_TOOLS = "has_tools"
+    ADD_MESSAGE = "add_message"
+    GET_CONTEXT = "get_context"
+    GET_VAR = "get_var"
+    SET_VAR = "set_var"
+    SET_VARS = "set_vars"
+    SET_VAR_PROPERTY = "set_var_property"
+    PARSE_JSON = "parse_json"
+    STRINGIFY_JSON = "stringify_json"
+    FORMAT_TOOL_RESULTS = "format_tool_results"
+    AGENT_TRACE_REPORT = "agent_trace_report"
+    BREAK_OBJECT = "break_object"
+    SYSTEM_DATETIME = "system_datetime"
+    MODEL_CATALOG = "model_catalog"
+    PROVIDER_CATALOG = "provider_catalog"
+    PROVIDER_MODELS = "provider_models"
+    # Literals
+    LITERAL_STRING = "literal_string"
+    LITERAL_NUMBER = "literal_number"
+    LITERAL_BOOLEAN = "literal_boolean"
+    LITERAL_JSON = "literal_json"
+    JSON_SCHEMA = "json_schema"
+    LITERAL_ARRAY = "literal_array"
+    TOOL_PARAMETERS = "tool_parameters"
+    # Effects
+    ASK_USER = "ask_user"
+    ANSWER_USER = "answer_user"
+    LLM_CALL = "llm_call"
+    WAIT_UNTIL = "wait_until"
+    WAIT_EVENT = "wait_event"
+    EMIT_EVENT = "emit_event"
+    READ_FILE = "read_file"
+    WRITE_FILE = "write_file"
+    MEMORY_NOTE = "memory_note"
+    MEMORY_QUERY = "memory_query"
+    MEMORY_TAG = "memory_tag"
+    MEMORY_COMPACT = "memory_compact"
+    MEMORY_REHYDRATE = "memory_rehydrate"
+    MEMORY_KG_ASSERT = "memory_kg_assert"
+    MEMORY_KG_QUERY = "memory_kg_query"
+    MEMORY_KG_RESOLVE = "memory_kg_resolve"
+    MEMACT_COMPOSE = "memact_compose"
+    TOOL_CALLS = "tool_calls"
+    CALL_TOOL = "call_tool"
+    TOOLS_ALLOWLIST = "tools_allowlist"
+    BOOL_VAR = "bool_var"
+    VAR_DECL = "var_decl"
+
+
+class Pin(BaseModel):
+    """A connection point on a node."""
+
+    id: str
+    label: str
+    type: PinType
+
+
+class Position(BaseModel):
+    """2D position on canvas."""
+
+    x: float
+    y: float
+
+
+class VisualNode(BaseModel):
+    """A node in the visual flow editor."""
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4())[:8])
+    type: NodeType
+    position: Position
+    data: Dict[str, Any] = Field(default_factory=dict)
+    # Node display properties (from template)
+    label: Optional[str] = None
+    icon: Optional[str] = None
+    headerColor: Optional[str] = None
+    inputs: List[Pin] = Field(default_factory=list)
+    outputs: List[Pin] = Field(default_factory=list)
+
+
+class VisualEdge(BaseModel):
+    """An edge connecting two nodes."""
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4())[:8])
+    source: str
+    sourceHandle: str  # Pin ID on source node
+    target: str
+    targetHandle: str  # Pin ID on target node
+    animated: bool = False
+
+
+class VisualFlow(BaseModel):
+    """A complete visual flow definition."""
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4())[:8])
+    name: str
+    description: str = ""
+    # Optional interface markers (host contracts).
+    # Example: ["abstractcode.agent.v1"] to indicate this workflow can be run as a RunnableFlow in chat-like clients.
+    interfaces: List[str] = Field(default_factory=list)
+    nodes: List[VisualNode] = Field(default_factory=list)
+    edges: List[VisualEdge] = Field(default_factory=list)
+    entryNode: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
+class FlowCreateRequest(BaseModel):
+    """Request to create a new flow."""
+
+    name: str
+    description: str = ""
+    interfaces: List[str] = Field(default_factory=list)
+    nodes: List[VisualNode] = Field(default_factory=list)
+    edges: List[VisualEdge] = Field(default_factory=list)
+    entryNode: Optional[str] = None
+
+
+class FlowUpdateRequest(BaseModel):
+    """Request to update an existing flow."""
+
+    name: Optional[str] = None
+    description: Optional[str] = None
+    interfaces: Optional[List[str]] = None
+    nodes: Optional[List[VisualNode]] = None
+    edges: Optional[List[VisualEdge]] = None
+    entryNode: Optional[str] = None
+
+
+class FlowRunRequest(BaseModel):
+    """Request to execute a flow."""
+
+    input_data: Dict[str, Any] = Field(default_factory=dict)
+
+
+class FlowRunResult(BaseModel):
+    """Result of a flow execution."""
+
+    success: bool
+    result: Optional[Any] = None
+    error: Optional[str] = None
+    run_id: Optional[str] = None
+    waiting: bool = False
+    wait_key: Optional[str] = None
+    prompt: Optional[str] = None
+    choices: Optional[List[str]] = None
+    allow_free_text: Optional[bool] = None
+
+
+class ExecutionMetrics(BaseModel):
+    """Optional per-step (or whole-run) execution metrics.
+
+    These fields are best-effort and may be omitted depending on host/runtime capabilities.
+    """
+
+    duration_ms: Optional[float] = None
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+    tokens_per_s: Optional[float] = None
+
+
+class ExecutionEvent(BaseModel):
+    """Real-time execution event for WebSocket."""
+
+    type: str  # "node_start", "node_complete", "flow_complete", "flow_error"
+    # ISO 8601 UTC timestamp for event emission (host-side observability).
+    ts: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    runId: Optional[str] = None
+    nodeId: Optional[str] = None
+    result: Optional[Any] = None
+    error: Optional[str] = None
+    meta: Optional[ExecutionMetrics] = None

abstractflow/visual/session_runner.py

@@ -0,0 +1,182 @@
+"""Session-aware runner for VisualFlow executions.
+
+This runner extends FlowRunner with:
+- A durable session_id (defaults to root run_id)
+- Auto-started custom event listener workflows ("On Event" nodes)
+
+This keeps VisualFlow JSON portable: any host can execute a visual flow and its
+event listeners using AbstractRuntime's durable semantics.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+from ..runner import FlowRunner
+
+if TYPE_CHECKING:
+    from abstractruntime.core.runtime import Runtime
+    from abstractruntime.core.spec import WorkflowSpec
+
+
+class VisualSessionRunner(FlowRunner):
+    """FlowRunner that starts event listener workflows within the same session."""
+
+    def __init__(
+        self,
+        flow: Any,
+        *,
+        runtime: Optional["Runtime"] = None,
+        event_listener_specs: Optional[List["WorkflowSpec"]] = None,
+    ) -> None:
+        super().__init__(flow, runtime=runtime)
+        self._event_listener_specs: List["WorkflowSpec"] = list(event_listener_specs or [])
+        self._event_listener_run_ids: List[str] = []
+
+    @property
+    def event_listener_run_ids(self) -> List[str]:
+        return list(self._event_listener_run_ids)
+
+    def start(
+        self,
+        input_data: Optional[Dict[str, Any]] = None,
+        *,
+        actor_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+    ) -> str:
+        run_id = super().start(input_data, actor_id=actor_id, session_id=session_id)
+
+        # Default session_id to the root run_id for session-scoped events.
+        # If a session_id is explicitly provided, preserve it.
+        effective_session_id = session_id
+        try:
+            state = self.runtime.get_state(run_id)
+            if not getattr(state, "session_id", None):
+                state.session_id = run_id  # type: ignore[attr-defined]
+                self.runtime.run_store.save(state)
+            effective_session_id = str(getattr(state, "session_id", None) or run_id).strip() or run_id
+        except Exception:
+            # Best-effort; session-scoped keys will fall back to run_id if missing.
+            effective_session_id = str(session_id).strip() if isinstance(session_id, str) and session_id.strip() else run_id
+
+        if not self._event_listener_specs:
+            return run_id
+
+        # Start listeners as child runs in the same session.
+        for spec in self._event_listener_specs:
+            try:
+                child_run_id = self.runtime.start(
+                    workflow=spec,
+                    vars={},
+                    session_id=effective_session_id,
+                    actor_id=actor_id,
+                    parent_run_id=run_id,
+                )
+                # Advance the listener to its first WAIT_EVENT (On Event node).
+                self.runtime.tick(workflow=spec, run_id=child_run_id, max_steps=10)
+                self._event_listener_run_ids.append(child_run_id)
+            except Exception:
+                # Listener start failures should surface during execution, but
+                # we don't want to hide root runs from starting.
+                continue
+
+        return run_id
+
+    def run(
+        self,
+        input_data: Optional[Dict[str, Any]] = None,
+        *,
+        actor_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Execute the root run and drive session-level listener runs.
+
+        Rationale:
+        - `EMIT_EVENT` resumes listener runs but does not (by default) execute them.
+        - Hosts that only "run the main workflow" should still see event handler branches run.
+        """
+        from abstractruntime.core.models import RunStatus, WaitReason
+
+        run_id = self.start(input_data, actor_id=actor_id, session_id=session_id)
+        runtime = self.runtime
+
+        def _list_session_runs() -> List[str]:
+            out: List[str] = [run_id]
+            try:
+                rs = getattr(runtime, "run_store", None)
+                if rs is not None and hasattr(rs, "list_children"):
+                    children = rs.list_children(parent_run_id=run_id)  # type: ignore[attr-defined]
+                    for c in children:
+                        cid = getattr(c, "run_id", None)
+                        if isinstance(cid, str) and cid and cid not in out:
+                            out.append(cid)
+            except Exception:
+                pass
+            for cid in self._event_listener_run_ids:
+                if cid not in out:
+                    out.append(cid)
+            return out
+
+        def _tick_child(child_run_id: str, *, max_steps: int = 100) -> None:
+            st = runtime.get_state(child_run_id)
+            if st.status != RunStatus.RUNNING:
+                # WAIT_UNTIL can auto-unblock, so still call tick() to allow progress.
+                if st.status == RunStatus.WAITING and st.waiting and st.waiting.reason == WaitReason.UNTIL:
+                    pass
+                else:
+                    return
+            reg = getattr(runtime, "workflow_registry", None)
+            if reg is None:
+                return
+            wf = reg.get(st.workflow_id)
+            if wf is None:
+                return
+            runtime.tick(workflow=wf, run_id=child_run_id, max_steps=max_steps)
+
+        while True:
+            state = runtime.tick(workflow=self.workflow, run_id=run_id, max_steps=100)
+
+            # Drive children that became RUNNING due to EMIT_EVENT (or subflows).
+            for cid in _list_session_runs():
+                if cid == run_id:
+                    continue
+                _tick_child(cid, max_steps=100)
+
+            # Root completion/termination conditions.
+            if state.status == RunStatus.COMPLETED:
+                # If all children are idle listeners (WAITING EVENT) or terminal, close the session.
+                all_idle_or_done = True
+                for cid in _list_session_runs():
+                    if cid == run_id:
+                        continue
+                    st = runtime.get_state(cid)
+                    if st.status in (RunStatus.COMPLETED, RunStatus.FAILED, RunStatus.CANCELLED):
+                        continue
+                    if st.status == RunStatus.WAITING and st.waiting and st.waiting.reason == WaitReason.EVENT:
+                        continue
+                    all_idle_or_done = False
+                if all_idle_or_done:
+                    # Cancel idle listeners to keep the session tidy.
+                    for cid in _list_session_runs():
+                        if cid == run_id:
+                            continue
+                        st = runtime.get_state(cid)
+                        if st.status == RunStatus.WAITING and st.waiting and st.waiting.reason == WaitReason.EVENT:
+                            try:
+                                runtime.cancel_run(cid, reason="Session completed")
+                            except Exception:
+                                pass
+                    return self._normalize_completed_output(state.output)
+                # Otherwise, keep driving until children settle into waits/terminal.
+                continue
+
+            if state.status == RunStatus.FAILED:
+                raise RuntimeError(f"Flow failed: {state.error}")
+
+            if state.status == RunStatus.WAITING:
+                # Preserve FlowRunner shape.
+                return {
+                    "waiting": True,
+                    "state": state,
+                    "wait_key": state.waiting.wait_key if state.waiting else None,
+                }

abstractflow/visual/workspace_scoped_tools.py

@@ -0,0 +1,29 @@
+"""Workspace-scoped tool execution helpers (AbstractFlow re-export).
+
+The core implementation lives in AbstractRuntime's AbstractCore integration so it can
+be shared across hosts/clients. AbstractFlow re-exports the types to preserve existing
+imports (`abstractflow.visual.workspace_scoped_tools`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from abstractruntime.integrations.abstractcore.workspace_scoped_tools import (  # noqa: F401
+    WorkspaceScope,
+    WorkspaceScopedToolExecutor,
+    resolve_workspace_base_dir,
+    resolve_user_path,
+)
+
+
+def build_scoped_tool_executor(*, scope: WorkspaceScope) -> Any:
+    """Create a local tool executor wrapped with workspace scoping."""
+    from abstractruntime.integrations.abstractcore.default_tools import get_default_tools
+    from abstractruntime.integrations.abstractcore.tool_executor import MappingToolExecutor
+
+    delegate = MappingToolExecutor.from_tools(get_default_tools())
+    return WorkspaceScopedToolExecutor(scope=scope, delegate=delegate)
+
+
+