@things-factory/integration-label-studio 9.1.19

package/TEST_GUIDE.md

@@ -0,0 +1,387 @@
+# Test Guide for Label Studio Integration
+
+This guide explains how to run the test scripts for the Label Studio integration.
+
+## Test Scripts Overview
+
+The integration includes three test scripts:
+
+1. **test-simple.js** - Tests AI inference without Label Studio
+2. **test-ai-prediction.js** - Tests complete AI prediction flow with Label Studio
+3. **test-dataset-integration.js** - Tests full dataset-to-Label Studio integration
+
+## Prerequisites
+
+### 1. Environment Setup
+
+Both Things Factory and Label Studio must be running on subdomain pattern:
+
+```bash
+# Things Factory
+http://app.dataset.localhost:3000
+
+# Label Studio
+http://label.dataset.localhost:8080
+```
+
+**Note:** Modern browsers automatically resolve `*.localhost` to `127.0.0.1`, so no `/etc/hosts` modification is needed.
+
+### 2. Label Studio Configuration
+
+Ensure Label Studio is configured with JWT SSO:
+
+```bash
+# In Label Studio .env file
+JWT_SSO_SECRET=your-secret-key
+JWT_SSO_COOKIE_NAME=ls_auth_token
+CSRF_TRUSTED_ORIGINS=http://app.dataset.localhost:3000,http://label.dataset.localhost:8080
+ALLOWED_HOSTS=localhost,label.dataset.localhost,*.dataset.localhost
+```
+
+### 3. Get API Token
+
+1. Login to Label Studio: http://label.dataset.localhost:8080
+2. Navigate to Account Settings → Access Token
+3. Create new token and copy it
+
+## Test 1: Simple AI Inference
+
+Tests AI detection functionality without Label Studio integration.
+
+### Run Test
+
+```bash
+cd /path/to/things-factory/packages/integration-label-studio
+
+# Run with default settings
+node test-simple.js
+
+# Or with custom GraphQL endpoint
+THINGS_FACTORY_GRAPHQL=http://app.dataset.localhost:3000/graphql node test-simple.js
+```
+
+### Expected Output
+
+```
+🤖 Testing AI Object Detection
+
+============================================================
+   GraphQL: http://app.dataset.localhost:3000/graphql
+   Test Image: https://example.com/test.jpg
+============================================================
+
+📤 Sending GraphQL request...
+
+✅ AI Detection successful!
+
+🎯 Detected 3 objects:
+
+   1. person
+      Confidence: 95.2%
+      BBox: x=100, y=150, w=200, h=300
+
+   2. car
+      Confidence: 87.5%
+      BBox: x=300, y=200, w=250, h=180
+
+✨ Mock AI is working correctly!
+```
+
+## Test 2: AI Prediction with Label Studio
+
+Tests the complete flow from AI inference to Label Studio prediction creation.
+
+### Setup
+
+```bash
+# Set environment variables
+export LABEL_STUDIO_URL=http://label.dataset.localhost:8080
+export LABEL_STUDIO_API_TOKEN=your-api-token-here
+export THINGS_FACTORY_GRAPHQL=http://app.dataset.localhost:3000/graphql
+export TEST_PROJECT_ID=2  # Your Label Studio project ID
+```
+
+### Run Test
+
+```bash
+cd /path/to/things-factory/packages/integration-label-studio
+
+node test-ai-prediction.js
+```
+
+### Expected Output
+
+```
+🚀 Starting AI Prediction Integration Test
+
+============================================================
+
+🔍 Testing Label Studio connection...
+   URL: http://label.dataset.localhost:8080
+✅ Label Studio connected successfully
+   Found 5 projects
+
+🔍 Getting test task from project 2...
+✅ Found task 42
+   Image: http://example.com/test.jpg
+   Annotations: 0
+   Predictions: 0
+
+🤖 Testing AI inference...
+   Image: http://example.com/test.jpg
+✅ AI detected 3 objects:
+   1. person (95.2%)
+   2. car (87.5%)
+   3. bicycle (72.3%)
+
+🎯 Testing prediction generation for task 42...
+✅ Prediction created successfully!
+   Prediction ID: 123
+   Objects detected: 3
+   Avg confidence: 85.0%
+
+✓ Verifying prediction in Label Studio...
+✅ Task has 1 prediction(s)
+   Latest prediction:
+   - ID: 123
+   - Model: yolov8-nano-v1.0
+   - Score: 85.0%
+   - Objects: 3
+
+============================================================
+✨ Test completed successfully!
+
+📝 Next steps:
+   1. Open Label Studio: http://label.dataset.localhost:8080/projects/2
+   2. Open task 42 to see the AI-generated prediction
+   3. The prediction should appear as pre-labeled regions
+```
+
+## Test 3: Dataset Integration
+
+Tests the complete integration between Things Factory Datasets and Label Studio.
+
+### Setup
+
+```bash
+# Set environment variables
+export THINGS_FACTORY_GRAPHQL=http://app.dataset.localhost:3000/graphql
+export LABEL_STUDIO_URL=http://label.dataset.localhost:8080
+export LABEL_STUDIO_PROJECT_ID=2
+```
+
+### Run Test
+
+```bash
+cd /path/to/things-factory/packages/integration-label-studio
+
+node test-dataset-integration.js
+```
+
+### Expected Output
+
+```
+🚀 Dataset-Label Studio Integration Test
+
+============================================================
+   Things Factory GraphQL: http://app.dataset.localhost:3000/graphql
+   Label Studio URL: http://label.dataset.localhost:8080
+   Label Studio Project ID: 2
+============================================================
+
+📊 Step 1: Querying DataSets...
+============================================================
+✅ Found 3 DataSet(s)
+
+Available DataSets:
+   1. Product Images (ds-001)
+      Active: true
+      Description: Product catalog images
+
+📦 Step 2: Querying DataSamples from DataSet ds-001...
+============================================================
+✅ Found 10 DataSample(s)
+
+DataSample details:
+   1. Sample-001
+      ID: sample-001
+      Collected: 2025-10-18T10:00:00Z
+      Image: http://example.com/product1.jpg
+
+🏷️  Step 3: Creating Label Studio tasks from DataSet ds-001...
+============================================================
+✅ Task creation completed!
+
+📊 Results:
+   Total samples processed: 10
+   Tasks created: 10
+   Tasks failed: 0
+   Tasks skipped: 0
+   AI predictions created: 10
+
+🎯 Created task IDs:
+   - Task 101
+   - Task 102
+   ...
+
+📈 Step 4: Querying labeling status for DataSet ds-001...
+============================================================
+✅ Labeling status retrieved!
+
+📊 Status for "Product Images":
+   Total samples: 10
+   Tasks created: 10
+   With AI predictions: 10
+   With annotations: 0
+   Annotations completed: 0
+   Not yet processed: 0
+   Completion rate: 0.0%
+
+🤖 Step 5: Generating AI predictions for DataSet ds-001...
+============================================================
+✅ Prediction generation completed!
+
+📊 Results:
+   Total tasks: 10
+   Succeeded: 10
+   Failed: 0
+   Model version: yolov8-nano-v1.0
+
+🔄 Step 6: Syncing annotations back to DataSet ds-001...
+============================================================
+✅ Annotation sync completed!
+
+📊 Results:
+   Total annotations processed: 0
+   DataSamples updated: 0
+   Updates failed: 0
+   Skipped: 0
+
+============================================================
+✨ Integration test completed successfully!
+
+📝 Next steps:
+   1. Open Label Studio: http://label.dataset.localhost:8080/projects/2
+   2. Review AI-generated predictions
+   3. Complete annotations
+   4. Run syncAnnotations again to update DataSamples
+============================================================
+```
+
+## Troubleshooting
+
+### Connection Errors
+
+**Symptom:** Cannot connect to Label Studio or Things Factory
+
+**Solutions:**
+1. Verify services are running:
+   ```bash
+   # Check Things Factory
+   curl http://app.dataset.localhost:3000/graphql
+
+   # Check Label Studio
+   curl http://label.dataset.localhost:8080/api/projects
+   ```
+
+2. Check subdomain resolution:
+   ```bash
+   # Should resolve to 127.0.0.1
+   ping app.dataset.localhost
+   ping label.dataset.localhost
+   ```
+
+### API Token Errors
+
+**Symptom:** 401 Unauthorized from Label Studio
+
+**Solutions:**
+1. Verify API token is correct and not expired
+2. Check token has admin/staff permissions
+3. Regenerate token if necessary
+
+### GraphQL Errors
+
+**Symptom:** GraphQL query fails
+
+**Solutions:**
+1. Check Things Factory is running and GraphQL endpoint is accessible
+2. Verify user is authenticated (for authenticated queries)
+3. Check GraphQL schema is up to date:
+   ```bash
+   curl -X POST http://app.dataset.localhost:3000/graphql \
+     -H "Content-Type: application/json" \
+     -d '{"query": "{ __schema { types { name } } }"}'
+   ```
+
+### No Tasks Found
+
+**Symptom:** Test cannot find tasks in Label Studio project
+
+**Solutions:**
+1. Create a project in Label Studio
+2. Add tasks manually or via API
+3. Ensure tasks have image data field
+4. Update `TEST_PROJECT_ID` environment variable
+
+## Advanced Usage
+
+### Custom Configuration
+
+All test scripts support environment variables:
+
+```bash
+# Full configuration example
+export THINGS_FACTORY_GRAPHQL=http://app.dataset.localhost:3000/graphql
+export LABEL_STUDIO_URL=http://label.dataset.localhost:8080
+export LABEL_STUDIO_API_TOKEN=your-token
+export LABEL_STUDIO_PROJECT_ID=2
+export TEST_PROJECT_ID=2
+
+# Run all tests
+node test-simple.js
+node test-ai-prediction.js
+node test-dataset-integration.js
+```
+
+### Continuous Integration
+
+For CI/CD pipelines:
+
+```bash
+#!/bin/bash
+
+# Start services
+docker-compose up -d things-factory label-studio
+
+# Wait for services to be ready
+sleep 10
+
+# Run tests
+export THINGS_FACTORY_GRAPHQL=http://app.dataset.localhost:3000/graphql
+export LABEL_STUDIO_URL=http://label.dataset.localhost:8080
+export LABEL_STUDIO_API_TOKEN=$CI_LABEL_STUDIO_TOKEN
+
+node test-simple.js || exit 1
+node test-ai-prediction.js || exit 1
+node test-dataset-integration.js || exit 1
+
+# Cleanup
+docker-compose down
+```
+
+## Next Steps
+
+After successful testing:
+
+1. Review the INTEGRATION.md guide for deployment configuration
+2. Configure production environment with proper subdomain setup
+3. Set up SSL certificates for HTTPS
+4. Configure cookie domain for production
+5. Set up monitoring and logging
+
+## References
+
+- [INTEGRATION.md](./INTEGRATION.md) - Full integration guide
+- [README.md](./README.md) - Module overview
+- [Label Studio Documentation](https://labelstud.io/guide/)