Instinct - Sistema de Orquestación de Agentes

Sistema de orquestación de agentes en Python con soporte para ejecución paralela, secuencial y condicional.

Requisitos

• Python 3.10 o superior
• pip

Instalación

1. Crear entorno virtual

Windows:

python -m venv venv
venv\Scripts\activate

Linux/Mac:

python3 -m venv venv
source venv/bin/activate

2. Instalar dependencias

pip install -r requirements.txt

3. Configurar variables de entorno

cp .env.example .env

Edita el archivo .env según tus necesidades.

Estructura del Proyecto

instinct/
├── src/
│   └── instinct/
│       ├── __init__.py
│       ├── agent.py          # Clase base para agentes
│       ├── orchestrator.py   # Orquestador principal
│       └── config.py          # Configuración del sistema
├── tests/
│   ├── __init__.py
│   └── test_orchestrator.py   # Tests del sistema
├── examples/
│   └── basic_example.py       # Ejemplo básico de uso
├── .env.example               # Plantilla de configuración
├── requirements.txt           # Dependencias
└── README.md

Uso Básico

Crear un Agente

from src.instinct.agent import Agent, AgentResult
import asyncio

class MiAgente(Agent):
    async def execute(self, input_data=None):
        # Tu lógica aquí
        return AgentResult(
            success=True,
            data="Resultado del procesamiento"
        )

# Crear instancia
agente = MiAgente("mi_agente", "Mi Agente Personalizado")

Usar el Orquestador

from src.instinct.orchestrator import Orchestrator
import asyncio

async def main():
    # Crear orquestador
    orchestrator = Orchestrator()
    
    # Registrar agentes
    orchestrator.register_agent(agente1)
    orchestrator.register_agent(agente2)
    
    # Ejecutar un agente
    result = await orchestrator.execute_agent("mi_agente", input_data="datos")
    
    # Ejecutar en paralelo
    results = await orchestrator.execute_parallel([
        {"agent_id": "agente1", "input_data": "data1"},
        {"agent_id": "agente2", "input_data": "data2"},
    ])
    
    # Ejecutar en secuencia
    results = await orchestrator.execute_sequence([
        {"agent_id": "agente1", "input_data": "inicial"},
        {"agent_id": "agente2"},  # Recibe resultado del anterior
    ], pass_result=True)

asyncio.run(main())

Ejecutar Ejemplos

python examples/basic_example.py

Macrocosmos (ingesta on-demand)

Módulo macrocosmos_client.py: solo ingesta de datos (query_on_demand_data). Sin Gravity, scheduling ni almacenamiento.

Dependencias necesarias:

• macrocosmos (API SN13 OnDemand)
• python-dotenv

Instalar con el proyecto: pip install -e . (pyproject.toml ya incluye macrocosmos). O solo:

pip install macrocosmos python-dotenv

Configuración: MC_API en .env (clave de Macrocosmos). Para el agente por instrucciones también CHUTES_API_TOKEN (Chutes LLM).

Agente por instrucciones (Macrocosmos MCP):

El agente interpreta órdenes en lenguaje natural, traduce a llamadas MCP (OnDemand + Gravity) y ejecuta.

• Herramientas: query_on_demand_data, create_gravity_task, get_gravity_task_status, build_dataset, get_dataset_status, cancel_gravity_task, cancel_dataset.
• Uso CLI:

  python run_macrocosmos_agent.py "Dame 20 tweets sobre #Bittensor"
  python run_macrocosmos_agent.py   # modo interactivo

• Uso en código:

  from macrocosmos_agent import run
  result = run("Posts de r/bittensor sobre dTAO, límite 50")
  print(result)

Ejemplo mínimo (async):

python examples/macrocosmos_example.py

import asyncio
from macrocosmos_client import query_social_data

async def main():
    data = await query_social_data(source="X", keywords=["AI"], limit=10)
    for item in data:
        print(item["texto"], item["timestamp"], item["autor"])

asyncio.run(main())

Ejecutar Tests

pytest tests/

Cliente de Inferencia API

Este proyecto también incluye un cliente para conectar con diferentes proveedores de inferencia (OpenAI, Anthropic, APIs personalizadas).

Uso del Cliente de Inferencia

from inference_client import create_client

client = create_client(provider="openai")

messages = [
    {"role": "user", "content": "Hola, ¿cómo estás?"}
]

response = client.chat_completion(messages=messages)
text = client.get_response_text(response)
print(text)

Ver example_usage.py para más ejemplos del cliente de inferencia.

Bot de Telegram (Intelligence Bot)

Sistema de orquestación controlado por Telegram que ejecuta el pipeline completo:

1. Consulta Macrocosmos MCP para obtener datos
2. Análisis inicial con Chutes API
3. Meta-análisis con Chutes API
4. Reporte estructurado vía Telegram

Inicio Rápido

# 1. Configurar .env con:
#    TELEGRAM_BOT_TOKEN=tu_token (obtener de @BotFather)
#    MC_API=tu_api_key_macrocosmos
#    CHUTES_API_TOKEN=tu_token_chutes

# 2. Instalar dependencias
pip install -r requirements.txt

# 3. Ejecutar el bot
python run_telegram_bot.py

Comandos Disponibles

• /start - Mensaje de bienvenida y comandos
• /analyze <topic> - Analiza un tema (ej: /analyze #Bittensor)
• /contracts <agency|region> - Analiza contratos (ej: /contracts NASA)
• /status - Estado del bot y servicios

Ver TELEGRAM_BOT_SETUP.md para documentación completa.

Configuración

El sistema se configura mediante variables de entorno en el archivo .env:

• DEBUG: Modo debug (True/False)
• LOG_LEVEL: Nivel de logging (DEBUG, INFO, WARNING, ERROR)
• DEFAULT_TIMEOUT: Timeout por defecto en segundos
• AGENT_TIMEOUT: Timeout para agentes en segundos
• MAX_PARALLEL_AGENTS: Máximo de agentes en paralelo
• MAX_RETRIES: Número máximo de reintentos
• TELEGRAM_BOT_TOKEN: Token del bot de Telegram (ver TELEGRAM_BOT_SETUP.md)
• MC_API o MACROCOSMOS_API_KEY: Clave API de Macrocosmos
• CHUTES_API_TOKEN: Token de la API de Chutes

Características

• ✅ Ejecución paralela de agentes
• ✅ Ejecución secuencial con paso de datos
• ✅ Ejecución condicional con reintentos
• ✅ Gestión de estado de agentes
• ✅ Historial de ejecuciones
• ✅ Sin frameworks innecesarios (solo biblioteca estándar + dependencias mínimas)

Desarrollo

El proyecto usa:

• asyncio para programación asíncrona (biblioteca estándar)
• typing para type hints (biblioteca estándar)
• pytest para testing
• python-dotenv para gestión de variables de entorno