Metadata-Version: 2.4
Name: anusara
Version: 1.0.0
Summary: Deterministic execution engine with traceable, immutable history
Author: Nataraj Narayana
License: MIT
Project-URL: Homepage, https://github.com/Nataraj-Narayana/anusara
Project-URL: Repository, https://github.com/Nataraj-Narayana/anusara
Project-URL: Issues, https://github.com/Nataraj-Narayana/anusara/issues
Keywords: deterministic-execution,event-sourcing,workflow-engine,orchestration,traceability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: api
Requires-Dist: fastapi>=0.110.0; extra == "api"
Requires-Dist: uvicorn>=0.29.0; extra == "api"
Provides-Extra: observability
Requires-Dist: opentelemetry-api==1.39.1; extra == "observability"
Requires-Dist: opentelemetry-sdk==1.39.1; extra == "observability"
Requires-Dist: opentelemetry-exporter-otlp==1.39.1; extra == "observability"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: pytest-repeat; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# Anusara

**Deterministic orchestration runtime for agent workflows.**

[![CI](https://github.com/Nataraj-Narayana/anusara/actions/workflows/ci.yml/badge.svg)](https://github.com/Nataraj-Narayana/anusara/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/anusara.svg)](https://pypi.org/project/anusara/)
[![Python Versions](https://img.shields.io/pypi/pyversions/anusara.svg)](https://pypi.org/project/anusara/)
[![License](https://img.shields.io/github/license/Nataraj-Narayana/anusara.svg)](LICENSE)
![Architecture](https://img.shields.io/badge/architecture-event--sourced%20runtime-blue)

---

## What is Anusara?

**Anusara is a deterministic runtime for executing agent workflows.**

It executes graphs of agents using:

- deterministic scheduling  
- event-sourced execution history  
- replay-driven state reconstruction  

Every execution becomes:

- replayable  
- inspectable  
- debuggable  
- reproducible  

Anusara treats workflow execution as a **runtime system problem**, not a
collection of loosely connected function calls.

---

## The Mental Model

```text
Agent Graph
     ↓
Deterministic Execution Engine
     ↓
Event Log (source of truth)
     ↓
Replay • Debug • Observability
```

Execution is not hidden state.

It is a **recorded, replayable system**.

---

## Why Anusara?

Most agent orchestration systems rely on implicit runtime behavior.

This leads to:

- nondeterministic execution  
- difficult debugging  
- hidden state transitions  
- unreliable retries  
- poor reproducibility  

Anusara solves this by enforcing:

- deterministic execution  
- event log authority  
- replay-based debugging  
- explicit lifecycle guarantees  

---

## Design Philosophy

```text
Anusara = Deterministic Event-Sourced Execution Runtime
```

Not just orchestration.  
Not just workflows.

A **runtime system for reliable execution**.

---

## Architecture Overview

```mermaid
flowchart LR

Client[Client / API / CLI]
Client --> Runtime

Runtime[Execution Runtime]

Runtime --> Graph[Graph Compiler]
Runtime --> Registry[Agent Registry]
Runtime --> Router[Router]
Runtime --> Mutation[Mutation Engine]

Runtime --> EventLog[(Event Log)]

EventLog --> Replay[Replay Engine]
EventLog --> Debugger[Debugger / Analysis]

Runtime --> Observability[Observability]
```

---

## Core Responsibilities

| Layer | Responsibility |
|------|------|
| Runtime | deterministic execution of workflows |
| Event Log | authoritative execution history |
| Router | execution decision logic |
| Mutation Engine | controlled graph evolution |
| Registry | agent discovery and lifecycle |
| Observability | debugging, metrics, visualization |

---

## Quick Start

Install:

```bash
pip install anusara
```

Minimal example:

```python
from anusara import ExecutionEngine, GraphDefinition

graph = GraphDefinition(
    nodes=[
        {"id": "A", "agent": agent_a},
        {"id": "B", "agent": agent_b},
    ],
    edges=[("A", "B")]
)

engine = ExecutionEngine()
result = engine.run(graph, input_data)
```

The runtime handles:

- scheduling  
- retries  
- event logging  
- replay  
- observability  

---

## Execution Graph

Workflows are defined as directed graphs.

```mermaid
graph LR
    A --> B
    A --> C

    subgraph Wave_0
        A
    end

    subgraph Wave_1
        B
        C
    end
```

Execution proceeds in deterministic waves.

---

## Key Features

- deterministic execution  
- event-sourced execution history  
- replayable workflows  
- graph-based orchestration  
- built-in observability  
- runtime debugging tools  
- controlled workflow mutation  

---

## Documentation

Documentation is available in the `docs/` directory.

### Concepts

- deterministic execution  
- event sourcing  
- execution waves  
- replay  

### Guides

- building workflows  
- running executions  
- debugging with replay  

### Architecture

- execution model  
- routing model  
- state machine  
- replay model  
- mutation model  

### Roadmap

See: `docs/roadmap.md`

---

## Project Status

Anusara is under active development.

Current focus:

- developer experience (API & usability)  
- onboarding workflows  
- improved tooling  

---

## Contributing

Contributions and discussions are welcome.

- CONTRIBUTING.md  
- CODE_OF_CONDUCT.md  
- SECURITY.md  

---

## License

MIT License
