eolaswork 0.1.0__tar.gz

eolaswork-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+dist/
+build/
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/

eolaswork-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: eolaswork
+Version: 0.1.0
+Summary: Official Python SDK for the EolasWork agentic platform
+Project-URL: Homepage, https://eolaswork.com
+Project-URL: Documentation, https://docs.eolaswork.com/sdk/python
+Project-URL: Repository, https://github.com/eolasflow/eolaswork-python
+Author: EolasWork
+License: MIT
+Keywords: agents,ai,automation,eolaswork,llm
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: httpx-sse<1.0,>=0.4
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# eolaswork
+
+Official Python SDK for the [EolasWork](https://eolaswork.com) agentic platform.
+
+## Install
+
+```
+pip install eolaswork
+```
+
+Python 3.11+. Sync + async clients ship together.
+
+## Quickstart
+
+```python
+from eolaswork import Client
+
+client = Client(api_key="nxa_...")        # or set EOLASWORK_API_KEY
+
+# Discover
+me     = client.account.whoami()
+roles  = client.roles.list()
+models = client.models.list()
+
+# Create a task + run an agent
+task = client.tasks.create(title="Q2 board prep")
+client.files.upload(task.id, "./Q2_sales.xlsx")
+
+run = client.runs.create(
+    task_id=task.id,
+    prompt="Build a board-ready summary from the Excel I attached.",
+    role="research-analyst",
+    model="claude-opus-4-7",
+    skills=["xlsx-reader"],
+    webhook_url="https://my-app.example.com/eolaswork/hook",  # optional
+)
+
+# Three ways to wait
+final = client.runs.wait(run.id, timeout=300)           # blocks
+# or:
+for ev in client.runs.stream(run.id):                   # live SSE
+    print(ev.kind, ev.payload)
+# or: don't wait; let the webhook arrive at your endpoint.
+
+print(final.status, final.output)
+```
+
+## Async
+
+```python
+import asyncio
+from eolaswork import AsyncClient
+
+async def main():
+    async with AsyncClient(api_key="nxa_...") as client:
+        task = await client.tasks.create(title="async run")
+        run = await client.runs.create(task_id=task.id, prompt="...")
+        async for ev in client.runs.astream(run.id):
+            print(ev)
+
+asyncio.run(main())
+```
+
+## Webhook receiver
+
+```python
+from eolaswork.webhooks import verify_signature
+
+@app.post("/eolaswork/hook")
+def hook(request):
+    payload = verify_signature(
+        raw_body=request.body,
+        signature_header=request.headers["X-EolasWork-Signature"],
+        secret=os.environ["EOLASWORK_WEBHOOK_SECRET"],
+    )
+    print(payload.run_id, payload.status, payload.output)
+    return "", 204
+```
+
+## Configuration
+
+| Env var | Default | Meaning |
+|---|---|---|
+| `EOLASWORK_API_KEY` | required | Bearer key (create at /settings/api-keys) |
+| `EOLASWORK_BASE_URL` | `https://nexa.aihq.ie` | Backend host (override for self-hosted) |
+
+Explicit constructor args win over env vars:
+
+```python
+client = Client(api_key="...", base_url="https://eolaswork.your-co.com",
+                timeout=120.0, max_retries=5)
+```
+
+## Resource surface
+
+| Resource | What it does |
+|---|---|
+| `client.account` | `whoami`, `instructions`, `preferences`, `artifacts` |
+| `client.api_keys` | list / create / revoke programmatic keys |
+| `client.tasks` | conversations CRUD + `send_message` |
+| `client.runs` | create / retrieve / list / cancel / `wait` / `stream` / approve / deny |
+| `client.files` | upload / list / download / delete / `to_pdf` |
+| `client.roles` | catalogue + file content (read-only) |
+| `client.teams` | catalogue + file content (read-only) |
+| `client.skills` | catalogue + file content (read-only) |
+| `client.models` | LLM model catalogue + providers |
+| `client.followups` | cross-conversation action items |
+| `client.memory` | user-level KV memory |
+
+Async variants share the exact same surface on `AsyncClient` -- every method is awaitable.
+
+## License
+
+MIT.

eolaswork-0.1.0/README.md

@@ -0,0 +1,114 @@
+# eolaswork
+
+Official Python SDK for the [EolasWork](https://eolaswork.com) agentic platform.
+
+## Install
+
+```
+pip install eolaswork
+```
+
+Python 3.11+. Sync + async clients ship together.
+
+## Quickstart
+
+```python
+from eolaswork import Client
+
+client = Client(api_key="nxa_...")        # or set EOLASWORK_API_KEY
+
+# Discover
+me     = client.account.whoami()
+roles  = client.roles.list()
+models = client.models.list()
+
+# Create a task + run an agent
+task = client.tasks.create(title="Q2 board prep")
+client.files.upload(task.id, "./Q2_sales.xlsx")
+
+run = client.runs.create(
+    task_id=task.id,
+    prompt="Build a board-ready summary from the Excel I attached.",
+    role="research-analyst",
+    model="claude-opus-4-7",
+    skills=["xlsx-reader"],
+    webhook_url="https://my-app.example.com/eolaswork/hook",  # optional
+)
+
+# Three ways to wait
+final = client.runs.wait(run.id, timeout=300)           # blocks
+# or:
+for ev in client.runs.stream(run.id):                   # live SSE
+    print(ev.kind, ev.payload)
+# or: don't wait; let the webhook arrive at your endpoint.
+
+print(final.status, final.output)
+```
+
+## Async
+
+```python
+import asyncio
+from eolaswork import AsyncClient
+
+async def main():
+    async with AsyncClient(api_key="nxa_...") as client:
+        task = await client.tasks.create(title="async run")
+        run = await client.runs.create(task_id=task.id, prompt="...")
+        async for ev in client.runs.astream(run.id):
+            print(ev)
+
+asyncio.run(main())
+```
+
+## Webhook receiver
+
+```python
+from eolaswork.webhooks import verify_signature
+
+@app.post("/eolaswork/hook")
+def hook(request):
+    payload = verify_signature(
+        raw_body=request.body,
+        signature_header=request.headers["X-EolasWork-Signature"],
+        secret=os.environ["EOLASWORK_WEBHOOK_SECRET"],
+    )
+    print(payload.run_id, payload.status, payload.output)
+    return "", 204
+```
+
+## Configuration
+
+| Env var | Default | Meaning |
+|---|---|---|
+| `EOLASWORK_API_KEY` | required | Bearer key (create at /settings/api-keys) |
+| `EOLASWORK_BASE_URL` | `https://nexa.aihq.ie` | Backend host (override for self-hosted) |
+
+Explicit constructor args win over env vars:
+
+```python
+client = Client(api_key="...", base_url="https://eolaswork.your-co.com",
+                timeout=120.0, max_retries=5)
+```
+
+## Resource surface
+
+| Resource | What it does |
+|---|---|
+| `client.account` | `whoami`, `instructions`, `preferences`, `artifacts` |
+| `client.api_keys` | list / create / revoke programmatic keys |
+| `client.tasks` | conversations CRUD + `send_message` |
+| `client.runs` | create / retrieve / list / cancel / `wait` / `stream` / approve / deny |
+| `client.files` | upload / list / download / delete / `to_pdf` |
+| `client.roles` | catalogue + file content (read-only) |
+| `client.teams` | catalogue + file content (read-only) |
+| `client.skills` | catalogue + file content (read-only) |
+| `client.models` | LLM model catalogue + providers |
+| `client.followups` | cross-conversation action items |
+| `client.memory` | user-level KV memory |
+
+Async variants share the exact same surface on `AsyncClient` -- every method is awaitable.
+
+## License
+
+MIT.

eolaswork-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "eolaswork"
+version = "0.1.0"
+description = "Official Python SDK for the EolasWork agentic platform"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "EolasWork" }]
+keywords = ["eolaswork", "agents", "ai", "llm", "automation"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  # httpx provides sync+async HTTP under a single client surface; we
+  # need both modes from one library so the SyncTransport and
+  # AsyncTransport share retry/error-mapping logic.
+  "httpx>=0.27,<1.0",
+  # httpx-sse adds connect_sse / aconnect_sse for the run event
+  # stream. Pinning to 0.4+ for the v12+ httpx API compatibility.
+  "httpx-sse>=0.4,<1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "ruff>=0.5",
+]
+
+[project.urls]
+Homepage = "https://eolaswork.com"
+Documentation = "https://docs.eolaswork.com/sdk/python"
+Repository = "https://github.com/eolasflow/eolaswork-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/eolaswork"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.pytest.ini_options]
+# `auto` lets us write async test functions without sprinkling
+# @pytest.mark.asyncio on every one.
+asyncio_mode = "auto"
+testpaths = ["tests"]

