Metadata-Version: 2.4
Name: pathway-engine
Version: 0.1.0
Summary: Pathway VM - declarative workflow execution engine for AI agents
Project-URL: Homepage, https://github.com/albusstudio/pathway-engine
Project-URL: Documentation, https://github.com/albusstudio/pathway-engine#readme
Project-URL: Repository, https://github.com/albusstudio/pathway-engine
License: MIT
Keywords: agents,ai,automation,llm,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Provides-Extra: all-llm
Requires-Dist: anthropic>=0.20; extra == 'all-llm'
Requires-Dist: google-generativeai>=0.5; extra == 'all-llm'
Requires-Dist: openai>=1.0; extra == 'all-llm'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: google
Requires-Dist: google-generativeai>=0.5; extra == 'google'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Description-Content-Type: text/markdown

# Pathway Engine

Declarative workflow execution engine for AI agents.

## Installation

```bash
pip install pathway-engine
```

With LLM providers:

```bash
pip install pathway-engine[openai]
pip install pathway-engine[anthropic]
pip install pathway-engine[all-llm]
```

## Quick Start

```python
from pathway_engine import Pathway, LLMNode, TransformNode, Connection, PathwayVM, Context

# Define a pathway
pathway = Pathway(
    id="greeting",
    name="Greeting Pipeline",
    nodes={
        "greet": LLMNode(
            id="greet",
            prompt="Write a friendly greeting for {{name}}",
            model="gpt-4o",
        ),
        "format": TransformNode(
            id="format",
            expr="greet.response.upper()",
        ),
    },
    connections=[
        Connection(from_node="greet", to_node="format"),
    ],
)

# Execute
ctx = Context(tools={})  # Add tools as needed
vm = PathwayVM(ctx)
result = await vm.execute(pathway, inputs={"name": "World"})
print(result.outputs)
```

## Core Concepts

### Pathway
A directed graph of nodes that defines a workflow.

### Nodes
Compute units that process data:

- **LLMNode** - Call language models
- **ToolNode** - Execute tools/functions
- **TransformNode** - Transform data with expressions
- **RouterNode** - Route to different paths based on conditions
- **GateNode** - Binary if/else routing
- **MemoryReadNode / MemoryWriteNode** - Persist state
- **EventSourceNode** - Stream events (timers, webhooks)
- **AgentLoopNode** - Agentic tool-use loops

### Connection
Data flow between nodes.

### Context
Runtime services injected into the VM:

```python
ctx = Context(
    tools={
        "search.web": my_search_handler,
        "workspace.read": my_file_handler,
    },
    memory=my_memory_store,
    extras={"custom": "services"},
)
```

### PathwayVM
Executes pathways:

```python
vm = PathwayVM(ctx)
result = await vm.execute(pathway, inputs={"key": "value"})
```

## Streaming

Built-in event sources for reactive workflows:

```python
from pathway_engine import EventSourceNode, WEBHOOK_BUS

# Timer-based
timer = EventSourceNode(
    id="tick",
    source="timer.interval",
    config={"seconds": 60},
)

# Webhook-based
webhook = EventSourceNode(
    id="events", 
    source="webhook.listen",
    config={"topic": "my-events"},
)

# Publish to webhook
WEBHOOK_BUS.publish("my-events", {"data": "hello"})
```

## Packs & Triggers

Organize pathways into deployable packs:

```python
from pathway_engine import Pack, Trigger, pack_builder

@pack_builder
def my_pack():
    return Pack(
        id="my-pack",
        name="My Pack",
        pathways={"main": my_pathway},
        triggers=[
            Trigger(
                id="on-webhook",
                source="webhook.my-topic",
                pathway="main",
            ),
        ],
    )
```

## License

MIT

