@things-factory/integration-label-studio 9.1.19

package/server/utils/label-studio-api-client.ts

@@ -0,0 +1,487 @@
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios'
+import { config } from '@things-factory/env'
+
+/**
+ * Label Studio API Client
+ * Provides methods to interact with Label Studio REST API
+ */
+export class LabelStudioApiClient {
+  private client: AxiosInstance | null = null
+  private serverUrl: string | null = null
+  private apiToken: string | null = null
+
+  constructor() {
+    // Defer initialization until first use
+  }
+
+  private ensureInitialized() {
+    if (this.client) {
+      return
+    }
+
+    const labelStudioConfig = config.get('labelStudio', {})
+    this.serverUrl = labelStudioConfig.serverUrl || 'http://localhost:8080'
+    this.apiToken = labelStudioConfig.apiToken || ''
+
+    this.client = axios.create({
+      baseURL: this.serverUrl,
+      headers: {
+        Authorization: `Token ${this.apiToken}`,
+        'Content-Type': 'application/json'
+      },
+      timeout: 30000
+    })
+  }
+
+  // ============================================================================
+  // Project Methods
+  // ============================================================================
+
+  /**
+   * Get all projects
+   */
+  async getProjects(): Promise<any[]> {
+    this.ensureInitialized()
+    const response = await this.client!.get('/api/projects')
+    return response.data.results || response.data
+  }
+
+  /**
+   * Get project by ID
+   */
+  async getProject(projectId: number): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.get(`/api/projects/${projectId}`)
+    return response.data
+  }
+
+  /**
+   * Create new project
+   */
+  async createProject(data: {
+    title: string
+    description?: string
+    label_config: string
+    expert_instruction?: string
+  }): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.post('/api/projects', data)
+    return response.data
+  }
+
+  /**
+   * Update project
+   */
+  async updateProject(projectId: number, data: any): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.patch(`/api/projects/${projectId}`, data)
+    return response.data
+  }
+
+  /**
+   * Delete project
+   */
+  async deleteProject(projectId: number): Promise<void> {
+    this.ensureInitialized()
+    await this.client!.delete(`/api/projects/${projectId}`)
+  }
+
+  // ============================================================================
+  // Task Methods
+  // ============================================================================
+
+  /**
+   * Get tasks for a project
+   */
+  async getTasks(projectId: number, params?: { page?: number; page_size?: number }): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.get(`/api/projects/${projectId}/tasks`, { params })
+    return response.data
+  }
+
+  /**
+   * Get single task
+   */
+  async getTask(taskId: number): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.get(`/api/tasks/${taskId}`)
+    return response.data
+  }
+
+  /**
+   * Create task
+   */
+  async createTask(projectId: number, data: any): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.post(`/api/projects/${projectId}/tasks`, data)
+    return response.data
+  }
+
+  /**
+   * Import tasks in bulk
+   */
+  async importTasks(projectId: number, tasks: any[]): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.post(`/api/projects/${projectId}/import`, tasks, {
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    })
+    return response.data
+  }
+
+  /**
+   * Delete task
+   */
+  async deleteTask(taskId: number): Promise<void> {
+    this.ensureInitialized()
+    await this.client!.delete(`/api/tasks/${taskId}`)
+  }
+
+  // ============================================================================
+  // Annotation Methods
+  // ============================================================================
+
+  /**
+   * Get annotations for a task
+   */
+  async getAnnotations(taskId: number): Promise<any[]> {
+    this.ensureInitialized()
+    const response = await this.client!.get(`/api/tasks/${taskId}/annotations`)
+    return response.data
+  }
+
+  /**
+   * Create annotation
+   */
+  async createAnnotation(taskId: number, annotation: any): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.post(`/api/tasks/${taskId}/annotations`, annotation)
+    return response.data
+  }
+
+  /**
+   * Update annotation
+   */
+  async updateAnnotation(annotationId: number, data: any): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.patch(`/api/annotations/${annotationId}`, data)
+    return response.data
+  }
+
+  /**
+   * Delete annotation
+   */
+  async deleteAnnotation(annotationId: number): Promise<void> {
+    this.ensureInitialized()
+    await this.client!.delete(`/api/annotations/${annotationId}`)
+  }
+
+  // ============================================================================
+  // Prediction Methods
+  // ============================================================================
+
+  /**
+   * Get all predictions for a task
+   */
+  async getPredictions(taskId: number): Promise<any[]> {
+    this.ensureInitialized()
+    const response = await this.client!.get('/api/predictions', {
+      params: { task: taskId }
+    })
+    return response.data.results || response.data
+  }
+
+  /**
+   * Get predictions for a project
+   */
+  async getProjectPredictions(projectId: number): Promise<any[]> {
+    this.ensureInitialized()
+    const response = await this.client!.get('/api/predictions', {
+      params: { project: projectId }
+    })
+    return response.data.results || response.data
+  }
+
+  /**
+   * Get single prediction by ID
+   */
+  async getPrediction(predictionId: number): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.get(`/api/predictions/${predictionId}`)
+    return response.data
+  }
+
+  /**
+   * Create a prediction for a task
+   */
+  async createPrediction(data: {
+    task: number
+    result: any[]
+    score?: number
+    model_version?: string
+  }): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.post('/api/predictions', data)
+    return response.data
+  }
+
+  /**
+   * Create predictions in bulk
+   */
+  async createPredictions(predictions: Array<{
+    task: number
+    result: any[]
+    score?: number
+    model_version?: string
+  }>): Promise<any> {
+    this.ensureInitialized()
+    const results = await Promise.all(
+      predictions.map(prediction => this.createPrediction(prediction))
+    )
+    return {
+      created: results.length,
+      predictions: results
+    }
+  }
+
+  /**
+   * Update prediction
+   */
+  async updatePrediction(predictionId: number, data: any): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.patch(`/api/predictions/${predictionId}`, data)
+    return response.data
+  }
+
+  /**
+   * Delete prediction
+   */
+  async deletePrediction(predictionId: number): Promise<void> {
+    this.ensureInitialized()
+    await this.client!.delete(`/api/predictions/${predictionId}`)
+  }
+
+  /**
+   * Import predictions for a project
+   * This is useful for bulk importing AI model predictions
+   */
+  async importPredictions(projectId: number, predictions: any[]): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.post(`/api/projects/${projectId}/import/predictions`, predictions)
+    return response.data
+  }
+
+  // ============================================================================
+  // Export Methods
+  // ============================================================================
+
+  /**
+   * Export annotations
+   */
+  async exportAnnotations(
+    projectId: number,
+    format: 'JSON' | 'JSON_MIN' | 'CSV' | 'TSV' | 'CONLL2003' | 'COCO' | 'VOC' | 'YOLO' = 'JSON'
+  ): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.get(`/api/projects/${projectId}/export`, {
+      params: { exportType: format }
+    })
+    return response.data
+  }
+
+  /**
+   * Get export files
+   */
+  async getExportFiles(projectId: number): Promise<any[]> {
+    this.ensureInitialized()
+    const response = await this.client!.get(`/api/projects/${projectId}/exports`)
+    return response.data
+  }
+
+  // ============================================================================
+  // ML Backend Methods
+  // ============================================================================
+
+  /**
+   * Get ML backends for project
+   */
+  async getMLBackends(projectId: number): Promise<any[]> {
+    this.ensureInitialized()
+    const response = await this.client!.get(`/api/ml`, {
+      params: { project: projectId }
+    })
+    return response.data.results || response.data
+  }
+
+  /**
+   * Add ML backend to project
+   */
+  async addMLBackend(data: {
+    project: number
+    url: string
+    title: string
+    is_interactive?: boolean
+  }): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.post('/api/ml', data)
+    return response.data
+  }
+
+  /**
+   * Delete ML backend
+   */
+  async deleteMLBackend(mlBackendId: number): Promise<void> {
+    this.ensureInitialized()
+    await this.client!.delete(`/api/ml/${mlBackendId}`)
+  }
+
+  /**
+   * Trigger predictions for tasks
+   */
+  async triggerPredictions(projectId: number, taskIds?: number[]): Promise<any> {
+    this.ensureInitialized()
+    const payload = taskIds ? { task_ids: taskIds } : {}
+    const response = await this.client!.post(`/api/projects/${projectId}/predict`, payload)
+    return response.data
+  }
+
+  /**
+   * Train ML model
+   */
+  async trainModel(mlBackendId: number): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.post(`/api/ml/${mlBackendId}/train`)
+    return response.data
+  }
+
+  // ============================================================================
+  // Statistics Methods
+  // ============================================================================
+
+  /**
+   * Get project statistics
+   */
+  async getProjectStats(projectId: number): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.get(`/api/projects/${projectId}`)
+    const project = response.data
+
+    // Get detailed statistics
+    const tasksResponse = await this.client!.get(`/api/projects/${projectId}/tasks`, {
+      params: { page_size: 1 }
+    })
+
+    return {
+      totalTasks: project.task_number || 0,
+      completedTasks: project.finished_task_number || 0,
+      totalAnnotations: project.total_annotations_number || 0,
+      avgAnnotationsPerTask:
+        project.task_number > 0 ? (project.total_annotations_number || 0) / project.task_number : 0,
+      completionRate: project.task_number > 0 ? (project.finished_task_number || 0) / project.task_number : 0
+    }
+  }
+
+  /**
+   * Get annotator statistics
+   */
+  async getAnnotatorStats(projectId: number): Promise<any[]> {
+    this.ensureInitialized()
+    const response = await this.client!.get(`/api/projects/${projectId}/annotations`)
+    const annotations = response.data.results || response.data
+
+    // Group by annotator
+    const statsByUser: { [email: string]: any } = {}
+
+    for (const annotation of annotations) {
+      const email = annotation.completed_by?.email || 'unknown'
+
+      if (!statsByUser[email]) {
+        statsByUser[email] = {
+          email,
+          annotationCount: 0,
+          totalTime: 0,
+          lastAnnotationDate: null
+        }
+      }
+
+      statsByUser[email].annotationCount++
+      if (annotation.lead_time) {
+        statsByUser[email].totalTime += annotation.lead_time
+      }
+
+      const annotationDate = new Date(annotation.created_at)
+      if (
+        !statsByUser[email].lastAnnotationDate ||
+        annotationDate > new Date(statsByUser[email].lastAnnotationDate)
+      ) {
+        statsByUser[email].lastAnnotationDate = annotation.created_at
+      }
+    }
+
+    return Object.values(statsByUser).map(stat => ({
+      ...stat,
+      avgTime: stat.annotationCount > 0 ? stat.totalTime / stat.annotationCount : 0
+    }))
+  }
+
+  // ============================================================================
+  // Webhook Methods
+  // ============================================================================
+
+  /**
+   * Create webhook
+   */
+  async createWebhook(data: {
+    project: number
+    url: string
+    send_payload?: boolean
+    send_for_all_actions?: boolean
+    headers?: { [key: string]: string }
+  }): Promise<any> {
+    this.ensureInitialized()
+    const response = await this.client!.post('/api/webhooks', data)
+    return response.data
+  }
+
+  /**
+   * Get webhooks for project
+   */
+  async getWebhooks(projectId: number): Promise<any[]> {
+    this.ensureInitialized()
+    const response = await this.client!.get('/api/webhooks', {
+      params: { project: projectId }
+    })
+    return response.data.results || response.data
+  }
+
+  /**
+   * Delete webhook
+   */
+  async deleteWebhook(webhookId: number): Promise<void> {
+    this.ensureInitialized()
+    await this.client!.delete(`/api/webhooks/${webhookId}`)
+  }
+}
+
+// Singleton instance (lazy initialization)
+let _instance: LabelStudioApiClient | null = null
+
+function getLabelStudioApiClient(): LabelStudioApiClient {
+  if (!_instance) {
+    _instance = new LabelStudioApiClient()
+  }
+  return _instance
+}
+
+// Export singleton accessor
+export const labelStudioApi = new Proxy({} as LabelStudioApiClient, {
+  get(_target, prop) {
+    const instance = getLabelStudioApiClient()
+    const value = (instance as any)[prop]
+    if (typeof value === 'function') {
+      return value.bind(instance)
+    }
+    return value
+  }
+})

