feat: Add docs
This commit is contained in:
148
README_TOOLS.md
Normal file
148
README_TOOLS.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# 🚀 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)
|
||||
Reference in New Issue
Block a user