Behemot Framework

Framework modular para crear asistentes IA multimodales

La filosofía es simple: el framework proporciona el motor; tú proporcionas la personalidad (configuración) y las habilidades (herramientas).

🚀 Inicio Rápido

Paso 1: Crear el Proyecto

# Crear directorio del proyecto
mkdir mi_asistente
cd mi_asistente

# Crear entorno virtual
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

Paso 2: Instalar Behemot Framework

Instala solo el core (modelos OpenAI + API REST):

pip install behemot-framework

O añade los extras que necesites:

pip install "behemot-framework[rag]"          # Retrieval-Augmented Generation
pip install "behemot-framework[voice]"        # Transcripción Whisper
pip install "behemot-framework[gemini]"       # Google Gemini
pip install "behemot-framework[gradio]"       # Interfaz local de pruebas
pip install "behemot-framework[rag,voice,gradio]"   # Combinables
pip install "behemot-framework[all]"          # Todo

También puedes instalar desde el repositorio (siempre la última versión):

pip install git+https://github.com/hernandezbg/behemot_framework.git

Paso 3: Generar Estructura del Proyecto

behemot-admin create-agent mi_asistente

Este comando crea automáticamente:

• config/mi_asistente.yaml - Configuración del asistente
• tools/ - Directorio para herramientas personalizadas
• main.py - Punto de entrada principal
• .env.example - Plantilla de variables de entorno
• README.md - Documentación del proyecto

Paso 4: Configurar Variables de Entorno

cp .env.example .env
# Editar .env con tus API keys

Paso 5: Ejecutar tu Asistente

python main.py

¡Tu asistente estará corriendo en http://localhost:8000!

🛠️ Personalización Avanzada

Configuración del Asistente

Edita config/mi_asistente.yaml para personalizar tu asistente:

# Configuración del modelo
MODEL_PROVIDER: "openai"  # openai, gemini, vertex
MODEL_NAME: "gpt-4o-mini"

# Prompt del sistema - Define la personalidad de tu asistente
PROMPT_SISTEMA: |
  Eres un asistente especializado en [tu dominio].
  Siempre eres amable, preciso y útil.
  
# Configuración de seguridad
SAFETY_LEVEL: "medium"  # low, medium, high

# RAG (Retrieval Augmented Generation) - Conocimiento personalizado
ENABLE_RAG: true
RAG_FOLDERS: ["./docs"]  # Carpetas locales, gcp://bucket/path, s3://bucket/key
RAG_EMBEDDING_PROVIDER: "openai"  # openai, google, huggingface

Crear Herramientas Personalizadas

Las herramientas son las "habilidades" de tu asistente. Créalas en el directorio tools/:

tools/mi_herramienta.py:

from behemot_framework.tooling import tool, Param

@tool(
    "mi_herramienta",
    "Descripción de lo que hace la herramienta",
    [
        Param("parametro", "string", "Descripción del parámetro", required=True)
    ]
)
async def mi_herramienta(args: dict):
    # El framework siempre llama al handler con el dict completo de argumentos
    parametro = args["parametro"]
    return f"Resultado procesando: {parametro}"

Luego agrégala a main.py:

app = create_behemot_app(
    # ... otras configuraciones
    use_tools=["mi_herramienta"],  # Agregar aquí
)

Habilitar RAG (Conocimiento Personalizado)

Agrega documentos a tu asistente para que responda basándose en tu contenido:

# En config/mi_asistente.yaml
ENABLE_RAG: true
RAG_FOLDERS: ["./docs", "gcp://mi-bucket/documentos", "s3://bucket/archivos"]

Formatos soportados: PDF, TXT, Markdown, CSV, URLs El asistente leerá automáticamente todo el contenido y podrá responder preguntas sobre tus documentos.

Habilitar Canales de Comunicación

En main.py, activa los canales que necesites:

app = create_behemot_app(
    enable_api=True,          # API REST
    enable_telegram=True,     # Bot de Telegram
    enable_whatsapp=True,     # WhatsApp Business
    enable_google_chat=True,  # Google Chat
    enable_voice=True,        # Procesamiento de voz
    enable_test_local=True,   # Interfaz de prueba local con Gradio
    config_path="config/mi_asistente.yaml",
)

Interfaz de Prueba Local

Para probar tu asistente de forma visual antes de desplegarlo:

