Metadata-Version: 2.4
Name: anusara
Version: 1.1.3
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"
Requires-Dist: fastapi>=0.110.0; extra == "dev"
Requires-Dist: uvicorn>=0.29.0; extra == "dev"
Dynamic: license-file

# Anusara

**Deterministic execution 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](https://img.shields.io/pypi/v/anusara?label=PyPI&color=blue&cacheSeconds=60)](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.

---

## 🚀 Quickstart (2 minutes)

### Install

```bash
pip install anusara[api]
```

### Run the server

```bash
PYTHONPATH=src python -m uvicorn anusara.adapters.http.app:create_app --factory --reload
```

### Register agent

```bash
curl -X POST http://127.0.0.1:8000/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "hello"}'
```

### Execute

```bash
curl -X POST http://127.0.0.1:8000/executions \
  -H "Content-Type: application/json" \
  -d '{"entry_nodes": ["hello"]}'
```

👉 You just ran your first deterministic workflow.

➡️ Full guide: `docs/guides/http-api-quickstart.md`

---

## 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  

---

## 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 |
| Registry | agent lifecycle & resolution |
| Router | execution decision logic |
| Mutation Engine | controlled graph evolution |
| Observability | debugging, metrics, visualization |

---

## Local Python Example

```python
import asyncio
from anusara import ExecutionEngine, ExecutionRequest, AgentRegistry

engine = ExecutionEngine()

registry = AgentRegistry()
registry.register("hello", HelloAgent())

request = ExecutionRequest(
    request_id="demo",
    entry_nodes=["hello"],
    payload={},
    metadata={},
)

asyncio.run(engine.execute(request, registry))
```

---

## Key Features

- deterministic execution  
- event-sourced execution history  
- replayable workflows  
- HTTP + CLI + Python runtime  
- agent lifecycle management  
- built-in observability  
- controlled workflow mutation  

---

## Documentation

### 🚀 Getting Started

- `docs/guides/http-api-quickstart.md`
- `docs/guides/running-anusara-locally.md`
- `docs/guides/creating-your-first-agent.md`

### 📚 Concepts

- agents  
- deterministic execution  
- event sourcing  
- replay  

### 🏗 Architecture

- execution model  
- runtime architecture  
- event log  
- mutation model  

### 📖 Reference

- HTTP API  
- agent registry  
- execution engine  

---

## Project Status

Anusara is under active development.

Current focus:

- developer experience (HTTP API & usability)  
- onboarding and documentation  
- production readiness  

---

## Contributing

Contributions and discussions are welcome.

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

---

## License

MIT License
