Asistente IA Local

Qué es y por qué existe

¿Qué es?

Es un chatbot con inteligencia artificial que corre completamente en tu propio computador, sin depender de servicios en la nube como OpenAI. Usa un modelo de IA local (a través de un programa llamado Ollama) para responder mensajes, y tiene un backend en Java y una interfaz web (dashboard) para conversar con él.

¿Por qué lo hice?

La motivación principal es reducir costos: los asistentes de IA basados en la nube cobran por cada mensaje o token que se envía, y ese costo crece con el uso. Al correr el modelo localmente:

• No hay costo por mensaje ni suscripción a una API externa.
• La información de la empresa o del usuario no sale del equipo, lo que mejora la privacidad.
• Se puede ajustar el comportamiento del asistente (sus reglas, su contexto) editando archivos simples, sin depender de un proveedor externo.

La idea de fondo es evaluar si un modelo local, más liviano y gratuito, puede ser una base razonable para un asistente virtual de empresa (atención a clientes, soporte interno, etc.) antes de invertir en soluciones pagadas en la nube.

Decisiones de diseño

Algunas decisiones se tomaron pensando en que este MVP pueda crecer hacia un producto real para empresas, no solo en que funcione hoy:

• Java como backend: se eligió por ser un lenguaje robusto y probado para sistemas que necesitan crecer. Facilita escalar el proyecto y prepararlo para soportar múltiples usuarios de forma ordenada, algo que sería más difícil de mantener con una base de código pensada solo para un prototipo rápido.
• Modelo de IA local: se optó por correr el modelo en el propio equipo (en vez de usar una IA en la nube) principalmente por privacidad. Los datos de una empresa nunca salen del entorno controlado, lo que reduce el riesgo de filtraciones de información sensible.
• Telegram como canal inicial: se usa por ahora porque es rápido y simple de integrar para pruebas, pero el diseño permite escalar fácilmente hacia canales más orientados a empresas, como WhatsApp Business.
• Base de datos (H2): se usa una base simple en archivo para agilizar esta primera etapa, pero la estructura está pensada para escalar sin problemas hacia un motor más robusto (como PostgreSQL) cuando el proyecto lo requiera.
• Contenedores (Docker): aunque no están activos en este MVP, el proyecto contempla poder integrarlos a futuro para mantener todo el entorno funcionando en local y controlado, evitando así fugas de datos en escenarios empresariales más complejos.

¿Qué hace hoy?

• Permite chatear con el asistente desde una interfaz web simple.
• Responde usando un modelo de IA (gemma2:2b) que corre en el mismo equipo.
• Su "conocimiento" de contexto (información del proyecto, reglas, datos del usuario) se edita en archivos de texto, sin tocar código.
• Guarda el historial de conversaciones.
• Tiene un horario de atención configurable (por defecto, días y horas de oficina).
• Puede conectarse opcionalmente a Telegram (viene desactivado).

¿Qué no hace todavía?

• No usa proveedores de IA en la nube (OpenAI u otros).
• No está pensado para múltiples usuarios o empresas al mismo tiempo, solo para un uso individual.
• No usa Docker ni una base de datos de producción (PostgreSQL); por ahora usa una base de datos simple en un archivo local. Esa migración está planeada, pero no implementada (ver "Qué viene después" más abajo).

---

Documentación técnica

Tecnologías principales

Área	Tecnología
Backend	Java 21 + Spring Boot 3.5
Build	Maven (vía Maven Wrapper, no requiere instalación aparte)
Base de datos	H2 (archivo local) + JPA + Flyway
IA	Ollama 0.32 + modelo gemma2:2b
Contexto editable	Archivos JSON (UTF-8)
Frontend	Next.js 16 + React 19 + TypeScript
Tareas programadas	Quartz
Autenticación	HTTP Basic (uso local)

Arquitectura general

flowchart LR
    user["Usuario"] --> ui["Dashboard (Next.js)<br/>localhost:3000"]
    ui -->|"HTTP + JSON"| api["Backend Java<br/>(Spring Boot) :8080"]
    api --> conv["Lógica de conversación"]
    conv -->|"1. arma contexto"| ctx["Servicio de Contexto"]
    conv -->|"2. genera respuesta"| llm["Servicio LLM"]
    llm --> ollama["Ollama local<br/>gemma2:2b"]
    ctx --> json["4 archivos JSON editables"]
    conv --> db["Base de datos H2<br/>(archivo local)"]

Loading

El backend es un monolito modular: toda la lógica (conversación, contexto, conexión con Ollama, configuración) vive en una sola aplicación Java. El dashboard, el backend y Ollama son tres procesos separados que se comunican por HTTP, todos en el mismo equipo.

Flujo de una conversación

