@things-factory/integration-label-studio 9.1.19

package/server/route/webhook.ts

@@ -0,0 +1,304 @@
+import Koa from 'koa'
+import Router from 'koa-router'
+import { getRepository } from 'typeorm'
+
+const webhookRouter = new Router()
+
+/**
+ * Label Studio Webhook Event Types
+ */
+export enum WebhookAction {
+  ANNOTATION_CREATED = 'ANNOTATION_CREATED',
+  ANNOTATION_UPDATED = 'ANNOTATION_UPDATED',
+  ANNOTATION_DELETED = 'ANNOTATION_DELETED',
+  TASK_CREATED = 'TASK_CREATED',
+  TASK_UPDATED = 'TASK_UPDATED',
+  TASK_DELETED = 'TASK_DELETED',
+  PROJECT_UPDATED = 'PROJECT_UPDATED'
+}
+
+export interface WebhookPayload {
+  action: WebhookAction
+  project: {
+    id: number
+    title: string
+  }
+  task?: {
+    id: number
+    data: any
+    annotations: any[]
+  }
+  annotation?: {
+    id: number
+    result: any[]
+    completed_by: {
+      id: number
+      email: string
+    }
+    lead_time: number
+  }
+}
+
+/**
+ * Webhook handler function type
+ * Applications can register custom handlers for any webhook action
+ */
+export type WebhookHandler = (payload: WebhookPayload, context: Koa.Context) => Promise<void>
+
+/**
+ * Registry for custom webhook handlers
+ * Multiple handlers can be registered per action
+ */
+const customHandlers: Map<WebhookAction, WebhookHandler[]> = new Map()
+
+/**
+ * Register a custom webhook handler
+ * Handlers are executed in registration order
+ *
+ * @param action - Webhook action to handle
+ * @param handler - Handler function
+ *
+ * @example
+ * registerWebhookHandler(WebhookAction.ANNOTATION_CREATED, async (payload, ctx) => {
+ *   console.log('Custom handler:', payload.annotation?.id)
+ *   // Store annotation in database
+ *   // Trigger ML training
+ *   // Send notifications
+ * })
+ */
+export function registerWebhookHandler(action: WebhookAction, handler: WebhookHandler): void {
+  if (!customHandlers.has(action)) {
+    customHandlers.set(action, [])
+  }
+  customHandlers.get(action)!.push(handler)
+}
+
+/**
+ * Unregister a webhook handler
+ */
+export function unregisterWebhookHandler(action: WebhookAction, handler: WebhookHandler): void {
+  const handlers = customHandlers.get(action)
+  if (handlers) {
+    const index = handlers.indexOf(handler)
+    if (index > -1) {
+      handlers.splice(index, 1)
+    }
+  }
+}
+
+/**
+ * Clear all custom handlers for an action
+ */
+export function clearWebhookHandlers(action?: WebhookAction): void {
+  if (action) {
+    customHandlers.delete(action)
+  } else {
+    customHandlers.clear()
+  }
+}
+
+/**
+ * Execute all registered handlers for an action
+ */
+async function executeCustomHandlers(action: WebhookAction, payload: WebhookPayload, ctx: Koa.Context): Promise<void> {
+  const handlers = customHandlers.get(action)
+  if (!handlers || handlers.length === 0) {
+    return
+  }
+
+  // Execute all handlers in sequence
+  for (const handler of handlers) {
+    try {
+      await handler(payload, ctx)
+    } catch (error) {
+      console.error(`[Webhook] Custom handler error for ${action}:`, error)
+      // Continue executing other handlers even if one fails
+    }
+  }
+}
+
+/**
+ * Handle annotation created event
+ */
+async function handleAnnotationCreated(payload: WebhookPayload) {
+  console.log(`[Webhook] Annotation created:`, {
+    projectId: payload.project.id,
+    taskId: payload.task?.id,
+    annotationId: payload.annotation?.id,
+    completedBy: payload.annotation?.completed_by?.email
+  })
+
+  // TODO: Implement business logic
+  // 1. Store annotation in Things-Factory database
+  // 2. Trigger downstream processes (e.g., model training)
+  // 3. Send notifications to stakeholders
+  // 4. Update task status in external systems
+}
+
+/**
+ * Handle annotation updated event
+ */
+async function handleAnnotationUpdated(payload: WebhookPayload) {
+  console.log(`[Webhook] Annotation updated:`, {
+    projectId: payload.project.id,
+    annotationId: payload.annotation?.id
+  })
+
+  // TODO: Update annotation in database
+}
+
+/**
+ * Handle annotation deleted event
+ */
+async function handleAnnotationDeleted(payload: WebhookPayload) {
+  console.log(`[Webhook] Annotation deleted:`, {
+    projectId: payload.project.id,
+    annotationId: payload.annotation?.id
+  })
+
+  // TODO: Remove annotation from database
+}
+
+/**
+ * Handle task created event
+ */
+async function handleTaskCreated(payload: WebhookPayload) {
+  console.log(`[Webhook] Task created:`, {
+    projectId: payload.project.id,
+    taskId: payload.task?.id
+  })
+
+  // TODO: Store task reference
+}
+
+/**
+ * Handle project updated event
+ */
+async function handleProjectUpdated(payload: WebhookPayload) {
+  console.log(`[Webhook] Project updated:`, {
+    projectId: payload.project.id,
+    projectTitle: payload.project.title
+  })
+
+  // TODO: Update project metadata
+}
+
+/**
+ * Main webhook endpoint
+ * Label Studio will POST events here
+ */
+webhookRouter.post('/label-studio/webhook', async (ctx: Koa.Context) => {
+  try {
+    const payload = ctx.request.body as WebhookPayload
+
+    console.log(`[Webhook] Received event: ${payload.action}`)
+
+    // Execute default handlers first
+    switch (payload.action) {
+      case WebhookAction.ANNOTATION_CREATED:
+        await handleAnnotationCreated(payload)
+        break
+
+      case WebhookAction.ANNOTATION_UPDATED:
+        await handleAnnotationUpdated(payload)
+        break
+
+      case WebhookAction.ANNOTATION_DELETED:
+        await handleAnnotationDeleted(payload)
+        break
+
+      case WebhookAction.TASK_CREATED:
+        await handleTaskCreated(payload)
+        break
+
+      case WebhookAction.TASK_UPDATED:
+        // Optional: handle task updates
+        break
+
+      case WebhookAction.TASK_DELETED:
+        // Optional: handle task deletions
+        break
+
+      case WebhookAction.PROJECT_UPDATED:
+        await handleProjectUpdated(payload)
+        break
+
+      default:
+        console.warn(`[Webhook] Unknown action: ${payload.action}`)
+    }
+
+    // Execute custom handlers
+    await executeCustomHandlers(payload.action, payload, ctx)
+
+    ctx.status = 200
+    ctx.body = { success: true }
+  } catch (error) {
+    console.error('[Webhook] Error processing webhook:', error)
+    ctx.status = 500
+    ctx.body = { error: error.message }
+  }
+})
+
+/**
+ * Webhook registration helper
+ * Call this to register webhook with Label Studio
+ */
+webhookRouter.post('/label-studio/webhook/register', async (ctx: Koa.Context) => {
+  try {
+    const { projectId } = ctx.request.body as { projectId: number }
+
+    // Get Things-Factory server URL
+    const serverUrl = process.env.SERVER_URL || 'http://localhost:3000'
+    const webhookUrl = `${serverUrl}/label-studio/webhook`
+
+    // Register webhook using Label Studio API
+    const { labelStudioApi } = await import('../utils/label-studio-api-client.js')
+
+    const webhook = await labelStudioApi.createWebhook({
+      project: projectId,
+      url: webhookUrl,
+      send_payload: true,
+      send_for_all_actions: true,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    })
+
+    ctx.status = 200
+    ctx.body = {
+      success: true,
+      webhook
+    }
+  } catch (error) {
+    console.error('[Webhook] Error registering webhook:', error)
+    ctx.status = 500
+    ctx.body = { error: error.message }
+  }
+})
+
+/**
+ * Get webhooks for a project
+ */
+webhookRouter.get('/label-studio/webhook/:projectId', async (ctx: Koa.Context) => {
+  try {
+    const projectId = parseInt(ctx.params.projectId)
+
+    const { labelStudioApi } = await import('../utils/label-studio-api-client.js')
+    const webhooks = await labelStudioApi.getWebhooks(projectId)
+
+    ctx.status = 200
+    ctx.body = webhooks
+  } catch (error) {
+    console.error('[Webhook] Error fetching webhooks:', error)
+    ctx.status = 500
+    ctx.body = { error: error.message }
+  }
+})
+
+// Register routes with Things-Factory
+process.on('bootstrap-module-domain-private-route', (_app: Koa, router: Router) => {
+  router.use(webhookRouter.routes())
+  router.use(webhookRouter.allowedMethods())
+})
+
+export { webhookRouter }

