shadow-os 1.0.0__py3-none-any.whl

shadow_os/__init__.py

@@ -0,0 +1,79 @@
+"""Shadow-OS — the official Python SDK.
+
+Build on Shadow-OS from Python: talk to your account assistant, manage documents and semantic search, and
+create + operate configured business agents end to end (knowledge, access links, customers, escalations,
+appointments, analytics).
+
+Quickstart::
+
+    from shadow_os import ShadowOS
+
+    with ShadowOS() as client:              # reads $SHADOW_OS_API_KEY
+        print(client.chat("hello"))
+
+See https://shadow-os-ai.vercel.app/developers for the full API reference.
+"""
+from ._version import __version__
+from .client import (
+    AgentClient,
+    AgentHandle,
+    AsyncAgentClient,
+    AsyncAgentHandle,
+    AsyncShadowOS,
+    ShadowOS,
+)
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    NotFoundError,
+    PayloadTooLarge,
+    PermissionDeniedError,
+    QuotaExceeded,
+    RateLimited,
+    ServerError,
+    ServiceUnavailable,
+    ShadowOSError,
+)
+from .models import (
+    Agent,
+    AgentConfig,
+    AgentReply,
+    AgentToken,
+    Analytics,
+    Appointment,
+    ChatResponse,
+    Conversation,
+    CreatedAgent,
+    DeliveryStatus,
+    Document,
+    Escalation,
+    KnowledgeItem,
+    Member,
+    Message,
+    PrimaryShareLink,
+    SearchHit,
+    SearchResults,
+    ShareLink,
+    Template,
+    ToolCatalog,
+    Usage,
+)
+
+__all__ = [
+    "__version__",
+    # clients
+    "ShadowOS", "AsyncShadowOS", "AgentClient", "AsyncAgentClient", "AgentHandle", "AsyncAgentHandle",
+    # models
+    "Agent", "AgentConfig", "AgentReply", "AgentToken", "Analytics", "Appointment", "ChatResponse",
+    "Conversation", "CreatedAgent", "DeliveryStatus", "Document", "Escalation", "KnowledgeItem",
+    "Member", "Message", "PrimaryShareLink", "SearchHit", "SearchResults", "ShareLink", "Template",
+    "ToolCatalog", "Usage",
+    # errors
+    "ShadowOSError", "APIConnectionError", "APITimeoutError", "APIStatusError", "BadRequestError",
+    "AuthenticationError", "PermissionDeniedError", "NotFoundError", "ConflictError", "QuotaExceeded",
+    "RateLimited", "PayloadTooLarge", "ServerError", "ServiceUnavailable",
+]

shadow_os/_specs.py

