atron 1.0.1
High-performance, framework-agnostic Agent Orchestration Queue with Redis backend and Human-in-the-Loop capabilities
License: MIT
Requires Python: >=3.8

# aTron - Agent Orchestration Queue

[![PyPI version](https://badge.fury.io/py/atron.svg)](https://badge.fury.io/py/atron)
[![Python Support](https://img.shields.io/pypi/pyversions/atron.svg)](https://pypi.org/project/atron/)
[![License](https://img.shields.io/github/license/atron-dev/atron.svg)](https://github.com/atron-dev/atron/blob/main/LICENSE)
[![Build Status](https://github.com/atron-dev/atron/workflows/CI/badge.svg)](https://github.com/atron-dev/atron/actions)

**aTron** is a high-performance, Redis-backed Agent Orchestration Queue designed for scalable multi-agent AI workflows with advanced Human-in-the-Loop (HIL) capabilities.

## 🚀 Key Features

### Core Orchestration
- **High-concurrency workflow management** supporting 10,000+ concurrent agent tasks
- **Framework-agnostic design** with generic adapter interface for integration with any agent framework
- **Sub-100ms latency** for workflow operations under load
- **Atomic state management** with Redis-backed checkpointing and state chaining

### Advanced Human-in-the-Loop (HIL)
- **Intra-agent HIL**: Criticality-driven pauses within individual agent workflows
- **Inter-agent HIL**: Manual review checkpoints between agent pipeline stages
- **Configurable criticality thresholds** for automated vs. manual decision points
- **Rich context delivery** for informed human decision-making

### Enterprise-Ready
- **Durable state persistence** with Redis AOF/RDB support
- **API-driven architecture** with security via API keys
- **Comprehensive audit logging** for compliance and debugging
- **Docker and Kubernetes deployment** support included

## 📦 Installation

```bash
# Install from PyPI
pip install atron

# Install with development dependencies
pip install atron[dev]

# Install with documentation tools
pip install atron[docs]
```

## 🏃 Quick Start

### 1. Start Redis
```bash
# Using Docker
docker run -d --name atron-redis -p 6379:6379 redis:7-alpine redis-server --appendonly yes

# Or using Redis locally
redis-server --appendonly yes
```

### 2. Basic Workflow Example
```python
import asyncio
from atron import aTron, Workflow, Agent

# Initialize aTron
atron = aTron(redis_url="redis://localhost:6379")

# Define a simple agent
async def my_agent(input_data):
    # Your agent logic here
    return {"result": f"Processed: {input_data}"}

# Create and submit workflow
workflow = Workflow(
    name="example_workflow",
    agents=[Agent(name="processor", func=my_agent)],
    criticality_threshold=0.7  # HIL threshold
)

# Submit and monitor
workflow_id = await atron.submit_workflow(workflow, {"data": "Hello World"})
result = await atron.get_workflow_result(workflow_id)
print(f"Workflow result: {result}")
```

### 3. Human-in-the-Loop Example
```python
# Agent with criticality-driven HIL
async def critical_agent(input_data):
    # High criticality score triggers HIL pause
    criticality_score = 0.9  # Above threshold
    
    if criticality_score > workflow.criticality_threshold:
        # Workflow will pause for human input
        human_input = await atron.request_human_input(
            context="Critical decision needed",
            options=["approve", "reject", "modify"]
        )
        return process_with_human_input(input_data, human_input)
    
    return process_automatically(input_data)
```

## 🏗️ Architecture Overview

aTron's architecture is built around Redis as the exclusive broker and state store:

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Agent Tasks   │───▶│  Orchestration  │───▶│   Redis Broker  │
│                 │    │     Engine      │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ HIL Interface   │◀───│ State Management│◀───│  Output Store   │
│                 │    │ & Checkpointing │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

### Core Components

1. **Orchestration Engine**: High-concurrency task scheduling and workflow lifecycle management
2. **State Management**: Atomic checkpointing with state chaining for pause/resume functionality
3. **Output Key-Value Store**: Configurable output storage with TTL and aggregation support
4. **HIL System**: Both intra-agent (criticality-driven) and inter-agent (pipeline) human controls
5. **Criticality Engine**: Heuristic scoring system for automated HIL trigger decisions
6. **Redis Broker Interface**: Optimized Redis integration with connection pooling and failover

## 🔧 Configuration

### Environment Variables
```bash
# Redis Configuration
ATRON_REDIS_URL=redis://localhost:6379
ATRON_REDIS_DB=0
ATRON_REDIS_PASSWORD=your_password

# API Configuration
ATRON_API_KEY=your_api_key
ATRON_API_PORT=8000

# HIL Configuration
ATRON_DEFAULT_CRITICALITY_THRESHOLD=0.7
ATRON_HIL_TIMEOUT=300

# Performance
ATRON_WORKER_CONCURRENCY=100
ATRON_REDIS_POOL_SIZE=20
```

### Configuration File (atron.yml)
```yaml
redis:
  url: "redis://localhost:6379"
  db: 0
  pool_size: 20
  
orchestration:
  worker_concurrency: 100
  max_retry_attempts: 3
  
hil:
  default_criticality_threshold: 0.7
  timeout_seconds: 300
  
outputs:
  default_ttl: 3600
  cleanup_interval: 300
  
logging:
  level: "INFO"
  format: "json"
```

## 🚀 Deployment

### Docker
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["atron-server", "--config", "/app/config/atron.yml"]
```

### Kubernetes
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: atron-orchestrator
spec:
  replicas: 3
  selector:
    matchLabels:
      app: atron
  template:
    metadata:
      labels:
        app: atron
    spec:
      containers:
      - name: atron
        image: atron:latest
        env:
        - name: ATRON_REDIS_URL
          value: "redis://redis-service:6379"
        ports:
        - containerPort: 8000
```

## 🧪 Testing

```bash
# Run unit tests
pytest tests/unit/

# Run integration tests (requires Redis)
pytest tests/integration/

# Run performance tests
pytest tests/performance/

# Generate coverage report
pytest --cov=atron --cov-report=html
```

## 📚 Documentation

- [**API Reference**](docs/api.md) - Complete API documentation
- [**Agent Integration Guide**](docs/integrations.md) - Framework-agnostic integration examples
- [**HIL Best Practices**](docs/hil-guide.md) - Human-in-the-loop implementation patterns
- [**Deployment Guide**](docs/deployment.md) - Production deployment recommendations
- [**Performance Tuning**](docs/performance.md) - Optimization and scaling guidelines

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup
```bash
git clone https://github.com/atron-dev/atron.git
cd atron
pip install -e .[dev]
pre-commit install
```

## 📄 License

aTron is released under the MIT License. See [LICENSE](LICENSE) for details.

## 🆘 Support

- **Documentation**: [https://atron.dev/docs](https://atron.dev/docs)
- **Issues**: [GitHub Issues](https://github.com/atron-dev/atron/issues)
- **Discussions**: [GitHub Discussions](https://github.com/atron-dev/atron/discussions)
- **Discord**: [aTron Community](https://discord.gg/atron)

---

**aTron** - Orchestrating the future of multi-agent AI workflows 🤖✨