Middleware Inteligente para Clasificación y Routing de Requerimientos Operacionales
Skema automatiza el triaje, categorización y enrutamiento de requerimientos de software a escala, transformando entradas de texto no estructurado en datos operativos accionables con inteligencia híbrida y feedback humano.
En equipos de producto y operaciones de ingeniería de alto volumen, la entrada de requerimientos (tickets, feedback de usuarios, historias de usuario) es caótica y ruidosa.
- Cuello de botella manual: Product Managers y Tech Leads pierden horas semanales clasificando y asignando tickets.
- Inconsistencia: La clasificación manual varía según quién la haga y cuándo.
- Datos muertos: El feedback valioso se pierde en el ruido por falta de etiquetado inmediato.
- Costo operacional: Clasificación deficiente genera routing incorrecto y retrasos en resolución.
Skema es un sistema operativo de intake inteligente diseñado para operar como middleware entre las fuentes de entrada (GitHub, Jira, Slack, Email) y los sistemas de gestión.
- Modularidad Aislada: La lógica de ingesta, limpieza, inferencia y persistencia están completamente desacopladas. Cambiar el motor de clasificación no afecta la API.
- Product-Ready: Construido con observabilidad, contratos de datos estrictos, persistencia real y operación continua en mente.
- Agnóstico al Modelo: Arquitectura hexagonal que permite intercambiar motores de clasificación (Reglas → Embeddings → LLMs → Ensembles) sin reescribir el sistema.
- Feedback Loop: Incorpora correcciones humanas para mejora continua del sistema.
- Reglas Keyword-Based: Detecta patrones determinísticos rápidamente
- Embeddings Semánticos: Búsqueda semántica cuando las reglas son insuficientes
- Confidence Scoring Real: Score 0.0-1.0 que refleja certeza verdadera
- Fallback Elegante: Sistema sigue funcionando incluso si embeddings no están disponibles
- PostgreSQL ORM: Persistencia real con SQLAlchemy
- 4 Modelos de Datos: Requirements, Classifications, Feedback, Metrics
- Feedback Loop Completo: Captura correcciones humanas para mejora continua
- Home: Últimas clasificaciones + estadísticas en tiempo real
- Revisión: Tickets de baja confianza listos para corrección humana
- Métricas: Distribución de categorías, histogramas de confianza, precisión
POST /classify- Clasificar nuevo requerimientoPOST /api/feedback- Registrar feedback humanoGET /- Dashboard principalGET /review- Panel de revisiónGET /metrics- Métricas del sistemaGET /health- Health check
- Bug: Defectos, errores, crashes
- Feature: Nuevas funcionalidades, mejoras
- Documentation: Docs, wikis, guías
- Infrastructure: DevOps, deployment, CI/CD
- Performance: Optimización, escalabilidad
- Security: Vulnerabilidades, seguridad
- General: Otros
┌─────────────────────────────────────────────────────────────┐
│ Entrada Externa │
│ (GitHub, Jira, Email, API) │
└─────────────────────────────────┬───────────────────────────┘
│
┌─────────────▼──────────────┐
│ FastAPI REST Endpoint │
│ /classify │
└─────────────┬──────────────┘
│
┌─────────────────────────▼──────────────────────────┐
│ Use Case: ClassifyRequirement │
└─────────────────────────┬──────────────────────────┘
│
┌─────────────────────────▼──────────────────────────┐
│ HybridClassifier Adapter │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Keyword Rules│ │ Embeddings │ │
│ └──────────────┘ └──────────────┘ │
│ │ │ │
│ └──────┬───────────┘ │
│ ▼ │
│ Confidence Score │
│ (0.0 - 1.0) │
└─────────────────────────┬──────────────────────────┘
│
┌─────────────────────────▼──────────────────────────┐
│ PostgreSQL Repository │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Requirements │ │Classifications│ │
│ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Feedback │ │ Metrics │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────┬──────────────────────────┘
│
┌─────────────▼──────────────┐
│ Dashboard + Observabilidad│
│ (Métricas, Precisión, UI) │
└────────────────────────────┘
# 1. Construye y levanta servicios
docker-compose up --build
# 2. En otra terminal: carga demo con 200 tickets
docker exec -it skema_api python scripts/demo.py
# 3. Abre dashboard
open http://localhost:8000# 1. Instala dependencias
pip install -r requirements.txt
# 2. Configura variable de entorno
export DATABASE_URL="postgresql://skema:skema@localhost:5432/skema_db"
# 3. Ejecuta demostración
python scripts/demo.py --count 200
# 4. Levanta API
python -m skema.api.main
# 5. Abre http://localhost:8000✅ 200 tickets clasificados automáticamente
✅ Dashboard visible con últimas clasificaciones
✅ Puedes proporcionar feedback humano
✅ Métricas en tiempo real
Estadísticas:
- Total procesado: 200
- Confianza promedio: 0.82
- Baja confianza (<60%): ~15 tickets
- Distribución: 30% Bugs, 25% Features, 15% Infrastructure, etc.
- Abre http://localhost:8000 (Dashboard Home)
- Verás últimas 20 clasificaciones automáticas
- Haz click en botón "Feedback" en cualquier ticket
- Proporciona feedback:
- "✓ Correcta" → marca como acertado
- "✎ Corregir" → proporciona categoría correcta
- En
/metricsverás actualizada la precisión
skema/
├── core/ # Dominio (limpio, sin dependencias)
│ ├── interfaces.py # Puertos hexagonales
│ ├── models.py # Entidades y Value Objects
│ └── use_cases.py # Application Services
├── adapters/ # Implementaciones concretas
│ ├── classifiers.py # Dummy + Hybrid (Reglas + Embeddings)
│ └── processor.py # Limpieza de texto
├── infrastructure/ # Capas técnicas
│ ├── database.py # SQLAlchemy setup
│ ├── models.py # ORM Models
│ └── repositories.py # PostgreSQL implementations
├── api/ # API REST + Dashboard
│ └── main.py # FastAPI server
├── dashboard/ # UI (Jinja2 templates)
│ └── templates/ # HTML pages
├── datasets/ # Data generation
│ └── __init__.py # Synthetic ticket generator
├── bootstrap.py # Dependency injection
└── tests/ # Test suite
- Clasificador híbrido (Reglas + Embeddings)
- Persistencia PostgreSQL
- Dashboard operacional (3 páginas)
- Feedback loop humano
- Dataset sintético realista
- Docker + docker-compose
- Logging estructurado (JSON)
- Prometheus metrics
- Unit + Integration tests
- Error handling mejorado
- CI/CD pipeline
- GitHub Issues adapter
- Jira API adapter
- Webhook listeners
- Batch processing
- Reentrenamiento incremental
- Multi-model ensemble
- Detección de drift
- Recomendaciones automáticas
- QUICKSTART.md - Instrucciones rápidas (5 minutos)
- CHANGELOG_MVP.md - Cambios técnicos detallados
- ARQUITECTURA.md - Visión de alto nivel
- docs/agents.md - Documento de agentes
- docs/skills.md - Documento de skills
Copia .env.example a .env y ajusta según necesites:
# Database
DATABASE_URL=postgresql://skema:skema@localhost:5432/skema_db
# API
API_PORT=8000
# Classifier
CLASSIFIER_MODEL=hybrid
CONFIDENCE_THRESHOLD=0.60
# Embeddings
EMBEDDINGS_MODEL=all-MiniLM-L6-v2- Backlog Grooming Automático: Etiquetar tickets como Bug/Feature/Tech Debt antes de que un humano los vea
- Routing de Soporte N1: Detectar keywords críticas para escalar incidentes de seguridad inmediatamente
- Análisis de Tendencias: Identificar patrones en miles de comentarios de usuarios
- Matriz de Impacto: Priorizar features basado en volumen de feedback
- Auditoría: Revisar decisiones automáticas con feedback humano
Por favor consulta BITACORA.md para detalles de desarrollo.
MIT
Estado Actual: FASE 1 - MVP Funcional ✅ Última actualización: 15 de mayo de 2026
Para más detalles técnicos, ver CHANGELOG_MVP.md