workflow-exec-engine 0.0.2__py3-none-any.whl

workflow_engine/core/models.py

@@ -0,0 +1,184 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""Data models for the Workflow Execution SDK."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional, Dict, Any
+
+
+class StepType(Enum):
+    ALL_SUCCESS = "AllSuccess"
+    ANY_SUCCESS = "AnySuccess"
+    SELF_LOOP = "SelfLoop"
+
+    @classmethod
+    def from_value(cls, value: Any) -> "StepType":
+        """Case-insensitive lookup by enum value or name.
+
+        Accepts "AllSuccess", "ALLSUCCESS", "allsuccess", "ALL_SUCCESS",
+        "any_success", etc. Falls back to ALL_SUCCESS when unknown.
+        Mirrors the Java SDK's StepType.fromValue().
+        """
+        if not value:
+            return cls.ALL_SUCCESS
+        if isinstance(value, StepType):
+            return value
+        # Handle enum objects from other modules (e.g. the orchestration
+        # center's own StepType): extract .value so str() does not produce
+        # "StepType.SELF_LOOP" which would never match.
+        if hasattr(value, "value"):
+            value = value.value
+        text = str(value).strip()
+        for member in cls:
+            if member.value.lower() == text.lower() or member.name.lower() == text.lower():
+                return member
+        return cls.ALL_SUCCESS
+
+
+class TaskStatus(Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCESS = "success"
+    FAILED = "failed"
+
+
+@dataclass
+class WorkflowSearchResult:
+    """Summary of a PSOP workflow returned by the search endpoint.
+
+    Mirrors the Java SDK's WorkflowSearchResult. Returned by
+    ``search_psop()``. To get the full workflow with steps, take
+    ``workflow_id`` and call ``load_psop()``.
+    """
+    workflow_id: str = ""
+    workflow_type: str = ""
+    name: str = ""
+    description: str = ""
+    tags: List[str] = field(default_factory=list)
+    created_at: str = ""
+    score: float = 1.0
+    user_intent: str = ""
+    related_preflow: str = ""
+    tasks_summary: str = ""
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "WorkflowSearchResult":
+        return cls(
+            workflow_id=data.get("workflow_id", data.get("id", "")),
+            workflow_type=data.get("workflow_type", ""),
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            tags=data.get("tags", []),
+            created_at=str(data["created_at"]) if data.get("created_at") else "",
+            score=float(data["score"]) if isinstance(data.get("score"), (int, float)) else 1.0,
+            user_intent=data.get("user_intent", ""),
+            related_preflow=data.get("related_preflow", ""),
+            tasks_summary=data.get("tasks_summary", ""),
+        )
+
+
+@dataclass
+class JumpCondition:
+    step: str
+    condition: str = ""
+
+
+@dataclass
+class Task:
+    agent: str
+    skill: str = ""
+    description: str = ""
+    status: TaskStatus = TaskStatus.PENDING
+
+
+@dataclass
+class WorkflowStep:
+    name: str
+    subtasks: List[Task] = field(default_factory=list)
+    next: List[JumpCondition] = field(default_factory=list)
+    layer: int = 0
+    context_from: Optional[List[str]] = None
+    step_type: StepType = StepType.ALL_SUCCESS
+
+
+@dataclass
+class Workflow:
+    id: str = ""
+    name: str = ""
+    description: str = ""
+    steps: List[WorkflowStep] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Workflow":
+        steps = []
+        for s in data.get("steps", []):
+            subtasks = [Task(agent=t.get("agent",""), skill=t.get("skill",""), description=t.get("description","")) for t in (s.get("subtasks") or [])]
+            next_list = [JumpCondition(step=jc.get("step",""), condition=jc.get("condition","")) for jc in (s.get("next") or [])]
+            st = s.get("step_type", s.get("type", "AllSuccess"))
+            step_type = StepType.from_value(st)
+            cf = s.get("context_from")
+            if cf and not isinstance(cf, list): cf = [cf]
+            steps.append(WorkflowStep(name=s.get("name",""), subtasks=subtasks, next=next_list, layer=s.get("layer",0), context_from=cf, step_type=step_type))
+        return cls(id=data.get("id",""), name=data.get("name",""), description=data.get("description",""), steps=steps)
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "Workflow":
+        import json
+        return cls.from_dict(json.loads(json_str))
+
+
+@dataclass
+class SendMessageResult:
+    text: str = ""
+    task: Any = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    task_state: str = ""
+
+
+@dataclass
+class TaskRequest:
+    agent_name: str
+    skill: str
+    message: str
+    context: str
+    step_name: str
+    subtask_index: int = 0
+    description: str = ""
+
+
+@dataclass
+class TaskResponse:
+    success: bool
+    output: str = ""
+    error: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class RouteDecision:
+    next_step: str
+    reason: str = ""
+
+
+@dataclass
+class ExecutionResult:
+    success: bool
+    history: List[Dict[str, Any]] = field(default_factory=list)
+    step_outputs: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+    error: Optional[str] = None

workflow_engine/registry/__init__.py

@@ -0,0 +1,21 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+
+from workflow_engine.registry.registry_client import RegistryClient, load_psop, search_psop
+
+__all__ = ["RegistryClient", "load_psop", "search_psop"]

workflow_engine/registry/registry_client.py

@@ -0,0 +1,177 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""Optional helper for fetching AgentCards from the Registry Center.
+
+Users can use this, or fetch AgentCards from any other source.
+The SDK does not depend on this module.
+"""
+
+import json
+from typing import List, Any
+from loguru import logger
+
+from workflow_engine.client.agentcard_normalizer import normalize_agent_dict
+
+
+
+async def load_psop(
+    base_url: str,
+    psop_id: str,
+    access_token: str = None,
+    ssl_verify: bool = True,
+) -> "Workflow":
+    """Fetch a PSOP from the orchestration center external API.
+
+    Uses the public external endpoint GET /api/v1/orchestrate/psop/{psop_id}.
+    Pass access_token when the orchestration center has external auth enabled.
+    Set ssl_verify=False for self-signed certs (dev only).
+    """
+    import httpx
+    from workflow_engine.core.models import Workflow
+    url = f"{base_url}/api/v1/orchestrate/psop/{psop_id}"
+    params = {}
+    if access_token:
+        params["access_token"] = access_token
+    logger.info(f"[Registry] Loading PSOP from {url} (ssl_verify={ssl_verify})")
+    async with httpx.AsyncClient(verify=ssl_verify, timeout=30, follow_redirects=True) as client:
+        resp = await client.get(url, params=params)
+        resp.raise_for_status()
+        data = resp.json()
+    wf = Workflow.from_dict(data.get("data", data))
+    logger.info(f"[Registry] Loaded workflow: {wf.name}, {len(wf.steps)} steps")
+    return wf
+
+
+async def search_psop(
+    base_url: str,
+    intent: str,
+    top_n: int = 5,
+    access_token: str = None,
+    ssl_verify: bool = True,
+) -> List["WorkflowSearchResult"]:
+    """Search for matching PSOP workflows from the orchestration center.
+
+    Uses the public external endpoint POST /api/v1/orchestrate/search.
+    Returns a list of WorkflowSearchResult summary objects. To get the full
+    workflow with steps, take ``workflow_id`` from a result and call
+    ``load_psop(base_url, workflow_id, ...)``. Mirrors the Java SDK's
+    LoadPsop.search which returns WorkflowSearchResult.
+    """
+    import httpx
+    from workflow_engine.core.models import WorkflowSearchResult
+    url = f"{base_url}/api/v1/orchestrate/search"
+    params = {}
+    if access_token:
+        params["access_token"] = access_token
+    body = {"intent": intent, "top_n": top_n}
+    logger.info(f"[Registry] Searching PSOP at {url} (intent={intent[:60]}, top_n={top_n})")
+    async with httpx.AsyncClient(verify=ssl_verify, timeout=30, follow_redirects=True) as client:
+        resp = await client.post(url, json=body, params=params)
+        resp.raise_for_status()
+        data = resp.json()
+    raw_results = data.get("data", [])
+    results = [WorkflowSearchResult.from_dict(r) for r in raw_results]
+    logger.info(f"[Registry] Search returned {len(results)} workflow(s)")
+    return results
+
+
+
+class RegistryClient:
+    """Fetches AgentCards from the Registry Center."""
+
+    def __init__(self, url: str, ssl_verify: bool = False, verify_ssl: bool = None):
+        # Accept the legacy ``verify_ssl`` keyword for backward compatibility;
+        # ``ssl_verify`` matches WorkflowEngineClient / load_psop / execute_psop.
+        if verify_ssl is not None:
+            ssl_verify = verify_ssl
+        self.url = url.rstrip("/")
+        self.ssl_verify = ssl_verify
+
+    async def fetch_agent_cards(self) -> List[Any]:
+        """Fetch all AgentCards. Returns protobuf objects if a2a-sdk available, else dicts."""
+        import httpx
+        logger.info(f"[Registry] Fetching all agent cards from {self.url}")
+        async with httpx.AsyncClient(verify=self.ssl_verify, timeout=30) as client:
+            resp = await client.get(f"{self.url}/rest/v1/registry-center/agent-cards")
+            resp.raise_for_status()
+            data = resp.json()
+            raw_cards = data.get("agentCards", data.get("data", []))
+        logger.info(f"[Registry] Received {len(raw_cards)} agent card(s)")
+        try:
+            from a2a.types import AgentCard
+            from google.protobuf.json_format import Parse
+            cards = []
+            for raw in raw_cards:
+                normalized = normalize_agent_dict(raw)
+                cards.append(Parse(json.dumps(normalized), AgentCard()))
+            logger.info(f"[Registry] Parsed {len(cards)} AgentCard(s) into protobuf objects")
+            return cards
+        except ImportError:
+            logger.info(f"[Registry] a2a-sdk not available, returning raw dicts")
+            return raw_cards
+
+    async def fetch_agent_card(self, name: str, organization: str = None) -> Any:
+        """Fetch a single AgentCard by name."""
+        import httpx
+        logger.info(f"[Registry] Fetching agent card: name={name}, org={organization}")
+        params = {"name": name}
+        if organization:
+            params["organization"] = organization
+        async with httpx.AsyncClient(verify=self.ssl_verify, timeout=30) as client:
+            resp = await client.get(f"{self.url}/rest/v1/registry-center/agent-cards", params=params)
+            resp.raise_for_status()
+            data = resp.json()
+            cards = data.get("agentCards", data.get("data", []))
+            if not cards:
+                logger.warning(f"[Registry] Agent card not found: name={name}")
+                return None
+            raw = cards[0]
+            try:
+                from a2a.types import AgentCard
+                from google.protobuf.json_format import Parse
+                normalized = normalize_agent_dict(raw)
+                card = Parse(json.dumps(normalized), AgentCard())
+                logger.info(f"[Registry] Agent card parsed: name={name}")
+                return card
+            except ImportError:
+                logger.info(f"[Registry] a2a-sdk not available, returning raw dict")
+                return raw
+
+    async def register_agent_card(self, agent_card) -> dict:
+        """Register or update an AgentCard in the registry.
+
+        POSTs to /rest/v1/registry-center/agent-cards with the card wrapped
+        in an ``agentCards`` list. Mirrors the Java SDK's
+        RegistryClient.registerAgentCard.
+        """
+        import httpx
+        url = f"{self.url}/rest/v1/registry-center/agent-cards"
+        payload = {"agentCards": [agent_card]}
+        logger.info(f"[Registry] Registering agent card: name={agent_card.get('name') if isinstance(agent_card, dict) else getattr(agent_card, 'name', '?')}")
+        async with httpx.AsyncClient(verify=self.ssl_verify, timeout=30) as client:
+            resp = await client.post(url, json=payload)
+            result = resp.json()
+            if resp.status_code in (200, 201):
+                logger.info(f"[Registry] Agent card registered")
+            else:
+                logger.warning(f"[Registry] Registration returned {resp.status_code}: {resp.text}")
+            return result
+
+    @property
+    def base_url(self) -> str:
+        return self.url

workflow_engine/runner.py

@@ -0,0 +1,247 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""High-level PSOP runner -- execute + stream events + persistence hook.
+
+This is Layer 2 of the SDK: it wraps the low-level WorkflowExecutor /
+WorkflowEngineClient and adds the event-stream lifecycle that every host
+(HTTP/SSE server, CLI, batch job) would otherwise rewrite. The business
+provides only the decision callbacks (ControlPoint), an optional
+persistence hook (on_finish), and the transport (drain the async
+iterator).
+"""
+
+import asyncio
+import time
+from typing import Any, AsyncIterator, Awaitable, Callable, Optional, Union
+
+from loguru import logger
+
+from workflow_engine.core.models import Workflow, ExecutionResult
+from workflow_engine.core.executor import WorkflowExecutor
+from workflow_engine.client.engine_client import WorkflowEngineClient
+from workflow_engine.client.a2a_transport import A2ATransport
+from workflow_engine.control.control_points import ControlPoint, EventCallback
+
+
+def _serialize(data: Any) -> Any:
+    """Make event data JSON-serializable (pydantic models, protobuf, etc.)."""
+    if data is None or isinstance(data, (str, int, float, bool)):
+        return data
+    if hasattr(data, "model_dump"):
+        try:
+            return data.model_dump()
+        except Exception:
+            pass
+    if isinstance(data, dict):
+        return {k: _serialize(v) for k, v in data.items()}
+    if isinstance(data, (list, tuple)):
+        return [_serialize(v) for v in data]
+    if hasattr(data, "__dict__"):
+        try:
+            return {k: _serialize(v) for k, v in data.__dict__.items()
+                    if not k.startswith("_")}
+        except Exception:
+            return str(data)
+    return str(data)
+
+
+class _EventEmitter(EventCallback):
+    """Async-queue-backed event emitter shared by executor + engine_client.
+
+    Implements EventCallback (so WorkflowExecutor can use it directly) and
+    exposes emit() for WorkflowEngineClient to push agent_request/response.
+    """
+
+    def __init__(self):
+        self._queue: "asyncio.Queue[Optional[dict]]" = asyncio.Queue()
+        self._collected: list = []
+
+    def on_event(self, event_type: str, data: dict):
+        event = {"type": event_type, "data": _serialize(data), "timestamp": time.time()}
+        self._queue.put_nowait(event)
+        self._collected.append(event)
+
+    # Alias used by WorkflowEngineClient.
+    def emit(self, event_type: str, data: dict):
+        self.on_event(event_type, data)
+
+    def finish(self):
+        """Push the None sentinel so drain() exits."""
+        self._queue.put_nowait(None)
+
+    async def drain(self) -> AsyncIterator[dict]:
+        while True:
+            event = await self._queue.get()
+            if event is None:
+                return
+            yield event
+
+    @property
+    def collected(self) -> list:
+        return list(self._collected)
+
+
+async def execute_psop(
+    psop: Union[dict, Workflow],
+    agent_cards: list,
+    control_point: ControlPoint,
+    *,
+    engine_client: Optional[WorkflowEngineClient] = None,
+    runtime_intent: str = "",
+    lang: str = "zh",
+    a2at_env_path: Optional[str] = None,
+    credentials_config: Optional[Union[str, dict]] = None,
+    ssl_verify: bool = True,
+    ca_certs_path: Optional[str] = None,
+    on_finish: Optional[Callable[[ExecutionResult, list], Awaitable[None]]] = None,
+    on_event: Optional[Callable[[dict], Any]] = None,
+) -> AsyncIterator[dict]:
+    """Execute a PSOP end-to-end, yielding serialized event dicts.
+
+    Draining this async iterator drives execution. The SDK manages:
+
+    - lifecycle events: ``start`` / ``complete`` / ``error`` / ``close``
+    - cancellation: closing the iterator cancels the running workflow
+    - event collection: the full event list is passed to ``on_finish``
+
+    The business provides:
+
+    - ``control_point``: decision callbacks (on_task / on_route /
+      on_negotiation) -- the only place flow-decision policy lives.
+    - ``on_finish``: optional persistence hook, called with
+      (ExecutionResult, collected_events) after the workflow ends.
+    - ``on_event``: optional event transformer. Called per event; may
+      return the event unchanged, a different event, a list of events
+      (to inject business-specific events like ``psop_update``), or
+      None (to skip).
+
+    Yields (in order): ``start`` then the executor/engine events
+    (``step_start``, ``agent_request``, ``agent_response``,
+    ``task_status_changed``, ``route_decision``, ``step_complete``,
+    ``negotiation_*``, ``authorization_request``, ``notification``),
+    then ``complete`` (or ``error``), then ``close``.
+    """
+    if isinstance(psop, dict):
+        workflow = Workflow.from_dict(psop)
+    else:
+        workflow = psop
+
+    emitter = _EventEmitter()
+    if engine_client is None:
+        transport = A2ATransport(
+            agent_cards=agent_cards,
+            a2at_env_path=a2at_env_path,
+            credentials_config=credentials_config,
+            ssl_verify=ssl_verify,
+            ca_certs_path=ca_certs_path,
+        )
+        engine_client = WorkflowEngineClient(
+            transport, event_callback=emitter,
+        )
+    else:
+        # Attach the emitter to a caller-provided client so its
+        # agent_request/agent_response events reach this stream.
+        engine_client.set_event_callback(emitter)
+    executor = WorkflowExecutor(
+        workflow=workflow,
+        control_point=control_point,
+        engine_client=engine_client,
+        event_callback=emitter,
+        runtime_intent=runtime_intent,
+        lang=lang,
+    )
+
+    emitter.emit("start", {"workflow": workflow.name, "steps": len(workflow.steps)})
+
+    holder: dict = {}
+
+    async def _run_and_finalize():
+        try:
+            holder["result"] = await executor.run()
+        except asyncio.CancelledError:
+            holder["error"] = "Workflow cancelled (client disconnected)"
+        except Exception as e:
+            logger.error(f"[execute_psop] Execution failed: {e}", exc_info=True)
+            holder["error"] = str(e)
+        finally:
+            try:
+                await engine_client.close()
+            except Exception:
+                pass
+
+        result: ExecutionResult = holder.get("result") or ExecutionResult(
+            success=False, error=holder.get("error") or "Unknown error"
+        )
+        if result.success and "error" not in holder:
+            emitter.emit("complete", {
+                "history": result.history,
+                "step_outputs": result.step_outputs,
+            })
+        else:
+            emitter.emit("error", {
+                "error": holder.get("error") or result.error or "Execution failed",
+                "history": result.history,
+                "step_outputs": result.step_outputs,
+            })
+
+        if on_finish:
+            try:
+                ret = on_finish(result, emitter.collected)
+                if hasattr(ret, "__await__"):
+                    await ret
+            except Exception as e:
+                logger.error(f"[execute_psop] on_finish failed: {e}", exc_info=True)
+
+        emitter.emit("close", {})
+        emitter.finish()
+
+    run_task = asyncio.create_task(_run_and_finalize())
+
+    try:
+        async for event in emitter.drain():
+            if on_event is None:
+                yield event
+                continue
+            try:
+                transformed = on_event(event)
+                if asyncio.iscoroutine(transformed):
+                    transformed = await transformed
+            except Exception as e:
+                logger.warning(f"[execute_psop] on_event raised: {e}")
+                transformed = event
+            if transformed is None:
+                continue
+            if isinstance(transformed, list):
+                for e in transformed:
+                    yield e
+            else:
+                yield transformed
+    except GeneratorExit:
+        run_task.cancel()
+        try:
+            await run_task
+        except (asyncio.CancelledError, Exception):
+            pass
+        return
+
+    if not run_task.done():
+        run_task.cancel()
+        try:
+            await run_task
+        except (asyncio.CancelledError, Exception):
+            pass