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

{modus_sdk-0.2.0 → modus_sdk-0.2.3}/CHANGELOG.md

@@ -1,8 +1,14 @@
 # Changelog
 
-**Current release:** [`0.2.0`](https://pypi.org/project/modus-sdk/0.2.0/).
+**Current release:** [`0.2.2`](https://pypi.org/project/modus-sdk/0.2.2/).
 
 
+## [Unreleased]
+
+## [0.2.3] — 2026-07-20
+
+## [0.2.2] — 2026-07-20
+
 ## [0.2.0] — 2026-07-20
 
 ### Added
@@ -34,6 +40,3 @@
 | Version | Notes |
 |---------|--------|
 | 0.1.0–0.1.7 | Internal / TestPyPI previews. Not published to production PyPI. Superseded by `0.2.0`. |
-
-## [Unreleased]
-

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modus-sdk
-Version: 0.2.0
+Version: 0.2.3
 Summary: Official Python client for Modus — your organization's context layer for AI
 License: MIT
 License-File: LICENSE
@@ -166,6 +166,10 @@ from modus.management import ModusManagement
 mgmt = ModusManagement()  # reads MODUS_API_KEY
 scope = mgmt.scopes.create(name="Analyst", model="claude-sonnet-5")
 mgmt.scopes.deploy(scope.id)
+
+# Create returns context_item_id (also available as .uid); list/get use .uid
+note = mgmt.context.create_note("Title", "Body")
+print(note.context_item_id, note.uid)  # same UUID
 ```
 
 Requires a token with write access to scopes and workflows (same as the Modus UI).

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

@@ -146,6 +146,10 @@ from modus.management import ModusManagement
 mgmt = ModusManagement()  # reads MODUS_API_KEY
 scope = mgmt.scopes.create(name="Analyst", model="claude-sonnet-5")
 mgmt.scopes.deploy(scope.id)
+
+# Create returns context_item_id (also available as .uid); list/get use .uid
+note = mgmt.context.create_note("Title", "Body")
+print(note.context_item_id, note.uid)  # same UUID
 ```
 
 Requires a token with write access to scopes and workflows (same as the Modus UI).

modus_sdk-0.2.3/modus/_agent_run_request.py

@@ -0,0 +1,22 @@
+"""Shared agent-host run request helpers (chat_stream + runs.create*)."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+from uuid import uuid4
+
+
+def resolve_agent_run_session_id(session_id: Optional[str] = None) -> str:
+    """Mint or reuse a non-empty sessionId for agent-host runs."""
+    if isinstance(session_id, str) and session_id.strip():
+        return session_id.strip()
+    return str(uuid4())
+
+
+def with_agent_run_session_id(body: Mapping[str, Any]) -> dict[str, Any]:
+    """Copy body and ensure sessionId is set (parity with chat_stream)."""
+    out: dict[str, Any] = dict(body)
+    out["sessionId"] = resolve_agent_run_session_id(
+        out.get("sessionId") if isinstance(out.get("sessionId"), str) else None
+    )
+    return out

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

@@ -21,6 +21,7 @@ from ._exceptions import AuthenticationError
 _ENV_VAR = "MODUS_API_KEY"
 _BASE_URL_ENV_VAR = "MODUS_BASE_URL"
 _AGENT_HOST_ENV_VAR = "MODUS_AGENT_HOST"
+_ORGANIZATION_ID_ENV_VAR = "MODUS_ORGANIZATION_ID"
 _TIMEOUT_ENV_VAR = "MODUS_TIMEOUT"
 _MAX_RETRIES_ENV_VAR = "MODUS_MAX_RETRIES"
 _KEY_PREFIX = "modus_"
@@ -37,13 +38,13 @@ def resolve_api_key(api_key: Optional[str]) -> str:
         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."
+            f"Create a token at app.getmodus.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."
+            f"Create a token at app.getmodus.com → Settings → API Tokens."
         )
 
     return key
@@ -62,11 +63,24 @@ 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``).
+    neither is set (caller uses the production default).
     """
     return agent_host or os.environ.get(_AGENT_HOST_ENV_VAR) or None
 
 
+def resolve_organization_id(organization_id: Optional[str]) -> Optional[str]:
+    """
+    Resolve an optional Clerk organization id for agent-host run bodies.
+    From ``organization_id=`` or ``MODUS_ORGANIZATION_ID``. Usually omitted —
+    agent-service falls back to the PAT principal's org.
+    """
+    raw = organization_id if organization_id is not None else os.environ.get(_ORGANIZATION_ID_ENV_VAR)
+    if raw is None:
+        return None
+    stripped = raw.strip()
+    return stripped 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.

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

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import Any, AsyncIterator, Dict, Iterator, List, Literal, Optional, Union
 from urllib.parse import quote
 
+from ._agent_run_request import resolve_agent_run_session_id
 from ._exceptions import ModusError, RunCancelledError, StreamTimeoutError
 from ._generated.models import SkillChatRequestDto, SkillChatResponseDto
 from ._http import AsyncHttpClient, HttpClient
@@ -34,6 +35,11 @@ def _effective_thread_id(thread_id: Optional[str]) -> Optional[str]:
     return thread_id
 
 
+def _resolve_session_id(thread_id: Optional[str]) -> str:
+    """Agent-host runs always require sessionId — reuse thread_id or mint a UUID."""
+    return resolve_agent_run_session_id(_effective_thread_id(thread_id))
+
+
 def _chat_path(
     resource: str,
     resource_id: Union[int, str],
@@ -82,28 +88,35 @@ def _agent_runs_body(
     message: str,
     model: str,
     *,
-    session_id: Optional[str] = None,
+    session_id: str,
+    organization_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"``.
+        message:          The user message.
+        model:            Model id, e.g. ``"claude-sonnet-5"``.
+        session_id:       Conversation/session ID (always required by agent-host).
+        organization_id:  Optional Clerk org id; omit to let the server use the PAT org.
+        version:          Run a specific variation — ``"published"`` or ``"draft"``.
     """
     body: Dict[str, Any] = {
         "message": message,
         "config": {"model": model},
+        "sessionId": session_id,
     }
-    if session_id is not None:
-        body["sessionId"] = session_id
+    if organization_id is not None:
+        body["organizationId"] = organization_id
     if version is not None:
         body["version"] = version
     return body
 
 
+def _org_from_http(http: Union[HttpClient, AsyncHttpClient]) -> Optional[str]:
+    return getattr(http.config, "organization_id", None)
+
+
 def _raise_for_event(event: RunEvent) -> RunEvent:
     if isinstance(event, ErrorEvent):
         raise ModusError(event.message)
@@ -318,9 +331,13 @@ def modus_stream_session(
 ) -> 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)
+    body = _agent_runs_body(
+        message,
+        model,
+        session_id=_resolve_session_id(thread_id),
+        organization_id=_org_from_http(agent_http),
+    )
     return ChatStream(agent_http, path, body)
 
 
@@ -333,9 +350,13 @@ def modus_stream_session_async(
 ) -> 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)
+    body = _agent_runs_body(
+        message,
+        model,
+        session_id=_resolve_session_id(thread_id),
+        organization_id=_org_from_http(agent_http),
+    )
     return AsyncChatStream(agent_http, path, body)
 
 
@@ -351,9 +372,14 @@ def scope_stream_session(
     """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)
+    body = _agent_runs_body(
+        message,
+        model,
+        session_id=_resolve_session_id(thread_id),
+        organization_id=_org_from_http(agent_http),
+        version=version,
+    )
     return ChatStream(agent_http, path, body)
 
 
@@ -369,9 +395,14 @@ def scope_stream_session_async(
     """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)
+    body = _agent_runs_body(
+        message,
+        model,
+        session_id=_resolve_session_id(thread_id),
+        organization_id=_org_from_http(agent_http),
+        version=version,
+    )
     return AsyncChatStream(agent_http, path, body)
 
 
@@ -387,9 +418,14 @@ def workflow_stream_session(
     """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)
+    body = _agent_runs_body(
+        message,
+        model,
+        session_id=_resolve_session_id(thread_id),
+        organization_id=_org_from_http(agent_http),
+        version=version,
+    )
     return ChatStream(agent_http, path, body)
 
 
@@ -405,7 +441,12 @@ def workflow_stream_session_async(
     """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)
+    body = _agent_runs_body(
+        message,
+        model,
+        session_id=_resolve_session_id(thread_id),
+        organization_id=_org_from_http(agent_http),
+        version=version,
+    )
     return AsyncChatStream(agent_http, path, body)

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

@@ -16,9 +16,16 @@ from ._auth import (
     resolve_api_key,
     resolve_base_url,
     resolve_max_retries,
+    resolve_organization_id,
     resolve_timeout,
 )
-from ._config import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, ModusConfig
+from ._config import (
+    DEFAULT_AGENT_HOST,
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    ModusConfig,
+)
 from ._http import AsyncHttpClient, HttpClient
 from .resources import (
     AsyncConnectionsResource,
@@ -47,11 +54,13 @@ class Modus:
         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``.
+                     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.
@@ -81,13 +90,20 @@ class Modus:
         *,
         base_url: Optional[str] = None,
         agent_host: Optional[str] = None,
+        organization_id: 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)
+        # Same precedence as TS: base_urls['agent-service'] drives streaming too.
+        resolved_agent_host = (
+            (base_urls or {}).get("agent-service")
+            or resolve_agent_host(agent_host)
+            or DEFAULT_AGENT_HOST
+        )
+        resolved_org = resolve_organization_id(organization_id)
         _t = resolve_timeout(timeout)
         resolved_timeout = _t if _t is not None else DEFAULT_TIMEOUT
         resolved_retries = resolve_max_retries(max_retries)
@@ -99,22 +115,20 @@ class Modus:
             timeout=resolved_timeout,
             max_retries=resolved_retries,
             agent_host=resolved_agent_host,
+            organization_id=resolved_org,
             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
+        _agent_config = ModusConfig(
+            api_key=resolved_key,
+            base_url=resolved_agent_host,
+            timeout=resolved_timeout,
+            max_retries=resolved_retries,
+            agent_host=resolved_agent_host,
+            organization_id=resolved_org,
+        )
+        self._agent_http: HttpClient = HttpClient(_agent_config)
 
         self.scopes: ScopesResource = ScopesResource(self._http, self._agent_http, self._config)
         self.modus: ModusResource = ModusResource(self._http, self._agent_http, self._config)
@@ -148,11 +162,11 @@ class AsyncModus:
     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``.
+                     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.
@@ -176,13 +190,20 @@ class AsyncModus:
         *,
         base_url: Optional[str] = None,
         agent_host: Optional[str] = None,
+        organization_id: 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)
+        # Same precedence as TS: base_urls['agent-service'] drives streaming too.
+        resolved_agent_host = (
+            (base_urls or {}).get("agent-service")
+            or resolve_agent_host(agent_host)
+            or DEFAULT_AGENT_HOST
+        )
+        resolved_org = resolve_organization_id(organization_id)
         _t = resolve_timeout(timeout)
         resolved_timeout = _t if _t is not None else DEFAULT_TIMEOUT
         resolved_retries = resolve_max_retries(max_retries)
@@ -194,20 +215,19 @@ class AsyncModus:
             timeout=resolved_timeout,
             max_retries=resolved_retries,
             agent_host=resolved_agent_host,
+            organization_id=resolved_org,
             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
+        _agent_config = ModusConfig(
+            api_key=resolved_key,
+            base_url=resolved_agent_host,
+            timeout=resolved_timeout,
+            max_retries=resolved_retries,
+            agent_host=resolved_agent_host,
+            organization_id=resolved_org,
+        )
+        self._agent_http: AsyncHttpClient = AsyncHttpClient(_agent_config)
 
         self.scopes: AsyncScopesResource = AsyncScopesResource(
             self._http, self._agent_http, self._config

{modus_sdk-0.2.0 → modus_sdk-0.2.3}/modus/_config.py

@@ -13,8 +13,9 @@ from typing import Mapping, Optional, Union
 
 import httpx
 
-# Defaults — override via Modus(base_url=..., timeout=..., max_retries=...)
-DEFAULT_BASE_URL = "https://api.modus.com"
+# Defaults — override via Modus(base_url=..., agent_host=..., timeout=..., max_retries=...)
+DEFAULT_BASE_URL = "https://api.getmodus.com"
+DEFAULT_AGENT_HOST = "https://agent.getmodus.com"
 
 
 def _default_timeout() -> httpx.Timeout:
@@ -48,6 +49,7 @@ class ModusConfig:
     timeout: Union[float, httpx.Timeout] = field(default_factory=_default_timeout)
     max_retries: int = DEFAULT_MAX_RETRIES
     agent_host: Optional[str] = None
+    organization_id: Optional[str] = None
     base_urls: Mapping[str, str] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
@@ -62,6 +64,8 @@ class ModusConfig:
         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))
+        if self.organization_id is not None:
+            object.__setattr__(self, "organization_id", self.organization_id.strip() or None)
         object.__setattr__(self, "base_urls", _normalize_base_urls(self.base_urls))
 
     def __repr__(self) -> str:

{modus_sdk-0.2.0 → modus_sdk-0.2.3}/modus/_exceptions.py

@@ -68,7 +68,7 @@ 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.
+    Create a token at app.getmodus.com → Settings → API Tokens.
     """
     def __init__(self, message: str, **kwargs: Any) -> None:
         super().__init__(message, status_code=401, **kwargs)