@@ -0,0 +1,281 @@
+"""One definition per API endpoint, shared by the sync and async clients.
+
+Every call is described ONCE as a :class:`Call` — method, path, payload and the function that turns the raw
+JSON into a model. The sync and async resource classes are then thin wrappers that execute a ``Call``. That
+is what keeps the two clients from drifting apart: a fix to a path or a parser lands in both, because there
+is only one of each.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Union
+
+from . import models as m
+
+FileLike = Union[str, "os.PathLike[str]", Path, tuple]
+
+
+def _compact(d: Dict[str, Any]) -> Dict[str, Any]:
+    """Drop keys whose value is None. No endpoint in this API distinguishes an explicit null from an absent
+    field, so sending nulls is pure noise on the wire (and in anyone's request logs)."""
+    return {k: v for k, v in d.items() if v is not None}
+
+
+@dataclass
+class Call:
+    method: str
+    path: str
+    json: Any = None
+    params: Optional[Dict[str, Any]] = None
+    files: Any = None
+    data: Any = None
+    timeout: Optional[float] = None
+    parse: Callable[[Any], Any] = field(default=lambda x: x)
+
+
+def _as_list(payload: Any, key: str, model) -> List[Any]:
+    rows = payload.get(key) if isinstance(payload, Mapping) else payload
+    return [model.from_dict(r) for r in (rows or [])]
+
+
+def _open_upload(file: FileLike, field_name: str = "file") -> Any:
+    """Normalise a path / (name, bytes) / (name, bytes, content_type) tuple into httpx's files format."""
+    if isinstance(file, tuple):
+        return {field_name: file}
+    p = Path(file)
+    if not p.is_file():
+        raise FileNotFoundError(f"No such file: {p}")
+    return {field_name: (p.name, p.read_bytes())}
+
+
+# ══ account assistant ═════════════════════════════════════════════════════════
+
+def chat(input: str, session_id: Optional[str] = None, scope: Optional[str] = None) -> Call:
+    return Call("POST", "/api/v1/agent",
+                json=_compact({"input": input, "session_id": session_id, "scope": scope}),
+                parse=m.ChatResponse.from_dict)
+
+
+def usage() -> Call:
+    return Call("GET", "/api/v1/usage", parse=m.Usage.from_dict)
+
+
+# ══ documents (account-scoped RAG) ════════════════════════════════════════════
+
+def upload(file: FileLike, session_id: Optional[str] = None, scope: Optional[str] = None) -> Call:
+    data = {k: v for k, v in {"session_id": session_id, "scope": scope}.items() if v is not None}
+    return Call("POST", "/api/v1/upload", files=_open_upload(file), data=data or None, parse=lambda d: d)
+
+
+def list_documents(session_id: Optional[str] = None, scope: Optional[str] = None) -> Call:
+    return Call("GET", "/api/v1/documents", params={"session_id": session_id, "scope": scope},
+                parse=lambda d: _as_list(d, "documents", m.Document))
+
+
+def search(query: str, top_k: int = 4, session_id: Optional[str] = None, scope: Optional[str] = None) -> Call:
+    return Call("POST", "/api/v1/search",
+                json=_compact({"query": query, "top_k": top_k, "session_id": session_id, "scope": scope}),
+                parse=m.SearchResults.from_dict)
+
+
+# ══ agents — lifecycle ════════════════════════════════════════════════════════
+
+def create_agent(name: str = "", persona: str = "", template: str = "",
+                 fields: Optional[Mapping[str, Any]] = None,
+                 config: Optional[Mapping[str, Any]] = None) -> Call:
+    return Call("POST", "/api/v1/agents",
+                json={"name": name, "persona": persona, "template": template,
+                      "fields": dict(fields or {}), "config": dict(config or {})},
+                parse=m.CreatedAgent.from_dict)
+
+
+def list_agents() -> Call:
+    return Call("GET", "/api/v1/agents", parse=lambda d: _as_list(d, "agents", m.Agent))
+
+
+def get_agent(agent_id: str) -> Call:
+    return Call("GET", f"/api/agents/{agent_id}",
+                parse=lambda d: m.Agent.from_dict(d.get("agent", d) if isinstance(d, Mapping) else d))
+
+
+def update_agent(agent_id: str, name: Optional[str] = None, persona: Optional[str] = None,
+                 config: Optional[Mapping[str, Any]] = None) -> Call:
+    body: Dict[str, Any] = {}
+    if name is not None:
+        body["name"] = name
+    if persona is not None:
+        body["persona"] = persona
+    if config is not None:
+        body["config"] = dict(config)
+    return Call("PATCH", f"/api/v1/agents/{agent_id}", json=body, parse=lambda d: d)
+
+
+def delete_agent(agent_id: str) -> Call:
+    return Call("DELETE", f"/api/agents/{agent_id}", parse=lambda d: d)
+
+
+def templates() -> Call:
+    return Call("GET", "/api/agent/templates", parse=lambda d: _as_list(d, "templates", m.Template))
+
+
+def tool_catalog() -> Call:
+    return Call("GET", "/api/agent/tool-catalog", parse=m.ToolCatalog.from_dict)
+
+
+# ══ agents — access (tokens & share links) ════════════════════════════════════
+
+def create_token(agent_id: str, role: str = "member", label: str = "") -> Call:
+    return Call("POST", f"/api/agents/{agent_id}/tokens", json={"role": role, "label": label},
+                parse=m.AgentToken.from_dict)
+
+
+def list_tokens(agent_id: str) -> Call:
+    return Call("GET", f"/api/agents/{agent_id}/tokens",
+                parse=lambda d: _as_list(d, "tokens", m.AgentToken))
+
+
+def revoke_token(agent_id: str, token_id: str) -> Call:
+    return Call("DELETE", f"/api/agents/{agent_id}/tokens/{token_id}", parse=lambda d: d)
+
+
+def create_share_link(agent_id: str, role: str = "member", label: str = "") -> Call:
+    return Call("POST", f"/api/agents/{agent_id}/share", json={"role": role, "label": label},
+                parse=m.ShareLink.from_dict)
+
+
+def list_share_links(agent_id: str) -> Call:
+    return Call("GET", f"/api/agents/{agent_id}/share", parse=lambda d: _as_list(d, "links", m.ShareLink))
+
+
+def primary_share_link(agent_id: str) -> Call:
+    return Call("GET", f"/api/agents/{agent_id}/share-link", parse=m.PrimaryShareLink.from_dict)
+
+
+def revoke_share_link(agent_id: str, share_id: str) -> Call:
+    return Call("DELETE", f"/api/agents/{agent_id}/share/{share_id}", parse=lambda d: d)
+
+
+# ══ agents — knowledge ════════════════════════════════════════════════════════
+
+def add_knowledge_text(agent_id: str, text: str, title: str = "note") -> Call:
+    # Server model is _KnowledgeText{title, text} — exactly these two fields.
+    return Call("POST", f"/api/agents/{agent_id}/knowledge",
+                json={"title": title or "note", "text": text}, parse=lambda d: d)
+
+
+def add_knowledge_file(agent_id: str, file: FileLike, description: str = "", display_name: str = "") -> Call:
+    data = {k: v for k, v in {"description": description, "display_name": display_name}.items() if v}
+    return Call("POST", f"/api/agents/{agent_id}/knowledge/file",
+                files=_open_upload(file), data=data or None, timeout=300.0, parse=lambda d: d)
+
+
+def add_knowledge_url(agent_id: str, url: str, title: str = "") -> Call:
+    # Server model is _KbUrl{url, title}.
+    return Call("POST", f"/api/agents/{agent_id}/knowledge/url",
+                json={"url": url, "title": title}, timeout=300.0, parse=lambda d: d)
+
+
+def list_knowledge(agent_id: str) -> Call:
+    return Call("GET", f"/api/agents/{agent_id}/knowledge",
+                parse=lambda d: _as_list(d, "files", m.KnowledgeItem))
+
+
+def delete_knowledge(agent_id: str, file_name: str) -> Call:
+    return Call("DELETE", f"/api/agents/{agent_id}/knowledge/{file_name}", parse=lambda d: d)
+
+
+def rename_knowledge(agent_id: str, file_name: str, new_name: str) -> Call:
+    # Server model is _KnowledgeRename{new_name} — a single required field.
+    return Call("PATCH", f"/api/agents/{agent_id}/knowledge/{file_name}",
+                json={"new_name": new_name}, parse=lambda d: d)
+
+
+def add_chat_files(agent_id: str, files: Sequence[FileLike]) -> Call:
+    """Files the agent may DELIVER to customers, without becoming searchable knowledge."""
+    payload = []
+    for f in files:
+        if isinstance(f, tuple):
+            payload.append(("files", f))
+        else:
+            p = Path(f)
+            if not p.is_file():
+                raise FileNotFoundError(f"No such file: {p}")
+            payload.append(("files", (p.name, p.read_bytes())))
+    return Call("POST", f"/api/agents/{agent_id}/chat-file", files=payload, timeout=300.0, parse=lambda d: d)
+
+
+# ══ agents — customers & operations ═══════════════════════════════════════════
+
+def list_members(agent_id: str) -> Call:
+    return Call("GET", f"/api/agents/{agent_id}/members", parse=lambda d: _as_list(d, "members", m.Member))
+
+
+def list_escalations(agent_id: str) -> Call:
+    return Call("GET", f"/api/agents/{agent_id}/escalations",
+                parse=lambda d: _as_list(d, "escalations", m.Escalation))
+
+
+def answer_escalation(agent_id: str, escalation_id: str, answer: str) -> Call:
+    return Call("POST", f"/api/agents/{agent_id}/escalations/{escalation_id}/answer",
+                json={"answer": answer}, parse=lambda d: d)
+
+
+def list_appointments(agent_id: str) -> Call:
+    return Call("GET", f"/api/agents/{agent_id}/appointments",
+                parse=lambda d: _as_list(d, "appointments", m.Appointment))
+
+
+def analytics(agent_id: str) -> Call:
+    return Call("GET", f"/api/agents/{agent_id}/analytics", parse=m.Analytics.from_dict)
+
+
+def delivery_status(agent_id: str) -> Call:
+    def _parse(d: Any) -> List[m.DeliveryStatus]:
+        statuses = (d or {}).get("statuses") or {}
+        return [m.DeliveryStatus.from_dict(k, v) for k, v in statuses.items()]
+    return Call("GET", f"/api/agents/{agent_id}/delivery-status", parse=_parse)
+
+
+def test_agent(agent_id: str, input: str, session_id: str = "test",
+               attachments: Optional[Sequence[str]] = None) -> Call:
+    return Call("POST", f"/api/agents/{agent_id}/test",
+                json={"input": input, "session_id": session_id, "attachments": list(attachments or [])},
+                parse=m.AgentReply.from_dict)
+
+
+def test_history(agent_id: str, session_id: str = "test") -> Call:
+    return Call("GET", f"/api/agents/{agent_id}/test-history", params={"session_id": session_id},
+                parse=lambda d: _as_list(d, "messages", m.Message))
+
+
+# ══ talking TO an agent (agent token / share code) ════════════════════════════
+
+def agent_info(token: str) -> Call:
+    return Call("GET", "/api/agent/info", params={"token": token}, parse=lambda d: d)
+
+
+def agent_run(token: str, input: str, session_id: str = "default",
+              member_key: str = "", member_name: str = "") -> Call:
+    return Call("POST", "/api/agent/run",
+                json={"token": token, "input": input, "session_id": session_id,
+                      "member_key": member_key, "member_name": member_name},
+                parse=m.AgentReply.from_dict)
+
+
+def agent_threads(token: str, member_key: str = "") -> Call:
+    return Call("GET", "/api/agent/threads", params={"token": token, "member_key": member_key},
+                parse=lambda d: _as_list(d, "threads", m.Conversation))
+
+
+def agent_history(token: str, session_id: str = "main", member_key: str = "") -> Call:
+    return Call("GET", "/api/agent/history",
+                params={"token": token, "session_id": session_id, "member_key": member_key},
+                parse=lambda d: _as_list(d, "messages", m.Message))
+
+
+def agent_delete_thread(token: str, session_id: str, member_key: str = "") -> Call:
+    return Call("POST", "/api/agent/thread/delete",
+                json={"token": token, "session_id": session_id, "member_key": member_key},
+                parse=lambda d: d)

shadow_os/_transport.py

@@ -0,0 +1,260 @@
+"""HTTP transport: one place that knows about retries, timeouts and the two error envelopes.
+
+Kept separate from the resource classes so retry/backoff behaviour is defined exactly once and every call in
+the SDK inherits it — including the ones added later.
+
+Two things here are shaped by how this particular backend behaves in production:
+
+* **Cold starts.** The service can be asleep; the first request then takes tens of seconds or returns 502/503.
+  So a connection error, a timeout and 502/503/504 are all treated as *retryable*, with exponential backoff
+  and full jitter, and the default timeout is generous rather than snappy.
+* **Two error envelopes.** ``/api/v1/*`` and ``/api/agent/run`` return
+  ``{"error": "...", "detail": "...", "request_id": "..."}``; the rest of the API returns FastAPI's plain
+  ``{"detail": ...}``. ``_extract_error`` understands both so callers always get the same exception shape.
+"""
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Mapping, Optional
+
+import httpx
+
+from . import errors
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://shadow-os-backend.onrender.com"
+DEFAULT_TIMEOUT = 120.0
+DEFAULT_MAX_RETRIES = 3
+_RETRY_STATUSES = frozenset({408, 409, 429, 500, 502, 503, 504})
+
+
+def _extract_error(response: httpx.Response) -> errors.APIStatusError:
+    """Turn a non-2xx response into the right exception, whichever envelope it used."""
+    code: Optional[str] = None
+    request_id: Optional[str] = response.headers.get("x-request-id")
+    message = f"HTTP {response.status_code}"
+    body: Any = None
+    try:
+        body = response.json()
+    except Exception:
+        text = (response.text or "").strip()
+        if text:
+            message = text[:500]
+
+    if isinstance(body, Mapping):
+        code = body.get("error") if isinstance(body.get("error"), str) else None
+        request_id = body.get("request_id") or request_id
+        detail = body.get("detail")
+        if isinstance(detail, str) and detail.strip():
+            message = detail
+        elif isinstance(detail, Mapping):
+            message = str(detail.get("message") or detail.get("error") or detail)
+            code = code or (detail.get("error") if isinstance(detail.get("error"), str) else None)
+        elif isinstance(detail, list) and detail:
+            # FastAPI validation errors: surface the first one in a readable way.
+            first = detail[0]
+            if isinstance(first, Mapping):
+                loc = ".".join(str(x) for x in (first.get("loc") or []))
+                message = f"{loc}: {first.get('msg')}" if loc else str(first.get("msg"))
+            else:
+                message = str(first)
+
+    retry_after: Optional[float] = None
+    raw_retry = response.headers.get("retry-after")
+    if raw_retry:
+        try:
+            retry_after = float(raw_retry)
+        except ValueError:
+            retry_after = None
+
+    return errors.error_for_status(
+        response.status_code,
+        message=message,
+        code=code,
+        request_id=request_id,
+        body=body,
+        retry_after=retry_after,
+    )
+
+
+def _backoff_delay(attempt: int, retry_after: Optional[float]) -> float:
+    """Exponential backoff with full jitter; an explicit Retry-After always wins."""
+    if retry_after is not None and retry_after >= 0:
+        return min(retry_after, 60.0)
+    return random.uniform(0, min(8.0, 0.5 * (2 ** attempt)))
+
+
+def build_headers(auth_header: Optional[dict], extra: Optional[Mapping[str, str]] = None) -> dict:
+    headers = {
+        "Accept": "application/json",
+        "User-Agent": f"shadow-os-python/{__version__}",
+    }
+    if auth_header:
+        headers.update(auth_header)
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+class Transport:
+    """Synchronous transport wrapping an ``httpx.Client``."""
+
+    def __init__(
+        self,
+        base_url: str,
+        auth_header: Optional[dict],
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        client: Optional[httpx.Client] = None,
+        default_headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._auth = auth_header
+        self.max_retries = max(0, int(max_retries))
+        self._owns_client = client is None
+        self._client = client or httpx.Client(timeout=timeout, follow_redirects=True)
+        self._default_headers = dict(default_headers or {})
+
+    # -- lifecycle ---------------------------------------------------------
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "Transport":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # -- request -----------------------------------------------------------
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Mapping[str, Any]] = None,
+        files: Any = None,
+        data: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        url = path if path.startswith("http") else f"{self.base_url}{path}"
+        merged = build_headers(self._auth, {**self._default_headers, **(headers or {})})
+        # Drop None params so callers can pass optional arguments straight through.
+        clean_params = {k: v for k, v in (params or {}).items() if v is not None} or None
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method, url, json=json, params=clean_params, files=files,
+                    data=data, headers=merged, timeout=timeout,
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = errors.APITimeoutError(f"Request timed out: {exc}")
+            except httpx.HTTPError as exc:
+                last_exc = errors.APIConnectionError(f"Could not reach Shadow-OS: {exc}")
+            else:
+                if response.status_code < 300:
+                    return _decode(response)
+                err = _extract_error(response)
+                # 409 is retryable only as a transient lock ("still processing"), never for a real conflict.
+                if response.status_code in _RETRY_STATUSES and attempt < self.max_retries:
+                    if response.status_code != 409 or "processing" in err.message.lower():
+                        time.sleep(_backoff_delay(attempt, getattr(err, "retry_after", None)))
+                        continue
+                raise err
+            if attempt < self.max_retries:
+                time.sleep(_backoff_delay(attempt, None))
+                continue
+            break
+        # Retries exhausted on a transport-level failure. The fallback is not decoration: `last_exc` is
+        # Optional, and `raise None` would turn a network problem into a confusing TypeError.
+        raise last_exc or errors.APIConnectionError("Request failed without a response.")
+
+
+class AsyncTransport:
+    """Asynchronous twin of :class:`Transport`. Same behaviour, ``await``-ed."""
+
+    def __init__(
+        self,
+        base_url: str,
+        auth_header: Optional[dict],
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        client: Optional[httpx.AsyncClient] = None,
+        default_headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._auth = auth_header
+        self.max_retries = max(0, int(max_retries))
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(timeout=timeout, follow_redirects=True)
+        self._default_headers = dict(default_headers or {})
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncTransport":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Mapping[str, Any]] = None,
+        files: Any = None,
+        data: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        import anyio
+
+        url = path if path.startswith("http") else f"{self.base_url}{path}"
+        merged = build_headers(self._auth, {**self._default_headers, **(headers or {})})
+        clean_params = {k: v for k, v in (params or {}).items() if v is not None} or None
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method, url, json=json, params=clean_params, files=files,
+                    data=data, headers=merged, timeout=timeout,
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = errors.APITimeoutError(f"Request timed out: {exc}")
+            except httpx.HTTPError as exc:
+                last_exc = errors.APIConnectionError(f"Could not reach Shadow-OS: {exc}")
+            else:
+                if response.status_code < 300:
+                    return _decode(response)
+                err = _extract_error(response)
+                if response.status_code in _RETRY_STATUSES and attempt < self.max_retries:
+                    if response.status_code != 409 or "processing" in err.message.lower():
+                        await anyio.sleep(_backoff_delay(attempt, getattr(err, "retry_after", None)))
+                        continue
+                raise err
+            if attempt < self.max_retries:
+                await anyio.sleep(_backoff_delay(attempt, None))
+                continue
+            break
+        raise last_exc or errors.APIConnectionError("Request failed without a response.")
+
+
+def _decode(response: httpx.Response) -> Any:
+    if response.status_code == 204 or not response.content:
+        return None
+    ctype = response.headers.get("content-type", "")
+    if "json" in ctype:
+        return response.json()
+    return response.text

shadow_os/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"