modus-sdk 0.2.2__tar.gz → 0.3.0__tar.gz

modus_sdk-0.3.0/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+**Current release:** [`0.3.0`](https://pypi.org/project/modus-sdk/0.3.0/).
+
+
+
+## [0.3.0] — 2026-07-26
+
+> Breaking surface vs `0.2.x` (pre-1.0 minor bump). See `distribution/docs/COMPATIBILITY.md`.
+
+### Added
+
+- `mgmt.usage.list()` / `list_async()` gain an optional `user_email` filter (repeated query param).
+- `mgmt.usage.list_users(since, until)` (sync + async) — distinct acting-user emails observed in the window.
+
+### Deprecated
+
+- **`Skill` / `Agent` type names** — use `Scope` / `Workflow` (and `ScopeStatus` / `WorkflowStatus`, `WorkflowType`, etc.). `Skill` and `Agent` remain as aliases.
+- **`conversation_skill_id()`** — use `conversation_scope_id()`.
+
+### Changed
+
+- SDK read types are now exported as `Scope` / `Workflow` backed by generated `ScopeDto` / `WorkflowDto`.
+- Custom context create responses always expose `.uid` (same value as `contextItemId`).
+
+### Removed
+
+- Dual list/deploy envelopes — responses use `scopes` / `workflows` and `scope` / `workflow` only (no `skills` / `agents` / `skill` / `agent` aliases).
+- Public Python type aliases **`SkillDto` / `AgentDto`** — use `ScopeDto` / `WorkflowDto` (thin `Skill` / `Agent` aliases remain).
+- Conversation `kind=skills` — use `kind=scopes` (`all` | `modus` | `scopes`).
+- `ModusManagement.organization.delete()` — organization deletion is no longer
+  part of the public API / PAT surface (SPA-only).
+- `GET /api/v1/users/member-groups` and `/org-members` no longer advertise `pageSize` /
+  `pageToken` query params or an always-`None` `next_page_token` response field (OpenAPI /
+  Management MCP surface — `ModusManagement.users.list_member_groups()` /
+  `list_org_members()` never exposed either). Both endpoints return the full org-bounded
+  roster; pagination was never honored server-side.
+
+### Fixed
+
+- `examples/apps/modus_skill_chat/app.py` called the removed `client.skills` accessor
+  (raised `AttributeError`); switched to `client.scopes.chat()` / `chat_stream()`.
+
+## [Unreleased]
+
+## [0.2.3] — 2026-07-20
+
+### Fixed
+
+- Streaming requests send `Accept: text/event-stream`; a non-SSE response (e.g. JSON polling body) raises `ModusError` instead of being silently treated as an empty stream.
+- `runs.create()` / `create_modus()` / `create_scope()` / `resume()` always mint (or reuse) a `sessionId`, matching `chat_stream`'s existing behavior.
+
+## [0.2.2] — 2026-07-20
+
+### Fixed
+
+- Streaming always sends `sessionId` (thread id or generated UUID) on agent-host runs.
+- Optional `organization_id` / `MODUS_ORGANIZATION_ID` for stream bodies; agent-service accepts omitted org and uses the PAT principal.
+- Default API/agent hosts are `*.getmodus.com` (no longer `*.modus.com`).
+- `base_urls['agent-service']` drives the streaming agent-host client (parity with TypeScript).
+
+### Added
+
+- Create responses expose `.uid` as an alias of `context_item_id`.
+
+## [0.2.0] — 2026-07-20
+
+### Added
+
+- **`modus.Modus` / `AsyncModus`** — read and invoke: scopes, workflows, context, connections, Modus assistant chat, runs, suggestions.
+- **`modus.management.ModusManagement` / `AsyncModusManagement`** — configure: CRUD, deploy, context creators, usage, org admin, scope evaluations.
+- Canonical **`client.scopes` / `client.workflows`** (and management equivalents) against `/api/v1/scopes` and `/api/v1/workflows`.
+- **`client.modus`** — org-wide Modus assistant (`chat`, `chat_stream`, `get_context`, `conversations`).
+- **`client.suggestions`** — list approved suggested questions; record impression/click/dismiss events.
+- **`client.workflows.runs.active()` / `active_by_session(...)`** — list or look up active conversation runs.
+- **`mgmt.scopes.evaluations(scope_id)`** — evaluation config, manual trigger, run history.
+- Bounded conversation windows via optional `message_limit` / `before_message_index` on `conversations(...).get()`.
+- MCP **`get_context_data`** batch + ACL: `{ items: [{ itemId, field?, mode?, limit? }, …], sessionId? }` → `{ results: [...] }` (max 20; per-item partial failures).
+- Cursor pagination, retries on 429/5xx, SSE streaming chat.
+- Full public OpenAPI operation coverage (contract-tested).
+
+### Changed
+
+- Public surface uses **Scope** / **Workflow** vocabulary (types remain `Skill` / `Agent` where the API still uses those names).
+- Scope-run helper: `client.workflows.runs.create_scope(scope_id, body)` (not `create_skill`).
+
+### Removed
+
+- Legacy **`client.skills` / `client.agents`** accessors (and management equivalents).

{modus_sdk-0.2.2 → modus_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modus-sdk
-Version: 0.2.2
+Version: 0.3.0
 Summary: Official Python client for Modus — your organization's context layer for AI
 License: MIT
 License-File: LICENSE

{modus_sdk-0.2.2 → modus_sdk-0.3.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.2 → modus_sdk-0.3.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.2 → modus_sdk-0.3.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.3.0/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.2 → modus_sdk-0.3.0}/modus/_chat.py

@@ -2,10 +2,10 @@
 
 from __future__ import annotations
 
-import uuid
 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
@@ -37,8 +37,7 @@ def _effective_thread_id(thread_id: Optional[str]) -> Optional[str]:
 
 def _resolve_session_id(thread_id: Optional[str]) -> str:
     """Agent-host runs always require sessionId — reuse thread_id or mint a UUID."""
-    tid = _effective_thread_id(thread_id)
-    return tid if tid is not None else str(uuid.uuid4())
+    return resolve_agent_run_session_id(_effective_thread_id(thread_id))
 
 
 def _chat_path(

{modus_sdk-0.2.2 → modus_sdk-0.3.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,
     )

{modus_sdk-0.2.2 → modus_sdk-0.3.0}/modus/_generated/__init__.py

@@ -10,7 +10,6 @@ from .models import (
     AddAgentInterfaceDto,
     AgentAccessConfigDto,
     AgentDeployResponseDto,
-    AgentDto,
     AgentGroupPermissionDto,
     AgentInterfaceDto,
     AgentInterfaceType,
@@ -94,6 +93,7 @@ from .models import (
     ListSkillsResponseDto,
     ListSuggestionQuestionsResponseDto,
     ListUsageResponseDto,
+    ListUsageUsersResponseDto,
     LookupContextItemDto,
     LookupContextItemResponseDto,
     LookupContextItemRowDto,
@@ -121,13 +121,13 @@ from .models import (
     RunReasoningEffort,
     RunSource,
     Scope,
+    ScopeDto,
     SearchMemoriesRequestDto,
     SetSupervisionRequestDto,
     SharedUserDto,
     SharedUserPermission,
     SkillChatRequestDto,
     SkillChatResponseDto,
-    SkillDto,
     SkillMcpInterfaceConfigDto,
     SkillRunDto,
     SkillVariationDto,
@@ -156,6 +156,7 @@ from .models import (
     UpdateSkillDto,
     UsageBucketDto,
     UsageTotalsDto,
+    UsageUserDto,
     UserContextDto,
     UserFeedback,
     Version,
@@ -163,6 +164,7 @@ from .models import (
     Weekday,
     WorkflowActionDto,
     WorkflowActionSource,
+    WorkflowDto,
     WorkflowEdgeDto,
     WorkflowNodeDto,
     WorkflowNodePositionDto,
@@ -180,7 +182,6 @@ __all__ = [
     "AddAgentInterfaceDto",
     "AgentAccessConfigDto",
     "AgentDeployResponseDto",
-    "AgentDto",
     "AgentGroupPermissionDto",
     "AgentInterfaceDto",
     "AgentInterfaceType",
@@ -264,6 +265,7 @@ __all__ = [
     "ListSkillsResponseDto",
     "ListSuggestionQuestionsResponseDto",
     "ListUsageResponseDto",
+    "ListUsageUsersResponseDto",
     "LookupContextItemDto",
     "LookupContextItemResponseDto",
     "LookupContextItemRowDto",
@@ -291,13 +293,13 @@ __all__ = [
     "RunReasoningEffort",
     "RunSource",
     "Scope",
+    "ScopeDto",
     "SearchMemoriesRequestDto",
     "SetSupervisionRequestDto",
     "SharedUserDto",
     "SharedUserPermission",
     "SkillChatRequestDto",
     "SkillChatResponseDto",
-    "SkillDto",
     "SkillMcpInterfaceConfigDto",
     "SkillRunDto",
     "SkillVariationDto",
@@ -326,6 +328,7 @@ __all__ = [
     "UpdateSkillDto",
     "UsageBucketDto",
     "UsageTotalsDto",
+    "UsageUserDto",
     "UserContextDto",
     "UserFeedback",
     "Version",
@@ -333,6 +336,7 @@ __all__ = [
     "Weekday",
     "WorkflowActionDto",
     "WorkflowActionSource",
+    "WorkflowDto",
     "WorkflowEdgeDto",
     "WorkflowNodeDto",
     "WorkflowNodePositionDto",