feat: Add docs
This commit is contained in:
229
docs/TOOLS_DOCUMENTATION_INDEX.md
Normal file
229
docs/TOOLS_DOCUMENTATION_INDEX.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# 📚 Í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
|
||||
Reference in New Issue
Block a user