modus-sdk 0.2.3__tar.gz → 0.4.0__tar.gz

modus_sdk-0.4.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+**Current release:** [`0.4.0`](https://pypi.org/project/modus-sdk/0.4.0/).
+
+Pre-1.0 (`0.x`) releases are internal. Detailed release notes are not maintained
+until `1.0.0` — keep `[Unreleased]` empty while the package stays on `0.x`.
+
+## [0.4.0] — 2026-08-01
+
+
+### Changed
+
+- Public OpenAPI updates from production release.
+
+
+## [Unreleased]
+
+## [0.3.0] — 2026-07-26

{modus_sdk-0.2.3 → modus_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modus-sdk
-Version: 0.2.3
+Version: 0.4.0
 Summary: Official Python client for Modus — your organization's context layer for AI
 License: MIT
 License-File: LICENSE
@@ -227,3 +227,7 @@ Runnable scripts ship with the package:
 - `examples/scripts/manage_skill.py` — create and deploy a scope (`ModusManagement`, `--write` optional)
 
 Optional Streamlit demo: `examples/apps/modus_skill_chat/` (streaming vs buffered scope chat side by side).
+
+## Docs
+
+Full guides: [docs.getmodus.com/guides/sdk](https://docs.getmodus.com/guides/sdk) (Python page: [sdk-python](https://docs.getmodus.com/guides/sdk-python)).

{modus_sdk-0.2.3 → modus_sdk-0.4.0}/README.md

@@ -207,3 +207,7 @@ Runnable scripts ship with the package:
 - `examples/scripts/manage_skill.py` — create and deploy a scope (`ModusManagement`, `--write` optional)
 
 Optional Streamlit demo: `examples/apps/modus_skill_chat/` (streaming vs buffered scope chat side by side).
+
+## Docs
+
+Full guides: [docs.getmodus.com/guides/sdk](https://docs.getmodus.com/guides/sdk) (Python page: [sdk-python](https://docs.getmodus.com/guides/sdk-python)).

modus_sdk-0.4.0/docs/sphinx/conf.py

@@ -0,0 +1,32 @@
+"""Sphinx config for Mintlify SDK reference (JSON builder)."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# Package root: distribution/clients/python/modus-sdk/
+sys.path.insert(0, os.path.abspath("../.."))
+
+project = "Python SDK"
+author = "Modus"
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+]
+# Keep types in the signature code fence only — putting [str] in prose breaks Mintlify MDX.
+autodoc_typehints = "signature"
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": False,
+    "show-inheritance": False,
+    "member-order": "bysource",
+}
+add_module_names = False
+napoleon_google_docstrings = True
+napoleon_numpy_docstrings = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+exclude_patterns = ["_build"]
+html_theme = "alabaster"
+nitpicky = False

modus_sdk-0.4.0/docs/sphinx/exceptions.rst

@@ -0,0 +1,8 @@
+Exceptions
+==========
+
+Shared error types raised by both clients.
+
+.. automodule:: modus._exceptions
+   :members:
+   :exclude-members: __init__

modus_sdk-0.4.0/docs/sphinx/index.rst

@@ -0,0 +1,21 @@
+Python SDK
+==========
+
+Official Python client for Modus.
+
+* **Modus** — day-to-day reads and chat
+* **ModusManagement** — create, update, and deploy
+
+Install::
+
+   pip install modus-sdk
+
+Authenticate with ``MODUS_API_KEY`` (create a token in the Modus app under
+**Settings → API Tokens**).
+
+.. toctree::
+   :maxdepth: 2
+
+   modus/index
+   management/index
+   exceptions

modus_sdk-0.4.0/docs/sphinx/management/context.rst

@@ -0,0 +1,20 @@
+Context
+=======
+
+Create and update context items (``mgmt.context``).
+
+.. autoclass:: modus.management.resources.context.context.ContextResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.context.context.AsyncContextResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.context.items.ContextItemsResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.context.custom_items.CustomContextItemsResource
+   :members:
+   :exclude-members: __init__

modus_sdk-0.4.0/docs/sphinx/management/index.rst

@@ -0,0 +1,31 @@
+ModusManagement
+===============
+
+Create, update, and deploy scopes, workflows, and context.
+
+.. code-block:: python
+
+   from modus.management import ModusManagement
+
+   mgmt = ModusManagement(api_key="modus_xxx")
+   scope = mgmt.scopes.create(name="Analyst", model="gpt-4o")
+   mgmt.scopes.deploy(scope.id)
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   scopes
+   workflows
+   context
+   tools
+   usage
+   users
+
+.. autoclass:: modus.management.ModusManagement
+   :members:
+   :exclude-members: __init__, __enter__, __exit__, __repr__
+
+.. autoclass:: modus.management.AsyncModusManagement
+   :members:
+   :exclude-members: __init__, __aenter__, __aexit__, __repr__

modus_sdk-0.4.0/docs/sphinx/management/scopes.rst

@@ -0,0 +1,28 @@
+Scopes
+======
+
+Create, update, deploy, and configure scopes (``mgmt.scopes``).
+
+.. autoclass:: modus.management.resources.scopes.scopes.ScopesResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.scopes.scopes.AsyncScopesResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.scopes.conversations.ScopeConversationsResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.scopes.memories.ScopeMemoriesResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.scopes.evaluations.ScopeEvaluationsResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.scopes.supervision.ScopeSupervisionResource
+   :members:
+   :exclude-members: __init__

modus_sdk-0.4.0/docs/sphinx/management/tools.rst

@@ -0,0 +1,12 @@
+Tools
+=====
+
+Browse tool / integration surfaces (``mgmt.tools``).
+
+.. autoclass:: modus.management.resources.tools.ToolsResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.tools.AsyncToolsResource
+   :members:
+   :exclude-members: __init__

modus_sdk-0.4.0/docs/sphinx/management/usage.rst

@@ -0,0 +1,12 @@
+Usage
+=====
+
+Organisation usage metrics (``mgmt.usage``).
+
+.. autoclass:: modus.management.resources.usage.UsageResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.usage.AsyncUsageResource
+   :members:
+   :exclude-members: __init__

modus_sdk-0.4.0/docs/sphinx/management/users.rst

@@ -0,0 +1,12 @@
+Users
+=====
+
+Organisation members and member groups (``mgmt.users``).
+
+.. autoclass:: modus.management.resources.users.UsersResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.users.AsyncUsersResource
+   :members:
+   :exclude-members: __init__

modus_sdk-0.4.0/docs/sphinx/management/workflows.rst

@@ -0,0 +1,20 @@
+Workflows
+=========
+
+Create, update, and deploy workflows (``mgmt.workflows``).
+
+.. autoclass:: modus.management.resources.workflows.workflows.WorkflowsResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.workflows.workflows.AsyncWorkflowsResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.workflows.interfaces.WorkflowInterfacesResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.management.resources.workflows.interfaces.AsyncWorkflowInterfacesResource
+   :members:
+   :exclude-members: __init__

modus_sdk-0.4.0/docs/sphinx/modus/chat.rst

@@ -0,0 +1,12 @@
+Chat
+====
+
+Org-wide Modus assistant (``client.modus``).
+
+.. autoclass:: modus.resources.modus.ModusResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.resources.modus.AsyncModusResource
+   :members:
+   :exclude-members: __init__

modus_sdk-0.4.0/docs/sphinx/modus/connections.rst

@@ -0,0 +1,12 @@
+Connections
+===========
+
+List and find integration connections (``client.connections``).
+
+.. autoclass:: modus.resources.connections.ConnectionsResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.resources.connections.AsyncConnectionsResource
+   :members:
+   :exclude-members: __init__

modus_sdk-0.4.0/docs/sphinx/modus/context.rst

@@ -0,0 +1,12 @@
+Context
+=======
+
+Read the knowledge base (``client.context``).
+
+.. autoclass:: modus.resources.context.ContextResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.resources.context.AsyncContextResource
+   :members:
+   :exclude-members: __init__

modus_sdk-0.4.0/docs/sphinx/modus/index.rst

@@ -0,0 +1,33 @@
+Modus
+=====
+
+Day-to-day client: read scopes, chat, browse context, stream workflow runs.
+
+.. code-block:: python
+
+   import modus
+
+   client = modus.Modus(api_key="modus_xxx")
+   for scope in client.scopes.list():
+       print(scope.name)
+
+Write operations use ``ModusManagement`` (Management section).
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   scopes
+   workflows
+   context
+   connections
+   chat
+   suggestions
+
+.. autoclass:: modus.Modus
+   :members:
+   :exclude-members: __init__, __enter__, __exit__, __repr__
+
+.. autoclass:: modus.AsyncModus
+   :members:
+   :exclude-members: __init__, __aenter__, __aexit__, __repr__

modus_sdk-0.4.0/docs/sphinx/modus/scopes.rst

@@ -0,0 +1,12 @@
+Scopes
+======
+
+Read and chat with scopes (``client.scopes``).
+
+.. autoclass:: modus.resources.scopes.ScopesResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.resources.scopes.AsyncScopesResource
+   :members:
+   :exclude-members: __init__

modus_sdk-0.4.0/docs/sphinx/modus/suggestions.rst

@@ -0,0 +1,12 @@
+Suggestions
+===========
+
+Suggested questions (``client.suggestions``).
+
+.. autoclass:: modus.resources.suggestions.SuggestionsResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.resources.suggestions.AsyncSuggestionsResource
+   :members:
+   :exclude-members: __init__

modus_sdk-0.4.0/docs/sphinx/modus/workflows.rst

@@ -0,0 +1,20 @@
+Workflows
+=========
+
+Read workflows and stream runs (``client.workflows``).
+
+.. autoclass:: modus.resources.workflows.WorkflowsResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.resources.workflows.AsyncWorkflowsResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.resources.workflows.WorkflowRunsResource
+   :members:
+   :exclude-members: __init__
+
+.. autoclass:: modus.resources.workflows.AsyncWorkflowRunsResource
+   :members:
+   :exclude-members: __init__

{modus_sdk-0.2.3 → modus_sdk-0.4.0}/examples/apps/modus_skill_chat/README.md

@@ -1,6 +1,6 @@
 # Modus Skill Chat (Streamlit)
 
-Optional interactive demo: compare **streaming** (`client.skills.chat_stream()`) vs **buffered** (`client.skills.chat()`) skill chat side by side.
+Optional interactive demo: compare **streaming** (`client.scopes.chat_stream()`) vs **buffered** (`client.scopes.chat()`) scope chat side by side.
 
 ## Setup
 

{modus_sdk-0.2.3 → modus_sdk-0.4.0}/examples/apps/modus_skill_chat/app.py

@@ -80,7 +80,7 @@ def get_buffered_client() -> modus.Modus:
 def load_active_skills() -> list[dict[str, Any]]:
     client = get_list_client()
     skills = []
-    for skill in client.skills.list().auto_paging_iter():
+    for skill in client.scopes.list().auto_paging_iter():
         if skill.status == "active":
             skills.append(
                 {
@@ -105,7 +105,7 @@ def _run_buffered_chat(
     thread_id: str | None,
 ) -> ChatResult | BaseException:
     try:
-        return get_buffered_client().skills.chat(
+        return get_buffered_client().scopes.chat(
             skill_id,
             message,
             model=model,
@@ -178,7 +178,7 @@ def _handle_parallel_send(
                 stream_placeholder = st.empty()
                 accumulated = ""
                 try:
-                    with get_stream_client().skills.chat_stream(
+                    with get_stream_client().scopes.chat_stream(
                         skill_id,
                         prompt,
                         model=model,

{modus_sdk-0.2.3 → modus_sdk-0.4.0}/modus/__init__.py

@@ -6,13 +6,13 @@ Quick start:
 
     client = modus.Modus(api_key="modus_xxx")
 
-    for skill in client.skills.list():
-        print(skill.name, skill.status)
+    for scope in client.scopes.list():
+        print(scope.name, scope.status)
 
     for item in client.context.items.list():
         print(modus.context_item_label(item))
 
-To create or configure skills, use modus.management.ModusManagement.
+To create or configure scopes, use modus.management.ModusManagement.
 """
 
 from importlib.metadata import PackageNotFoundError
@@ -53,6 +53,9 @@ from .types import (
     ModusRunCreateRequest,
     Page,
     ResumeRunRequest,
+    Scope,
+    ScopeStatus,
+    ScopeVariation,
     Skill,
     SkillContextComposition,
     SkillRunCreateRequest,
@@ -60,8 +63,14 @@ from .types import (
     SuggestionEventSource,
     SuggestionEventType,
     SuggestionQuestion,
+    Workflow,
     WorkflowActionRequest,
+    WorkflowStatus,
+    WorkflowType,
+    WorkflowVariation,
     context_item_label,
+    conversation_scope_id,
+    conversation_skill_id,
     is_verified,
     link_title,
     link_url,
@@ -128,6 +137,9 @@ __all__ = [
     "RateLimitError",
     "ResumeRunRequest",
     "RunCancelledError",
+    "Scope",
+    "ScopeStatus",
+    "ScopeVariation",
     "Skill",
     "SkillContextComposition",
     "SkillRunCreateRequest",
@@ -139,6 +151,12 @@ __all__ = [
     "StreamTimeoutEvent",
     "TokenEvent",
     "UnprocessableError",
+    "Workflow",
     "WorkflowActionRequest",
+    "WorkflowStatus",
+    "WorkflowType",
+    "WorkflowVariation",
+    "conversation_scope_id",
+    "conversation_skill_id",
     "__version__",
 ]

{modus_sdk-0.2.3 → modus_sdk-0.4.0}/modus/_auth.py

@@ -68,6 +68,32 @@ def resolve_agent_host(agent_host: Optional[str]) -> Optional[str]:
     return agent_host or os.environ.get(_AGENT_HOST_ENV_VAR) or None
 
 
+def _is_modus_api_hostname(hostname: str) -> bool:
+    """Modus-owned API hosts only: ``api.getmodus.com`` or ``api.<env>.getmodus.com``."""
+    import re
+
+    if hostname == "api.getmodus.com":
+        return True
+    return re.fullmatch(r"api\.[a-z0-9-]+\.getmodus\.com", hostname, flags=re.IGNORECASE) is not None
+
+
+def derive_agent_host_from_base_url(base_url: str) -> Optional[str]:
+    """
+    Map ``https://api.<env>.getmodus.com`` → ``https://agent.<env>.getmodus.com``
+    (and prod ``api.getmodus.com`` → ``agent.getmodus.com``). Returns ``None``
+    for localhost / custom / non-Modus origins so callers set agent host explicitly.
+    """
+    from urllib.parse import urlsplit, urlunsplit
+
+    parts = urlsplit(base_url)
+    host = parts.hostname
+    if not host or not _is_modus_api_hostname(host):
+        return None
+    agent_host = f"agent.{host[len('api.') :]}"
+    netloc = f"{agent_host}:{parts.port}" if parts.port is not None else agent_host
+    return urlunsplit((parts.scheme, netloc, "", "", ""))
+
+
 def resolve_organization_id(organization_id: Optional[str]) -> Optional[str]:
     """
     Resolve an optional Clerk organization id for agent-host run bodies.

{modus_sdk-0.2.3 → modus_sdk-0.4.0}/modus/_chat.py

@@ -150,12 +150,14 @@ class ChatStream:
 
     @property
     def text_stream(self) -> Iterator[str]:
+        """Yield assistant reply text as it arrives, one token at a time."""
         for event in self._event_stream_impl(supports_reset=False):
             if isinstance(event, TokenEvent):
                 yield event.content
 
     @property
     def event_stream(self) -> Iterator[RunEvent]:
+        """Yield typed stream events (tokens, tool calls, done, errors)."""
         return self._event_stream_impl(supports_reset=True)
 
     def _event_stream_impl(self, *, supports_reset: bool) -> Iterator[RunEvent]:
@@ -181,6 +183,11 @@ class ChatStream:
                 yield event
 
     def get_final_result(self) -> ChatResult:
+        """Return the assembled reply after the stream finishes.
+
+        Raises:
+            ModusError: if called before the stream emits a done event.
+        """
         if self._final is None:
             raise ModusError(
                 "Stream ended without a done event; call get_final_result() only after "
@@ -212,6 +219,7 @@ class AsyncChatStream:
 
     @property
     def text_stream(self) -> AsyncIterator[str]:
+        """Yield assistant reply text as it arrives. See sync ``text_stream`` for details."""
         return self._text_stream_impl()
 
     async def _text_stream_impl(self) -> AsyncIterator[str]:
@@ -221,6 +229,7 @@ class AsyncChatStream:
 
     @property
     def event_stream(self) -> AsyncIterator[RunEvent]:
+        """Yield typed stream events as they arrive. See sync ``event_stream`` for details."""
         return self._event_stream_impl(supports_reset=True)
 
     async def _event_stream_impl(self, *, supports_reset: bool) -> AsyncIterator[RunEvent]:
@@ -246,6 +255,7 @@ class AsyncChatStream:
                 yield event
 
     def get_final_result(self) -> ChatResult:
+        """Return the assembled reply after the stream finishes. See sync ``get_final_result``."""
         if self._final is None:
             raise ModusError(
                 "Stream ended without a done event; call get_final_result() only after "

{modus_sdk-0.2.3 → modus_sdk-0.4.0}/modus/_client.py

@@ -12,6 +12,7 @@ from typing import Mapping, Optional, Union
 import httpx
 
 from ._auth import (
+    derive_agent_host_from_base_url,
     resolve_agent_host,
     resolve_api_key,
     resolve_base_url,
@@ -55,33 +56,9 @@ class Modus:
                      MODUS_API_KEY environment variable.
         base_url:    API origin without a path suffix (default
                      https://api.getmodus.com).
-        agent_host:  Agent host origin for streaming runs (default
-                     https://agent.getmodus.com). Override via argument or
-                     MODUS_AGENT_HOST.
-        organization_id: Optional Clerk org id for agent-host run bodies.
-                     Usually omit — agent-service uses the PAT principal org.
-                     Override via MODUS_ORGANIZATION_ID when needed.
-        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__(
@@ -98,9 +75,11 @@ class Modus:
         resolved_key = resolve_api_key(api_key)
         resolved_url = resolve_base_url(base_url) or DEFAULT_BASE_URL
         # Same precedence as TS: base_urls['agent-service'] drives streaming too.
+        # Derive agent.<rest> from api.<rest> so staging works with only the API origin.
         resolved_agent_host = (
             (base_urls or {}).get("agent-service")
             or resolve_agent_host(agent_host)
+            or derive_agent_host_from_base_url(resolved_url)
             or DEFAULT_AGENT_HOST
         )
         resolved_org = resolve_organization_id(organization_id)
@@ -163,25 +142,9 @@ class AsyncModus:
         api_key:     Your Modus API key. If omitted, reads from MODUS_API_KEY.
         base_url:    API origin without a path suffix (default
                      https://api.getmodus.com).
-        agent_host:  Agent host origin for streaming runs (default
-                     https://agent.getmodus.com). Override via argument or
-                     MODUS_AGENT_HOST.
-        organization_id: Optional Clerk org id for agent-host run bodies.
-        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__(
@@ -198,9 +161,11 @@ class AsyncModus:
         resolved_key = resolve_api_key(api_key)
         resolved_url = resolve_base_url(base_url) or DEFAULT_BASE_URL
         # Same precedence as TS: base_urls['agent-service'] drives streaming too.
+        # Derive agent.<rest> from api.<rest> so staging works with only the API origin.
         resolved_agent_host = (
             (base_urls or {}).get("agent-service")
             or resolve_agent_host(agent_host)
+            or derive_agent_host_from_base_url(resolved_url)
             or DEFAULT_AGENT_HOST
         )
         resolved_org = resolve_organization_id(organization_id)

{modus_sdk-0.2.3 → modus_sdk-0.4.0}/modus/_deprecation.py

@@ -1,8 +1,9 @@
 """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.
+invokes an OpenAPI operation marked ``deprecated: true``. Soft deprecation is
+optional — keep the method working and warn; remove it in a later **MAJOR**
+when the operation leaves the public spec.
 """
 
 from __future__ import annotations
@@ -23,7 +24,7 @@ def warn_deprecated(*, old: str, new: str, stacklevel: int = 2) -> None:
         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.",
+        f"{old} is deprecated and may be removed in a future MAJOR release; use {new} instead.",
         DeprecationWarning,
         stacklevel=stacklevel,
     )