# 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/)