liyaengine 0.2.0__tar.gz → 0.3.0__tar.gz

{liyaengine-0.2.0 → liyaengine-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: liyaengine
-Version: 0.2.0
+Version: 0.3.0
 Summary: Official Python client for the Liya Engine public API
 Project-URL: Homepage, https://liyaengine.ai
 Project-URL: Documentation, https://liyaengine.ai/docs/sdks/python
@@ -31,7 +31,7 @@ Description-Content-Type: text/markdown
 
 Official Python client for the [Liya Engine](https://liyaengine.ai) public API.
 
-> **Status: early access.** This SDK currently covers Collections and Agents. More resources (Domains, Run, Workflows, Guardrail Policies, Evals) ship incrementally — see [Roadmap](#roadmap).
+> **Status: early access.** This SDK currently covers Collections, Agents, and Workflows. More resources (Domains, Run, Guardrail Policies, Evals) ship incrementally — see [Roadmap](#roadmap).
 
 ## Install
 
@@ -81,6 +81,33 @@ result = client.agents.run(agent.agent_key, input={"message": "My order hasn't a
 history = client.agents.list_runs(agent.agent_key)
 ```
 
+## Workflows
+
+```python
+workflow = client.workflows.create(
+    name="Lead Intake",
+    steps=[{"step_type": "trigger", "config": {"trigger_subtype": "webhook"}}],
+)
+
+# Workflows are created in draft status — deploy to publish and make them
+# callable. Deploying a webhook-triggered workflow for the first time mints
+# its webhook secret; capture it immediately, it is never returned again.
+deployed = client.workflows.deploy(workflow.workflow_key)
+webhook_url, webhook_secret = deployed["webhook_url"], deployed["webhook_secret"]
+
+# Roll the secret with a grace window so in-flight senders don't break.
+client.workflows.rotate_webhook_secret(workflow.workflow_key, grace_period_seconds=300)
+
+# Flip a deployed workflow on/off without touching its definition.
+client.workflows.toggle(workflow.workflow_key)
+
+result = client.workflows.run(workflow.workflow_key, input={"email": "ada@example.com"})
+
+history = client.workflows.list_runs(workflow.workflow_key)
+```
+
+> `deploy()` and `rotate_webhook_secret()` return the plaintext webhook secret exactly once. Store it immediately — subsequent reads (`get`, `list`) only ever expose `trigger_config["has_secret"]`.
+
 ## Error handling
 
 Every failed request raises `LiyaEngineAPIError`, carrying the API's `code`, `message`, and HTTP `status`:
@@ -114,9 +141,9 @@ LiyaEngine(
 
 - [x] Collections
 - [x] Agents (full CRUD, deploy, run, run/session history)
+- [x] Workflows (full CRUD, toggle, deploy, webhook secret rotate, run, run history)
 - [ ] Domains (custom domain + intent CRUD)
 - [ ] Run / Run (streaming)
-- [ ] Workflows
 - [ ] Guardrail Policies
 - [ ] Evaluations
 - [ ] Async client

{liyaengine-0.2.0 → liyaengine-0.3.0}/README.md

@@ -2,7 +2,7 @@
 
 Official Python client for the [Liya Engine](https://liyaengine.ai) public API.
 
-> **Status: early access.** This SDK currently covers Collections and Agents. More resources (Domains, Run, Workflows, Guardrail Policies, Evals) ship incrementally — see [Roadmap](#roadmap).
+> **Status: early access.** This SDK currently covers Collections, Agents, and Workflows. More resources (Domains, Run, Guardrail Policies, Evals) ship incrementally — see [Roadmap](#roadmap).
 
 ## Install
 
@@ -52,6 +52,33 @@ result = client.agents.run(agent.agent_key, input={"message": "My order hasn't a
 history = client.agents.list_runs(agent.agent_key)
 ```
 
+## Workflows
+
+```python
+workflow = client.workflows.create(
+    name="Lead Intake",
+    steps=[{"step_type": "trigger", "config": {"trigger_subtype": "webhook"}}],
+)
+
+# Workflows are created in draft status — deploy to publish and make them
+# callable. Deploying a webhook-triggered workflow for the first time mints
+# its webhook secret; capture it immediately, it is never returned again.
+deployed = client.workflows.deploy(workflow.workflow_key)
+webhook_url, webhook_secret = deployed["webhook_url"], deployed["webhook_secret"]
+
+# Roll the secret with a grace window so in-flight senders don't break.
+client.workflows.rotate_webhook_secret(workflow.workflow_key, grace_period_seconds=300)
+
+# Flip a deployed workflow on/off without touching its definition.
+client.workflows.toggle(workflow.workflow_key)
+
+result = client.workflows.run(workflow.workflow_key, input={"email": "ada@example.com"})
+
+history = client.workflows.list_runs(workflow.workflow_key)
+```
+
+> `deploy()` and `rotate_webhook_secret()` return the plaintext webhook secret exactly once. Store it immediately — subsequent reads (`get`, `list`) only ever expose `trigger_config["has_secret"]`.
+
 ## Error handling
 
 Every failed request raises `LiyaEngineAPIError`, carrying the API's `code`, `message`, and HTTP `status`:
@@ -85,9 +112,9 @@ LiyaEngine(
 
 - [x] Collections
 - [x] Agents (full CRUD, deploy, run, run/session history)
+- [x] Workflows (full CRUD, toggle, deploy, webhook secret rotate, run, run history)
 - [ ] Domains (custom domain + intent CRUD)
 - [ ] Run / Run (streaming)
-- [ ] Workflows
 - [ ] Guardrail Policies
 - [ ] Evaluations
 - [ ] Async client

{liyaengine-0.2.0 → liyaengine-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "liyaengine"
-version = "0.2.0"
+version = "0.3.0"
 description = "Official Python client for the Liya Engine public API"
 readme = "README.md"
 license = "MIT"

{liyaengine-0.2.0 → liyaengine-0.3.0}/src/liyaengine/__init__.py

@@ -2,6 +2,7 @@ from .client import LiyaEngine
 from .errors import LiyaEngineAPIError, LiyaEngineNetworkError
 from .resources.agents import Agent
 from .resources.collections import Collection
+from .resources.workflows import Workflow
 
 __all__ = [
     "LiyaEngine",
@@ -9,6 +10,7 @@ __all__ = [
     "LiyaEngineNetworkError",
     "Collection",
     "Agent",
+    "Workflow",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{liyaengine-0.2.0 → liyaengine-0.3.0}/src/liyaengine/client.py

@@ -7,6 +7,7 @@ import httpx
 from ._http import HttpClient
 from .resources.agents import AgentsResource
 from .resources.collections import CollectionsResource
+from .resources.workflows import WorkflowsResource
 
 _DEFAULT_BASE_URL = "https://api.liyaengine.ai"
 
@@ -41,6 +42,7 @@ class LiyaEngine:
         )
         self.collections = CollectionsResource(self._http)
         self.agents = AgentsResource(self._http)
+        self.workflows = WorkflowsResource(self._http)
 
     def close(self) -> None:
         self._http.close()

liyaengine-0.3.0/src/liyaengine/resources/workflows.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, cast
+from urllib.parse import quote, urlencode
+
+from .._http import HttpClient
+
+
+@dataclass(frozen=True)
+class Workflow:
+    id: str
+    tenant_id: str
+    name: str
+    workflow_key: str
+    description: Optional[str]
+    is_active: bool
+    status: str
+    trigger_type: str
+    trigger_config: Optional[Dict[str, Any]]
+    created_at: str
+    updated_at: str
+    steps: List[Dict[str, Any]]
+
+    @classmethod
+    def _from_dict(cls, data: Dict[str, Any]) -> "Workflow":
+        return cls(
+            id=data["id"],
+            tenant_id=data["tenant_id"],
+            name=data["name"],
+            workflow_key=data["workflow_key"],
+            description=data.get("description"),
+            is_active=data["is_active"],
+            status=data["status"],
+            trigger_type=data["trigger_type"],
+            trigger_config=data.get("trigger_config"),
+            created_at=data["created_at"],
+            updated_at=data["updated_at"],
+            steps=data.get("steps", []),
+        )
+
+
+def _query(**params: Any) -> str:
+    pairs = {k: v for k, v in params.items() if v is not None}
+    return f"?{urlencode(pairs)}" if pairs else ""
+
+
+class WorkflowsResource:
+    """Multi-step graphs of intents/agents/actions/conditions. Mirrors the
+    full /v1/workflows surface (see openapi.yaml): CRUD + toggle/deploy/
+    webhook-secret-rotate, plus run/run-history. `workflow_id_or_key` in
+    every method below accepts either the database id or the human-readable
+    workflow_key.
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> List[Workflow]:
+        data = self._http.get("/v1/workflows")
+        return [Workflow._from_dict(w) for w in cast(List[Dict[str, Any]], data)]
+
+    def get(self, workflow_id_or_key: str) -> Workflow:
+        data = self._http.get(f"/v1/workflows/{quote(workflow_id_or_key)}")
+        return Workflow._from_dict(data)
+
+    def create(
+        self,
+        *,
+        name: str,
+        description: Optional[str] = None,
+        steps: Optional[List[Dict[str, Any]]] = None,
+    ) -> Workflow:
+        body: Dict[str, Any] = {"name": name}
+        if description is not None:
+            body["description"] = description
+        if steps is not None:
+            body["steps"] = steps
+
+        data = self._http.post("/v1/workflows", body)
+        return Workflow._from_dict(data["workflow"])
+
+    def update(
+        self,
+        workflow_id_or_key: str,
+        *,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        workflow_key: Optional[str] = None,
+        steps: Optional[List[Dict[str, Any]]] = None,
+    ) -> Workflow:
+        """`steps` is upsert-by-id: an existing step id present in this list is
+        updated in place, a new one is created, and any existing step id
+        omitted from this list is deleted.
+        """
+        body: Dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        if workflow_key is not None:
+            body["workflow_key"] = workflow_key
+        if steps is not None:
+            body["steps"] = steps
+
+        data = self._http.patch(f"/v1/workflows/{quote(workflow_id_or_key)}", body)
+        return Workflow._from_dict(data["workflow"])
+
+    def toggle(self, workflow_id_or_key: str) -> Workflow:
+        """Flips is_active on an already-deployed workflow. Blocked on a draft
+        (raises LiyaEngineAPIError(code='DEPLOY_REQUIRED')) — deploy() it first.
+        """
+        data = self._http.patch(f"/v1/workflows/{quote(workflow_id_or_key)}/toggle")
+        return Workflow._from_dict(data["workflow"])
+
+    def deploy(self, workflow_id_or_key: str) -> Dict[str, Any]:
+        """The draft->published transition. On first deploy of a
+        webhook-triggered workflow, also mints the webhook infrastructure and
+        returns the secret exactly once as `webhook_secret` — capture it
+        immediately, it is never retrievable again. Returns
+        {"workflow": Workflow-shaped dict, "webhook_url"?: str, "webhook_secret"?: str}.
+        """
+        return cast(Dict[str, Any], self._http.post(f"/v1/workflows/{quote(workflow_id_or_key)}/deploy"))
+
+    def rotate_webhook_secret(
+        self, workflow_id_or_key: str, *, grace_period_seconds: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """Only valid for a webhook-triggered, already-deployed workflow. The
+        previous secret stays valid for `grace_period_seconds` (default 300,
+        max 3600) so external senders can roll over without downtime; pass 0
+        for an immediate hard cutover. The new secret is returned exactly once.
+        """
+        body = {"grace_period_seconds": grace_period_seconds} if grace_period_seconds is not None else None
+        return cast(Dict[str, Any], self._http.post(f"/v1/workflows/{quote(workflow_id_or_key)}/webhook-secret/rotate", body))
+
+    def delete(self, workflow_id_or_key: str) -> None:
+        """A hard delete — unlike Collections and Agents, there is no soft-delete/inactive state for a removed workflow."""
+        self._http.delete(f"/v1/workflows/{quote(workflow_id_or_key)}")
+
+    def run(
+        self, workflow_id_or_key: str, *, input: Optional[Dict[str, Any]] = None, conversation_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {}
+        if input is not None:
+            body["input"] = input
+        if conversation_id is not None:
+            body["conversation_id"] = conversation_id
+        return cast(Dict[str, Any], self._http.post(f"/v1/workflows/{quote(workflow_id_or_key)}/run", body))
+
+    def list_runs(
+        self, workflow_id_or_key: str, *, page: Optional[int] = None, page_size: Optional[int] = None, status: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        qs = _query(page=page, pageSize=page_size, status=status)
+        return cast(Dict[str, Any], self._http.get(f"/v1/workflows/{quote(workflow_id_or_key)}/runs{qs}"))
+
+    def get_run(self, workflow_id_or_key: str, run_id: str) -> Dict[str, Any]:
+        data = self._http.get(f"/v1/workflows/{quote(workflow_id_or_key)}/runs/{quote(run_id)}")
+        return cast(Dict[str, Any], data["run"])

liyaengine-0.3.0/tests/test_workflows.py

@@ -0,0 +1,163 @@
+import httpx
+import pytest
+import respx
+
+from liyaengine import LiyaEngine, LiyaEngineAPIError
+
+BASE_URL = "https://api.test.liyaengine.ai"
+
+FIXTURE_WORKFLOW = {
+    "id": "wf_123",
+    "tenant_id": "tenant_1",
+    "name": "Lead Intake",
+    "workflow_key": "lead-intake",
+    "description": None,
+    "is_active": False,
+    "status": "draft",
+    "trigger_type": "webhook",
+    "trigger_config": None,
+    "created_at": "2026-01-01T00:00:00.000Z",
+    "updated_at": "2026-01-01T00:00:00.000Z",
+    "steps": [],
+}
+
+
+@pytest.fixture
+def client():
+    with LiyaEngine(api_key="liya_test_key", base_url=BASE_URL) as c:
+        yield c
+
+
+@respx.mock
+def test_list_returns_deployed_workflows(client):
+    respx.get(f"{BASE_URL}/v1/workflows").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": [{**FIXTURE_WORKFLOW, "status": "active", "is_active": True}]})
+    )
+    workflows = client.workflows.list()
+    assert len(workflows) == 1
+    assert workflows[0].workflow_key == "lead-intake"
+
+
+@respx.mock
+def test_get_returns_workflow(client):
+    respx.get(f"{BASE_URL}/v1/workflows/lead-intake").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": FIXTURE_WORKFLOW})
+    )
+    workflow = client.workflows.get("lead-intake")
+    assert workflow.id == "wf_123"
+
+
+@respx.mock
+def test_get_raises_typed_404(client):
+    respx.get(f"{BASE_URL}/v1/workflows/missing").mock(
+        return_value=httpx.Response(404, json={"success": False, "error": {"code": "WORKFLOW_NOT_FOUND", "message": "not found"}})
+    )
+    with pytest.raises(LiyaEngineAPIError) as exc_info:
+        client.workflows.get("missing")
+    assert exc_info.value.code == "WORKFLOW_NOT_FOUND"
+
+
+@respx.mock
+def test_create_returns_draft_workflow(client):
+    respx.post(f"{BASE_URL}/v1/workflows").mock(
+        return_value=httpx.Response(201, json={"success": True, "data": {"workflow": {**FIXTURE_WORKFLOW, "id": "wf_new"}}})
+    )
+    workflow = client.workflows.create(name="Lead Intake")
+    assert workflow.id == "wf_new"
+    assert workflow.status == "draft"
+
+
+@respx.mock
+def test_update_patches_workflow(client):
+    respx.patch(f"{BASE_URL}/v1/workflows/lead-intake").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {"workflow": {**FIXTURE_WORKFLOW, "name": "Renamed"}}})
+    )
+    updated = client.workflows.update("lead-intake", name="Renamed")
+    assert updated.name == "Renamed"
+
+
+@respx.mock
+def test_toggle_flips_is_active(client):
+    respx.patch(f"{BASE_URL}/v1/workflows/lead-intake/toggle").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {"workflow": {**FIXTURE_WORKFLOW, "status": "active", "is_active": True}}})
+    )
+    toggled = client.workflows.toggle("lead-intake")
+    assert toggled.is_active is True
+
+
+@respx.mock
+def test_toggle_raises_typed_409_when_draft(client):
+    respx.patch(f"{BASE_URL}/v1/workflows/draft-wf/toggle").mock(
+        return_value=httpx.Response(409, json={"success": False, "error": {"code": "DEPLOY_REQUIRED", "message": "deploy first"}})
+    )
+    with pytest.raises(LiyaEngineAPIError) as exc_info:
+        client.workflows.toggle("draft-wf")
+    assert exc_info.value.code == "DEPLOY_REQUIRED"
+
+
+@respx.mock
+def test_deploy_returns_one_time_webhook_secret(client):
+    respx.post(f"{BASE_URL}/v1/workflows/lead-intake/deploy").mock(
+        return_value=httpx.Response(200, json={
+            "success": True,
+            "data": {
+                "workflow": {**FIXTURE_WORKFLOW, "status": "active", "is_active": True},
+                "webhook_url": "https://api.test.liyaengine.ai/webhooks/workflows/abc123",
+                "webhook_secret": "plaintext-secret-shown-once",
+            },
+        })
+    )
+    result = client.workflows.deploy("lead-intake")
+    assert result["workflow"]["status"] == "active"
+    assert result["webhook_secret"] == "plaintext-secret-shown-once"
+
+
+@respx.mock
+def test_rotate_webhook_secret_returns_new_secret(client):
+    respx.post(f"{BASE_URL}/v1/workflows/lead-intake/webhook-secret/rotate").mock(
+        return_value=httpx.Response(200, json={
+            "success": True,
+            "data": {
+                "webhook_url": "https://api.test.liyaengine.ai/webhooks/workflows/abc123",
+                "webhook_secret": "new-plaintext-secret",
+                "previous_secret_valid_until": "2026-01-01T00:05:00.000Z",
+            },
+        })
+    )
+    result = client.workflows.rotate_webhook_secret("lead-intake", grace_period_seconds=300)
+    assert result["webhook_secret"] == "new-plaintext-secret"
+    assert result["previous_secret_valid_until"] == "2026-01-01T00:05:00.000Z"
+
+
+@respx.mock
+def test_delete_does_not_raise(client):
+    respx.delete(f"{BASE_URL}/v1/workflows/lead-intake").mock(return_value=httpx.Response(200, json={"success": True}))
+    client.workflows.delete("lead-intake")
+
+
+@respx.mock
+def test_run_returns_result(client):
+    respx.post(f"{BASE_URL}/v1/workflows/lead-intake/run").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {"run_id": "run_1", "conversation_id": "convo_1", "status": "completed", "trace": []}})
+    )
+    result = client.workflows.run("lead-intake", input={"name": "Ada"})
+    assert result["run_id"] == "run_1"
+    assert result["status"] == "completed"
+
+
+@respx.mock
+def test_list_runs(client):
+    respx.get(f"{BASE_URL}/v1/workflows/lead-intake/runs").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {"runs": [], "pagination": {"page": 1}}})
+    )
+    result = client.workflows.list_runs("lead-intake")
+    assert result["runs"] == []
+
+
+@respx.mock
+def test_get_run(client):
+    respx.get(f"{BASE_URL}/v1/workflows/lead-intake/runs/run_1").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {"run": {"id": "run_1"}}})
+    )
+    run = client.workflows.get_run("lead-intake", "run_1")
+    assert run["id"] == "run_1"