threadify-sdk 0.2.7__tar.gz → 0.2.9__tar.gz

{threadify_sdk-0.2.7/threadify_sdk.egg-info → threadify_sdk-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadify-sdk
-Version: 0.2.7
+Version: 0.2.9
 Summary: Python SDK for Threadify — Service-delivery intelligence. Track every customer request from start to finish across every system, team, and partner. Visit: https://threadify.dev
 Author-email: Threadify Team <team@threadify.dev>
 License: MIT
@@ -63,7 +63,14 @@ async def main():
         return
 
     try:
-        thread = await conn.start("Order-123")
+        thread = await conn.start(
+            contract_name="order_processing",
+            role="customer",
+            refs={"order_id": "ORD-123"},
+            tags=["priority"],
+        )
+
+        await thread.add_refs({"crm_id": "CRM-456"})
         
         # Easy chaining!
         await (
@@ -130,6 +137,22 @@ thread = await conn.join(
 )
 ```
 
+### Start options
+
+`Connection.start(...)` supports named options for contract, role, refs, and tags, while preserving the older positional forms:
+
+```python
+thread = await conn.start(
+    contract_name="order_processing",
+    role="customer",
+    refs={"customer_id": "123"},
+    tags=["priority"],
+)
+thread = await conn.start("Order-123", "customer")
+thread = await conn.start({"customer_id": "123"}, "customer")
+thread = await conn.start("Order-123")  # contract is optional
+```
+
 ## Subscriptions
 
 Preferred API:

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9}/README.md

@@ -36,7 +36,14 @@ async def main():
         return
 
     try:
-        thread = await conn.start("Order-123")
+        thread = await conn.start(
+            contract_name="order_processing",
+            role="customer",
+            refs={"order_id": "ORD-123"},
+            tags=["priority"],
+        )
+
+        await thread.add_refs({"crm_id": "CRM-456"})
         
         # Easy chaining!
         await (
@@ -103,6 +110,22 @@ thread = await conn.join(
 )
 ```
 
+### Start options
+
+`Connection.start(...)` supports named options for contract, role, refs, and tags, while preserving the older positional forms:
+
+```python
+thread = await conn.start(
+    contract_name="order_processing",
+    role="customer",
+    refs={"customer_id": "123"},
+    tags=["priority"],
+)
+thread = await conn.start("Order-123", "customer")
+thread = await conn.start({"customer_id": "123"}, "customer")
+thread = await conn.start("Order-123")  # contract is optional
+```
+
 ## Subscriptions
 
 Preferred API:

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "threadify-sdk"
-version = "0.2.7"
+version = "0.2.9"
 description = "Python SDK for Threadify — Service-delivery intelligence. Track every customer request from start to finish across every system, team, and partner. Visit: https://threadify.dev"
 readme = "README.md"
 requires-python = ">=3.10"

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9}/tests/test_client.py

@@ -9,14 +9,21 @@ from threadify.models import ConnectOptions
 
 class TestThreadifyConnect:
     @pytest.mark.asyncio
-    async def test_requires_ws_url(self, monkeypatch):
-        ws_connect = AsyncMock(
-            side_effect=AssertionError("websockets.connect should not be called")
-        )
+    async def test_connect_uses_default_ws_url_when_not_provided(self, monkeypatch):
+        ws = AsyncMock()
+        ws.send = AsyncMock()
+        ws.recv = AsyncMock(return_value=json.dumps({"action": "connect", "status": "success"}))
+        ws.close = AsyncMock()
+
+        ws_connect = AsyncMock(return_value=ws)
         monkeypatch.setattr("threadify.client.websockets.connect", ws_connect)
 
-        with pytest.raises(ValueError, match="ws_url is required"):
-            await Threadify.connect("test-api-key", "test-service")
+        conn = await Threadify.connect("test-api-key", "test-service")
+
+        ws_connect.assert_awaited_once_with("wss://eng.threadify.dev/threads")
+        sent_msg = json.loads(ws.send.call_args.args[0])
+        assert sent_msg["serviceName"] == "test-service"
+        assert conn.is_connected is True
 
     @pytest.mark.asyncio
     async def test_connect_with_explicit_ws_url(self, monkeypatch):
@@ -64,6 +71,6 @@ class TestThreadifyConnect:
 
 
 class TestThreadifyFactory:
-    def test_create_requires_ws_url(self):
-        with pytest.raises(ValueError, match="ws_url is required"):
-            Threadify.create("test-api-key")
+    def test_create_uses_default_ws_url(self):
+        factory = Threadify.create("test-api-key")
+        assert factory._options.ws_url == "wss://eng.threadify.dev/threads"

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9}/tests/test_connection.py

