# 🚀 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)