eolaswork 0.1.0__py3-none-any.whl

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/_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/_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/_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},
+    )

eolaswork/_transport.py

@@ -0,0 +1,175 @@
+"""Synchronous HTTP transport for the eolaswork SDK.
+
+Wraps httpx.Client to apply auth, JSON encoding, error mapping, and
+retries. Resources never see httpx.Response directly - they call
+`transport.request()` and get either parsed JSON or None (for 204s)
+back, with exceptions raised for any non-2xx status.
+
+Streaming: `transport.stream()` returns a raw httpx.Response with
+`stream=True` for SSE/binary use. The streaming module + files
+resource own it from there.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import Any
+
+import httpx
+
+from ._config import ClientConfig
+from .errors import (
+    APIConnectionError,
+    APITimeoutError,
+    EolasWorkError,
+    error_for_status,
+)
+
+# Status codes worth retrying when the request is safe to repeat. 429
+# and the transient 5xx classes only. Connection errors are retried
+# unconditionally (when retry-eligible).
+RETRY_STATUSES = {429, 502, 503, 504}
+
+# HTTP verbs we treat as retry-safe by default. POST is included ONLY
+# when the caller passed an Idempotency-Key (resources do this for
+# runs.create so a network blip doesn't spawn a duplicate run).
+SAFE_VERBS = {"GET", "DELETE", "PUT", "HEAD"}
+
+
+class SyncTransport:
+    """Thin sync wrapper around httpx.Client.
+
+    Designed to be one-per-Client so the auth header and base URL are
+    bound once on construction. Close via .close() or use as a context
+    manager.
+    """
+
+    def __init__(self, config: ClientConfig):
+        self._config = config
+        self._client = httpx.Client(
+            base_url=config.base_url,
+            timeout=config.timeout,
+            transport=config.transport,
+            headers={
+                "user-agent": config.user_agent,
+                "authorization": f"Bearer {config.api_key}",
+            },
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+    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:
+        """Make a request and return parsed JSON / None / raise on error."""
+        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 = self._client.request(
+                    method, path, params=params, json=json, files=files,
+                    data=data, headers=headers,
+                )
+            except httpx.TimeoutException as exc:
+                if attempt + 1 < attempts:
+                    self._sleep_backoff(attempt, None)
+                    continue
+                raise APITimeoutError(str(exc)) from exc
+            except httpx.HTTPError as exc:
+                if attempt + 1 < attempts:
+                    self._sleep_backoff(attempt, None)
+                    continue
+                raise APIConnectionError(str(exc)) from exc
+
+            if response.status_code in RETRY_STATUSES and attempt + 1 < attempts:
+                self._sleep_backoff(attempt, _retry_after(response))
+                continue
+
+            return self._handle(response)
+
+        # Unreachable - the loop returns or raises every iteration. The
+        # raise here exists for type-checker satisfaction.
+        raise EolasWorkError("retry loop exited without response")
+
+    def stream(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """Open a streaming response without consuming the body.
+
+        Caller is responsible for closing it (or using a context manager).
+        Used by the SSE iterator and the files resource's download path.
+        Streaming is single-shot (no retry) - SSE has its own reconnect
+        logic in _streaming.py.
+        """
+        req = self._client.build_request(method, path, **kwargs)
+        return 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:
+            # Non-JSON body (e.g. binary download accidentally routed
+            # through .request()) - hand back the text so error_for_status
+            # at least has something.
+            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
+    def _sleep_backoff(attempt: int, retry_after_sec: float | None) -> None:
+        if retry_after_sec is not None:
+            time.sleep(retry_after_sec)
+            return
+        # Exponential with jitter: 0.5s, 1s, 2s, ... capped at 8s.
+        # Jitter avoids thundering-herd on coordinated retry from many
+        # clients after a service blip.
+        base = min(0.5 * (2 ** attempt), 8.0)
+        time.sleep(base + random.uniform(0, base / 2))
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    """Parse the Retry-After header value as seconds.
+
+    Accepts the integer-seconds form only; HTTP-date is rare in
+    practice and supporting it just adds parsing surface area.
+    """
+    raw = response.headers.get("retry-after")
+    if not raw:
+        return None
+    try:
+        return float(raw)
+    except ValueError:
+        return None

eolaswork/async_client.py

@@ -0,0 +1,75 @@
+"""Async mirror of Client.
+
+Same surface as the sync Client but every method is awaitable. Use
+inside FastAPI / aiohttp / any asyncio agent framework.
+
+Example:
+    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="hi")
+            async for event in client.runs.astream(run.id):
+                print(event)
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._atransport import AsyncTransport
+from ._config import ClientConfig
+from .resources.account import AsyncAccount
+from .resources.api_keys import AsyncApiKeys
+from .resources.files import AsyncFiles
+from .resources.followups import AsyncFollowups
+from .resources.memory import AsyncMemory
+from .resources.models import AsyncModels
+from .resources.roles import AsyncRoles
+from .resources.runs import AsyncRuns
+from .resources.skills import AsyncSkills
+from .resources.tasks import AsyncTasks
+from .resources.teams import AsyncTeams
+
+
+class AsyncClient:
+    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,
+    ):
+        self._config = ClientConfig(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            transport=transport,
+        )
+        self._transport = AsyncTransport(self._config)
+        self.account = AsyncAccount(self._transport)
+        self.api_keys = AsyncApiKeys(self._transport)
+        self.tasks = AsyncTasks(self._transport)
+        self.runs = AsyncRuns(self._transport)
+        self.files = AsyncFiles(self._transport)
+        self.roles = AsyncRoles(self._transport)
+        self.teams = AsyncTeams(self._transport)
+        self.skills = AsyncSkills(self._transport)
+        self.models = AsyncModels(self._transport)
+        self.followups = AsyncFollowups(self._transport)
+        self.memory = AsyncMemory(self._transport)
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        await self.aclose()

