@things-factory/integration-label-studio 9.1.19

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+### Changed
+
+- **[2025-10-07] Fixed hardcoded project ID in `label-studio-label-page.ts`**
+  - **Impact**: Critical bug fix - Now supports dynamic project routing
+  - **Changes**:
+    - Replaced hardcoded `/projects/3` with dynamic project ID extraction from URL route
+    - Added `projectId` property to LabelStudioLabelPage component
+    - Implemented `_extractProjectIdFromRoute()` method to parse project ID from window.location.pathname
+    - Added error handling for missing project ID
+  - **Files modified**:
+    - `client/label-studio-label-page.ts:28,33-60`
+  - **Migration**: No breaking changes - component now accepts optional `projectId` property
+
+- **[2025-10-07] Enhanced error handling and loading states**
+  - **Impact**: Improved user experience with better feedback
+  - **Changes**:
+    - Added iframe load timeout detection (15 seconds)
+    - Added iframe error event handler
+    - Added `iframeLoaded` state tracking
+    - Improved error messages for iframe loading failures
+  - **Files modified**:
+    - `client/label-studio-wrapper.ts:124,127-137,168-178,223`
+  - **Benefits**: Users now get clear feedback when Label Studio fails to load
+
+- **[2025-10-07] Uncommented webhook exports in server/index.ts**
+  - **Impact**: Public API now properly exports webhook-related types and functions
+  - **Changes**:
+    - Uncommented exports for: `WebhookAction`, `WebhookPayload`, `WebhookHandler`, `registerWebhookHandler`, `unregisterWebhookHandler`, `clearWebhookHandlers`
+    - These exports were previously commented out but are fully implemented and functional
+  - **Files modified**:
+    - `server/index.ts:5-12`
+  - **Benefits**: Users can now extend webhook functionality for custom Label Studio event handling
+
+### Technical Details
+
+#### Dynamic Project ID Implementation
+
+```typescript
+// Before
+const path = '/projects/3' // Hardcoded project ID
+
+// After
+const projectId = this.projectId || this._extractProjectIdFromRoute()
+const path = `/projects/${projectId}`
+```
+
+#### Error Handling Enhancement
+
+- Added `@error=${this.handleIframeError}` event listener on iframe element
+- Added timeout detection to catch cases where iframe loads but never fires load event
+- Clear error messages guide users to check server connectivity
+
+#### Webhook API Exports
+
+Users can now register custom webhook handlers:
+
+```typescript
+import { registerWebhookHandler, WebhookAction } from 'integration-label-studio'
+
+registerWebhookHandler(WebhookAction.ANNOTATION_CREATED, async (payload, ctx) => {
+  // Custom annotation handling logic
+})
+```
+
+### Summary
+
+**Total Files Modified**: 3
+
+- `client/label-studio-label-page.ts` - Fixed hardcoded project ID
+- `client/label-studio-wrapper.ts` - Enhanced error handling
+- `server/index.ts` - Enabled webhook API exports
+
+**Impact**:
+
+- ✅ Fixes critical routing bug
+- ✅ Improves user experience with loading states
+- ✅ Enables webhook extensibility
+
+**Production Ready**: Yes - All changes are backward compatible

package/EXTERNAL_DATA_SOURCING.md

