# FEID-MAS: Agent Template for Multi-Agent Systems

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

**FEID-MAS** is a **template library** to create agents fast (in ~5 lines) and consistently. It is **not a framework**. It is the **first part of a trilogy** of templates that together will enable full MAS construction:

- **Agent** (this repo): `AgenteMaestroNASA` and agent scaffolding
- **Environment** (pending): provides the shared space where agents live and interact
- **Protocols** (pending): handles cross‑agent communication

This library can be **embedded by existing frameworks** to speed up agent creation.

## Scope and boundaries

FEID-MAS **only delivers an embeddable agent** ready to operate inside a project (pure Python or a framework). It **does not** cover full MAS design, inter‑agent infrastructure, or fleet lifecycle orchestration.

- ✅ **In scope**: a standalone, embeddable agent; local execution; extensibility (hooks/middleware); resilience (retries, circuit breaker, DLQ); local observability (metrics/audit).
- ❌ **Out of scope**: MAS architecture, distributed inter‑agent communication, fleet supervision, external brokers.

Production readiness should be evaluated for the **embedded agent**, not for a distributed MAS (which must be provided by the host project).

## Overview

FEID-MAS provides a practical agent template 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
git clone https://github.com/albernetr/feid.git
cd feid
pip install -e .           # Basic install
pip install -e ".[test]"   # With test dependencies
```

**Setup & Troubleshooting**: [SETUP.md](SETUP.md) (English) | [SETUP_ES.md](SETUP_ES.md) (Español)

### 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, high-volume
agent = AgenteFactory.industrial(AgenteMaestroNASA, name="IndustrialAgent")
```

## 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 |
| **Lifecycle Hooks** | Extend agent behavior | Monitoring, logging, custom workflows |
| **Middleware Pipeline** | Transform messages | Encryption, validation, tracing |
| **Protocol Strict Mode** | Formal validation (opt-in) | FIPA/KQML compliance, research |

## 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: High-volume workloads
- Queue: 10,000 items | Workers: 8 | Retries: 5
- Maximum features (circuit breaker, anti-starvation, security)

## Agent Identity Profile (Optional)

You can define a human‑like identity without mixing it with logic. Configure `AgentProfile` in `ConfigAgente` to describe:

- `display_name`: public name
- `role`: primary role (e.g., analyst, operator)
- `skills`: list of skills
- `specialties`: deep expertise areas
- `limitations`: boundaries or exclusions
- `tags`: searchable labels

## Features: Real vs Planned

| Area | Real (This Repo) | Planned (Trilogy) |
|------|------------------|------------------|
| Agent template | ✅ Implemented | ✅ Core of trilogy |
| Hooks & middleware | ✅ Implemented | ✅ Shared patterns |
| Protocol strict mode | ✅ Implemented | ➖ |
| Environment (space) | ➖ | 🕒 Pending |
| Inter-agent protocols | ➖ | 🕒 Pending |
| Distributed MAS runtime | ➖ | 🕒 Pending |

## Production Readiness Levels

| Level | Scope | What it means |
|-------|-------|---------------|
| A — Template Stable | Single node | Core APIs stable, shutdown/metrics/hooks tested |
| B — Single‑Node Production | Single node | Hard timeouts, rate limits, audit, clear limits |
| C — Distributed MAS | Multi‑node | Brokers, inter‑process protocols (out of scope) |

## Benchmark (Short, Reproducible)

This is a **reference** run, not a guarantee. Variables you should record:
CPU, workers, payload size, `backpressure_threshold`, `ciclo_timeout_segundos`.

Example command (short run):

```bash
python samples/quickstart_agent.py
```

## E2E Example (Hook + Middleware)

```python
from feid.agent import AgenteMaestroNASA
from feid.core import MiddlewarePlugin

class UppercaseMiddleware(MiddlewarePlugin):
    def before(self, task, context):
        return str(task).upper()

class DemoAgent(AgenteMaestroNASA):
    def _technical_work(self, task):
        return f"ok:{task}"

agent = DemoAgent("Demo")
agent.add_middleware(UppercaseMiddleware())

def on_received(payload):
    print("received", payload["task_id"], payload["task"])

agent.register_hook("on_task_received", on_received)
agent.send_task("hola")
agent.graceful_shutdown()
```

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

