Metadata-Version: 2.4
Name: langchain-lightning
Version: 1.0.0
Summary: Lightning AI sandbox integration for Deep Agents
License-Expression: MIT
Project-URL: Homepage, https://github.com/lightning-ai/langchain-lightning
Project-URL: Repository, https://github.com/lightning-ai/langchain-lightning
Project-URL: Documentation, https://github.com/lightning-ai/langchain-lightning#readme
Project-URL: Issues, https://github.com/lightning-ai/langchain-lightning/issues
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <4.0,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: deepagents<0.7.0,>=0.6.0
Requires-Dist: lightning-sdk>=2026.7.9
Dynamic: license-file

# langchain-lightning

[![PyPI - Version](https://img.shields.io/pypi/v/langchain-lightning?label=%20)](https://pypi.org/project/langchain-lightning/#history)
[![PyPI - License](https://img.shields.io/pypi/l/langchain-lightning)](https://opensource.org/licenses/MIT)
[![PyPI - Downloads](https://img.shields.io/pepy/dt/langchain-lightning)](https://pypistats.org/packages/langchain-lightning)

[Lightning AI](https://lightning.ai) sandbox integration for [Deep Agents](https://github.com/langchain-ai/deepagents).

## Quick Install

```bash
pip install langchain-lightning
```

## Deep Agents SDK

```python
from lightning_sdk.sandbox import Sandbox
from langchain_lightning import LightningSandbox, ensure_workdir

# python313 ships python3, which Deep Agents file tools require.
sandbox = Sandbox.create(
    instance_type="cpu-1",
    runtime="python313",
    persistent=True,  # optional: stop/resume by id across runs
)
ensure_workdir(sandbox, "/root")
backend = LightningSandbox(sandbox=sandbox)

try:
    result = backend.execute("python3 --version && echo hello")
    print(result.output)
finally:
    sandbox.delete()
```

Reconnect to a durable sandbox (auto-resumes when paused):

```python
from lightning_sdk.sandbox import Sandbox
from langchain_lightning import LightningSandbox, ensure_workdir, resume_if_needed

sandbox = resume_if_needed(Sandbox().get("sbx_..."))
ensure_workdir(sandbox, "/root")
backend = LightningSandbox(sandbox=sandbox)
```

The backend also works with async Deep Agents via the inherited `aexecute`,
`aupload_files`, `adownload_files`, and related methods (the Lightning SDK is
synchronous, so these run on a worker thread).

## Deep Agents Code

Install `langchain-lightning` into the `dcode` environment, then run with the
Lightning sandbox provider:

```bash
dcode --install langchain-lightning --package
export LIGHTNING_API_KEY=...
dcode --sandbox lightning
```

The provider defaults:

| Setting | Default |
|---|---|
| runtime | `python313` (has `python3`) |
| instance type | `cpu-1` |
| sandbox lifetime | 30 minutes |
| workdir | `/root` |
| persistent | `false` |

Optional env vars: `LIGHTNING_SANDBOX_RUNTIME`, `LIGHTNING_SANDBOX_IMAGE`,
`LIGHTNING_SANDBOX_INSTANCE_TYPE`, `LIGHTNING_SANDBOX_TIMEOUT` (seconds),
`LIGHTNING_SANDBOX_PERSISTENT`, `LIGHTNING_SANDBOX_NETWORK_POLICY`,
`LIGHTNING_CLOUD_URL`.

When reconnecting by sandbox id, the provider **resumes** paused/stopped
persistent sandboxes and ensures the workdir exists.

## What is this?

`langchain-lightning` adapts an existing [Lightning AI](https://lightning.ai) sandbox to the Deep Agents
sandbox protocol. It implements the `execute`, `upload_files`, and
`download_files` primitives over the `lightning_sdk.sandbox` SDK; Deep Agents
derives the rest of the filesystem operations (`ls`, `read`, `write`, `edit`,
`grep`, `glob`) from those.

Commands run detached and are awaited so per-command timeouts are honored. File
transfer is bridged through base64 so arbitrary binary content round-trips
losslessly despite Lightning's text-based file API.

For SDK use, this package intentionally does not hide Lightning sandbox
lifecycle management. Use the Lightning SDK to create, connect to, configure,
and delete sandboxes, then pass the sandbox object to `LightningSandbox`.

For Deep Agents Code, the package also exposes a `dcode` sandbox provider entry
point. The provider creates, reconnects to, and deletes Lightning sandboxes for
`dcode --sandbox lightning`.

> [!NOTE]
> Deep Agents runs its file operations with `python3` inside the sandbox, so
> create sandboxes with a runtime that ships a Python interpreter (e.g.
> `runtime="python313"`, the default for the provider). The bare default CPU
> image does **not** include Python.

## Contributing

Contributions are welcome. Keep the adapter focused on implementing the Deep
Agents sandbox backend protocol over the official [Lightning SDK](https://github.com/Lightning-AI/sdk).

## Development

```bash
uv sync --group test
make test
make lint
```

Integration tests require `LIGHTNING_API_KEY` and hit the real Lightning API
(create / shell / files / pause-resume):

```bash
export LIGHTNING_API_KEY=...
make integration_tests
```

CI runs unit tests on every PR and live integration tests when the
`LIGHTNING_API_KEY` repository secret is available (same-repo PRs, pushes to
`main`, nightly schedule, and manual `workflow_dispatch`).
