docs: update README with current project structure
This commit is contained in:
196
README.md
196
README.md
@@ -1,160 +1,130 @@
|
|||||||
# NaliiaBot
|
# 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
|
- Agente conversacional inteligente basado en LangGraph
|
||||||
- Sistema de tools (herramientas) con patrón Registry
|
- Sistema de herramientas (tools) con integración MCP
|
||||||
- Integración con modelos LLM (Anthropic)
|
- Integración con modelos LLM (Anthropic Claude, DeepSeek)
|
||||||
- API FastAPI para interacción
|
- API FastAPI para interacción
|
||||||
- Tests completos
|
- Checkpointing con PostgreSQL para persistencia de estado
|
||||||
- Documentación exhaustiva
|
- Tests completos con pytest
|
||||||
|
|
||||||
## 📚 Documentación
|
## Estructura del proyecto
|
||||||
|
|
||||||
### 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
|
|
||||||
|
|
||||||
```
|
```
|
||||||
NaliiaBot/
|
NaliiaBot/
|
||||||
├── docs/ # Documentación completa
|
|
||||||
│ ├── INICIO.txt
|
|
||||||
│ ├── TOOLS_DOCUMENTATION_INDEX.md
|
|
||||||
│ ├── QUICK_START.py
|
|
||||||
│ ├── TOOLS_GUIDE.md
|
|
||||||
│ ├── AGENDA_TOOLS_EXAMPLE.py
|
|
||||||
│ └── ...
|
|
||||||
│
|
|
||||||
├── src/
|
├── src/
|
||||||
│ ├── naliiabot/
|
│ ├── naliiabot/
|
||||||
│ │ ├── bot/
|
│ │ ├── bot/
|
||||||
│ │ │ ├── agent/ # Agente principal
|
│ │ │ ├── agent/ # Agente LangGraph
|
||||||
│ │ │ │ ├── agent.py
|
│ │ │ │ ├── agent.py
|
||||||
│ │ │ │ └── schemas.py
|
│ │ │ │ └── schemas.py
|
||||||
│ │ │ └── tools/ # Sistema de tools
|
│ │ │ ├── tools/ # Herramientas del agente
|
||||||
│ │ │ ├── __init__.py
|
│ │ │ │ ├── naliia_tools.py
|
||||||
│ │ │ ├── tool_registry.py
|
│ │ │ │ └── schemes.py
|
||||||
│ │ │ └── tools.py # ← Define aquí tus tools
|
│ │ │ ├── factories/ # Factorías (LLM)
|
||||||
│ │ └── naliiabotapi/
|
│ │ │ └── prompts/ # Prompts del agente
|
||||||
│ │ └── main.py # API FastAPI
|
│ │ └── bot/
|
||||||
│ └── ui/
|
│ ├── naliiabotapi/ # API FastAPI
|
||||||
│ └── ... # Frontend
|
│ │ ├── main.py
|
||||||
│
|
│ │ ├── api/
|
||||||
|
│ │ │ ├── v1/endpoints/
|
||||||
|
│ │ │ └── v1/webhooks/
|
||||||
|
│ │ └── schemes/
|
||||||
|
│ ├── mcp/ # Servidor MCP
|
||||||
|
│ └── ui/ # Frontend
|
||||||
├── tests/
|
├── tests/
|
||||||
│ ├── test_agent.py
|
├── docker-compose.yaml # PostgreSQL para checkpointing
|
||||||
│ ├── test_naliia_agent_tools.py
|
├── pyproject.toml # Configuración Poetry
|
||||||
│ └── ...
|
└── README.md
|
||||||
│
|
|
||||||
└── README.md (este archivo)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🔧 Instalación
|
## Requisitos
|
||||||
|
|
||||||
|
- Python 3.13+
|
||||||
|
- PostgreSQL (via Docker)
|
||||||
|
- MCP server ejecutándose en `http://localhost:8001/mcp`
|
||||||
|
|
||||||
|
## Instalación
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clonar proyecto
|
# Instalar dependencias con Poetry
|
||||||
git clone <repo>
|
poetry install
|
||||||
cd NaliiaBot
|
|
||||||
|
|
||||||
# Instalar dependencias
|
|
||||||
pip install -r requirements.txt
|
|
||||||
|
|
||||||
# Configurar variables de entorno
|
# Configurar variables de entorno
|
||||||
cp .env.example .env
|
cp .env.example .env
|
||||||
# Editar .env con tus configuraciones
|
# 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
|
# Iniciar servidor MCP
|
||||||
from .tool_registry import BaseTool
|
# (configurar según implementación)
|
||||||
|
|
||||||
class MiHerramienta(BaseTool):
|
# Iniciar API
|
||||||
@property
|
task dev
|
||||||
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"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Usar el agente
|
### Comandos disponibles
|
||||||
|
|
||||||
```python
|
| Comando | Descripción |
|
||||||
from src.naliiabot.bot.tools import ToolRegistry
|
|---------|-------------|
|
||||||
from src.naliiabot.bot.tools.tools import MiHerramienta
|
| `task dev` | Iniciar servidor API en puerto 8010 |
|
||||||
from src.naliiabot.bot.agent.agent import Agent
|
| `task test` | Ejecutar todos los tests |
|
||||||
from langchain_anthropic import ChatAnthropic
|
| `task test-cov` | Ejecutar tests con coverage |
|
||||||
|
|
||||||
# Crear registry
|
### Variables de entorno
|
||||||
registry = ToolRegistry()
|
|
||||||
registry.register(MiHerramienta())
|
|
||||||
|
|
||||||
# Crear agente
|
| Variable | Descripción | Valor por defecto |
|
||||||
modelo = ChatAnthropic(model="claude-3-5-sonnet-20241022")
|
|----------|-------------|-------------------|
|
||||||
agent = Agent(model=modelo, tools=registry.get_all_tools_as_langchain())
|
| `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
|
## Tools disponibles
|
||||||
resultado = agent.invoke({"messages": [...]})
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📖 Documentación detallada
|
El agente cuenta con las siguientes herramientas:
|
||||||
|
|
||||||
| Tema | Ubicación |
|
- `get_current_datetime` - Consulta fecha y hora actual
|
||||||
|------|-----------|
|
- `get_tomorrow_date` - Calcula la fecha de mañana
|
||||||
| Sistema de tools | [docs/TOOLS_DOCUMENTATION_INDEX.md](docs/TOOLS_DOCUMENTATION_INDEX.md) |
|
- `find_service_centers` - Lista centros de servicio disponibles
|
||||||
| Quick start | [docs/QUICK_START.py](docs/QUICK_START.py) |
|
- `find_products_and_services` - Lista productos y servicios
|
||||||
| Guía completa | [docs/TOOLS_GUIDE.md](docs/TOOLS_GUIDE.md) |
|
- `schedule_appointment` - Agenda una cita
|
||||||
| Ejemplos | [docs/AGENDA_TOOLS_EXAMPLE.py](docs/AGENDA_TOOLS_EXAMPLE.py) |
|
|
||||||
|
|
||||||
## ✅ 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
|
```bash
|
||||||
# Ejecutar todos los tests
|
# Ejecutar todos los tests
|
||||||
pytest
|
pytest -v
|
||||||
|
|
||||||
# Tests específicos
|
# Tests con coverage
|
||||||
pytest tests/test_naliia_agent_tools.py -v
|
task test-cov
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🔗 Enlaces útiles
|
## Desarrollo
|
||||||
|
|
||||||
- [Documentación de tools](README_TOOLS.md)
|
El proyecto sigue una arquitectura basada en:
|
||||||
- [Sistema Registry](docs/TOOLS_DOCUMENTATION_INDEX.md)
|
- **LangGraph**: Grafo de estados para el agente conversacional
|
||||||
- [Ejemplos de herramientas](docs/AGENDA_TOOLS_EXAMPLE.py)
|
- **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
|
MIT
|
||||||
|
|
||||||
## 👥 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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user