ART Redmine es una plataforma operativa para equipos de soporte que sincroniza tickets desde Redmine, clasifica prioridad y completitud, recupera contexto local, redacta una respuesta propuesta y deja cada decisión lista para revisión humana, auditoría y mejora continua.
El proyecto está diseñado como un MVP profesional, demostrable y extensible: integra backend FastAPI, dashboard React, persistencia local o PostgreSQL, autenticación con roles, segundo factor, sincronización de usuarios con Redmine y un flujo de validación antes de publicar cualquier respuesta en Redmine.
Agente para Redmine es un proyecto abierto y distribuido bajo la licencia MIT. La comunidad puede estudiarlo, usarlo, adaptarlo y colaborar mediante issues y pull requests. Toda contribución debe preservar la revisión humana, la seguridad y la trazabilidad como principios del producto.
redmine fastapi react vite postgresql docker dashboard ticketing support-automation audit-log knowledge-base human-review workflow-automation open-source
En equipos de soporte, responder tickets exige leer contexto, detectar faltantes, mantener criterio consistente y documentar decisiones. ART centraliza ese flujo en un panel operativo:
- sincroniza tickets, prioridades, estados y usuarios desde Redmine;
- identifica si el caso corresponde al solicitante o al equipo interno;
- clasifica categoría, nivel de soporte, prioridad sugerida y completitud;
- recupera reglas, procedimientos y antecedentes validados;
- analiza adjuntos Redmine legibles como contexto de la respuesta;
- genera una propuesta editable para el consultor;
- exige revisión humana antes de aprobar o publicar;
- registra auditoría, actividad administrativa y trazabilidad de decisiones;
- agrupa incidentes repetidos, mide calidad y señala brechas de conocimiento o riesgo SLA;
- administra usuarios, roles y grupos con equivalencia Redmine;
- permite que el aprendizaje tome ejemplos desde journals y respuestas reales de Redmine.
| Área | Descripción |
|---|---|
| Dashboard operativo | Cola de propuestas, métricas, filtros por responsabilidad, prioridad, período y asignación. |
| Mesa de validación | Revisión del ticket, respuesta propuesta editable, fuentes utilizadas, decisión y publicación controlada. |
| Adjuntos Redmine | Pestaña condicional de adjuntos, vista previa de imagen/PDF/texto, descarga segura e iconos por tipo. |
| Contexto de adjuntos para IA | Extracción de texto desde TXT/CSV/JSON/XML, PDF y DOCX; OCR opcional para imágenes y PDFs escaneados. |
| Kanban | Tablero horizontal con columnas de estado ART, tarjetas pequeñas y detalle modal por ticket. |
| Semáforo operativo | Informe IA bajo demanda que clasifica la salud del sistema en verde, amarillo o rojo sin llamadas automáticas continuas. |
| Análisis | Radar de incidentes, calidad de respuestas, brechas de conocimiento y riesgo SLA explicable, además de volumen y confianza. |
| Actividad | Registro auditable de eventos, acciones administrativas y contexto de request. |
| Administración | Usuarios, roles, permisos, grupos Redmine, activación, segundo factor, reseteo de clave y base general de conocimiento. |
| Perfil y Redmine personal | Configuración individual de credenciales, conexión y datos del usuario. |
| Gobierno Redmine | Alta o actualización de usuarios en Redmine, membresías por proyecto, grupos, watchers, relaciones, tiempos y workflow. |
| Aprendizaje desde journals | Importación supervisada de notas de Redmine como ejemplos para mejorar futuras propuestas. |
| Tour ARTI | Recorrido guiado con mascota, ayudas contextuales y assets visuales para explicar el sistema. |
| Panel embebido Redmine | Plugin liviano para ver propuesta, fuentes y riesgo dentro de cada issue. |
| Persistencia | Soporte para archivos JSON locales o PostgreSQL en despliegues persistentes. |
| Despliegue | Imagen Docker y Docker Compose para ejecución local o en servidores propios. |
flowchart LR
A[Redmine API] --> B[FastAPI]
B --> C[Motor ART]
C --> D[Clasificación]
C --> E[Contexto local]
C --> F[Respuesta propuesta]
B --> G[(PostgreSQL o runtime JSON)]
B --> H[Dashboard React]
H --> I[Validación humana]
I --> J[Auditoría]
I --> K[Publicación controlada]
- Python, FastAPI y Pydantic.
- Cliente Redmine con manejo de tickets, usuarios, prioridades y perfiles.
- Operaciones Redmine extendidas: usuarios, roles, grupos, membresías, watchers, relaciones, tiempos, estados permitidos y workflow.
- Proxy seguro de adjuntos y extractor de contexto para generación IA.
- OCR local opcional con Tesseract/Poppler para imágenes y PDFs escaneados.
- Clasificación operativa y reglas de completitud.
- Motor de propuestas con fallback local.
- Auditoría, autenticación, permisos por rol, TOTP y almacenamiento configurable.
- React 19 con Vite.
- CSS global propio, sin framework visual externo.
- Interfaz en español orientada a soporte y consultoría.
- Pantallas principales: Dashboard, Análisis, Validación, Actividad, Documentación, Configuración, Perfil y Administración.
- Kanban operativo y vista móvil simplificada para priorizar validación de tickets.
- Tour guiado con ARTI y ayudas contextuales para conexión Redmine, roles, seguridad, aprendizaje y búsqueda de tickets.
runtime/para estado local generado.- PostgreSQL para despliegues persistentes.
- Base de conocimiento editable y ejemplos de respuestas validadas.
- Identidad Redmine por usuario:
redmine_user_id, rol Redmine, membresías de proyecto y grupos. - Journals importados como memoria de aprendizaje cuando el administrador lo solicita.
- El sistema sincroniza tickets desde Redmine.
- Cada ticket se normaliza y clasifica por prioridad, categoría, nivel y completitud.
- Al regenerar con IA, ART descarga adjuntos acotados y extrae texto de formatos soportados.
- Si el adjunto es imagen o PDF escaneado, intenta OCR local cuando el runtime tiene Tesseract/Poppler.
- ART recupera contexto útil desde reglas, conocimiento local, adjuntos y ejemplos validados.
- Se prepara una respuesta propuesta editable.
- Un consultor revisa, corrige, aprueba o descarta.
- La decisión queda auditada.
- Si corresponde, la respuesta validada puede publicarse de forma controlada en Redmine.
- El administrador puede importar journals de Redmine para alimentar ejemplos supervisados.
- Los usuarios pueden mantenerse alineados entre ART y Redmine con rol, grupos y proyectos.
ART mantiene un modelo de permisos propio y lo aproxima al modelo de Redmine:
| Rol ART | Equivalencia Redmine sugerida | Permisos principales |
|---|---|---|
| Administrador | Manager | Operación completa, usuarios, seguridad, auditoría, conocimiento general, importación de journals y publicación. |
| Operador | Developer | Gestión de tickets, validación, publicación, workflow, tiempos, relaciones y base personal. |
| Solo lectura | Reporter | Consulta de tickets, métricas y trazabilidad sin modificar ART ni Redmine. |
Desde Administración se puede:
- crear usuarios locales y, opcionalmente, replicarlos en Redmine;
- asignar rol Redmine explícito o usar la equivalencia por rol ART;
- asociar proyectos y grupos Redmine;
- cambiar rol local y sincronizar el cambio con Redmine;
- resetear clave local y propagar contraseña temporal a Redmine cuando corresponde;
- auditar desvíos entre usuarios ART y Redmine, incluyendo roles, membresías, grupos, vínculos, 2FA y usuarios activos fuera de ART;
- consultar la matriz real de permisos Redmine para recertificar roles;
- revisar permisos efectivos, estado de 2FA, vínculo Redmine y grupos asignados.
Además de leer tickets y publicar notas, la API interna expone operaciones para acercar ART al uso diario de Redmine:
- detalle completo del issue con journals, adjuntos, relaciones, watchers y estados permitidos;
- descarga autenticada de adjuntos para vista previa y extracción de contexto;
- cambio controlado de estado, prioridad, responsable, categoría, versión y fecha objetivo;
- alta y baja de watchers;
- creación y eliminación de relaciones entre issues;
- carga y eliminación de tiempo trabajado;
- lectura de consultas guardadas y proyectos visibles;
- catálogo administrativo de roles, permisos, proyectos, grupos, campos personalizados, categorías y versiones;
- guardrails de workflow que rechazan estados, prioridades, responsables, fechas o campos personalizados no válidos antes de impactar Redmine.
El aprendizaje no depende solamente de respuestas aprobadas dentro de ART. Los administradores pueden importar journals de Redmine para convertir notas reales en ejemplos supervisados:
- ART consulta issues y journals según proyectos, estado y paginación configurada.
- Filtra notas demasiado cortas o privadas si el administrador lo indica.
- Registra ejemplos con asunto, descripción, respuesta, metadatos y embedding.
- Las siguientes propuestas recuperan ejemplos similares como memoria operativa.
Este flujo mantiene la validación humana como control principal: los journals aportan contexto y ejemplos, pero no habilitan publicación automática.
La base de conocimiento combina BM25, contexto de categoria/area y embeddings. El modo liviano usa hash-v2, con normalizacion de acentos, bigramas y fragmentos de palabras; la memoria de respuestas validadas reutiliza el mismo motor, evita recuperar el ticket actual y deduplica respuestas. En produccion liviana el valor recomendado sigue siendo:
ART_KNOWLEDGE_EMBEDDER=hashSi el entorno instala requirements-ml.txt, puede usarse ART_KNOWLEDGE_EMBEDDER=auto o sentence-transformers con intfloat/multilingual-e5-small. ART aplica los prefijos query/passage requeridos por E5 y guarda los vectores de conocimiento en runtime/embeddings/knowledge-*.json, invalidados por hash de entradas, proveedor, version y modelo. Si el proveedor semantico falla, la propuesta deja diagnostico del fallback a hash-v2 en sus metadatos de generacion.
Cuando el usuario presiona Generar respuesta, ART puede sumar adjuntos al contexto del prompt sin enviar archivos crudos:
- TXT, CSV, JSON, XML y Markdown se leen como texto.
- PDF se procesa con
pypdfpara extraer la capa textual. - DOCX se procesa con
python-docx. - Imágenes y PDFs escaneados usan OCR local si el runtime tiene
tesseractypdftoppm. - Si OCR no está disponible o el archivo no tiene texto legible, la propuesta debe pedir una versión legible o el dato puntual, no inventar contenido.
El Dockerfile productivo instala tesseract-ocr, tesseract-ocr-spa, tesseract-ocr-eng y poppler-utils para procesar OCR dentro del contenedor. Los límites se controlan por variables:
ART_ATTACHMENT_CONTEXT_ENABLED=true
ART_ATTACHMENT_OCR_ENABLED=true
ART_ATTACHMENT_OCR_LANGS="spa+eng"
ART_ATTACHMENT_MAX_BYTES=5000000
ART_ATTACHMENT_MAX_ITEMS=5
ART_ATTACHMENT_PDF_MAX_PAGES=5
ART_ATTACHMENT_OCR_MAX_PAGES=2
ART_REDMINE_UPLOAD_MAX_BYTES=10000000Desde la pestaña Adjuntos de Validación, los operadores con permiso de edición Redmine pueden cargar archivos nuevos al ticket. ART sube el archivo a Redmine, asocia el token al issue, refresca la copia local y deja auditoría de la operación.
La interfaz incorpora un recorrido guiado con la mascota ARTI para que nuevos usuarios entiendan el sistema sin depender de capacitación externa. El tour cubre dashboard, cola, validación, actividad, configuración, administración, roles, matriz de permisos, alta sincronizada y sincronización.
Los assets viven en:
frontend/public/tour-mascot/
Además de las poses base, se incorporaron variantes para roles, seguridad, aprendizaje y búsqueda/sincronización de tickets:
roles.png/roles.webpsecurity.png/security.webplearning.png/learning.webpticket-search.png/ticket-search.webp
ART está pensado para operar con control humano y trazabilidad:
- publicación bloqueada en modo seguro si
ART_DRY_RUN=true; - autenticación con sesiones;
- roles de administrador, operador y solo lectura con permisos explícitos;
- segundo factor TOTP;
- ocultamiento de credenciales sensibles;
- auditoría de eventos administrativos y operativos;
- separación entre propuesta, validación y publicación.
- sincronización opcional de usuarios, roles, proyectos y grupos con Redmine.
art_agent/ Backend, dominio, Redmine, auditoría y almacenamiento
frontend/src/ Dashboard React y estilos de la interfaz
data/ Datos de ejemplo y base de conocimiento inicial
docs/ Documentación técnica, operativa y visual
scripts/ Utilidades de operación, migración y pruebas
tests/ Suite de pruebas backend y contratos principales
docker-compose.yml App completa con PostgreSQL
Dockerfile Imagen productiva con frontend compilado
Crear un archivo .env desde .env.example y completar la configuración necesaria:
REDMINE_URL="https://tu-redmine.example.com"
REDMINE_API_KEY="TU_API_KEY"
ART_SECRET_KEY="clave-larga-aleatoria"
ART_DRY_RUN=true
ART_SLA_LOW_HOURS=72
ART_SLA_NORMAL_HOURS=48
ART_SLA_HIGH_HOURS=12
ART_SLA_URGENT_HOURS=4No se deben versionar claves reales, tokens ni datos sensibles.
Los valores ART_SLA_*_HOURS son la semilla historica para la configuracion inicial. El SLA operativo se administra desde Administracion > SLA, con reglas por proyecto, calendario laboral, feriados, estados pausados y tipos de ticket incluidos.
docker compose up --buildLa aplicación queda disponible en:
http://localhost:8000python -m pip install -r requirements.txt
python scripts/run_api.pycd frontend
npm install
npm run devPara apuntar el dashboard al backend local:
VITE_API_URL=http://localhost:8000 npm run devpython -m pytestcd frontend
npm run buildLa suite cubre autenticación, seguridad administrativa, cliente Redmine, filtros del dashboard, almacenamiento, memoria de aprendizaje, reglas operativas y contratos de API.
El proyecto incluye:
Dockerfileproductivo;docker-compose.ymlpara app y PostgreSQL local;- healthcheck en
/api/health; - soporte para almacenamiento PostgreSQL en producción y servidores autogestionados.
Healthcheck:
GET /api/healthGuía completa de requisitos, variables, Docker, validación y rollback: docs/despliegue.md.
El repositorio incluye un primer plugin liviano en redmine_plugins/art_redmine_panel. El plugin inserta un iframe en la vista de cada issue y carga el panel:
GET /embed/issues/{issue_id}El panel muestra propuesta, SLA, fuentes, confianza, riesgos, estado de sincronizacion y acceso directo a la mesa de validacion completa. Tambien permite copiar la respuesta propuesta desde el iframe cuando el navegador lo habilita. Para produccion, configurar el mismo secreto en Redmine y ART:
ART_EMBED_SHARED_SECRET=valor-largo-y-seguroGuía completa: docs/panel_redmine_plugin.md.
- Estado actual del producto:
docs/estado_actual.md. - Guía de despliegue:
docs/despliegue.md. - Plan funcional y técnico:
docs/plan_art.md. - Seguimiento de iteraciones:
docs/seguimiento.md. - Propuesta de resolución:
docs/propuesta.md. - Objetivo del proyecto:
docs/objetivo.md.
Las contribuciones son bienvenidas. Antes de proponer un cambio:
- Abrí un issue con el problema, mejora o caso de uso.
- Creá una rama enfocada y agregá pruebas cuando corresponda.
- Verificá
python -m pytestynpm run builddentro defrontend/. - Enviá un pull request explicando el impacto funcional y cualquier consideración de seguridad.
No incluyas credenciales, tokens, datos reales de tickets ni información personal en commits, ejemplos o reportes.
- Endurecer observabilidad y métricas de operación.
- Ampliar conectores de conocimiento documental.
- Validar los patrones repetidos y las brechas detectadas con históricos reales autorizados.
- Evolucionar las señales heurísticas de riesgo SLA hacia modelos calibrados cuando exista volumen de datos suficiente.
- Formalizar pipeline de despliegue continuo.
- Julieta Ventre
- Gian Sosa
- Gonzalo Otouzbirian
- Ivan Agustin Zarate
- Matias Gaya
Este proyecto se distribuye bajo la licencia MIT. Podés usarlo, modificarlo y redistribuirlo conforme a sus términos.