Metadata-Version: 2.4
Name: boardwalk
Version: 0.1.2
Summary: The Python SDK for Boardwalk agent workflows: write async def run(input, context), import capabilities like agent() and secrets, and run on the Boardwalk platform.
Project-URL: Homepage, https://github.com/boardwalk-labs/sdk-python
Project-URL: Repository, https://github.com/boardwalk-labs/sdk-python
Author: Robot Networks Inc.
License: MIT License
        
        Copyright (c) 2026 Robot Networks Inc.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
        associated documentation files (the "Software"), to deal in the Software without restriction, including
        without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
        following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial
        portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
        LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
        EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
        IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
        USE OR OTHER DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Boardwalk Python SDK

The Python SDK for [Boardwalk](https://boardwalk.sh) agent workflows. A workflow is a plain
async function; capabilities are imports:

```python
from boardwalk import agent, phase, secrets

async def run(input, context):
    key = await secrets.get("STRIPE_API_KEY")
    phase("analyze")
    note = await agent(f"Why did payment {input['id']} fail?")
    return {"action": "retry", "note": note}
```

The entry is a module-level `run` (async or sync), found by name — positional params,
Lambda-style: `input` is param 0, `context` is param 1, and declaring fewer params is fine.
The return value is the run's output. Typed I/O is opt-in: annotate `input` with a Pydantic
model / dataclass / `TypedDict` and the return type, and the platform derives the contract —
rich types (`datetime`, `bytes`, `set`, `Decimal`, big `int`) cross the wire in canonical
JSON encodings and arrive revived.

**Status: pre-alpha.** Built as part of the workflow format redesign; the platform side is
still landing.

## The surface

```python
from boardwalk import (
    agent,        # run an LLM leaf: await agent(prompt, model=..., schema=..., tools=[...])
    workflows,    # workflows.call / workflows.run / workflows.schedule
    sleep,        # await sleep(1500) / sleep(until=...)
    human_input,  # pause for a person; text / choice / multiselect
    secrets,      # await secrets.get("NAME")
    artifacts,    # await artifacts.write(name, content_type, body)
    computer,     # computer.open_browser() -> BrowserSession / open_desktop() -> DesktopSession
    shell,        # await shell(cmd) -> ShellResult (never raises on non-zero exit)
    parallel,     # run thunks concurrently; failures isolate to None
    phase,        # phase("analyze") — a run-timeline marker
    auth,         # await auth.id_token(audience) / auth.api_token()
    usage,        # await usage.get() — live budget state
    Context,      # run(input, context)'s second parameter (frozen dataclass)
)
```

## Unit testing

`install_test_host` makes `run(input, context)` a plain function call over stubs — no
socket, no engine:

```python
from boardwalk import install_test_host

host = install_test_host(
    agent=lambda prompt, opts: "LGTM",
    secrets={"STRIPE_API_KEY": "sk_test_1"},
)
out = await run({"id": "pay_1"}, host.context())
```

## How it works

Every capability is a thin client of the Boardwalk host protocol — newline-delimited
JSON-RPC 2.0 over a local Unix socket (`BOARDWALK_HOST_SOCK`) served by the runner inside
the run's machine. The SDK holds no model credentials and no platform secrets; the runner
brokers everything. Inline `agent()` tools run in your program process — only their
declarations cross the wire, and the engine calls the handlers back over the protocol. The
runner invokes your program via `python -m boardwalk._loader <entry>`.

## Development

```
make install   # uv sync
make check     # ruff lint + format check + mypy --strict + pytest with coverage
```

Stdlib-only at runtime (pydantic is optional, used for input validation only when your
`run` is annotated with a model and pydantic is importable).

## Sibling repos

- [`sdk-typescript`](https://github.com/boardwalk-labs/sdk-typescript) — `@boardwalk-labs/workflow`, the TypeScript SDK
- [`runner`](https://github.com/boardwalk-labs/runner) — the worker runtime that serves the host protocol
- [`cli`](https://github.com/boardwalk-labs/cli) — the `boardwalk` CLI
- [`examples`](https://github.com/boardwalk-labs/examples) — reference workflows

## License

MIT
