eolaswork 0.1.0__py3-none-any.whl

eolaswork/errors.py

@@ -0,0 +1,126 @@
+"""Exception hierarchy for the eolaswork SDK.
+
+Every error raised from Client/AsyncClient is a subclass of EolasWorkError
+so callers can `except EolasWorkError` to catch every SDK-originated
+failure. Each leaf class corresponds to a single HTTP failure mode or
+client-side problem (timeout, connection, signature mismatch).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class EolasWorkError(Exception):
+    """Base class for all SDK errors.
+
+    Carries the original HTTP status, server-issued request_id (for
+    support correspondence), and the parsed response body so callers
+    can drill in past the human-readable message when needed.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        body: Any = None,
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.request_id = request_id
+        self.body = body
+
+
+class AuthenticationError(EolasWorkError):
+    """401 - missing, invalid, or revoked credentials."""
+
+
+class PermissionDeniedError(EolasWorkError):
+    """403 - caller is authenticated but not authorized for the action."""
+
+
+class NotFoundError(EolasWorkError):
+    """404 - the resource does not exist."""
+
+
+class ConflictError(EolasWorkError):
+    """409 - the requested state conflicts with the current state."""
+
+
+class ValidationError(EolasWorkError):
+    """400 / 422 - the request body or query params were rejected.
+
+    `.field_errors` exposes any per-field detail the server returned in
+    the body's `field_errors` key, so callers can build form-style UX
+    without re-parsing the response body themselves.
+    """
+
+    def __init__(self, message: str, **kwargs: Any):
+        super().__init__(message, **kwargs)
+        body = kwargs.get("body") or {}
+        self.field_errors: dict[str, Any] = (
+            body.get("field_errors", {}) if isinstance(body, dict) else {}
+        )
+
+
+class RateLimitError(EolasWorkError):
+    """429 - server is throttling the caller.
+
+    `.retry_after` (seconds, float) is populated from the Retry-After
+    header when present so callers can build a polite backoff loop.
+    """
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kwargs: Any):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(EolasWorkError):
+    """5xx - server failure. Usually retryable, often transient."""
+
+
+class APIConnectionError(EolasWorkError):
+    """Network / DNS / TLS failure - the request never reached the server."""
+
+
+class APITimeoutError(EolasWorkError):
+    """Client-side timeout - the server didn't respond within `timeout=`."""
+
+
+def error_for_status(
+    status: int,
+    *,
+    request_id: str | None,
+    body: Any,
+    retry_after: float | None = None,
+) -> EolasWorkError:
+    """Map an HTTP status code to the matching SDK exception type.
+
+    The transport calls this on every non-2xx response. Unknown 4xx
+    codes fall through to the generic EolasWorkError so the caller
+    still gets a useful exception with status + body attached rather
+    than an opaque HTTPError from httpx.
+    """
+    message = (
+        body.get("message")
+        if isinstance(body, dict) and isinstance(body.get("message"), str)
+        else f"HTTP {status}"
+    )
+    common = {"status_code": status, "request_id": request_id, "body": body}
+    if status == 401:
+        return AuthenticationError(message, **common)
+    if status == 403:
+        return PermissionDeniedError(message, **common)
+    if status == 404:
+        return NotFoundError(message, **common)
+    if status == 409:
+        return ConflictError(message, **common)
+    if status in (400, 422):
+        return ValidationError(message, **common)
+    if status == 429:
+        return RateLimitError(message, retry_after=retry_after, **common)
+    if 500 <= status < 600:
+        return ServerError(message, **common)
+    return EolasWorkError(message, **common)

eolaswork/resources/__init__.py

@@ -0,0 +1 @@
+"""Resource modules, one per top-level API path family."""

eolaswork/resources/_base.py