**Installation & Setup**: [SETUP.md](SETUP.md) (English) | [SETUP_ES.md](SETUP_ES.md) (Español)

**Main Index**: [INDEX.md](docs/INDEX.md) (English) | [INDEX_ES.md](docs/INDEX_ES.md) (Español)

### English Documentation
- **[QUICKSTART.md](docs/QUICKSTART.md)** - Get started in 5 minutes
- **[CONCEPTUAL_GUIDE.md](docs/CONCEPTUAL_GUIDE.md)** - Core concepts and design
- **[PLUGINS_MIDDLEWARE.md](docs/PLUGINS_MIDDLEWARE.md)** - Lifecycle hooks & middleware pipeline
- **[PROTOCOL_GUIDE.md](docs/PROTOCOL_GUIDE.md)** - Multi-protocol communication & strict mode
- **[API_REFERENCE.md](docs/API_REFERENCE.md)** - Complete API documentation
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - Internal design
- **[EXAMPLES.md](docs/EXAMPLES.md)** - Code examples
- **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Problem-solving guide
- **[MULTIAGENT_SYSTEMS.md](docs/MULTIAGENT_SYSTEMS.md)** - Building multi-agent systems

### Documentación en Español
- **[QUICKSTART_ES.md](docs/QUICKSTART_ES.md)** - Empieza en 5 minutos
- **[CONCEPTUAL_GUIDE_ES.md](docs/CONCEPTUAL_GUIDE_ES.md)** - Conceptos centrales y diseño
- **[PLUGINS_MIDDLEWARE.md](docs/PLUGINS_MIDDLEWARE.md)** - Hooks del ciclo de vida y middleware (complementario)
- **[PROTOCOL_GUIDE.md](docs/PROTOCOL_GUIDE.md)** - Comunicación multiprotocolo (complementario)
- **[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
- **[EXAMPLES_ES.md](docs/EXAMPLES_ES.md)** - Ejemplos de código
- **[TROUBLESHOOTING_ES.md](docs/TROUBLESHOOTING_ES.md)** - Guía de solución de problemas
- **[MULTIAGENT_SYSTEMS_ES.md](docs/MULTIAGENT_SYSTEMS_ES.md)** - Sistemas multi-agente

## 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")
```

### Advanced Features

**Lifecycle Hooks** - Extend agent behavior:
```python
def on_task_complete(context):
    print(f"Task {context['task_id']} completed in {context['duration']:.2f}s")

agent.register_hook('on_task_completed', on_task_complete)
```

**Middleware Pipeline** - Transform messages:
```python
from feid.core import MiddlewarePlugin

class LoggingMiddleware(MiddlewarePlugin):
    def before_task(self, task):
        print(f"→ {task}")
        return task

agent.add_middleware(LoggingMiddleware())
```

**Protocol Strict Mode** - Formal validation:
```python
from feid.core import ConfigAgente

config = ConfigAgente(protocol_strict_mode=True)
agent = MyAgent("StrictAgent", config=config)
# Now validates FIPA/KQML/JSON-RPC messages formally
```

See [PLUGINS_MIDDLEWARE.md](docs/PLUGINS_MIDDLEWARE.md) for complete guide.

## Testing

All 181 tests passing ✅

```bash
pytest tests/ -v           # Run all tests
pytest tests/ -m "not slow" # Skip long-running tests
pytest tests/ --cov=feid   # With coverage report
```

See [SETUP.md](SETUP.md) for test configuration and running specific tests.

**Includes:**
- Unit tests (maestro, backlog features, stress tests)
- Integration tests (multi-protocol communication)
- Stress tests (1000+ tasks, concurrent processing)
- Soak tests (15-minute sustained load)

## Requirements

- **Python**: 3.10+
- **Dependencies**: None (stdlib only)
- **Test dependencies**: pytest, coverage, pytest-timeout, pytest-xdist (optional)

---

**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)
