Metadata-Version: 2.4
Name: synapserun
Version: 0.6.1rc1
Summary: Synapse Cell SDK — receipted Wasm execution for bounded AI-agent logic, with streaming, filesystem, git, PTY, Dockerfile transpilation, and bundled Wasm runtimes.
Author-email: Mike Mazur <hello@synapserun.dev>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://synapserun.dev
Project-URL: Documentation, https://synapserun.dev/docs
Project-URL: Source, https://github.com/Synapse-Run/cell
Project-URL: Bug Tracker, https://github.com/Synapse-Run/cell/issues
Project-URL: Support, https://synapserun.dev
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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 :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Emulators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Provides-Extra: local
Requires-Dist: synapse-cell>=0.2.1rc1; extra == "local"
Provides-Extra: crypto
Requires-Dist: cryptography>=42.0; extra == "crypto"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3.0; extra == "langchain"
Requires-Dist: pydantic>=2.0; extra == "langchain"
Provides-Extra: crewai
Requires-Dist: crewai>=0.80.0; extra == "crewai"
Requires-Dist: pydantic>=2.0; extra == "crewai"
Provides-Extra: openai-agents
Requires-Dist: openai-agents; extra == "openai-agents"
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2.0; extra == "autogen"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.11.0; extra == "llamaindex"
Provides-Extra: all
Requires-Dist: langchain-core>=0.3.0; extra == "all"
Requires-Dist: crewai>=0.80.0; extra == "all"
Requires-Dist: openai-agents; extra == "all"
Requires-Dist: pyautogen>=0.2.0; extra == "all"
Requires-Dist: llama-index-core>=0.11.0; extra == "all"
Requires-Dist: websocket-client>=1.6.0; extra == "all"
Requires-Dist: cryptography>=42.0; extra == "all"

# synapserun

**Receipted Wasm execution for bounded AI-agent logic. Canadian-built. Self-hosted. Cryptographic execution receipts.**