package/server/route.ts

@@ -0,0 +1,35 @@
+/**
+ * Label Studio Integration Routes
+ *
+ * This module registers all Label Studio-related routes:
+ * - Webhook handler for Label Studio events (PUBLIC)
+ * - SSO authentication endpoint (PRIVATE - requires authentication)
+ *
+ * ## Subdomain Cookie Sharing Architecture:
+ * This integration uses subdomain-based cookie sharing instead of proxying.
+ * - Backend gets JWT token from Label Studio and sets shared domain cookie
+ * - Frontend loads Label Studio directly (not through proxy)
+ * - Cookie is automatically sent with all subdomain requests
+ */
+import Koa from 'koa'
+import Router from 'koa-router'
+import { webhookRouter } from './route/webhook'
+import { ssoRouter } from './route/label-studio-sso'
+
+// Public routes - No authentication required
+process.on('bootstrap-module-global-public-route' as any, (_app: Koa, routes: Router) => {
+  /*
+   * Register webhook routes (Label Studio → Things Factory)
+   * These must be public so Label Studio can send events
+   */
+  routes.use(webhookRouter.routes(), webhookRouter.allowedMethods())
+})
+
+// Private routes - Authentication required
+process.on('bootstrap-module-domain-private-route' as any, (_app: Koa, routes: Router) => {
+  /*
+   * Register Label Studio SSO routes
+   * This requires authentication - ctx.state.user will be available
+   */
+  routes.use(ssoRouter.routes(), ssoRouter.allowedMethods())
+})

