DonConfia_Dev/agents/app/documentation.md

DonConfiao - Asistente Virtual de Tienda La Ilusión

Índice

1. Descripción General
2. Arquitectura
3. Componentes Principales
4. Gestión de Pedidos
5. Catálogo de Productos
6. Base de Datos
7. API y Endpoints
8. Guía de Uso
9. Configuración y Despliegue

Descripción General

DonConfiao es un asistente virtual diseñado para Tienda La Ilusión que facilita la gestión de pedidos y la atención al cliente. Utiliza procesamiento de lenguaje natural para entender y responder a las solicitudes de los clientes de manera eficiente y amigable.

Arquitectura

El sistema está construido utilizando una arquitectura modular basada en agentes, implementada con LangGraph y LangChain. Los principales componentes son:

• Classifier Agent: Clasifica las intenciones del usuario
• Catalog Agent: Maneja consultas relacionadas con productos
• Order Agent: Gestiona todo lo relacionado con pedidos
• RAG System: Proporciona respuestas basadas en conocimiento contextual

Componentes Principales

Classifier Agent

• Analiza el contexto completo de la conversación
• Categoriza las consultas en:
  • general_info: Información general
  • catalog: Consultas sobre productos
  • order: Gestión de pedidos

Catalog Manager

• Gestiona el catálogo de productos
• Funcionalidades:
  • Búsqueda de productos
  • Verificación de disponibilidad
  • Actualización de precios
  • Gestión de inventario

Order Manager

• Sistema completo de gestión de pedidos

• Estados de Pedido:

  • in_cart: En carrito
  • confirmed: Confirmado
  • processing: En proceso
  • ready: Listo
  • delivering: En entrega
  • delivered: Entregado
  • cancelled: Cancelado

• Estados de Entrega:

  • pending: Pendiente
  • assigned: Asignado
  • in_transit: En tránsito
  • delivered: Entregado
  • failed: Fallido

Gestión de Pedidos

Funcionalidades Principales

1. Gestión de Carrito

   • Agregar productos
   • Remover productos
   • Ver contenido
   • Modificar cantidades

2. Gestión de Pedidos

   • Confirmar pedidos
   • Modificar pedidos existentes
   • Combinar múltiples pedidos
   • Eliminar pedidos
   • Consultar estado
   • Aplicar descuentos

3. Seguimiento de Entregas

   • Actualización de estado
   • Gestión de direcciones
   • Notificaciones de cambios

Herramientas Disponibles

- add_to_cart
- remove_from_cart
- view_cart
- confirm_order
- view_order_history
- get_order_status
- merge_orders
- delete_order
- modify_order
- get_order_products
- update_delivery_status
- apply_discount

Catálogo de Productos

Estructura de Producto

{
    'producto_id': str,
    'producto': str,
    'precio': float,
    'unidad': str,
    'categoria': str,
    'stock': int
}

Funcionalidades

• Búsqueda por nombre
• Filtrado por categoría
• Verificación de stock
• Actualización de precios
• Gestión de inventario

Base de Datos

Tablas Principales

Orders

CREATE TABLE orders (
    order_id TEXT PRIMARY KEY,
    phone TEXT NOT NULL,
    status TEXT NOT NULL,
    total REAL DEFAULT 0,
    delivery_address TEXT,
    delivery_status TEXT,
    payment_method TEXT,
    discount_applied REAL DEFAULT 0,
    notes TEXT,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
)

Order Items

CREATE TABLE order_items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    order_id TEXT NOT NULL,
    product_id TEXT NOT NULL,
    quantity INTEGER NOT NULL,
    price REAL NOT NULL,
    unit TEXT NOT NULL,
    FOREIGN KEY (order_id) REFERENCES orders (order_id)
)

API y Endpoints

Chat API

• POST /chat: Procesa mensajes de chat

  {
    "message": str,
    "phone": str,
    "context": dict
  }
  

• GET /history: Obtiene historial de conversación

  {
    "phone": str
  }
  

Server API

• GET /products: Lista de productos
• GET /orders: Historial de pedidos
• POST /orders: Crear nuevo pedido
• PUT /orders/{id}: Actualizar pedido
• DELETE /orders/{id}: Eliminar pedido

Guía de Uso

Ejemplos de Interacción

1. Consultar Productos

Usuario: "¿Qué productos tienen disponibles?"
DonConfiao: [Lista productos con precios y disponibilidad]

2. Crear Pedido

Usuario: "Quiero 2 kilos de arroz"
DonConfiao: [Agrega al carrito y muestra confirmación]

3. Modificar Pedido

Usuario: "Modifica mi pedido #123"
DonConfiao: [Muestra opciones de modificación]

4. Combinar Pedidos

Usuario: "Combina mis pedidos #123 y #456"
DonConfiao: [Verifica y combina los pedidos]

Mejores Prácticas

1. Usar número de teléfono para identificación
2. Verificar disponibilidad antes de confirmar
3. Confirmar cambios importantes
4. Mantener actualizadas las direcciones de entrega

Configuración y Despliegue

Requisitos

• Python 3.8+
• SQLite3
• Dependencias en requirements.txt

Variables de Entorno

OPENAI_API_KEY=your_api_key
DATABASE_PATH=path/to/database

Estructura del Proyecto

app/
├── data/
│   ├── orders.db
│   └── catalog.db
├── langgraph_tools/
│   ├── tools/
│   │   ├── orders/
│   │   └── catalog/
│   ├── nodes.py
│   └── prompts.yaml
├── rag/
│   └── knowledge_base/
├── server.py
├── chat.py
└── requirements.txt

Instalación

# Clonar repositorio
git clone [repository_url]

# Instalar dependencias
pip install -r requirements.txt

# Inicializar base de datos
python init_db.py

# Iniciar servidor
python server.py

Testing

# Ejecutar todos los tests
python -m pytest test/

# Ejecutar tests específicos
python -m pytest test/test_catalog_db.py
python -m pytest test/test_db.py

Mantenimiento y Soporte

Logs y Monitoreo

• Los logs se guardan en data/logs/
• Monitoreo de errores y excepciones
• Seguimiento de uso y rendimiento

Backup y Recuperación

• Backups automáticos diarios
• Procedimiento de recuperación documentado
• Gestión de versiones de la base de datos

Contacto y Soporte

• Equipo de desarrollo: dev@tiendailusion.com
• Soporte técnico: support@tiendailusion.com
• Documentación adicional: [wiki_url]

---

Esta documentación está en constante evolución. Para sugerencias o correcciones, por favor contactar al equipo de desarrollo.