[![PyPI](https://img.shields.io/pypi/v/synapserun)](https://pypi.org/project/synapserun/)
[![npm](https://img.shields.io/npm/v/synapserun)](https://www.npmjs.com/package/synapserun)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://github.com/Synapse-Run/cell/blob/main/LICENSE-AGPL.md)

## Install

```bash
pip install "synapserun[local]"
synapse doctor
synapse demo assurance
```

The local install bundles real CPython 3.12 and QuickJS 0.14 compiled to Wasm.
Local execution works with **zero configuration** — no Docker, no gateway,
no API key needed for the `api_url="local"` path.
`synapse doctor` verifies that the native local backend can return receipt-bearing results before you rely on the local demo path.

For Node.js:

```bash
npm install @runsynapse/sdk
```

## Quick Start — 5 seconds to first execution

```python
from synapse.cell import Cell

cell = Cell(api_url="local")
result = cell.run("print(2 + 2)")
print(result.stdout)      # '4\n'
print(result.latency_ms)  # ~1-2ms on the AX102 fast path
print(result.receipt.verify())
# Signed deployments can require Ed25519 signature verification too:
# print(result.receipt.verify(require_signature=True))
# Install `synapserun[crypto]` for Python-side Ed25519 verification.
cell.kill()
```

### Receipt bundles and replay

```bash
synapse receipt create --code examples/policy_gate_cell_code.py --out policy.bundle.json
synapse receipt inspect policy.bundle.json
synapse receipt verify policy.bundle.json
synapse receipt replay policy.bundle.json --api-url local
synapse evidence report policy.bundle.json --out policy.evidence.html
```

Receipt bundles are portable audit artifacts for bounded code execution. They
verify receipt integrity and can replay the code locally to compare stable
hashes/results. They do not prove the AI was correct.
Evidence packets are self-contained HTML reports for reviewer handoff. They
show receipt identity, verification status, optional replay status, and payload
hashes without including full code/stdout/stderr bodies by default.

### CPython-WASI fallback — broad Python, benchmark-dependent latency

```python
with Cell(api_url="local") as cell:
    result = cell.run("""
import hashlib, json
def sign(data: bytes) -> str:
    return hashlib.sha256(data).hexdigest()
print(json.dumps({"sig": sign(b'hello')}))
""")
    print(result.stdout)
    # {"sig": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"}
```

### JavaScript via QuickJS-WASI

```python
cell = Cell(api_url="local", template="javascript")
result = cell.run("console.log([1,2,3].reduce((a,b) => a+b))")
print(result.stdout)  # '6'
cell.kill()
```

### E2B-style migration for common execution flows

Already using E2B? Change one import:

```python
# Before:
# from e2b_code_interpreter import Sandbox

# After:
from synapse.e2b_compat import Sandbox

sbx = Sandbox(api_url="local")
result = sbx.run_code("print('hello')")
print(result.stdout)
```

Common E2B-style methods are available for code execution and file workflows:
`run_code`, `files.read/write/list`, `commands.run`, `kill`, `connect`,
`pause`/`resume`, and `get_info`. Test your full workflow before treating it
as parity with an agent-computer workspace.

## What's in the box

- **Real Python 3.12** (CPython-WASI) — broad Python fallback with bundled
  stdlib modules for code that does not fit the low-ms fast subset
- **Real JavaScript** (QuickJS-WASI) — ES2023, `await`, closures, typed arrays
- **Low-ms .syn transpile path** for simple arithmetic, f-strings, and numeric policy gates
- **Filesystem API** — `cell.files.write/read/list/exists/get_info/make_dir`
- **Git namespace** — `cell.git.clone/commit/push/pull/checkout/...` (21 methods)
- **PTY terminal** — `cell.pty.create(on_data=...)` (needs `pip install websocket-client`)
- **Dockerfile transpiler** — `synapse template build -f Dockerfile`
- **Framework integrations** (soft imports — install frameworks separately):
  - LangChain: `from synapse.langchain_tool import SynapseCellExecuteTool`
  - CrewAI: `from synapse.crewai_tool import SynapseCellCrewTool`
  - AutoGen: `from synapse.autogen_tool import SynapseCellExecutor`
  - LlamaIndex: `from synapse.llamaindex_tool import SynapseCellTool`
  - OpenAI Agents SDK: `from synapse.openai_agents_tool import synapse_cell_execute`
- **Persistent Volumes** — `cell.volumes.write/read/delete/list_all` (Pro license)
- **Async SDK** — `from synapse.async_cell import AsyncCell`

## Performance (latest AX102 run: 2026-05-15 vs live E2B)

| Metric | Cell | E2B | Delta |
|---|---|---|---|
| Simple eval (.syn transpile) | **1.334 ms** | 202.559 ms | **151.8×** lower p50 latency |
| Math heavy (10K loop sum) | **1.1873 ms** | 196.8904 ms | **165.8×** lower p50 latency |
| Numeric policy gate (deep probe) | **1.3348 ms** | 194.6455 ms | **145.8×** lower p50 latency |
| Fresh-process local cold total | **144.1622 ms** | 855.5838 ms E2B cold total | **5.9×** lower p50 latency |
| CPython-WASI fallback snippets | **133-170 ms** measured p50 range | — | Not a headline E2B claim |
| Memory per sandbox | ~1 MB | ~133 MB | **133×** density |
| Execution receipts | ✅ SHA-256 | ❌ | — |
| Jurisdiction | 🇨🇦 / 🇪🇺 | 🇺🇸 | — |

Reproduce from the repo root: `python3 benchmarks/e2b_apples_to_apples.py --runs 100 --warmup 10`

The current canonical AX102 row is `b9e6eb1f639599d1da02cbf00a035528c7886303`
from 2026-05-15. Keep public wording tied to the exact benchmark row and do
not reuse older internal speedup claims without a fresh canonical run.

## Deployment modes

| Mode | How | When |
|---|---|---|
| **Local** (zero-config) | `Cell(api_url="local")` | Dev, CI, small workloads, bundled into your app |
| **Self-hosted gateway** | Run the Rust gateway via Docker or native binary | Production, custom hardware, fleet management |

## Dockerfile → Wasm template (the E2B replacement bridge)

```bash
synapse template build -f Dockerfile --install-packages
```

Handles 80% of AI-agent Dockerfiles:
- `FROM python:*` / `node:*` → runtime selection
- `RUN pip install` / `npm install` → package bundles
- `COPY`, `WORKDIR`, `ENV`, `USER`, `CMD`, `ENTRYPOINT` → all mapped
- `RUN apt-get install git` → warning + "Use `cell.git.*`"
- Custom base images → clear error + migration hint

Examples: see `dockerfile_examples/` in the repo.

## CLI

```bash
synapse auth --api-key cell_sk_...
synapse sandbox create --template python3 --persistent
synapse sandbox run <id> "print(42)"
synapse template build -f Dockerfile
synapse template list
```

## Framework integrations

Tool classes are bundled in the wheel; frameworks are opt-in extras:

```bash
pip install "synapserun[local,langchain]"   # local runtime + LangChain deps
pip install "synapserun[local,crewai]"      # local runtime + CrewAI deps
pip install "synapserun[local,all]"         # local runtime + all integrations
```

## Correctness guardrails

The SDK auto-selects between:
1. **Fast path (.syn transpile, sub-ms)** — simple arithmetic, f-strings, numeric policy gates
2. **Full path (real CPython-WASI, benchmark-dependent)** — anything with `import` of non-trivial
   modules, bytes literals, `sys.exit`, f-strings with format specs, string
   multiplication, etc.

You never have to pick. The fast path has strict correctness gates; anything
it can't faithfully execute falls through to real CPython automatically.

For latency-sensitive local use, call `Cell.prewarm(api_url="local")` once at
process startup. This front-loads Wasmtime template loading/AOT setup so later
local Cell creates reuse the warmed manager.

## Links

- **Homepage:** https://synapserun.dev
- **Documentation:** https://synapserun.dev/docs
- **Support:** hello@synapserun.dev

## License

AGPL-3.0 with commercial dual-license. Apache 2.0 on the core runtime. Free for self-hosted use.
Pro features require a license key.
Contact hello@synapserun.dev for commercial licensing.

---

Built by [Synapse Run](https://synapserun.dev), Canada 🇨🇦 — Wasm-native, sovereign, self-hosted.
