diff --git a/README.md b/README.md index 059f103..61afa3d 100644 --- a/README.md +++ b/README.md @@ -1,160 +1,130 @@ # NaliiaBot -Agente conversacional basado en LangGraph para gestión de agenda. +Agente conversacional basado en LangGraph para gestión de agenda y atención al cliente. -## 🚀 Características +## Características -- Agente conversacional inteligente -- Sistema de tools (herramientas) con patrón Registry -- Integración con modelos LLM (Anthropic) +- Agente conversacional inteligente basado en LangGraph +- Sistema de herramientas (tools) con integración MCP +- Integración con modelos LLM (Anthropic Claude, DeepSeek) - API FastAPI para interacción -- Tests completos -- Documentación exhaustiva +- Checkpointing con PostgreSQL para persistencia de estado +- Tests completos con pytest -## 📚 Documentación - -### Sistema de Herramientas (Tools) - -Toda la documentación sobre cómo crear y usar herramientas está en **[`docs/`](docs/)** - -**Comienza aquí:** -1. [docs/INICIO.txt](docs/INICIO.txt) - Bienvenida (2 min) -2. [docs/TOOLS_DOCUMENTATION_INDEX.md](docs/TOOLS_DOCUMENTATION_INDEX.md) - Índice (10 min) -3. [docs/QUICK_START.py](docs/QUICK_START.py) - Tutorial (5 min) - -Ver [README_TOOLS.md](README_TOOLS.md) para más detalles. - -## 🏗️ Estructura del proyecto +## Estructura del proyecto ``` NaliiaBot/ -├── docs/ # Documentación completa -│ ├── INICIO.txt -│ ├── TOOLS_DOCUMENTATION_INDEX.md -│ ├── QUICK_START.py -│ ├── TOOLS_GUIDE.md -│ ├── AGENDA_TOOLS_EXAMPLE.py -│ └── ... -│ ├── src/ │ ├── naliiabot/ │ │ ├── bot/ -│ │ │ ├── agent/ # Agente principal +│ │ │ ├── agent/ # Agente LangGraph │ │ │ │ ├── agent.py │ │ │ │ └── schemas.py -│ │ │ └── tools/ # Sistema de tools -│ │ │ ├── __init__.py -│ │ │ ├── tool_registry.py -│ │ │ └── tools.py # ← Define aquí tus tools -│ │ └── naliiabotapi/ -│ │ └── main.py # API FastAPI -│ └── ui/ -│ └── ... # Frontend -│ +│ │ │ ├── tools/ # Herramientas del agente +│ │ │ │ ├── naliia_tools.py +│ │ │ │ └── schemes.py +│ │ │ ├── factories/ # Factorías (LLM) +│ │ │ └── prompts/ # Prompts del agente +│ │ └── bot/ +│ ├── naliiabotapi/ # API FastAPI +│ │ ├── main.py +│ │ ├── api/ +│ │ │ ├── v1/endpoints/ +│ │ │ └── v1/webhooks/ +│ │ └── schemes/ +│ ├── mcp/ # Servidor MCP +│ └── ui/ # Frontend ├── tests/ -│ ├── test_agent.py -│ ├── test_naliia_agent_tools.py -│ └── ... -│ -└── README.md (este archivo) +├── docker-compose.yaml # PostgreSQL para checkpointing +├── pyproject.toml # Configuración Poetry +└── README.md ``` -## 🔧 Instalación +## Requisitos + +- Python 3.13+ +- PostgreSQL (via Docker) +- MCP server ejecutándose en `http://localhost:8001/mcp` + +## Instalación ```bash -# Clonar proyecto -git clone -cd NaliiaBot - -# Instalar dependencias -pip install -r requirements.txt +# Instalar dependencias con Poetry +poetry install # Configurar variables de entorno cp .env.example .env # Editar .env con tus configuraciones ``` -## 🚀 Uso +## Uso -### Crear herramientas +### Iniciar servicios -En `src/naliiabot/bot/tools/tools.py`: +```bash +# Iniciar PostgreSQL +docker-compose up -d -```python -from .tool_registry import BaseTool +# Iniciar servidor MCP +# (configurar según implementación) -class MiHerramienta(BaseTool): - @property - def name(self) -> str: - return "mi_herramienta" - - @property - def description(self) -> str: - return "Descripción" - - @property - def args_schema(self): - return {...} - - def invoke(self, **kwargs) -> str: - return "resultado" +# Iniciar API +task dev ``` -### Usar el agente +### Comandos disponibles -```python -from src.naliiabot.bot.tools import ToolRegistry -from src.naliiabot.bot.tools.tools import MiHerramienta -from src.naliiabot.bot.agent.agent import Agent -from langchain_anthropic import ChatAnthropic +| Comando | Descripción | +|---------|-------------| +| `task dev` | Iniciar servidor API en puerto 8010 | +| `task test` | Ejecutar todos los tests | +| `task test-cov` | Ejecutar tests con coverage | -# Crear registry -registry = ToolRegistry() -registry.register(MiHerramienta()) +### Variables de entorno -# Crear agente -modelo = ChatAnthropic(model="claude-3-5-sonnet-20241022") -agent = Agent(model=modelo, tools=registry.get_all_tools_as_langchain()) +| Variable | Descripción | Valor por defecto | +|----------|-------------|-------------------| +| `LLM_MODEL` | Modelo LLM a usar | `deepseek` | +| `POSTGRES_USER` | Usuario PostgreSQL | `postgres` | +| `POSTGRES_PASSWORD` | Contraseña PostgreSQL | `postgres` | +| `POSTGRES_DB` | Base de datos | `messages` | -# Usar agente -resultado = agent.invoke({"messages": [...]}) -``` +## Tools disponibles -## 📖 Documentación detallada +El agente cuenta con las siguientes herramientas: -| Tema | Ubicación | -|------|-----------| -| Sistema de tools | [docs/TOOLS_DOCUMENTATION_INDEX.md](docs/TOOLS_DOCUMENTATION_INDEX.md) | -| Quick start | [docs/QUICK_START.py](docs/QUICK_START.py) | -| Guía completa | [docs/TOOLS_GUIDE.md](docs/TOOLS_GUIDE.md) | -| Ejemplos | [docs/AGENDA_TOOLS_EXAMPLE.py](docs/AGENDA_TOOLS_EXAMPLE.py) | +- `get_current_datetime` - Consulta fecha y hora actual +- `get_tomorrow_date` - Calcula la fecha de mañana +- `find_service_centers` - Lista centros de servicio disponibles +- `find_products_and_services` - Lista productos y servicios +- `schedule_appointment` - Agenda una cita -## ✅ Tests +## API Endpoints + +- `GET /` - Raíz +- `GET /health` - Health check +- `POST /api/v1/chat` - Enviar mensaje al agente +- `POST /api/v1/webhooks/chat` - Webhook para callbacks + +## Tests ```bash # Ejecutar todos los tests -pytest +pytest -v -# Tests específicos -pytest tests/test_naliia_agent_tools.py -v +# Tests con coverage +task test-cov ``` -## 🔗 Enlaces útiles +## Desarrollo -- [Documentación de tools](README_TOOLS.md) -- [Sistema Registry](docs/TOOLS_DOCUMENTATION_INDEX.md) -- [Ejemplos de herramientas](docs/AGENDA_TOOLS_EXAMPLE.py) +El proyecto sigue una arquitectura basada en: +- **LangGraph**: Grafo de estados para el agente conversacional +- **FastAPI**: API REST sincrónica +- **PostgreSQL**: Persistencia de estado via checkpointing +- **MCP**: Modelo de contexto para herramientas externas -## 📝 Licencia +## Licencia -Especificar la licencia del proyecto - -## 👥 Contribuciones - -Para contribuir al proyecto, por favor: - -1. Fork el repositorio -2. Crea una rama para tu feature -3. Commit tus cambios -4. Push a la rama -5. Abre un Pull Request +MIT