cocoonstack-sandbox-langchain 0.1.0__py3-none-any.whl

cocoonsandbox_langchain/__init__.py

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

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+cocoonsandbox_langchain/__init__.py,sha256=9_otWHxffnMJBm2_1XcZQdA2InXQParAM1Pha-SyXt4,130
+cocoonsandbox_langchain/toolkit.py,sha256=hcCcp24ldUZz7iKd4H88EZiwaJ8AxuKf3SFOwUk63Ts,5008
+cocoonstack_sandbox_langchain-0.1.0.dist-info/METADATA,sha256=HSPW_g5wCG_QN31LTH-QHiPv6-ueLGFeKUcHxFnjk2c,1249
+cocoonstack_sandbox_langchain-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+cocoonstack_sandbox_langchain-0.1.0.dist-info/top_level.txt,sha256=H0cckpx__PMsnQoWLd94bpqIQtu8sB0qJxKmhib3ntI,24
+cocoonstack_sandbox_langchain-0.1.0.dist-info/RECORD,,

cocoonstack_sandbox_langchain-0.1.0.dist-info/WHEEL

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

cocoonstack_sandbox_langchain-0.1.0.dist-info/top_level.txt

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