Metadata-Version: 2.4
Name: drydock-sdk
Version: 0.1.0
Summary: Python SDK for drydock — build and test AI agents and agentic workflows locally.
Author-email: Sai Kumar Yava <saikumar.geek@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/scionoftech/drydock
Project-URL: Repository, https://github.com/scionoftech/drydock
Project-URL: Documentation, https://github.com/scionoftech/drydock/blob/main/docs/SDK.md
Project-URL: Issues, https://github.com/scionoftech/drydock/issues
Project-URL: Changelog, https://github.com/scionoftech/drydock/blob/main/CHANGELOG.md
Keywords: ai,agents,agent-runtime,llm,mcp,drydock,agentic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
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: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# drydock-sdk

Python SDK for [**drydock**](https://github.com/scionoftech/drydock) — build and test AI agents and agentic workflows locally, one binary, with or without Docker.

Write an agent, tool, or MCP server as a plain Python function, decorate it, and the drydock runtime launches it as an isolated node: hot-reloaded during development, wired to other agents (A2A) and MCP servers, and fully traced.

```python
from drydock import node

@node(name="greeter", role="agent")
async def greet(ctx, name: str = "world"):
    await ctx.emit({"status": "thinking"})   # stream a partial update
    return {"message": f"hello, {name}"}
```

## Requires the drydock runtime

This package is the **author-side SDK only**. It has no effect on its own — nodes
are launched and orchestrated by the separate `drydock` binary (the runtime, HTTP
API, web UI, and tracing all live there). Install the runtime first:

```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/scionoftech/drydock/main/scripts/install.sh | sh
```

See the [project README](https://github.com/scionoftech/drydock) for tarball and
build-from-source options.

## Install

```bash
pip install drydock-sdk
```

Zero runtime dependencies, pure Python, ships type hints (PEP 561). Install it
into the virtualenv of each node you author.

## Write a node

A node is a directory with your handler and a `node.yaml` manifest:

```python
# handler.py
from drydock import node

@node(name="hello", role="agent")   # role: "agent" | "tool" | "mcp"
async def hi(ctx, name: str = "world"):
    return {"message": f"hello, {name}"}
```

```yaml
# node.yaml
name: hello
version: 0.1.0
role: agent
runtime: python
entry: handler.py:hi
```

```bash
drydock dev                                   # hot-reload daemon + web UI
drydock invoke hello --input '{"name":"Sai"}'
```

## The `ctx` object

Every handler receives a context as its first argument:

| Call | Does |
|---|---|
| `await ctx.a2a.call(target, input)` | Invoke another node by name (agent-to-agent) |
| `await ctx.mcp.call(alias, tool, args)` | Call a tool on a declared MCP server |
| `await ctx.mcp.list(alias)` | List an MCP server's tools |
| `await ctx.session.append(role, content)` | Append to the persistent transcript |
| `await ctx.session.history(limit)` | Read recent transcript entries |
| `await ctx.emit(data)` | Stream a partial chunk (no-op on plain invoke) |
| `ctx.session_id`, `ctx.streaming`, `ctx.trace` | Invocation metadata |

Handlers may be `async def` (served concurrently) or plain `def` (run in a thread
pool). A JSON-object input is spread onto handler kwargs; return any
JSON-serializable value.

Full reference — input mapping, session semantics, the error model, streaming, and
environment scrubbing — is in
[docs/SDK.md](https://github.com/scionoftech/drydock/blob/main/docs/SDK.md).

## Links

- **Project & docs:** https://github.com/scionoftech/drydock
- **SDK reference:** https://github.com/scionoftech/drydock/blob/main/docs/SDK.md
- **Issues:** https://github.com/scionoftech/drydock/issues

## License

MIT