# En main.py
app = create_behemot_app(
    enable_test_local=True,   # Activar interfaz visual
    config_path="config/mi_asistente.yaml",
)

Esto creará una interfaz web en http://localhost:7860 con:

• 💬 Chat interactivo con tema oscuro - Interfaz moderna y elegante
• 🎤 Entrada de voz - Si enable_voice=True
• 🔧 Panel de herramientas - Ve las herramientas disponibles
• ⚙️ Configuración - Revisa la configuración actual
• 🌐 Compartir públicamente - Configura GRADIO_SHARE=true para obtener URL pública

Configurar acceso público (opcional)

# En config/mi_asistente.yaml
GRADIO_SHARE: true

O con variable de entorno:

export GRADIO_SHARE=true
python main.py

Configurar Filtro de Seguridad

El framework incluye un filtro de seguridad configurable para proteger contra contenido inapropiado:

# En config/mi_asistente.yaml
SAFETY_LEVEL: "medium"  # off, low, medium, high

Niveles disponibles:

• "off" - Filtro deshabilitado - Permite todo el contenido
• "low" - Muy permisivo - Solo bloquea contenido extremadamente peligroso
• "medium" - Equilibrado (recomendado) - Bloquea contenido inapropiado, permite conversación normal
• "high" - Estricto - Filtrado más riguroso para entornos sensibles

Nota: El filtro permite automáticamente conversaciones normales como preguntas sobre nombres, edad, fechas, etc.

Control de Abuso

Activado por defecto en WhatsApp, Telegram, Google Chat y /api/chat. Corta los mensajes antes de transcribir o llamar al modelo, así que no consumen tokens. Cada valor se ajusta por variable de entorno o en el YAML, y 0 desactiva esa regla:

ABUSE_GUARD_ENABLED: true          # false apaga todo
ABUSE_RATE_LIMIT_PER_MINUTE: 30    # mensajes por usuario
ABUSE_REPEAT_MAX: 3                # repeticiones exactas consecutivas permitidas
ABUSE_REPEAT_WINDOW_SECONDS: 60
ABUSE_MAX_STRIKES: 3               # infracciones hasta el bloqueo temporal
ABUSE_STRIKE_WINDOW_SECONDS: 3600
ABUSE_BLOCK_SECONDS: 300           # duración del bloqueo
ABUSE_BLOCK_MESSAGE: "Recibimos muchos mensajes seguidos. Esperá unos minutos y volvé a escribirnos."
ABUSE_BLACKLIST: []                # IDs o números bloqueados, sin aviso
ABUSE_INSULT_WORDS: []             # vacío = filtro de insultos desactivado
ABUSE_USER_DAILY_LIMIT: 0          # mensajes por usuario en 24 horas; 0 = sin tope
ABUSE_GLOBAL_DAILY_LIMIT: 0        # mensajes de todo el agente en 24 horas; 0 = sin tope
ABUSE_DAILY_LIMIT_MESSAGE: "Por ahora no podemos seguir respondiendo. Volvé a escribirnos más tarde."
MAX_HISTORY_MESSAGES: 20           # historial enviado al modelo y guardado; 0 = sin recorte

Al alcanzar ABUSE_GLOBAL_DAILY_LIMIT, el bot deja de llamar al modelo para todos los usuarios. Conviene calcularlo con el volumen real del agente.

MAX_HISTORY_MESSAGES hace que el bot olvide lo que quedó fuera de esa ventana.

El usuario recibe un solo aviso por incidente y después se lo ignora en silencio. Cada bloqueo queda en los logs con el prefijo AbuseGuard.

Configurar Sistema de Permisos

El framework incluye un sistema de permisos granular para comandos administrativos. Por defecto ningún usuario es admin — debes declarar explícitamente quién puede ejecutar comandos privilegiados.

# En config/mi_asistente.yaml
ADMIN_MODE: "production"  # default seguro

ADMIN_USERS:
  - user_id: "1069636329"        # Tu ID de usuario
    platform: "telegram"        # telegram, whatsapp, google_chat, api
    permissions: ["super_admin"] # super_admin, broadcast, user_management, system, rag_admin

Permisos disponibles:

