modus-sdk 0.2.0__py3-none-any.whl

modus/__init__.py

@@ -0,0 +1,144 @@
+"""
+Modus Python SDK — consumption client.
+
+Quick start:
+    import modus
+
+    client = modus.Modus(api_key="modus_xxx")
+
+    for skill in client.skills.list():
+        print(skill.name, skill.status)
+
+    for item in client.context.items.list():
+        print(modus.context_item_label(item))
+
+To create or configure skills, use modus.management.ModusManagement.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from ._client import AsyncModus, Modus
+from ._exceptions import (
+    APIConnectionError,
+    AuthenticationError,
+    ConflictError,
+    InternalServerError,
+    ModusError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RunCancelledError,
+    StreamTimeoutError,
+    UnprocessableError,
+)
+from .types import (
+    Agent,
+    AgentRun,
+    AgentRunCreateRequest,
+    AgentRunListItem,
+    AgentStatus,
+    AgentType,
+    AsyncPage,
+    CancelRunRequest,
+    ChatResult,
+    Connection,
+    ContextItem,
+    ContextType,
+    Conversation,
+    ConversationListItem,
+    EditQueuedRunRequest,
+    InterruptRunRequest,
+    Message,
+    ModusRunCreateRequest,
+    Page,
+    ResumeRunRequest,
+    Skill,
+    SkillContextComposition,
+    SkillRunCreateRequest,
+    SkillStatus,
+    SuggestionEventSource,
+    SuggestionEventType,
+    SuggestionQuestion,
+    WorkflowActionRequest,
+    context_item_label,
+    is_verified,
+    link_title,
+    link_url,
+    note_body,
+    note_title,
+    saved_query_name,
+    saved_query_sql,
+)
+from .types.runs import (
+    AssistantContentResetEvent,
+    CancelledEvent,
+    DoneEvent,
+    ErrorEvent,
+    StreamTimeoutEvent,
+    TokenEvent,
+)
+
+try:
+    __version__ = _pkg_version("modus-sdk")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "APIConnectionError",
+    "AssistantContentResetEvent",
+    "Agent",
+    "AgentRun",
+    "AgentRunCreateRequest",
+    "AgentRunListItem",
+    "AgentStatus",
+    "AgentType",
+    "AsyncModus",
+    "AsyncPage",
+    "AuthenticationError",
+    "CancelledEvent",
+    "ChatResult",
+    "ConflictError",
+    "Connection",
+    "CancelRunRequest",
+    "ContextItem",
+    "ContextType",
+    "context_item_label",
+    "is_verified",
+    "link_title",
+    "link_url",
+    "note_body",
+    "note_title",
+    "saved_query_name",
+    "saved_query_sql",
+    "Conversation",
+    "ConversationListItem",
+    "DoneEvent",
+    "EditQueuedRunRequest",
+    "ErrorEvent",
+    "InternalServerError",
+    "InterruptRunRequest",
+    "Message",
+    "ModusRunCreateRequest",
+    "Modus",
+    "ModusError",
+    "NotFoundError",
+    "Page",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ResumeRunRequest",
+    "RunCancelledError",
+    "Skill",
+    "SkillContextComposition",
+    "SkillRunCreateRequest",
+    "SkillStatus",
+    "SuggestionEventSource",
+    "SuggestionEventType",
+    "SuggestionQuestion",
+    "StreamTimeoutError",
+    "StreamTimeoutEvent",
+    "TokenEvent",
+    "UnprocessableError",
+    "WorkflowActionRequest",
+    "__version__",
+]

modus/_auth.py

@@ -0,0 +1,111 @@
+"""
+API key resolution and auth header generation.
+
+The SDK accepts an API key via:
+  1. Explicit argument: Modus(api_key="modus_xxx")
+  2. Environment variable: MODUS_API_KEY=modus_xxx
+
+The SDK validates the key format at initialization time so users get a
+clear error immediately rather than a cryptic 401 on the first request.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional, Union
+
+import httpx
+
+from ._exceptions import AuthenticationError
+
+_ENV_VAR = "MODUS_API_KEY"
+_BASE_URL_ENV_VAR = "MODUS_BASE_URL"
+_AGENT_HOST_ENV_VAR = "MODUS_AGENT_HOST"
+_TIMEOUT_ENV_VAR = "MODUS_TIMEOUT"
+_MAX_RETRIES_ENV_VAR = "MODUS_MAX_RETRIES"
+_KEY_PREFIX = "modus_"
+
+
+def resolve_api_key(api_key: Optional[str]) -> str:
+    """
+    Resolve the API key from an explicit argument or the environment.
+    Raises AuthenticationError if no key is found or the format is invalid.
+    """
+    key = api_key or os.environ.get(_ENV_VAR)
+
+    if not key:
+        raise AuthenticationError(
+            f"No API key provided. "
+            f"Pass api_key= or set the {_ENV_VAR} environment variable. "
+            f"Create a token at app.modus.com → Settings → API Tokens."
+        )
+
+    if not key.startswith(_KEY_PREFIX):
+        raise AuthenticationError(
+            f"Invalid API key format. Modus API keys start with '{_KEY_PREFIX}'. "
+            f"Create a token at app.modus.com → Settings → API Tokens."
+        )
+
+    return key
+
+
+def resolve_base_url(base_url: Optional[str]) -> Optional[str]:
+    """
+    Resolve the base URL from an explicit constructor argument, or from the
+    ``MODUS_BASE_URL`` environment variable when set. Returns ``None`` if
+    neither is set (caller uses the production default).
+    """
+    return base_url or os.environ.get(_BASE_URL_ENV_VAR) or None
+
+
+def resolve_agent_host(agent_host: Optional[str]) -> Optional[str]:
+    """
+    Resolve the agent host from an explicit constructor argument, or from the
+    ``MODUS_AGENT_HOST`` environment variable when set. Returns ``None`` if
+    neither is set (streaming falls back to ``base_url``).
+    """
+    return agent_host or os.environ.get(_AGENT_HOST_ENV_VAR) or None
+
+
+def resolve_timeout(explicit: Union[float, httpx.Timeout, None]) -> Union[float, httpx.Timeout, None]:
+    """
+    Resolve timeout from an explicit argument or the MODUS_TIMEOUT env var.
+    Returns None if neither is set (caller will use the default).
+
+    If MODUS_TIMEOUT is set but invalid, returns None (falls back to default).
+    """
+    if explicit is not None:
+        return explicit
+    raw = os.environ.get(_TIMEOUT_ENV_VAR)
+    if raw is not None:
+        try:
+            return float(raw)
+        except ValueError:
+            return None
+    return None
+
+
+def resolve_max_retries(explicit: Optional[int]) -> Optional[int]:
+    """
+    Resolve max_retries from an explicit argument or the MODUS_MAX_RETRIES env var.
+    Returns None if neither is set (caller will use the default).
+
+    If MODUS_MAX_RETRIES is set but invalid, returns None (falls back to default).
+    """
+    if explicit is not None:
+        if explicit < 0:
+            raise ValueError(f"max_retries must be >= 0, got {explicit}")
+        return explicit
+    raw = os.environ.get(_MAX_RETRIES_ENV_VAR)
+    if raw is not None:
+        try:
+            value = int(raw)
+            return value if value >= 0 else None
+        except ValueError:
+            return None
+    return None
+
+
+def auth_headers(api_key: str) -> dict[str, str]:
+    """Return the Authorization header dict for a given API key."""
+    return {"Authorization": f"Bearer {api_key}"}