sequenceDiagram
    actor U as Usuario
    participant UI as Dashboard
    participant API as Backend
    participant CTX as Contexto
    participant LLM as Ollama

    U->>UI: Escribe un mensaje
    UI->>API: Envía el mensaje
    API->>CTX: Busca información relevante (JSON)
    CTX-->>API: Fragmento de contexto
    API->>LLM: Envía historial + contexto + mensaje
    LLM-->>API: Respuesta generada
    API-->>UI: Responde y guarda en base de datos
    UI-->>U: Muestra la respuesta

Loading

El navegador nunca habla directamente con Ollama: siempre pasa por el backend, que controla el prompt, el contexto y los errores.

Contexto editable (JSON)

Hay 4 archivos JSON que alimentan al asistente con información, sin necesitar recompilar nada:

• user-context.json — perfil y preferencias del usuario.
• project-context.json — información del proyecto/empresa.
• assistant-rules.json — reglas de comportamiento del asistente.
• conversation-context.json — datos temporales o cambiantes.

Cada elemento dentro de estos archivos tiene un texto, palabras clave (para saber cuándo es relevante), una prioridad y un interruptor de encendido/apagado. Si un archivo falta o está mal formado, el sistema no falla: ignora ese elemento, deja una advertencia y sigue funcionando con reglas seguras por defecto.

Integración con Ollama

• URL local: http://localhost:11434
• Modelo: gemma2:2b
• Sin streaming (la respuesta llega completa, no palabra por palabra).
• Tiempo de espera configurable (120 segundos por defecto).
• Si Ollama está apagado o responde algo inválido, el backend devuelve un error claro (no una respuesta falsa).

Base de datos y configuración

• H2 guarda configuración, conversaciones, mensajes, eventos y reportes en un solo archivo local (data/database/assistant.mv.db).
• La configuración (modelo, URL, horario, contraseña, etc.) se puede ajustar por variables de entorno al iniciar, o después desde el dashboard.
• Variables más relevantes: APP_ADMIN_PASSWORD, OLLAMA_MODEL, OLLAMA_BASE_URL, ASSISTANT_CONTEXT_DIRECTORY.

API principal

Método	Ruta	Qué hace
GET	/api/public/health	Verifica que el backend esté vivo
POST	/api/conversations/messages	Envía un mensaje y obtiene la respuesta del asistente
GET	/api/conversations	Lista conversaciones
GET/PUT	/api/configuration	Consulta o actualiza la configuración
POST	/api/integrations/ollama/test	Prueba la conexión con Ollama
GET/POST/PUT	/api/reports	Gestión de reportes

Todos requieren autenticación básica, salvo el endpoint de salud.

Requisitos para instalarlo

• Windows 10/11, JDK 21, Node.js 22+, Ollama instalado con el modelo gemma2:2b descargado.
• Opcional: Eclipse, si se quiere revisar o modificar el código.

Puesta en marcha (resumen)

1. Verificar el entorno con el script incluido (check-environment.ps1).
2. Iniciar Ollama y confirmar que el modelo esté disponible.
3. Iniciar el backend (run-backend.ps1) → queda en localhost:8080.
4. Iniciar el dashboard (run-dashboard.ps1) → queda en localhost:3000.
5. Conectarse desde el dashboard con el usuario admin y la contraseña inicial (cambiarla apenas sea posible).

Pruebas realizadas

Se ejecutaron pruebas automatizadas (24 en total, todas exitosas) que cubren: manejo de contexto (archivos faltantes o corruptos), comportamiento cuando Ollama está apagado, persistencia de conversaciones, y el horario de atención. También se validó en la práctica que el asistente responde correctamente con el modelo real y que los datos persisten tras reiniciar.

Seguridad y privacidad

• Mientras Ollama corra localmente, nada de la conversación sale del equipo.
• No guardar contraseñas ni datos sensibles en los archivos de contexto.
• Cambiar la contraseña por defecto antes de un uso más permanente.
• No exponer los puertos (3000, 8080, 11434) a internet sin protección adicional.

Limitaciones actuales

• Pensado para un solo usuario/instalación a la vez.
• Solo soporta Ollama como proveedor de IA.
• La calidad de respuesta depende del modelo pequeño gemma2:2b.
• El contexto se selecciona por palabras clave, no con búsqueda semántica (embeddings).
• Sin respuestas en tiempo real (streaming); la respuesta llega completa al final.

Qué viene después

• Posible migración a PostgreSQL y Docker (documentado como plan a futuro, no implementado aún).
• Respuestas en tiempo real (streaming).
• Mejor selección de contexto (por ejemplo, con búsqueda semántica).
• Respaldo automático de la base de datos.
• Comparación de rendimiento entre distintos modelos locales.