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

```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.