modus/_chat.py

@@ -0,0 +1,411 @@
+"""Shared chat path building and SSE stream session helpers."""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict, Iterator, List, Literal, Optional, Union
+from urllib.parse import quote
+
+from ._exceptions import ModusError, RunCancelledError, StreamTimeoutError
+from ._generated.models import SkillChatRequestDto, SkillChatResponseDto
+from ._http import AsyncHttpClient, HttpClient
+from ._openapi_invoke import format_operation_path
+from ._streaming import parse_sse_stream
+from ._validation import validate_chat_model, validate_id
+from .types.chat import ChatResult
+from .types.runs import (
+    AssistantContentResetEvent,
+    CancelledEvent,
+    DoneEvent,
+    ErrorEvent,
+    RunEvent,
+    StreamTimeoutEvent,
+    TokenEvent,
+)
+
+RunVersion = Union[Literal["published", "draft"], str]
+
+
+def _effective_thread_id(thread_id: Optional[str]) -> Optional[str]:
+    """Treat None and blank strings as "start a new thread"."""
+    if thread_id is None:
+        return None
+    if isinstance(thread_id, str) and not thread_id.strip():
+        return None
+    return thread_id
+
+
+def _chat_path(
+    resource: str,
+    resource_id: Union[int, str],
+    *,
+    thread_id: Optional[str],
+    stream: bool,
+) -> str:
+    safe_id = quote(str(resource_id), safe="")
+    suffix = "/stream" if stream else ""
+    tid = _effective_thread_id(thread_id)
+    if tid is not None:
+        safe_tid = quote(str(tid), safe="")
+        return f"/api/v1/{resource}/{safe_id}/conversations/{safe_tid}/chat{suffix}"
+    return f"/api/v1/{resource}/{safe_id}/chat{suffix}"
+
+
+def _modus_chat_path(*, thread_id: Optional[str], stream: bool) -> str:
+    suffix = "/stream" if stream else ""
+    if thread_id is not None:
+        validate_id(thread_id, name="thread_id")
+    tid = _effective_thread_id(thread_id)
+    if tid is not None:
+        safe_tid = quote(str(tid), safe="")
+        return f"/api/v1/modus/conversations/{safe_tid}/chat{suffix}"
+    return f"/api/v1/modus/chat{suffix}"
+
+
+def _chat_body(message: str, model: str) -> Dict[str, Any]:
+    return SkillChatRequestDto(message=message, model=model).model_dump(  # type: ignore[arg-type]
+        by_alias=True,
+        exclude_none=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Agent-host runs paths (streaming only)
+# ---------------------------------------------------------------------------
+
+
+def _agent_host_modus_runs_path() -> str:
+    """POST {agent_host}/agent/v1/modus/runs — SSE stream."""
+    return "/agent/v1/modus/runs"
+
+
+def _agent_runs_body(
+    message: str,
+    model: str,
+    *,
+    session_id: Optional[str] = None,
+    version: Optional[RunVersion] = None,
+) -> Dict[str, Any]:
+    """Build the request body for agent-host runs (streaming) requests.
+
+    Args:
+        message:    The user message.
+        model:      Model id, e.g. ``"claude-sonnet-5"``.
+        session_id: Existing conversation/session ID (``thread_id`` on the SDK surface).
+        version:    Run a specific variation — ``"published"`` or ``"draft"``.
+    """
+    body: Dict[str, Any] = {
+        "message": message,
+        "config": {"model": model},
+    }
+    if session_id is not None:
+        body["sessionId"] = session_id
+    if version is not None:
+        body["version"] = version
+    return body
+
+
+def _raise_for_event(event: RunEvent) -> RunEvent:
+    if isinstance(event, ErrorEvent):
+        raise ModusError(event.message)
+    if isinstance(event, CancelledEvent):
+        raise RunCancelledError()
+    if isinstance(event, StreamTimeoutEvent):
+        raise StreamTimeoutError()
+    return event
+
+
+class ChatStream:
+    """Sync context manager for SSE chat streams."""
+
+    def __init__(
+        self,
+        http: HttpClient,
+        path: str,
+        body: Dict[str, Any],
+    ) -> None:
+        self._http = http
+        self._path = path
+        self._body = body
+        self._final: Optional[ChatResult] = None
+        self._text_parts: List[str] = []
+
+    def __enter__(self) -> "ChatStream":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        return None
+
+    @property
+    def text_stream(self) -> Iterator[str]:
+        for event in self._event_stream_impl(supports_reset=False):
+            if isinstance(event, TokenEvent):
+                yield event.content
+
+    @property
+    def event_stream(self) -> Iterator[RunEvent]:
+        return self._event_stream_impl(supports_reset=True)
+
+    def _event_stream_impl(self, *, supports_reset: bool) -> Iterator[RunEvent]:
+        body = dict(self._body)
+        if supports_reset:
+            body["streamProtocolVersion"] = 2
+        for line in self._http.stream_post(self._path, json=body):
+            for event in parse_sse_stream(iter([line])):
+                event = _raise_for_event(event)
+                if isinstance(event, TokenEvent):
+                    self._text_parts.append(event.content)
+                if isinstance(event, AssistantContentResetEvent):
+                    self._text_parts[:] = [event.content]
+                if isinstance(event, DoneEvent):
+                    content = "".join(self._text_parts)
+                    self._final = SkillChatResponseDto(
+                        content=content,
+                        thread_id=event.thread_id,
+                        run_id=event.run_id,
+                    )
+                    yield event
+                    return
+                yield event
+
+    def get_final_result(self) -> ChatResult:
+        if self._final is None:
+            raise ModusError(
+                "Stream ended without a done event; call get_final_result() only after "
+                "consuming text_stream or event_stream."
+            )
+        return self._final
+
+
+class AsyncChatStream:
+    """Async context manager for SSE chat streams."""
+
+    def __init__(
+        self,
+        http: AsyncHttpClient,
+        path: str,
+        body: Dict[str, Any],
+    ) -> None:
+        self._http = http
+        self._path = path
+        self._body = body
+        self._final: Optional[ChatResult] = None
+        self._text_parts: List[str] = []
+
+    async def __aenter__(self) -> "AsyncChatStream":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        return None
+
+    @property
+    def text_stream(self) -> AsyncIterator[str]:
+        return self._text_stream_impl()
+
+    async def _text_stream_impl(self) -> AsyncIterator[str]:
+        async for event in self._event_stream_impl(supports_reset=False):
+            if isinstance(event, TokenEvent):
+                yield event.content
+
+    @property
+    def event_stream(self) -> AsyncIterator[RunEvent]:
+        return self._event_stream_impl(supports_reset=True)
+
+    async def _event_stream_impl(self, *, supports_reset: bool) -> AsyncIterator[RunEvent]:
+        body = dict(self._body)
+        if supports_reset:
+            body["streamProtocolVersion"] = 2
+        async for line in self._http.stream_post(self._path, json=body):
+            for event in parse_sse_stream(iter([line])):
+                event = _raise_for_event(event)
+                if isinstance(event, TokenEvent):
+                    self._text_parts.append(event.content)
+                if isinstance(event, AssistantContentResetEvent):
+                    self._text_parts[:] = [event.content]
+                if isinstance(event, DoneEvent):
+                    content = "".join(self._text_parts)
+                    self._final = SkillChatResponseDto(
+                        content=content,
+                        thread_id=event.thread_id,
+                        run_id=event.run_id,
+                    )
+                    yield event
+                    return
+                yield event
+
+    def get_final_result(self) -> ChatResult:
+        if self._final is None:
+            raise ModusError(
+                "Stream ended without a done event; call get_final_result() only after "
+                "consuming text_stream or event_stream."
+            )
+        return self._final
+
+
+def chat_buffered(
+    http: HttpClient,
+    resource: str,
+    resource_id: Union[int, str],
+    message: str,
+    *,
+    model: str,
+    thread_id: Optional[str] = None,
+) -> ChatResult:
+    """POST buffered chat (JSON response)."""
+    validate_id(resource_id, name=f"{resource}_id")
+    validate_chat_model(model)
+    path = _chat_path(resource, resource_id, thread_id=thread_id, stream=False)
+    data = http.post(path, json=_chat_body(message, model))
+    return SkillChatResponseDto.model_validate(data)
+
+
+async def chat_buffered_async(
+    http: AsyncHttpClient,
+    resource: str,
+    resource_id: Union[int, str],
+    message: str,
+    *,
+    model: str,
+    thread_id: Optional[str] = None,
+) -> ChatResult:
+    validate_id(resource_id, name=f"{resource}_id")
+    validate_chat_model(model)
+    path = _chat_path(resource, resource_id, thread_id=thread_id, stream=False)
+    data = await http.post(path, json=_chat_body(message, model))
+    return SkillChatResponseDto.model_validate(data)
+
+
+def modus_chat_buffered(
+    http: HttpClient,
+    message: str,
+    *,
+    model: str,
+    thread_id: Optional[str] = None,
+) -> ChatResult:
+    validate_chat_model(model)
+    path = _modus_chat_path(thread_id=thread_id, stream=False)
+    data = http.post(path, json=_chat_body(message, model))
+    return SkillChatResponseDto.model_validate(data)
+
+
+async def modus_chat_buffered_async(
+    http: AsyncHttpClient,
+    message: str,
+    *,
+    model: str,
+    thread_id: Optional[str] = None,
+) -> ChatResult:
+    validate_chat_model(model)
+    path = _modus_chat_path(thread_id=thread_id, stream=False)
+    data = await http.post(path, json=_chat_body(message, model))
+    return SkillChatResponseDto.model_validate(data)
+
+
+# ---------------------------------------------------------------------------
+# Agent-host stream sessions (scopes / modus / workflows)
+#
+# Scope and workflow run paths (/agent/v1/scopes|workflows/{id}/runs) are
+# resolved from the generated OPERATIONS registry rather than a hardcoded
+# literal; the Modus run path is a fixed agent-host route.
+# ---------------------------------------------------------------------------
+
+
+def modus_stream_session(
+    agent_http: HttpClient,
+    message: str,
+    *,
+    model: str,
+    thread_id: Optional[str] = None,
+) -> ChatStream:
+    """Stream a Modus chat via the agent host's by-reference runs path."""
+    validate_chat_model(model)
+    session_id = _effective_thread_id(thread_id)
+    path = _agent_host_modus_runs_path()
+    body = _agent_runs_body(message, model, session_id=session_id)
+    return ChatStream(agent_http, path, body)
+
+
+def modus_stream_session_async(
+    agent_http: AsyncHttpClient,
+    message: str,
+    *,
+    model: str,
+    thread_id: Optional[str] = None,
+) -> AsyncChatStream:
+    """Async stream a Modus chat via the agent host's by-reference runs path."""
+    validate_chat_model(model)
+    session_id = _effective_thread_id(thread_id)
+    path = _agent_host_modus_runs_path()
+    body = _agent_runs_body(message, model, session_id=session_id)
+    return AsyncChatStream(agent_http, path, body)
+
+
+def scope_stream_session(
+    agent_http: HttpClient,
+    resource_id: Union[int, str],
+    message: str,
+    *,
+    model: str,
+    thread_id: Optional[str] = None,
+    version: Optional[RunVersion] = None,
+) -> ChatStream:
+    """Stream a scope chat via the agent host's by-reference runs path."""
+    validate_id(resource_id, name="scope_id")
+    validate_chat_model(model)
+    session_id = _effective_thread_id(thread_id)
+    path = format_operation_path("ScopeRunsController_create", {"id": resource_id})
+    body = _agent_runs_body(message, model, session_id=session_id, version=version)
+    return ChatStream(agent_http, path, body)
+
+
+def scope_stream_session_async(
+    agent_http: AsyncHttpClient,
+    resource_id: Union[int, str],
+    message: str,
+    *,
+    model: str,
+    thread_id: Optional[str] = None,
+    version: Optional[RunVersion] = None,
+) -> AsyncChatStream:
+    """Async stream a scope chat via the agent host's by-reference runs path."""
+    validate_id(resource_id, name="scope_id")
+    validate_chat_model(model)
+    session_id = _effective_thread_id(thread_id)
+    path = format_operation_path("ScopeRunsController_create", {"id": resource_id})
+    body = _agent_runs_body(message, model, session_id=session_id, version=version)
+    return AsyncChatStream(agent_http, path, body)
+
+
+def workflow_stream_session(
+    agent_http: HttpClient,
+    resource_id: Union[int, str],
+    message: str,
+    *,
+    model: str,
+    thread_id: Optional[str] = None,
+    version: Optional[RunVersion] = None,
+) -> ChatStream:
+    """Stream a workflow chat via the agent host's by-reference runs path."""
+    validate_id(resource_id, name="workflow_id")
+    validate_chat_model(model)
+    session_id = _effective_thread_id(thread_id)
+    path = format_operation_path("WorkflowRunsController_create", {"id": resource_id})
+    body = _agent_runs_body(message, model, session_id=session_id, version=version)
+    return ChatStream(agent_http, path, body)
+
+
+def workflow_stream_session_async(
+    agent_http: AsyncHttpClient,
+    resource_id: Union[int, str],
+    message: str,
+    *,
+    model: str,
+    thread_id: Optional[str] = None,
+    version: Optional[RunVersion] = None,
+) -> AsyncChatStream:
+    """Async stream a workflow chat via the agent host's by-reference runs path."""
+    validate_id(resource_id, name="workflow_id")
+    validate_chat_model(model)
+    session_id = _effective_thread_id(thread_id)
+    path = format_operation_path("WorkflowRunsController_create", {"id": resource_id})
+    body = _agent_runs_body(message, model, session_id=session_id, version=version)
+    return AsyncChatStream(agent_http, path, body)