# 📚 Í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](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](REGISTRY_IMPLEMENTATION_SUMMARY.md)** (10 minutos)
   - Qué se hizo y por qué
   - Cómo está organizado ahora
   - Próximos pasos

3. **[TOOLS_GUIDE.md](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](TOOLS_GUIDE.md#2-crear-una-herramienta-personalizada)** | Cómo crear una herramienta básica |
| **[TOOLS_GUIDE.md](TOOLS_GUIDE.md#5-ejemplo-completo)** | Ejemplo completo con validaciones |
| **[AGENDA_TOOLS_EXAMPLE.py](AGENDA_TOOLS_EXAMPLE.py)** | 5 herramientas reales para agenda |

### Para usar tools

| Documento | Contenido |
|-----------|-----------|
| **[TOOLS_GUIDE.md](TOOLS_GUIDE.md#3-registrar-y-usar-herramientas)** | Cómo registrar y usar tools |
| **[TOOLS_GUIDE.md](TOOLS_GUIDE.md#4-métodos-disponibles)** | API completo de ToolRegistry |
| **[TOOLS_GUIDE.md](TOOLS_GUIDE.md#6-usar-con-el-agent)** | Integración con Agent |

### Para entender la arquitectura

| Documento | Contenido |
|-----------|-----------|
| **[REGISTRY_IMPLEMENTATION_SUMMARY.md](REGISTRY_IMPLEMENTATION_SUMMARY.md)** | Estructura general |
| **[CHANGES_SUMMARY.md](CHANGES_SUMMARY.md)** | Qué cambió respecto a antes |
| **[src/naliiabot/bot/tools/tool_registry.py](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](QUICK_START.py)
- **Entender el patrón Registry** → [TOOLS_GUIDE.md](TOOLS_GUIDE.md)
- **Ver ejemplos de tools reales** → [AGENDA_TOOLS_EXAMPLE.py](AGENDA_TOOLS_EXAMPLE.py)
- **Saber qué cambió** → [CHANGES_SUMMARY.md](CHANGES_SUMMARY.md)
- **Registrar herramientas** → [TOOLS_GUIDE.md#3](TOOLS_GUIDE.md#3-registrar-y-usar-herramientas)
- **Ver métodos de ToolRegistry** → [TOOLS_GUIDE.md#4](TOOLS_GUIDE.md#4-métodos-disponibles-del-toolregistry)
- **Hacer tests** → [tests/test_naliia_agent_tools.py](tests/test_naliia_agent_tools.py)
- **Ver el código del Registry** → [src/naliiabot/bot/tools/tool_registry.py](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](TOOLS_GUIDE.md#1-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](TOOLS_GUIDE.md#4-métodos-disponibles-del-toolregistry)

### El flujo completo
```
Tool (BaseTool)
    ↓
Registry (ToolRegistry)
    ↓
Agent (recibe tools)
    ↓
LLM (usa las tools)
```

**Leer en:** [TOOLS_GUIDE.md#uso-con-el-agent](TOOLS_GUIDE.md#6-usar-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](TOOLS_GUIDE.md#2-crear-una-herramienta-personalizada)
- **¿Cuáles son los métodos?** → [TOOLS_GUIDE.md#4](TOOLS_GUIDE.md#4-métodos-disponibles-del-toolregistry)
- **¿Tengo un error?** → [TOOLS_GUIDE.md#7](TOOLS_GUIDE.md#7-ventajas-del-patrón-registry)
- **¿Quiero ejemplos?** → [AGENDA_TOOLS_EXAMPLE.py](AGENDA_TOOLS_EXAMPLE.py)

## 📞 Resumen rápido

### Lo esencial (30 segundos)

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