Skip to content
BranchesTags

Repository files navigation

Sapient Lab Backend

NestJS TypeScript MySQL Swagger Microsoft Innovation Challenge

Backend API para Sapient Lab, proyecto del Microsoft Innovation Challenge 2026 en el reto: Lab Notebook AI Assistant.

Contexto del reto

Challenge oficial (Innovation Challenge 2026):

Los investigadores quieren ayuda para razonar sobre experimentos sin reemplazar el juicio cientifico. Desarrolle un asistente de cuaderno de laboratorio basado en agentes que interprete protocolos experimentales, sugiera variaciones para los siguientes pasos y analice resultados a partir de texto, archivos CSV o imagenes, explicando claramente por que se hacen las recomendaciones. El sistema debe aplicar limites de seguridad estrictos (especialmente en dominios biologicos o clinicos), aplicar filtrado de contenido y evitar comportamientos de asesoramiento no permitidos. Los equipos deben centrarse en la explicabilidad, el diseno seguro de agentes y una orquestacion solida de datos y modelos.

Este backend implementa una arquitectura de agentes para responder exactamente a ese reto:

  • Interpretar protocolos experimentales.
  • Sugerir variaciones para los siguientes pasos.
  • Analizar resultados desde texto, CSV o imagenes.
  • Explicar de forma transparente por que se propone cada recomendacion.

Ademas, el sistema aplica controles de seguridad para reducir riesgos en contextos biologicos y clinicos, con foco en:

  • Explicabilidad
  • Diseno seguro de agentes
  • Orquestacion robusta de datos y modelos

Capacidades principales

  • Chat de investigacion con contexto de notebook.
  • Interpretacion y analisis de protocolos/resultados experimentales.
  • Analisis multimodal de imagenes y documentos.
  • Extraccion de contenido apto para insertar en notebook (sin envoltura conversacional).
  • Integraciones de plataforma (proyectos, notas, invitaciones, recursos, metricas).
  • Gestion de contexto de proyecto y documentos para enriquecer prompts.
  • Integraciones Microsoft y almacenamiento en Azure Blob.
  • Integracion OpenML para consultar datasets, tareas, runs y evaluaciones de benchmark.

Tecnologias

Categoria Stack
Runtime Node.js + TypeScript
Framework NestJS
Persistencia MySQL (mysql2)
Validacion class-validator, class-transformer
HTTP Cliente axios
API Docs @nestjs/swagger, swagger-ui-express
IA y agentes Azure Foundry/OpenAI
Recurso de benchmark OpenML API
Voz y vision Azure Speech, Azure Vision
Documentos Azure Document Intelligence
Archivos Azure Blob Storage

Arquitectura de modulos

Estructura principal en src:

OpenML en el flujo de investigacion

OpenML se usa como capa de soporte para razonamiento comparativo y validacion de hipotesis:

  1. El investigador formula una consulta en lenguaje natural en el notebook.
  2. El backend transforma esa consulta en criterios de busqueda (dataset/task/evaluation).
  3. Se consultan endpoints OpenML y se recupera metadata relevante.
  4. El agente sintetiza hallazgos y los presenta como recomendacion explicada.
  5. El modulo de seguridad valida que la recomendacion no cruce limites de asesoramiento no permitido.

Esto aporta trazabilidad porque cada recomendacion puede vincularse a evidencia externa de benchmark.

Principios de seguridad y explicabilidad

El backend esta orientado a que la IA asista, no sustituya, el criterio humano:

  • Recomendaciones con justificacion explicita.
  • Control de riesgo en contenido sensible (bio/clinico).
  • Filtrado de salidas para evitar asesoramiento no permitido.
  • Separacion entre orquestacion de agentes, capa de datos y capa HTTP.
  • Validacion estricta de payloads (ValidationPipe con whitelist y forbidNonWhitelisted).

Requisitos

  • Node.js 18+ recomendado.
  • MySQL 8+ (local o administrado).
  • Credenciales de al menos un proveedor de IA.

Instalacion y ejecucion

cd back_end
npm install

Crear variables de entorno:

copy .env.example .env

Ejecutar en desarrollo:

npm run start:dev

Compilar y ejecutar en modo produccion:

npm run build
npm run start:prod

Configuracion de entorno

Referencia base: .env.example.

