@mesh-sync/worker-backend-client 4.0.2 → 4.0.3

package/README.md

@@ -324,7 +324,7 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 - `modelId` (string) [✗]: The unique identifier for the model to be downloaded.
 
-- `ownerId` (string) [✗]: The identifier of the user who owns the model.
+- `ownerId` (string) [✗]: The identifier of the user who owns the model. Optional - if not provided, will be retrieved from StorageConnection.
 
 - `storageLocation` (object) [✗]: The storage location of the model.
 
@@ -908,7 +908,7 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 ### model-metadata-generation-completed
 
-**Description:** Handles model metadata generation completed.
+**Description:** Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
 
 **Method:** `client.modelMetadataGenerationCompleted(data)`
 
@@ -916,15 +916,15 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 **Fields:**
 
-- `modelId` (string) [✓]: The unique identifier for the model.
+- `modelId` (string) [✓]: UUID of the model that was processed.
 
-- `metadata` (object) [✓]: The enriched metadata for the model.
+- `metadata` (object) [✓]: Enriched marketplace metadata generated by LLM.
 
 
 
 ### model-metadata-generation-request
 
-**Description:** Handles model metadata generation requests. Supports both storage provider downloads and MinIO-cached files.
+**Description:** Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM analysis with optional vision capabilities. Worker fetches model data from database and uses thumbnails for enhanced analysis when available. Prerequisites: file download, thumbnail generation (optional for vision), and technical metadata analysis (strongly recommended).
 
 **Method:** `client.modelMetadataGenerationRequest(data)`
 
@@ -932,29 +932,17 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 **Fields:**
 
-- `modelId` (string) [✗]: The unique identifier for the model.
-
-- `ownerId` (string) [✗]: The identifier of the user who owns the model.
-
-- `storageConnectionId` (string) [✗]: The ID of the storage connection (legacy - used if minioPath not provided).
-
-- `filePath` (string) [✗]: The path to the model file (legacy - used if minioPath not provided).
-
-- `minioPath` (string) [✗]: Path to model in MinIO (e.g., 'raw_models/{modelId}/original.glb'). If provided, file will be read from MinIO instead of downloading from storage provider.
+- `modelId` (string) [✗]: UUID of the model to generate metadata for. Worker queries database for: Model.fileName, Model.fileSize, Model.storageItem (path, provider). For vision-enhanced analysis, worker queries thumbnail_media table for thumbnail paths.
 
-- `fileName` (string) [✗]: The name of the model file.
-
-- `fileSize` (number) [✗]: The size of the model file in bytes.
+- `ownerId` (string) [✗]: UUID of the model owner. Used for authorization and audit logging.
 
-- `fileLastModified` (string) [✗]: The last modified date of the model file.
+- `parentJobId` (string) [✗]: ID of parent job (file-download, thumbnail-generation, or technical-analysis) for BullMQ dependency tracking. Ensures metadata generation runs after prerequisites complete. Should reference thumbnail-generation job when vision analysis is desired.
 
-- `storageProviderType` (string) [✗]: The type of the storage provider.
+- `technicalMetadata` (object) [✗]: Technical analysis results (geometry, quality metrics, printability) passed from backend. Worker-core-lib Model schema lacks technical_metadata column, so backend must provide this data. Used for enhanced LLM prompt context. Include: vertexCount, faceCount, surfaceArea, volume, qualityScore, printabilityScore, detectedIssues, etc.
 
-- `parentJobId` (string) [✗]: ID of parent file-download job (for BullMQ dependency tracking).
-
-- `modelThumbnailUrl` (string) [✗]: The URL of the model thumbnail.
+- `thumbnailPath` (string) [✗]: Path to generated thumbnail in MinIO storage (e.g., 'thumbnails/{modelId}/thumbnail.webp'). If provided, enables vision-enhanced metadata generation. Worker can also query thumbnail_media table, but explicit path improves performance.
 
-- `metamodel` (object) [✗]: The metamodel of the model.
+- `enableVisionAnalysis` (boolean) [✗]: Flag to enable vision-based metadata enrichment using thumbnail images. Requires thumbnailPath or available thumbnail in database. Vision analysis generates more accurate descriptions, tags, and classifications based on visual appearance.
 
 
 
@@ -1383,6 +1371,70 @@ Each worker includes its specific metrics in the `metrics` object.
 
 
 
