@eyepop.ai/eyepop 3.25.3 → 3.25.4

package/dist/eyepop.index.d.mts

@@ -665,6 +665,16 @@ interface InferRequest {
     refresh?: boolean;
     transform_into?: TransformInto;
     response_schema?: ResponseSchema;
+    /**
+     * Auto-label task. The worker derives the prompt and output schema from the task and
+     * `prompts`, so `text_prompt`, `transform_into` and `response_schema` must be unset.
+     * Object detection returns `objects`, image classification `classes`, each labeled with a
+     * prompt's label. A task takes one image. Leave `config.max_new_tokens` unset to use the
+     * worker's default, which leaves room for a detection answer.
+     */
+    task?: AutoAnnotateTask;
+    /** Labels and what each one means, for `task`; required with a task. */
+    prompts?: AutoAnnotatePrompt[];
 }
 interface EvaluateFilter {
     partitions?: string[];
@@ -1477,6 +1487,11 @@ interface WorkerOptions extends Options {
      * Defaults to process.env['EYEPOP_PIPELINE_MODE'].
      */
     isPipelineMode?: boolean;
+    /**
+     * In pipeline mode, the most sockets the endpoint opens. Each runs its own pipeline, which plays its
+     * sources one after another; a new one opens only while every open one has a source. Defaults to 4.
+     */
+    pipelineSockets?: number;
 }
 
 /**
@@ -2014,10 +2029,12 @@ declare const PIPELINE_PATH = "/api/v1/pipeline";
 declare const SUBPROTOCOL = "eyepop.v1";
 /** A socket may have this many open sources; one more is answered `queue_full`. */
 declare const MAX_OPEN_SOURCES = 256;
+/** The most sockets an endpoint opens unless `pipelineSockets` says otherwise. */
+declare const PIPELINE_SOCKETS = 4;
 /** Uploads up to this size go as one combined message, larger ones in chunks. */
 declare const COMBINED_UPLOAD_MAX_BYTES: number;
 /** Why pipeline mode refused its configuration. */
-type PipelineConfigurationProblem = 'session_options' | 'job_queue_length' | 'no_pipeline_api_url' | 'insecure_url';
+type PipelineConfigurationProblem = 'session_options' | 'job_queue_length' | 'pipeline_sockets' | 'no_pipeline_api_url' | 'insecure_url';
 /** Pipeline mode cannot run as configured; `options` names the refused options for `session_options`. */
 declare class PipelineConfigurationError extends Error {
     readonly problem: PipelineConfigurationProblem;
@@ -2102,18 +2119,23 @@ declare class PipelineJob implements ResultStream {
     cancel(): void;
     [Symbol.asyncIterator](): AsyncIterator<Prediction>;
 }
-/** Runs jobs on one socket to the pipeline API, opened when the endpoint connects. */
+/**
+ * Runs jobs on up to `pipelineSockets` sockets to the pipeline API; connecting opens the first. A
+ * socket's pipeline plays its sources one after another, so a batch on one socket leaves the GPU
+ * mostly idle. While every open socket has a source and fewer than `pipelineSockets` are open, the next
+ * job opens another; each job goes on the socket that has room and the fewest open sources.
+ */
 declare class PipelineBackend implements WorkerBackend {
     private readonly ctx;
     private _pipelineApiUrl;
-    private _socket;
+    private _sockets;
     private _connecting;
     private _sendChain;
     private _disconnecting;
     private _nextId;
     private _currentPop;
     private readonly _warned;
-    private _heartbeat;
+    private _noExtraSocketUntil;
     private _reconnects;
     constructor(ctx: WorkerContext);
     reconnect(): Promise<void>;
@@ -2122,8 +2144,17 @@ declare class PipelineBackend implements WorkerBackend {
     popName(): string | null;
     authorizationHeader(): Promise<string>;
     private inOrder;
-    /** The open socket, or a new one with the last pop set on it. */
+    private openSockets;
+    /** An open socket, or a new one with the last pop set on it. */
     private ensureSocket;
+    /**
+     * The socket for the next job; the caller runs it in submission order. A live job goes on a socket
+     * of its own, an idle one or a new one, which `pipelineSockets` does not count. Any other job skips
+     * the sockets with a live source: a new one while every other socket has a source and fewer than
+     * `pipelineSockets` are open, else the one with room and the fewest sources.
+     */
+    private socketForJob;
+    /** A new socket with the last pop set on it; `patient` waits through 503 with Retry-After. */
     private openSocket;
     private startHeartbeat;
     private socketUrl;
@@ -2137,7 +2168,11 @@ declare class PipelineBackend implements WorkerBackend {
     /** Send a command that is answered by `result` or `error` under its id. */
     private command;
     pop(): Pop | null;
-    /** Set the pop on the socket's pipeline; a pop it refuses rejects, and the last pop it took stays. */
+    /**
+     * Set the pop on every open socket's pipeline; a pop the first refuses rejects, and the last pop it
+     * took stays. shortcut: a refusal from a later socket, which the first took, leaves the earlier ones
+     * on the new pop; a refusal is the pop's own fault, so every socket answers it alike.
+     */
     changePop(pop: Pop): Promise<void>;
     private setPopOn;
     submit(work: WorkerWork): Promise<ResultStream>;
@@ -2290,4 +2325,4 @@ declare namespace EyePop {
     function dataEndpoint(opts?: DataOptions): DataEndpoint;
 }
 
-export { type AbilityAliasEntry, AbstractJob, type AccessTokenAuth, type AliasResolution, type Annotation, AnnotationInclusionMode, AnnotationType, type ApiKeyAuth, type Area, AreaType, ArtifactType, type Asset, type AssetImport, AssetInclusionMode, AssetStatus, AssetUrlType, type AssetUuidSource, type Auth0Options, type Authentication, type AutoAnnotate, type AutoAnnotateParams, type AutoAnnotatePrompt, AutoAnnotateStatus, AutoAnnotateTask, type AutoPromptConfig, type AutoTask, type BaseArea, type BaseComponent, type BaseTask, type Box, COMBINED_UPLOAD_MAX_BYTES, type Camera, type CameraDistortion, type CameraExtrinsics, type CameraIntrinsics, type ChangeEvent, ChangeType, type ClassificationTask, type CloudBounds, type CloudBox, type ComponentFinderComponent, type ComponentParams, ComputeAccountMismatchError, ComputeApiError, type Contour, type ContourArea, type ContourFinderComponent, ContourType, type CreateWorkflow, type CreateWorkflowConfig, DEFAULT_PREDICTION_VERSION, DataApiType, DataEndpoint, type DataOptions, type DataSession, type Dataset, type DatasetAutoAnnotate, type DatasetAutoAnnotateCreate, type DatasetAutoAnnotateUpdate, type DatasetCreate, type DatasetHeroAssetUpdate, type DatasetParent, type DatasetUpdate, type DatasetVersion, type DatasetVersionAssetStats, type Depth, DepthMap, type DepthSemantic, type DownloadResponse, Endpoint, EndpointState, type EvaluateConfig, type EvaluateFilter, type EvaluateRequest, type EvaluateResponse, type EvaluateRunInfo, EvaluationStatus, ExportedBy, EyePop, EyePopDataWebSocketError, EyepopLineDecoder, type FileSource, type ForwardComponent, ForwardOperatorType, type HttpClient, type InferRequest, type InferRunInfo, type InferRuntimeConfig, type InferenceComponent, InferenceType, type ListWorkFlowItem, type ListWorkFlowItemMetadata, type ListWorkflowItemMetadataLabels, LoadFromAssetUuidJob, LoadFromGroupJob, LoadFromJob, LoadMediaStreamJob, type LocalAuth, MAX_OPEN_SOURCES, type Mask, type MediaStreamSource, type Model, type ModelCreate, type ModelExport, ModelExportStatus, ModelFormat, type ModelMetrics, ModelPrecisionType, type ModelSample, ModelStatus, ModelTask, type ModelTrainingProgress, ModelTrainingStage, ModelType, type ModelUpdate, type MotionDetectConfig, MotionModel, type MultipartContent, type MultipartPart, type OAuth2Auth, type OnChangeEvent, type Options, PIPELINE_PATH, type PathSource, PipelineBackend, PipelineCommandError, PipelineConfigurationError, type PipelineConfigurationProblem, PipelineJob, PipelineSocketClosedError, PipelineSourceError, type PlatformSupport, type Point2d, type Point3d, PointCloud, type Pop, type PopComponent, PopComponentType, type PopCrop, type PopDepthMap, type PopForward, type PopForwardOperator, type PopSelect, type PredictedClass, type PredictedEmbedding, type PredictedKeyPoint, type PredictedKeyPoints, type PredictedMesh, type PredictedMotion, type PredictedObject, type PredictedText, type Prediction, PredictionVersion, type ProcessParams, type ProcessRequest, QUATERNION_TOLERANCE, type QcAiHubExportParams, type Quaternion, type RectangleArea, type ResponseSchema, type ResultStream, type Roi, SUBPROTOCOL, SelectMode, Semaphore, type Session, type SessionAuth, SessionBackend, type Source, type SourceDefaults, Stream, type StreamEvent, type StreamSource, type StreamTime, TaskMode, TaskType, type TimeSpan, type TrackingComponent, TranscodeMode, type TransformInto, TransientPopId, UploadGroupJob, UploadJob, type UploadSource, type UrlSource, UserReview, type Vector3, type Vector3d, VideoMode, type VlmAbility, type VlmAbilityCreate, type VlmAbilityGroup, type VlmAbilityGroupCreate, type VlmAbilityGroupUpdate, VlmAbilityStatus, type VlmAbilityUpdate, WebrtcBase, WebrtcWhep, WebrtcWhip, type WorkerBackend, type WorkerContext, WorkerEndpoint, type WorkerOptions, type WorkerSession, type WorkerWork, type Workflow, WorkflowPhase, accessTokenCredential, apiKeyCredential, cloudOfDepth, cloudOfObject, cloudsOfPrediction, decodeDepthMap, decodePointCloud, EyePop as default, encodeMultipartFormData, getBaseUrl, isSelectOperator, popSelects, randomMultipartBoundary, readableStreamFromString, resolveAuth, validateCamera, validatePop };
+export { type AbilityAliasEntry, AbstractJob, type AccessTokenAuth, type AliasResolution, type Annotation, AnnotationInclusionMode, AnnotationType, type ApiKeyAuth, type Area, AreaType, ArtifactType, type Asset, type AssetImport, AssetInclusionMode, AssetStatus, AssetUrlType, type AssetUuidSource, type Auth0Options, type Authentication, type AutoAnnotate, type AutoAnnotateParams, type AutoAnnotatePrompt, AutoAnnotateStatus, AutoAnnotateTask, type AutoPromptConfig, type AutoTask, type BaseArea, type BaseComponent, type BaseTask, type Box, COMBINED_UPLOAD_MAX_BYTES, type Camera, type CameraDistortion, type CameraExtrinsics, type CameraIntrinsics, type ChangeEvent, ChangeType, type ClassificationTask, type CloudBounds, type CloudBox, type ComponentFinderComponent, type ComponentParams, ComputeAccountMismatchError, ComputeApiError, type Contour, type ContourArea, type ContourFinderComponent, ContourType, type CreateWorkflow, type CreateWorkflowConfig, DEFAULT_PREDICTION_VERSION, DataApiType, DataEndpoint, type DataOptions, type DataSession, type Dataset, type DatasetAutoAnnotate, type DatasetAutoAnnotateCreate, type DatasetAutoAnnotateUpdate, type DatasetCreate, type DatasetHeroAssetUpdate, type DatasetParent, type DatasetUpdate, type DatasetVersion, type DatasetVersionAssetStats, type Depth, DepthMap, type DepthSemantic, type DownloadResponse, Endpoint, EndpointState, type EvaluateConfig, type EvaluateFilter, type EvaluateRequest, type EvaluateResponse, type EvaluateRunInfo, EvaluationStatus, ExportedBy, EyePop, EyePopDataWebSocketError, EyepopLineDecoder, type FileSource, type ForwardComponent, ForwardOperatorType, type HttpClient, type InferRequest, type InferRunInfo, type InferRuntimeConfig, type InferenceComponent, InferenceType, type ListWorkFlowItem, type ListWorkFlowItemMetadata, type ListWorkflowItemMetadataLabels, LoadFromAssetUuidJob, LoadFromGroupJob, LoadFromJob, LoadMediaStreamJob, type LocalAuth, MAX_OPEN_SOURCES, type Mask, type MediaStreamSource, type Model, type ModelCreate, type ModelExport, ModelExportStatus, ModelFormat, type ModelMetrics, ModelPrecisionType, type ModelSample, ModelStatus, ModelTask, type ModelTrainingProgress, ModelTrainingStage, ModelType, type ModelUpdate, type MotionDetectConfig, MotionModel, type MultipartContent, type MultipartPart, type OAuth2Auth, type OnChangeEvent, type Options, PIPELINE_PATH, PIPELINE_SOCKETS, type PathSource, PipelineBackend, PipelineCommandError, PipelineConfigurationError, type PipelineConfigurationProblem, PipelineJob, PipelineSocketClosedError, PipelineSourceError, type PlatformSupport, type Point2d, type Point3d, PointCloud, type Pop, type PopComponent, PopComponentType, type PopCrop, type PopDepthMap, type PopForward, type PopForwardOperator, type PopSelect, type PredictedClass, type PredictedEmbedding, type PredictedKeyPoint, type PredictedKeyPoints, type PredictedMesh, type PredictedMotion, type PredictedObject, type PredictedText, type Prediction, PredictionVersion, type ProcessParams, type ProcessRequest, QUATERNION_TOLERANCE, type QcAiHubExportParams, type Quaternion, type RectangleArea, type ResponseSchema, type ResultStream, type Roi, SUBPROTOCOL, SelectMode, Semaphore, type Session, type SessionAuth, SessionBackend, type Source, type SourceDefaults, Stream, type StreamEvent, type StreamSource, type StreamTime, TaskMode, TaskType, type TimeSpan, type TrackingComponent, TranscodeMode, type TransformInto, TransientPopId, UploadGroupJob, UploadJob, type UploadSource, type UrlSource, UserReview, type Vector3, type Vector3d, VideoMode, type VlmAbility, type VlmAbilityCreate, type VlmAbilityGroup, type VlmAbilityGroupCreate, type VlmAbilityGroupUpdate, VlmAbilityStatus, type VlmAbilityUpdate, WebrtcBase, WebrtcWhep, WebrtcWhip, type WorkerBackend, type WorkerContext, WorkerEndpoint, type WorkerOptions, type WorkerSession, type WorkerWork, type Workflow, WorkflowPhase, accessTokenCredential, apiKeyCredential, cloudOfDepth, cloudOfObject, cloudsOfPrediction, decodeDepthMap, decodePointCloud, EyePop as default, encodeMultipartFormData, getBaseUrl, isSelectOperator, popSelects, randomMultipartBoundary, readableStreamFromString, resolveAuth, validateCamera, validatePop };

package/dist/eyepop.index.d.ts

@@ -665,6 +665,16 @@ interface InferRequest {
     refresh?: boolean;
     transform_into?: TransformInto;
     response_schema?: ResponseSchema;
+    /**
+     * Auto-label task. The worker derives the prompt and output schema from the task and
+     * `prompts`, so `text_prompt`, `transform_into` and `response_schema` must be unset.
+     * Object detection returns `objects`, image classification `classes`, each labeled with a
+     * prompt's label. A task takes one image. Leave `config.max_new_tokens` unset to use the
+     * worker's default, which leaves room for a detection answer.
+     */
+    task?: AutoAnnotateTask;
+    /** Labels and what each one means, for `task`; required with a task. */
+    prompts?: AutoAnnotatePrompt[];
 }
 interface EvaluateFilter {
     partitions?: string[];
@@ -1477,6 +1487,11 @@ interface WorkerOptions extends Options {
      * Defaults to process.env['EYEPOP_PIPELINE_MODE'].
      */
     isPipelineMode?: boolean;
+    /**
+     * In pipeline mode, the most sockets the endpoint opens. Each runs its own pipeline, which plays its
+     * sources one after another; a new one opens only while every open one has a source. Defaults to 4.
+     */
+    pipelineSockets?: number;
 }
 
 /**
@@ -2014,10 +2029,12 @@ declare const PIPELINE_PATH = "/api/v1/pipeline";
 declare const SUBPROTOCOL = "eyepop.v1";
 /** A socket may have this many open sources; one more is answered `queue_full`. */
 declare const MAX_OPEN_SOURCES = 256;
+/** The most sockets an endpoint opens unless `pipelineSockets` says otherwise. */
+declare const PIPELINE_SOCKETS = 4;
 /** Uploads up to this size go as one combined message, larger ones in chunks. */
 declare const COMBINED_UPLOAD_MAX_BYTES: number;
 /** Why pipeline mode refused its configuration. */
-type PipelineConfigurationProblem = 'session_options' | 'job_queue_length' | 'no_pipeline_api_url' | 'insecure_url';
+type PipelineConfigurationProblem = 'session_options' | 'job_queue_length' | 'pipeline_sockets' | 'no_pipeline_api_url' | 'insecure_url';
 /** Pipeline mode cannot run as configured; `options` names the refused options for `session_options`. */
 declare class PipelineConfigurationError extends Error {
     readonly problem: PipelineConfigurationProblem;
@@ -2102,18 +2119,23 @@ declare class PipelineJob implements ResultStream {
     cancel(): void;
     [Symbol.asyncIterator](): AsyncIterator<Prediction>;
 }
-/** Runs jobs on one socket to the pipeline API, opened when the endpoint connects. */
+/**
+ * Runs jobs on up to `pipelineSockets` sockets to the pipeline API; connecting opens the first. A
+ * socket's pipeline plays its sources one after another, so a batch on one socket leaves the GPU
+ * mostly idle. While every open socket has a source and fewer than `pipelineSockets` are open, the next
+ * job opens another; each job goes on the socket that has room and the fewest open sources.
+ */
 declare class PipelineBackend implements WorkerBackend {
     private readonly ctx;
     private _pipelineApiUrl;
-    private _socket;
+    private _sockets;
     private _connecting;
     private _sendChain;
     private _disconnecting;
     private _nextId;
     private _currentPop;
     private readonly _warned;
-    private _heartbeat;
+    private _noExtraSocketUntil;
     private _reconnects;
     constructor(ctx: WorkerContext);
     reconnect(): Promise<void>;
@@ -2122,8 +2144,17 @@ declare class PipelineBackend implements WorkerBackend {
     popName(): string | null;
     authorizationHeader(): Promise<string>;
     private inOrder;
-    /** The open socket, or a new one with the last pop set on it. */
+    private openSockets;
+    /** An open socket, or a new one with the last pop set on it. */
     private ensureSocket;
+    /**
+     * The socket for the next job; the caller runs it in submission order. A live job goes on a socket
+     * of its own, an idle one or a new one, which `pipelineSockets` does not count. Any other job skips
+     * the sockets with a live source: a new one while every other socket has a source and fewer than
+     * `pipelineSockets` are open, else the one with room and the fewest sources.
+     */
+    private socketForJob;
+    /** A new socket with the last pop set on it; `patient` waits through 503 with Retry-After. */
     private openSocket;
     private startHeartbeat;
     private socketUrl;
@@ -2137,7 +2168,11 @@ declare class PipelineBackend implements WorkerBackend {
     /** Send a command that is answered by `result` or `error` under its id. */
     private command;
     pop(): Pop | null;
-    /** Set the pop on the socket's pipeline; a pop it refuses rejects, and the last pop it took stays. */
+    /**
+     * Set the pop on every open socket's pipeline; a pop the first refuses rejects, and the last pop it
+     * took stays. shortcut: a refusal from a later socket, which the first took, leaves the earlier ones
+     * on the new pop; a refusal is the pop's own fault, so every socket answers it alike.
+     */
     changePop(pop: Pop): Promise<void>;
     private setPopOn;
     submit(work: WorkerWork): Promise<ResultStream>;
@@ -2290,4 +2325,4 @@ declare namespace EyePop {
     function dataEndpoint(opts?: DataOptions): DataEndpoint;
 }
 
-export { type AbilityAliasEntry, AbstractJob, type AccessTokenAuth, type AliasResolution, type Annotation, AnnotationInclusionMode, AnnotationType, type ApiKeyAuth, type Area, AreaType, ArtifactType, type Asset, type AssetImport, AssetInclusionMode, AssetStatus, AssetUrlType, type AssetUuidSource, type Auth0Options, type Authentication, type AutoAnnotate, type AutoAnnotateParams, type AutoAnnotatePrompt, AutoAnnotateStatus, AutoAnnotateTask, type AutoPromptConfig, type AutoTask, type BaseArea, type BaseComponent, type BaseTask, type Box, COMBINED_UPLOAD_MAX_BYTES, type Camera, type CameraDistortion, type CameraExtrinsics, type CameraIntrinsics, type ChangeEvent, ChangeType, type ClassificationTask, type CloudBounds, type CloudBox, type ComponentFinderComponent, type ComponentParams, ComputeAccountMismatchError, ComputeApiError, type Contour, type ContourArea, type ContourFinderComponent, ContourType, type CreateWorkflow, type CreateWorkflowConfig, DEFAULT_PREDICTION_VERSION, DataApiType, DataEndpoint, type DataOptions, type DataSession, type Dataset, type DatasetAutoAnnotate, type DatasetAutoAnnotateCreate, type DatasetAutoAnnotateUpdate, type DatasetCreate, type DatasetHeroAssetUpdate, type DatasetParent, type DatasetUpdate, type DatasetVersion, type DatasetVersionAssetStats, type Depth, DepthMap, type DepthSemantic, type DownloadResponse, Endpoint, EndpointState, type EvaluateConfig, type EvaluateFilter, type EvaluateRequest, type EvaluateResponse, type EvaluateRunInfo, EvaluationStatus, ExportedBy, EyePop, EyePopDataWebSocketError, EyepopLineDecoder, type FileSource, type ForwardComponent, ForwardOperatorType, type HttpClient, type InferRequest, type InferRunInfo, type InferRuntimeConfig, type InferenceComponent, InferenceType, type ListWorkFlowItem, type ListWorkFlowItemMetadata, type ListWorkflowItemMetadataLabels, LoadFromAssetUuidJob, LoadFromGroupJob, LoadFromJob, LoadMediaStreamJob, type LocalAuth, MAX_OPEN_SOURCES, type Mask, type MediaStreamSource, type Model, type ModelCreate, type ModelExport, ModelExportStatus, ModelFormat, type ModelMetrics, ModelPrecisionType, type ModelSample, ModelStatus, ModelTask, type ModelTrainingProgress, ModelTrainingStage, ModelType, type ModelUpdate, type MotionDetectConfig, MotionModel, type MultipartContent, type MultipartPart, type OAuth2Auth, type OnChangeEvent, type Options, PIPELINE_PATH, type PathSource, PipelineBackend, PipelineCommandError, PipelineConfigurationError, type PipelineConfigurationProblem, PipelineJob, PipelineSocketClosedError, PipelineSourceError, type PlatformSupport, type Point2d, type Point3d, PointCloud, type Pop, type PopComponent, PopComponentType, type PopCrop, type PopDepthMap, type PopForward, type PopForwardOperator, type PopSelect, type PredictedClass, type PredictedEmbedding, type PredictedKeyPoint, type PredictedKeyPoints, type PredictedMesh, type PredictedMotion, type PredictedObject, type PredictedText, type Prediction, PredictionVersion, type ProcessParams, type ProcessRequest, QUATERNION_TOLERANCE, type QcAiHubExportParams, type Quaternion, type RectangleArea, type ResponseSchema, type ResultStream, type Roi, SUBPROTOCOL, SelectMode, Semaphore, type Session, type SessionAuth, SessionBackend, type Source, type SourceDefaults, Stream, type StreamEvent, type StreamSource, type StreamTime, TaskMode, TaskType, type TimeSpan, type TrackingComponent, TranscodeMode, type TransformInto, TransientPopId, UploadGroupJob, UploadJob, type UploadSource, type UrlSource, UserReview, type Vector3, type Vector3d, VideoMode, type VlmAbility, type VlmAbilityCreate, type VlmAbilityGroup, type VlmAbilityGroupCreate, type VlmAbilityGroupUpdate, VlmAbilityStatus, type VlmAbilityUpdate, WebrtcBase, WebrtcWhep, WebrtcWhip, type WorkerBackend, type WorkerContext, WorkerEndpoint, type WorkerOptions, type WorkerSession, type WorkerWork, type Workflow, WorkflowPhase, accessTokenCredential, apiKeyCredential, cloudOfDepth, cloudOfObject, cloudsOfPrediction, decodeDepthMap, decodePointCloud, EyePop as default, encodeMultipartFormData, getBaseUrl, isSelectOperator, popSelects, randomMultipartBoundary, readableStreamFromString, resolveAuth, validateCamera, validatePop };
+export { type AbilityAliasEntry, AbstractJob, type AccessTokenAuth, type AliasResolution, type Annotation, AnnotationInclusionMode, AnnotationType, type ApiKeyAuth, type Area, AreaType, ArtifactType, type Asset, type AssetImport, AssetInclusionMode, AssetStatus, AssetUrlType, type AssetUuidSource, type Auth0Options, type Authentication, type AutoAnnotate, type AutoAnnotateParams, type AutoAnnotatePrompt, AutoAnnotateStatus, AutoAnnotateTask, type AutoPromptConfig, type AutoTask, type BaseArea, type BaseComponent, type BaseTask, type Box, COMBINED_UPLOAD_MAX_BYTES, type Camera, type CameraDistortion, type CameraExtrinsics, type CameraIntrinsics, type ChangeEvent, ChangeType, type ClassificationTask, type CloudBounds, type CloudBox, type ComponentFinderComponent, type ComponentParams, ComputeAccountMismatchError, ComputeApiError, type Contour, type ContourArea, type ContourFinderComponent, ContourType, type CreateWorkflow, type CreateWorkflowConfig, DEFAULT_PREDICTION_VERSION, DataApiType, DataEndpoint, type DataOptions, type DataSession, type Dataset, type DatasetAutoAnnotate, type DatasetAutoAnnotateCreate, type DatasetAutoAnnotateUpdate, type DatasetCreate, type DatasetHeroAssetUpdate, type DatasetParent, type DatasetUpdate, type DatasetVersion, type DatasetVersionAssetStats, type Depth, DepthMap, type DepthSemantic, type DownloadResponse, Endpoint, EndpointState, type EvaluateConfig, type EvaluateFilter, type EvaluateRequest, type EvaluateResponse, type EvaluateRunInfo, EvaluationStatus, ExportedBy, EyePop, EyePopDataWebSocketError, EyepopLineDecoder, type FileSource, type ForwardComponent, ForwardOperatorType, type HttpClient, type InferRequest, type InferRunInfo, type InferRuntimeConfig, type InferenceComponent, InferenceType, type ListWorkFlowItem, type ListWorkFlowItemMetadata, type ListWorkflowItemMetadataLabels, LoadFromAssetUuidJob, LoadFromGroupJob, LoadFromJob, LoadMediaStreamJob, type LocalAuth, MAX_OPEN_SOURCES, type Mask, type MediaStreamSource, type Model, type ModelCreate, type ModelExport, ModelExportStatus, ModelFormat, type ModelMetrics, ModelPrecisionType, type ModelSample, ModelStatus, ModelTask, type ModelTrainingProgress, ModelTrainingStage, ModelType, type ModelUpdate, type MotionDetectConfig, MotionModel, type MultipartContent, type MultipartPart, type OAuth2Auth, type OnChangeEvent, type Options, PIPELINE_PATH, PIPELINE_SOCKETS, type PathSource, PipelineBackend, PipelineCommandError, PipelineConfigurationError, type PipelineConfigurationProblem, PipelineJob, PipelineSocketClosedError, PipelineSourceError, type PlatformSupport, type Point2d, type Point3d, PointCloud, type Pop, type PopComponent, PopComponentType, type PopCrop, type PopDepthMap, type PopForward, type PopForwardOperator, type PopSelect, type PredictedClass, type PredictedEmbedding, type PredictedKeyPoint, type PredictedKeyPoints, type PredictedMesh, type PredictedMotion, type PredictedObject, type PredictedText, type Prediction, PredictionVersion, type ProcessParams, type ProcessRequest, QUATERNION_TOLERANCE, type QcAiHubExportParams, type Quaternion, type RectangleArea, type ResponseSchema, type ResultStream, type Roi, SUBPROTOCOL, SelectMode, Semaphore, type Session, type SessionAuth, SessionBackend, type Source, type SourceDefaults, Stream, type StreamEvent, type StreamSource, type StreamTime, TaskMode, TaskType, type TimeSpan, type TrackingComponent, TranscodeMode, type TransformInto, TransientPopId, UploadGroupJob, UploadJob, type UploadSource, type UrlSource, UserReview, type Vector3, type Vector3d, VideoMode, type VlmAbility, type VlmAbilityCreate, type VlmAbilityGroup, type VlmAbilityGroupCreate, type VlmAbilityGroupUpdate, VlmAbilityStatus, type VlmAbilityUpdate, WebrtcBase, WebrtcWhep, WebrtcWhip, type WorkerBackend, type WorkerContext, WorkerEndpoint, type WorkerOptions, type WorkerSession, type WorkerWork, type Workflow, WorkflowPhase, accessTokenCredential, apiKeyCredential, cloudOfDepth, cloudOfObject, cloudsOfPrediction, decodeDepthMap, decodePointCloud, EyePop as default, encodeMultipartFormData, getBaseUrl, isSelectOperator, popSelects, randomMultipartBoundary, readableStreamFromString, resolveAuth, validateCamera, validatePop };

package/dist/eyepop.index.js

@@ -8698,6 +8698,7 @@ __export(index_exports, {
   ModelType: () => ModelType,
   MotionModel: () => MotionModel,
   PIPELINE_PATH: () => PIPELINE_PATH,
+  PIPELINE_SOCKETS: () => PIPELINE_SOCKETS,
   PipelineBackend: () => PipelineBackend,
   PipelineCommandError: () => PipelineCommandError,
   PipelineConfigurationError: () => PipelineConfigurationError,
@@ -9050,7 +9051,7 @@ var Endpoint = class {
     this._expire_token_time = null;
     this._client = null;
     this._statusRetryHandlers = /* @__PURE__ */ new Map();
-    this._statusRetryHandlers.set(401, this.statusHandler401);
+    this._statusRetryHandlers.set(401, (statusCode) => this.statusHandler401(statusCode));
     this._limit = new Semaphore(this._options.jobQueueLength ?? 1024);
     this._state = "Idle" /* Idle */;
     this._message = null;
@@ -9066,7 +9067,7 @@ var Endpoint = class {
   }
   setStatusRetryHandlers(statusRetryHandlers = void 0) {
     this._statusRetryHandlers = new Map(statusRetryHandlers);
-    this._statusRetryHandlers.set(401, this.statusHandler401);
+    this._statusRetryHandlers.set(401, (statusCode) => this.statusHandler401(statusCode));
   }
   eyepopUrl() {
     if (this._options.eyepopUrl) {
@@ -11612,6 +11613,8 @@ if (isBrowser) {
 var PIPELINE_PATH = "/api/v1/pipeline";
 var SUBPROTOCOL = "eyepop.v1";
 var MAX_OPEN_SOURCES = 256;
+var PIPELINE_SOCKETS = 4;
+var EXTRA_SOCKET_RETRY_MS = 10 * 1e3;
 var COMBINED_UPLOAD_MAX_BYTES = 8 * 1024 * 1024;
 var CHUNK = 1;
 var COMBINED = 2;
@@ -11731,6 +11734,8 @@ var PipelineSocket = class {
     // The ids of sources sent on this socket that have neither ended nor been refused, as the
     // pipeline API counts them, cancelled ones included.
     this.held = /* @__PURE__ */ new Set();
+    // The held sources that are live. A live source never ends, so nothing queued behind it plays.
+    this.lives = /* @__PURE__ */ new Set();
     // The held sources the pipeline API took: only these end, so only these make room.
     this.accepted = /* @__PURE__ */ new Set();
     // The ends on this socket so far.
@@ -11739,6 +11744,7 @@ var PipelineSocket = class {
     // the next send waits. Null once none is held.
     this.cap = null;
     this._roomWaiters = [];
+    this.heartbeat = null;
     this.closed = new Promise((resolve) => this._markClosed = resolve);
   }
   /** A source ended or the socket closed: wake the send waiting for room. */
@@ -11772,6 +11778,10 @@ var PipelineSocket = class {
     return !this._closed && this.ws.readyState === 1;
   }
   markClosed() {
+    if (this.heartbeat !== null) {
+      clearInterval(this.heartbeat);
+      this.heartbeat = null;
+    }
     this._closed = true;
     this._markClosed();
     this.freed();
@@ -11860,14 +11870,14 @@ var PipelineBackend = class {
   constructor(ctx) {
     this.ctx = ctx;
     this._pipelineApiUrl = null;
-    this._socket = null;
+    this._sockets = [];
     this._connecting = null;
     // Every job's setSource and every changePop goes out through this chain, in the order submitted.
     this._sendChain = Promise.resolve();
     this._disconnecting = false;
     this._nextId = 0;
     this._warned = /* @__PURE__ */ new Set();
-    this._heartbeat = null;
+    this._noExtraSocketUntil = 0;
     // Reconnects at once since a source last played.
     this._reconnects = 0;
     this._currentPop = ctx.options.pop ?? null;
@@ -11881,13 +11891,9 @@ var PipelineBackend = class {
   async disconnect(closeEndpoint) {
     await closeEndpoint();
     this._disconnecting = true;
-    if (this._heartbeat !== null) {
-      clearInterval(this._heartbeat);
-      this._heartbeat = null;
-    }
-    const socket = this._socket;
-    this._socket = null;
-    if (socket !== null) {
+    const sockets = this._sockets;
+    this._sockets = [];
+    for (const socket of sockets) {
       socket.ws.close(1e3);
       await socket.closed;
     }
@@ -11905,21 +11911,55 @@ var PipelineBackend = class {
     this._sendChain = result.catch(() => void 0);
     return result;
   }
-  /** The open socket, or a new one with the last pop set on it. */
+  openSockets() {
+    return this._sockets.filter((socket) => socket.open);
+  }
+  /** An open socket, or a new one with the last pop set on it. */
   async ensureSocket() {
-    if (this._socket !== null && this._socket.open) {
-      return this._socket;
+    const open = this.openSockets()[0];
+    if (open !== void 0) {
+      return open;
     }
     if (this._connecting === null) {
-      this._connecting = this.openSocket().finally(() => this._connecting = null);
+      this._connecting = this.openSocket(true).finally(() => this._connecting = null);
     }
     return await this._connecting;
   }
-  async openSocket() {
+  /**
+   * The socket for the next job; the caller runs it in submission order. A live job goes on a socket
+   * of its own, an idle one or a new one, which `pipelineSockets` does not count. Any other job skips
+   * the sockets with a live source: a new one while every other socket has a source and fewer than
+   * `pipelineSockets` are open, else the one with room and the fewest sources.
+   */
+  async socketForJob(job) {
+    if (job.live) {
+      return this.openSockets().find((socket) => socket.held.size === 0) ?? await this.openSocket(true);
+    }
+    const sockets = this.openSockets().filter((socket) => socket.lives.size === 0);
+    if (sockets.length === 0) {
+      return await this.openSocket(true);
+    }
+    if (sockets.length < (this.ctx.options.pipelineSockets ?? PIPELINE_SOCKETS) && sockets.every((socket) => socket.held.size > 0) && Date.now() >= this._noExtraSocketUntil) {
+      try {
+        return await this.openSocket(false);
+      } catch (error) {
+        this._noExtraSocketUntil = Date.now() + EXTRA_SOCKET_RETRY_MS;
+        this.ctx.requestLogger.info("could not open another pipeline API socket: %s", error);
+      }
+    }
+    const rank = (socket) => (socket.hasRoom ? 0 : MAX_OPEN_SOURCES + 1) + socket.held.size;
+    return sockets.reduce((best, socket) => rank(socket) < rank(best) ? socket : best);
+  }
+  /** A new socket with the last pop set on it; `patient` waits through 503 with Retry-After. */
+  async openSocket(patient) {
     if (this.ctx.client() === null) {
       throw new PipelineSocketClosedError(void 0, "the endpoint is not connected");
     }
-    const ws = await this.upgrade(await this.socketUrl());
+    const ws = await this.upgrade(await this.socketUrl(), patient);
+    if (this._disconnecting) {
+      ws.close(1e3);
+      throw new PipelineSocketClosedError(void 0, "the endpoint disconnected");
+    }
     const socket = new PipelineSocket(ws);
     ws.onmessage = (event) => {
       if (typeof event.data === "string") {
@@ -11933,31 +11973,29 @@ var PipelineBackend = class {
     ws.onerror = () => {
     };
     ws.onclose = (event) => this.closed(socket, event.code, event.reason);
-    this._socket = socket;
-    this.startHeartbeat(ws);
+    this._sockets.push(socket);
+    this.startHeartbeat(socket);
     if (this._currentPop !== null) {
       try {
         await this.setPopOn(socket, this._currentPop);
       } catch (error) {
-        this._socket = null;
+        this._sockets = this._sockets.filter((other) => other !== socket);
         ws.close(1e3);
         throw error;
       }
     }
     return socket;
   }
-  startHeartbeat(ws) {
-    if (this._heartbeat !== null) {
-      clearInterval(this._heartbeat);
-    }
+  startHeartbeat(socket) {
+    const ws = socket.ws;
     const ping = ws.ping;
     if (typeof ping === "function") {
-      this._heartbeat = setInterval(() => {
+      socket.heartbeat = setInterval(() => {
         if (ws.readyState === 1) {
           ping.call(ws);
         }
       }, HEARTBEAT_MS);
-      this._heartbeat.unref?.();
+      socket.heartbeat.unref?.();
     }
   }
   async socketUrl() {
@@ -11995,7 +12033,7 @@ var PipelineBackend = class {
     return (await this.ctx.credentialHeader()).replace(/^Bearer /, "");
   }
   /** Open the socket, waiting through 503 with Retry-After and exchanging the API key again after a 401. */
-  async upgrade(url) {
+  async upgrade(url, patient) {
     const deadline = Date.now() + MAX_RETRY_MS;
     let rejected = false;
     while (true) {
@@ -12013,7 +12051,7 @@ var PipelineBackend = class {
           continue;
         }
         const wait = error.status === 503 && error.retryAfter !== void 0 ? Math.max(error.retryAfter, 1) * 1e3 : void 0;
-        if (wait === void 0 || Date.now() + wait > deadline) {
+        if (!patient || wait === void 0 || Date.now() + wait > deadline) {
           throw error;
         }
         this.ctx.requestLogger.info("the pipeline API answered 503, retrying in %d ms", wait);
@@ -12023,9 +12061,7 @@ var PipelineBackend = class {
   }
   closed(socket, code, reason) {
     socket.markClosed();
-    if (this._socket === socket) {
-      this._socket = null;
-    }
+    this._sockets = this._sockets.filter((other) => other !== socket);
     const error = new PipelineSocketClosedError(code, reason);
     socket.sources.forEach((source) => source.close(error));
     socket.commands.forEach((command) => command.reject(error));
@@ -12051,12 +12087,14 @@ var PipelineBackend = class {
     const source = typeof id === "string" ? socket.sources.get(id) : void 0;
     if (type === "end") {
       socket.held.delete(id);
+      socket.lives.delete(id);
       socket.accepted.delete(id);
       socket.freed();
     } else if (type === "result" && socket.held.has(id)) {
       socket.accepted.add(id);
     } else if (type === "error" && message["error"] !== "unknown_command") {
       socket.held.delete(id);
+      socket.lives.delete(id);
       socket.wake();
     }
     if (type === "send" || type === "credit") {
@@ -12098,6 +12136,10 @@ var PipelineBackend = class {
   command(socket, message) {
     const id = this.newId(message["type"]);
     return new Promise((resolve, reject) => {
+      if (!socket.open) {
+        reject(new PipelineSocketClosedError(void 0, "the socket closed"));
+        return;
+      }
       socket.commands.set(id, { resolve, reject });
       socket.sendJson({ ...message, id });
     });
@@ -12106,15 +12148,28 @@ var PipelineBackend = class {
   pop() {
     return this._currentPop;
   }
-  /** Set the pop on the socket's pipeline; a pop it refuses rejects, and the last pop it took stays. */
+  /**
+   * Set the pop on every open socket's pipeline; a pop the first refuses rejects, and the last pop it
+   * took stays. shortcut: a refusal from a later socket, which the first took, leaves the earlier ones
+   * on the new pop; a refusal is the pop's own fault, so every socket answers it alike.
+   */
   async changePop(pop) {
     if (this.ctx.client() === null) {
       this._currentPop = pop;
       return;
     }
     await this.inOrder(async () => {
-      if (this._socket !== null && this._socket.open) {
-        await this.setPopOn(this._socket, pop);
+      const sockets = this.openSockets();
+      if (sockets.length > 0) {
+        for (const socket of sockets) {
+          try {
+            await this.setPopOn(socket, pop);
+          } catch (error) {
+            if (!(error instanceof PipelineSocketClosedError)) {
+              throw error;
+            }
+          }
+        }
         this._currentPop = pop;
         return;
       }
@@ -12275,22 +12330,30 @@ var PipelineBackend = class {
   }
   /** Send the job's setSource; the caller runs it in submission order. */
   async setSource(job) {
-    if (job.cancelled) {
-      return null;
-    }
-    let socket = await this.ensureSocket();
-    await socket.room(job);
     if (job.cancelled) {
       return null;
     }
     const combined = await combinedMedia(job);
-    socket = await this.ensureSocket();
+    let socket;
+    while (true) {
+      socket = await this.socketForJob(job);
+      await socket.room(job);
+      if (job.cancelled) {
+        return null;
+      }
+      if (socket.open) {
+        break;
+      }
+    }
     const source = new OpenSource(this.newId("source"));
     if (combined === null) {
       uploadKeys(job).forEach((key) => source.uploads.set(key, new Credit()));
     }
     socket.sources.set(source.id, source);
     socket.held.add(source.id);
+    if (job.live) {
+      socket.lives.add(source.id);
+    }
     source.endedBefore = socket.ended;
     job.openSource = source;
     job.stopOnPipeline = () => {
@@ -12566,6 +12629,9 @@ var WorkerEndpoint = class extends Endpoint {
       if (options.jobQueueLength > MAX_OPEN_SOURCES) {
         throw new PipelineConfigurationError("job_queue_length", `jobQueueLength ${options.jobQueueLength} exceeds ${MAX_OPEN_SOURCES}, the open sources a pipeline API socket takes`);
       }
+      if (options.pipelineSockets !== void 0 && !(Number.isInteger(options.pipelineSockets) && options.pipelineSockets > 0)) {
+        throw new PipelineConfigurationError("pipeline_sockets", `pipelineSockets ${options.pipelineSockets} is not a positive whole number`);
+      }
     }
     super(options);
     const context = {
@@ -14541,6 +14607,7 @@ var index_default = EyePop;
   ModelType,
   MotionModel,
   PIPELINE_PATH,
+  PIPELINE_SOCKETS,
   PipelineBackend,
   PipelineCommandError,
   PipelineConfigurationError,