@@ -36,6 +36,7 @@ def _make_connection():
     conn._notification_handlers = {}
     conn._active_subscriptions = {}
     conn._processed_notifications = set()
+    conn._processed_notifications_max_size = 10_000
     conn._recv_queue = asyncio.Queue()
     conn._data_retriever = None
     import logging
@@ -120,6 +121,105 @@ class TestConnectionProperties:
         assert conn.is_connected is True
 
 
+class TestStart:
+    @pytest.mark.asyncio
+    async def test_start_with_label_and_optional_contract(self):
+        conn = _make_connection()
+        conn._send = AsyncMock()
+        conn._wait_response = AsyncMock(
+            return_value={
+                "action": "startThread",
+                "status": "success",
+                "threadId": "thread-123",
+            }
+        )
+
+        thread = await conn.start("customer-123", "customer")
+
+        assert thread.thread_id == "thread-123"
+        assert thread.role == "test"
+        assert thread.refs["label"] == "customer-123"
+        assert thread.refs["serviceName"] == "test-service"
+        sent_msg = conn._send.call_args.args[0]
+        assert sent_msg["refs"]["label"] == "customer-123"
+        assert sent_msg["contractName"] == "customer"
+        assert sent_msg["role"] == "test"
+
+    @pytest.mark.asyncio
+    async def test_start_with_refs_and_contract(self):
+        conn = _make_connection()
+        conn._send = AsyncMock()
+        conn._wait_response = AsyncMock(
+            return_value={
+                "action": "startThread",
+                "status": "success",
+                "threadId": "thread-legacy-123",
+            }
+        )
+
+        thread = await conn.start(refs={"customer_id": "123"}, contract_name="customer")
+
+        assert thread.thread_id == "thread-legacy-123"
+        assert thread.refs["customer_id"] == "123"
+        assert thread.refs["serviceName"] == "test-service"
+        sent_msg = conn._send.call_args.args[0]
+        assert sent_msg["refs"]["customer_id"] == "123"
+        assert "label" not in sent_msg["refs"]
+        assert sent_msg["contractName"] == "customer"
+
+    @pytest.mark.asyncio
+    async def test_start_without_contract_still_works(self):
+        conn = _make_connection()
+        conn._send = AsyncMock()
+        conn._wait_response = AsyncMock(
+            return_value={
+                "action": "startThread",
+                "status": "success",
+                "threadId": "thread-no-contract-123",
+            }
+        )
+
+        thread = await conn.start("customer-123")
+
+        assert thread.thread_id == "thread-no-contract-123"
+        assert thread.refs["label"] == "customer-123"
+        assert thread.refs["serviceName"] == "test-service"
+        sent_msg = conn._send.call_args.args[0]
+        assert sent_msg["refs"]["label"] == "customer-123"
+        assert "contractName" not in sent_msg
+        assert "role" not in sent_msg
+
+    @pytest.mark.asyncio
+    async def test_start_accepts_keyword_config_options(self):
+        conn = _make_connection()
+        conn._send = AsyncMock()
+        conn._wait_response = AsyncMock(
+            return_value={
+                "action": "startThread",
+                "status": "success",
+                "threadId": "thread-options-123",
+            }
+        )
+
+        thread = await conn.start(
+            contract_name="order_processing",
+            role="merchant",
+            refs={"customer_id": "123"},
+            tags=["priority", "external"],
+        )
+
+        assert thread.thread_id == "thread-options-123"
+        assert thread.role == "merchant"
+        assert thread.tags == ["priority", "external"]
+        assert thread.refs["customer_id"] == "123"
+        assert thread.refs["serviceName"] == "test-service"
+        sent_msg = conn._send.call_args.args[0]
+        assert sent_msg["contractName"] == "order_processing"
+        assert sent_msg["role"] == "merchant"
+        assert sent_msg["refs"]["customer_id"] == "123"
+        assert sent_msg["tags"] == ["priority", "external"]
+
+
 class TestJoin:
     @pytest.mark.asyncio
     async def test_join_with_token_keyword(self):

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9}/tests/test_models.py