@@ -0,0 +1,484 @@
+# 🌐 Label Studio 외부 데이터 소싱 가이드
+
+Label Studio 프로젝트에 외부 데이터를 import하는 다양한 방법을 설명합니다.
+
+## 📋 목차
+
+1. [Dataset 모듈 활용](#1-dataset-모듈-활용-추천)
+2. [외부 REST API 연동](#2-외부-rest-api-연동)
+3. [JSON/CSV 파일 Import](#3-jsoncsv-파일-import)
+4. [클라우드 스토리지 연동](#4-클라우드-스토리지-연동)
+
+---
+
+## 1. Dataset 모듈 활용 (추천)
+
+Things Factory의 Dataset 모듈에서 DataSample을 Label Studio로 자동 export합니다.
+
+### 장점
+- ✅ 데이터 구조 자동 변환
+- ✅ 메타데이터 자동 매핑
+- ✅ AI 예측 자동 생성
+- ✅ 양방향 동기화 지원
+
+### GraphQL API
+
+```graphql
+mutation {
+  createLabelingTasksFromDataset(input: {
+    projectId: 2
+    dataSetId: "your-dataset-id"
+    imageField: "image"
+    autoGeneratePredictions: true
+    confidenceThreshold: 0.5
+    limit: 100
+  }) {
+    totalSamples
+    tasksCreated
+    tasksFailed
+    predictionsCreated
+    taskIds
+  }
+}
+```
+
+### 사용 방법
+
+1. **DataSet 생성**
+   ```graphql
+   mutation {
+     createDataSet(dataSet: {
+       name: "Product Images"
+       description: "Quality inspection images"
+       active: true
+     }) {
+       id
+       name
+     }
+   }
+   ```
+
+2. **DataSample 추가**
+   ```graphql
+   mutation {
+     createDataSample(dataSample: {
+       dataSetId: "dataset-id"
+       name: "Sample-001"
+       data: {
+         image: "https://example.com/image1.jpg"
+         product_id: "P123"
+         batch: "B456"
+       }
+       collectedAt: "2025-01-13T10:00:00Z"
+     }) {
+       id
+     }
+   }
+   ```
+
+3. **Label Studio로 Export**
+   ```graphql
+   mutation {
+     createLabelingTasksFromDataset(input: {
+       projectId: 2
+       dataSetId: "dataset-id"
+       autoGeneratePredictions: true
+     }) {
+       tasksCreated
+     }
+   }
+   ```
+
+---
+
+## 2. 외부 REST API 연동
+
+REST API 엔드포인트에서 직접 데이터를 가져와 Label Studio에 import합니다.
+
+### 미리보기 (Preview)
+
+먼저 데이터 구조를 확인합니다:
+
+```graphql
+query {
+  previewExternalDataSource(source: {
+    sourceType: "api"
+    sourceUrl: "https://api.example.com/images"
+    authHeader: "Bearer YOUR_TOKEN"
+    httpMethod: "GET"
+    dataPath: "data.items"
+  }) {
+    itemCount
+    sampleData
+    schema
+  }
+}
+```
+
+**응답 예시:**
+```json
+{
+  "itemCount": 1,
+  "sampleData": "{\n  \"id\": \"123\",\n  \"imageUrl\": \"https://...\",\n  \"category\": \"defect\"\n}",
+  "schema": "{\n  \"id\": \"string\",\n  \"imageUrl\": \"string\",\n  \"category\": \"string\"\n}"
+}
+```
+
+### Import 실행
+
+```graphql
+mutation {
+  importFromExternalSource(input: {
+    projectId: 2
+    source: {
+      sourceType: "api"
+      sourceUrl: "https://api.example.com/images"
+      authHeader: "Bearer YOUR_TOKEN"
+      httpMethod: "GET"
+      dataPath: "data.items"
+    }
+    imageField: "imageUrl"
+    fieldMapping: "{\"id\":\"task_id\", \"category\":\"label\"}"
+    autoGeneratePredictions: true
+    limit: 100
+  }) {
+    totalFetched
+    tasksImported
+    tasksFailed
+    taskIds
+  }
+}
+```
+
+### API 응답 형식
+
+외부 API는 다음 형식으로 응답해야 합니다:
+
+```json
+{
+  "data": {
+    "items": [
+      {
+        "id": "img-001",
+        "imageUrl": "https://storage.example.com/image1.jpg",
+        "category": "electronics",
+        "metadata": {
+          "width": 1920,
+          "height": 1080
+        }
+      }
+    ]
+  }
+}
+```
+
+또는 배열 직접 반환:
+
+```json
+[
+  {
+    "id": "img-001",
+    "imageUrl": "https://storage.example.com/image1.jpg"
+  }
+]
+```
+
+---
+
+## 3. JSON/CSV 파일 Import
+
+파일 URL에서 직접 데이터를 가져옵니다.
+
+### JSON 파일
+
+```graphql
+mutation {
+  importFromExternalSource(input: {
+    projectId: 2
+    source: {
+      sourceType: "json"
+      sourceUrl: "https://example.com/data/images.json"
+      dataPath: "images"
+    }
+    imageField: "url"
+    limit: 50
+  }) {
+    totalFetched
+    tasksImported
+  }
+}
+```
+
+**images.json 예시:**
+```json
+{
+  "images": [
+    {
+      "url": "https://example.com/img1.jpg",
+      "label": "cat",
+      "confidence": 0.95
+    },
+    {
+      "url": "https://example.com/img2.jpg",
+      "label": "dog",
+      "confidence": 0.87
+    }
+  ]
+}
+```
+
+### CSV 파일
+
+```graphql
+mutation {
+  importFromExternalSource(input: {
+    projectId: 2
+    source: {
+      sourceType: "csv"
+      sourceUrl: "https://example.com/data/images.csv"
+    }
+    imageField: "image_url"
+    limit: 50
+  }) {
+    totalFetched
+    tasksImported
+  }
+}
+```
+
+**images.csv 예시:**
+```csv
+id,image_url,category,status
+1,https://example.com/img1.jpg,electronics,new
+2,https://example.com/img2.jpg,furniture,new
+3,https://example.com/img3.jpg,clothing,new
+```
+
+---
+
+## 4. 클라우드 스토리지 연동
+
+### S3/GCS/Azure Blob (Presigned URLs)
+
+클라우드 스토리지의 경우 presigned URL을 사용합니다:
+
+```graphql
+mutation {
+  importFromExternalSource(input: {
+    projectId: 2
+    source: {
+      sourceType: "url"
+      sourceUrl: "https://my-bucket.s3.amazonaws.com/manifest.json?X-Amz-..."
+    }
+    imageField: "s3_url"
+  }) {
+    tasksImported
+  }
+}
+```
+
+**manifest.json 예시:**
+```json
+[
+  {
+    "s3_url": "https://my-bucket.s3.amazonaws.com/image1.jpg?X-Amz-...",
+    "object_key": "images/2025/01/image1.jpg",
+    "size": 245678,
+    "uploaded_at": "2025-01-13T10:00:00Z"
+  }
+]
+```
+
+### Label Studio Cloud Storage 직접 연동
+
+Label Studio는 클라우드 스토리지 직접 연동도 지원합니다:
+
+1. **Label Studio UI에서 Storage 설정**
+   - Project Settings → Cloud Storage
+   - Add Source Storage (S3/GCS/Azure)
+
+2. **Sync 버튼으로 자동 import**
+   - Storage에서 자동으로 task 생성
+   - Label Studio가 직접 스토리지 접근
+
+---
+
+## 📊 Field Mapping (필드 매핑)
+
+소스 데이터의 필드명과 Label Studio 필드명이 다를 때 매핑을 지정합니다.
+
+### 예시
+
+**소스 데이터:**
+```json
+{
+  "product_image": "https://...",
+  "sku": "SKU-123",
+  "inspection_date": "2025-01-13"
+}
+```
+
+**Field Mapping:**
+```json
+{
+  "product_image": "image",
+  "sku": "product_id",
+  "inspection_date": "date"
+}
+```
+
+**GraphQL:**
+```graphql
+mutation {
+  importFromExternalSource(input: {
+    projectId: 2
+    source: { ... }
+    imageField: "product_image"
+    fieldMapping: "{\"product_image\":\"image\",\"sku\":\"product_id\",\"inspection_date\":\"date\"}"
+  }) { ... }
+}
+```
+
+---
+
+## 🔄 데이터 흐름 다이어그램
+
+```
+┌─────────────────┐
+│  External API   │
+│  JSON/CSV File  │
+│  Cloud Storage  │
+└────────┬────────┘
+         │ HTTP Request
+         ▼
+┌─────────────────────────┐
+│ ExternalDataSourceService│
+│ - fetchFromSource()     │
+│ - transformData()       │
+└────────┬────────────────┘
+         │ Label Studio API
+         ▼
+┌─────────────────┐
+│  Label Studio   │
+│     Project     │
+│   (Tasks 생성)   │
+└─────────────────┘
+```
+
+---
+
+## 🛠️ 고급 사용법
+
+### 1. 인증 헤더 사용
+
+```graphql
+source: {
+  sourceType: "api"
+  sourceUrl: "https://api.example.com/data"
+  authHeader: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+}
+```
+
+### 2. POST 요청으로 데이터 가져오기
+
+```graphql
+source: {
+  sourceType: "api"
+  sourceUrl: "https://api.example.com/search"
+  httpMethod: "POST"
+  requestBody: "{\"query\":\"defect images\",\"limit\":100}"
+  dataPath: "results"
+}
+```
+
+### 3. 중첩된 데이터 추출
+
+```graphql
+source: {
+  sourceType: "url"
+  sourceUrl: "https://example.com/data.json"
+  dataPath: "response.data.items"  # response.data.items 배열 추출
+}
+```
+
+---
+
+## 📝 Best Practices
+
+### 1. 미리보기 먼저 실행
+항상 `previewExternalDataSource`로 데이터 구조를 확인한 후 import를 실행하세요.
+
+### 2. 배치 크기 조절
+대량 데이터는 `limit` 파라미터로 나누어 import합니다:
+```graphql
+# 첫 번째 배치
+mutation { importFromExternalSource(input: { limit: 100 }) { ... } }
+
+# 두 번째 배치 (API에서 offset/page 지원 필요)
+mutation { importFromExternalSource(input: { limit: 100 }) { ... } }
+```
+
+### 3. 오류 처리
+Import 결과를 확인하고 실패한 항목은 재시도합니다:
+```graphql
+mutation {
+  importFromExternalSource(input: { ... }) {
+    totalFetched
+    tasksImported
+    tasksFailed  # 이 값 확인
+    error
+  }
+}
+```
+
+### 4. 이미지 URL 검증
+Import 전에 이미지 URL이 유효한지 확인하세요:
+- URL이 공개 접근 가능한지
+- CORS 설정이 올바른지
+- Presigned URL의 만료 시간 확인
+
+---
+
+## 🚨 문제 해결
+
+### "No image URL found"
+- `imageField` 파라미터를 소스 데이터의 실제 필드명으로 설정
+- Preview로 데이터 구조 확인
+
+### "401 Unauthorized"
+- `authHeader`에 유효한 인증 토큰 설정
+- API 키나 Bearer 토큰 확인
+
+### "Path not found in data"
+- `dataPath`가 올바른지 확인
+- Preview로 실제 응답 구조 확인
+
+### Import는 성공했지만 이미지가 안 보임
+- Label Studio에서 이미지 URL 접근 가능한지 확인
+- CORS 설정 확인
+- Presigned URL 만료 확인
+
+---
+
+## 📚 참고 자료
+
+- [Label Studio API Documentation](https://labelstud.io/api)
+- [Label Studio Cloud Storage](https://labelstud.io/guide/storage.html)
+- [Things Factory Dataset Module](../dataset/README.md)
+
+---
+
+## 🎯 요약
+
+| 방법 | 용도 | 장점 | 단점 |
+|------|------|------|------|
+| **Dataset 모듈** | Things Factory 내부 데이터 | 자동 변환, 양방향 동기화 | Things Factory 전용 |
+| **REST API** | 외부 시스템 연동 | 실시간 데이터, 동적 조회 | API 개발 필요 |
+| **JSON/CSV 파일** | 정적 데이터셋 | 간단함, 표준 형식 | 수동 업데이트 필요 |
+| **Cloud Storage** | 대용량 이미지 | 확장성, 비용 효율 | 설정 복잡 |
+
+**추천 순서:**
+1. Things Factory 내부 데이터 → **Dataset 모듈**
+2. 외부 API 있음 → **REST API 연동**
+3. 파일 형태 데이터 → **JSON/CSV Import**
+4. 대용량 이미지 → **Cloud Storage**