feid-mas 0.1.2

Framework Experimental para Integracion de Datos (FEID) - Multi-Agent Systems

FEID-MAS: Agent Template for Multi-Agent Systems

Language / Idioma: English (README) | Español (README_ES)

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): MasterAgentNASA 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

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 (English) | SETUP_ES.md (Español)

Your First Agent

from feid.agent import MasterAgentNASA

class MyAgent(MasterAgentNASA):
    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)

from feid.agent import AgentFactory, MasterAgentNASA

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

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

# Industrial profile: maximum features, high-volume
agent = AgentFactory.industrial(MasterAgentNASA, 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 AgentConfig 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):

python samples/quickstart_agent.py

E2E Example (Hook + Middleware)

from feid.agent import MasterAgentNASA
from feid.core import MiddlewarePlugin

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

class DemoAgent(MasterAgentNASA):
    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

MasterAgentNASA (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 (English) | SETUP_ES.md (Español)

Main Index: INDEX.md (English) | INDEX_ES.md (Español)

English Documentation

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

Documentación en Español

• QUICKSTART_ES.md - Empieza en 5 minutos
• CONCEPTUAL_GUIDE_ES.md - Conceptos centrales y diseño
• PLUGINS_MIDDLEWARE.md - Hooks del ciclo de vida y middleware (complementario)
• PROTOCOL_GUIDE.md - Comunicación multiprotocolo (complementario)
• API_REFERENCE_ES.md - Documentación completa de la API
• ARCHITECTURE_ES.md - Diseño interno
• EXAMPLES_ES.md - Ejemplos de código
• TROUBLESHOOTING_ES.md - Guía de solución de problemas
• MULTIAGENT_SYSTEMS_ES.md - Sistemas multi-agente

Typical Workflow

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

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:

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:

from feid.core import AgentConfig

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

See PLUGINS_MIDDLEWARE.md for complete guide.

Testing

All 181 tests passing ✅

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 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 [samples/real_world_monitoring_agent.py](samples/real_world_monitoring_agent.py) para demostración completa de features.

```bash
python samples/real_world_monitoring_agent.py

Estado

Proyecto experimental (v0.1.0). Ver BACKLOG para roadmap y próximos pasos.

Autor

Leon Alberne Torres Restrepo

• GitHub: albernetr
• LinkedIn: leon-alberne-torres-restrepo
• Email: [e-mail]

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