Variables clave:

  • PORT: puerto HTTP (por defecto 3000).
  • REQUEST_BODY_LIMIT: limite de payload (por defecto 15mb).
  • CORS_ORIGINS: origenes permitidos separados por coma.

Nota de CORS:

  • El backend agrega por defecto https://zealous-cliff-0c0b6d90f.4.azurestaticapps.net y http://localhost:5173.
  • CORS_ORIGINS se fusiona con estos origenes base.

Base de datos:

  • MYSQL_HOST
  • MYSQL_PORT
  • MYSQL_USER
  • MYSQL_PASSWORD
  • MYSQL_DATABASE
  • MYSQL_SSL (true para entornos administrados con TLS)

Proveedor IA por defecto:

  • LLM_PROVIDER (valor esperado: azure)

Credenciales IA/integraciones (segun stack habilitado):

  • Azure Foundry / OpenAI
  • Azure Vision
  • Azure Speech
  • Azure Document Intelligence
  • Azure Storage Blob

Nota de compatibilidad:

  • En .env.example aun existen variables legacy de Mistral/DeepSeek, pero el proveedor activo del backend es Azure.

API base y documentacion

  • Base URL local: http://localhost:3000/api
  • Swagger (no production): http://localhost:3000/api/docs

El prefijo global api se aplica en src/main.ts.

Endpoints clave

Salud y estado

  • GET /api/health
  • GET /api/ai/providers/status

IA para notebook y analisis cientifico

  • POST /api/ai/conversation
  • POST /api/ai/notebook/chat
  • POST /api/ai/notebook/extract-insertable
  • POST /api/ai/protocol/interpret
  • POST /api/ai/results/analyze
  • POST /api/ai/images/analyze
  • POST /api/ai/analyze-image (compatibilidad)
  • POST /api/ai/document/analyze
  • POST /api/ai/speech
  • POST /api/ai/speech-to-text

Contexto de proyecto y documentos

  • PUT /api/project-context/:projectId
  • GET /api/project-context/:projectId
  • POST /api/project-context/:projectId/documents
  • GET /api/project-context/:projectId/documents
  • DELETE /api/project-context/:projectId/documents/:documentId
  • GET /api/project-context/:projectId/context-prompt
  • GET /api/project-context/:projectId/context-prompt-debug

API estilo Copilot

  • POST /api/ai/copilot/chat
  • POST /api/ai/copilot/completions
  • POST /api/ai/copilot/explain

Plataforma y notebook colaborativo

Nota: varias rutas de plataforma viven en el controlador raiz (sin prefijo platform), definidas en src/platform/platform.controller.ts.

  • POST /api/auth/register
  • POST /api/auth/login
  • GET /api/projects
  • POST /api/projects
  • POST /api/projects/:id/join
  • GET /api/frontend/home
  • GET /api/frontend/themes
  • POST /api/frontend/metrics/counter-clicks/increment
  • POST /api/experiments/:experimentId/notes
  • GET /api/experiments/:experimentId/notes
  • PUT /api/experiments/:experimentId/notes/:noteId
  • DELETE /api/experiments/:experimentId/notes/:noteId
  • POST /api/experiments/:experimentId/notes/:noteId/ai-suggestions

Otros modulos

  • POST /api/reports/generate
  • POST /api/reports/download-pdf
  • POST /api/safety/analyze
  • POST /api/storage/upload
  • GET /api/integrations/microsoft/status
  • POST /api/integrations/microsoft/teams/test

OpenML (nuevo recurso Innovation Challenge 2026)

  • GET /api/openml/datasets
  • GET /api/openml/datasets/qualities/list
  • GET /api/openml/datasets/tag
  • GET /api/openml/datasets/:id
  • GET /api/openml/datasets/:id/features
  • GET /api/openml/datasets/:id/qualities
  • GET /api/openml/tasks
  • GET /api/openml/tasks/types
  • GET /api/openml/tasks/types/:id
  • GET /api/openml/tasks/:id
  • GET /api/openml/flows
  • GET /api/openml/flows/exists
  • GET /api/openml/flows/:id
  • GET /api/openml/runs
  • GET /api/openml/runs/:id
  • GET /api/openml/runs/:id/trace
  • GET /api/openml/evaluations
  • GET /api/openml/evaluations/measures
  • GET /api/openml/setups/:id
  • GET /api/openml/studies
  • GET /api/openml/studies/:id

