# Agente IA para SAP Business One + HANA ## Objetivo Construir progresivamente un agente de IA tipo chat para la empresa, conectado a SAP Business One sobre HANA, usando modelos locales mediante Ollama. La evolución prevista es: - Consultas de negocio en lenguaje natural. - KPIs. - Análisis de datos. - Gráficos y cuadros resumen. - Reportes PDF y Excel. - Resúmenes gerenciales. - Alertas y análisis automáticos. La estrategia es comenzar pequeño y agregar capacidades mediante herramientas independientes. ## Arquitectura ```text USUARIO | v +-------------+ | Chat Web UI | | React/Vite | +------+------+ | v +-------------+ | FastAPI | | Backend | +------+------+ | +---------+---------+ | | v v +-----------+ +--------------+ | Ollama | | Tool / Skill | | Local LLM | | Engine | +-----------+ +-------+------+ | +--------+--------+ | | v v SAP HANA SAP Service Layer ``` ### Principio fundamental El modelo de IA no debe tener acceso directo e irrestricto a SAP. El LLM debe solicitar herramientas (`tools`) que ejecuten consultas controladas. Ejemplo: ```text Usuario: ¿Cuánto vendimos este mes? | v Ollama | v ventas_mes() | v Python / FastAPI | v SAP HANA | v Resultado | v Ollama | v Respuesta al usuario ``` Esto permite controlar permisos, consultas y calidad de los resultados. ## Tecnologías ### Frontend - React - Vite - Interfaz tipo ChatGPT - Tablas - Gráficos - Dashboards ### Backend - Python - FastAPI - Herramientas / Skills - Control de acceso - Gestión de conversaciones - Generación de reportes ### IA - Ollama - Modelos locales - Candidatos iniciales: Qwen 3 8B, Qwen 3 14B, Mistral Small y Gemma 3 12B. - La elección final dependerá del hardware y de pruebas reales. ### Datos e integración - SAP Business One - SAP HANA - Vistas HANA - SQL controlado - SAP Service Layer para operaciones que necesiten la lógica de SAP ### Visualización y documentos - Plotly para gráficos interactivos - Matplotlib para imágenes/gráficos destinados a documentos - ReportLab para PDF - OpenPyXL para Excel # Fase 1: herramientas básicas Crear inicialmente un conjunto pequeño de funciones Python: ```text ventas_hoy() ventas_mes() top_clientes() productos_mas_vendidos() facturas_pendientes() compras_mes() stock_critico() cuentas_por_cobrar() cuentas_por_pagar() utilidad_mes() ``` Cada herramienta ejecutará internamente una consulta SQL o utilizará una vista HANA. El usuario pregunta: ```text ¿Cuánto vendimos este mes? ``` El agente determina: ```text tool = ventas_mes() ``` Obtiene el resultado y genera una respuesta en lenguaje natural. ## Fase 2: herramientas con parámetros Agregar parámetros: ```text ventas_por_cliente(cliente) ventas_por_fecha(desde, hasta) compras_por_proveedor(proveedor, desde, hasta) stock_almacen(almacen) articulo(codigo) ``` Ejemplo: ```text ¿Cuánto le hemos vendido a Alicorp este año? ``` Puede interpretarse como: ```text ventas_cliente( cliente="ALICORP", año=2026 ) ``` ## Fase 3: capa semántica empresarial En lugar de hacer que el modelo conozca todas las tablas de SAP Business One, crear vistas orientadas al negocio: ```text VW_VENTAS VW_COMPRAS VW_STOCK VW_CXC VW_CXP VW_CLIENTES VW_PRODUCTOS VW_VENDEDORES VW_KPI_VENTAS VW_KPI_COBRANZAS ``` Las vistas deben presentar información clara y consistente, por ejemplo: ```text Cliente RUC Vendedor Línea Ciudad Total Margen Cantidad Fecha ``` ## Fase 4: SQL generado por IA Cuando el sistema básico sea estable, se puede permitir que el modelo genere SQL, pero únicamente sobre vistas analíticas autorizadas. Ejemplo: ```text Vista: VW_VENTAS Campos: Fecha Cliente Ciudad Total Margen Cantidad Vendedor ``` Pregunta: ```text ¿Cuánto vendimos por ciudad? ``` Consulta posible: ```sql SELECT Ciudad, SUM(Total) AS TotalVentas FROM VW_VENTAS GROUP BY Ciudad; ``` El backend debe validar el SQL antes de ejecutarlo. ## Fase 5: conversación con contexto El agente debe mantener el contexto: ```text Usuario: Muéstrame las ventas de marzo. Agente: ... Usuario: Ahora solo Lima. Agente: ... Usuario: Compáralo con febrero. Agente: ... Usuario: Haz un gráfico. Agente: ... ``` ## Fase 6: gráficos El agente podrá generar visualizaciones como: - Ventas por vendedor - Ventas por ciudad - Ventas mensuales - Margen por línea - Top 10 productos - Top 10 clientes - Evolución de cobranza - Stock por almacén Flujo: ```text Pregunta -> Tool -> HANA -> Datos -> Motor de gráficos -> Gráfico -> Chat ``` ## Fase 7: KPIs Crear un catálogo de indicadores. ### Ventas - Ventas del mes - Ventas acumuladas - Cumplimiento de meta - Crecimiento vs. período anterior - Ticket promedio - Ventas por vendedor - Ventas por cliente - Ventas por producto ### Rentabilidad - Margen bruto - Margen por producto - Margen por línea - Margen por vendedor ### Inventario - Stock disponible - Stock crítico - Rotación - Productos sin movimiento - Productos próximos a agotarse ### Finanzas - Cuentas por cobrar - Cuentas por pagar - Vencimientos - Cobranza - Antigüedad de saldos ## Fase 8: reportes El usuario podrá solicitar: ```text Genera un resumen gerencial de junio. ``` El sistema: 1. Consulta los datos. 2. Calcula KPIs. 3. Genera gráficos. 4. Utiliza el LLM para interpretar los resultados. 5. Genera conclusiones. 6. Crea un PDF. 7. Puede crear un Excel. Estructura posible: ```text REPORTE GERENCIAL Resumen ejecutivo Ventas Rentabilidad Inventario Cuentas por cobrar Principales variaciones Principales clientes Principales productos Conclusiones ``` ## Fase 9: alertas automáticas Ejemplo de resumen diario: ```text Ventas: S/ 124,500 Meta: 95% Margen: 28% Top vendedor: Carlos Productos sin stock: 14 Clientes con deuda: 18 ``` El agente también podría detectar anomalías: ```text - Las ventas de Arequipa disminuyeron 15%. - El producto X cayó 20% respecto al promedio. - Las cobranzas aumentaron 12%. - Tres clientes concentran una parte importante de la deuda vencida. ``` La IA debe aportar principalmente interpretación de datos reales, no inventar respuestas plausibles. ## Seguridad Principios desde el inicio: - El LLM no debe tener credenciales directas de HANA. - Las herramientas deben estar controladas por el backend. - Separar consultas de lectura de operaciones de escritura. - No permitir SQL arbitrario inicialmente. - Validar parámetros. - Registrar las consultas ejecutadas. - Registrar usuario, herramienta y fecha. - Controlar qué herramientas puede utilizar cada usuario. - Utilizar Service Layer para operaciones que modifiquen SAP. - No permitir que una pregunta de lenguaje natural ejecute operaciones destructivas. Arquitectura de lectura: ```text Usuario -> LLM -> Tool controlada -> Vista/Query HANA -> Resultado ``` Arquitectura de operaciones: ```text Usuario -> LLM -> Tool controlada -> Validación -> Service Layer -> SAP Business One ``` # Capa semántica empresarial Uno de los componentes más importantes será un catálogo que explique al agente qué significa cada dato. Ejemplo: ```text VW_VENTAS Descripción: Información consolidada de documentos de venta. Campos: Fecha Fecha del documento. Cliente Código del cliente. NombreCliente Nombre comercial. Vendedor Vendedor responsable. Total Importe total del documento. Margen Margen bruto calculado. Cantidad Cantidad vendida. ``` También se deben documentar reglas de negocio, por ejemplo: ```text "Ventas" significa documentos de venta contabilizados. "No considerar documentos cancelados." "Margen" se calcula utilizando el costo correspondiente. "Ventas del mes" utiliza DocDate salvo que se indique otra fecha. ``` Esto será más importante que intentar meter miles de tablas SAP en el contexto del LLM. # Estructura inicial del proyecto ```text agente_sap/ | +-- app/ | +-- main.py | +-- api/ | | +-- chat.py | | +-- reports.py | +-- agent/ | | +-- agent.py | | +-- prompts.py | | +-- tools.py | +-- tools/ | | +-- ventas.py | | +-- compras.py | | +-- stock.py | | +-- clientes.py | | +-- finanzas.py | +-- database/ | | +-- hana.py | +-- sap/ | | +-- service_layer.py | +-- reports/ | | +-- pdf.py | | +-- excel.py | +-- charts/ | +-- charts.py | +-- frontend/ | +-- ... | +-- sql/ | +-- views/ | +-- queries/ | +-- docs/ | +-- semantic_layer/ | +-- tests/ | +-- .env +-- requirements.txt +-- README.md ``` # Primera versión recomendada No empezar con dashboards, agentes autónomos ni SQL generado por IA. La primera versión debería hacer solamente: ```text Chat | v Ollama | v Tools Python | v HANA | v Resultado | v Ollama | v Respuesta ``` Con cinco herramientas iniciales: ```text ventas_hoy() ventas_mes() top_clientes() stock_critico() cuentas_por_cobrar() ``` Y una interfaz web sencilla. # Evolución recomendada ```text FASE 1 Chat + Ollama + 5 tools | v FASE 2 Tools con parámetros | v FASE 3 Vistas HANA / capa semántica | v FASE 4 SQL controlado sobre vistas | v FASE 5 Contexto conversacional | v FASE 6 Gráficos | v FASE 7 KPIs | v FASE 8 PDF / Excel | v FASE 9 Dashboards | v FASE 10 Alertas y análisis automáticos ``` # Objetivo final El asistente podrá responder preguntas como: ```text ¿Cuánto vendimos este mes? ¿Cuáles son nuestros 10 mejores clientes? ¿Qué productos están cayendo en ventas? ¿Qué vendedores no están alcanzando su meta? ¿Cuánto tenemos pendiente de cobrar? ¿Qué clientes tienen mayor deuda vencida? ¿Cómo se comportaron las ventas frente al mes anterior? ¿Cuál es nuestro margen promedio? Genera un reporte gerencial del mes. Genera un Excel con las ventas por vendedor. Muéstrame un gráfico de ventas de los últimos 12 meses. ¿Qué problemas ves en los datos de este mes? ``` Posteriormente: ```text Analiza la situación comercial de la empresa y dame las principales conclusiones. ``` Las conclusiones deben basarse en datos reales obtenidos de SAP, no en respuestas inventadas por el modelo. # Principio de diseño La arquitectura debe ser modular. Cada nueva capacidad debe incorporarse como una nueva herramienta: ```text Nueva necesidad | v Nueva Tool | v Consulta / Vista HANA | v Documentación semántica | v Disponible para el agente ``` Esto permite crecer sin rehacer toda la aplicación. # Conclusión La estrategia recomendada es construir primero un **asistente de consulta sobre SAP Business One**, no un sistema autónomo. La combinación: ```text React + FastAPI + Ollama + Tools Python + SAP HANA + Service Layer ``` es suficiente para construir una primera versión sólida. La pieza más importante no será el modelo de IA, sino la **capa de herramientas y conocimiento empresarial** que conectará el lenguaje natural con los datos reales de SAP. El modelo puede cambiarse posteriormente. Las herramientas, vistas, reglas de negocio y capa semántica serán el verdadero activo del proyecto.