@@ -0,0 +1,28 @@
+"""Resource base mixins.
+
+Each resource holds one typed reference to a transport. The mixin
+exists so the resource classes don't reimplement the constructor 11
+times - and so a future cross-cutting concern (resource-level metrics,
+logging, etc.) has one place to land.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .._atransport import AsyncTransport
+    from .._transport import SyncTransport
+
+
+class BaseResource:
+    def __init__(self, transport: "SyncTransport"):
+        # Single-letter alias because resource methods reference it on
+        # every line; the shorter name keeps each method body
+        # comfortably under a single visual span.
+        self._t = transport
+
+
+class BaseAsyncResource:
+    def __init__(self, transport: "AsyncTransport"):
+        self._t = transport

eolaswork/resources/account.py

@@ -0,0 +1,63 @@
+"""Account resource - whoami, system instructions, preferences, artifacts."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from ..types import Account as AccountType
+from ._base import BaseAsyncResource, BaseResource
+
+
+class Account(BaseResource):
+    def whoami(self) -> AccountType:
+        body = self._t.request("GET", "/api/auth/me")
+        return AccountType.from_raw(body)
+
+    def get_instructions(self) -> str:
+        body = self._t.request("GET", "/api/me/instructions")
+        if isinstance(body, dict):
+            return body.get("text", "")
+        return str(body or "")
+
+    def set_instructions(self, text: str) -> None:
+        self._t.request("PUT", "/api/me/instructions", json={"text": text})
+
+    def get_preference(self, key: str) -> Any:
+        return self._t.request("GET", f"/api/me/preferences/{quote(key, safe='')}")
+
+    def set_preference(self, key: str, value: Any) -> None:
+        self._t.request(
+            "PUT", f"/api/me/preferences/{quote(key, safe='')}", json={"value": value}
+        )
+
+    def artifacts(self) -> list[dict[str, Any]]:
+        body = self._t.request("GET", "/api/me/artifacts")
+        return list(body) if isinstance(body, list) else body.get("items", [])
+
+
+class AsyncAccount(BaseAsyncResource):
+    async def whoami(self) -> AccountType:
+        body = await self._t.request("GET", "/api/auth/me")
+        return AccountType.from_raw(body)
+
+    async def get_instructions(self) -> str:
+        body = await self._t.request("GET", "/api/me/instructions")
+        if isinstance(body, dict):
+            return body.get("text", "")
+        return str(body or "")
+
+    async def set_instructions(self, text: str) -> None:
+        await self._t.request("PUT", "/api/me/instructions", json={"text": text})
+
+    async def get_preference(self, key: str) -> Any:
+        return await self._t.request("GET", f"/api/me/preferences/{quote(key, safe='')}")
+
+    async def set_preference(self, key: str, value: Any) -> None:
+        await self._t.request(
+            "PUT", f"/api/me/preferences/{quote(key, safe='')}", json={"value": value}
+        )
+
+    async def artifacts(self) -> list[dict[str, Any]]:
+        body = await self._t.request("GET", "/api/me/artifacts")
+        return list(body) if isinstance(body, list) else body.get("items", [])

eolaswork/resources/api_keys.py

@@ -0,0 +1,45 @@
+"""Programmatic API key management - list, create, revoke.
+
+Mirrors POST/GET/DELETE on /api/me/api-keys. The plaintext key is
+returned on create() ONLY; users must persist it immediately because
+the server stores only the argon2 hash + 8-char public prefix.
+"""
+
+from __future__ import annotations
+
+from ..types import ApiKey
+from ._base import BaseAsyncResource, BaseResource
+
+
+class ApiKeys(BaseResource):
+    def list(self) -> list[ApiKey]:
+        rows = self._t.request("GET", "/api/me/api-keys") or []
+        return [ApiKey.from_raw(r) for r in rows]
+
+    def create(self, name: str, scopes: list[str] | None = None) -> ApiKey:
+        body = self._t.request(
+            "POST",
+            "/api/me/api-keys",
+            json={"name": name, "scopes": scopes or []},
+        )
+        return ApiKey.from_raw(body)
+
+    def revoke(self, key_id: str) -> None:
+        self._t.request("DELETE", f"/api/me/api-keys/{key_id}")
+
+
+class AsyncApiKeys(BaseAsyncResource):
+    async def list(self) -> list[ApiKey]:
+        rows = await self._t.request("GET", "/api/me/api-keys") or []
+        return [ApiKey.from_raw(r) for r in rows]
+
+    async def create(self, name: str, scopes: list[str] | None = None) -> ApiKey:
+        body = await self._t.request(
+            "POST",
+            "/api/me/api-keys",
+            json={"name": name, "scopes": scopes or []},
+        )
+        return ApiKey.from_raw(body)
+
+    async def revoke(self, key_id: str) -> None:
+        await self._t.request("DELETE", f"/api/me/api-keys/{key_id}")