@@ -3,6 +3,7 @@ import pytest
 from threadify.models import (
     DEFAULT_CONNECT_TIMEOUT,
     DEFAULT_MAX_IN_FLIGHT,
+    DEFAULT_WS_URL,
     ConnectOptions,
     StepResult,
     StepStatus,
@@ -77,10 +78,10 @@ class TestConnectOptions:
     def test_defaults(self):
         opts = ConnectOptions()
         opts.with_defaults()
-        assert opts.ws_url == ""
+        assert opts.ws_url == DEFAULT_WS_URL
         assert opts.max_in_flight == DEFAULT_MAX_IN_FLIGHT
         assert opts.connect_timeout == DEFAULT_CONNECT_TIMEOUT
-        assert opts.graphql_url == ""
+        assert opts.graphql_url == derive_graphql_url(DEFAULT_WS_URL)
 
     def test_preserves_custom(self):
         opts = ConnectOptions(
@@ -100,7 +101,7 @@ class TestConnectOptions:
         opts2 = ConnectOptions(ws_url="wss://custom.com/threads", max_in_flight=100)
         opts2.validate()  # Should not raise.
 
-    def test_validate_requires_ws_url(self):
+    def test_validate_requires_non_empty_ws_url(self):
         opts = ConnectOptions(ws_url="")
         with pytest.raises(ValueError, match="ws_url is required"):
             opts.validate()

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9}/tests/test_step.py

@@ -24,9 +24,7 @@ class TestThreadStepFluent:
     def test_chaining(self):
         thread = _make_thread()
         step = ThreadStep("order_placed", thread, "test-svc")
-        result = step.add_context({"orderId": "ORD-1", "amount": "99.99"}).add_refs(
-            {"stripe": "pi_abc"}
-        )
+        result = step.add_context({"orderId": "ORD-1", "amount": "99.99"})
         assert result is step  # Fluent returns self.
         assert step.context == {"orderId": "ORD-1", "amount": "99.99"}
 
@@ -278,3 +276,4 @@ class TestStepProperties:
         assert data["action"] == "recordThreadEvent"
         assert data["stepName"] == "order_placed"
         assert data["threadId"] == "thread-001"
+        assert "refs" not in data

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9}/threadify/connection.py

@@ -20,6 +20,8 @@ from threadify.models import (
     ACTION_START_THREAD,
     ACTION_SUBSCRIBE,
     ACTION_UNSUBSCRIBE,
+    DEFAULT_PROCESSED_MAX_SIZE,
+    FIELD_ACCESS_LEVEL,
     FIELD_ACK_TOKEN,
     FIELD_ACTION,
     FIELD_CONTRACT_NAME,
@@ -35,11 +37,11 @@ from threadify.models import (
     FIELD_SERVICE_NAME,
     FIELD_STATUS,
     FIELD_STEP_NAME,
+    FIELD_TAGS,
     FIELD_THREAD_ID,
     FIELD_THREAD_ID_ACK,
     FIELD_THREAD_TOKEN,
     STATUS_SUCCESS,
-    DEFAULT_PROCESSED_MAX_SIZE,
     RefQuery,
     first_non_empty,
     require_non_empty,
@@ -144,6 +146,8 @@ class Connection:
         contract_name: str = "",
         service_name: str = "",
         refs: dict[str, Any] | None = None,
+        tags: list[str] | None = None,
+        role: str = "",
     ) -> ThreadInstance:
         from threadify.thread import ThreadInstance
 
@@ -152,27 +156,36 @@ class Connection:
 
         effective_service = first_non_empty(service_name, self._service_name)
 
-        # Prepare refs
         message_refs = (refs or {}).copy()
+        label_value = label
+
         message_refs[FIELD_SERVICE_NAME] = effective_service
-        if label:
-            message_refs["label"] = label
+        if label_value:
+            message_refs["label"] = label_value
 
         msg: dict[str, Any] = {
             FIELD_ACTION: ACTION_START_THREAD,
             FIELD_REFS: message_refs,
         }
 
+        effective_role = role
         if contract_name:
             msg[FIELD_CONTRACT_NAME] = contract_name
-            role = ""
-            # Check if role is in refs or if we should derive it
-            if effective_service:
-                role = effective_service.removesuffix("-service")
-            else:
-                role = "participant"
-            
-            msg[FIELD_ROLE] = role
+            if not effective_role:
+                if effective_service:
+                    effective_role = effective_service.removesuffix("-service")
+                else:
+                    effective_role = "participant"
+
+        if effective_role:
+            msg[FIELD_ROLE] = effective_role
+
+        # Validate and attach tags if provided
+        if tags:
+            for t in tags:
+                if not isinstance(t, str) or not t.strip():
+                    raise ValueError("Each tag must be a non-empty string")
+            msg[FIELD_TAGS] = list(tags)
 
         await self._send(msg)
 
@@ -182,7 +195,15 @@ class Connection:
             raise RuntimeError(resp.get(FIELD_MESSAGE, "failed to start thread"))
 
         thread_id = resp[FIELD_THREAD_ID]
-        thread = ThreadInstance(self, thread_id, contract_name, "", resp.get(FIELD_ACCESS_LEVEL, ""), None)
+        thread = ThreadInstance(
+            self,
+            thread_id,
+            contract_name,
+            effective_role,
+            resp.get(FIELD_ACCESS_LEVEL, ""),
+            message_refs.copy(),
+        )
+        thread.tags = list(tags) if tags else []
         self._threads[thread_id] = thread
         self._logger.debug(f"Thread started: {thread_id}")
         return thread
@@ -209,16 +230,19 @@ class Connection:
             msg[FIELD_THREAD_TOKEN] = token
         elif thread_id is not None:
             require_non_empty("thread_id", thread_id)
-            require_non_empty("role", role)
             msg[FIELD_THREAD_ID] = thread_id
-            msg[FIELD_ROLE] = role
-        elif token_or_thread_id is not None:
-            require_non_empty("token_or_thread_id", token_or_thread_id)
             if role:
-                msg[FIELD_THREAD_ID] = token_or_thread_id
                 msg[FIELD_ROLE] = role
-            else:
+        elif token_or_thread_id is not None:
+            require_non_empty("token_or_thread_id", token_or_thread_id)
+            # If it has 3 parts (JWT) or is a long string, it's likely a token. Otherwise it's a thread ID.
+            is_token = len(token_or_thread_id.split('.')) == 3 or len(token_or_thread_id) > 50
+            if is_token and not role:
                 msg[FIELD_THREAD_TOKEN] = token_or_thread_id
+            else:
+                msg[FIELD_THREAD_ID] = token_or_thread_id
+                if role:
+                    msg[FIELD_ROLE] = role
         else:
             raise ValueError("provide token, thread_id+role, or token_or_thread_id")
 
@@ -264,7 +288,7 @@ class Connection:
         event: str,
         step_name_or_handler: str | NotificationHandler | None = None,
         handler: NotificationHandler | None = None,
-    ) -> "Connection":
+    ) -> Connection:
         """Subscribe to notifications for a step or thread-level event.
 
         Supports two signatures:
@@ -296,7 +320,7 @@ class Connection:
         self._notification_handlers.setdefault(key, []).append(actual_handler)
         return self
 
-    def unsubscribe(self, event: str, step_name: str = "") -> "Connection":
+    def unsubscribe(self, event: str, step_name: str = "") -> Connection:
         """Unsubscribe from notifications.
 
         Args:

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9}/threadify/data_retriever.py

