Metadata-Version: 2.4
Name: persevere-plumbing
Version: 1.0.6
Summary: Typed composition algebra for wiring LLM agent pipelines
Author-email: William Waites <ww@leithdocs.com>
License: # Plumbing — Licence
        
        Copyright (c) 2026 Leith Document Company Limited. All rights reserved.
        
        ## Permission
        
        You may use, copy, and distribute this software free of charge, but
        only for Permitted Purposes as described below.
        
        Any use that is not a Permitted Purpose requires a commercial licence
        from Leith Document Company Limited. To enquire about commercial
        licensing, contact licensing@leithdocs.com. We are happy to discuss
        terms.
        
        ## Permitted Purposes
        
        A **Permitted Purpose** is any use that meets all of the following
        conditions:
        
        1. The use is for personal learning, private study, hobby projects,
           academic teaching, or academic research.
        
        2. The use is not part of, or in support of, delivering a product,
           service, or operational capability to any third party, whether or
           not payment is involved.
        
        3. The use is not undertaken on behalf of, or funded by, any
           organisation for the purpose of evaluating the software for
           operational deployment.
        
        For the avoidance of doubt:
        
        - A researcher at a university using the software for research or
          teaching is a Permitted Purpose.
        
        - The same researcher using the software as part of paid consulting
          work is not a Permitted Purpose.
        
        - An individual experimenting with the software at home is a Permitted
          Purpose.
        
        - A company or government body evaluating the software for
          operational use requires a commercial licence.
        
        ## Source Code
        
        The source code of this software is not included in this distribution
        and is not licensed under these terms.
        
        ## Redistribution
        
        You may redistribute unmodified copies of this software, provided
        that you include this licence text in its entirety with every copy.
        
        You may not modify, reverse-engineer, decompile, or disassemble this
        software, except to the extent that applicable law expressly permits
        such activity notwithstanding this restriction.
        
        ## No Warranty
        
        This software is provided "as is", without warranty of any kind,
        express or implied. Leith Document Company Limited accepts no liability
        for any loss or damage arising from the use or inability to use this
        software, to the fullest extent permitted by law.
        
        Nothing in this licence excludes or limits liability for death or
        personal injury caused by negligence, for fraud, or for any other
        liability that cannot be excluded or limited under the laws of
        Scotland.
        
        ## General
        
        This licence is governed by the laws of Scotland and the parties
        submit to the exclusive jurisdiction of the Scottish courts.
        
        If any provision of this licence is found to be unenforceable, the
        remaining provisions continue in full force.
        
        Leith Document Company Limited reserves the right to offer this software
        under different terms, including free and open-source licences, at
        its sole discretion.
        
Project-URL: Homepage, https://leithdocs.com/plumbing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Compilers
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-asyncio>=0.21; extra == "test"
Provides-Extra: pydantic
Requires-Dist: pydantic-ai>=0.1; extra == "pydantic"
Dynamic: license-file

# Persevere Plumbing

A typed composition algebra for wiring LLM agent pipelines. Plumbing
is a pipeline language and runtime where agents are Unix processes,
channels are Unix pipes, and types are validated at every channel
boundary. You declare processes and their types in `.plumb` files, then
compose them using a small algebra of stream morphisms.

## Installation

Install from PyPI:

```sh
pip install persevere-plumbing
```

Pre-built wheels are also available for macOS (arm64) and Linux (x86_64).
To install directly from a staged wheel file:

```sh
pip install persevere_plumbing-*.whl
```

## Quick start

### Type-check a pipeline

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

result = pb.check(Path("pipeline.plumb"))
print(result.bindings)    # declared processes and their types
```

### One-shot execution

```python
results = pb.call_sync(Path("pipeline.plumb"), "hello")
```

### Streaming execution

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

async def main():
    async with await pb.run(Path("pipeline.plumb")) as pipeline:
        await pipeline.send("hello")
        response = await pipeline.recv()
        print(response)

asyncio.run(main())
```

### Build pipelines in Python

The `persevere.plumbing.dsl` subpackage lets you construct pipelines as Python
objects that render to `.plumb` source text:

```python
from persevere.plumbing.dsl import Program, Agent

prog = Program()
prog.let("writer", input=str, output=str,
    impl=Agent(model="claude-sonnet-4-5-20250514"))
results = prog.call_sync("Write a haiku about types")
```

## Platform availability

- macOS arm64 (Apple Silicon)
- Linux x86_64

## Documentation

Full documentation is included in the source repository under `doc/`:

- [Python bindings](https://leithdocs.com/plumbing) — complete API
  reference for `check()`, `call_sync()`, `run()`, and the DSL
- [Language reference](https://leithdocs.com/plumbing) — `.plumb`
  syntax, types, modules, protocols

## Licence

Copyright (c) 2026 Leith Document Company Limited. Free for
non-commercial use (personal learning, academic research, hobby
projects). Commercial use requires a licence — contact
licensing@leithdocs.com. See [LICENSE](LICENSE) for full terms.
