vangrex 0.1.0__tar.gz

vangrex-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Mohammed Maaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vangrex-0.1.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.5
+Name: vangrex
+Version: 0.1.0
+Summary: Official Python SDK for the Vangrex AI workflow platform
+Project-URL: Homepage, https://vangrex.com
+Project-URL: Repository, https://github.com/Maaz2623/vangrex-v4
+Author: Mohammed Maaz
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,automation,vangrex,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio<2.0,>=0.23; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
+Requires-Dist: respx<1.0,>=0.21; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Vangrex Python SDK
+
+Official Python SDK for the Vangrex AI workflow platform.
+
+Trigger Vangrex workflows from your Python applications and consume execution updates in real time.
+
+## Installation
+
+```bash
+pip install vangrex
+```

vangrex-0.1.0/README.md

@@ -0,0 +1,11 @@
+# Vangrex Python SDK
+
+Official Python SDK for the Vangrex AI workflow platform.
+
+Trigger Vangrex workflows from your Python applications and consume execution updates in real time.
+
+## Installation
+
+```bash
+pip install vangrex
+```

vangrex-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[project]
+name = "vangrex"
+version = "0.1.0"
+description = "Official Python SDK for the Vangrex AI workflow platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+
+authors = [
+    { name = "Mohammed Maaz" }
+]
+
+dependencies = [
+    "httpx>=0.27.0,<1.0.0"
+]
+
+keywords = [
+    "vangrex",
+    "ai",
+    "workflow",
+    "automation",
+    "agents"
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0,<9.0",
+    "pytest-asyncio>=0.23,<2.0",
+    "respx>=0.21,<1.0",
+    "ruff>=0.6,<1.0",
+]
+
+
+[project.urls]
+Homepage = "https://vangrex.com"
+Repository = "https://github.com/Maaz2623/vangrex-v4"
+
+
+[tool.hatch.build.targets.wheel]
+packages = ["vangrex"]
+
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

vangrex-0.1.0/tests/test_async.py

@@ -0,0 +1,66 @@
+import httpx
+import pytest
+import respx
+
+from vangrex import AsyncVangrex
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_run_workflow():
+    respx.post(
+        "https://api.vangrex.com/api/v1/workflows/workflow-123/executions"
+    ).mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "executionId": "execution-123",
+                "status": "pending",
+            },
+        )
+    )
+
+    client = AsyncVangrex(api_key="vx_test")
+
+    result = await client.workflows.run(
+        "workflow-123",
+        {"message": "hello"},
+    )
+
+    assert result.execution_id == "execution-123"
+    assert result.status == "pending"
+
+    await client.close()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_get_execution():
+    respx.get(
+        "https://api.vangrex.com/api/v1/executions/execution-123"
+    ).mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "id": "execution-123",
+                "workflowId": "workflow-123",
+                "status": "success",
+                "input": {},
+                "output": {"result": "done"},
+                "error": None,
+                "startedAt": None,
+                "completedAt": None,
+                "createdAt": "2026-09-11T10:00:00Z",
+            },
+        )
+    )
+
+    client = AsyncVangrex(api_key="vx_test")
+
+    execution = await client.executions.get("execution-123")
+
+    assert execution.id == "execution-123"
+    assert execution.status == "success"
+    assert execution.output == {"result": "done"}
+
+    await client.close()

vangrex-0.1.0/tests/test_errors.py

@@ -0,0 +1,37 @@
+import httpx
+import pytest
+import respx
+
+from vangrex import Vangrex, VangrexError
+
+
+@respx.mock
+def test_api_error():
+    respx.get(
+        "https://api.vangrex.com/api/v1/executions/bad-execution"
+    ).mock(
+        return_value=httpx.Response(
+            404,
+            json={
+                "error": "Execution not found",
+            },
+        )
+    )
+
+    client = Vangrex(api_key="vx_test")
+
+    with pytest.raises(VangrexError) as exc_info:
+        client.executions.get("bad-execution")
+
+    error = exc_info.value
+
+    assert error.status == 404
+    assert error.message == "Execution not found"
+    assert error.body == {"error": "Execution not found"}
+
+    client.close()
+
+
+def test_empty_api_key():
+    with pytest.raises(ValueError):
+        Vangrex(api_key="")

