# FEID-MAS: Enterprise-Grade Multi-Agent System Framework

**Language / Idioma**: [English (README)](README.md) | [Español (README_ES)](README_ES.md)

**FEID-MAS** (Framework for Enterprise Intelligent Distributed - Multi-Agent System) is a production-ready Python framework for building professional, scalable, and fault-tolerant autonomous agents.

## Overview

FEID-MAS provides a solid foundation for creating intelligent agents that can:

- **Process high-volume task queues** with priority handling and backpressure management
- **Tolerate failures** through circuit breakers, automatic retries, and exponential backoff
- **Scale horizontally** with rate limiting, metrics collection, and health probes
- **Communicate across protocols** (FIPA, KQML, JSON-RPC, SIMPLE)
- **Persist events** with automatic rotation and external handler callbacks
- **Maintain audit trails** with structured logging and incident tracking
- **Enforce security policies** with sandboxing and whitelist/denylist controls
- **Monitor performance** with real-time metrics, latency tracking, and error rates

## Quick Start (2 Minutes)

### Installation
```bash
pip install -e .
```

### Your First Agent
```python
from feid.agent import AgenteMaestroNASA

class MyAgent(AgenteMaestroNASA):
    def _technical_work(self, task):
        """Implement your business logic here"""
        return f"Processed: {task}"

# Create and use agent
agent = MyAgent("MyAgent")
agent.send_task("Hello World", priority=1)
agent.graceful_shutdown()
```

### Use Factory Profiles (Pre-configured)
```python
from feid.agent import AgenteFactory, AgenteMaestroNASA

# Quick profile: lightweight, testing
agent = AgenteFactory.quick(AgenteMaestroNASA, name="LightAgent")

# Standard profile: balanced, general-purpose
agent = AgenteFactory.standard(AgenteMaestroNASA, name="StandardAgent")

# Industrial profile: maximum features, production
agent = AgenteFactory.industrial(AgenteMaestroNASA, name="ProductionAgent")
```

## Key Features

| Feature | Benefit | Use Case |
|---------|---------|----------|
| **Priority Queue** | Control task execution order | Emergency/VIP task handling |
| **Circuit Breaker** | Prevent cascading failures | Fault tolerance |
| **Retry Strategy** | Automatic recovery | Transient errors |
| **Rate Limiting** | Control request flow | API integration |
| **Metrics & Monitoring** | Real-time visibility | Production observability |
| **Audit Logging** | Complete event trail | Compliance |
| **Multi-Protocol** | FIPA, KQML, JSON-RPC | Enterprise integration |
| **Security Sandbox** | Prevent malicious tasks | Untrusted input |
| **Health Probes** | Kubernetes-compatible | Container orchestration |

## Agent Profiles

### 🚀 Quick Profile
- Best for: Testing, prototyping
- Queue: 50 items | Workers: 1 | Retries: 1
- Minimal features

### ⚡ Standard Profile  
- Best for: General-purpose applications
- Queue: 500 items | Workers: 4 | Retries: 3
- Full features (metrics, audit, rate limiting)

### 🏭 Industrial Profile
- Best for: Production, high-volume
- Queue: 10,000 items | Workers: 8 | Retries: 5
- Maximum features (circuit breaker, anti-starvation, security)

## System Architecture

```
AgenteMaestroNASA (Orchestrator)
├── ProtocolAdapter (Multi-protocol)
├── EventSink (Persistence)
├── QueueManager (Validation & backpressure)
├── TaskProcessor (Execution & retry)
├── AgentRuntime (Lifecycle)
├── Facades (Simplified APIs)
│   ├── MetricsFacade
│   ├── SecurityFacade
│   └── HealthFacade
└── Enterprise
    ├── CircuitBreaker
    ├── RetryStrategy
    ├── RateLimiter
    └── Security
```

## Documentation

**Start here:** [Documentation Index (EN)](docs/INDEX.md) | [Índice de Documentación (ES)](docs/INDEX_ES.md)

### English
- **[CONCEPTUAL_GUIDE.md](docs/CONCEPTUAL_GUIDE.md)** - Core concepts and design
- **[MULTIAGENT_SYSTEMS.md](docs/MULTIAGENT_SYSTEMS.md)** - Building multi-agent systems
- **[EXAMPLES.md](docs/EXAMPLES.md)** - Code examples
- **[API_REFERENCE.md](docs/API_REFERENCE.md)** - Complete API documentation
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - Internal design
- **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Problem-solving guide

### Español
- **[CONCEPTUAL_GUIDE_ES.md](docs/CONCEPTUAL_GUIDE_ES.md)** - Conceptos centrales y diseño
- **[MULTIAGENT_SYSTEMS_ES.md](docs/MULTIAGENT_SYSTEMS_ES.md)** - Sistemas multi-agente
- **[EXAMPLES_ES.md](docs/EXAMPLES_ES.md)** - Ejemplos de código
- **[API_REFERENCE_ES.md](docs/API_REFERENCE_ES.md)** - Documentación completa de la API
- **[ARCHITECTURE_ES.md](docs/ARCHITECTURE_ES.md)** - Diseño interno
- **[TROUBLESHOOTING_ES.md](docs/TROUBLESHOOTING_ES.md)** - Guía de solución de problemas

## Typical Workflow

```python
# 1. Create agent
agent = MyAgent("WorkerAgent")

# 2. Send tasks
task_id = agent.send_task("process data", priority=1, ttl=30)

# 3. Monitor
metrics = agent.metrics.get_all()
print(f"Success rate: {1 - agent.metrics.get_error_rate():.2%}")

# 4. Graceful shutdown
stats = agent.graceful_shutdown(timeout=30)
print(f"Processed {stats['successful_tasks']} tasks")
```

## Testing

All 131 tests passing:
```bash
pytest tests/ -v
```

Includes:
- Unit tests (maestro, backlog features)
- Integration tests (multi-protocol communication)
- Stress tests (1000+ tasks, concurrent processing)

## Requirements

- Python 3.10+
- No external dependencies (stdlib only)

---

**FEID-MAS**: Enterprise intelligent agents, simplified.


# Enviar tarea con correlation ID (distributed tracing)
m_id = agente.enviar_orden(
    "procesar-datos",
    correlation_id="req-2024-001"
)

# Monitorear salud (incluye estado de circuit breaker y estrategia)
salud = agente.monitorear_salud()
```

## Documentación

- [Enterprise Features Guide](docs/enterprise_features.md) - Correlation IDs, Circuit Breaker, Retry Strategies
- [Handler Development](docs/handler_guide.md) - Integración con sistemas externos
- [Contributing](CONTRIBUTING.md) - Guía para contribuidores

## Ejemplos

Ver [examples/enterprise_demo.py](examples/enterprise_demo.py) para demostración completa de features.

```bash
python examples/enterprise_demo.py
```

## Estado
Proyecto experimental (v0.1.0). Ver [BACKLOG](BACKLOG.md) para roadmap y próximos pasos.

## Autor
**Leon Alberne Torres Restrepo**
- GitHub: [albernetr](https://github.com/albernetr)
- LinkedIn: [leon-alberne-torres-restrepo](https://www.linkedin.com/in/leon-alberne-torres-restrepo/)
- Email: albernetorres@gmail.com

## Disclaimer
Proyecto de desarrollo personal realizado en tiempo personal con equipos personales.
No afiliado ni respaldado por empleadores anteriores o actuales.
Proveido "como esta", sin garantias.

## Licencia
MIT License - Ver [LICENSE](LICENSE)
