obsidian-vault/005-Learn/Planificación desarrollo agente ia.md

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

                    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:

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:

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:

¿Cuánto vendimos este mes?

El agente determina:

tool = ventas_mes()

Obtiene el resultado y genera una respuesta en lenguaje natural.

Fase 2: herramientas con parámetros

Agregar parámetros:

ventas_por_cliente(cliente)
ventas_por_fecha(desde, hasta)
compras_por_proveedor(proveedor, desde, hasta)
stock_almacen(almacen)
articulo(codigo)

Ejemplo:

¿Cuánto le hemos vendido a Alicorp este año?

Puede interpretarse como:

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:

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:

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:

Vista: VW_VENTAS

Campos:
Fecha
Cliente
Ciudad
Total
Margen
Cantidad
Vendedor

Pregunta:

¿Cuánto vendimos por ciudad?

Consulta posible:

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:

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:

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:

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:

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:

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:

- 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:

Usuario -> LLM -> Tool controlada -> Vista/Query HANA -> Resultado

Arquitectura de operaciones:

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:

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:

"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

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:

Chat
  |
  v
Ollama
  |
  v
Tools Python
  |
  v
HANA
  |
  v
Resultado
  |
  v
Ollama
  |
  v
Respuesta

Con cinco herramientas iniciales:

ventas_hoy()
ventas_mes()
top_clientes()
stock_critico()
cuentas_por_cobrar()

Y una interfaz web sencilla.

Evolución recomendada

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:

¿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:

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:

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:

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.