harness-sdk-python 0.32.1__tar.gz → 0.33.0__tar.gz

harness_sdk_python-0.33.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: harness-sdk-python
+Version: 0.33.0
+Summary: RunManager: the harness-sdk runs subsystem for Python Statewire hosts
+Project-URL: Repository, https://github.com/assistant-ui/harness-sdk
+License-Expression: MIT
+Requires-Python: <4.0,>=3.12
+Requires-Dist: pinned<0.16,>=0.15.0
+Requires-Dist: statewire<0.14,>=0.13.0
+Provides-Extra: deepagents
+Requires-Dist: deepagents>=0.6.12; extra == 'deepagents'
+Requires-Dist: langchain-core>=0.3; extra == 'deepagents'
+Requires-Dist: langchain-openai>=0.3; extra == 'deepagents'
+Requires-Dist: langgraph>=1.0.0; extra == 'deepagents'
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'deepagents'
+Provides-Extra: postgres
+Requires-Dist: langgraph-checkpoint-postgres>=2.0.0; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# harness-sdk-python
+
+The runs subsystem for Python Statewire hosts: `@run_manager` turns one async method into the run executor and mounts the `run/*` command surface (enqueue, steer, dequeue, edit, reload, stop, continue, input), each run in its own tray. Part of [harness-sdk](https://github.com/assistant-ui/harness-sdk), with `statewire` and `pinned`.
+
+## Install
+
+```sh
+uv add harness-sdk-python
+```
+
+Extras: `uv add "harness-sdk-python[postgres]"`, `uv add "harness-sdk-python[deepagents]"`.
+
+## Use
+
+```python
+from statewire import Statewire, command
+
+from harness_sdk import RunManager, run_manager
+
+
+class RunsHost(Statewire):
+    async def lifespan(self):
+        self.state = {"messages": []}
+        yield
+
+    @run_manager()
+    async def run(self, ctx: RunManager.RunContext):
+        for message in ctx.messages:
+            self.state["messages"].append({"id": message["id"]})
+        ctx.applied()
+        return RunManager.Complete()
+
+    @command("run/enqueue")
+    async def run_enqueue(self, params, *, ctx):
+        return await (await self.run.get()).enqueue(params, applied=ctx.applied)
+```
+
+## Docs
+
+- Get started: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/get-started/chat-app/page.mdx
+- Guide: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/guides/harness/host/page.mdx
+- Reference: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/reference/harness-sdk-python/page.mdx
+- Spec: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/spec/runs-protocol/page.mdx

harness_sdk_python-0.33.0/README.md

@@ -0,0 +1,43 @@
+# harness-sdk-python
+
+The runs subsystem for Python Statewire hosts: `@run_manager` turns one async method into the run executor and mounts the `run/*` command surface (enqueue, steer, dequeue, edit, reload, stop, continue, input), each run in its own tray. Part of [harness-sdk](https://github.com/assistant-ui/harness-sdk), with `statewire` and `pinned`.
+
+## Install
+
+```sh
+uv add harness-sdk-python
+```
+
+Extras: `uv add "harness-sdk-python[postgres]"`, `uv add "harness-sdk-python[deepagents]"`.
+
+## Use
+
+```python
+from statewire import Statewire, command
+
+from harness_sdk import RunManager, run_manager
+
+
+class RunsHost(Statewire):
+    async def lifespan(self):
+        self.state = {"messages": []}
+        yield
+
+    @run_manager()
+    async def run(self, ctx: RunManager.RunContext):
+        for message in ctx.messages:
+            self.state["messages"].append({"id": message["id"]})
+        ctx.applied()
+        return RunManager.Complete()
+
+    @command("run/enqueue")
+    async def run_enqueue(self, params, *, ctx):
+        return await (await self.run.get()).enqueue(params, applied=ctx.applied)
+```
+
+## Docs
+
+- Get started: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/get-started/chat-app/page.mdx
+- Guide: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/guides/harness/host/page.mdx
+- Reference: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/reference/harness-sdk-python/page.mdx
+- Spec: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/docs/spec/runs-protocol/page.mdx

{harness_sdk_python-0.32.1 → harness_sdk_python-0.33.0}/examples/runs_app.py

@@ -193,6 +193,6 @@ worker = PinnedWorker(
     advertise_url=os.environ.get("ADVERTISE_URL"),
 )
 router = PinnedHost(RunsHost, worker=worker, namespace="/threads")
-app = FastAPI(lifespan=router.lifespan)
+app = FastAPI()
 app.include_router(worker)
 app.include_router(router)

{harness_sdk_python-0.32.1 → harness_sdk_python-0.33.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "harness-sdk-python"
-version = "0.32.1"
+version = "0.33.0"
 description = "RunManager: the harness-sdk runs subsystem for Python Statewire hosts"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.12,<4.0"
-dependencies = ["statewire>=0.12.3,<0.13", "pinned>=0.14.6,<0.15"]
+dependencies = ["statewire>=0.13.0,<0.14", "pinned>=0.15.0,<0.16"]
 
 [project.optional-dependencies]
 postgres = ["langgraph-checkpoint-postgres>=2.0.0"]

{harness_sdk_python-0.32.1 → harness_sdk_python-0.33.0}/src/harness_sdk/__init__.py

@@ -8,16 +8,26 @@ from .checkpoints import (
     Snapshot,
     checkpoint_thread,
     langgraph_checkpoints,
+    langgraph_checkpointer,
     langgraph_snapshot,
+    langgraph_state_snapshot,
     langgraph_switch_values,
 )
-from .deepagents import DeepagentsMessages
+from .deepagents import (
+    DeepagentsMessages,
+    deepagents_drop_ephemeral,
+    deepagents_ingest,
+    deepagents_restamp,
+    deepagents_role,
+    deepagents_upsert_ephemeral,
+)
 from .linear_thread import linear_thread
 from .run_manager import RunManager, RunManagerDescriptor, run_manager
 from .voice import (
     VoiceManager,
     VoiceManagerDescriptor,
     VoiceProvider,
+    VoiceTurnCommitDeferred,
     end_voice,
     start_voice,
     temp_frontend_tool_result,
@@ -39,10 +49,18 @@ __all__ = [
     "VoiceManager",
     "VoiceManagerDescriptor",
     "VoiceProvider",
+    "VoiceTurnCommitDeferred",
     "checkpoint_thread",
+    "deepagents_drop_ephemeral",
+    "deepagents_ingest",
+    "deepagents_restamp",
+    "deepagents_role",
+    "deepagents_upsert_ephemeral",
     "end_voice",
     "langgraph_checkpoints",
+    "langgraph_checkpointer",
     "langgraph_snapshot",
+    "langgraph_state_snapshot",
     "langgraph_switch_values",
     "linear_thread",
     "run_manager",

{harness_sdk_python-0.32.1 → harness_sdk_python-0.33.0}/src/harness_sdk/checkpoints.py

@@ -27,6 +27,7 @@ _TIP_TRIGGERS = (
     "stop-continue",
     "steer",
 )
+_UNREAD: Any = object()
 
 
 @dataclass(frozen=True)
@@ -326,37 +327,66 @@ def _values_snapshot(
     lineage = values.get(lineage_key)
     if lineage is not None and not isinstance(lineage, dict):
         raise ValueError(f"lineage channel must be an object, got {lineage!r}")
+    # an unwritten channel is absent from the checkpoint
+    messages = values.get(messages_key, [])
+    if not isinstance(messages, list):
+        raise TypeError(f"{messages_key} channel must be a list, got {messages!r}")
     return Snapshot(
         checkpoint_id=checkpoint_id,
-        messages=[_message_dict(m) for m in values.get(messages_key, [])],
+        messages=[_message_dict(m) for m in messages],
         lineage=lineage,
     )
 
 
-def langgraph_checkpoints(
-    graph: Any,
+def langgraph_state_snapshot(
+    state: Any,
+    *,
+    messages_key: str = "messages",
+    lineage_key: str = "lineage",
+) -> Snapshot | None:
+    """A Snapshot from a compiled graph's ``aget_state`` result; None for a thread without a checkpoint."""
+    if state.metadata is None:
+        return None
+    return _values_snapshot(
+        state.config["configurable"]["checkpoint_id"],
+        state.values,
+        messages_key,
+        lineage_key,
+    )
+
+
+def _thread_config(
+    thread_id: str, checkpoint_ns: str, checkpoint_id: str | None
+) -> dict[str, Any]:
+    configurable: dict[str, Any] = {
+        "thread_id": thread_id,
+        "checkpoint_ns": checkpoint_ns,
+    }
+    if checkpoint_id is not None:
+        configurable["checkpoint_id"] = checkpoint_id
+    return {"configurable": configurable}
+
+
+def langgraph_checkpointer(
+    checkpointer: Any,
     *,
     thread_id: str,
     checkpoint_ns: str = "",
     messages_key: str = "messages",
     lineage_key: str = "lineage",
 ) -> CheckpointStore:
-    """A CheckpointStore over a compiled langgraph graph's ``aget_state``."""
+    """A CheckpointStore over a langgraph checkpoint saver's ``aget_tuple``."""
 
     class _Store:
         async def get(self, checkpoint_id: str | None) -> Snapshot | None:
-            configurable: dict[str, Any] = {
-                "thread_id": thread_id,
-                "checkpoint_ns": checkpoint_ns,
-            }
-            if checkpoint_id is not None:
-                configurable["checkpoint_id"] = checkpoint_id
-            state = await graph.aget_state({"configurable": configurable})
-            if state.metadata is None:
+            saved = await checkpointer.aget_tuple(
+                _thread_config(thread_id, checkpoint_ns, checkpoint_id)
+            )
+            if saved is None:
                 return None
             return _values_snapshot(
-                state.config["configurable"]["checkpoint_id"],
-                state.values,
+                saved.checkpoint["id"],
+                saved.checkpoint["channel_values"],
                 messages_key,
                 lineage_key,
             )
@@ -364,6 +394,29 @@ def langgraph_checkpoints(
     return _Store()
 
 
+def langgraph_checkpoints(
+    graph: Any,
+    *,
+    thread_id: str,
+    checkpoint_ns: str = "",
+    messages_key: str = "messages",
+    lineage_key: str = "lineage",
+) -> CheckpointStore:
+    """A CheckpointStore over a compiled langgraph graph's ``aget_state``."""
+
+    class _Store:
+        async def get(self, checkpoint_id: str | None) -> Snapshot | None:
+            return langgraph_state_snapshot(
+                await graph.aget_state(
+                    _thread_config(thread_id, checkpoint_ns, checkpoint_id)
+                ),
+                messages_key=messages_key,
+                lineage_key=lineage_key,
+            )
+
+    return _Store()
+
+
 def langgraph_snapshot(
     payload: dict[str, Any],
     *,
@@ -415,6 +468,10 @@ class CheckpointThread:
     _path: list[int] = field(default_factory=lambda: [0])
     _pending_fork: dict[str, Any] | None = None
 
+    def abandon_plan(self) -> None:
+        """Discard a planned fork whose run will not be ingested."""
+        self._pending_fork = None
+
     def _projection(self):
         return linear_thread(messages=lambda: self.transcript, role=self._role)
 
@@ -463,6 +520,8 @@ class CheckpointThread:
 
     async def plan(self, trigger: str, *, rollback_to: str | None = None) -> Plan:
         """The resumption for ``trigger``; a fork trigger names its last surviving message via ``rollback_to``."""
+        # an abandoned plan's fork must not leak into the next turn's ingest
+        self.abandon_plan()
         if trigger in _TIP_TRIGGERS:
             if rollback_to is not None:
                 raise ValueError(f"rollback_to is invalid for trigger {trigger!r}")
@@ -657,15 +716,21 @@ async def checkpoint_thread(
     thread_id: str,
     checkpoint_ns: str = "",
     role: Callable[[dict[str, Any]], str],
+    snapshot: Snapshot | None = _UNREAD,
 ) -> CheckpointThread:
-    """Boot a CheckpointThread: the thread row and the latest snapshot load concurrently."""
+    """Boot a CheckpointThread: the thread row and the latest snapshot load concurrently; ``snapshot`` hands in a latest snapshot already read (``None`` for a thread without one) and skips the store read."""
     if not isinstance(thread_id, str) or not thread_id:
         raise ValueError(f"thread_id must be a non-empty string, got {thread_id!r}")
     if not callable(role):
         raise TypeError("role must be callable")
-    branches, snapshot = await asyncio.gather(
-        index.read_thread(thread_id, checkpoint_ns), store.get(None)
-    )
+    if snapshot is _UNREAD:
+        branches, snapshot = await asyncio.gather(
+            index.read_thread(thread_id, checkpoint_ns), store.get(None)
+        )
+    else:
+        if snapshot is not None and not isinstance(snapshot, Snapshot):
+            raise TypeError(f"snapshot must be a Snapshot or None, got {snapshot!r}")
+        branches = await index.read_thread(thread_id, checkpoint_ns)
     thread = CheckpointThread(
         transcript=[],
         branches=branches,