package/server/utils/media-url-extractor.ts

@@ -0,0 +1,193 @@
+import { DataSample } from '@things-factory/dataset'
+
+/**
+ * Media URL Extractor
+ *
+ * Extracts media URLs (image, video, audio) from DataSample for Label Studio tasks
+ */
+
+export interface MediaUrls {
+  [fieldName: string]: string | string[]
+}
+
+export interface AttachmentInfo {
+  id: string
+  mimetype: string
+  name: string
+  fullpath: string
+}
+
+/**
+ * Extract all media URLs from a DataSample
+ * Returns an object with field names as keys and URLs as values
+ *
+ * @param sample - DataSample containing media attachments
+ * @param baseUrl - Base URL for converting relative paths to absolute URLs (e.g., 'https://tf.example.com')
+ * @param mediaFields - Optional array of field names to extract. If not provided, extracts all fields.
+ * @returns Object with media URLs keyed by field name
+ */
+export function extractMediaUrls(
+  sample: DataSample,
+  baseUrl: string,
+  mediaFields?: string[]
+): MediaUrls {
+  const urls: MediaUrls = {}
+
+  if (!sample.data || typeof sample.data !== 'object') {
+    return urls
+  }
+
+  const fieldsToExtract = mediaFields || Object.keys(sample.data)
+
+  for (const fieldName of fieldsToExtract) {
+    const fieldValue = sample.data[fieldName]
+
+    if (!fieldValue) continue
+
+    // Handle array of attachments
+    if (Array.isArray(fieldValue)) {
+      const extractedUrls = extractUrlsFromAttachmentArray(fieldValue, baseUrl)
+      if (extractedUrls.length > 0) {
+        urls[fieldName] = extractedUrls.length === 1 ? extractedUrls[0] : extractedUrls
+      }
+    }
+    // Handle single URL string
+    else if (typeof fieldValue === 'string') {
+      const url = normalizeUrl(fieldValue, baseUrl)
+      if (url) {
+        urls[fieldName] = url
+      }
+    }
+    // Handle single attachment object
+    else if (typeof fieldValue === 'object' && 'fullpath' in fieldValue) {
+      const url = normalizeUrl(fieldValue.fullpath, baseUrl)
+      if (url) {
+        urls[fieldName] = url
+      }
+    }
+  }
+
+  return urls
+}
+
+/**
+ * Extract URL from DataSample for a specific field
+ * Handles both single values and arrays
+ */
+export function extractMediaUrl(
+  sample: DataSample,
+  fieldName: string,
+  baseUrl: string
+): string | string[] | null {
+  if (!sample.data || typeof sample.data !== 'object') {
+    return null
+  }
+
+  const fieldValue = sample.data[fieldName]
+
+  if (!fieldValue) return null
+
+  // Handle array of attachments
+  if (Array.isArray(fieldValue)) {
+    const urls = extractUrlsFromAttachmentArray(fieldValue, baseUrl)
+    return urls.length > 0 ? (urls.length === 1 ? urls[0] : urls) : null
+  }
+
+  // Handle single URL string
+  if (typeof fieldValue === 'string') {
+    return normalizeUrl(fieldValue, baseUrl)
+  }
+
+  // Handle single attachment object
+  if (typeof fieldValue === 'object' && 'fullpath' in fieldValue) {
+    return normalizeUrl(fieldValue.fullpath, baseUrl)
+  }
+
+  return null
+}
+
+/**
+ * Extract URLs from an array of attachments
+ * Handles nested arrays created by create-data-sample.ts
+ */
+function extractUrlsFromAttachmentArray(arr: any[], baseUrl: string): string[] {
+  const urls: string[] = []
+
+  for (const item of arr) {
+    if (Array.isArray(item)) {
+      // Nested array - recursively extract
+      urls.push(...extractUrlsFromAttachmentArray(item, baseUrl))
+    } else if (item && typeof item === 'object' && 'fullpath' in item) {
+      // Attachment object
+      const url = normalizeUrl(item.fullpath, baseUrl)
+      if (url) urls.push(url)
+    } else if (typeof item === 'string') {
+      // Direct URL string
+      const url = normalizeUrl(item, baseUrl)
+      if (url) urls.push(url)
+    }
+  }
+
+  return urls
+}
+
+/**
+ * Normalize URL - convert relative paths to absolute URLs
+ *
+ * @param path - Relative path (e.g., '/attachments/2024/01/image.jpg') or absolute URL
+ * @param baseUrl - Base URL (e.g., 'https://tf.example.com')
+ * @returns Absolute URL or null if invalid
+ */
+function normalizeUrl(path: string | undefined, baseUrl: string): string | null {
+  if (!path) return null
+
+  // Already absolute URL
+  if (path.startsWith('http://') || path.startsWith('https://')) {
+    return path
+  }
+
+  // Relative path - convert to absolute
+  if (path.startsWith('/')) {
+    const cleanBaseUrl = baseUrl.replace(/\/+$/, '') // Remove trailing slashes
+    return `${cleanBaseUrl}${path}`
+  }
+
+  // Invalid format
+  return null
+}
+
+/**
+ * Build Label Studio task data from DataSample
+ * Automatically extracts all media fields and converts to absolute URLs
+ *
+ * @param sample - DataSample with media attachments
+ * @param baseUrl - Base URL for the Things-Factory server
+ * @param mediaFields - Optional list of media field names to include
+ * @returns Object ready for Label Studio task creation
+ */
+export function buildLabelStudioTaskData(
+  sample: DataSample,
+  baseUrl: string,
+  mediaFields?: string[]
+): Record<string, any> {
+  return extractMediaUrls(sample, baseUrl, mediaFields)
+}
+
+/**
+ * Helper: Get base URL from context or environment
+ * Falls back to environment variable or localhost
+ */
+export function getBaseUrl(context?: any): string {
+  // Try from context (request)
+  if (context?.state?.domain?.systemUrl) {
+    return context.state.domain.systemUrl
+  }
+
+  // Try from environment
+  if (process.env.THINGS_FACTORY_URL) {
+    return process.env.THINGS_FACTORY_URL
+  }
+
+  // Fallback
+  return 'http://localhost:3000'
+}