@things-factory/labeling 9.1.19

package/README.md

@@ -0,0 +1,551 @@
+# @things-factory/labeling
+
+[![Version](https://img.shields.io/npm/v/@things-factory/labeling.svg)](https://www.npmjs.com/package/@things-factory/labeling)
+[![License](https://img.shields.io/npm/l/@things-factory/labeling.svg)](https://github.com/hatiolab/things-factory/blob/master/LICENSE)
+
+Labeling workflow orchestration module for Things-Factory platform.
+
+## Overview
+
+This module provides comprehensive workflow orchestration capabilities for data labeling processes, including both **backend services** (GraphQL API, database persistence) and **frontend UI components** (workflow builder, list view).
+
+## Features
+
+### Backend (Server) ✅
+
+- **Workflow Management**: Create, execute, pause, resume, and delete labeling workflows
+- **TypeORM Entities**: Persistent storage with PostgreSQL/SQLite support
+- **GraphQL API**: Full-featured GraphQL resolvers with type safety
+- **Multi-tenancy**: Domain-based data isolation
+- **Execution Tracking**: Monitor workflow and step-level execution status
+- **Error Handling**: Configurable retry logic and continue-on-error behavior
+- **Step Types**:
+  - `import_data` - Import data from datasets or external sources
+  - `generate_predictions` - Generate AI predictions for pre-labeling
+  - `wait_for_annotations` - Wait for human annotations with completion tracking
+  - `sync_annotations` - Sync labels back to dataset
+  - `validate_quality` - Quality validation checks
+  - `export_results` - Export annotations to external systems
+  - `notification` - Send alerts and notifications
+
+### Frontend (Client) ✅
+
+- **Workflow List Page**: View and manage all workflows with filtering
+- **Workflow Builder**: Visual workflow creation and editing interface
+- **Step Editor**: Configure individual workflow steps with JSON config
+- **Status Indicators**: Color-coded workflow status (Active, Draft, Paused, Failed)
+- **CRUD Operations**: Complete workflow lifecycle management
+- **Responsive Design**: Material Design 3 themed UI components
+
+## Terminology
+
+This module uses **"workflow"** terminology to distinguish from the existing `scenario` entity in Things-Factory:
+
+- `LabelingWorkflow` - A workflow definition
+- `WorkflowExecution` - A workflow execution instance
+- `WorkflowStep` - Individual step in a workflow
+- `WorkflowStatus` - Workflow state (Draft, Active, Paused, Completed, Failed)
+
+## Installation
+
+```bash
+npm install @things-factory/labeling
+```
+
+## Dependencies
+
+### Server
+- `@things-factory/integration-label-studio` - Label Studio API integration
+- `@things-factory/dataset` - Dataset management
+- `@things-factory/ai-inference` - AI model inference
+- `@things-factory/auth-base` - Authentication
+- `@things-factory/shell` - Core framework
+- `typeorm` - Database ORM
+
+### Client
+- `@operato/shell` - Shell components and navigation
+- `@operato/graphql` - GraphQL client
+- `lit` - Web components framework
+- `graphql-tag` - GraphQL query parsing
+- `i18next` - Internationalization
+
+## Usage
+
+### Backend
+
+```typescript
+import { LabelingWorkflowService } from '@things-factory/labeling'
+
+// Create workflow service
+const service = new LabelingWorkflowService()
+
+// Create workflow
+const workflow = await service.createLabelingWorkflow({
+  name: 'Image Classification Workflow',
+  description: 'Automated image classification with AI',
+  projectId: 123,
+  triggerType: 'manual',
+  steps: [
+    {
+      name: 'Import Images',
+      type: 'import_data',
+      config: JSON.stringify({
+        sourceType: 'dataset',
+        dataSetId: 'my-dataset',
+        limit: 1000
+      }),
+      continueOnError: false
+    },
+    {
+      name: 'Generate Predictions',
+      type: 'generate_predictions',
+      config: JSON.stringify({
+        modelId: 'resnet50-v2',
+        confidenceThreshold: 0.7
+      }),
+      continueOnError: true
+    }
+  ],
+  autoStart: false
+}, context)
+
+// Execute workflow
+const execution = await service.executeLabelingWorkflow({
+  workflowId: workflow.id
+}, context)
+
+// Monitor execution
+const status = await service.workflowExecution(execution.executionId, context)
+```
+
+### Frontend
+
+```typescript
+// Import UI components
+import '@things-factory/labeling/dist-client/pages/workflow-list'
+import '@things-factory/labeling/dist-client/pages/workflow-builder'
+
+// Use in HTML
+<workflow-list-page></workflow-list-page>
+<workflow-builder-page></workflow-builder-page>
+
+// Edit existing workflow
+<workflow-builder-page workflowId="workflow-uuid"></workflow-builder-page>
+```
+
+### Menu Integration
+
+```typescript
+import { getMenuTemplate } from '@things-factory/labeling'
+
+// Get menu items (owner = true for admin features)
+const menuItems = getMenuTemplate(true)
+
+// Integrate into your app's menu
+export function getAppMenu(owner: boolean) {
+  return [
+    ...yourMenuItems,
+    ...getMenuTemplate(owner)
+  ]
+}
+```
+
+### Route Configuration
+
+```typescript
+import route from '@things-factory/labeling/dist-client/route'
+
+// Available routes:
+// - /workflows          → Workflow list page
+// - /workflow-builder   → Create new workflow
+// - /workflow-builder/{id} → Edit existing workflow
+
+// In your app's route.ts:
+export default function appRoute(page: string) {
+  // Try labeling routes first
+  const labelingRoute = route(page)
+  if (labelingRoute) return labelingRoute
+
+  // Your other routes
+  switch (page) {
+    // ...
+  }
+}
+```
+
+## GraphQL API
+
+### Mutations
+
+```graphql
+# Create workflow
+mutation CreateWorkflow($input: CreateWorkflowRequest!) {
+  createLabelingWorkflow(input: $input) {
+    id
+    name
+    status
+    steps {
+      name
+      type
+      order
+    }
+  }
+}
+
+# Update workflow
+mutation UpdateWorkflow($workflowId: String!, $input: UpdateWorkflowRequest!) {
+  updateLabelingWorkflow(workflowId: $workflowId, input: $input) {
+    id
+    name
+  }
+}
+
+# Execute workflow
+mutation ExecuteWorkflow($input: ExecuteWorkflowRequest!) {
+  executeLabelingWorkflow(input: $input) {
+    executionId
+    status
+    summary
+  }
+}
+
+# Pause workflow
+mutation PauseWorkflow($workflowId: String!) {
+  pauseLabelingWorkflow(workflowId: $workflowId) {
+    id
+    status
+  }
+}
+
+# Resume workflow
+mutation ResumeWorkflow($workflowId: String!) {
+  resumeLabelingWorkflow(workflowId: $workflowId) {
+    id
+    status
+  }
+}
+
+# Delete workflow
+mutation DeleteWorkflow($workflowId: String!) {
+  deleteLabelingWorkflow(workflowId: $workflowId)
+}
+```
+
+### Queries
+
+```graphql
+# List workflows
+query GetWorkflows($projectId: Int) {
+  labelingWorkflows(projectId: $projectId) {
+    items {
+      id
+      name
+      description
+      status
+      projectId
+      triggerType
+      steps {
+        name
+        type
+        config
+      }
+      createdAt
+      lastExecutedAt
+    }
+    total
+  }
+}
+
+# Get workflow details
+query GetWorkflow($workflowId: String!) {
+  labelingWorkflow(workflowId: $workflowId) {
+    id
+    name
+    description
+    projectId
+    steps {
+      name
+      type
+      order
+      config
+      continueOnError
+    }
+    status
+  }
+}
+
+# Get execution status
+query GetExecution($executionId: String!) {
+  workflowExecution(executionId: $executionId) {
+    id
+    workflowName
+    status
+    steps {
+      stepName
+      stepType
+      status
+      order
+      startedAt
+      completedAt
+      durationMs
+      output
+      error
+    }
+    startedAt
+    completedAt
+    totalDurationMs
+    summary
+  }
+}
+```
+
+## Database Schema
+
+### Tables
+
+**labeling_workflows**
+- `id` (UUID) - Primary key
+- `domain_id` - Multi-tenancy
+- `creator_id` - User who created workflow
+- `name`, `description` - Workflow metadata
+- `project_id` - Label Studio project ID
+- `trigger_type` - Manual/Scheduled/Event
+- `trigger_config` - Trigger configuration (JSON)
+- `steps` (JSONB) - Workflow step definitions
+- `status` - Draft/Active/Paused/Completed/Failed
+- `last_executed_at`, `next_execution_at` - Scheduling
+- `created_at`, `updated_at`, `deleted_at` - Timestamps
+
+**workflow_executions**
+- `id` (UUID) - Execution instance ID
+- `workflow_id` - Reference to workflow
+- `status` - running/completed/failed
+- `started_at`, `completed_at`, `total_duration_ms` - Timing
+- `summary`, `error` - Results
+
+**workflow_execution_steps**
+- `id` (UUID) - Step instance ID
+- `execution_id` - Reference to execution
+- `step_name`, `step_type` - Step info
+- `order` - Execution sequence
+- `status` - pending/running/completed/failed/skipped
+- `started_at`, `completed_at`, `duration_ms` - Timing
+- `output`, `error` - Results
+
+### Indexes
+
+- `ix_labeling_workflow_0` - (domain, projectId, status)
+- `ix_labeling_workflow_1` - (domain, name)
+- `ix_workflow_execution_0` - (domain, workflow, status)
+- `ix_workflow_execution_1` - (domain, startedAt)
+- `ix_workflow_execution_step_0` - (domain, execution, status)
+- `ix_workflow_execution_step_1` - (domain, execution, order)
+
+## Step Configuration Examples
+
+### Import Data Step
+```json
+{
+  "sourceType": "dataset",
+  "dataSetId": "dataset-uuid",
+  "imageField": "image",
+  "limit": 1000
+}
+```
+
+### Generate Predictions Step
+```json
+{
+  "modelId": "resnet50-v2",
+  "confidenceThreshold": 0.7,
+  "forceRegenerate": false
+}
+```
+
+### Wait for Annotations Step
+```json
+{
+  "minCompletionRate": 0.9,
+  "autoProceed": false
+}
+```
+
+### Sync Annotations Step
+```json
+{
+  "completedOnly": true,
+  "targetDataSet": "dataset-uuid"
+}
+```
+
+### Validate Quality Step
+```json
+{
+  "minQualityScore": 0.8,
+  "validationRules": ["consistency", "completeness"]
+}
+```
+
+## Architecture
+
+```
+@things-factory/labeling
+├── server/                    # Backend
+│   ├── entities/             # TypeORM entities
+│   │   ├── labeling-workflow.ts
+│   │   ├── workflow-execution.ts
+│   │   └── workflow-execution-step.ts
+│   ├── service/              # Business logic
+│   │   └── labeling-workflow-service.ts
+│   ├── types/                # GraphQL types
+│   │   └── workflow-types.ts
+│   └── index.ts              # Exports
+│
+└── client/                    # Frontend
+    ├── pages/                # Page components
+    │   ├── workflow-list.ts
+    │   └── workflow-builder.ts
+    ├── route.ts              # Route configuration
+    ├── menu.ts               # Menu configuration
+    └── index.ts              # Exports
+```
+
+## Integration Examples
+
+### With operato-dataset
+
+```typescript
+// Extend with dataset-specific functionality
+import { LabelingWorkflowService } from '@things-factory/labeling'
+
+@Resolver()
+export class DatasetLabelingWorkflow {
+  private workflowService = new LabelingWorkflowService()
+
+  @Mutation()
+  async createDatasetLabelingWorkflow(
+    @Arg('dataSetId') dataSetId: string,
+    @Arg('projectId', type => Int) projectId: number
+  ) {
+    return await this.workflowService.createLabelingWorkflow({
+      name: `Auto-label ${dataSetId}`,
+      projectId,
+      steps: [
+        // Dataset-specific preset steps
+      ]
+    }, context)
+  }
+}
+```
+
+### Custom UI Wrapper
+
+```typescript
+// Create custom workflow builder with presets
+@customElement('custom-workflow-builder')
+export class CustomWorkflowBuilder extends LitElement {
+  render() {
+    return html`
+      <workflow-builder-page
+        .defaultConfig=${{
+          triggerType: 'event',
+          steps: [/* preset steps */]
+        }}
+      ></workflow-builder-page>
+    `
+  }
+}
+```
+
+## Documentation
+
+- **[UI Documentation](./UI_DOCUMENTATION.md)** - Complete UI component reference
+- **[Entity Implementation](./ENTITY_IMPLEMENTATION.md)** - Database schema details
+- **[Integration Guide](../operato-dataset/LABELING_INTEGRATION.md)** - Integration examples
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build both server and client
+npm run build
+
+# Build server only
+npm run build:server
+
+# Build client only
+npm run build:client
+
+# Clean build artifacts
+npm run clean
+```
+
+## Best Practices
+
+1. **Validate JSON configurations** before saving workflows
+2. **Use continue-on-error judiciously** for non-critical steps
+3. **Monitor execution status** for long-running workflows
+4. **Set appropriate limits** in import_data steps
+5. **Use descriptive step names** for clarity
+
+## Troubleshooting
+
+**Issue**: Workflow not saving
+- **Solution**: Check JSON configuration syntax, ensure required fields are filled
+
+**Issue**: Execution stuck
+- **Solution**: Check workflow_execution_steps table for failed steps, review error messages
+
+**Issue**: UI components not loading
+- **Solution**: Verify route configuration, check browser console for import errors
+
+## Future Enhancements
+
+- [x] Database persistence with TypeORM
+- [x] Visual workflow builder UI
+- [x] GraphQL API
+- [ ] Schedule-based triggers (cron support)
+- [ ] Event-based triggers (webhook integration)
+- [ ] Drag & drop workflow builder
+- [ ] Real-time execution monitoring
+- [ ] Workflow templates library
+- [ ] Conditional branching
+- [ ] Parallel step execution
+- [ ] Workflow versioning
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please follow the Things-Factory contribution guidelines.
+
+## Support
+
+For issues and questions, please open an issue on GitHub or contact the Things-Factory team.
+
+## Changelog
+
+### 9.1.0 (2024-10-14)
+
+**Added**:
+- ✅ Complete backend with TypeORM entities
+- ✅ GraphQL API for workflow management
+- ✅ Workflow list page UI component
+- ✅ Workflow builder page UI component
+- ✅ Step editor with JSON configuration
+- ✅ Route and menu integration
+- ✅ Multi-tenancy support
+- ✅ PostgreSQL and SQLite compatibility
+- ✅ Comprehensive documentation
+
+**Changed**:
+- Renamed from "scenario" to "workflow" terminology
+- Separated from integration-label-studio package
+
+**Fixed**:
+- Parameter order issues in GraphQL resolvers
+- Type conflicts between entities and GraphQL types