Metadata-Version: 2.4
Name: swarmplane
Version: 0.0.1
Summary: A living task graph for agent orchestration on Google Cloud. Reference implementation.
Project-URL: Homepage, https://swarmplane.dev
Project-URL: Documentation, https://swarmplane.dev
Project-URL: Source, https://github.com/gadekar-pravin/swarmplane
Author: Pravin Gadekar
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: a2ui,agents,dag,gcp,mcp,orchestration
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Swarmplane

**A living task graph for agent orchestration on Google Cloud.**

An agent run leaves behind two artefacts: whatever state the runtime checkpointed, and
whatever trace it emitted alongside. Reconstructing why a run reached its conclusion means
reconciling them against each other.

Plan-and-execute designs assert the whole future up front, then flail when step three
returns something they didn't anticipate. ReAct loops adapt beautifully but leave behind
a transcript — not something you can inspect, diff, or hand to an auditor.

Swarmplane grows the graph from outcomes. Expansion is **append-only**: a retry is a new
node whose parent is the failure, never an edge back to a completed one. The graph stays
acyclic, and the complete causal history is preserved by construction.

Two properties follow:

**The execution graph is meant to *be* the audit log.** Every node is a span. Every edge
is a causal claim. There is no separate trace to reconcile against state — a commitment
the implementation has to earn, not a property that falls out of acyclicity.

**Every seam is an open protocol.** [MCP](https://modelcontextprotocol.io) for tools,
[A2A](https://a2a-protocol.org) for agents, [A2UI](https://a2ui.org) for interface.
Nothing proprietary between layers — including Swarmplane itself, which you can remove
and keep your agents.

## Three opinions

1. **The graph is primary, not the agent.** Agents are node executors.
2. **Every boundary is an open protocol.** No proprietary abstraction at any seam.
3. **GCP-native, not cloud-agnostic.** Portability is not a goal.

Swarmplane is not *unopinionated*. It is *transparent*: every decision is visible,
inspectable, and replaceable.

> "Swarm" here means **fleet**, not emergence. A *plane* coordinates workers against a
> shared graph.

## Why the append-only graph makes serverless work

Cloud Run allows a request up to 60 minutes, but a request dispatched through Cloud Tasks
is capped at 30. Frameworks that model an agent run as one long-lived process fight that
ceiling. Swarmplane has no long-lived process: each expansion is one short request, the
graph is durable, and a crash resumes from the frontier. A node parked on a human
approval or a remote agent enters `waiting` — alive, but holding no worker and no open
request — so a run can wait six hours without anything running for six hours.

## Status

**Pre-alpha. Nothing here is stable.** Anything on PyPI at `0.0.x` is a name
reservation, not a release.

The philosophy and architecture writing is live at **[swarmplane.dev](https://swarmplane.dev)**.
Implementation has not started — `src/swarmplane/` is a package skeleton.

Swarmplane is a *reference implementation* — a small, deliberately readable codebase
meant to be read, copied, and forked. It is installable (`uv add swarmplane`) so that
you can build on the argument, but there is no API-stability promise and there will
not be one until the design is proven: the version stays `0.x`, and any release may
break any API ([ADR-0007](adr/0007-installable-but-unpromised.md)).

The architecture writing at **[swarmplane.dev](https://swarmplane.dev)** is the primary
artifact. The code is the evidence.

Current phase, next steps and open questions: **[ROADMAP.md](ROADMAP.md)**.

## Repository layout

| Path | Contents |
|---|---|
| `docs/` | All prose. This *is* swarmplane.dev. |
| `src/swarmplane/` | The reference implementation. |
| `ui/` | Graph visualizer and A2UI host. |
| `examples/warehouse-agent/` | The flagship demo, with a bundled synthetic dataset. |
| `deploy/` | Terraform for Cloud Run, Cloud Tasks, and the graph store. |

## License

[Apache-2.0](LICENSE)