@@ -183,8 +183,12 @@ class DataRetriever:
         if q.started_before:
             variables["startedBefore"] = q.started_before
         data = await self._client.query(query, variables)
-        connection = data.get("threadsByRef") or {}
-        threads_list = connection.get("threads") or []
+        threads_by_ref = data.get("threadsByRef")
+        if isinstance(threads_by_ref, list):
+            threads_list = threads_by_ref
+        else:
+            connection = threads_by_ref or {}
+            threads_list = connection.get("threads") or []
         return [ArchivedThread(t, self._client) for t in threads_list if isinstance(t, dict)]
 
     async def get_validation_results(self, thread_id: str, step_name: str = "") -> list[dict[str, Any]]:

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9}/threadify/models.py

@@ -75,6 +75,7 @@ FIELD_OWNER_ID = "ownerId"
 FIELD_SEVERITY = "severity"
 FIELD_TIMESTAMP = "timestamp"
 FIELD_VIOLATION_TYPE = "violationType"
+FIELD_TAGS = "tags"
 
 # Protocol status values
 STATUS_SUCCESS = "success"

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9}/threadify/otel_exporter.py

@@ -150,6 +150,7 @@ class ThreadifySpanExporter(_SpanExporterBase):
                 "threadify.step_name",
                 "threadify.role",
                 "threadify.service",
+                "threadify.tags",
             }:
                 continue
 
@@ -169,7 +170,7 @@ class ThreadifySpanExporter(_SpanExporterBase):
         if context:
             step.add_context(context)
         if refs:
-            step.add_refs(refs)
+            await thread.add_refs(refs)
 
         # Map timing (OTel uses nanoseconds since epoch)
         start_time_ns = span.start_time
@@ -228,8 +229,6 @@ class ThreadifySpanExporter(_SpanExporterBase):
 
     async def _get_or_start_thread(self, span: ReadableSpan, trace_id: str) -> Any:
         """Get or create a ThreadInstance for this trace."""
-        from threadify.thread import ThreadInstance
-
         if trace_id not in self._trace_threads:
             fut: asyncio.Future[Any] = asyncio.get_event_loop().create_future()
             self._trace_threads[trace_id] = fut
