SageFlow AI — API

Concepto

SageFlow AI automatiza el analisis de informacion financiera no estructurada (informes de mercado, transcripciones de resultados, noticias) para analistas financieros y boutiques de gestion de patrimonio. Sustituye horas de lectura manual por ingesta automatica, insights generados por IA (resumen, sentimiento, KPIs) y un chat en lenguaje natural sobre los propios documentos (RAG). B2B SaaS por suscripcion, facturado por documentos procesados/mes y asientos de usuario.

Arquitectura

Spring Boot 4.0.4 / Java 25, capas clasicas:

• %%INLINE0%% — entidades JPA: %%INLINE1%%, %%INLINE2%%, %%INLINE3%%, GeneratedInsight.
• repository — Spring Data JPA sobre las entidades anteriores.
• dto — records inmutables para request/response.
• %%INLINE7%% — JWT stateless (%%INLINE8%%, %%INLINE9%%, %%INLINE10%%, CustomUserDetailsService).
• service — logica de negocio e IA (ver pipeline abajo).
• %%INLINE13%% — %%INLINE14%% hacia la API de un LLM de terceros (formato compatible OpenAI chat completions).
• %%INLINE15%% — %%INLINE16%%, DocumentController.
• %%INLINE18%% — manejo uniforme de errores (%%INLINE19%%, ApiError).

Pipeline de ingesta y RAG

1. %%INLINE21%% (multipart, PDF/TXT) o %%INLINE22%% (URL publica).
2. %%INLINE23%% / %%INLINE24%% extraen texto plano.

- TXT: lectura directa UTF-8. - PDF: extraccion ligera por filtrado de bytes imprimibles (MVP). En produccion se recomienda sustituir por Apache PDFBox sin cambiar el contrato del servicio. - URL: java.net.http.HttpClient + strip de tags HTML.

1. ChunkingService divide el texto en fragmentos solapados (~800 chars, overlap 100).
2. EmbeddingService genera un vector determinista por hashing de tokens (128 dim,

normalizado) y lo serializa en la propia fila (DocumentChunk.embedding). Es un fallback local sin dependencias externas; el contrato es intercambiable por embeddings reales del proveedor de LLM o por pgvector.

1. %%INLINE29%% genera resumen, sentimiento y KPIs via %%INLINE30%%.
2. RagQueryService (chat con tus documentos): embebe la pregunta, calcula

similitud coseno contra los chunks del documento, toma el top-3 como contexto y pide la respuesta a LlmGatewayService.

%%INLINE33%% llama a %%INLINE34%% (Feign) cuando hay sageflow.llm.api-key configurada; si no, usa heuristicas locales deterministas (extraccion de primeras frases, deteccion de palabras clave de sentimiento, regex de cifras monetarias) para que el MVP funcione sin credenciales de terceros.

Endpoints

Metodo	Path	Auth	Descripcion
POST	/api/auth/register	publico	Alta de usuario, devuelve JWT
POST	/api/auth/login	publico	Login, devuelve JWT
POST	/api/documents/upload	JWT	Sube PDF/TXT, dispara ingesta + insights
POST	/api/documents/ingest-url	JWT	Ingiere articulo/transcripcion desde una URL
GET	/api/documents	JWT	Dashboard: lista documentos del usuario
GET	/api/documents/{id}/summary	JWT	Resumen, sentimiento y KPIs del documento
POST	/api/documents/{id}/query	JWT	Chat con el documento (RAG)

Autenticacion: header Authorization: Bearer <token> obtenido en login/register.

Como ejecutar

cd solutions/2026-07-26-sageflow-ai-api
mvn spring-boot:run

Base de datos: sin spring.datasource.url configurado, Spring Boot autoconfigura H2 embebido (in-memory) al arrancar — no requiere instalacion previa. Para PostgreSQL en produccion, definir spring.datasource.* (driver org.postgresql, ya en el classpath).

Variables opcionales para activar el LLM real (sin ellas, el MVP usa heuristicas locales):

export SAGEFLOW_LLM_API_KEY=sk-...
export SAGEFLOW_LLM_BASE_URL=https://api.openai.com/v1

(mapear a %%INLINE47%% / %%INLINE48%% via variables de entorno de Spring).

Flujo de prueba rapido:

curl -X POST localhost:8080/api/auth/register -H 'Content-Type: application/json' \
  -d '{"email":"analyst@fund.com","password":"password123","fullName":"Jane Analyst"}'

curl -X POST localhost:8080/api/documents/ingest-url \
  -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/earnings-call","title":"Q2 Earnings Call"}'

curl localhost:8080/api/documents/1/summary -H "Authorization: Bearer <token>"

curl -X POST localhost:8080/api/documents/1/query \
  -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' \
  -d '{"question":"Cual fue el crecimiento de ingresos reportado?"}'

Analisis de negocio

• Problema: analistas pierden horas leyendo manualmente informes/transcripciones, con riesgo de perder oportunidades por procesar la info tarde.
• Solucion: ingesta + insights automaticos + chat RAG reducen ese tiempo a minutos y estandarizan el analisis.
• Monetizacion: SaaS B2B por niveles, segun documentos/mes y asientos — encaja con el ciclo de decision de firmas boutique que no pueden pagar infraestructura de banca grande.
• Barrera de entrada: baja — se apoya en APIs de LLM existentes (via Feign, intercambiable de proveedor) en vez de entrenar modelos propios, permitiendo iterar rapido el MVP.
• Riesgo principal a validar: calidad/precision del RAG sobre documentos financieros complejos (tablas, notas al pie) — el extractor PDF del MVP es deliberadamente simple y es el primer candidato a reemplazar (PDFBox/Tika) antes de vender a clientes reales.