package/server/service/ai-prediction-service.ts

@@ -0,0 +1,239 @@
+import { Resolver, Mutation, Arg, Ctx, Int, Float, Directive } from 'type-graphql'
+import { AIModelClientFactory, DetectedObject } from '@things-factory/ai-inference'
+import { labelStudioApi } from '../utils/label-studio-api-client.js'
+import {
+  GeneratePredictionRequest,
+  BatchGeneratePredictionRequest,
+  PredictionGenerationResult,
+  BatchPredictionResult
+} from '../types/prediction-types.js'
+
+/**
+ * Label Studio AI Prediction Service
+ *
+ * Integrates AI inference with Label Studio prediction system
+ * Uses ai-inference module for pure AI operations
+ */
+@Resolver()
+export class LabelStudioAIPredictionService {
+  /**
+   * Generate Label Studio prediction for a task
+   * Runs AI model and creates prediction in Label Studio
+   */
+  @Mutation(returns => PredictionGenerationResult, {
+    description: 'Generate Label Studio prediction for a task using AI model'
+  })
+  @Directive('@privilege(category: "label-studio", privilege: "mutation")')
+  async generatePrediction(
+    @Arg('input') input: GeneratePredictionRequest,
+    @Ctx() context: ResolverContext
+  ): Promise<PredictionGenerationResult> {
+    try {
+      // 1. Run AI model using ai-inference module
+      const modelClient = input.modelId
+        ? AIModelClientFactory.getClient(input.modelId)
+        : AIModelClientFactory.getDefaultClient()
+
+      const objects = await modelClient.detectObjects(input.imageUrl, {
+        confidenceThreshold: input.confidenceThreshold
+      })
+
+      if (objects.length === 0) {
+        return {
+          taskId: input.taskId,
+          success: true,
+          objectCount: 0,
+          error: 'No objects detected'
+        }
+      }
+
+      // 2. Convert AI results to Label Studio format
+      const labelStudioResult = this.convertToLabelStudioFormat(objects)
+
+      // 3. Calculate average confidence
+      const avgConfidence = objects.reduce((sum, obj) => sum + obj.confidence, 0) / objects.length
+
+      // 4. Create prediction in Label Studio
+      const prediction = await labelStudioApi.createPrediction({
+        task: input.taskId,
+        result: labelStudioResult,
+        score: avgConfidence,
+        model_version: input.modelId || 'default-model-v1.0'
+      })
+
+      console.log(
+        `[LS AI Prediction] Created prediction ${prediction.id} for task ${input.taskId} with ${objects.length} objects`
+      )
+
+      return {
+        taskId: input.taskId,
+        predictionId: prediction.id,
+        success: true,
+        objectCount: objects.length,
+        avgConfidence
+      }
+    } catch (error) {
+      console.error(`[LS AI Prediction] Failed for task ${input.taskId}:`, error)
+      return {
+        taskId: input.taskId,
+        success: false,
+        objectCount: 0,
+        error: error.message
+      }
+    }
+  }
+
+  /**
+   * Generate predictions for multiple tasks in batch
+   */
+  @Mutation(returns => BatchPredictionResult, {
+    description: 'Generate Label Studio predictions for multiple tasks in batch'
+  })
+  @Directive('@privilege(category: "label-studio", privilege: "mutation")')
+  async generateBatchPredictions(
+    @Arg('input') input: BatchGeneratePredictionRequest,
+    @Ctx() context: ResolverContext
+  ): Promise<BatchPredictionResult> {
+    const results: PredictionGenerationResult[] = []
+    let succeeded = 0
+    let failed = 0
+
+    const modelId = input.modelId || 'default-model-v1.0'
+
+    try {
+      // Process tasks in parallel (limit concurrency to avoid overload)
+      const BATCH_SIZE = 5
+      for (let i = 0; i < input.taskIds.length; i += BATCH_SIZE) {
+        const batch = input.taskIds.slice(i, i + BATCH_SIZE)
+
+        const batchPromises = batch.map(async taskId => {
+          try {
+            // Get task data from Label Studio
+            const task = await labelStudioApi.getTask(taskId)
+
+            if (!task || !task.data || !task.data.image) {
+              failed++
+              return {
+                taskId,
+                success: false,
+                objectCount: 0,
+                error: 'Task has no image data'
+              }
+            }
+
+            // Generate prediction
+            const result = await this.generatePrediction(
+              {
+                taskId,
+                imageUrl: task.data.image,
+                modelId: input.modelId,
+                confidenceThreshold: input.confidenceThreshold
+              },
+              context
+            )
+
+            if (result.success) {
+              succeeded++
+            } else {
+              failed++
+            }
+
+            return result
+          } catch (error) {
+            failed++
+            return {
+              taskId,
+              success: false,
+              objectCount: 0,
+              error: error.message
+            }
+          }
+        })
+
+        const batchResults = await Promise.all(batchPromises)
+        results.push(...batchResults)
+      }
+
+      console.log(
+        `[LS AI Prediction] Batch completed: ${succeeded} succeeded, ${failed} failed out of ${input.taskIds.length} tasks`
+      )
+
+      return {
+        total: input.taskIds.length,
+        succeeded,
+        failed,
+        results,
+        modelVersion: modelId
+      }
+    } catch (error) {
+      console.error('[LS AI Prediction] Batch processing failed:', error)
+      throw new Error(`Batch prediction generation failed: ${error.message}`)
+    }
+  }
+
+  /**
+   * Auto-generate predictions for all unlabeled tasks in a project
+   */
+  @Mutation(returns => BatchPredictionResult, {
+    description: 'Auto-generate predictions for all unlabeled tasks in a Label Studio project'
+  })
+  @Directive('@privilege(category: "label-studio", privilege: "mutation")')
+  async autoGeneratePredictions(
+    @Arg('projectId', type => Int) projectId: number,
+    @Arg('modelId', { nullable: true }) modelId: string,
+    @Arg('confidenceThreshold', type => Float, { nullable: true }) confidenceThreshold: number,
+    @Ctx() context: ResolverContext
+  ): Promise<BatchPredictionResult> {
+    try {
+      // Get all tasks from project
+      const tasksResponse = await labelStudioApi.getTasks(projectId, {
+        page_size: 1000 // Adjust as needed
+      })
+
+      const tasks = tasksResponse.tasks || tasksResponse.results || []
+
+      // Filter unlabeled tasks (no annotations)
+      const unlabeledTasks = tasks.filter((task: any) => {
+        const annotationCount = task.annotations?.length || task.total_annotations || 0
+        return annotationCount === 0
+      })
+
+      console.log(
+        `[LS AI Prediction] Auto-generating predictions for ${unlabeledTasks.length} unlabeled tasks in project ${projectId}`
+      )
+
+      // Generate predictions in batch
+      return await this.generateBatchPredictions(
+        {
+          projectId,
+          taskIds: unlabeledTasks.map((t: any) => t.id),
+          modelId,
+          confidenceThreshold
+        },
+        context
+      )
+    } catch (error) {
+      console.error(`[LS AI Prediction] Auto-generation failed for project ${projectId}:`, error)
+      throw new Error(`Auto prediction generation failed: ${error.message}`)
+    }
+  }
+
+  /**
+   * Convert AI detection results to Label Studio format
+   * This handles the Label Studio-specific data structure
+   */
+  private convertToLabelStudioFormat(objects: DetectedObject[]) {
+    return objects.map(obj => ({
+      from_name: 'label',
+      to_name: 'image',
+      type: 'rectanglelabels',
+      value: {
+        x: obj.bbox.x,
+        y: obj.bbox.y,
+        width: obj.bbox.width,
+        height: obj.bbox.height,
+        rectanglelabels: [obj.className]
+      }
+    }))
+  }
+}