@@ -264,10 +263,12 @@ class ThreadifySpanExporter(_SpanExporterBase):
                     except Exception:
                         pass
 
+                    tags = self._span_attr_list(span, "threadify.tags")
                     thread = await self._connection.start(
                         label=label,
                         contract_name=contract_name or "",
                         service_name=service_name,
+                        tags=tags,
                     )
                 fut.set_result(thread)
             except Exception as exc:
@@ -298,6 +299,18 @@ class ThreadifySpanExporter(_SpanExporterBase):
         value = span.attributes.get(key)
         return str(value) if value is not None else None
 
+    @staticmethod
+    def _span_attr_list(span: ReadableSpan, key: str) -> list[str] | None:
+        value = span.attributes.get(key)
+        if value is None:
+            return None
+        if isinstance(value, list):
+            return [str(v) for v in value]
+        if isinstance(value, str):
+            # Allow comma-separated tags as a fallback
+            return [v.strip() for v in value.split(",") if v.strip()]
+        return None
+
     @staticmethod
     def _make_result(code: int, error: str | None = None) -> Any:
         """Build an OpenTelemetry ExportResult-compatible object."""

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9}/threadify/step.py

@@ -13,7 +13,6 @@ from threadify.models import (
     FIELD_IDEMPOTENCY_KEY,
     FIELD_IS_DUPLICATE,
     FIELD_MESSAGE,
-    FIELD_REFS,
     FIELD_SERVICE_NAME,
     FIELD_STARTED_AT,
     FIELD_STATUS,
@@ -41,7 +40,6 @@ class ThreadStep:
         result = await (
             step
             .add_context({"orderId": "ORD-123", "amount": 99.99})
-            .add_refs({"stripe_id": "pi_abc"})
             .success("Order placed!")
         )
     """
@@ -59,7 +57,6 @@ class ThreadStep:
         self._manual_idempotency_key: str = ""
         self._sub_steps: list[SubStepData] = []
         self._context: dict[str, str] = {}
-        self._refs: dict[str, str] = {}
         self._metadata: dict[str, Any] | None = None
         self._error: Exception | None = None
 
@@ -108,14 +105,6 @@ class ThreadStep:
                 self._context[f"private_{k}"] = s
         return self
 
-    def add_refs(self, refs: dict[str, str] | None) -> ThreadStep:
-        """Add external system references."""
-        if self._error is not None:
-            return self
-        if refs:
-            self._refs.update(refs)
-        return self
-
     def sub_step(
         self,
         name: str,
@@ -181,7 +170,6 @@ class ThreadStep:
         self._event[FIELD_FINISHED_AT] = now_iso()
         self._event[FIELD_STATUS] = status
         self._event[FIELD_CONTEXT] = self._context
-        self._event[FIELD_REFS] = self._refs
 
         # Handle optional message/data.
         if message_or_data is not None:

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9}/threadify/thread.py

@@ -71,6 +71,7 @@ class ThreadInstance:
         self.role = role
         self.access_level = access_level
         self.refs: dict[str, str] = refs or {}
+        self.tags: list[str] = []  # Tags applied at thread creation (immutable)
 
         self._steps: dict[str, Any] = {}
         self._pending_waits: dict[str, _PendingWait] = {}

{threadify_sdk-0.2.7 → threadify_sdk-0.2.9/threadify_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadify-sdk
-Version: 0.2.7
+Version: 0.2.9
 Summary: Python SDK for Threadify — Service-delivery intelligence. Track every customer request from start to finish across every system, team, and partner. Visit: https://threadify.dev
 Author-email: Threadify Team <team@threadify.dev>
 License: MIT
@@ -63,7 +63,14 @@ async def main():
         return
 
     try:
-        thread = await conn.start("Order-123")
+        thread = await conn.start(
+            contract_name="order_processing",
+            role="customer",
+            refs={"order_id": "ORD-123"},
+            tags=["priority"],
+        )
+
+        await thread.add_refs({"crm_id": "CRM-456"})
         
         # Easy chaining!
         await (
@@ -130,6 +137,22 @@ thread = await conn.join(
 )
 ```
 
+### Start options
+
+`Connection.start(...)` supports named options for contract, role, refs, and tags, while preserving the older positional forms:
+
+```python
+thread = await conn.start(
+    contract_name="order_processing",
+    role="customer",
+    refs={"customer_id": "123"},
+    tags=["priority"],
+)
+thread = await conn.start("Order-123", "customer")
+thread = await conn.start({"customer_id": "123"}, "customer")
+thread = await conn.start("Order-123")  # contract is optional
+```
+
 ## Subscriptions
 
 Preferred API: