ClarityDocs AI — Explainer

Concepto

ClarityDocs AI es una plataforma B2B SaaS de **inteligencia documental con explicabilidad y supervisión humana** para equipos legales, de cumplimiento y riesgo en sectores regulados (financiero, legal, seguros). A diferencia de una IA genérica de "caja negra", cada respuesta generada se ancla a un fragmento y página exactos del documento original, y pasa por un ciclo de revisión humana antes de considerarse confiable para uso en auditoría.

Problema que ataca: profesionales regulados pierden horas verificando documentos densos, y las herramientas de IA existentes no ofrecen trazabilidad legalmente exigible. La solución: un motor RAG (Retrieval-Augmented Generation) que cita sus fuentes de forma verificable, más una interfaz de revisión que crea un registro de auditoría exportable.

Arquitectura

Spring Boot 4.0.4 / Java 25, capas clásicas %%INLINE0%% → %%INLINE1%% → %%INLINE2%% → %%INLINE3%%:

controller/   AuthController, DocumentController, QueryController, AuditController
service/      AuthService, DocumentService, TextExtractionService, ChunkingService,
              EmbeddingService, QAService, ReviewService, AuditReportService
repository/   UserRepository, DocumentMetadataRepository, DocumentChunkRepository,
              QAPairRepository, AuditTrailRepository (Spring Data JPA)
model/        User, DocumentMetadata, DocumentChunk, QAPair, AuditTrail (entidades JPA),
              Role, DocumentStatus, VerificationStatus (enums), EmbeddingConverter
dto/          Records inmutables para requests/responses
client/       LlmFeignClient (OpenFeign) + ChatCompletionRequest/Response/ChatMessage/ChatChoice
security/     JwtService, JwtAuthenticationFilter, CustomUserDetailsService, SecurityConfig
config/       JacksonConfig (pre-provisto), JwtProperties, LlmProperties, AppPropertiesConfig,
              FeignClientConfig
exception/    ApiException, GlobalExceptionHandler

Pipeline de ingesta (DocumentService.processDocument):

1. Se sube el archivo (multipart), se genera un storageKey simulando un bucket S3/GCS cifrado.
2. %%INLINE6%% extrae texto plano. Nota de honestidad técnica: el %%INLINE7%%

pre-provisto de este proyecto no incluye Apache Tika, por lo que el parser MVP soporta texto plano UTF-8 directo; en producción se sustituye por AutoDetectParser de Tika para PDF/DOCX binarios reales (requiere añadir %%INLINE9%%/%%INLINE10%% al pom).

1. ChunkingService divide el texto en fragmentos de ~800 caracteres.
2. EmbeddingService genera un embedding determinístico (hashing de bag-of-words, 64 dims,

normalizado) por chunk. Nota: simula el embedding real para que el pipeline funcione sin credenciales de proveedor; en producción se reemplaza por una llamada al endpoint de embeddings del LLM vía OpenFeign, y el vector se persiste con el tipo nativo vector de la extensión pgvector en vez de la columna %%INLINE14%% serializada que usa %%INLINE15%%.

1. Los chunks + embeddings se persisten en document_chunk.

Pipeline de Q&A (RAG) (QAService.askQuestion):

1. Se genera el embedding de la pregunta con el mismo EmbeddingService.
2. Se calcula similitud coseno contra todos los chunks del documento y se toman los TOP_K=3.
3. Se arma un prompt con el contexto recuperado y se llama a LlmFeignClient (OpenFeign) contra

el LLM externo configurado (%%INLINE21%%, modelo %%INLINE22%% por defecto, compatible con la API de chat completions de OpenAI/Claude).

1. Si la llamada externa falla (sin API key configurada, red no disponible), se degrada a una

respuesta extractiva local con el fragmento más relevante — el sistema nunca se cae por falta de credenciales de LLM.

1. La respuesta y sus fuentes (SourceReferenceDto: chunk, página, extracto, score) se persisten

como %%INLINE24%% con estado %%INLINE25%%, y se registra un AuditTrail.

Revisión humana (%%INLINE27%%): un revisor cambia el estado a %%INLINE28%%, %%INLINE29%% (con texto corregido) o %%INLINE30%%, quedando trazado en AuditTrail.

Informe de auditoría (%%INLINE32%%): lista de %%INLINE33%% por documento — pregunta, respuesta, estado de verificación, revisor y fuentes citadas.