eolaswork-0.1.0/release.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Build + publish the eolaswork SDK to PyPI.
+#
+# Requires PYPI_TOKEN in the environment (project-scoped API token from
+# https://pypi.org/manage/account/token/). Run from a clean working
+# tree on the release tag - this script DOES NOT verify branch / tag
+# state for you.
+#
+# Usage:
+#   PYPI_TOKEN=pypi-... bash release.sh
+#
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+if [[ -z "${PYPI_TOKEN:-}" ]]; then
+  echo "ERROR: PYPI_TOKEN env var not set" >&2
+  exit 1
+fi
+
+echo "[release] cleaning dist/"
+rm -rf dist/
+
+echo "[release] building wheel + sdist"
+python -m build
+
+echo "[release] uploading to PyPI"
+python -m twine upload \
+  --username __token__ \
+  --password "$PYPI_TOKEN" \
+  dist/*
+
+echo "[release] uploaded: $(ls dist/)"

eolaswork-0.1.0/src/eolaswork/__init__.py

@@ -0,0 +1,77 @@
+"""EolasWork Python SDK.
+
+Programmatic access to the EolasWork agentic platform: create tasks
+(conversations), launch agentic runs against roles / teams / skills,
+upload + download files, stream events, and receive webhook callbacks
+on terminal-state transitions.
+
+Public surface:
+    Client / AsyncClient                - entry points
+    EolasWorkError + subclasses         - exception hierarchy
+    Account, Task, Run, RunEvent,       - response dataclasses
+    File, Model, Role, Team, Skill,
+    Followup, MemoryEntry, ApiKey
+
+See README.md for usage examples.
+"""
+
+__version__ = "0.1.0"
+
+from .async_client import AsyncClient
+from .client import Client
+from .errors import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    EolasWorkError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .types import (
+    Account,
+    ApiKey,
+    File,
+    Followup,
+    MemoryEntry,
+    Model,
+    Role,
+    Run,
+    RunEvent,
+    Skill,
+    Task,
+    Team,
+)
+
+__all__ = [
+    "__version__",
+    "Client",
+    "AsyncClient",
+    # Errors
+    "EolasWorkError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "APIConnectionError",
+    "APITimeoutError",
+    # Types
+    "Account",
+    "Task",
+    "Run",
+    "RunEvent",
+    "File",
+    "Model",
+    "Role",
+    "Team",
+    "Skill",
+    "Followup",
+    "MemoryEntry",
+    "ApiKey",
+]

eolaswork-0.1.0/src/eolaswork/_atransport.py

@@ -0,0 +1,123 @@
+"""Async mirror of SyncTransport.
+
+Shares the same _handle / status-mapping logic; differs only in
+awaiting httpx.AsyncClient. The two transports import the shared
+constants (RETRY_STATUSES, SAFE_VERBS, _retry_after) from _transport
+so the two stay in lock-step.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+from typing import Any
+
+import httpx
+
+from ._config import ClientConfig
+from ._transport import RETRY_STATUSES, SAFE_VERBS, _retry_after
+from .errors import (
+    APIConnectionError,
+    APITimeoutError,
+    EolasWorkError,
+    error_for_status,
+)
+
+
+class AsyncTransport:
+    def __init__(self, config: ClientConfig):
+        self._config = config
+        self._client = httpx.AsyncClient(
+            base_url=config.base_url,
+            timeout=config.timeout,
+            transport=config.transport,
+            headers={
+                "user-agent": config.user_agent,
+                "authorization": f"Bearer {config.api_key}",
+            },
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        await self.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        files: Any = None,
+        data: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> Any:
+        headers = dict(extra_headers or {})
+        if idempotency_key:
+            headers["idempotency-key"] = idempotency_key
+
+        retry_eligible = method.upper() in SAFE_VERBS or idempotency_key is not None
+        attempts = max(self._config.max_retries + 1, 1) if retry_eligible else 1
+
+        for attempt in range(attempts):
+            try:
+                response = await self._client.request(
+                    method, path, params=params, json=json, files=files,
+                    data=data, headers=headers,
+                )
+            except httpx.TimeoutException as exc:
+                if attempt + 1 < attempts:
+                    await self._sleep(attempt, None)
+                    continue
+                raise APITimeoutError(str(exc)) from exc
+            except httpx.HTTPError as exc:
+                if attempt + 1 < attempts:
+                    await self._sleep(attempt, None)
+                    continue
+                raise APIConnectionError(str(exc)) from exc
+
+            if response.status_code in RETRY_STATUSES and attempt + 1 < attempts:
+                await self._sleep(attempt, _retry_after(response))
+                continue
+
+            return self._handle(response)
+
+        raise EolasWorkError("retry loop exited without response")
+
+    async def stream(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """Open an async streaming response. Caller awaits + closes."""
+        req = self._client.build_request(method, path, **kwargs)
+        return await self._client.send(req, stream=True)
+
+    def _handle(self, response: httpx.Response) -> Any:
+        request_id = response.headers.get("x-request-id")
+        if response.status_code == 204 or not response.content:
+            if 200 <= response.status_code < 300:
+                return None
+            raise error_for_status(response.status_code, request_id=request_id, body=None)
+        try:
+            body = response.json()
+        except Exception:
+            body = response.text
+        if 200 <= response.status_code < 300:
+            return body
+        raise error_for_status(
+            response.status_code,
+            request_id=request_id,
+            body=body,
+            retry_after=_retry_after(response),
+        )
+
+    @staticmethod
+    async def _sleep(attempt: int, retry_after_sec: float | None) -> None:
+        if retry_after_sec is not None:
+            await asyncio.sleep(retry_after_sec)
+            return
+        base = min(0.5 * (2 ** attempt), 8.0)
+        await asyncio.sleep(base + random.uniform(0, base / 2))

eolaswork-0.1.0/src/eolaswork/_config.py

@@ -0,0 +1,74 @@
+"""Client-wide configuration: API key, base URL, timeouts, retries.
+
+Resolution order for every field:
+  1. Explicit constructor argument (wins)
+  2. Corresponding environment variable
+  3. Built-in default
+
+Centralized here so both Client and AsyncClient share one canonical
+factory and any future config key only needs to be added in one place.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import EolasWorkError
+
+# Default base URL points at the production EolasWork host. Self-hosted
+# / on-prem (e.g. HCL) deployments override via EOLASWORK_BASE_URL or
+# the explicit `base_url=` arg.
+DEFAULT_BASE_URL = "https://nexa.aihq.ie"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 3
+
+
+@dataclass
+class ClientConfig:
+    """Resolved config for one Client / AsyncClient instance.
+
+    Constructed eagerly so a missing API key fails fast at construction
+    time, not on the first network call. The dataclass field defaults
+    are placeholders; the __init__ override below performs real
+    env-var resolution.
+    """
+
+    api_key: str = field(default="")
+    base_url: str = field(default="")
+    timeout: float = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+    # httpx.BaseTransport for tests. Untyped on purpose so we don't pull
+    # httpx into this module's import surface; transport modules import
+    # it themselves where needed.
+    transport: Any = None
+    user_agent: str = field(default="")
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        transport: Any = None,
+        user_agent: str | None = None,
+    ):
+        self.api_key = api_key or os.environ.get("EOLASWORK_API_KEY", "")
+        if not self.api_key:
+            raise EolasWorkError(
+                "api_key required - pass api_key= or set EOLASWORK_API_KEY"
+            )
+        # Strip any trailing slash so resource modules can confidently
+        # concatenate paths starting with `/api/...`.
+        self.base_url = (
+            base_url or os.environ.get("EOLASWORK_BASE_URL", DEFAULT_BASE_URL)
+        ).rstrip("/")
+        self.timeout = timeout if timeout is not None else DEFAULT_TIMEOUT
+        self.max_retries = max_retries if max_retries is not None else DEFAULT_MAX_RETRIES
+        self.transport = transport
+        # Defer the __version__ import to construction time so a circular
+        # import (eolaswork.__init__ -> ClientConfig -> __version__)
+        # can't fire at module load.
+        from . import __version__
+        self.user_agent = user_agent or f"eolaswork-python/{__version__}"

eolaswork-0.1.0/src/eolaswork/_streaming.py

@@ -0,0 +1,65 @@
+"""SSE iterators for the EolasWork run event stream.
+
+The backend emits standard text/event-stream lines:
+  event: <kind>
+  data: <json>
+  (blank line)
+  id: <optional event id>
+
+We yield RunEvent dataclasses with `kind` (the event name), `action_id`
+extracted from the JSON payload when present, and `payload` carrying
+the parsed JSON body of the event.
+
+httpx-sse provides the connect_sse / aconnect_sse context managers
+that wrap an httpx Client + request + EventSource setup; we wire
+those to our transports' underlying clients.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import AsyncIterator, Iterator
+
+from httpx_sse import aconnect_sse, connect_sse
+
+from ._atransport import AsyncTransport
+from ._transport import SyncTransport
+from .types import RunEvent
+
+
+def iter_run_events(transport: SyncTransport, run_id: str) -> Iterator[RunEvent]:
+    # connect_sse owns the underlying httpx.Client streaming response;
+    # using it as a context manager guarantees the socket is closed
+    # when the caller stops iterating (or an exception fires).
+    with connect_sse(
+        transport._client, "GET", f"/api/runs/{run_id}/stream"
+    ) as event_source:
+        for sse in event_source.iter_sse():
+            yield _to_event(sse.event, sse.data)
+
+
+async def aiter_run_events(
+    transport: AsyncTransport, run_id: str
+) -> AsyncIterator[RunEvent]:
+    async with aconnect_sse(
+        transport._client, "GET", f"/api/runs/{run_id}/stream"
+    ) as event_source:
+        async for sse in event_source.aiter_sse():
+            yield _to_event(sse.event, sse.data)
+
+
+def _to_event(event_name: str | None, raw_data: str) -> RunEvent:
+    try:
+        payload = json.loads(raw_data) if raw_data else {}
+    except json.JSONDecodeError:
+        # Non-JSON data event - rare, surface verbatim under `raw` so
+        # nothing is silently dropped.
+        payload = {"raw": raw_data}
+    return RunEvent(
+        kind=event_name or "message",
+        # SSE events frequently carry the relevant action id in
+        # payload.actionId; lift it onto the dataclass as a first-class
+        # field so consumers don't have to keep digging into payload.
+        action_id=payload.get("actionId") if isinstance(payload, dict) else None,
+        payload=payload if isinstance(payload, dict) else {"raw": payload},
+    )