modus-sdk 0.2.0__py3-none-any.whl

modus/_pagination.py

@@ -0,0 +1,175 @@
+"""
+Helpers to build Page[T] / AsyncPage[T] from Modus API list responses.
+
+Public list endpoints return resource-plural arrays and ``nextPageToken``:
+    { "skills": [...], "nextPageToken": "..." }
+
+Query params use ``pageSize`` and ``pageToken``. Python resources expose
+``page_size`` / ``page_token``; ``Page.next_page_token`` maps from ``nextPageToken``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Type, TypeVar
+
+from ._exceptions import ModusError
+from .types.pagination import AsyncPage, Page
+
+T = TypeVar("T")
+
+
+def normalize_page_token(token: Optional[str]) -> Optional[str]:
+    """Treat None and blank strings as no page token."""
+    if token is None or not str(token).strip():
+        return None
+    return token
+
+
+def aip_list_params(
+    page_size: int,
+    page_token: Optional[str] = None,
+    **extra: Any,
+) -> Dict[str, Any]:
+    """Build cursor-pagination query params (pageSize, pageToken) plus optional filters."""
+    params: Dict[str, Any] = {"pageSize": page_size, **extra}
+    token = normalize_page_token(page_token)
+    if token is not None:
+        params["pageToken"] = token
+    return params
+
+
+def _next_page_token_from_response(data: Dict[str, Any]) -> Optional[str]:
+    return normalize_page_token(data.get("nextPageToken"))
+
+
+def _require_items_list(data: Dict[str, Any], items_key: str) -> List[Any]:
+    """Return ``data[items_key]`` when it is a list; otherwise raise ModusError."""
+    value = data.get(items_key)
+    if not isinstance(value, list):
+        raise ModusError(
+            f"Unexpected list response shape: {items_key!r} must be a list, "
+            f"got {type(value).__name__}. This is likely a backend error."
+        )
+    return value
+
+
+def build_aip_page(
+    data: Dict[str, Any],
+    items_key: str,
+    item_class: Type[T],
+    fetch_page: Callable[[str], Page[T]],
+) -> Page[T]:
+    """Construct Page[T] from an AIP list response with a Pydantic item class."""
+    if not isinstance(data, dict) or items_key not in data:
+        raise ModusError(
+            f"Unexpected list response shape: missing {items_key!r}. "
+            f"Got: {type(data).__name__}. This is likely a backend error."
+        )
+    raw_items: List[Dict[str, Any]] = _require_items_list(data, items_key)
+    items = [item_class.model_validate(raw) for raw in raw_items]  # type: ignore[attr-defined]
+    return Page(
+        items=items,
+        next_page_token=_next_page_token_from_response(data),
+        _fetch_page=fetch_page,
+    )
+
+
+def build_async_aip_page(
+    data: Dict[str, Any],
+    items_key: str,
+    item_class: Type[T],
+    fetch_page: Callable[[str], Awaitable[AsyncPage[T]]],
+) -> AsyncPage[T]:
+    """Construct AsyncPage[T] from an AIP list response with a Pydantic item class."""
+    if not isinstance(data, dict) or items_key not in data:
+        raise ModusError(
+            f"Unexpected list response shape: missing {items_key!r}. "
+            f"Got: {type(data).__name__}. This is likely a backend error."
+        )
+    raw_items: List[Dict[str, Any]] = _require_items_list(data, items_key)
+    items = [item_class.model_validate(raw) for raw in raw_items]  # type: ignore[attr-defined]
+    return AsyncPage(
+        items=items,
+        next_page_token=_next_page_token_from_response(data),
+        _fetch_page=fetch_page,
+    )
+
+
+def build_aip_page_mapped(
+    data: Dict[str, Any],
+    items_key: str,
+    map_item: Callable[[Dict[str, Any]], T],
+    fetch_page: Callable[[str], Page[T]],
+) -> Page[T]:
+    """Construct Page[T] from an AIP list response using a per-item mapper."""
+    if not isinstance(data, dict) or items_key not in data:
+        raise ModusError(
+            f"Unexpected list response shape: missing {items_key!r}. "
+            f"Got: {type(data).__name__}. This is likely a backend error."
+        )
+    raw_items: List[Dict[str, Any]] = _require_items_list(data, items_key)
+    items = [map_item(raw) for raw in raw_items]
+    return Page(
+        items=items,
+        next_page_token=_next_page_token_from_response(data),
+        _fetch_page=fetch_page,
+    )
+
+
+def build_async_aip_page_mapped(
+    data: Dict[str, Any],
+    items_key: str,
+    map_item: Callable[[Dict[str, Any]], T],
+    fetch_page: Callable[[str], Awaitable[AsyncPage[T]]],
+) -> AsyncPage[T]:
+    """Construct AsyncPage[T] from an AIP list response using a per-item mapper."""
+    if not isinstance(data, dict) or items_key not in data:
+        raise ModusError(
+            f"Unexpected list response shape: missing {items_key!r}. "
+            f"Got: {type(data).__name__}. This is likely a backend error."
+        )
+    raw_items: List[Dict[str, Any]] = _require_items_list(data, items_key)
+    items = [map_item(raw) for raw in raw_items]
+    return AsyncPage(
+        items=items,
+        next_page_token=_next_page_token_from_response(data),
+        _fetch_page=fetch_page,
+    )
+
+
+def build_aip_page_raw(
+    data: Dict[str, Any],
+    items_key: str,
+    fetch_page: Callable[[str], Page[Dict[str, Any]]],
+) -> Page[Dict[str, Any]]:
+    """Construct Page[dict] from an AIP list response (e.g. context item values)."""
+    if not isinstance(data, dict) or items_key not in data:
+        raise ModusError(
+            f"Unexpected list response shape: missing {items_key!r}. "
+            f"Got: {type(data).__name__}. This is likely a backend error."
+        )
+    items: List[Dict[str, Any]] = [dict(x) for x in _require_items_list(data, items_key)]
+    return Page(
+        items=items,
+        next_page_token=_next_page_token_from_response(data),
+        _fetch_page=fetch_page,
+    )
+
+
+def build_async_aip_page_raw(
+    data: Dict[str, Any],
+    items_key: str,
+    fetch_page: Callable[[str], Awaitable[AsyncPage[Dict[str, Any]]]],
+) -> AsyncPage[Dict[str, Any]]:
+    """Construct AsyncPage[dict] from an AIP list response."""
+    if not isinstance(data, dict) or items_key not in data:
+        raise ModusError(
+            f"Unexpected list response shape: missing {items_key!r}. "
+            f"Got: {type(data).__name__}. This is likely a backend error."
+        )
+    items: List[Dict[str, Any]] = [dict(x) for x in _require_items_list(data, items_key)]
+    return AsyncPage(
+        items=items,
+        next_page_token=_next_page_token_from_response(data),
+        _fetch_page=fetch_page,
+    )

modus/_query.py

@@ -0,0 +1,38 @@
+"""Small helpers for building request URLs."""
+from __future__ import annotations
+
+from typing import Optional
+from urllib.parse import quote
+
+
+def _validate_update_mask(update_mask: str) -> None:
+    if not update_mask.strip():
+        raise ValueError(
+            "update_mask must be a non-empty comma-separated list of field names"
+        )
+
+
+def update_mask_query(update_mask: Optional[str]) -> Optional[dict[str, str]]:
+    """Build an ``updateMask`` query dict for PATCH via ``invoke_operation``."""
+    if update_mask is None:
+        return None
+    _validate_update_mask(update_mask)
+    return {"updateMask": update_mask}
+
+
+def with_update_mask(path: str, update_mask: Optional[str]) -> str:
+    """Append an ``updateMask`` query parameter to ``path`` when provided.
+
+    The API uses ``updateMask`` (a comma-separated list of field names) on PATCH
+    requests to explicitly clear fields. When ``update_mask`` is ``None`` the path
+    is returned unchanged.
+
+    Raises:
+        ValueError: If ``update_mask`` is given but empty or whitespace-only — an
+            empty ``updateMask=`` query value has ambiguous PATCH semantics.
+    """
+    if update_mask is None:
+        return path
+    _validate_update_mask(update_mask)
+    sep = "&" if "?" in path else "?"
+    return f"{path}{sep}updateMask={quote(update_mask, safe='')}"

modus/_retry.py

@@ -0,0 +1,123 @@
+"""
+Retry logic for transient errors.
+
+RateLimitError, InternalServerError, and APIConnectionError are retried.
+Client errors (4xx except 429) are not retried — they represent caller mistakes.
+
+Backoff strategy:
+  - attempt 0 -> no sleep (immediate retry)
+  - attempt 1 -> ~1s + jitter
+  - attempt 2 -> ~2s + jitter
+  - If Retry-After header is present on 429, use that value instead.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from typing import Awaitable, Callable, TypeVar
+
+from ._exceptions import APIConnectionError, InternalServerError, NotFoundError, RateLimitError
+
+T = TypeVar("T")
+
+_RETRYABLE_ERRORS = (RateLimitError, InternalServerError, APIConnectionError)
+_DEPLOY_NOT_FOUND_BACKOFF_SECONDS = 0.5
+_MAX_DEPLOY_NOT_FOUND_RETRIES = 1
+
+
+def _backoff_seconds(attempt: int, exc: Exception) -> float:
+    """Calculate how long to sleep before the next retry attempt."""
+    if isinstance(exc, RateLimitError) and exc.retry_after is not None:
+        return max(0.0, float(exc.retry_after))
+    if attempt == 0:
+        return 0.0
+    # Exponential backoff: 1s, 2s, ... with ±0.3s jitter
+    return max(0.5, (2 ** (attempt - 1)) + (random.random() * 0.6 - 0.3))
+
+
+def with_retry(
+    func: Callable[[], T],
+    max_retries: int,
+    *,
+    retry_not_found_on_deploy: bool = False,
+) -> T:
+    """
+    Call func, retrying on RateLimitError, InternalServerError, and APIConnectionError.
+
+    Args:
+        func:        Zero-argument callable to invoke.
+        max_retries: Maximum number of additional attempts after the first.
+                     0 means no retries (single attempt total).
+        retry_not_found_on_deploy:
+                     When True, retry HTTP 404 once with a short fixed delay.
+                     This deploy-specific retry does not consume max_retries.
+
+    Returns:
+        The return value of func on success.
+
+    Raises:
+        The last exception if all attempts are exhausted.
+        Any non-retryable exception immediately (no retry).
+    """
+    deploy_not_found_retries = 0
+    attempt = 0
+    while True:
+        try:
+            return func()
+        except NotFoundError:
+            if (
+                retry_not_found_on_deploy
+                and deploy_not_found_retries < _MAX_DEPLOY_NOT_FOUND_RETRIES
+            ):
+                deploy_not_found_retries += 1
+                time.sleep(_DEPLOY_NOT_FOUND_BACKOFF_SECONDS)
+                continue
+            raise
+        except _RETRYABLE_ERRORS as exc:
+            if attempt >= max_retries:
+                raise
+            time.sleep(_backoff_seconds(attempt, exc))
+            attempt += 1
+
+
+async def async_with_retry(
+    func: Callable[[], Awaitable[T]],
+    max_retries: int,
+    *,
+    retry_not_found_on_deploy: bool = False,
+) -> T:
+    """
+    Async version of with_retry. Uses asyncio.sleep so the event loop is
+    not blocked during backoff waits.
+
+    Args:
+        func:        Zero-argument async callable (coroutine function) to invoke.
+        max_retries: Maximum number of additional attempts after the first.
+        retry_not_found_on_deploy:
+                     When True, retry HTTP 404 once with a short fixed delay.
+                     This deploy-specific retry does not consume max_retries.
+
+    Returns:
+        The return value of func on success.
+    """
+    deploy_not_found_retries = 0
+    attempt = 0
+    while True:
+        try:
+            return await func()
+        except NotFoundError:
+            if (
+                retry_not_found_on_deploy
+                and deploy_not_found_retries < _MAX_DEPLOY_NOT_FOUND_RETRIES
+            ):
+                deploy_not_found_retries += 1
+                await asyncio.sleep(_DEPLOY_NOT_FOUND_BACKOFF_SECONDS)
+                continue
+            raise
+        except _RETRYABLE_ERRORS as exc:
+            if attempt >= max_retries:
+                raise
+            await asyncio.sleep(_backoff_seconds(attempt, exc))
+            attempt += 1

modus/_streaming.py

@@ -0,0 +1,115 @@
+"""
+SSE stream parser.
+
+parse_sse_stream() converts raw SSE lines into typed RunEvent objects.
+
+Events and their handling:
+    token          -> TokenEvent  (yielded to text_stream)
+    done           -> DoneEvent   (ends iteration; use ChatResult from chat())
+    error          -> ErrorEvent  (raised as ModusError)
+    cancelled      -> CancelledEvent (raised as RunCancelledError)
+    stream_timeout -> StreamTimeoutEvent (raised as StreamTimeoutError)
+    all others     -> silently ignored
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Iterator, Optional
+
+from .types.runs import (
+    AssistantContentResetEvent,
+    CancelledEvent,
+    DoneEvent,
+    ErrorEvent,
+    RunEvent,
+    StreamTimeoutEvent,
+    TokenEvent,
+)
+
+_SILENTLY_IGNORED = frozenset(
+    {
+        "heartbeat",
+        "ws_chunk",
+        "unknown",
+        "tool_start",
+        "tool_end",
+        "tool_chunk",
+        "agent_thinking",
+        "warning",
+        "selected_final_content",
+    }
+)
+
+
+def _parse_line(line: str) -> Optional[Dict[str, Any]]:
+    """
+    Parse a single SSE line. Returns the parsed JSON payload or None.
+    SSE lines that carry data start with "data: ".
+    """
+    if not line.startswith("data: "):
+        return None
+    raw = line[6:].strip()
+    if not raw or raw == "[DONE]":
+        return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+
+
+def parse_sse_stream(lines: Iterator[str]) -> Iterator[RunEvent]:
+    """
+    Convert a raw SSE line iterator into typed RunEvent objects.
+
+    Silently drops keepalive and unrecognized event types.
+    Yields only: TokenEvent, DoneEvent, ErrorEvent, CancelledEvent,
+    StreamTimeoutEvent.
+    """
+    for line in lines:
+        data = _parse_line(line)
+        if data is None:
+            continue
+
+        event_type = data.get("type", "unknown")
+
+        if event_type == "token":
+            yield TokenEvent(content=data.get("content", ""))
+        elif event_type == "done":
+            yield DoneEvent(
+                run_id=data.get("runId", ""),
+                thread_id=data.get("threadId", ""),
+            )
+        elif event_type == "error":
+            msg = (
+                data.get("error")
+                or data.get("message")
+                or data.get("content")
+                or "Unknown run error"
+            )
+            yield ErrorEvent(message=str(msg))
+        elif event_type == "cancelled":
+            yield CancelledEvent()
+        elif event_type == "stream_timeout":
+            yield StreamTimeoutEvent()
+        elif event_type == "assistant_content_reset":
+            content = data.get("content")
+            if not isinstance(content, str):
+                continue
+            yield AssistantContentResetEvent(
+                content=content,
+                visible_content=(
+                    str(data["visibleContent"])
+                    if isinstance(data.get("visibleContent"), str)
+                    else None
+                ),
+                attempt=(int(data["attempt"]) if isinstance(data.get("attempt"), int) else 1),
+                reason=(
+                    str(data["reason"])
+                    if isinstance(data.get("reason"), str)
+                    else "provider_stream_failed"
+                ),
+            )
+        elif event_type in _SILENTLY_IGNORED:
+            continue
+        # Truly unknown types: silently ignored for forward compatibility

modus/_validation.py

@@ -0,0 +1,61 @@
+"""Tiny client-side validators shared across resources.
+
+These exist so we fail fast on obvious bad inputs (empty IDs, negative limits)
+before making a network call. They raise ``ValueError`` — caller-visible bugs,
+not server-side conditions.
+"""
+from __future__ import annotations
+
+from typing import Optional, Union
+
+# API max page size for context list and values surfaces.
+DEFAULT_MAX_PAGE_SIZE = 200
+
+
+def validate_page_size(page_size: int, *, max_page_size: Optional[int] = None) -> None:
+    """Reject page_size values that the backend would reject anyway, locally."""
+    if not isinstance(page_size, int) or isinstance(page_size, bool) or page_size < 1:
+        raise ValueError(f"page_size must be a positive int, got {page_size!r}")
+    if max_page_size is not None and page_size > max_page_size:
+        raise ValueError(
+            f"page_size must be <= {max_page_size}, got {page_size!r}"
+        )
+
+
+def validate_id(resource_id: Union[int, str], *, name: str = "id") -> None:
+    """Reject empty/whitespace-only string IDs that would produce ambiguous URLs."""
+    if isinstance(resource_id, str) and not resource_id.strip():
+        raise ValueError(f"{name} must be a non-empty string or int")
+
+
+# Canonical chat model ids from SkillChatRequestDto (keep in sync with the API spec).
+ALLOWED_CHAT_MODELS = frozenset({
+    "claude-sonnet-5",
+    "claude-sonnet-4.6",
+    "claude-opus-4.8",
+    "gpt-5.2",
+    "gpt-5.5",
+    "gpt-5-mini",
+    "gpt-oss-120b",
+    "gpt-oss-20b",
+    "qwen3-235b-a22b-2507",
+    "qwen3-coder",
+    "qwen3-32b",
+    "deepseek-chat-v3.1",
+    "minimax-m2.7",
+    "llama-4-maverick",
+    "llama-4-scout",
+    "llama-3.3-70b-instruct",
+    "gemini-3.1-pro-preview",
+    "gemini-3-flash-preview",
+    "grok-4.3-fast",
+    "grok-4.3",
+})
+
+
+def validate_chat_model(model: str) -> None:
+    if model not in ALLOWED_CHAT_MODELS:
+        supported = ", ".join(sorted(ALLOWED_CHAT_MODELS))
+        raise ValueError(
+            f"Unsupported model {model!r}. Choose one of: {supported}."
+        )

modus/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

modus/management/__init__.py

@@ -0,0 +1,74 @@
+"""
+modus.management — configuration surface for the Modus SDK.
+
+    from modus.management import ModusManagement
+    mgmt = ModusManagement(api_key="modus_...")
+    mgmt.skills.create(name="Analyst", model="gpt-4o")
+
+Errors are the shared modus.* hierarchy (modus.NotFoundError, etc.).
+"""
+
+from ._client import AsyncModusManagement, ModusManagement
+from .types import (
+    Agent,
+    AgentSelection,
+    AgentSelectionEntry,
+    AgentStatus,
+    AgentTrigger,
+    AgentTriggerValue,
+    AgentType,
+    AsyncPage,
+    ContextItem,
+    ContextItemDeletion,
+    ContextItemUpdate,
+    ContextType,
+    Conversation,
+    ConversationListItem,
+    CreatedContextItem,
+    JsonObject,
+    ManualTrigger,
+    Memory,
+    MemorySearchRequest,
+    MemoryUpdate,
+    Message,
+    Page,
+    ScheduleTrigger,
+    Skill,
+    SkillStatus,
+    Toolset,
+    TriggerSchedule,
+    WorkflowGraph,
+)
+
+__all__ = [
+    "Agent",
+    "AgentSelection",
+    "AgentSelectionEntry",
+    "AgentStatus",
+    "AgentTrigger",
+    "AgentTriggerValue",
+    "AgentType",
+    "AsyncModusManagement",
+    "AsyncPage",
+    "ContextItem",
+    "ContextItemDeletion",
+    "ContextItemUpdate",
+    "ContextType",
+    "Conversation",
+    "ConversationListItem",
+    "CreatedContextItem",
+    "JsonObject",
+    "ManualTrigger",
+    "Memory",
+    "MemorySearchRequest",
+    "MemoryUpdate",
+    "Message",
+    "ModusManagement",
+    "Page",
+    "ScheduleTrigger",
+    "Skill",
+    "SkillStatus",
+    "Toolset",
+    "TriggerSchedule",
+    "WorkflowGraph",
+]