threadify-sdk 0.2.0__py3-none-any.whl

threadify/thread.py

@@ -0,0 +1,323 @@
+from __future__ import annotations
+
+import asyncio
+import re
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from threadify.notification import Notification
+    from threadify.step import ThreadStep
+
+from threadify.models import (
+    ACTION_ADD_REFS,
+    ACTION_CLOSE_THREAD,
+    ACTION_INVITE_PARTY,
+    ACTION_THREAD_END,
+    DEFAULT_WAIT_TIMEOUT,
+    FIELD_ACCESS_LEVEL,
+    FIELD_ACTION,
+    FIELD_CANCELLED_AT,
+    FIELD_CLOSED_AT,
+    FIELD_COMPLETED_AT,
+    FIELD_EXPIRES_AT,
+    FIELD_EXPIRES_IN,
+    FIELD_MESSAGE,
+    FIELD_REASON,
+    FIELD_REFS,
+    FIELD_ROLE,
+    FIELD_STATUS,
+    FIELD_THREAD_ID,
+    FIELD_THREAD_STATUS,
+    FIELD_THREAD_TOKEN,
+    STATUS_CANCELLED,
+    STATUS_COMPLETED,
+    STATUS_SUCCESS,
+    InviteOptions,
+    InviteResponse,
+    ThreadEndResponse,
+    WaitOptions,
+    first_non_empty,
+    require_non_empty,
+)
+
+UUID_REGEX = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE
+)
+
+
+class ThreadInstance:
+    """Represents an active thread on the Threadify Engine.
+
+    Usage::
+
+        thread = await conn.start(contract_name="order_flow")
+        step = thread.step("order_placed")
+        result = await step.add_context({"orderId": "ORD-123"}).success("Order received")
+        await thread.complete("All done")
+    """
+
+    def __init__(
+        self,
+        conn: Any,  # Connection (forward ref to avoid circular import)
+        thread_id: str,
+        contract_id: str = "",
+        role: str = "",
+        refs: dict[str, str] | None = None,
+    ):
+        self._conn = conn
+        self.thread_id = thread_id
+        self.contract_id = contract_id
+        self.role = role
+        self.refs: dict[str, str] = refs or {}
+
+        self._steps: dict[str, Any] = {}
+        self._pending_waits: dict[str, _PendingWait] = {}
+
+    def step(self, step_name: str) -> ThreadStep:
+        """Create a new step builder for this thread.
+
+        Args:
+            step_name: Unique name for the step.
+
+        Returns:
+            A ThreadStep builder.
+        """
+        from threadify.step import ThreadStep
+
+        s = ThreadStep(step_name, self, first_non_empty(self._conn.service_name))
+        if not step_name or not step_name.strip():
+            s._error = ValueError("step_name must be a non-empty string")
+
+        self._steps[step_name] = s
+        return s
+
+    async def invite_party(self, options: InviteOptions) -> InviteResponse:
+        """Create an invitation token for an external party.
+
+        Args:
+            options: Invitation configuration (role is required).
+
+        Returns:
+            InviteResponse with the token and metadata.
+        """
+        require_non_empty("role", options.role)
+
+        msg = {
+            FIELD_ACTION: ACTION_INVITE_PARTY,
+            FIELD_THREAD_ID: self.thread_id,
+            FIELD_ROLE: options.role,
+            FIELD_ACCESS_LEVEL: options.access_level or "external",
+            FIELD_EXPIRES_IN: options.expires_in or "24h",
+        }
+
+        await self._send(msg)
+
+        resp = await self._conn._wait_response(lambda m: m.get(FIELD_ACTION) == ACTION_INVITE_PARTY)
+
+        if resp.get(FIELD_STATUS) != STATUS_SUCCESS:
+            raise RuntimeError(resp.get(FIELD_MESSAGE, "failed to create invitation token"))
+
+        return InviteResponse(
+            token=resp.get(FIELD_THREAD_TOKEN, ""),
+            thread_id=self.thread_id,
+            role=resp.get(FIELD_ROLE, ""),
+            access_level=resp.get(FIELD_ACCESS_LEVEL, ""),
+            expires_at=resp.get(FIELD_EXPIRES_AT, ""),
+        )
+
+    async def wait_for(
+        self,
+        step_name: str,
+        options: WaitOptions | None = None,
+    ) -> Notification:
+        """Block until a notification arrives for the given step.
+
+        Args:
+            step_name: Step to wait for.
+            options: WaitOptions with timeout and status filters.
+
+        Returns:
+            The matching Notification.
+
+        Raises:
+            asyncio.TimeoutError: If the wait times out.
+        """
+        require_non_empty("step_name", step_name)
+
+        timeout = DEFAULT_WAIT_TIMEOUT
+        statuses: list[str] = []
+        if options:
+            if options.timeout > 0:
+                timeout = options.timeout
+            statuses = options.statuses
+
+        fut: asyncio.Future[Notification] = asyncio.get_event_loop().create_future()
+        pw = _PendingWait(future=fut, statuses=statuses)
+        self._pending_waits[step_name] = pw
+
+        try:
+            return await asyncio.wait_for(fut, timeout=timeout)
+        except asyncio.TimeoutError as err:
+            raise asyncio.TimeoutError(
+                f"Timeout waiting for step: {step_name} ({timeout}s)"
+            ) from err
+        finally:
+            self._pending_waits.pop(step_name, None)
+
+    async def add_refs(self, refs: dict[str, str]) -> None:
+        """Add external references to this thread.
+
+        Args:
+            refs: Key-value pairs of references.
+        """
+        if not refs:
+            raise ValueError("refs must be a non-empty dict")
+
+        msg = {
+            FIELD_ACTION: ACTION_ADD_REFS,
+            FIELD_THREAD_ID: self.thread_id,
+            FIELD_REFS: refs,
+        }
+
+        await self._send(msg)
+
+        resp = await self._conn._wait_response(lambda m: m.get(FIELD_ACTION) == ACTION_ADD_REFS)
+
+        if resp.get(FIELD_STATUS) != STATUS_SUCCESS:
+            raise RuntimeError(resp.get(FIELD_MESSAGE, "failed to add refs"))
+
+        self.refs.update(refs)
+
+    async def link_thread(self, thread_id: str, relationship: str = "parent") -> None:
+        """Link this thread to another thread via a reference.
+
+        Args:
+            thread_id: UUID of the thread to link.
+            relationship: Relationship type (default: "parent").
+        """
+        require_non_empty("thread_id", thread_id)
+        if not UUID_REGEX.match(thread_id):
+            raise ValueError("Invalid thread ID format")
+
+        ref_key = f"linkedThread:{relationship}"
+        await self.add_refs({ref_key: thread_id})
+
+    async def end(
+        self, status: str = STATUS_CANCELLED, reason: str | dict[str, Any] = ""
+    ) -> ThreadEndResponse:
+        """End the thread with the given status.
+
+        Args:
+            status: Thread end status ("cancelled", "completed").
+            reason: Optional reason message (string) or data dict.
+        """
+        return await self._end_thread(status, reason)
+
+    async def close(self, reason: str | dict[str, Any] = "") -> ThreadEndResponse:
+        """Close the thread (convenience for end with 'cancelled')."""
+        return await self._end_thread(STATUS_CANCELLED, reason)
+
+    async def complete(self, reason: str | dict[str, Any] = "") -> ThreadEndResponse:
+        """Complete the thread (convenience for end with 'completed')."""
+        return await self._end_thread(STATUS_COMPLETED, reason)
+
+    async def _end_thread(self, status: str, reason: str | dict[str, Any]) -> ThreadEndResponse:
+        msg: dict[str, Any] = {
+            FIELD_ACTION: ACTION_THREAD_END,
+            FIELD_THREAD_ID: self.thread_id,
+            FIELD_STATUS: status,
+        }
+        if isinstance(reason, str) and reason:
+            msg[FIELD_REASON] = reason
+        elif isinstance(reason, dict) and reason:
+            msg.update(reason)
+
+        await self._send(msg)
+
+        resp = await self._conn._wait_response(
+            lambda m: m.get(FIELD_ACTION) in (ACTION_THREAD_END, ACTION_CLOSE_THREAD)
+        )
+
+        if resp.get(FIELD_STATUS) != STATUS_SUCCESS:
+            raise RuntimeError(resp.get(FIELD_MESSAGE, "failed to end thread"))
+
+        self._cleanup()
+
+        import datetime as dt
+
+        ended_at = first_non_empty(
+            resp.get(FIELD_CLOSED_AT, ""),
+            resp.get(FIELD_COMPLETED_AT, ""),
+            resp.get(FIELD_CANCELLED_AT, ""),
+            dt.datetime.now(dt.timezone.utc).isoformat(),
+        )
+
+        return ThreadEndResponse(
+            thread_id=self.thread_id,
+            status=resp.get(FIELD_THREAD_STATUS, ""),
+            ended_at=ended_at,
+            message=resp.get(FIELD_MESSAGE, ""),
+        )
+
+    async def _send(self, msg: dict[str, Any]) -> None:
+        await self._conn._send(msg)
+
+    def _handle_notification(self, notif: Notification) -> None:
+        """Route notification to pending wait_for calls."""
+        pw = self._pending_waits.get(notif.step_name)
+        if pw is None:
+            return
+
+        # Check status filter.
+        if pw.statuses and notif.step_status not in pw.statuses:
+            return
+
+        # Deliver notification.
+        if not pw.future.done():
+            pw.future.set_result(notif)
+
+    def get_step(self, step_name: str) -> Any | None:
+        """Return the step instance for the given step name, if any."""
+        return self._steps.get(step_name)
+
+    def get_all_steps(self) -> list[Any]:
+        """Return all recorded steps for this thread."""
+        return list(self._steps.values())
+
+    def get_thread_id(self) -> str:
+        """Return the thread ID."""
+        return self.thread_id
+
+    def get_contract_id(self) -> str:
+        """Return the contract ID (or empty string)."""
+        return self.contract_id
+
+    def create_span_exporter(self, options: dict[str, Any] | None = None) -> Any:
+        """Create an OpenTelemetry SpanExporter wired to this thread.
+
+        Args:
+            options: Optional configuration dict. Supported keys:
+                - ``refs``: list of attribute keys to map to Threadify refs.
+
+        Returns:
+            A :class:`~threadify.otel_exporter.ThreadifySpanExporter` instance.
+        """
+        from threadify.otel_exporter import ThreadifySpanExporter
+
+        return ThreadifySpanExporter(self._conn, options or {})
+
+    def _cleanup(self) -> None:
+        """Cancel pending waits and unregister from connection."""
+        for pw in self._pending_waits.values():
+            if not pw.future.done():
+                pw.future.cancel()
+        self._pending_waits.clear()
+        self._conn._remove_thread(self.thread_id)
+
+
+class _PendingWait:
+    """Internal state for a pending wait_for call."""
+
+    def __init__(self, future: asyncio.Future, statuses: list[str]):
+        self.future = future
+        self.statuses = statuses

