230 lines
7.2 KiB
Markdown
230 lines
7.2 KiB
Markdown
# 📚 Í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
|