# Plumbing

Plumbing is a typed composition language for agent pipelines, developed
by Leith Document Company. You declare agents and their types, wire them
together with sequential composition and tensor product, and the runtime
enforces types at every channel boundary.

## Install

```sh
pip install persevere_plumbing
```

Or download binaries:

- [Linux (x86_64)](https://ldc-downloads.hel1.your-objectstorage.com/plumbing/plumbing-1-linux-x86_64.tar.gz)
- [macOS (Apple Silicon)](https://ldc-downloads.hel1.your-objectstorage.com/plumbing/plumbing-1-darwin-aarch64.tar.gz)

Unpack and place the `plumb` binary on your PATH.

## Usage

Run a pipeline (input on stdin must be valid JSON, correctly typed
according to the pipeline's input type):

```sh
echo '"your input"' | plumb pipeline.plumb
```

From Python:

```python
import persevere.plumbing as pb
from pathlib import Path

print(pb.call_sync(Path("pipeline.plumb"), "your input"))
```

## Documentation

Source markdown for all documentation pages is served alongside the HTML.

### Language reference

- [Language reference](/plumbing/doc/plumbing.5.md) — syntax, types, modules, protocols
- [Agent contract](/plumbing/doc/system.md) — what agents see: wiring syntax, JSON contract, runtime behaviour
- [Processes](/plumbing/doc/processes.md) — stream transducers and the composition algebra
- [Tools](/plumbing/doc/tools.md) — tool semantics and MCP integration
- [Session types](/plumbing/doc/protocols.md) — linear protocols for control channels
- [Errors](/plumbing/doc/errors.md) — error types and diagnostics

### Python

- [Python bindings](/plumbing/doc/python-bindings.md) — the Python API
- [Python DSL](/plumbing/doc/dsl-reference.md) — constructing programs in Python

### Man pages

- [plumb(1)](/plumbing/doc/plumb.1.md) — run a pipeline
- [plumb-agent(1)](/plumbing/doc/plumb-agent.1.md) — LLM conversation process
- [plumb-chat(1)](/plumbing/doc/plumb-chat.1.md) — interactive frontend
- [plumb-mcp(1)](/plumbing/doc/plumb-mcp.1.md) — MCP server
- [plumb-render(1)](/plumbing/doc/plumb-render.1.md) — render pipeline diagram
- [Agent runtime](/plumbing/doc/agent-runtime.md) — agent runtime environment

### Grammar

- [Formal PEG grammar](/plumbing/grammar.peg)

### Examples

- [Examples](/plumbing/examples/index.md) — annotated examples with `.plumb` pipelines and `.py` runners

## Benchmark

LLMs can write plumbing. A one-shot generation benchmark across 25
models and 1000 trials showed that 6 frontier models achieved a
perfect 40/40 score, and 10 scored 95% or above. Given the grammar
and explanatory documentation in the system prompt, most current
models can produce syntactically valid, type-correct plumbing
programs from natural-language descriptions.

- [Plumbing generation benchmark](https://leithdocs.com/ldc/files/notes/evaluation/plumbing-generation-benchmark.md) — full methodology and results

## Licence

Free for personal use, academic research, and education.
Commercial use requires a licence from Leith Document Company Limited.
Contact [licensing@leithdocs.com](mailto:licensing@leithdocs.com).