eolaswork/client.py

@@ -0,0 +1,77 @@
+"""Synchronous Client facade.
+
+Constructed once per process / call site. Holds the resolved
+ClientConfig, the SyncTransport, and one resource instance per
+top-level API path family. Close via .close() or use as a context
+manager.
+
+Example:
+    from eolaswork import Client
+
+    client = Client(api_key="nxa_...")
+    me = client.account.whoami()
+    task = client.tasks.create(title="Q2 board prep")
+    run = client.runs.create(task_id=task.id, prompt="...", role="analyst")
+    final = client.runs.wait(run.id)
+    print(final.status, final.output)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._config import ClientConfig
+from ._transport import SyncTransport
+from .resources.account import Account
+from .resources.api_keys import ApiKeys
+from .resources.files import Files
+from .resources.followups import Followups
+from .resources.memory import Memory
+from .resources.models import Models
+from .resources.roles import Roles
+from .resources.runs import Runs
+from .resources.skills import Skills
+from .resources.tasks import Tasks
+from .resources.teams import Teams
+
+
+class Client:
+    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,
+    ):
+        self._config = ClientConfig(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            transport=transport,
+        )
+        self._transport = SyncTransport(self._config)
+        # All 11 resources hang off the client. Constructing them is
+        # cheap (one assignment); doing so up front means the dot-path
+        # surface is fully discoverable in any IDE / REPL.
+        self.account = Account(self._transport)
+        self.api_keys = ApiKeys(self._transport)
+        self.tasks = Tasks(self._transport)
+        self.runs = Runs(self._transport)
+        self.files = Files(self._transport)
+        self.roles = Roles(self._transport)
+        self.teams = Teams(self._transport)
+        self.skills = Skills(self._transport)
+        self.models = Models(self._transport)
+        self.followups = Followups(self._transport)
+        self.memory = Memory(self._transport)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()