eolaswork/resources/files.py

@@ -0,0 +1,180 @@
+"""Conversation/task file storage - upload, list, download, delete, to_pdf.
+
+200 MB / file cap matches the multer config in
+api/server/routes/conversations.js (search for `fileSize`). 25 files
+per request is the server's max too. We validate caller-side so we
+fail fast before sending the multipart body up the wire.
+"""
+
+from __future__ import annotations
+
+import io
+from pathlib import Path
+from typing import BinaryIO
+
+from ..errors import ValidationError
+from ..types import File
+from ._base import BaseAsyncResource, BaseResource
+
+MAX_FILE_BYTES = 200 * 1024 * 1024
+MAX_FILES_PER_REQUEST = 25
+
+
+def _coerce_to_file(
+    source: str | Path | bytes | BinaryIO,
+    filename: str | None,
+    content_type: str | None,
+) -> tuple[str, BinaryIO, str | None]:
+    """Coerce one of several source shapes into the (name, file-like, ct)
+    triple httpx expects for a multipart part.
+
+    Validates the byte-count for bytes/Path sources. BinaryIO sources
+    are not pre-checked (length unknown without seek+tell which would
+    consume the stream) - the server caps at MAX_FILE_BYTES regardless.
+    """
+    ct = content_type
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        size = path.stat().st_size
+        if size > MAX_FILE_BYTES:
+            raise ValidationError(
+                f"file {path.name} ({size} bytes) exceeds {MAX_FILE_BYTES}-byte limit"
+            )
+        name = filename or path.name
+        return (name, path.open("rb"), ct)
+    if isinstance(source, bytes):
+        if len(source) > MAX_FILE_BYTES:
+            raise ValidationError(
+                f"bytes payload ({len(source)} bytes) exceeds {MAX_FILE_BYTES}-byte limit"
+            )
+        if not filename:
+            raise ValidationError("filename= required when source is bytes")
+        return (filename, io.BytesIO(source), ct)
+    # Assume BinaryIO-like - any file-like object opened in binary mode.
+    if not filename:
+        raise ValidationError("filename= required when source is a file-like object")
+    return (filename, source, ct)
+
+
+def _httpx_files_arg(
+    items: list[tuple[str, BinaryIO, str | None]],
+) -> list[tuple[str, tuple[str, BinaryIO, str]]]:
+    """Build the list-of-tuples form httpx accepts for repeated multipart
+    fields. The backend's multer config is `upload.array('files', 25)`
+    so every part uses the field name 'files'."""
+    if len(items) > MAX_FILES_PER_REQUEST:
+        raise ValidationError(
+            f"too many files: {len(items)} > {MAX_FILES_PER_REQUEST} limit per request"
+        )
+    return [
+        ("files", (name, fobj, ct or "application/octet-stream"))
+        for (name, fobj, ct) in items
+    ]
+
+
+def _unwrap_files_response(body: object, fallback_name: str) -> File:
+    """Backend may return a single file dict, a list, or {files:[...]}.
+    Normalize all three shapes to the first File."""
+    if isinstance(body, list) and body:
+        return File.from_raw(body[0])
+    if isinstance(body, dict) and "files" in body and body["files"]:
+        return File.from_raw(body["files"][0])
+    if isinstance(body, dict) and body:
+        return File.from_raw(body)
+    return File.from_raw({"name": fallback_name, "size": 0})
+
+
+class Files(BaseResource):
+    def list(self, task_id: str) -> list[File]:
+        rows = self._t.request("GET", f"/api/conversations/{task_id}/files") or []
+        items = rows.get("files") if isinstance(rows, dict) else rows
+        return [File.from_raw(r) for r in items or []]
+
+    def upload(
+        self,
+        task_id: str,
+        source: str | Path | bytes | BinaryIO,
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+    ) -> File:
+        name, fobj, ct = _coerce_to_file(source, filename, content_type)
+        try:
+            files_arg = _httpx_files_arg([(name, fobj, ct)])
+            body = self._t.request(
+                "POST", f"/api/conversations/{task_id}/files", files=files_arg
+            )
+        finally:
+            try:
+                fobj.close()
+            except Exception:
+                pass
+        return _unwrap_files_response(body, name)
+
+    def download(self, task_id: str, name: str) -> bytes:
+        # Bypass JSON parsing via the streaming path so binary bodies
+        # come back as bytes without going through .json().
+        with self._t.stream("GET", f"/api/conversations/{task_id}/files/{name}") as resp:
+            resp.raise_for_status()
+            return resp.read()
+
+    def delete(self, task_id: str, name: str) -> None:
+        self._t.request("DELETE", f"/api/conversations/{task_id}/files/{name}")
+
+    def to_pdf(self, task_id: str, name: str) -> bytes:
+        with self._t.stream(
+            "GET", f"/api/conversations/{task_id}/files/{name}/pdf"
+        ) as resp:
+            resp.raise_for_status()
+            return resp.read()
+
+
+class AsyncFiles(BaseAsyncResource):
+    async def list(self, task_id: str) -> list[File]:
+        rows = await self._t.request("GET", f"/api/conversations/{task_id}/files") or []
+        items = rows.get("files") if isinstance(rows, dict) else rows
+        return [File.from_raw(r) for r in items or []]
+
+    async def upload(
+        self,
+        task_id: str,
+        source: str | Path | bytes | BinaryIO,
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+    ) -> File:
+        name, fobj, ct = _coerce_to_file(source, filename, content_type)
+        try:
+            files_arg = _httpx_files_arg([(name, fobj, ct)])
+            body = await self._t.request(
+                "POST", f"/api/conversations/{task_id}/files", files=files_arg
+            )
+        finally:
+            try:
+                fobj.close()
+            except Exception:
+                pass
+        return _unwrap_files_response(body, name)
+
+    async def download(self, task_id: str, name: str) -> bytes:
+        resp = await self._t.stream(
+            "GET", f"/api/conversations/{task_id}/files/{name}"
+        )
+        try:
+            resp.raise_for_status()
+            return await resp.aread()
+        finally:
+            await resp.aclose()
+
+    async def delete(self, task_id: str, name: str) -> None:
+        await self._t.request("DELETE", f"/api/conversations/{task_id}/files/{name}")
+
+    async def to_pdf(self, task_id: str, name: str) -> bytes:
+        resp = await self._t.stream(
+            "GET", f"/api/conversations/{task_id}/files/{name}/pdf"
+        )
+        try:
+            resp.raise_for_status()
+            return await resp.aread()
+        finally:
+            await resp.aclose()

