cocoonstack-sandbox-langchain 0.1.0__tar.gz

cocoonstack_sandbox_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: cocoonstack-sandbox-langchain
+Version: 0.1.0
+Summary: LangChain tools backed by cocoon microVM sandboxes
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: langchain-core>=1.0
+Requires-Dist: cocoonstack-sandbox>=0.1
+
+# cocoonstack-sandbox-langchain
+
+LangChain tools backed by cocoon microVM sandboxes: a `CocoonToolkit`
+claims one sandbox lazily on first tool use and exposes it as
+`StructuredTool`s an agent can call — shell exec, file read/write, and
+directory listing, with disk state persisting across calls.
+
+```python
+from cocoonsandbox_langchain import CocoonToolkit
+
+with CocoonToolkit("10.0.0.5:7777", api_token="...") as kit:
+    agent = create_react_agent(model, kit.get_tools())
+    agent.invoke({"messages": [("user", "run the tests in /work")]})
+```
+
+`from_checkpoint="ck_..."` branches the sandbox from a checkpoint's
+captured moment instead of a clean template — agents resume from prepared
+state (dependencies installed, repo cloned) in milliseconds.
+
+Sync-native (`_run` calls the stdlib-only cocoonstack-sandbox SDK
+directly); async agents get `_arun` bridged via `asyncio.to_thread`.
+
+Full reference: https://cocoonstack.github.io/sandbox/langchain

cocoonstack_sandbox_langchain-0.1.0/README.md

@@ -0,0 +1,23 @@
+# cocoonstack-sandbox-langchain
+
+LangChain tools backed by cocoon microVM sandboxes: a `CocoonToolkit`
+claims one sandbox lazily on first tool use and exposes it as
+`StructuredTool`s an agent can call — shell exec, file read/write, and
+directory listing, with disk state persisting across calls.
+
+```python
+from cocoonsandbox_langchain import CocoonToolkit
+
+with CocoonToolkit("10.0.0.5:7777", api_token="...") as kit:
+    agent = create_react_agent(model, kit.get_tools())
+    agent.invoke({"messages": [("user", "run the tests in /work")]})
+```
+
+`from_checkpoint="ck_..."` branches the sandbox from a checkpoint's
+captured moment instead of a clean template — agents resume from prepared
+state (dependencies installed, repo cloned) in milliseconds.
+
+Sync-native (`_run` calls the stdlib-only cocoonstack-sandbox SDK
+directly); async agents get `_arun` bridged via `asyncio.to_thread`.
+
+Full reference: https://cocoonstack.github.io/sandbox/langchain

cocoonstack_sandbox_langchain-0.1.0/cocoonsandbox_langchain/__init__.py

@@ -0,0 +1,7 @@
+"""LangChain tools backed by cocoon microVM sandboxes."""
+
+from .toolkit import CocoonToolkit
+
+__all__ = [
+    "CocoonToolkit",
+]

cocoonstack_sandbox_langchain-0.1.0/cocoonsandbox_langchain/toolkit.py