Seguridad: JWT stateless (%%INLINE34%% 0.12.6). %%INLINE35%% es público; el resto de endpoints exige %%INLINE36%%, validado por %%INLINE37%%. Contraseñas con BCrypt.

Endpoints

Método	Ruta	Descripción	Auth
POST	/api/auth/register	Alta de usuario, devuelve JWT	No
POST	/api/auth/login	Login, devuelve JWT	No
POST	%%INLINE40%% (multipart %%INLINE41%%)	Carga y procesa un documento (extrae, chunkea, embebe)	Sí
GET	/api/documents	Lista documentos del usuario autenticado	Sí
POST	/api/documents/{id}/query	Pregunta en lenguaje natural sobre el documento (RAG)	Sí
PUT	/api/queries/{queryId}/review	Revisión humana: validar/corregir/rechazar	Sí
GET	/api/documents/{id}/audit-report	Informe de auditoría exportable	Sí

Referencias

• Business case: "Inteligencia Documental con Explicabilidad y Supervisión Humana" (Y Combinator,

https://www.ycombinator.com/companies/industry/Artificial%20Intelligence).

• Spring Boot 4.0.4 / Spring Framework 7.x, Jakarta EE 11, Jackson 3 (tools.jackson.*).
• jjwt 0.12.6 (io.jsonwebtoken), Spring Cloud OpenFeign 4.2.1.

Análisis de negocio

• Monetización: SaaS B2B por niveles — usuarios activos, volumen de documentos procesados,

acceso a informes de auditoría avanzados (feature ya presente en el MVP como diferenciador de tier superior).

• Ventaja competitiva: citación verificable por fragmento/página + ciclo de revisión humana

auditable resuelve el problema de confianza que bloquea la adopción de IA genérica en legal, compliance y riesgo.

• Camino a producción: reemplazar el extractor de texto por Apache Tika, el embedding

simulado por el endpoint de embeddings real del LLM, la columna TEXT de embeddings por pgvector, y el storageKey simulado por una subida real a S3/GCS con cifrado en reposo (KMS).

Cómo ejecutar

Requiere PostgreSQL accesible. El %%INLINE50%% pre-provisto no fija %%INLINE51%%; Spring Boot los toma de variables de entorno (relaxed binding), por ejemplo:

export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/claritydocs
export SPRING_DATASOURCE_USERNAME=claritydocs
export SPRING_DATASOURCE_PASSWORD=claritydocs
export SPRING_JPA_HIBERNATE_DDL_AUTO=update

export SECURITY_JWT_SECRET=cambia-este-secreto-por-uno-de-al-menos-32-bytes
export LLM_API_URL=https://api.openai.com
export LLM_API_KEY=sk-...
export LLM_API_MODEL=gpt-4o-mini

mvn spring-boot:run

Flujo de prueba rápido:

# 1. Registro
curl -X POST localhost:8080/api/auth/register -H "Content-Type: application/json" \
  -d '{"username":"ana","email":"ana@empresa.com","password":"secreta123","role":"ANALYST"}'

# 2. Subir documento (usar el token del paso 1)
curl -X POST localhost:8080/api/documents -H "Authorization: Bearer <TOKEN>" \
  -F "file=@contrato.txt"

# 3. Preguntar
curl -X POST localhost:8080/api/documents/1/query -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" -d '{"question":"¿Cuál es la fecha de vencimiento?"}'

# 4. Revisar
curl -X PUT localhost:8080/api/queries/1/review -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"status":"VERIFIED","reviewerNote":"Confirmado contra cláusula 4.2"}'

# 5. Informe de auditoría
curl localhost:8080/api/documents/1/audit-report -H "Authorization: Bearer <TOKEN>"

---

FinOps Analysis para ClarityDocs AI

Resumen de Costos y Rentabilidad (MVP inicial)

Para una micro-startup como ClarityDocs AI en su fase MVP, la estrategia FinOps se centra en la eficiencia extrema y el monitoreo constante. Nuestros cálculos iniciales demuestran un modelo de negocio con un alto potencial de rentabilidad, asumiendo un enfoque muy lean en la infraestructura y el uso de APIs.

• Ingreso Mensual Estimado: $500 (basado en 20 clientes a $25/mes cada uno).
• Costos Operativos Mensuales Estimados: $50