eolaswork/resources/followups.py

@@ -0,0 +1,73 @@
+"""Followups - cross-conversation action items the agent flagged.
+
+Backed by /api/followups; mirrors the SPA's Follow-ups page surface.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..types import Followup
+from ._base import BaseAsyncResource, BaseResource
+
+
+def _items(body: Any) -> list[dict[str, Any]]:
+    if isinstance(body, dict):
+        return list(body.get("items", []))
+    return list(body or [])
+
+
+class Followups(BaseResource):
+    def list(self, projects: bool = False) -> list[Followup]:
+        params = {"projects": "true"} if projects else None
+        return [
+            Followup.from_raw(r)
+            for r in _items(self._t.request("GET", "/api/followups", params=params))
+        ]
+
+    def create(
+        self, *, text: str, due_at: str | None = None, **extra: Any
+    ) -> Followup:
+        body: dict[str, Any] = {"text": text}
+        if due_at:
+            body["dueAt"] = due_at
+        body.update(extra)
+        return Followup.from_raw(self._t.request("POST", "/api/followups", json=body))
+
+    def update(self, followup_id: str, **fields: Any) -> Followup:
+        return Followup.from_raw(
+            self._t.request("PATCH", f"/api/followups/{followup_id}", json=fields)
+        )
+
+    def delete(self, followup_id: str) -> None:
+        self._t.request("DELETE", f"/api/followups/{followup_id}")
+
+
+class AsyncFollowups(BaseAsyncResource):
+    async def list(self, projects: bool = False) -> list[Followup]:
+        params = {"projects": "true"} if projects else None
+        return [
+            Followup.from_raw(r)
+            for r in _items(
+                await self._t.request("GET", "/api/followups", params=params)
+            )
+        ]
+
+    async def create(
+        self, *, text: str, due_at: str | None = None, **extra: Any
+    ) -> Followup:
+        body: dict[str, Any] = {"text": text}
+        if due_at:
+            body["dueAt"] = due_at
+        body.update(extra)
+        return Followup.from_raw(
+            await self._t.request("POST", "/api/followups", json=body)
+        )
+
+    async def update(self, followup_id: str, **fields: Any) -> Followup:
+        return Followup.from_raw(
+            await self._t.request("PATCH", f"/api/followups/{followup_id}", json=fields)
+        )
+
+    async def delete(self, followup_id: str) -> None:
+        await self._t.request("DELETE", f"/api/followups/{followup_id}")

eolaswork/resources/memory.py

@@ -0,0 +1,74 @@
+"""User-level memory key-value store backed by /api/memories.
+
+The backend has no per-key GET endpoint; SDK callers wanting a single
+entry should call .list() and filter (entries are small).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..types import MemoryEntry
+from ._base import BaseAsyncResource, BaseResource
+
+
+def _items(body: Any) -> list[dict[str, Any]]:
+    if isinstance(body, dict):
+        return list(body.get("items", []))
+    return list(body or [])
+
+
+class Memory(BaseResource):
+    def list(self) -> list[MemoryEntry]:
+        return [
+            MemoryEntry.from_raw(r)
+            for r in _items(self._t.request("GET", "/api/memories"))
+        ]
+
+    def put(self, key: str, value: str) -> MemoryEntry:
+        return MemoryEntry.from_raw(
+            self._t.request("POST", "/api/memories", json={"key": key, "value": value})
+        )
+
+    def update(self, key: str, value: str) -> MemoryEntry:
+        return MemoryEntry.from_raw(
+            self._t.request("PATCH", f"/api/memories/{key}", json={"value": value})
+        )
+
+    def delete(self, key: str) -> None:
+        self._t.request("DELETE", f"/api/memories/{key}")
+
+    def set_opt_out(self, enabled: bool) -> None:
+        self._t.request(
+            "PATCH", "/api/memories/preferences", json={"optOut": enabled}
+        )
+
+
+class AsyncMemory(BaseAsyncResource):
+    async def list(self) -> list[MemoryEntry]:
+        return [
+            MemoryEntry.from_raw(r)
+            for r in _items(await self._t.request("GET", "/api/memories"))
+        ]
+
+    async def put(self, key: str, value: str) -> MemoryEntry:
+        return MemoryEntry.from_raw(
+            await self._t.request(
+                "POST", "/api/memories", json={"key": key, "value": value}
+            )
+        )
+
+    async def update(self, key: str, value: str) -> MemoryEntry:
+        return MemoryEntry.from_raw(
+            await self._t.request(
+                "PATCH", f"/api/memories/{key}", json={"value": value}
+            )
+        )
+
+    async def delete(self, key: str) -> None:
+        await self._t.request("DELETE", f"/api/memories/{key}")
+
+    async def set_opt_out(self, enabled: bool) -> None:
+        await self._t.request(
+            "PATCH", "/api/memories/preferences", json={"optOut": enabled}
+        )

eolaswork/resources/models.py

@@ -0,0 +1,35 @@
+"""Models + providers catalogue. Read-only."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..types import Model
+from ._base import BaseAsyncResource, BaseResource
+
+
+def _items(body: Any) -> list[dict[str, Any]]:
+    if isinstance(body, dict):
+        return list(body.get("items", []))
+    return list(body or [])
+
+
+class Models(BaseResource):
+    def list(self) -> list[Model]:
+        return [
+            Model.from_raw(r) for r in _items(self._t.request("GET", "/api/llm-models"))
+        ]
+
+    def providers(self) -> list[dict[str, Any]]:
+        return _items(self._t.request("GET", "/api/providers"))
+
+
+class AsyncModels(BaseAsyncResource):
+    async def list(self) -> list[Model]:
+        return [
+            Model.from_raw(r)
+            for r in _items(await self._t.request("GET", "/api/llm-models"))
+        ]
+
+    async def providers(self) -> list[dict[str, Any]]:
+        return _items(await self._t.request("GET", "/api/providers"))