149 lines
4.9 KiB
Markdown
149 lines
4.9 KiB
Markdown
# 🚀 NaliiaBot - Patrón Registry para Herramientas
|
|
|
|
Bienvenido al sistema de **herramientas (tools)** de NaliiaBot.
|
|
|
|
## 📚 Documentación
|
|
|
|
Toda la documentación está en la carpeta **[`docs/`](docs/)**
|
|
|
|
### ⭐ Comienza aquí:
|
|
|
|
1. **[docs/INICIO.txt](docs/INICIO.txt)** - Bienvenida y guía visual (2 min)
|
|
2. **[docs/TOOLS_DOCUMENTATION_INDEX.md](docs/TOOLS_DOCUMENTATION_INDEX.md)** - Índice maestro (10 min)
|
|
3. **[docs/QUICK_START.py](docs/QUICK_START.py)** - Tutorial interactivo (5 min)
|
|
|
|
### 📖 Documentación completa:
|
|
|
|
| Archivo | Descripción |
|
|
|---------|-----------|
|
|
| [docs/INICIO.txt](docs/INICIO.txt) | Bienvenida con instrucciones visuales |
|
|
| [docs/TOOLS_DOCUMENTATION_INDEX.md](docs/TOOLS_DOCUMENTATION_INDEX.md) | Índice y navegación de toda la documentación |
|
|
| [docs/QUICK_START.py](docs/QUICK_START.py) | Tutorial de 5 minutos para empezar |
|
|
| [docs/TOOLS_GUIDE.md](docs/TOOLS_GUIDE.md) | Guía completa del patrón Registry |
|
|
| [docs/AGENDA_TOOLS_EXAMPLE.py](docs/AGENDA_TOOLS_EXAMPLE.py) | 5 herramientas reales de ejemplo |
|
|
| [docs/REGISTRY_IMPLEMENTATION_SUMMARY.md](docs/REGISTRY_IMPLEMENTATION_SUMMARY.md) | Resumen de la implementación |
|
|
| [docs/README_REGISTRY.md](docs/README_REGISTRY.md) | Resumen ejecutivo |
|
|
| [docs/TOOL_REGISTRY_GUIDE.md](docs/TOOL_REGISTRY_GUIDE.md) | Guía de patrones y mejores prácticas |
|
|
| [docs/CHANGES_SUMMARY.md](docs/CHANGES_SUMMARY.md) | Qué cambió en el sistema |
|
|
|
|
## 🏗️ Estructura del proyecto
|
|
|
|
```
|
|
NaliiaBot/
|
|
├── 📁 docs/ ← Toda la documentación
|
|
│ ├── INICIO.txt
|
|
│ ├── TOOLS_DOCUMENTATION_INDEX.md
|
|
│ ├── QUICK_START.py
|
|
│ ├── TOOLS_GUIDE.md
|
|
│ ├── AGENDA_TOOLS_EXAMPLE.py
|
|
│ └── ... (más documentación)
|
|
│
|
|
├── 📁 src/naliiabot/bot/tools/
|
|
│ ├── __init__.py
|
|
│ ├── tool_registry.py (infraestructura)
|
|
│ └── tools.py (← Aquí van TUS herramientas)
|
|
│
|
|
└── 📁 tests/
|
|
└── test_naliia_agent_tools.py
|
|
```
|
|
|
|
## ✨ ¿Qué es el patrón Registry?
|
|
|
|
Sistema centralizado para registrar y gestionar herramientas del agente:
|
|
|
|
1. **Definir** - Crear una herramienta que herede de `BaseTool`
|
|
2. **Registrar** - Agregar a `ToolRegistry`
|
|
3. **Usar** - Pasar al `Agent` para que el LLM las use
|
|
|
|
```python
|
|
# Crear
|
|
class MiTool(BaseTool):
|
|
def name(self): return "mi_herramienta"
|
|
# ...
|
|
|
|
# Registrar
|
|
registry = ToolRegistry()
|
|
registry.register(MiTool())
|
|
|
|
# Usar
|
|
agent = Agent(model=modelo, tools=registry.get_all_tools_as_langchain())
|
|
```
|
|
|
|
## 🎯 Próximos pasos
|
|
|
|
1. **Lee** la bienvenida: [docs/INICIO.txt](docs/INICIO.txt)
|
|
2. **Entiende** la estructura: [docs/TOOLS_DOCUMENTATION_INDEX.md](docs/TOOLS_DOCUMENTATION_INDEX.md)
|
|
3. **Sigue** el tutorial: [docs/QUICK_START.py](docs/QUICK_START.py)
|
|
4. **Crea** tus herramientas en: `src/naliiabot/bot/tools/tools.py`
|
|
|
|
## 📝 Crear tu primera herramienta
|
|
|
|
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 mi herramienta"
|
|
|
|
@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}"
|
|
```
|
|
|
|
Luego regístrala:
|
|
|
|
```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()
|
|
```
|
|
|
|
## 🔗 Enlaces rápidos
|
|
|
|
| Necesito... | Ir a... |
|
|
|-----------|---------|
|
|
| Entender el sistema | [docs/TOOLS_DOCUMENTATION_INDEX.md](docs/TOOLS_DOCUMENTATION_INDEX.md) |
|
|
| Un tutorial rápido | [docs/QUICK_START.py](docs/QUICK_START.py) |
|
|
| Crear una herramienta | [docs/TOOLS_GUIDE.md](docs/TOOLS_GUIDE.md#2-crear-una-herramienta-personalizada) |
|
|
| Ver ejemplos | [docs/AGENDA_TOOLS_EXAMPLE.py](docs/AGENDA_TOOLS_EXAMPLE.py) |
|
|
| Registrar tools | [docs/TOOLS_GUIDE.md](docs/TOOLS_GUIDE.md#3-registrar-y-usar-herramientas) |
|
|
| Métodos disponibles | [docs/TOOLS_GUIDE.md](docs/TOOLS_GUIDE.md#4-métodos-disponibles-del-toolregistry) |
|
|
| Hacer tests | [docs/TOOLS_GUIDE.md](docs/TOOLS_GUIDE.md#7-mejores-prácticas) |
|
|
|
|
## ✅ ¿Qué obtienes?
|
|
|
|
✅ Sistema centralizado de herramientas
|
|
✅ Documentación completa y detallada
|
|
✅ Ejemplos funcionales
|
|
✅ Tests automáticos
|
|
✅ Guías paso a paso
|
|
✅ Listo para producción
|
|
|
|
---
|
|
|
|
**Comenzar:** Lee [docs/INICIO.txt](docs/INICIO.txt) ahora (2 minutos)
|