* LLM/API (OpenAI gpt-4o-mini): $15 * Este presupuesto cubre aproximadamente 700K tokens/mes, distribuidos entre la generación de embeddings para nuevos documentos y las interacciones de Preguntas y Respuestas (RAG). Se asume el uso predominante de gpt-4o-mini por su excelente relación costo-rendimiento, con un buffer para picos o tareas específicas. * Cloud Hosting (AWS/GCP/Azure): $25 * Incluye una instancia de cómputo pequeña (ej. AWS EC2 t3.small o GCP e2-small) para la aplicación Spring Boot, almacenamiento de objetos (ej. AWS S3) para documentos originales, y costos mínimos de red y monitoreo básico. * Base de Datos (PostgreSQL con pgvector): $10 * Cubre una instancia de base de datos administrada pequeña (ej. AWS RDS db.t3.micro) para PostgreSQL, incluyendo el almacenamiento y las operaciones de E/S para los metadatos de documentos, pares Q&A y los vectores de embeddings.

• Margen de Beneficio Estimado: 90%

* ((500 - 50) / 500) * 100 = 90%

Este margen elevado es indicativo de un modelo de negocio con costos variables bien controlados y una infraestructura inicial muy optimizada. Es crucial mantener esta disciplina a medida que la startup escale.

Drivers Clave de Costo

Los principales impulsores de costo son el consumo de tokens de LLM y la infraestructura de base de datos/cómputo. El uso de pgvector en PostgreSQL ayuda a consolidar la base de datos, pero el volumen de embeddings y las consultas pueden aumentar los costos de E/S y almacenamiento a medida que crece la base de documentos.

Recomendaciones FinOps para Optimización Continua

1. Optimización del Consumo de LLM:

* Caching Inteligente: Implementar un sistema de caché para respuestas de LLM, especialmente para preguntas idénticas o muy similares sobre el mismo contexto documental. Esto reduce la necesidad de llamar al LLM repetidamente. * Selección Dinámica de Modelos: Utilizar %%INLINE55%% como modelo predeterminado para la mayoría de las operaciones de Q&A. Reservar modelos más potentes (y costosos) como %%INLINE56%% solo para funcionalidades de alto valor añadido que requieran mayor complejidad (ej. resúmenes ejecutivos avanzados, análisis de auditoría complejos) donde el costo adicional se justifique por el valor entregado. * Ingeniería de Prompts Eficiente: Refinar los prompts para ser lo más concisos posible, minimizando el número de tokens de entrada sin sacrificar la calidad de la respuesta. Esto incluye la optimización del tamaño de los chunks de RAG y la estrategia de recuperación.

1. Optimización de Infraestructura Cloud:

* Serverless para Cargas Irregulares: Considerar migrar el procesamiento de documentos (parsing y generación de embeddings) a funciones serverless (ej. AWS Lambda, Google Cloud Functions). Esto permite pagar solo por el tiempo de cómputo utilizado, ideal para cargas de trabajo que son bursty y no constantes. * Instancias Reservadas/Compromiso de Uso: Una vez que la carga de trabajo de la aplicación Spring Boot y la base de datos se estabilice, evaluar la compra de instancias reservadas (Reserved Instances en AWS) o contratos de compromiso de uso (Committed Use Discounts en GCP) para reducir los costos de cómputo y base de datos en un 30-60%. * Monitorización de Almacenamiento: Monitorear el crecimiento de S3 y los volúmenes de pgvector en PostgreSQL. Implementar políticas de ciclo de vida para S3 si los documentos más antiguos pueden ser movidos a almacenamiento de menor costo.

1. Gestión de Costos Proactiva:

* Dashboards de Costos: Configurar dashboards de costos en la nube (ej. AWS Cost Explorer, GCP Billing Reports) y herramientas de terceros para tener visibilidad en tiempo real del gasto. Establecer alertas para desviaciones significativas. * Control de Versiones y Despliegue (CI/CD): Asegurar que el pipeline de CI/CD incluya pruebas de rendimiento y estrés para detectar ineficiencias antes de que lleguen a producción, evitando costos inesperados por escalado excesivo o bugs. * Cuotas y Límites por Cliente: A medida que la plataforma crezca, implementar límites de uso (ej. número de documentos, preguntas por mes) para cada nivel de suscripción, permitiendo controlar mejor los costos variables asociados al consumo de LLM y recursos de cómputo.

Adoptando estas prácticas FinOps desde el inicio, ClarityDocs AI puede asegurar un crecimiento sostenible y mantener su alta rentabilidad a medida que escala.