Flujo sugerido para el frontend

  1. Crear o recuperar contexto del experimento (notas/proyecto).
  2. Enviar mensaje a POST /api/ai/notebook/chat con contexto estructurado.
  3. Mostrar respuesta explicada al investigador.
  4. Si se quiere persistir en notebook, pasar la respuesta por POST /api/ai/notebook/extract-insertable.
  5. Guardar contenido limpio en notas del experimento.

Flujo complementario para contexto documental:

  1. Registrar contexto de proyecto con PUT /api/project-context/:projectId.
  2. Subir documentos con POST /api/project-context/:projectId/documents.
  3. Consumir endpoints de IA que aprovechan este contexto para respuestas mas precisas.

Coherencia con Frontend

  • El frontend consume siempre rutas bajo /api/*, coherente con el prefijo global en src/main.ts.
  • El notebook usa POST /api/ai/notebook/chat y POST /api/ai/notebook/extract-insertable como flujo principal.
  • La biblioteca documental en frontend depende de project-context para carga/listado/eliminacion de documentos.

Base de datos y semillas

El modulo de base de datos inicializa automaticamente esquema y contenido base al arrancar la aplicacion. La logica de bootstrap y seed vive en src/database/database.service.ts.

Scripts SQL de referencia en Document/sql/mysql.

Modelo de datos (ilustrado)

erDiagram
	USERS ||--o{ PROJECTS : "crea/participa"
	USERS ||--o{ PROJECT_MEMBERS : "pertenece"
	PROJECTS ||--o{ PROJECT_MEMBERS : "incluye"
	PROJECTS ||--o{ PROJECT_DOCUMENTS : "adjunta"
	PROJECTS ||--o{ PROJECT_INVITATIONS : "invita"
	PROJECTS ||--o{ EXPERIMENTS : "contiene"

	EXPERIMENTS ||--o{ EXPERIMENT_STEPS : "define pasos"
	EXPERIMENTS ||--o{ EXPERIMENT_NOTES : "registra notas"
	EXPERIMENTS ||--o{ EXPERIMENT_ARTIFACTS : "guarda evidencias"
	EXPERIMENTS ||--o{ AI_INTERACTIONS : "genera interacciones IA"
	AI_INTERACTIONS ||--o{ SAFETY_REVIEWS : "es revisada por seguridad"

	PAGES ||--o{ SECTIONS : "estructura UI"
	SECTIONS ||--o{ LINKS : "publica enlaces"
	SECTIONS ||--o{ SECTION_ASSETS : "usa recursos"
	ASSETS ||--o{ SECTION_ASSETS : "asignado a seccion"
	THEMES ||--o{ THEME_TOKENS : "define tokens"
	PAGES ||--o{ UI_METRICS : "mide eventos"
	UI_METRICS ||--o{ UI_METRIC_EVENTS : "historial"
Loading

Explicacion por dominios

  • Colaboracion de proyecto:
    • users, projects, project_members, project_invitations, project_documents, project_logs.
    • Permite ownership, membresia, invitaciones y documentacion por proyecto.
  • Cuaderno experimental:
    • experiments, experiment_steps, experiment_notes, experiment_artifacts.
    • Modela el ciclo del experimento: objetivo, pasos, notas y evidencia (CSV, imagen, documento, reporte).
  • IA responsable y trazabilidad:
    • ai_interactions, safety_reviews.
    • Guarda trazas de prompts/respuestas, latencia, flags de seguridad y decisiones (allow, warn, block).
  • Configuracion UI/landing y metricas:
    • pages, sections, assets, section_assets, links, themes, theme_tokens, ui_metrics, ui_metric_events.
    • Soporta contenido administrable del frontend y observabilidad basica de uso.

Scripts SQL clave

Adicionalmente, el bootstrap en src/database/database.service.ts garantiza creacion idempotente de tablas base (users, projects, entre otras) al iniciar el servicio.

Scripts npm

  • npm run start: ejecuta el build compilado.
  • npm run start:dev: desarrollo con recarga (ts-node-dev).
  • npm run build: compilacion TypeScript a dist.
  • npm run start:prod: ejecucion de salida compilada.

Estructura rapida del repositorio

back_end/
	src/
		ai/
		experiment-notes/
		platform/
		reports/
		safety/
		storage/
		microsoft/
		database/
	Document/sql/mysql/
	documents/
	consumibles/
	.env.example
	package.json

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages