modus-sdk 0.2.0__py3-none-any.whl

modus/_client.py

@@ -0,0 +1,240 @@
+"""
+Top-level client classes.
+
+Modus      — synchronous client for scripts, notebooks, data pipelines
+AsyncModus — asynchronous client for FastAPI, async workflows
+"""
+
+from __future__ import annotations
+
+from typing import Mapping, Optional, Union
+
+import httpx
+
+from ._auth import (
+    resolve_agent_host,
+    resolve_api_key,
+    resolve_base_url,
+    resolve_max_retries,
+    resolve_timeout,
+)
+from ._config import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, ModusConfig
+from ._http import AsyncHttpClient, HttpClient
+from .resources import (
+    AsyncConnectionsResource,
+    AsyncContextResource,
+    AsyncModusResource,
+    AsyncScopesResource,
+    AsyncSuggestionsResource,
+    AsyncWorkflowsResource,
+    ConnectionsResource,
+    ContextResource,
+    ModusResource,
+    ScopesResource,
+    SuggestionsResource,
+    WorkflowsResource,
+)
+
+
+class Modus:
+    """
+    Synchronous Modus API client.
+
+    Instantiate once and reuse across your script or application.
+    The client is thread-safe for concurrent GET requests.
+
+    Args:
+        api_key:     Your Modus API key. If omitted, reads from the
+                     MODUS_API_KEY environment variable.
+        base_url:    API origin without a path suffix (default
+                     https://api.modus.com).
+        agent_host:  Agent host origin for streaming runs (e.g.
+                     https://agent.modus.com). If omitted, reads from the
+                     MODUS_AGENT_HOST environment variable. When not set,
+                     streaming falls back to ``base_url``.
+        base_urls:   Optional service-specific API origins.
+        timeout:     Request timeout as seconds or httpx.Timeout. Default is
+                     5s connect and 300s read.
+        max_retries: Number of automatic retries on 429/5xx (default 2).
+
+    Example:
+        import modus
+
+        client = modus.Modus(api_key="modus_xxx")
+
+        for scope in client.scopes.list():
+            print(scope.name)
+
+        # Write operations use the management client in the same package:
+        from modus.management import ModusManagement
+
+        mgmt = ModusManagement(api_key="modus_xxx")
+        mgmt.context.create_note(
+            title="Fiscal Year",
+            content="Runs Feb 1 – Jan 31.",
+        )
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        agent_host: Optional[str] = None,
+        base_urls: Optional[Mapping[str, str]] = None,
+        timeout: Union[float, httpx.Timeout, None] = None,
+        max_retries: Optional[int] = None,
+    ) -> None:
+        resolved_key = resolve_api_key(api_key)
+        resolved_url = resolve_base_url(base_url) or DEFAULT_BASE_URL
+        resolved_agent_host = resolve_agent_host(agent_host)
+        _t = resolve_timeout(timeout)
+        resolved_timeout = _t if _t is not None else DEFAULT_TIMEOUT
+        resolved_retries = resolve_max_retries(max_retries)
+        if resolved_retries is None:
+            resolved_retries = DEFAULT_MAX_RETRIES
+        self._config = ModusConfig(
+            api_key=resolved_key,
+            base_url=resolved_url,
+            timeout=resolved_timeout,
+            max_retries=resolved_retries,
+            agent_host=resolved_agent_host,
+            base_urls=base_urls or {},
+        )
+        self._http = HttpClient(self._config)
+        # Dedicated HTTP client for streaming to the agent host.
+        # When agent_host is not configured, _agent_http shares the same
+        # base_url as _http so streaming falls back gracefully.
+        if resolved_agent_host is not None:
+            _agent_config = ModusConfig(
+                api_key=resolved_key,
+                base_url=resolved_agent_host,
+                timeout=resolved_timeout,
+                max_retries=resolved_retries,
+            )
+            self._agent_http: HttpClient = HttpClient(_agent_config)
+        else:
+            self._agent_http = self._http
+
+        self.scopes: ScopesResource = ScopesResource(self._http, self._agent_http, self._config)
+        self.modus: ModusResource = ModusResource(self._http, self._agent_http, self._config)
+        self.workflows: WorkflowsResource = WorkflowsResource(
+            self._http, self._agent_http, self._config
+        )
+        self.context: ContextResource = ContextResource(self._http, self._config)
+        self.connections: ConnectionsResource = ConnectionsResource(self._http, self._config)
+        self.suggestions: SuggestionsResource = SuggestionsResource(self._http, self._config)
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+        if self._agent_http is not self._http:
+            self._agent_http.close()
+
+    def __enter__(self) -> "Modus":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"Modus(base_url={self._config.base_url!r})"
+
+
+class AsyncModus:
+    """
+    Asynchronous Modus API client.
+
+    Args:
+        api_key:     Your Modus API key. If omitted, reads from MODUS_API_KEY.
+        base_url:    API origin without a path suffix (default
+                     https://api.modus.com).
+        agent_host:  Agent host origin for streaming runs (e.g.
+                     https://agent.modus.com). If omitted, reads from the
+                     MODUS_AGENT_HOST environment variable. When not set,
+                     streaming falls back to ``base_url``.
+        base_urls:   Optional service-specific API origins.
+        timeout:     Request timeout as seconds or httpx.Timeout. Default is
+                     5s connect and 300s read.
+        max_retries: Retries on 429/5xx (default 2).
+
+    Example:
+        import modus
+
+        client = modus.AsyncModus(api_key="modus_xxx")
+
+        async def main():
+            page = await client.scopes.list()
+            for scope in page:
+                print(scope.name)
+            await client.aclose()
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        agent_host: Optional[str] = None,
+        base_urls: Optional[Mapping[str, str]] = None,
+        timeout: Union[float, httpx.Timeout, None] = None,
+        max_retries: Optional[int] = None,
+    ) -> None:
+        resolved_key = resolve_api_key(api_key)
+        resolved_url = resolve_base_url(base_url) or DEFAULT_BASE_URL
+        resolved_agent_host = resolve_agent_host(agent_host)
+        _t = resolve_timeout(timeout)
+        resolved_timeout = _t if _t is not None else DEFAULT_TIMEOUT
+        resolved_retries = resolve_max_retries(max_retries)
+        if resolved_retries is None:
+            resolved_retries = DEFAULT_MAX_RETRIES
+        self._config = ModusConfig(
+            api_key=resolved_key,
+            base_url=resolved_url,
+            timeout=resolved_timeout,
+            max_retries=resolved_retries,
+            agent_host=resolved_agent_host,
+            base_urls=base_urls or {},
+        )
+        self._http = AsyncHttpClient(self._config)
+        # Dedicated HTTP client for streaming to the agent host.
+        if resolved_agent_host is not None:
+            _agent_config = ModusConfig(
+                api_key=resolved_key,
+                base_url=resolved_agent_host,
+                timeout=resolved_timeout,
+                max_retries=resolved_retries,
+            )
+            self._agent_http: AsyncHttpClient = AsyncHttpClient(_agent_config)
+        else:
+            self._agent_http = self._http
+
+        self.scopes: AsyncScopesResource = AsyncScopesResource(
+            self._http, self._agent_http, self._config
+        )
+        self.modus: AsyncModusResource = AsyncModusResource(self._http, self._agent_http, self._config)
+        self.workflows: AsyncWorkflowsResource = AsyncWorkflowsResource(
+            self._http, self._agent_http, self._config
+        )
+        self.context: AsyncContextResource = AsyncContextResource(self._http, self._config)
+        self.connections: AsyncConnectionsResource = AsyncConnectionsResource(
+            self._http, self._config
+        )
+        self.suggestions: AsyncSuggestionsResource = AsyncSuggestionsResource(
+            self._http, self._config
+        )
+
+    async def aclose(self) -> None:
+        """Close the underlying async HTTP connection pool."""
+        await self._http.aclose()
+        if self._agent_http is not self._http:
+            await self._agent_http.aclose()
+
+    async def __aenter__(self) -> "AsyncModus":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return f"AsyncModus(base_url={self._config.base_url!r})"

modus/_config.py

@@ -0,0 +1,89 @@
+"""
+SDK configuration.
+
+ModusConfig holds all settings for a client instance. It is created once
+during Modus.__init__ and passed down to the HTTP client and all resources.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Mapping, Optional, Union
+
+import httpx
+
+# Defaults — override via Modus(base_url=..., timeout=..., max_retries=...)
+DEFAULT_BASE_URL = "https://api.modus.com"
+
+
+def _default_timeout() -> httpx.Timeout:
+    """Factory function to create the default timeout object."""
+    return httpx.Timeout(
+        connect=5.0,
+        read=300.0,
+        write=10.0,
+        pool=5.0,
+    )
+
+
+DEFAULT_TIMEOUT: Union[float, httpx.Timeout] = _default_timeout()
+DEFAULT_MAX_RETRIES = 2  # retried on 429 + 5xx only
+
+
+def _normalize_base_url(value: str) -> str:
+    return value.rstrip("/")
+
+
+def _normalize_base_urls(value: Mapping[str, str]) -> Mapping[str, str]:
+    return MappingProxyType(
+        {service: _normalize_base_url(base_url) for service, base_url in value.items()}
+    )
+
+
+@dataclass(frozen=True)
+class ModusConfig:
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+    timeout: Union[float, httpx.Timeout] = field(default_factory=_default_timeout)
+    max_retries: int = DEFAULT_MAX_RETRIES
+    agent_host: Optional[str] = None
+    base_urls: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        # Reject obviously-bad max_retries early — negative/non-int would later
+        # bottom out in `range(max_retries + 1)` yielding zero attempts and a
+        # confusing "unreachable" RuntimeError from the retry loop.
+        if not isinstance(self.max_retries, int) or isinstance(self.max_retries, bool) or self.max_retries < 0:
+            raise ValueError(
+                f"max_retries must be a non-negative int, got {self.max_retries!r}"
+            )
+        # frozen=True prevents self.base_url = ... — use object.__setattr__
+        object.__setattr__(self, "base_url", _normalize_base_url(self.base_url))
+        if self.agent_host is not None:
+            object.__setattr__(self, "agent_host", _normalize_base_url(self.agent_host))
+        object.__setattr__(self, "base_urls", _normalize_base_urls(self.base_urls))
+
+    def __repr__(self) -> str:
+        masked = f"{self.api_key[:10]}***" if len(self.api_key) > 10 else "***"
+        return (
+            f"ModusConfig(api_key={masked!r}, base_url={self.base_url!r}, "
+            f"timeout={self.timeout!r}, max_retries={self.max_retries!r})"
+        )
+
+
+def resolve_service_base_url(
+    config: ModusConfig,
+    service: str,
+    server_url: Optional[str],
+) -> str:
+    """Return the origin for an operation's owning public service."""
+    if service == "modus-api":
+        return config.base_url
+    if service in config.base_urls:
+        return config.base_urls[service]
+    if service == "agent-service" and config.agent_host:
+        return config.agent_host
+    if server_url:
+        return _normalize_base_url(server_url)
+    return config.base_url

modus/_deprecation.py

@@ -0,0 +1,29 @@
+"""Shared deprecation warnings for public SDK surfaces.
+
+Call :func:`warn_deprecated` at the start of any public method that still
+invokes an OpenAPI operation marked ``deprecated: true``. Release N keeps the
+method working and warns; release N+1 removes the operation and the method.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+
+def warn_deprecated(*, old: str, new: str, stacklevel: int = 2) -> None:
+    """Emit a :class:`DeprecationWarning` naming the replacement surface.
+
+    Parameters
+    ----------
+    old:
+        The deprecated public name (method, attribute, or path segment).
+    new:
+        The replacement callers should use.
+    stacklevel:
+        Passed to :func:`warnings.warn` (default 2 points at the caller).
+    """
+    warnings.warn(
+        f"{old} is deprecated and will be removed in the next release; use {new} instead.",
+        DeprecationWarning,
+        stacklevel=stacklevel,
+    )

modus/_exceptions.py

@@ -0,0 +1,149 @@
+"""
+Modus SDK exception hierarchy.
+
+All exceptions raised by the SDK are subclasses of ModusError.
+HTTP errors are mapped from status codes; run errors are raised from SSE events.
+
+HTTP mapping:
+    401 -> AuthenticationError
+    403 -> PermissionDeniedError
+    404 -> NotFoundError
+    409 -> ConflictError
+    422 -> UnprocessableError
+    429 -> RateLimitError
+    5xx -> InternalServerError
+
+SSE event mapping:
+    { type: "error" }        -> ModusError (raised from run/stream)
+    { type: "cancelled" }    -> RunCancelledError
+    { type: "stream_timeout" } -> StreamTimeoutError
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+
+class ModusError(Exception):
+    """Base class for all Modus SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        request_id: Optional[str] = None,
+        response_headers: Optional[Mapping[str, str]] = None,
+        body: Optional[str] = None,
+        code: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+        self.response_headers = dict(response_headers) if response_headers else None
+        self.body = body
+        self.code = code
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"message={self.message!r}, "
+            f"status_code={self.status_code!r}, "
+            f"request_id={self.request_id!r})"
+        )
+
+
+class APIConnectionError(ModusError):
+    """
+    Network-level failure (ConnectError, ReadTimeout, etc.) after all
+    automatic retries are exhausted.
+    """
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class AuthenticationError(ModusError):
+    """
+    The API key is missing, invalid, or expired (HTTP 401).
+
+    Check that MODUS_API_KEY is set correctly, or pass api_key= explicitly.
+    Create a token at app.modus.com → Settings → API Tokens.
+    """
+    def __init__(self, message: str, **kwargs: Any) -> None:
+        super().__init__(message, status_code=401, **kwargs)
+
+
+class PermissionDeniedError(ModusError):
+    """Raised when the API key does not have permission for the requested operation (HTTP 403)."""
+    def __init__(self, message: str, **kwargs: Any) -> None:
+        super().__init__(message, status_code=403, **kwargs)
+
+
+class NotFoundError(ModusError):
+    """The requested resource does not exist (HTTP 404)."""
+    def __init__(self, message: str, **kwargs: Any) -> None:
+        super().__init__(message, status_code=404, **kwargs)
+
+
+class ConflictError(ModusError):
+    """
+    Idempotency conflict — a run with this ID already exists with a different
+    body (HTTP 409). Use a new idempotency key or omit it to auto-generate.
+    """
+    def __init__(self, message: str, **kwargs: Any) -> None:
+        super().__init__(message, status_code=409, **kwargs)
+
+
+class UnprocessableError(ModusError):
+    """
+    Request validation failed (HTTP 422).
+    The `errors` attribute contains the full validation error detail.
+    """
+    def __init__(self, message: str, *, errors: Optional[Any] = None, **kwargs: Any) -> None:
+        super().__init__(message, status_code=422, **kwargs)
+        self.errors = errors
+
+
+class RateLimitError(ModusError):
+    """
+    Rate limit exceeded (HTTP 429).
+
+    The `retry_after` attribute contains the number of seconds to wait
+    before retrying, if the server provided a Retry-After header.
+    The SDK retries automatically — this error only surfaces after all
+    retry attempts are exhausted.
+    """
+    def __init__(self, message: str, *, retry_after: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(message, status_code=429, **kwargs)
+        self.retry_after = retry_after
+
+
+class InternalServerError(ModusError):
+    """
+    The server encountered an internal error (HTTP 5xx).
+    The SDK retries automatically — this error only surfaces after all
+    retry attempts are exhausted.
+    """
+    def __init__(self, message: str, *, status_code: int, **kwargs: Any) -> None:
+        super().__init__(message, status_code=status_code, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Run-specific errors (raised from SSE events, not HTTP status codes)
+# ---------------------------------------------------------------------------
+
+
+class RunCancelledError(ModusError):
+    """Raised when a chat stream is cancelled before completing."""
+
+    def __init__(self, message: str = "Run was cancelled.") -> None:
+        super().__init__(message)
+
+
+class StreamTimeoutError(ModusError):
+    """Raised when a chat stream times out before completion."""
+
+    def __init__(self, message: str = "Stream timed out.") -> None:
+        super().__init__(message)
+