• "user_info" - Ver información propia (&whoami)
• "broadcast" - Envío masivo (&sendmsg, &list_users)
• "user_management" - Gestión de usuarios (&delete_session, &list_sessions)
• "system" - Comandos de sistema (&status, &monitor, &clear_msg)
• "rag" - Consulta del sistema RAG (&rag_search, &rag_status)
• "rag_admin" - Reindexación RAG (&reindex_rag) — separado para minimizar superficie
• "super_admin" - Todos los comandos (acceso total)

Comandos útiles:

• &whoami - Ver tu ID de usuario y permisos actuales
• &help - Lista completa de comandos disponibles

🔐 Seguridad — Variables clave para producción

El framework aplica defaults seguros, pero hay variables que debes configurar antes de exponer un agente a internet:

# .env

# --- Webhooks firmados (CRÍTICO en producción) ---
TELEGRAM_WEBHOOK_SECRET=...        # auto-generado si falta (no persiste entre réplicas)
WHATSAPP_APP_SECRET=...            # del Meta Developer Console — sin esto el webhook acepta cualquier POST

# --- RAG anti-path-traversal / anti-SSRF ---
RAG_ALLOWED_ROOTS=./docs,./manuals       # paths permitidos para fuentes locales
RAG_ALLOWED_URL_HOSTS=docs.miempresa.com # whitelist opcional para URLs HTTP/HTTPS
# RAG_ALLOW_PRIVATE_NETWORKS=false       # default: rechaza IPs privadas/loopback/metadata cloud

# --- Endpoints expuestos ---
STATUS_API_TOKEN=...               # Bearer token para /status; sin esto queda abierto
API_AUTH_MODE=api_key              # none | api_key
API_KEYS=key-1,key-2               # solo si API_AUTH_MODE=api_key
API_RATE_LIMIT_PER_MINUTE=60       # 0 desactiva
API_MAX_REQUEST_SIZE=10485760      # 10MB
API_MAX_AUDIO_SIZE=26214400        # 25MB

# --- Privacidad de logs ---
LOG_REDACT_PII=true                # enmascara emails, teléfonos y tokens largos

Garantías que ofrece el framework:

Configurar Variables de Entorno

Edita tu archivo .env:

# OpenAI
GPT_API_KEY=sk-...

# Google Gemini (opcional)
GEMINI_API_KEY=AI...

# Google Vertex AI (opcional)
VERTEX_PROJECT_ID=mi-proyecto-gcp
VERTEX_LOCATION=us-central1

# Redis para persistencia (opcional)
REDIS_PUBLIC_URL=redis://localhost:6379

# Telegram (opcional)
TELEGRAM_TOKEN=...
TELEGRAM_WEBHOOK_URL=https://tu-dominio.com/webhook

# WhatsApp Business (opcional)
WHATSAPP_TOKEN=...
WHATSAPP_VERIFY_TOKEN=...
WHATSAPP_WEBHOOK_URL=https://tu-dominio.com/whatsapp-webhook

# API REST - Para plataformas web personalizadas (opcional)
API_WEBHOOK_URL=https://tu-plataforma-web.com/api

# Google Chat (opcional)
GC_PROJECT_ID=...
GC_PRIVATE_KEY=...
GC_CLIENT_EMAIL=...

🌟 Características

• 🤖 Múltiples Modelos IA: OpenAI GPT, Google Gemini y Vertex AI
• 📱 Múltiples Canales: API REST, Telegram, WhatsApp, Google Chat
• 🧠 RAG Integrado: Lee carpetas locales, GCP, S3, Google Drive automáticamente
• 🔧 Herramientas Extensibles: Sistema de plugins simple
• 🎤 Procesamiento de Voz: Transcripción automática de audio
• 🔒 Filtros de Seguridad: Contenido seguro por defecto (configurable)
• 👥 Sistema de Permisos: Control granular de acceso a comandos administrativos
• 📨 Mensajería Masiva: Envío de mensajes a todos los usuarios activos
• 💾 Persistencia de Contexto: Conversaciones continuas con Redis
• 📊 Diagnósticos: Monitoreo automático de componentes

📂 Ejemplos

El directorio examples/ contiene plantillas listas para arrancar:

Cada ejemplo es ejecutable directamente con python examples/<nombre>.py.

📚 Documentación Adicional

Para casos de uso avanzados, configuraciones especiales y ejemplos completos, consulta la documentación en el repositorio.

🤝 Contribuir

¡Las contribuciones son bienvenidas! Por favor:

1. Haz fork del repositorio
2. Crea una rama para tu feature
3. Haz commit de tus cambios
4. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.