Metadata-Version: 2.4
Name: langchain-disposable
Version: 0.1.1
Summary: LangChain tool for running Python in disposable-exec isolated containers
Project-URL: Homepage, https://disposable-exec.com
Project-URL: Source, https://github.com/DevBunny-exe/disposable-exec
Project-URL: Documentation, https://disposable-exec.com
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: disposable-exec>=0.2.1
Requires-Dist: langchain-core>=0.2
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# langchain-disposable

Give your LangChain agent a code execution tool that runs in an isolated container — no network, read-only filesystem, 30-second timeout. Every run is disposable.

## When to use it

Use this package if you already use LangChain and want:

- a LangChain tool for remote execution
- API-key-authenticated execution through Disposable Exec
- the standard Disposable Exec flow behind a LangChain-facing interface

If you just need the raw client, use `disposable-exec`.

## Install

```bash
pip install langchain-disposable disposable-exec
```

For the agent example, also install the LangChain packages and model provider package you already use.

## Environment variables

```bash
export DISPOSABLE_EXEC_BASE_URL="https://your-api-host"
export DISPOSABLE_EXEC_API_KEY="de_xxx"
```

## Minimal tool example

```python
import os

from langchain_disposable import DisposableExecTool

tool = DisposableExecTool(
    api_key=os.environ["DISPOSABLE_EXEC_API_KEY"],
    base_url=os.environ["DISPOSABLE_EXEC_BASE_URL"],
)

result = tool.invoke({"script": "print(2 + 2)"})
print(result)
```

## Minimal agent example

```python
import os

from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

from langchain_disposable import DisposableExecTool

tool = DisposableExecTool(
    api_key=os.environ["DISPOSABLE_EXEC_API_KEY"],
    base_url=os.environ["DISPOSABLE_EXEC_BASE_URL"],
)

prompt = ChatPromptTemplate.from_messages(
    [
        ("system", "Use the execution tool when Python is useful."),
        ("human", "{input}"),
        ("placeholder", "{agent_scratchpad}"),
    ]
)

agent = create_tool_calling_agent(ChatOpenAI(model="gpt-4o-mini"), [tool], prompt)
executor = AgentExecutor(agent=agent, tools=[tool], verbose=True)

print(executor.invoke({"input": "Use Python to compute the mean of [2, 4, 6, 8]."}))
```

## What the agent gets back

The tool returns a JSON string with:
- `stdout` — captured standard output
- `stderr` — captured standard error  
- `exit_code` — process exit code (0 = success)
- `failure_reason` — structured reason if failed: `timeout`, `exit_nonzero`, `sandbox_error`, `platform_error`, `orphaned`
- `duration` — execution time in seconds

Your agent can use `failure_reason` to decide whether to retry, rewrite the code, or give up.

## Relationship to Disposable Exec

`langchain-disposable` is a thin LangChain wrapper on top of `disposable-exec`. Disposable Exec provides the API key, `/me`, `/run`, `/status`, and `/result` flow. This package makes that flow easy to use from LangChain.