+### worker-metrics-enriched-event
+
+**Description:** Enriched metrics event for detailed worker monitoring, cost tracking,
+and performance analysis. Published to backend.logging.events for
+centralized monitoring and cost attribution.
+
+This event is emitted by all workers on job completion and includes:
+- LLM token usage and cost breakdown
+- System resource consumption (CPU, RAM, disk I/O)
+- Detailed timing breakdown by stage
+- User and context attribution
+- Model-specific metadata
+
+
+**Method:** `client.workerMetricsEnrichedEvent(data)`
+
+**Payload Type:** `WorkerMetricsEnrichedEventMessage`
+
+**Fields:**
+
+- `eventType` (string) [✓]: Fixed type for enriched worker metrics
+
+- `workerId` (string) [✓]: Identifier of the worker
+
+- `jobId` (string) [✓]: Unique BullMQ job identifier
+
+- `timestamp` (string) [✓]: ISO 8601 timestamp when job completed
+
+- `status` (string) [✓]: Job completion status
+
+- `userId` (string) [✗]: User who owns the resource/triggered the job
+
+- `tenantId` (string) [✗]: Organization/tenant ID (for multi-tenant deployments)
+
+- `sessionId` (string) [✗]: Session ID for correlating user actions
+
+- `requestId` (string) [✗]: Request ID from originating API call (X-Request-Id)
+
+- `modelId` (string) [✗]: Model ID being processed
+
+- `metamodelId` (string) [✗]: Metamodel ID being processed
+
+- `storageItemId` (string) [✗]: Storage item ID (for file operations)
+
+- `timing` (object) [✗]: Comprehensive timing breakdown
+
+- `llmUsage` (object) [✗]: LLM token usage and cost breakdown
+
+- `resources` (object) [✗]: System resource consumption during job
+
+- `workerMetrics` (object) [✗]: Worker-specific metrics (varies by worker type)
+
+- `error` (object) [✗]: Error details if status is failure
+
+- `environment` (string) [✗]: Deployment environment
+
+- `region` (string) [✗]: Cloud region/datacenter
+
+- `workerVersion` (string) [✗]: Worker service version
+
+- `hostname` (string) [✗]: Pod/container hostname
+
+
+
 ## Configuration
 
 ### Environment Variables
@@ -1536,10 +1588,10 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
   - Handles model discovery scan requests events.
 
 - `modelMetadataGenerationCompleted(data: ModelMetadataGenerationCompletedMessage): Promise<JobResponse>`
-  - Handles model metadata generation completed.
+  - Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
 
 - `modelMetadataGenerationRequest(data: ModelMetadataGenerationRequestMessage): Promise<JobResponse>`
-  - Handles model metadata generation requests. Supports both storage provider downloads and MinIO-cached files.
+  - Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM analysis with optional vision capabilities. Worker fetches model data from database and uses thumbnails for enhanced analysis when available. Prerequisites: file download, thumbnail generation (optional for vision), and technical metadata analysis (strongly recommended).
 
 - `modelMetamodelDetectionFound(data: ModelMetamodelDetectionFoundMessage): Promise<JobResponse>`
   - Handles model metamodel detection found with hierarchical relationships.
@@ -1598,6 +1650,19 @@ All workers MUST emit this event upon job completion (success or failure).
 Each worker includes its specific metrics in the `metrics` object.
 
 
+- `workerMetricsEnrichedEvent(data: WorkerMetricsEnrichedEventMessage): Promise<JobResponse>`
+  - Enriched metrics event for detailed worker monitoring, cost tracking,
+and performance analysis. Published to backend.logging.events for
+centralized monitoring and cost attribution.
+
+This event is emitted by all workers on job completion and includes:
+- LLM token usage and cost breakdown
+- System resource consumption (CPU, RAM, disk I/O)
+- Detailed timing breakdown by stage
+- User and context attribution
+- Model-specific metadata
+
+
 
 ### Response Types
 

package/dist/client.d.ts

