modus-sdk 0.2.0__py3-none-any.whl

modus/management/_client.py

@@ -0,0 +1,168 @@
+"""
+ModusManagement — synchronous client for managing Modus scopes, workflows, and context.
+AsyncModusManagement — asynchronous client for the same.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+import httpx
+
+from modus._auth import resolve_api_key, resolve_base_url, resolve_max_retries, resolve_timeout
+from modus._config import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, ModusConfig
+from modus._http import AsyncHttpClient, HttpClient
+
+from .resources import (
+    AsyncContextResource,
+    AsyncOrganizationResource,
+    AsyncScopesResource,
+    AsyncUsageResource,
+    AsyncUsersResource,
+    AsyncWorkflowsResource,
+    ContextResource,
+    OrganizationResource,
+    ScopesResource,
+    UsageResource,
+    UsersResource,
+    WorkflowsResource,
+)
+
+
+class ModusManagement:
+    """
+    Synchronous Modus management client.
+
+    Instantiate once and reuse. Thread-safe for concurrent reads.
+
+    Args:
+        api_key:     Your Modus API key (requires scopes:write + workflows:write scopes).
+                     Falls back to MODUS_API_KEY env var.
+        base_url:    API origin without a path suffix (default
+                     https://api.modus.com).
+        timeout:     Request timeout as seconds or httpx.Timeout. Default is
+                     5s connect and 300s read.
+        max_retries: Retries on 429/5xx (default 2).
+
+    Example:
+        from modus.management import ModusManagement
+
+        client = ModusManagement(api_key="modus_xxx")
+
+        scope = client.scopes.create(
+            name="Snowflake Analyst",
+            instructions=["Answer data questions using Snowflake."],
+            model="gpt-4o",
+        )
+        client.scopes.deploy(scope.id)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[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
+        _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,
+        )
+        self._http = HttpClient(self._config)
+
+        self.scopes: ScopesResource = ScopesResource(self._http, self._config)
+        self.workflows: WorkflowsResource = WorkflowsResource(self._http, self._config)
+        self.context: ContextResource = ContextResource(self._http, self._config)
+        self.usage: UsageResource = UsageResource(self._http, self._config)
+        self.users: UsersResource = UsersResource(self._http, self._config)
+        self.organization: OrganizationResource = OrganizationResource(self._http, self._config)
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> "ModusManagement":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"ModusManagement(base_url={self._config.base_url!r})"
+
+
+class AsyncModusManagement:
+    """
+    Asynchronous Modus management client.
+
+    Args:
+        api_key:     Modus API key with write scopes. Falls back to MODUS_API_KEY.
+        base_url:    API origin without a path suffix (default
+                     https://api.modus.com).
+        timeout:     Request timeout as seconds or httpx.Timeout. Default is
+                     5s connect and 300s read.
+        max_retries: Retries on 429/5xx (default 2).
+
+    Example:
+        client = AsyncModusManagement(api_key="modus_xxx")
+        async def main():
+            scope = await client.scopes.create(name="Analyst", model="gpt-4o")
+            await client.aclose()
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[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
+        _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,
+        )
+        self._http = AsyncHttpClient(self._config)
+
+        self.scopes: AsyncScopesResource = AsyncScopesResource(self._http, self._config)
+        self.workflows: AsyncWorkflowsResource = AsyncWorkflowsResource(self._http, self._config)
+        self.context: AsyncContextResource = AsyncContextResource(self._http, self._config)
+        self.usage: AsyncUsageResource = AsyncUsageResource(self._http, self._config)
+        self.users: AsyncUsersResource = AsyncUsersResource(self._http, self._config)
+        self.organization: AsyncOrganizationResource = AsyncOrganizationResource(
+            self._http, self._config
+        )
+
+    async def aclose(self) -> None:
+        """Close the underlying async HTTP connection pool."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncModusManagement":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return f"AsyncModusManagement(base_url={self._config.base_url!r})"

modus/management/resources/__init__.py

@@ -0,0 +1,21 @@
+from .context.context import AsyncContextResource, ContextResource
+from .organization import AsyncOrganizationResource, OrganizationResource
+from .scopes.scopes import AsyncScopesResource, ScopesResource
+from .usage import AsyncUsageResource, UsageResource
+from .users import AsyncUsersResource, UsersResource
+from .workflows.workflows import AsyncWorkflowsResource, WorkflowsResource
+
+__all__ = [
+    "AsyncContextResource",
+    "AsyncOrganizationResource",
+    "AsyncScopesResource",
+    "AsyncUsageResource",
+    "AsyncUsersResource",
+    "AsyncWorkflowsResource",
+    "ContextResource",
+    "OrganizationResource",
+    "ScopesResource",
+    "UsageResource",
+    "UsersResource",
+    "WorkflowsResource",
+]

modus/management/resources/_access_config_write.py

@@ -0,0 +1,31 @@
+"""Resolve accessConfig wire blobs for guardrails= writes (private)."""
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from ..types._guardrails_access import (
+    access_config_wire_for_create,
+    access_config_wire_for_update,
+)
+
+
+def _access_from_response(raw: Dict[str, Any]) -> Dict[str, Any]:
+    value = raw.get("accessConfig") or raw.get("access_config") or {}
+    return value if isinstance(value, dict) else {}
+
+
+def access_config_body_for_create(
+    guardrails: Optional[List[str]],
+) -> Optional[Dict[str, Any]]:
+    if guardrails is None:
+        return None
+    return access_config_wire_for_create(guardrails)
+
+
+def access_config_body_for_update(
+    guardrails: Optional[List[str]],
+    load_resource: Callable[[], Dict[str, Any]],
+) -> Optional[Dict[str, Any]]:
+    if guardrails is None:
+        return None
+    return access_config_wire_for_update(_access_from_response(load_resource()), guardrails)

modus/management/resources/context/_content_merge.py

@@ -0,0 +1,128 @@
+"""Merge helpers for user-created context item content blobs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modus.types.context import ContextItem
+
+from ...types.context import UserFeedback
+from .items import AsyncContextItemsResource, ContextItemsResource
+
+
+def merge_note_content(existing: dict[str, Any], *, title: str, body: str) -> dict[str, Any]:
+    """Build note ``content`` for ``items.update``, preserving server-owned keys."""
+    return {**existing, "title": title, "content": body}
+
+
+def merge_link_content(
+    existing: dict[str, Any],
+    *,
+    title: str | None = None,
+    url: str | None = None,
+) -> dict[str, Any]:
+    """Build link ``content`` for ``items.update``. Does not re-fetch the URL."""
+    merged = dict(existing)
+    if title is not None:
+        merged["title"] = title
+    if url is not None:
+        merged["url"] = url
+    return merged
+
+
+def merge_saved_query_content(
+    existing: dict[str, Any],
+    *,
+    name: str,
+    query: str,
+    connection_id: str | None = None,
+    path: list[str] | None = None,
+) -> dict[str, Any]:
+    """Build saved_query ``content`` for ``items.update``."""
+    merged: dict[str, Any] = {**existing, "name": name, "query": query}
+    if connection_id is not None:
+        merged["connectionId"] = connection_id
+    if path is not None:
+        merged["path"] = path
+    return merged
+
+
+def _require_content_dict(item: ContextItem, *, context_type: str) -> dict[str, Any]:
+    if item.context_type != context_type:
+        raise ValueError(
+            f"Expected context_type {context_type!r}, got {item.context_type!r}."
+        )
+    content = item.content
+    if not isinstance(content, dict):
+        raise ValueError(
+            f"Context item {item.uid!r} has no dict content; cannot merge {context_type} fields."
+        )
+    return content
+
+
+def update_with_merged_content(
+    items: ContextItemsResource,
+    uid: str,
+    *,
+    context_type: str,
+    merged_content: dict[str, Any],
+    existing: ContextItem | None = None,
+    description: str | None = None,
+    user_feedback: UserFeedback | str | None = None,
+    topics: list[str] | None = None,
+) -> ContextItem:
+    if existing is not None:
+        _require_content_dict(existing, context_type=context_type)
+    return items.update(
+        uid,
+        context_type=context_type,
+        content=merged_content,
+        description=description,
+        user_feedback=user_feedback,
+        topics=topics,
+    )
+
+
+async def async_update_with_merged_content(
+    items: AsyncContextItemsResource,
+    uid: str,
+    *,
+    context_type: str,
+    merged_content: dict[str, Any],
+    existing: ContextItem | None = None,
+    description: str | None = None,
+    user_feedback: UserFeedback | str | None = None,
+    topics: list[str] | None = None,
+) -> ContextItem:
+    if existing is not None:
+        _require_content_dict(existing, context_type=context_type)
+    return await items.update(
+        uid,
+        context_type=context_type,
+        content=merged_content,
+        description=description,
+        user_feedback=user_feedback,
+        topics=topics,
+    )
+
+
+def resolve_existing_content(
+    items: ContextItemsResource,
+    uid: str,
+    *,
+    context_type: str,
+    existing: ContextItem | None,
+) -> dict[str, Any]:
+    item = existing if existing is not None else items.get(uid)
+    return _require_content_dict(item, context_type=context_type)
+
+
+async def async_resolve_existing_content(
+    items: AsyncContextItemsResource,
+    uid: str,
+    *,
+    context_type: str,
+    existing: ContextItem | None,
+) -> dict[str, Any]:
+    item = existing if existing is not None else await items.get(uid)
+    return _require_content_dict(item, context_type=context_type)