---

FinOps Analysis para SageFlow AI

Visión General

SageFlow AI, como micro-startup en el nicho de automatización financiera con IA, demuestra un modelo de negocio con un potencial de margen de beneficio operativo excepcionalmente alto. Esto se debe principalmente a que los costos directos de infraestructura y APIs de LLM son relativamente bajos en comparación con el valor de alto precio que se puede cobrar en el mercado B2B de servicios financieros. La clave para mantener esta rentabilidad será una gestión FinOps proactiva y el control del costo por cliente a medida que la startup escale.

Desglose de Costos Mensuales Estimados

Para una fase MVP inicial con ~20 clientes activos, los costos operativos se estiman en $203/mes:

• APIs de LLM (OpenAI): $60/mes

* Basado en un uso híbrido de %%INLINE49%% para resúmenes críticos (6.5M input, 0.5M output tokens) y %%INLINE50%% para chat (10.5M input, 2M output tokens), además de text-embedding-3-small para embeddings (6.5M tokens). * Este costo incluye un pequeño buffer para variaciones en el uso.

• Infraestructura Cloud (AWS): $133/mes

* Cómputo (EC2): 2x t3.small (para redundancia y estabilidad básica) - ~$60/mes * Base de Datos (RDS PostgreSQL): db.t3.small (con 50GB de almacenamiento SSD GP2) - ~$40/mes * Balanceador de Carga (ALB): Para distribuir tráfico y asegurar alta disponibilidad - ~$18/mes * Almacenamiento (S3): Para documentos brutos y backups - ~$5/mes * Monitorización (CloudWatch): Para logs y métricas - ~$10/mes

• Misceláneos: $10/mes

* Incluye costos de dominio, certificados SSL (si no son gratuitos con el proveedor cloud), y servicios básicos de email transaccional.

Ingresos Mensuales Estimados

Con un modelo de suscripción por niveles y una base inicial de 20 clientes:

• 15 clientes en el nivel básico (ej. $99/mes): $1,485
• 5 clientes en un nivel intermedio (ej. $249/mes): $1,245
• Ingreso Total Estimado: $2,730/mes

Margen de Beneficio Operativo

Considerando los ingresos y costos operativos directos:

• Beneficio Bruto: $2,730 (Ingresos) - $203 (Costos) = $2,527

Margen de Beneficio: (($2,527 / $2,730)) 100 = ~93%

Este margen es muy saludable para una fase inicial, indicando que la estructura de costos directos es altamente eficiente. Es crucial recordar que este análisis no incluye costos indirectos como salarios de desarrollo, marketing, ventas, soporte o gastos legales, los cuales serían significativos para una startup en crecimiento.

Estrategias de Optimización FinOps

Para mantener y mejorar este margen a medida que SageFlow AI escala, se recomiendan las siguientes estrategias:

1. Optimización del Uso de LLM:

* Caché Inteligente: Implementar un sistema de caché para respuestas de LLM, especialmente para resúmenes de documentos que no cambian o para preguntas frecuentes sobre el mismo contenido. Esto reduce llamadas redundantes a la API. * Modelos Híbridos: Continuar con la estrategia de usar modelos más caros (ej. %%INLINE54%%) solo para tareas críticas que requieren alta calidad (ej. extracción de KPIs, resúmenes complejos) y modelos más baratos (ej. %%INLINE55%% o incluso modelos de código abierto como Llama 3 si la calidad es suficiente) para tareas de menor criticidad (ej. chat interactivo, embeddings). * Compresión de Contexto: Utilizar técnicas como el resumen de contexto o la filtración inteligente de chunks para reducir la cantidad de tokens enviados a los LLMs, especialmente en el pipeline RAG. * Procesamiento en Lotes (Batch Processing): Para la ingesta y el resumen de documentos, procesar las solicitudes en lotes durante horas de menor actividad o en horarios específicos para aprovechar tarifas más bajas (si el proveedor las ofrece) o usar instancias spot en la infraestructura cloud.

1. Optimización de Infraestructura Cloud:

* Serverless para Eventos: Considerar el uso de AWS Lambda para el procesamiento de documentos una vez subidos. Esto permite pagar solo por el tiempo de cómputo utilizado, escalando automáticamente sin servidores persistentes. * Instancias Reservadas/Savings Plans: Una vez que la carga base sea predecible, adquirir Reserved Instances o Savings Plans en AWS puede reducir significativamente los costos de EC2 y RDS (hasta un 40-60%). * Auto-escalado: Implementar políticas de auto-escalado para EC2 y, si es posible, para la base de datos, para asegurar que los recursos se ajusten dinámicamente a la demanda, evitando el sobredimensionamiento. * Optimización de Base de Datos: Monitorear el rendimiento de PostgreSQL y optimizar consultas. Si el pgvector se usa intensivamente, evaluar soluciones vectoriales dedicadas si el volumen lo justifica, o explorar opciones más económicas como Supabase/Neon para la base de datos. * Monitoreo de Costos: Utilizar herramientas de gestión de costos de AWS (Cost Explorer, Budgets) para tener visibilidad granular del gasto y establecer alertas para evitar sorpresas.

1. Gestión de la Demanda y Precios:

* Modelos de Precios Basados en Valor: Ajustar los niveles de suscripción para reflejar el valor real que la IA aporta a los clientes financieros, asegurando que el precio cubra no solo los costos operativos sino también el desarrollo y el soporte. * Capacitación del Usuario: Educar a los usuarios sobre cómo formular preguntas eficientes para el LLM puede reducir el uso excesivo de tokens por parte del cliente.