NaliiaBot/docs/TOOLS_DOCUMENTATION_INDEX.md

📚 Índice de Documentación: Patrón Registry para Tools

Bienvenido al sistema de Tools de NaliiaBot usando el patrón Registry.

🚀 Comienza por aquí

Si es tu primer día con esto:

1. QUICK_START.py ⭐ (5 minutos)

   • Tutorial interactivo paso a paso
   • Ejemplo simple que funciona inmediatamente
   • Puedes ejecutarlo: python QUICK_START.py

2. REGISTRY_IMPLEMENTATION_SUMMARY.md (10 minutos)

   • Qué se hizo y por qué
   • Cómo está organizado ahora
   • Próximos pasos

3. TOOLS_GUIDE.md (20 minutos)

   • Guía completa del patrón Registry
   • Métodos disponibles
   • Mejores prácticas

📖 Documentación por tema

Para crear herramientas

Documento	Contenido
TOOLS_GUIDE.md	Cómo crear una herramienta básica
TOOLS_GUIDE.md	Ejemplo completo con validaciones
AGENDA_TOOLS_EXAMPLE.py	5 herramientas reales para agenda

Para usar tools

Documento	Contenido
TOOLS_GUIDE.md	Cómo registrar y usar tools
TOOLS_GUIDE.md	API completo de ToolRegistry
TOOLS_GUIDE.md	Integración con Agent

Para entender la arquitectura

Documento	Contenido
REGISTRY_IMPLEMENTATION_SUMMARY.md	Estructura general
CHANGES_SUMMARY.md	Qué cambió respecto a antes
src/naliiabot/bot/tools/tool_registry.py	Código fuente del Registry

🎯 Casos de uso comunes

Caso 1: Crear una herramienta simple

1. Lee: QUICK_START.py
2. Lee: TOOLS_GUIDE.md (sección 2)
3. Copia código de QUICK_START.py a tools.py
4. Listo ✅

Caso 2: Crear herramientas para gestionar agenda

1. Lee: AGENDA_TOOLS_EXAMPLE.py
2. Adapta los ejemplos a tu lógica
3. Copia a tools.py
4. Registra en tu main.py
5. Listo ✅

Caso 3: Entender cómo funciona el Registry

1. Lee: REGISTRY_IMPLEMENTATION_SUMMARY.md
2. Revisa: tool_registry.py
3. Lee: TOOLS_GUIDE.md (sección 4)
4. Experimenta con los métodos
5. Entiendido ✅

Caso 4: Hacer pruebas de tools

1. Abre: tests/test_naliia_agent_tools.py
2. Agrega tus tests
3. Ejecuta: pytest tests/test_naliia_agent_tools.py -v
4. Testeado ✅

📂 Estructura de archivos

NaliiaBot/
│
├── 📄 QUICK_START.py                          ← EMPIEZA AQUÍ
├── 📄 REGISTRY_IMPLEMENTATION_SUMMARY.md       ← Resumen
├── 📄 TOOLS_GUIDE.md                          ← Guía completa
├── 📄 AGENDA_TOOLS_EXAMPLE.py                 ← Ejemplos reales
├── 📄 CHANGES_SUMMARY.md                      ← Qué cambió
├── 📄 TOOLS_DOCUMENTATION_INDEX.md             ← Este archivo
│
├── 📁 src/naliiabot/bot/tools/
│   ├── __init__.py                             ← Exporta BaseTool, ToolRegistry
│   ├── tool_registry.py                        ← Infraestructura (código fuente)
│   └── tools.py                                ← ← TUS HERRAMIENTAS AQUÍ
│
└── 📁 tests/
    └── test_naliia_agent_tools.py              ← Tests de tools

🔍 Búsqueda rápida

Necesito...

• Crear mi primera tool → QUICK_START.py
• Entender el patrón Registry → TOOLS_GUIDE.md
• Ver ejemplos de tools reales → AGENDA_TOOLS_EXAMPLE.py
• Saber qué cambió → CHANGES_SUMMARY.md
• Registrar herramientas → TOOLS_GUIDE.md#3
• Ver métodos de ToolRegistry → TOOLS_GUIDE.md#4
• Hacer tests → tests/test_naliia_agent_tools.py
• Ver el código del Registry → src/naliiabot/bot/tools/tool_registry.py

📊 Recomendación de lectura

Para nuevos usuarios (20 minutos)

1. QUICK_START.py           (5 min)
2. TOOLS_GUIDE.md           (15 min)
   ↓
   Ahora puedes crear tools

Para desarrollo completo (1 hora)

1. QUICK_START.py                       (5 min)
2. REGISTRY_IMPLEMENTATION_SUMMARY.md   (10 min)
3. TOOLS_GUIDE.md                       (20 min)
4. AGENDA_TOOLS_EXAMPLE.py              (15 min)
5. Revisar tests                        (10 min)
   ↓
   Experto en el patrón

Para entender la arquitectura (30 minutos)

1. CHANGES_SUMMARY.md                (10 min)
2. tool_registry.py                  (15 min)
3. tests/test_naliia_agent_tools.py  (5 min)
   ↓
   Entiendes cómo está construido

🎓 Conceptos clave

BaseTool

Clase abstracta que define qué es una herramienta:

• name: Identificador único
• description: Para que el LLM sepa cuándo usarla
• args_schema: Qué argumentos acepta (JSON Schema)
• invoke(): Cómo se ejecuta

Leer en: TOOLS_GUIDE.md#estructura-básica

ToolRegistry

Clase que administra todas las herramientas:

• register(): Agregar una herramienta
• get_tool(): Obtener una específica
• get_all_tools(): Obtener todas (BaseTool)
• get_all_tools_as_langchain(): Obtener en formato LangChain

Leer en: TOOLS_GUIDE.md#métodos-disponibles

El flujo completo

Tool (BaseTool)
    ↓
Registry (ToolRegistry)
    ↓
Agent (recibe tools)
    ↓
LLM (usa las tools)

Leer en: TOOLS_GUIDE.md#uso-con-el-agent

✅ Checklist: Empezar a usar Tools

• Leí QUICK_START.py
• Entiendo qué es BaseTool
• Entiendo qué es ToolRegistry
• Creé una herramienta simple en tools.py
• Registré la herramienta
• Usé la herramienta con Agent
• Los tests pasan
• Leí ejemplos de agenda (AGENDA_TOOLS_EXAMPLE.py)
• Sé cómo conectar con BD
• Sé cómo manejar errores

Si marcaste todo ✅, ¡estás listo para trabajar con el sistema de tools!

🆘 Necesito ayuda

• ¿Cómo creo una tool? → TOOLS_GUIDE.md#2
• ¿Cuáles son los métodos? → TOOLS_GUIDE.md#4
• ¿Tengo un error? → TOOLS_GUIDE.md#7
• ¿Quiero ejemplos? → AGENDA_TOOLS_EXAMPLE.py

📞 Resumen rápido

Lo esencial (30 segundos)

# 1. Crear una tool
class MiTool(BaseTool):
    def name(self) -> str:
        return "mi_tool"
    # ... más detalles

# 2. Registrar
registry = ToolRegistry()
registry.register(MiTool())

# 3. Usar
agent = Agent(model=modelo, tools=registry.get_all_tools_as_langchain())

Eso es todo. El resto está en la documentación.

---

Última actualización: 15 Feb 2026
Status: ✅ Documentación completa