@@ -230,13 +230,13 @@ export declare class WorkerClient {
      */
     modelDiscoveryScanRequest(data: types.ModelDiscoveryScanRequestMessage): Promise<JobResponse>;
     /**
-     * Handles model metadata generation completed.
+     * Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
      * @param data - The message payload
      * @returns Job response with job ID
      */
     modelMetadataGenerationCompleted(data: types.ModelMetadataGenerationCompletedMessage): Promise<JobResponse>;
     /**
-     * Handles model metadata generation requests. Supports both storage provider downloads and MinIO-cached files.
+     * Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM analysis with optional vision capabilities. Worker fetches model data from database and uses thumbnails for enhanced analysis when available. Prerequisites: file download, thumbnail generation (optional for vision), and technical metadata analysis (strongly recommended).
      * @param data - The message payload
      * @returns Job response with job ID
      */
@@ -334,4 +334,20 @@ export declare class WorkerClient {
      * @returns Job response with job ID
      */
     workerAnalyticsEvent(data: types.WorkerAnalyticsEventMessage): Promise<JobResponse>;
+    /**
+     * Enriched metrics event for detailed worker monitoring, cost tracking,
+  and performance analysis. Published to backend.logging.events for
+  centralized monitoring and cost attribution.
+  
+  This event is emitted by all workers on job completion and includes:
+  - LLM token usage and cost breakdown
+  - System resource consumption (CPU, RAM, disk I/O)
+  - Detailed timing breakdown by stage
+  - User and context attribution
+  - Model-specific metadata
+  
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    workerMetricsEnrichedEvent(data: types.WorkerMetricsEnrichedEventMessage): Promise<JobResponse>;
 }

package/dist/client.js

@@ -305,7 +305,7 @@ export class WorkerClient {
         return this.sendToQueue(types.MessageTypes.MODEL_DISCOVERY_SCAN_REQUEST, data);
     }
     /**
-     * Handles model metadata generation completed.
+     * Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
      * @param data - The message payload
      * @returns Job response with job ID
      */
@@ -313,7 +313,7 @@ export class WorkerClient {
         return this.sendToQueue(types.MessageTypes.MODEL_METADATA_GENERATION_COMPLETED, data);
     }
     /**
-     * Handles model metadata generation requests. Supports both storage provider downloads and MinIO-cached files.
+     * Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM analysis with optional vision capabilities. Worker fetches model data from database and uses thumbnails for enhanced analysis when available. Prerequisites: file download, thumbnail generation (optional for vision), and technical metadata analysis (strongly recommended).
      * @param data - The message payload
      * @returns Job response with job ID
      */
@@ -437,4 +437,22 @@ export class WorkerClient {
     async workerAnalyticsEvent(data) {
         return this.sendToQueue(types.MessageTypes.WORKER_ANALYTICS_EVENT, data);
     }
+    /**
+     * Enriched metrics event for detailed worker monitoring, cost tracking,
+  and performance analysis. Published to backend.logging.events for
+  centralized monitoring and cost attribution.
+  
+  This event is emitted by all workers on job completion and includes:
+  - LLM token usage and cost breakdown
+  - System resource consumption (CPU, RAM, disk I/O)
+  - Detailed timing breakdown by stage
+  - User and context attribution
+  - Model-specific metadata
+  
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    async workerMetricsEnrichedEvent(data) {
+        return this.sendToQueue(types.MessageTypes.WORKER_METRICS_ENRICHED_EVENT, data);
+    }
 }

package/dist/types.d.ts

@@ -42,6 +42,7 @@ export declare const MessageTypes: {
     readonly THUMBNAIL_GENERATION_REQUEST: "thumbnail-generation-request";
     readonly USER_ENGAGEMENT_EVENT: "user-engagement-event";
     readonly WORKER_ANALYTICS_EVENT: "worker-analytics-event";
+    readonly WORKER_METRICS_ENRICHED_EVENT: "worker-metrics-enriched-event";
 };
 export type MessageType = typeof MessageTypes[keyof typeof MessageTypes];
 /**
@@ -220,7 +221,7 @@ export interface FileDownloadCompletedMessage {
 export interface FileDownloadRequestMessage {
     /** The unique identifier for the model to be downloaded. */
     modelId?: string;
-    /** The identifier of the user who owns the model. */
+    /** The identifier of the user who owns the model. Optional - if not provided, will be retrieved from StorageConnection. */
     ownerId?: string;
     /** The storage location of the model. */
     storageLocation?: Record<string, string | number | boolean>;
@@ -669,42 +670,30 @@ export interface ModelDiscoveryScanRequestMessage {
     path?: string;
 }
 /**
- * Handles model metadata generation completed.
+ * Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
  */
 export interface ModelMetadataGenerationCompletedMessage {
-    /** The unique identifier for the model. */
+    /** UUID of the model that was processed. */
     modelId: string;
-    /** The enriched metadata for the model. */
+    /** Enriched marketplace metadata generated by LLM. */
     metadata: Record<string, string | number | boolean>;
 }
 /**
- * Handles model metadata generation requests. Supports both storage provider downloads and MinIO-cached files.
+ * Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM analysis with optional vision capabilities. Worker fetches model data from database and uses thumbnails for enhanced analysis when available. Prerequisites: file download, thumbnail generation (optional for vision), and technical metadata analysis (strongly recommended).
  */
 export interface ModelMetadataGenerationRequestMessage {
-    /** The unique identifier for the model. */
+    /** UUID of the model to generate metadata for. Worker queries database for: Model.fileName, Model.fileSize, Model.storageItem (path, provider). For vision-enhanced analysis, worker queries thumbnail_media table for thumbnail paths. */
     modelId?: string;
-    /** The identifier of the user who owns the model. */
+    /** UUID of the model owner. Used for authorization and audit logging. */
     ownerId?: string;
-    /** The ID of the storage connection (legacy - used if minioPath not provided). */
-    storageConnectionId?: string;
-    /** The path to the model file (legacy - used if minioPath not provided). */
-    filePath?: string;
-    /** Path to model in MinIO (e.g., 'raw_models/{modelId}/original.glb'). If provided, file will be read from MinIO instead of downloading from storage provider. */
-    minioPath?: string;
-    /** The name of the model file. */
-    fileName?: string;
-    /** The size of the model file in bytes. */
-    fileSize?: number;
-    /** The last modified date of the model file. */
-    fileLastModified?: string;
-    /** The type of the storage provider. */
-    storageProviderType?: string;
-    /** ID of parent file-download job (for BullMQ dependency tracking). */
+    /** ID of parent job (file-download, thumbnail-generation, or technical-analysis) for BullMQ dependency tracking. Ensures metadata generation runs after prerequisites complete. Should reference thumbnail-generation job when vision analysis is desired. */
     parentJobId?: string;
-    /** The URL of the model thumbnail. */
-    modelThumbnailUrl?: string;
-    /** The metamodel of the model. */
-    metamodel?: Record<string, string | number | boolean>;
+    /** Technical analysis results (geometry, quality metrics, printability) passed from backend. Worker-core-lib Model schema lacks technical_metadata column, so backend must provide this data. Used for enhanced LLM prompt context. Include: vertexCount, faceCount, surfaceArea, volume, qualityScore, printabilityScore, detectedIssues, etc. */
+    technicalMetadata?: Record<string, string | number | boolean>;
+    /** Path to generated thumbnail in MinIO storage (e.g., 'thumbnails/{modelId}/thumbnail.webp'). If provided, enables vision-enhanced metadata generation. Worker can also query thumbnail_media table, but explicit path improves performance. */
+    thumbnailPath?: string;
+    /** Flag to enable vision-based metadata enrichment using thumbnail images. Requires thumbnailPath or available thumbnail in database. Vision analysis generates more accurate descriptions, tags, and classifications based on visual appearance. */
+    enableVisionAnalysis?: boolean;
 }
 /**
  * Handles model metamodel detection found with hierarchical relationships.
@@ -1047,3 +1036,60 @@ export interface WorkerAnalyticsEventMessage {
     /** Worker-specific metrics. Structure varies by eventType. */
     metrics?: Record<string, string | number | boolean>;
 }
+/**
+ * Enriched metrics event for detailed worker monitoring, cost tracking,
+and performance analysis. Published to backend.logging.events for
+centralized monitoring and cost attribution.
+
+This event is emitted by all workers on job completion and includes:
+- LLM token usage and cost breakdown
+- System resource consumption (CPU, RAM, disk I/O)
+- Detailed timing breakdown by stage
+- User and context attribution
+- Model-specific metadata
+
+ */
+export interface WorkerMetricsEnrichedEventMessage {
+    /** Fixed type for enriched worker metrics */
+    eventType: string;
+    /** Identifier of the worker */
+    workerId: string;
+    /** Unique BullMQ job identifier */
+    jobId: string;
+    /** ISO 8601 timestamp when job completed */
+    timestamp: string;
+    /** Job completion status */
+    status: string;
+    /** User who owns the resource/triggered the job */
+    userId?: string;
+    /** Organization/tenant ID (for multi-tenant deployments) */
+    tenantId?: string;
+    /** Session ID for correlating user actions */
+    sessionId?: string;
+    /** Request ID from originating API call (X-Request-Id) */
+    requestId?: string;
+    /** Model ID being processed */
+    modelId?: string;
+    /** Metamodel ID being processed */
+    metamodelId?: string;
+    /** Storage item ID (for file operations) */
+    storageItemId?: string;
+    /** Comprehensive timing breakdown */
+    timing?: Record<string, string | number | boolean>;
+    /** LLM token usage and cost breakdown */
+    llmUsage?: Record<string, string | number | boolean>;
+    /** System resource consumption during job */
+    resources?: Record<string, string | number | boolean>;
+    /** Worker-specific metrics (varies by worker type) */
+    workerMetrics?: Record<string, string | number | boolean>;
+    /** Error details if status is failure */
+    error?: Record<string, string | number | boolean>;
+    /** Deployment environment */
+    environment?: string;
+    /** Cloud region/datacenter */
+    region?: string;
+    /** Worker service version */
+    workerVersion?: string;
+    /** Pod/container hostname */
+    hostname?: string;
+}

package/dist/types.js

@@ -43,4 +43,5 @@ export const MessageTypes = {
     THUMBNAIL_GENERATION_REQUEST: 'thumbnail-generation-request',
     USER_ENGAGEMENT_EVENT: 'user-engagement-event',
     WORKER_ANALYTICS_EVENT: 'worker-analytics-event',
+    WORKER_METRICS_ENRICHED_EVENT: 'worker-metrics-enriched-event',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mesh-sync/worker-backend-client",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "description": "Auto-generated TypeScript client for worker-backend - provides type-safe methods for enqueueing jobs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",