vangrex-0.1.0/tests/test_executions.py

@@ -0,0 +1,73 @@
+import httpx
+import respx
+
+from vangrex import Vangrex
+
+
+@respx.mock
+def test_get_execution():
+    respx.get(
+        "https://api.vangrex.com/api/v1/executions/execution-123"
+    ).mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "id": "execution-123",
+                "workflowId": "workflow-123",
+                "status": "success",
+                "input": {"message": "hello"},
+                "output": {"result": "world"},
+                "error": None,
+                "startedAt": "2026-09-11T10:00:00Z",
+                "completedAt": "2026-09-11T10:00:03Z",
+                "createdAt": "2026-09-11T10:00:00Z",
+            },
+        )
+    )
+
+    client = Vangrex(api_key="vx_test")
+
+    execution = client.executions.get("execution-123")
+
+    assert execution.id == "execution-123"
+    assert execution.workflow_id == "workflow-123"
+    assert execution.status == "success"
+    assert execution.output == {"result": "world"}
+
+    client.close()
+
+
+@respx.mock
+def test_execution_events():
+    respx.get(
+        "https://api.vangrex.com/api/v1/executions/execution-123/events"
+    ).mock(
+        return_value=httpx.Response(
+            200,
+            headers={"Content-Type": "text/event-stream"},
+            content=(
+                b'data: {"id":"event-1","executionId":"execution-123",'
+                b'"workflowId":"workflow-123","type":"execution.started",'
+                b'"timestamp":"2026-09-11T10:00:00Z","data":{}}\n\n'
+                b'data: {"id":"event-2","executionId":"execution-123",'
+                b'"workflowId":"workflow-123","type":"node.completed",'
+                b'"timestamp":"2026-09-11T10:00:01Z",'
+                b'"data":{"nodeId":"node-1","status":"success",'
+                b'"output":{"value":42}}}\n\n'
+            ),
+        )
+    )
+
+    client = Vangrex(api_key="vx_test")
+
+    events = list(client.executions.events("execution-123"))
+
+    assert len(events) == 2
+
+    assert events[0].type == "execution.started"
+
+    assert events[1].type == "node.completed"
+    assert events[1].data.node_id == "node-1"
+    assert events[1].data.output == {"value": 42}
+
+    client.close()

vangrex-0.1.0/tests/test_workflows.py

@@ -0,0 +1,47 @@
+import httpx
+import respx
+
+from vangrex import Vangrex
+
+
+@respx.mock
+def test_run_workflow():
+    route = respx.post(
+        "https://api.vangrex.com/api/v1/workflows/workflow-123/executions"
+    ).mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "executionId": "execution-123",
+                "status": "pending",
+            },
+        )
+    )
+
+    client = Vangrex(api_key="vx_test")
+
+    result = client.workflows.run(
+        "workflow-123",
+        {"message": "hello"},
+    )
+
+    assert result.execution_id == "execution-123"
+    assert result.status == "pending"
+
+    assert route.called
+    assert route.calls[0].request.headers["Authorization"] == "Bearer vx_test"
+
+    client.close()
+
+
+def test_invalid_workflow_id():
+    client = Vangrex(api_key="vx_test")
+
+    try:
+        client.workflows.run("")
+    except ValueError as exc:
+        assert str(exc) == "workflow_id must be a non-empty string"
+    else:
+        raise AssertionError("Expected ValueError")
+
+    client.close()

vangrex-0.1.0/vangrex/__init__.py

