feat: Add docs

2026-02-15 16:03:09 -05:00
parent e28c42ddd8
commit 9823bc19d2
14 changed files with 3208 additions and 0 deletions
--- a/docs/REGISTRY_IMPLEMENTATION_SUMMARY.md
+++ b/docs/REGISTRY_IMPLEMENTATION_SUMMARY.md
@@ -0,0 +1,171 @@
+# ✅ Resumen: Implementación del Patrón Registry para Tools
+
+## 📋 Qué se hizo
+
+Se implementó el **patrón Registry** para gestionar las herramientas del agente Naliia de forma centralizada, escalable y fácil de mantener.
+
+### Archivos modificados:
+
+| Archivo | Cambio | Estado |
+|---------|--------|--------|
+| `src/naliiabot/bot/tools/tools.py` | Removidas tools de ejemplo (Calculator, Greeter, Weather, Time) | ✅ Limpio |
+| `src/naliiabot/bot/tools/__init__.py` | Removidas importaciones de tools de ejemplo | ✅ Actualizado |
+
+### Archivos ya existentes (infraestructura):
+
+| Archivo | Descripción |
+|---------|-----------|
+| `src/naliiabot/bot/tools/tool_registry.py` | Patrón Registry: `BaseTool` + `ToolRegistry` |
+
+### Archivos de documentación y ejemplos creados:
+
+| Archivo | Contenido |
+|---------|-----------|
+| **TOOLS_GUIDE.md** | Guía completa con ejemplos de uso |
+| **AGENDA_TOOLS_EXAMPLE.py** | 5 herramientas reales para gestión de agenda |
+| **CHANGES_SUMMARY.md** | Resumen de cambios |
+
+## 🎯 Estado actual
+
+El proyecto está listo para que **definas tus propias herramientas** en:
+
+```
+src/naliiabot/bot/tools/tools.py  ← Aquí van TUS tools
+```
+
+## 📚 Cómo empezar
+
+### 1. Lee la documentación
+
+```bash
+# Abre estos archivos en orden:
+1. CHANGES_SUMMARY.md      # Resumen rápido
+2. TOOLS_GUIDE.md          # Guía detallada
+3. AGENDA_TOOLS_EXAMPLE.py # Ejemplos prácticos
+```
+
+### 2. Define una herramienta simple
+
+En `src/naliiabot/bot/tools/tools.py`:
+
+```python
+from typing import Any, Dict
+from .tool_registry import BaseTool
+
+class MiPrimeraHerramienta(BaseTool):
+    @property
+    def name(self) -> str:
+        return "mi_herramienta"
+    
+    @property
+    def description(self) -> str:
+        return "Descripción de qué hace"
+    
+    @property
+    def args_schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "param1": {
+                    "type": "string",
+                    "description": "Un parámetro"
+                }
+            },
+            "required": ["param1"]
+        }
+    
+    def invoke(self, **kwargs) -> str:
+        param = kwargs.get("param1")
+        return f"Resultado para {param}"
+```
+
+### 3. Registra y usa
+
+```python
+from src.naliiabot.bot.tools import ToolRegistry
+from src.naliiabot.bot.tools.tools import MiPrimeraHerramienta
+
+registry = ToolRegistry()
+registry.register(MiPrimeraHerramienta())
+tools = registry.get_all_tools_as_langchain()
+
+# Usar con el Agent
+agent = Agent(model=modelo, tools=tools)
+```
+
+## 🔍 Inspeccionar el ToolRegistry
+
+```python
+registry = ToolRegistry()
+registry.register(MiHerramienta())
+
+# Ver todas las tools
+tools = registry.get_all_tools()
+
+# Ver nombres disponibles
+nombres = registry.list_tool_names()  # ['mi_herramienta', ...]
+
+# Obtener una específica
+herramienta = registry.get_tool("mi_herramienta")
+
+# Verificar si existe
+existe = registry.has_tool("mi_herramienta")  # True
+
+# Obtener descripción
+desc = registry.get_tool_description("mi_herramienta")
+```
+
+## ✨ Ventajas
+
+✅ **Centralizado** - Una única fuente de verdad para todas las tools  
+✅ **Extensible** - Agregar nuevas tools sin tocar código existente  
+✅ **Testeable** - Cada tool se prueba de forma independiente  
+✅ **Mantenible** - Cambios aislados en cada tool  
+✅ **Validado** - Schema automático de argumentos  
+✅ **Documentado** - Fácil inspeccionar tools disponibles  
+✅ **Seguro** - Sin tools de ejemplo conflictivas  
+
+## 📁 Estructura de directorios
+
+```
+NaliiaBot/
+├── src/naliiabot/bot/tools/
+│   ├── __init__.py              # Exporta ToolRegistry, BaseTool
+│   ├── tool_registry.py         # Infraestructura (BaseTool + ToolRegistry)
+│   └── tools.py                 # ← TUS HERRAMIENTAS AQUÍ (vacío y listo)
+│
+├── tests/
+│   └── test_naliia_agent_tools.py  # Tests de tools (ya creados)
+│
+├── TOOLS_GUIDE.md               # Guía completa
+├── AGENDA_TOOLS_EXAMPLE.py      # Ejemplos reales para agenda
+├── CHANGES_SUMMARY.md           # Resumen de cambios
+└── README.md
+```
+
+## 🚀 Próximos pasos sugeridos
+
+1. **Lee TOOLS_GUIDE.md** para entender completamente el patrón
+2. **Copia ejemplos de AGENDA_TOOLS_EXAMPLE.py** si necesitas tools de agenda
+3. **Crea tus propias herramientas** en `src/naliiabot/bot/tools/tools.py`
+4. **Escribe tests** para tus tools (usa test_naliia_agent_tools.py como referencia)
+5. **Integra con el API** en `src/naliiabotapi/main.py`
+
+## ❓ Preguntas frecuentes
+
+**P: ¿Cómo agrego una nueva herramienta?**  
+R: Define una clase que herede de `BaseTool` en `tools.py` y registra en `ToolRegistry`
+
+**P: ¿Puedo usar varias registries?**  
+R: Sí, puedes crear múltiples `ToolRegistry` si necesitas diferentes conjuntos de tools
+
+**P: ¿Cómo conecto una tool con una BD real?**  
+R: En el método `invoke()`, hace la consulta a tu BD. Los ejemplos aquí usan datos simulados.
+
+**P: ¿Necesito modificar agent.py?**  
+R: No, `agent.py` ya soporta tools. Solo necesitas crear las tools y pasar a `Agent(tools=...)`
+
+---
+
+**Última actualización:** 15 Feb 2026  
+**Status:** ✅ Implementación completada y documentada