@@ -0,0 +1,127 @@
+"""LangChain toolkit over cocoon microVM sandboxes: one claimed sandbox
+behind a set of StructuredTools (exec, file read/write, list). The claim is
+lazy — building an agent costs nothing until a tool actually runs — and the
+toolkit is a context manager whose exit releases the sandbox."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+
+from cocoonsandbox import Client, Sandbox
+from langchain_core.tools import StructuredTool
+from pydantic import BaseModel, Field
+
+
+class ExecInput(BaseModel):
+    command: str = Field(description="shell command, run via sh -c inside the sandbox")
+    cwd: str = Field(default="", description="working directory (optional)")
+
+
+class WriteFileInput(BaseModel):
+    path: str = Field(description="absolute path in the sandbox")
+    content: str = Field(description="file content to write")
+
+
+class PathInput(BaseModel):
+    path: str = Field(description="absolute path in the sandbox")
+
+
+class CocoonToolkit:
+    """LangChain tools backed by one sandbox, claimed on first tool use.
+
+    from_checkpoint branches a fresh sandbox from that checkpoint's captured
+    moment instead of claiming a clean template — agents resume from
+    prepared state.
+    """
+
+    def __init__(self, addr: str, api_token: str = "", template: str = "rt:24.04",
+                 net: str = "", ttl_seconds: int = 0, from_checkpoint: str = ""):
+        self._client = Client(addr, api_token=api_token)
+        self._template = template
+        self._net = net
+        self._ttl = ttl_seconds
+        self._from_checkpoint = from_checkpoint
+        self._lock = threading.Lock()
+        self._sb: Sandbox | None = None
+        self._closed = False
+
+    def __enter__(self) -> CocoonToolkit:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def get_tools(self) -> list[StructuredTool]:
+        """The sandbox tool set; sync-native (_run), async via to_thread."""
+        return [
+            self._tool("sandbox_exec",
+                       "Run a shell command in the sandbox; returns stdout, stderr, "
+                       "and the exit code. State on disk persists across calls.",
+                       ExecInput, self._exec),
+            self._tool("sandbox_write_file",
+                       "Write a text file in the sandbox (atomic).",
+                       WriteFileInput, self._write_file),
+            self._tool("sandbox_read_file",
+                       "Read a text file from the sandbox.",
+                       PathInput, self._read_file),
+            self._tool("sandbox_list_dir",
+                       "List a sandbox directory as JSON entries.",
+                       PathInput, self._list_dir),
+        ]
+
+    def close(self) -> None:
+        """Releases the sandbox; safe to call twice or before any claim.
+        Tools invoked after close raise instead of silently claiming a
+        sandbox nothing would ever release."""
+        with self._lock:
+            sb, self._sb = self._sb, None
+            self._closed = True
+        if sb is not None:
+            sb.close()
+
+    def sandbox(self) -> Sandbox:
+        """The claimed sandbox, claiming (or branching) on first use."""
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("toolkit is closed")
+            if self._sb is None:
+                self._sb = self._claim()
+            return self._sb
+
+    def _claim(self) -> Sandbox:
+        if self._from_checkpoint:
+            return self._client.checkpoint(self._from_checkpoint).new(ttl_seconds=self._ttl)
+        return self._client.new(self._template, net=self._net, ttl_seconds=self._ttl)
+
+    def _tool(self, name: str, description: str, schema: type[BaseModel], func) -> StructuredTool:
+        async def arun(**kwargs):
+            return await asyncio.to_thread(func, **kwargs)
+
+        return StructuredTool.from_function(func=func, coroutine=arun, name=name,
+                                            description=description, args_schema=schema)
+
+    def _exec(self, command: str, cwd: str = "") -> str:
+        out: list[bytes] = []
+        errs: list[bytes] = []
+        code = self.sandbox().run(["sh", "-c", command], cwd=cwd,
+                                  on_stdout=out.append, on_stderr=errs.append)
+        stdout = b"".join(out).decode(errors="replace")
+        stderr = b"".join(errs).decode(errors="replace")
+        result = stdout
+        if stderr:
+            result += ("\n" if result else "") + "stderr: " + stderr
+        if code != 0:
+            result += ("\n" if result else "") + f"exit code: {code}"
+        return result or "(no output)"
+
+    def _write_file(self, path: str, content: str) -> str:
+        self.sandbox().write_file(path, content.encode())
+        return f"wrote {path}"
+
+    def _read_file(self, path: str) -> str:
+        return self.sandbox().read_file(path).decode(errors="replace")
+
+    def _list_dir(self, path: str) -> str:
+        return json.dumps(self.sandbox().list_dir(path))

cocoonstack_sandbox_langchain-0.1.0/cocoonstack_sandbox_langchain.egg-info/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: cocoonstack-sandbox-langchain
+Version: 0.1.0
+Summary: LangChain tools backed by cocoon microVM sandboxes
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: langchain-core>=1.0
+Requires-Dist: cocoonstack-sandbox>=0.1
+
+# cocoonstack-sandbox-langchain
+
+LangChain tools backed by cocoon microVM sandboxes: a `CocoonToolkit`
+claims one sandbox lazily on first tool use and exposes it as
+`StructuredTool`s an agent can call — shell exec, file read/write, and
+directory listing, with disk state persisting across calls.
+
+```python
+from cocoonsandbox_langchain import CocoonToolkit
+
+with CocoonToolkit("10.0.0.5:7777", api_token="...") as kit:
+    agent = create_react_agent(model, kit.get_tools())
+    agent.invoke({"messages": [("user", "run the tests in /work")]})
+```
+
+`from_checkpoint="ck_..."` branches the sandbox from a checkpoint's
+captured moment instead of a clean template — agents resume from prepared
+state (dependencies installed, repo cloned) in milliseconds.
+
+Sync-native (`_run` calls the stdlib-only cocoonstack-sandbox SDK
+directly); async agents get `_arun` bridged via `asyncio.to_thread`.
+
+Full reference: https://cocoonstack.github.io/sandbox/langchain

cocoonstack_sandbox_langchain-0.1.0/cocoonstack_sandbox_langchain.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+cocoonsandbox_langchain/__init__.py
+cocoonsandbox_langchain/toolkit.py
+cocoonstack_sandbox_langchain.egg-info/PKG-INFO
+cocoonstack_sandbox_langchain.egg-info/SOURCES.txt
+cocoonstack_sandbox_langchain.egg-info/dependency_links.txt
+cocoonstack_sandbox_langchain.egg-info/requires.txt
+cocoonstack_sandbox_langchain.egg-info/top_level.txt
+tests/test_toolkit.py

cocoonstack_sandbox_langchain-0.1.0/cocoonstack_sandbox_langchain.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cocoonstack_sandbox_langchain-0.1.0/cocoonstack_sandbox_langchain.egg-info/requires.txt

@@ -0,0 +1,2 @@
+langchain-core>=1.0
+cocoonstack-sandbox>=0.1

cocoonstack_sandbox_langchain-0.1.0/cocoonstack_sandbox_langchain.egg-info/top_level.txt

@@ -0,0 +1 @@
+cocoonsandbox_langchain

cocoonstack_sandbox_langchain-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cocoonstack-sandbox-langchain"
+version = "0.1.0"
+description = "LangChain tools backed by cocoon microVM sandboxes"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+readme = "README.md"
+dependencies = ["langchain-core>=1.0", "cocoonstack-sandbox>=0.1"]
+
+[tool.setuptools.packages.find]
+include = ["cocoonsandbox_langchain*"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]

cocoonstack_sandbox_langchain-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cocoonstack_sandbox_langchain-0.1.0/tests/test_toolkit.py

@@ -0,0 +1,88 @@
+"""Toolkit wiring against a fake sandbox: tool names/schemas, exec output
+shaping, lazy claim, and double-close safety — no real node."""
+
+import asyncio
+
+import pytest
+
+from cocoonsandbox_langchain import CocoonToolkit
+
+
+class FakeSandbox:
+    def __init__(self):
+        self.closed = 0
+        self.files = {}
+
+    def run(self, argv, cwd="", on_stdout=None, on_stderr=None, **_):
+        assert argv[:2] == ["sh", "-c"]
+        if argv[2] == "boom":
+            on_stderr(b"kaboom\n")
+            return 3
+        on_stdout(f"ran: {argv[2]}\n".encode())
+        return 0
+
+    def write_file(self, path, data):
+        self.files[path] = data
+
+    def read_file(self, path):
+        return self.files[path]
+
+    def list_dir(self, path):
+        return [{"name": "a.txt", "kind": "file", "size": 3}]
+
+    def close(self):
+        self.closed += 1
+
+
+def hooked(monkeypatch):
+    kit = CocoonToolkit("127.0.0.1:1")
+    fake = FakeSandbox()
+    monkeypatch.setattr(kit, "_claim", lambda: fake)
+    return kit, fake
+
+
+def test_tools_shape(monkeypatch):
+    kit, _ = hooked(monkeypatch)
+    tools = kit.get_tools()
+    names = [t.name for t in tools]
+    assert names == ["sandbox_exec", "sandbox_write_file", "sandbox_read_file", "sandbox_list_dir"]
+    assert all(t.description for t in tools)
+    assert kit._sb is None, "get_tools must not claim"
+
+
+def test_exec_tool_output(monkeypatch):
+    kit, _ = hooked(monkeypatch)
+    exec_tool = kit.get_tools()[0]
+    assert exec_tool.invoke({"command": "echo hi"}) == "ran: echo hi\n"
+    out = exec_tool.invoke({"command": "boom"})
+    assert "kaboom" in out and "exit code: 3" in out
+
+
+def test_async_bridge(monkeypatch):
+    kit, _ = hooked(monkeypatch)
+    exec_tool = kit.get_tools()[0]
+    result = asyncio.run(exec_tool.ainvoke({"command": "echo async"}))
+    assert result == "ran: echo async\n"
+
+
+def test_file_tools_round_trip(monkeypatch):
+    kit, _ = hooked(monkeypatch)
+    _, write, read, list_dir = kit.get_tools()
+    assert write.invoke({"path": "/w/a.txt", "content": "body"}) == "wrote /w/a.txt"
+    assert read.invoke({"path": "/w/a.txt"}) == "body"
+    assert "a.txt" in list_dir.invoke({"path": "/w"})
+
+
+def test_close_releases_once(monkeypatch):
+    kit, fake = hooked(monkeypatch)
+    kit.get_tools()[0].invoke({"command": "x"})  # forces the claim
+    kit.close()
+    kit.close()
+    assert fake.closed == 1
+
+
+def test_use_after_close_raises(monkeypatch):
+    kit, _ = hooked(monkeypatch)
+    kit.close()
+    with pytest.raises(RuntimeError):
+        kit.sandbox()