@@ -0,0 +1,105 @@
+from .client import (
+    AsyncVangrexClient,
+    VangrexClient,
+)
+from .errors import VangrexError
+from .executions import (
+    AsyncExecutionsResource,
+    ExecutionsResource,
+)
+from .types import (
+    Execution,
+    ExecutionEvent,
+    ExecutionEventData,
+    ExecutionEventType,
+    ExecutionStatus,
+    RunWorkflowResponse,
+)
+from .workflows import (
+    AsyncWorkflowsResource,
+    WorkflowsResource,
+)
+
+
+class Vangrex:
+    """
+    Official Vangrex Python SDK.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.vangrex.com",
+        timeout: float = 30.0,
+    ) -> None:
+        self._client = VangrexClient(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+
+        self.workflows = WorkflowsResource(self._client)
+        self.executions = ExecutionsResource(self._client)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "Vangrex":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncVangrex:
+    """
+    Asynchronous Vangrex Python SDK.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.vangrex.com",
+        timeout: float = 30.0,
+    ) -> None:
+        self._client = AsyncVangrexClient(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+
+        self.workflows = AsyncWorkflowsResource(self._client)
+        self.executions = AsyncExecutionsResource(self._client)
+
+    async def close(self) -> None:
+        await self._client.close()
+
+    async def __aenter__(self) -> "AsyncVangrex":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+
+__all__ = [
+    "Vangrex",
+    "AsyncVangrex",
+    "VangrexClient",
+    "AsyncVangrexClient",
+    "VangrexError",
+    "WorkflowsResource",
+    "AsyncWorkflowsResource",
+    "ExecutionsResource",
+    "AsyncExecutionsResource",
+    "RunWorkflowResponse",
+    "Execution",
+    "ExecutionEvent",
+    "ExecutionEventData",
+    "ExecutionEventType",
+    "ExecutionStatus",
+]
+
+
+VERSION = "0.1.0"

vangrex-0.1.0/vangrex/client.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+from typing import Any, TypeVar
+
+import httpx
+
+from .errors import VangrexError
+
+T = TypeVar("T")
+
+
+DEFAULT_BASE_URL = "https://api.vangrex.com"
+
+
+class VangrexClient:
+    """
+    Low-level synchronous HTTP client for the Vangrex API.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise ValueError("api_key must be a non-empty string")
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        response = self._http.request(
+            method,
+            path,
+            json=json,
+            headers=headers,
+        )
+
+        return self._handle_response(response)
+
+    def get(
+        self,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        return self.request("GET", path, headers=headers)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        return self.request("POST", path, json=json, headers=headers)
+
+    def stream(
+        self,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+    ) -> Iterator[str]:
+        stream_headers = {
+            "Accept": "text/event-stream",
+            **(headers or {}),
+        }
+
+        with self._http.stream(
+            "GET",
+            path,
+            headers=stream_headers,
+        ) as response:
+            self._raise_for_status(response)
+
+            yield from response.iter_lines()
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        if response.is_success:
+            return
+
+        body: Any = None
+
+        try:
+            body = response.json()
+        except ValueError:
+            body = response.text
+
+        message = (
+            body.get("error")
+            if isinstance(body, dict) and isinstance(body.get("error"), str)
+            else f"Request failed with status {response.status_code}"
+        )
+
+        raise VangrexError(
+            message,
+            status=response.status_code,
+            body=body,
+        )
+
+    @classmethod
+    def _handle_response(cls, response: httpx.Response) -> Any:
+        cls._raise_for_status(response)
+
+        if not response.content:
+            return None
+
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise VangrexError(
+                "Vangrex API returned an invalid JSON response",
+                status=response.status_code,
+                body=response.text,
+            ) from exc
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> VangrexClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncVangrexClient:
+    """
+    Low-level asynchronous HTTP client for the Vangrex API.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise ValueError("api_key must be a non-empty string")
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+        self._http = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        response = await self._http.request(
+            method,
+            path,
+            json=json,
+            headers=headers,
+        )
+
+        return await self._handle_response(response)
+
+    async def get(
+        self,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        return await self.request("GET", path, headers=headers)
+
+    async def post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        return await self.request("POST", path, json=json, headers=headers)
+
+    async def stream(
+        self,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+    ) -> AsyncIterator[str]:
+        stream_headers = {
+            "Accept": "text/event-stream",
+            **(headers or {}),
+        }
+
+        async with self._http.stream(
+            "GET",
+            path,
+            headers=stream_headers,
+        ) as response:
+            self._raise_for_status(response)
+
+            async for line in response.aiter_lines():
+                yield line
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        if response.is_success:
+            return
+
+        body: Any = None
+
+        try:
+            body = response.json()
+        except ValueError:
+            body = response.text
+
+        message = (
+            body.get("error")
+            if isinstance(body, dict) and isinstance(body.get("error"), str)
+            else f"Request failed with status {response.status_code}"
+        )
+
+        raise VangrexError(
+            message,
+            status=response.status_code,
+            body=body,
+        )
+
+    @classmethod
+    async def _handle_response(cls, response: httpx.Response) -> Any:
+        cls._raise_for_status(response)
+
+        if not response.content:
+            return None
+
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise VangrexError(
+                "Vangrex API returned an invalid JSON response",
+                status=response.status_code,
+                body=response.text,
+            ) from exc
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncVangrexClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

vangrex-0.1.0/vangrex/errors.py

@@ -0,0 +1,26 @@
+from typing import Any
+
+
+class VangrexError(Exception):
+    """
+    Error raised when a Vangrex API request fails.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+
+        self.message = message
+        self.status = status
+        self.body = body
+
+    def __str__(self) -> str:
+        if self.status is not None:
+            return f"{self.message} (HTTP {self.status})"
+
+        return self.message

vangrex-0.1.0/vangrex/executions.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+from .client import AsyncVangrexClient, VangrexClient
+from .types import Execution, ExecutionEvent, ExecutionEventData
+
+
+class ExecutionsResource:
+    def __init__(self, client: VangrexClient) -> None:
+        self._client = client
+
+    def get(self, execution_id: str) -> Execution:
+        self._validate_execution_id(execution_id)
+
+        response = self._client.get(
+            f"/api/v1/executions/{execution_id}"
+        )
+
+        return self._parse_execution(response)
+
+    def events(self, execution_id: str) -> Iterator[ExecutionEvent]:
+        self._validate_execution_id(execution_id)
+
+        data_lines: list[str] = []
+
+        for line in self._client.stream(
+            f"/api/v1/executions/{execution_id}/events"
+        ):
+            # SSE comments / keep-alives
+            if line.startswith(":"):
+                continue
+
+            if line.startswith("data:"):
+                data_lines.append(line[5:].lstrip())
+                continue
+
+            # An empty line terminates an SSE event.
+            if not line.strip():
+                if data_lines:
+                    event = self._parse_event("\n".join(data_lines))
+
+                    if event is not None:
+                        yield event
+
+                    data_lines.clear()
+
+        # Handle a final event without a trailing blank line.
+        if data_lines:
+            event = self._parse_event("\n".join(data_lines))
+
+            if event is not None:
+                yield event
+
+    @staticmethod
+    def _validate_execution_id(execution_id: str) -> None:
+        if not isinstance(execution_id, str) or not execution_id.strip():
+            raise ValueError("execution_id must be a non-empty string")
+
+    @staticmethod
+    def _parse_execution(data: dict[str, Any]) -> Execution:
+        return Execution(
+            id=data["id"],
+            workflow_id=data["workflowId"],
+            status=data["status"],
+            input=data.get("input"),
+            output=data.get("output"),
+            error=data.get("error"),
+            started_at=data.get("startedAt"),
+            completed_at=data.get("completedAt"),
+            created_at=data["createdAt"],
+        )
+
+    @staticmethod
+    def _parse_event(raw: str) -> ExecutionEvent | None:
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError:
+            # Match the TypeScript SDK behaviour:
+            # malformed events should not break the stream.
+            return None
+
+        event_data = data.get("data") or {}
+
+        return ExecutionEvent(
+            id=data["id"],
+            execution_id=data["executionId"],
+            workflow_id=data["workflowId"],
+            type=data["type"],
+            timestamp=data["timestamp"],
+            data=ExecutionEventData(
+                node_id=event_data.get("nodeId"),
+                status=event_data.get("status"),
+                output=event_data.get("output"),
+                error=event_data.get("error"),
+            ),
+        )
+
+
+class AsyncExecutionsResource:
+    def __init__(self, client: AsyncVangrexClient) -> None:
+        self._client = client
+
+    async def get(self, execution_id: str) -> Execution:
+        self._validate_execution_id(execution_id)
+
+        response = await self._client.get(
+            f"/api/v1/executions/{execution_id}"
+        )
+
+        return ExecutionsResource._parse_execution(response)
+
+    async def events(
+        self,
+        execution_id: str,
+    ) -> AsyncIterator[ExecutionEvent]:
+        self._validate_execution_id(execution_id)
+
+        data_lines: list[str] = []
+
+        async for line in self._client.stream(
+            f"/api/v1/executions/{execution_id}/events"
+        ):
+            if line.startswith(":"):
+                continue
+
+            if line.startswith("data:"):
+                data_lines.append(line[5:].lstrip())
+                continue
+
+            if not line.strip():
+                if data_lines:
+                    event = ExecutionsResource._parse_event(
+                        "\n".join(data_lines)
+                    )
+
+                    if event is not None:
+                        yield event
+
+                    data_lines.clear()
+
+        if data_lines:
+            event = ExecutionsResource._parse_event(
+                "\n".join(data_lines)
+            )
+
+            if event is not None:
+                yield event
+
+    @staticmethod
+    def _validate_execution_id(execution_id: str) -> None:
+        if not isinstance(execution_id, str) or not execution_id.strip():
+            raise ValueError("execution_id must be a non-empty string")

vangrex-0.1.0/vangrex/types.py

@@ -0,0 +1,57 @@
+from dataclasses import dataclass
+from typing import Any, Literal
+
+ExecutionStatus = Literal[
+    "pending",
+    "running",
+    "success",
+    "error",
+    "cancelled",
+]
+
+ExecutionEventType = Literal[
+    "execution.started",
+    "node.started",
+    "node.output",
+    "node.completed",
+    "node.failed",
+    "execution.completed",
+    "execution.failed",
+]
+
+
+@dataclass(frozen=True)
+class RunWorkflowResponse:
+    execution_id: str
+    status: str
+
+
+@dataclass(frozen=True)
+class Execution:
+    id: str
+    workflow_id: str
+    status: ExecutionStatus
+    input: Any
+    output: Any
+    error: Any
+    started_at: str | None
+    completed_at: str | None
+    created_at: str
+
+
+@dataclass(frozen=True)
+class ExecutionEventData:
+    node_id: str | None = None
+    status: str | None = None
+    output: Any = None
+    error: Any = None
+
+
+@dataclass(frozen=True)
+class ExecutionEvent:
+    id: str
+    execution_id: str
+    workflow_id: str
+    type: ExecutionEventType
+    timestamp: str
+    data: ExecutionEventData

vangrex-0.1.0/vangrex/workflows.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .client import AsyncVangrexClient, VangrexClient
+from .types import RunWorkflowResponse
+
+
+class WorkflowsResource:
+    def __init__(self, client: VangrexClient) -> None:
+        self._client = client
+
+    def run(
+        self,
+        workflow_id: str,
+        input: Any = None,
+    ) -> RunWorkflowResponse:
+        self._validate_workflow_id(workflow_id)
+
+        response = self._client.post(
+            f"/api/v1/workflows/{workflow_id}/executions",
+            json={
+                "input": {} if input is None else input,
+            },
+        )
+
+        return RunWorkflowResponse(
+            execution_id=response["executionId"],
+            status=response["status"],
+        )
+
+    @staticmethod
+    def _validate_workflow_id(workflow_id: str) -> None:
+        if not isinstance(workflow_id, str) or not workflow_id.strip():
+            raise ValueError("workflow_id must be a non-empty string")
+
+
+class AsyncWorkflowsResource:
+    def __init__(self, client: AsyncVangrexClient) -> None:
+        self._client = client
+
+    async def run(
+        self,
+        workflow_id: str,
+        input: Any = None,
+    ) -> RunWorkflowResponse:
+        if not isinstance(workflow_id, str) or not workflow_id.strip():
+            raise ValueError("workflow_id must be a non-empty string")
+
+        response = await self._client.post(
+            f"/api/v1/workflows/{workflow_id}/executions",
+            json={
+                "input": {} if input is None else input,
+            },
+        )
+
+        return RunWorkflowResponse(
+            execution_id=response["executionId"],
+            status=response["status"],
+        )