Metadata-Version: 2.4
Name: orch-lib
Version: 3.1.1
Summary: A Python library for agent orchestration with task scheduling, conditional routing, and memory management
Author-email: Durga Sai Gundubogula <dsainvg.20.12@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/dsainvg/orch-lib
Project-URL: Documentation, https://github.com/dsainvg/orch-lib#readme
Project-URL: Repository, https://github.com/dsainvg/orch-lib.git
Project-URL: Issues, https://github.com/dsainvg/orch-lib/issues
Keywords: orchestration,agents,task-scheduling,workflows
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.14
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: isort>=5.13; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Dynamic: license-file

# orch-lib

A Python library for agent orchestration with task scheduling, conditional routing, and memory management.

## Features

- **Agent Orchestration**: Build complex multi-agent workflows with central coordination
- **Task Management**: Define and execute tasks with memory scoping
- **Conditional Routing**: Route task execution based on dynamic conditions
- **Memory Management**: Isolated and shared memory across agents and graphs
- **Graph Execution**: Coordinate multiple agents at the graph level
- **Expression Evaluation**: Evaluate dynamic expressions with memory access

## Installation

```bash
pip install orch-lib
```

## Quick Start

### Basic Agent Example

```python
from orch_lib import Agent, Task, Memory

# Create an agent
agent = Agent(name="worker")

# Define a task
def process_data(scope=None):
    scope["private"]["result"] = "processed"
    return scope["private"]["result"]

task = Task("process", process_data)

# Add task to agent
agent.add_task("process", task)
agent.add_route("process", "on_start")

# Execute agent
agent()
```

### Agent with Conditional Routing

```python
from orch_lib import Agent, Task, Conditional, Memory

agent = Agent(memory=Memory())
agent.memory.store("should_run", True)

def task_fn(*args, scope=None):
    print("Task executed!")

agent.add_task("work", Task("work", task_fn))
agent.add_route("work", Conditional("private['should_run']"))

agent(max_passes=2)
```

### Graph-Level Orchestration

```python
from orch_lib import Graph, Agent, Task, Conditional

graph = Graph()

# Create agents
agent1 = Agent()
agent2 = Agent(parent=graph)

# Configure agents with tasks and routes
# ... (add tasks and routes as shown above)

# Add to graph
graph.add_agent("agent1", agent1)
graph.add_agent("agent2", agent2)

# Execute graph
graph()
```

## Core Concepts

### Memory

Agents and graphs maintain isolated memory spaces:

- **Private Memory**: Agent-level memory not accessible to other agents
- **Public Memory**: Graph-level memory accessible to all agents
- **Agent Memory**: Per-agent memory in graph context

### Tasks

Tasks are callable units of work:

```python
task = Task(
    name="my_task",
    function=my_function,
    memories={"key": "value"}  # task-level memory
)
```

### Conditionals

Routes can be conditional:

```python
condition = Conditional("private['flag'] and public['enabled']")
agent.add_route("task_id", condition)
```

### Expressions

Evaluate expressions with memory context:

```python
from orch_lib import Expression

expr = Expression("count + 1")
result = expr(parent={"count": 5})
```

## API Reference

### Agent

```python
Agent(
    tasks=None,           # dict of Task objects
    memory=None,          # Memory object
    routes=None,          # dict of routes
    name=None,            # agent name
    parent=None,          # parent memory reference
    max_passes=10         # max execution passes
)
```

### Task

```python
Task(
    name: str,
    function: Callable,
    memories: dict = None
)
```

### Conditional

```python
Conditional(
    condition: str,       # Python expression string
    parent=None           # parent memory reference
)
```

### Memory

```python
Memory(agents=None)
```

Methods: `store()`, `retrieve()`, `delete()`, `clear()`, `clear_agent_memory()`

### Graph

```python
Graph(
    agents=None,          # dict of Agent objects
    memory=None,          # Memory object
    routes=None,          # dict of conditional routes
    max_passes=10         # max execution passes
)
```

## Development

### Setup

```bash
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Code Quality

```bash
black src/
ruff check src/
mypy src/
```

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.