threadify_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: threadify-sdk
+Version: 0.2.0
+Summary: Python SDK for the Threadify Engine — workflow orchestration via WebSocket and GraphQL
+Author-email: Threadify Team <team@threadify.dev>
+License: MIT
+Keywords: threadify,workflow,orchestration,websocket,graphql
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=12.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Dynamic: license-file
+
+# Threadify Python SDK
+
+Python SDK for connecting to the Threadify Engine over WebSocket and querying archived data over GraphQL.
+
+## Installation
+
+```bash
+pip install threadify-sdk
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import asyncio
+import logging
+from threadify import Threadify
+
+
+async def main():
+    try:
+        conn = await Threadify.connect(
+            "your-api-key",
+            service_name="orders-service",
+            ws_url="wss://eng.threadify.dev/threads",
+        )
+    except Exception as e:
+        logging.error(f"Failed to connect: {e}")
+        return
+
+    try:
+        thread = await conn.start(contract_name="order_flow")
+        
+        # Easy chaining!
+        await (
+            thread.step("order_received")
+            .add_context({"orderId": "ORD-123"})
+            .success("Order accepted")
+        )
+    except Exception as e:
+        logging.error(f"Error in thread: {e}")
+    finally:
+        await conn.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+`ws_url` is required. The SDK no longer uses a hardcoded default URL.
+
+## Configuration
+
+### Connect options
+
+Use keyword arguments with `Threadify.connect(...)`:
+
+- `service_name`
+- `ws_url` (required)
+- `graphql_url`
+- `debug`
+- `max_in_flight`
+- `connect_timeout`
+
+Example:
+
+```python
+from threadify import Threadify
+
+conn = await Threadify.connect(
+    "your-api-key",
+    service_name="inventory-service",
+    ws_url="wss://eng.threadify.dev/threads",
+    debug=True,
+)
+```
+
+### Join options
+
+Use `Connection.join(...)` with keyword arguments:
+
+- `token=...`
+- `thread_id=...` and `role=...`
+
+Example:
+
+```python
+thread = await conn.join(token="jwt-token")
+```
+
+Or:
+
+```python
+thread = await conn.join(
+    thread_id="thread-123",
+    role="supplier",
+)
+```
+
+## Subscriptions
+
+Preferred API:
+
+- `subscribe(event, step_name, handler)`
+- `unsubscribe(event, step_name)`
+
+Supported event patterns:
+
+- `step.success`
+- `step.failed`
+- `step.*`
+- `rule.passed`
+- `rule.violated`
+- `rule.*`
+- `*`
+
+Example:
+
+```python
+def handle_notification(notification):
+    if notification.is_violated:
+        print(notification.message)
+
+
+
+conn.subscribe("rule.violated", "payment_step", handle_notification)
+```
+
+## Versioning & Releases
+
+This SDK follows [Semantic Versioning](https://semver.org/) and [Conventional Commits](https://www.conventionalcommits.org/). Releases are automated via GitHub Actions.
+
+- `fix: ...` -> Patch bump
+- `feat: ...` -> Minor bump
+- `feat!: ...` or `BREAKING CHANGE: ...` -> Major bump
+
+## Testing
+
+To run the SDK tests, execute:
+
+```bash
+make test
+```
+
+Alternatively, use `pytest`:
+
+```bash
+python3 -m pytest
+```

threadify_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+threadify/__init__.py,sha256=hlYiyomlvtHxKh0c-hU-pNtCidkdxvC7ymcKJyFRUqI,1215
+threadify/client.py,sha256=uS2IFZVzBY2siTDYcxZ3L_7f9j2uV4oH-mdlhRnTyds,5782
+threadify/connection.py,sha256=TXxC95vnPfmL77tVjJI6QSTOVJXBslKzUsoRG5MM0ys,17869
+threadify/data_retriever.py,sha256=jjI6nljYd8h1yF06rGUmSwLtGqHBNBHemVaDlYMmFeg,15484
+threadify/models.py,sha256=TMdXJQCG7kCRepyeWSBXimK5Toxt9K7oTZPChxhwFUM,7224
+threadify/notification.py,sha256=lYddMp9xtp5-4I4vB41MKwviEyhZ5rMJ0QvQodzOHac,4886
+threadify/otel_exporter.py,sha256=OrQwfz_MIL2vF9SzwcylgQCu3WLUDd1-AmVg9C_8gzg,11807
+threadify/step.py,sha256=-z0HL-aqz3qBzwgUQPWYrct3lCSOpviARUqQA5qhGWw,9950
+threadify/thread.py,sha256=KllVL9Zi5xp30bXxuyoZAD64Nj7rcB8TSUNnNHndOIQ,10295
+threadify_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=orhDDcZEkD3EZpCpx7e7e1_dP_cI0Udimcoz6Kl9iW0,1066
+threadify_sdk-0.2.0.dist-info/METADATA,sha256=5namSZAJQKMV4AyXbmthhUHBMpEn5jww881tPbz9_l8,3769
+threadify_sdk-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+threadify_sdk-0.2.0.dist-info/top_level.txt,sha256=xeA9h3XRewc6Orx51hv8tBaiRU9FvmVP9wJrG54_xew,10
+threadify_sdk-0.2.0.dist-info/RECORD,,

threadify_sdk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

threadify_sdk-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Threadify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

threadify_sdk-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+threadify