feat!: realign SDK with platform API (1.0.0)

Major, breaking release bringing the SDK back in line with the current
platform. Verified: ruff + mypy clean, 124 tests passing.

Core:
- Fix SSE event dispatch: normalize event name from data["type"] (B-group
  streams) / event: field (A-group); terminal-event stop; heartbeat filter;
  typed connect errors.
- Structured 402/billing denial mapping (BillingError + Payment/Quota/Credit/
  Wallet subclasses); RateLimitError carries limit/remaining/reset.
- _paginate supports page / offset (has_next|has_more|total) / cursor styles
  and nested data.<items> envelopes.
- Pydantic v2 base (ModulexModel) + AsyncPage[T]; declare typing-extensions.
- Packaging: version 1.0.0, Production classifier, CI on dev/staging,
  User-Agent header, env-var config, Idempotency-Key; remove dead _compat.

Resources:
- composer: chat(llm=dict) fix, resume() HITL, set_focus(), list(); drop history().
- executions: drop llm(410)/knowledge_config, add attribution_workflow_id +
  idempotency_key; add list_runs/iter_runs/get_run (/workflow-runs).
- assistant: new resource (8 endpoints, HITL) sharing realtime models.
- credentials: OAuth2 initiate/refresh + create(oauth_config=).
- organizations: preview_invite, get_settings, set_llm_model_visibility,
  set_composer_llm.

Types: all domains migrated TypedDict -> Pydantic v2; methods return typed
models (dict-style access preserved via shim; unknown fields kept).

Removed: templates resource, system.metrics, api_keys.is_revoked.

Docs: README + CHANGELOG updated for the new typed surface.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sezeryavuz

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, dev, staging]
   pull_request:
-    branches: [main]
+    branches: [main, dev, staging]
 
 jobs:
   test:

CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to the ModuleX Python SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] - 2026-06-19
+
+Major release realigning the SDK with the current platform API. **Breaking.**
+
+### Added
+
+- **`assistant` resource** — agentic standard chat (chat/get/list/listen/resume/cancel/status/delete) with HITL.
+- **Composer HITL** — `composer.resume()`, `composer.set_focus()`, `composer.list()`; `composer.chat(llm=...)` now takes a provider-config dict (`ComposerLLMConfig`).
+- **Execution history** — `executions.list_runs()`, `executions.iter_runs()` (typed `AsyncPage`), `executions.get_run()`; `executions.run(idempotency_key=...)` and `attribution_workflow_id`.
+- **Credentials OAuth2** — `initiate_oauth2()`, `refresh_oauth2()`, and `create(oauth_config=...)`.
+- **Organization settings** — `preview_invite()`, `get_settings()`, `set_llm_model_visibility()`, `set_composer_llm()`.
+- **Structured billing errors** — `BillingError` + `PaymentRequiredError`/`QuotaExceededError`/`CreditExhaustedError`/`WalletError` (402/403/429) exposing `code`/`layer`/`key`/`current`/`limit`/`reason`; `RateLimitError` now carries `limit`/`remaining`/`reset`.
+- **Typed responses** — every method returns a Pydantic v2 model (`ModulexModel`); dict-style access still works; unknown backend fields are preserved.
+- Environment-variable config (`MODULEX_API_KEY`/`MODULEX_BASE_URL`/`MODULEX_ORGANIZATION_ID`), `User-Agent` header, `default_headers`, `Idempotency-Key` support.
+
+### Changed
+
+- **SSE event dispatch fixed** — `event.event` is normalized from `data["type"]`, so workflow/composer/assistant streams dispatch correctly; terminal events stop iteration; heartbeats filtered.
+- `_paginate` now supports page / offset (`has_next`|`has_more`|`total`) / cursor styles and nested `data.<items>` envelopes.
+- All response types migrated from `TypedDict` to Pydantic v2 models, aligned field-by-field with the backend.
+
+### Removed
+
+- **`templates` resource** (removed from the platform).
+- `system.metrics()` (endpoint no longer exists), composer workflow-`history()` (deprecated), `ApiKeyResponse.is_revoked`, the unused sync `_compat.run_sync` shim, and the removed `/workflows/run` `llm`/`knowledge_config` parameters.
+
 ## [0.1.0] - 2026-03-09
 
 ### Added

README.md

@@ -113,43 +113,46 @@ result = await client.executions.run(
     workflow_id="workflow-uuid",
     input={"messages": [{"role": "user", "content": "Hello!"}]},
 )
+print(result.run_id)  # typed attribute access (responses are Pydantic models)
 
-# Direct LLM call
+# Safely retry a run without double-execution
 result = await client.executions.run(
-    llm={
-        "integration_name": "openai",
-        "provider_id": "openai",
-        "model_id": "gpt-4o-mini",
-        "temperature": 0.4,
-    },
-    input={"messages": [{"role": "user", "content": "Hello!"}]},
+    workflow_id="workflow-uuid",
+    input={"messages": [...]},
+    idempotency_key="order-4823",  # stable key across retries
 )
 
-# Get execution state
+# Get execution state / resume after interrupt / cancel
 state = await client.executions.get_state(thread_id="thread-uuid")
-
-# Resume after interrupt
-await client.executions.resume(
-    thread_id="thread-uuid",
-    run_id="run-uuid",
-    resume_value="user input",
-)
-
-# Cancel execution
+await client.executions.resume(thread_id="thread-uuid", run_id="run-uuid", resume_value="user input")
 await client.executions.cancel(run_id="run-uuid", reason="No longer needed")
+
+# Run history (workflow-runs)
+runs = await client.executions.list_runs(workflow_id="workflow-uuid", limit=50)
+async for run in client.executions.iter_runs(status="succeeded"):  # auto-paginates
+    print(run.run_id, run.status)
+detail = await client.executions.get_run(run_pk="run-row-id")
 ```
 
+> Agentic ("direct LLM") chat moved off `/workflows/run` — use `client.assistant.chat(...)` instead.
+
 ### SSE Streaming
 
+The backend carries the event type in the SSE `event:` field for `/chats/stream`, and in the JSON
+`data["type"]` for workflow/composer/assistant streams. The SDK normalizes both, so `event.event`
+always holds the logical type. Streams stop after a terminal event (`done`/`error`/`cancelled`/
+`interrupted`) and heartbeats are filtered by default.
+
 ```python
 # Listen to workflow execution events
 async for event in client.executions.listen(run_id="run-uuid"):
     if event.event == "node_update":
-        print(f"Node {event.data['node_id']}: {event.data['status']}")
-    elif event.event == "done":
-        print(f"Completed in {event.data['total_execution_time_ms']}ms")
-    elif event.event == "error":
-        print(f"Error: {event.data['error_message']}")
+        print(f"Node {event.data['node']}: {event.data.get('output')}")
+    elif event.event == "interrupt":
+        payload = event.data["data"]  # InterruptEventData is nested under data["data"]
+        print(f"Needs input: {payload.get('message')}")
+    elif event.is_terminal:
+        print(f"Stream ended: {event.event}")
 
 # Listen to chat list updates
 async for event in client.chats.stream():
@@ -237,20 +240,6 @@ runs = await client.schedules.list_runs(schedule["id"])
 stats = await client.schedules.run_stats(schedule["id"], days=30)
 ```
 
-### Templates
-
-```python
-# Browse templates
-templates = await client.templates.list()
-
-# Use a template
-result = await client.templates.use("template-id")
-print(f"Created workflow: {result['workflow']['id']}")
-
-# Like a template
-await client.templates.like("template-id")
-```
-
 ### Deployments
 
 ```python
@@ -269,23 +258,48 @@ await client.deployments.deactivate("workflow-uuid")
 
 ### Composer
 
+`llm` is a provider config dict ({integration_name, provider_id, model_id, credential_id?}) — pass a
+`ComposerLLMConfig` or an equivalent dict.
+
 ```python
-# Start a composer session
+from modulex.types import ComposerLLMConfig, YesNoResponse, user_input_request_from_event
+
 result = await client.composer.chat(
     message="Add an LLM node that summarizes the input",
     workflow_id="workflow-uuid",
-    llm={"integration_name": "anthropic", "model_id": "claude-sonnet-4-20250514"},
+    llm=ComposerLLMConfig(integration_name="anthropic", provider_id="anthropic", model_id="claude-sonnet-4-20250514"),
 )
 
-# Listen to composer events
-async for event in client.composer.listen(result["composer_chat_id"], result["run_id"]):
-    if event.event == "workflow_change":
-        print(f"Workflow modified: {event.data}")
-    elif event.event == "done":
+# Listen, and answer a human-in-the-loop question (HITL) when the run pauses
+async for event in client.composer.listen(result.composer_chat_id, result.run_id):
+    if event.event == "user_input_request":
+        question = user_input_request_from_event(event.data)  # typed UserInputRequest
+        await client.composer.resume(
+            result.composer_chat_id,
+            request_id=question.request_id,
+            response=YesNoResponse(answer=True),
+            llm={"integration_name": "anthropic", "provider_id": "anthropic", "model_id": "claude-sonnet-4-20250514"},
+        )  # returns a NEW run_id — re-subscribe with listen() on it
+    elif event.is_terminal:
         break
 
-# Save or revert changes
-await client.composer.save(result["composer_chat_id"])
+chats = await client.composer.list(limit=20)        # cursor-paginated
+await client.composer.save(result.composer_chat_id)  # or .revert(...)
+```
+
+### Assistant (agentic chat)
+
+Shares the HITL contract with the composer. All endpoints are available to any org member.
+
+```python
+result = await client.assistant.chat("Summarize my latest runs", llm=ComposerLLMConfig(
+    integration_name="openai", provider_id="openai", model_id="gpt-4o-mini",
+))
+async for event in client.assistant.listen(result.chat_id, result.run_id):
+    if event.event == "response_chunk":
+        print(event.data.get("data", {}).get("text", ""), end="")
+    elif event.is_terminal:
+        break
 ```
 
 ### Other Resources
@@ -338,7 +352,7 @@ try:
 except NotFoundError:
     print("Workflow not found")
 except RateLimitError as e:
-    print(f"Rate limited. Retry after {e.retry_after}s")
+    print(f"Rate limited. Retry after {e.retry_after}s (limit={e.limit}, remaining={e.remaining})")
 except AuthenticationError:
     print("Invalid API key")
 except ValidationError as e:
@@ -347,13 +361,28 @@ except ModulexError as e:
     print(f"API error ({e.status_code}): {e.message}")
 ```
 
+Usage/billing denials (quota, credit, wallet) are surfaced structurally via `BillingError` and its
+subclasses, which expose `code`, `layer`, `key`, `current`, `limit`, and `reason`:
+
+```python
+from modulex import BillingError, CreditExhaustedError
+
+try:
+    await client.executions.run(workflow_id="wf")
+except CreditExhaustedError as e:           # 402, layer="credit"
+    print(f"Out of credits: {e.current}/{e.limit}")
+except BillingError as e:                   # any quota/credit/wallet denial
+    print(f"Denied ({e.layer}/{e.code}): {e.reason}")
+```
+
 ### Exception Hierarchy
 
 | Exception | HTTP Status | Description |
 |-----------|-------------|-------------|
 | `ModulexError` | — | Base exception |
 | `BadRequestError` | 400 | Malformed request |
 | `AuthenticationError` | 401 | Invalid/missing auth |
+| `PaymentRequiredError` | 402 | Payment required (billing) |
 | `PermissionError` | 403 | Insufficient permissions |
 | `NotFoundError` | 404 | Resource not found |
 | `ConflictError` | 409 | Resource conflict |
@@ -362,12 +391,18 @@ except ModulexError as e:
 | `InternalError` | 500 | Server error |
 | `ExternalServiceError` | 502 | External service failure |
 | `ServiceUnavailableError` | 503 | Service unavailable |
+| `BillingError` | 402/403/429 | Usage denial (base) — `code`/`layer`/`reason` |
+| `QuotaExceededError` | 403 | Quota exceeded (`layer="quota"`) |
+| `CreditExhaustedError` | 402 | Credit plan exhausted (`layer="credit"`) |
+| `WalletError` | 402 | Wallet overage denied (`layer="wallet"`) |
 | `StreamError` | — | SSE stream error |
 | `TimeoutError` | — | Request timeout |
 
 ## Type Hints
 
-All types are available for import:
+Responses are **Pydantic v2 models** — use typed attribute access (`result.id`) or, for
+compatibility, dict-style access (`result["id"]`). Unknown fields the backend may add are preserved.
+All models are importable:
 
 ```python
 from modulex import SSEEvent
@@ -377,6 +412,8 @@ from modulex.types import (
     EdgeDefinition,
     LLMConfig,
     RunResponse,
+    AsyncPage,        # typed auto-pagination (e.g. executions.iter_runs)
+    ModulexModel,     # base class for all response models
 )
 ```
 

examples/streaming_example.py

@@ -1,4 +1,10 @@
-"""Detailed SSE streaming example with all event types."""
+"""Detailed SSE streaming example with all event types.
+
+The backend emits workflow/composer/assistant events as raw ``data: {"type": ...}``
+frames (no SSE ``event:`` line). The SDK normalizes this so ``event.event`` carries
+the logical type. Note the nesting: ``interrupt`` and ``error`` carry their payload
+under ``event.data["data"]``, while ``node_update``/``done`` fields are root-level.
+"""
 
 import asyncio
 
@@ -9,14 +15,13 @@ async def handle_workflow_events(client: Modulex, run_id: str) -> None:
     """Handle all SSE event types from workflow execution."""
     async for event in client.executions.listen(run_id):
         if event.event == "metadata":
-            print(f"[META] Workflow: {event.data.get('workflow_name')} v{event.data.get('workflow_version')}")
-            nodes = event.data.get("nodes", [])
-            print(f"  Nodes: {len(nodes)}")
+            print(f"[META] workflow_type={event.data.get('workflow_type')}")
 
         elif event.event == "node_update":
+            # node_update fields are root-level (no "data" wrapper).
             node_id = event.data.get("node_id")
             node_type = event.data.get("node_type")
-            status = event.data.get("status")
+            status = event.data.get("status")  # started | completed | error
             time_ms = event.data.get("execution_time_ms")
 
             if status == "started":
@@ -27,28 +32,34 @@ async def handle_workflow_events(client: Modulex, run_id: str) -> None:
                 print(f"  [{node_type}] {node_id} FAILED: {event.data.get('error')}")
 
         elif event.event == "interrupt":
-            print(f"\n[INTERRUPT] {event.data.get('message')}")
-            print(f"  Node: {event.data.get('node_id')}")
-            print(f"  Instructions: {event.data.get('resume_instructions')}")
-
-        elif event.event == "resumed":
-            print(f"[RESUMED] Thread: {event.data.get('thread_id')}")
+            # InterruptEventData is nested under data["data"].
+            payload = event.data.get("data", {})
+            print(f"\n[INTERRUPT] {payload.get('message')}")
+            print(f"  Node: {payload.get('node_id')}")
+            print(f"  Instructions: {payload.get('resume_instructions')}")
 
         elif event.event == "done":
+            # Terminal event — the stream stops after this. Fields are root-level.
             print(f"\n[DONE] Steps: {event.data.get('steps_executed')}")
             print(f"  Total time: {event.data.get('total_execution_time_ms')}ms")
 
         elif event.event == "error":
-            print(f"\n[ERROR] {event.data.get('error_type')}: {event.data.get('error_message')}")
-            if event.data.get("node_id"):
-                print(f"  At node: {event.data['node_id']}")
+            # ErrorEventData is nested under data["data"]. Terminal event.
+            payload = event.data.get("data", {})
+            print(f"\n[ERROR] {payload.get('error_type')}: {payload.get('error_message')}")
+            if payload.get("node_id"):
+                print(f"  At node: {payload['node_id']}")
+
+        elif event.event == "cancelled":
+            # Terminal — fields are root-level.
+            print(f"\n[CANCELLED] reason={event.data.get('reason')}")
 
         else:
             print(f"[{event.event}] {event.data}")
 
 
 async def handle_chat_stream(client: Modulex) -> None:
-    """Listen for real-time chat list updates."""
+    """Listen for real-time chat list updates (A-group: real SSE event: names)."""
     async for event in client.chats.stream():
         if event.event == "connected":
             print("Connected to chat stream")
@@ -61,13 +72,11 @@ async def main() -> None:
         api_key="mx_live_your_api_key_here",
         organization_id="your-org-id",
     ) as client:
-        # Run a workflow
+        # Run a workflow, then listen to its event stream.
         result = await client.executions.run(
             workflow_id="your-workflow-id",
             input={"messages": [{"role": "user", "content": "Analyze this data"}]},
         )
-
-        # Handle all events
         await handle_workflow_events(client, result["run_id"])
 
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modulex-python"
-version = "0.1.0"
+version = "1.0.0"
 description = "Official Python SDK for the ModuleX AI workflow orchestration platform"
 readme = "README.md"
 license = "MIT"
@@ -14,7 +14,7 @@ authors = [
 ]
 keywords = ["modulex", "ai", "workflow", "orchestration", "sdk"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
@@ -29,6 +29,8 @@ classifiers = [
 dependencies = [
     "httpx>=0.27",
     "httpx-sse>=0.4",
+    "pydantic>=2.7",
+    "typing-extensions>=4.10",
 ]
 
 [project.optional-dependencies]
@@ -68,6 +70,13 @@ line-length = 120
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "W", "UP"]
 
+[tool.ruff.lint.per-file-ignores]
+# Pydantic models evaluate their annotations at runtime to build fields. On
+# Python 3.9 the PEP 604 `X | None` syntax raises TypeError when eval'd, so the
+# response-model files must keep explicit Optional/Union — exempt the whole
+# types/ package from the UP (pyupgrade) modernizers.
+"src/modulex/types/*.py" = ["UP"]
+
 [tool.mypy]
 python_version = "3.9"
 strict = true