@superlinked/sie-sdk 0.6.15 → 0.6.17
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +735 -5
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +450 -12
- package/dist/index.d.ts +450 -12
- package/dist/index.js +732 -6
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,153 @@
|
|
|
1
1
|
export { maxsim, maxsimBatch, maxsimDocuments } from './scoring.js';
|
|
2
2
|
|
|
3
|
+
/**
|
|
4
|
+
* Jobs surface (`client.jobs`) — pure helpers + wire types.
|
|
5
|
+
*
|
|
6
|
+
* The jobs API is the gateway's batch class. `client.jobs.submit(...)` binds to
|
|
7
|
+
* `POST /v1/jobs`; this module owns the transport-free pieces (the
|
|
8
|
+
* `source → operation → sink / when` slot mapping and result decoding) so they
|
|
9
|
+
* mirror the Python SDK's `sie_sdk.jobs`.
|
|
10
|
+
*/
|
|
11
|
+
/** Job lifecycle state (queued → running → terminal). */
|
|
12
|
+
type JobState = "queued" | "running" | "succeeded" | "failed" | "suspended" | "cancelled";
|
|
13
|
+
/** Terminal states with no further transitions (job lifecycle). */
|
|
14
|
+
declare const TERMINAL_JOB_STATES: ReadonlySet<JobState>;
|
|
15
|
+
/** One inline input item (the `/v1/encode` item contract: `{text}` / `{id,text}`). */
|
|
16
|
+
type JobItem = {
|
|
17
|
+
text?: string;
|
|
18
|
+
id?: string;
|
|
19
|
+
} & Record<string, unknown>;
|
|
20
|
+
/**
|
|
21
|
+
* A job source: inline items (a list, or a bare string = one text item) or a
|
|
22
|
+
* connector `scheme://<connection>/…` URI.
|
|
23
|
+
*/
|
|
24
|
+
type JobSource = string | Array<string | JobItem>;
|
|
25
|
+
/**
|
|
26
|
+
* The uniform source-mapping slots (wire-shaped, mirroring the Python
|
|
27
|
+
* SDK's dict): `id_field` ≈ `custom_id`, `input_field` ≈ `body.input`,
|
|
28
|
+
* `carry` = source fields echoed to the sink keyed by id, `input_type` pins
|
|
29
|
+
* the item shape. The sink slot rides separately as `outputField`. All
|
|
30
|
+
* optional — per-connector URI params stay as aliases.
|
|
31
|
+
*/
|
|
32
|
+
interface JobFieldMap {
|
|
33
|
+
id_field?: string;
|
|
34
|
+
input_field?: string;
|
|
35
|
+
carry?: string[];
|
|
36
|
+
input_type?: "text" | "document";
|
|
37
|
+
}
|
|
38
|
+
/** Options for `client.jobs.submit`. */
|
|
39
|
+
interface SubmitJobOptions {
|
|
40
|
+
/** Inline items or a connector URI (incl. `upload://<file-id>`). */
|
|
41
|
+
source: JobSource;
|
|
42
|
+
/** Model id (e.g. "BAAI/bge-m3"). */
|
|
43
|
+
model: string;
|
|
44
|
+
/** Job operation: encode | score | extract | parse | generate (default "encode"). */
|
|
45
|
+
operation?: string;
|
|
46
|
+
/** Sink: "return" (default), "inplace", or a connector URI. */
|
|
47
|
+
sink?: string | null;
|
|
48
|
+
/** Override the source connection name (default: derived from the URI). */
|
|
49
|
+
connection?: string | null;
|
|
50
|
+
/** Distinct connection name for the sink. */
|
|
51
|
+
sinkConnection?: string | null;
|
|
52
|
+
/** Uniform source mapping (connector jobs only). */
|
|
53
|
+
fieldMap?: JobFieldMap | null;
|
|
54
|
+
/** Sink target (≈ `response.body`; aliases PG `column` / object-store `suffix`). */
|
|
55
|
+
outputField?: string | null;
|
|
56
|
+
/** Trigger: "now" (default), "schedule:<cron>", or "watch:<source>". */
|
|
57
|
+
when?: string | null;
|
|
58
|
+
/** Encode output types (default: dense). */
|
|
59
|
+
outputTypes?: string[];
|
|
60
|
+
/**
|
|
61
|
+
* Per-item options plus the op inputs, forwarded as-is (operation
|
|
62
|
+
* matrix): score → `options.query`, extract → `options.labels` /
|
|
63
|
+
* `options.output_schema`, generate → sampling (e.g. `max_new_tokens`).
|
|
64
|
+
*/
|
|
65
|
+
options?: Record<string, unknown> | null;
|
|
66
|
+
}
|
|
67
|
+
/** The preflight reservation echoed on submit / status. */
|
|
68
|
+
interface JobPreflight {
|
|
69
|
+
estimated_credits?: number;
|
|
70
|
+
estimate_basis?: string;
|
|
71
|
+
}
|
|
72
|
+
/** One spawned chunk's settle metadata (`output.chunks[]`; results-as-refs). */
|
|
73
|
+
interface JobChunk {
|
|
74
|
+
seq?: number;
|
|
75
|
+
items?: number;
|
|
76
|
+
state?: string;
|
|
77
|
+
ref?: string | null;
|
|
78
|
+
units?: number | null;
|
|
79
|
+
credits?: number | null;
|
|
80
|
+
error?: unknown;
|
|
81
|
+
}
|
|
82
|
+
/** The `201` envelope from `POST /v1/jobs` (inline or connector job). */
|
|
83
|
+
interface JobSubmitResult {
|
|
84
|
+
id: string;
|
|
85
|
+
object: string;
|
|
86
|
+
operation: string;
|
|
87
|
+
model: string;
|
|
88
|
+
state: JobState;
|
|
89
|
+
total_items?: number;
|
|
90
|
+
chunks?: number;
|
|
91
|
+
preflight?: JobPreflight;
|
|
92
|
+
input_source?: string;
|
|
93
|
+
source?: string;
|
|
94
|
+
sink?: string;
|
|
95
|
+
}
|
|
96
|
+
/** A job's public status doc from `GET /v1/jobs/{id}` (refs, never payloads). */
|
|
97
|
+
interface JobStatus {
|
|
98
|
+
id: string;
|
|
99
|
+
object: string;
|
|
100
|
+
operation: string;
|
|
101
|
+
model: string;
|
|
102
|
+
state: JobState;
|
|
103
|
+
total_items?: number;
|
|
104
|
+
completed_items?: number;
|
|
105
|
+
preflight?: JobPreflight;
|
|
106
|
+
settled_credits?: number;
|
|
107
|
+
created_at?: number;
|
|
108
|
+
finished_at?: number | null;
|
|
109
|
+
output?: {
|
|
110
|
+
kind?: string;
|
|
111
|
+
chunks?: JobChunk[];
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
/** One decoded per-item result retrieved from a finished job's chunk refs. */
|
|
115
|
+
interface JobResultItem {
|
|
116
|
+
id: string | null;
|
|
117
|
+
success: boolean | null;
|
|
118
|
+
units: unknown;
|
|
119
|
+
dims: number | null;
|
|
120
|
+
dense: number[] | Float32Array | null;
|
|
121
|
+
}
|
|
122
|
+
/** A finished job's decoded results — the chunk refs read and unpacked. */
|
|
123
|
+
interface JobResults {
|
|
124
|
+
job_id: string;
|
|
125
|
+
state: JobState | undefined;
|
|
126
|
+
total_items: number | undefined;
|
|
127
|
+
settled_credits: number | undefined;
|
|
128
|
+
chunks: JobChunk[];
|
|
129
|
+
retrieved: number;
|
|
130
|
+
dims: number | null;
|
|
131
|
+
items: JobResultItem[];
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Derive a connection name from a connector URI's authority.
|
|
135
|
+
*
|
|
136
|
+
* `postgres://warehouse?query=…` → `warehouse`; `s3://customer-bucket/in/` →
|
|
137
|
+
* `customer-bucket`. Credentials never appear in the call — the job only names
|
|
138
|
+
* the connection; the runner resolves it org-scoped.
|
|
139
|
+
*/
|
|
140
|
+
declare function connectionName(uri: string): string;
|
|
141
|
+
/**
|
|
142
|
+
* Compose the `POST /v1/jobs` body from the source/op/sink/when slots.
|
|
143
|
+
*
|
|
144
|
+
* A thin, pure mapping: inline `items` or connector `src`/`sink` +
|
|
145
|
+
* connection name, plus an optional trigger. Only the fields that are set ride
|
|
146
|
+
* the wire, so an inline submit is byte-for-byte the realtime POC body and the
|
|
147
|
+
* connector body is additive (`/v1` additive-only rule).
|
|
148
|
+
*/
|
|
149
|
+
declare function buildJobBody(options: SubmitJobOptions): Record<string, unknown>;
|
|
150
|
+
|
|
3
151
|
/**
|
|
4
152
|
* Image handling utilities for the SIE TypeScript SDK.
|
|
5
153
|
*
|
|
@@ -333,10 +481,18 @@ interface WorkerInfo {
|
|
|
333
481
|
url: string;
|
|
334
482
|
/** GPU type (e.g., "l4", "a100-80gb") */
|
|
335
483
|
gpu: string;
|
|
484
|
+
/** Number of GPUs on this worker */
|
|
485
|
+
gpuCount: number;
|
|
486
|
+
/** Number of worker GPU slots ready to receive work */
|
|
487
|
+
readyGpuSlots: number;
|
|
336
488
|
/** Whether the worker is healthy */
|
|
337
489
|
healthy: boolean;
|
|
338
490
|
/** Number of items in the worker's queue */
|
|
339
491
|
queueDepth: number;
|
|
492
|
+
/** Worker-local scheduler pending cost */
|
|
493
|
+
pendingCost: number;
|
|
494
|
+
/** Number of batches currently executing on the worker */
|
|
495
|
+
inflightBatches: number;
|
|
340
496
|
/** List of model names loaded on this worker */
|
|
341
497
|
loadedModels: string[];
|
|
342
498
|
}
|
|
@@ -359,6 +515,26 @@ interface CapacityInfo {
|
|
|
359
515
|
/** List of worker details */
|
|
360
516
|
workers: WorkerInfo[];
|
|
361
517
|
}
|
|
518
|
+
/**
|
|
519
|
+
* Optional arguments for `SIEClient.createPool`, mirroring the Python SDK's
|
|
520
|
+
* `create_pool` keyword arguments (`bundle`, `minimum_worker_count`,
|
|
521
|
+
* `pinned_models`).
|
|
522
|
+
*/
|
|
523
|
+
interface CreatePoolOptions {
|
|
524
|
+
/** Optional bundle filter. When set, only workers running this bundle will be assigned to the pool. */
|
|
525
|
+
bundle?: string;
|
|
526
|
+
/**
|
|
527
|
+
* Per-pool warm floor (minimum machines kept warm). The gateway publishes
|
|
528
|
+
* it as `sie_gateway_pool_warm_floor` for KEDA. Defaults to 0 (scale to zero).
|
|
529
|
+
*/
|
|
530
|
+
minimumWorkerCount?: number;
|
|
531
|
+
/**
|
|
532
|
+
* Model ids to keep loaded so the first request to them pays no cold
|
|
533
|
+
* model-load. Each id must be a model the gateway already tracks and may be
|
|
534
|
+
* profile-qualified ("model-name:profile_name"); unknown ids are rejected.
|
|
535
|
+
*/
|
|
536
|
+
pinnedModels?: string[];
|
|
537
|
+
}
|
|
362
538
|
/**
|
|
363
539
|
* Pool specification returned by the gateway.
|
|
364
540
|
*/
|
|
@@ -408,7 +584,15 @@ interface PoolInfo {
|
|
|
408
584
|
/** Pool status */
|
|
409
585
|
status: PoolStatus;
|
|
410
586
|
}
|
|
411
|
-
|
|
587
|
+
/**
|
|
588
|
+
* Canonical model residency states. The runtime `MODEL_STATES` array is the
|
|
589
|
+
* single source the `ModelState` type is derived from, so it can be checked
|
|
590
|
+
* against the shared golden fixture (`packages/wire-fixtures/model_state.json`)
|
|
591
|
+
* in CI. Includes `"failed"` (a terminal load-failure state) to stay in parity
|
|
592
|
+
* with the Python SDK and server, which already carry it.
|
|
593
|
+
*/
|
|
594
|
+
declare const MODEL_STATES: readonly ["available", "loading", "loaded", "unloading", "failed"];
|
|
595
|
+
type ModelState = (typeof MODEL_STATES)[number];
|
|
412
596
|
interface ClusterSummary {
|
|
413
597
|
worker_count: number;
|
|
414
598
|
gpu_count: number;
|
|
@@ -497,10 +681,110 @@ interface SIEClientOptions {
|
|
|
497
681
|
gpu?: string;
|
|
498
682
|
/** API key for authentication (sent as Bearer token) */
|
|
499
683
|
apiKey?: string;
|
|
500
|
-
/**
|
|
684
|
+
/**
|
|
685
|
+
* Whether to auto-retry retryable capacity signals (503 PROVISIONING,
|
|
686
|
+
* idempotent 504 gateway timeouts, transient connect errors).
|
|
687
|
+
* Default: `true`, matching the Python SDK's `wait_for_capacity=True`.
|
|
688
|
+
* BREAKING (0.7): the default was previously `false` — pass `false`
|
|
689
|
+
* explicitly to fail fast.
|
|
690
|
+
*/
|
|
501
691
|
waitForCapacity?: boolean;
|
|
502
692
|
/** Maximum time to wait for provisioning in milliseconds (default: 300000) */
|
|
503
693
|
provisionTimeout?: number;
|
|
694
|
+
/**
|
|
695
|
+
* Control-plane base URL for the `connections` namespace (connector
|
|
696
|
+
* auth lives on the control plane, not the keyed gateway). Required to call
|
|
697
|
+
* `client.connections.*`.
|
|
698
|
+
*/
|
|
699
|
+
controlPlaneUrl?: string;
|
|
700
|
+
/** Org the `connections` namespace operates on (org-scoped by path in the POC). */
|
|
701
|
+
org?: string;
|
|
702
|
+
}
|
|
703
|
+
/**
|
|
704
|
+
* An org-scoped connection (connector auth by name). The secret is never
|
|
705
|
+
* returned by the list endpoint (only the job-runner resolve path sees it).
|
|
706
|
+
*/
|
|
707
|
+
interface Connection {
|
|
708
|
+
id?: number;
|
|
709
|
+
type?: string;
|
|
710
|
+
name?: string;
|
|
711
|
+
created_at?: number;
|
|
712
|
+
}
|
|
713
|
+
/** The `201` envelope from creating a connection (org + connection, no secret). */
|
|
714
|
+
interface ConnectionCreated extends Connection {
|
|
715
|
+
org?: string;
|
|
716
|
+
account_id?: number;
|
|
717
|
+
}
|
|
718
|
+
/** The envelope from revoking (soft-deleting) a connection. */
|
|
719
|
+
interface ConnectionRevoked {
|
|
720
|
+
org?: string;
|
|
721
|
+
account_id?: number;
|
|
722
|
+
name?: string;
|
|
723
|
+
state?: string;
|
|
724
|
+
}
|
|
725
|
+
/**
|
|
726
|
+
* An OpenAI-shaped file object (`POST/GET /v1/files`). The
|
|
727
|
+
* gateway emits `{id, object:"file", bytes, created_at, filename, purpose}`;
|
|
728
|
+
* `status` / `expires_at` are the optional OpenAI fields surfaced
|
|
729
|
+
* when the TTL-GC lands. Byte-for-byte OpenAI's `FileObject`.
|
|
730
|
+
*/
|
|
731
|
+
interface File {
|
|
732
|
+
id?: string;
|
|
733
|
+
object?: string;
|
|
734
|
+
bytes?: number;
|
|
735
|
+
created_at?: number;
|
|
736
|
+
filename?: string;
|
|
737
|
+
purpose?: string;
|
|
738
|
+
status?: string;
|
|
739
|
+
expires_at?: number;
|
|
740
|
+
}
|
|
741
|
+
/** The envelope from deleting a file (OpenAI `FileDeleted`). */
|
|
742
|
+
interface FileDeleted {
|
|
743
|
+
id?: string;
|
|
744
|
+
object?: string;
|
|
745
|
+
deleted?: boolean;
|
|
746
|
+
}
|
|
747
|
+
/** Per-batch request tally (OpenAI `request_counts`). */
|
|
748
|
+
interface BatchRequestCounts {
|
|
749
|
+
total?: number;
|
|
750
|
+
completed?: number;
|
|
751
|
+
failed?: number;
|
|
752
|
+
}
|
|
753
|
+
/**
|
|
754
|
+
* An OpenAI-shaped batch object (`POST/GET /v1/batches`).
|
|
755
|
+
* The gateway emits `{id, object:"batch", endpoint, input_file_id,
|
|
756
|
+
* completion_window, status, output_file_id, error_file_id, created_at,
|
|
757
|
+
* finished_at, request_counts, errors}`. The granular OpenAI
|
|
758
|
+
* timestamps (`completed_at` etc.) are optional — a strict OpenAI SDK reads them
|
|
759
|
+
* when the gateway surfaces them.
|
|
760
|
+
*/
|
|
761
|
+
interface Batch {
|
|
762
|
+
id?: string;
|
|
763
|
+
object?: string;
|
|
764
|
+
endpoint?: string;
|
|
765
|
+
input_file_id?: string;
|
|
766
|
+
completion_window?: string;
|
|
767
|
+
status?: string;
|
|
768
|
+
output_file_id?: string | null;
|
|
769
|
+
error_file_id?: string | null;
|
|
770
|
+
created_at?: number;
|
|
771
|
+
finished_at?: number | null;
|
|
772
|
+
in_progress_at?: number | null;
|
|
773
|
+
completed_at?: number | null;
|
|
774
|
+
failed_at?: number | null;
|
|
775
|
+
expired_at?: number | null;
|
|
776
|
+
cancelled_at?: number | null;
|
|
777
|
+
request_counts?: BatchRequestCounts;
|
|
778
|
+
errors?: unknown;
|
|
779
|
+
metadata?: Record<string, unknown> | null;
|
|
780
|
+
}
|
|
781
|
+
/** The listing envelope from `GET /v1/batches` (OpenAI cursor page). */
|
|
782
|
+
interface BatchList {
|
|
783
|
+
object?: string;
|
|
784
|
+
data?: Batch[];
|
|
785
|
+
first_id?: string;
|
|
786
|
+
last_id?: string;
|
|
787
|
+
has_more?: boolean;
|
|
504
788
|
}
|
|
505
789
|
/**
|
|
506
790
|
* Options for encode operation.
|
|
@@ -821,11 +1105,11 @@ interface ChatCompletionChunk {
|
|
|
821
1105
|
interface ChatCompletionOptions {
|
|
822
1106
|
/**
|
|
823
1107
|
* When `true`, retry the SAFE pre-execution capacity signals
|
|
824
|
-
* (`503 PROVISIONING`, `503 MODEL_LOADING`)
|
|
825
|
-
* `provisionTimeoutMs` elapses. When `false`, the first
|
|
826
|
-
* throws (`ProvisioningError` / `ModelLoadingError`
|
|
827
|
-
* Defaults to the client's `waitForCapacity`
|
|
828
|
-
* constructor opted
|
|
1108
|
+
* (`503 PROVISIONING`, `503 MODEL_LOADING`, `503 RESOURCE_EXHAUSTED`)
|
|
1109
|
+
* until `provisionTimeoutMs` elapses. When `false`, the first
|
|
1110
|
+
* provisioning signal throws (`ProvisioningError` / `ModelLoadingError`
|
|
1111
|
+
* / `ServerError`). Defaults to the client's `waitForCapacity`
|
|
1112
|
+
* (true unless the constructor opted out).
|
|
829
1113
|
*/
|
|
830
1114
|
waitForCapacity?: boolean;
|
|
831
1115
|
/**
|
|
@@ -919,6 +1203,84 @@ declare function toFloat32Array(arr: number[]): Float32Array;
|
|
|
919
1203
|
* ```
|
|
920
1204
|
*/
|
|
921
1205
|
|
|
1206
|
+
/** The `client.jobs` batch namespace. */
|
|
1207
|
+
interface JobsNamespace {
|
|
1208
|
+
/** Submit a batch job (`POST /v1/jobs`); returns the created-job envelope. */
|
|
1209
|
+
submit(options: SubmitJobOptions): Promise<JobSubmitResult>;
|
|
1210
|
+
/** Fetch a job's public status doc (`GET /v1/jobs/{id}`). */
|
|
1211
|
+
get(jobId: string): Promise<JobStatus>;
|
|
1212
|
+
/** List the org's jobs (`GET /v1/jobs`; scoped to the key's org). */
|
|
1213
|
+
list(): Promise<JobStatus[]>;
|
|
1214
|
+
/** Cancel a job (`POST /v1/jobs/{id}/cancel`); the hold's remainder releases. */
|
|
1215
|
+
cancel(jobId: string): Promise<JobStatus>;
|
|
1216
|
+
/** Retrieve a finished job's chunk refs and decode the per-item results. */
|
|
1217
|
+
results(jobId: string): Promise<JobResults>;
|
|
1218
|
+
/**
|
|
1219
|
+
* Poll `get` until the job reaches a terminal state, then return its status.
|
|
1220
|
+
* Throws a `job_wait_timeout` `RequestError` if `timeoutMs` elapses first.
|
|
1221
|
+
* Mirrors the Python SDK's `jobs.wait` (default 600s timeout, 2s poll).
|
|
1222
|
+
*/
|
|
1223
|
+
wait(jobId: string, options?: {
|
|
1224
|
+
timeoutMs?: number;
|
|
1225
|
+
pollMs?: number;
|
|
1226
|
+
}): Promise<JobStatus>;
|
|
1227
|
+
}
|
|
1228
|
+
/** The `client.connections` namespace (org-scoped connector auth). */
|
|
1229
|
+
interface ConnectionsNamespace {
|
|
1230
|
+
/** Create an org-scoped connection (connector auth by name). */
|
|
1231
|
+
add(name: string, type: string, secret: string): Promise<ConnectionCreated>;
|
|
1232
|
+
/** List the org's active connections (secrets redacted). */
|
|
1233
|
+
list(): Promise<Connection[]>;
|
|
1234
|
+
/** Revoke (soft-delete) a connection; frees the name for reuse. */
|
|
1235
|
+
revoke(name: string): Promise<ConnectionRevoked>;
|
|
1236
|
+
}
|
|
1237
|
+
/** Accepted upload payloads — the same shapes `fetch` sends as a body. */
|
|
1238
|
+
type FileUploadInput = Uint8Array | ArrayBuffer | string | Blob;
|
|
1239
|
+
/**
|
|
1240
|
+
* The `client.files` OpenAI-compatible Files namespace. Method
|
|
1241
|
+
* names/args mirror `openai.files` so an `openai` → `sie-sdk` swap is mechanical.
|
|
1242
|
+
*/
|
|
1243
|
+
interface FilesNamespace {
|
|
1244
|
+
/** Upload a file (`POST /v1/files`); `purpose` defaults to `"batch"`. */
|
|
1245
|
+
upload(file: FileUploadInput, options?: {
|
|
1246
|
+
purpose?: string;
|
|
1247
|
+
filename?: string;
|
|
1248
|
+
}): Promise<File>;
|
|
1249
|
+
/** OpenAI-exact alias for {@link upload} (`files.create({ file, purpose })`). */
|
|
1250
|
+
create(options: {
|
|
1251
|
+
file: FileUploadInput;
|
|
1252
|
+
purpose?: string;
|
|
1253
|
+
filename?: string;
|
|
1254
|
+
}): Promise<File>;
|
|
1255
|
+
/** Fetch a file's metadata (`GET /v1/files/{id}`). */
|
|
1256
|
+
retrieve(fileId: string): Promise<File>;
|
|
1257
|
+
/** Download a file's raw bytes (`GET /v1/files/{id}/content`). */
|
|
1258
|
+
content(fileId: string): Promise<Uint8Array>;
|
|
1259
|
+
/** Delete a file (`DELETE /v1/files/{id}`; additive OpenAI-parity surface). */
|
|
1260
|
+
delete(fileId: string): Promise<FileDeleted>;
|
|
1261
|
+
}
|
|
1262
|
+
/**
|
|
1263
|
+
* The `client.batches` OpenAI-compatible Batch namespace. A
|
|
1264
|
+
* batch is a job over an uploaded file's JSONL lines;
|
|
1265
|
+
* `list` / `cancel` are the additive OpenAI-parity completion of the surface.
|
|
1266
|
+
* Args are OpenAI's exact snake_case body keys, so an `openai` → `sie-sdk` swap
|
|
1267
|
+
* is mechanical.
|
|
1268
|
+
*/
|
|
1269
|
+
interface BatchesNamespace {
|
|
1270
|
+
/** Create a batch (`POST /v1/batches`); returns the Batch object. */
|
|
1271
|
+
create(options: {
|
|
1272
|
+
input_file_id: string;
|
|
1273
|
+
endpoint?: string;
|
|
1274
|
+
completion_window?: string;
|
|
1275
|
+
metadata?: Record<string, unknown>;
|
|
1276
|
+
}): Promise<Batch>;
|
|
1277
|
+
/** Fetch a batch's status (`GET /v1/batches/{id}`). */
|
|
1278
|
+
retrieve(batchId: string): Promise<Batch>;
|
|
1279
|
+
/** List the org's batches (`GET /v1/batches`; additive OpenAI-parity). */
|
|
1280
|
+
list(): Promise<Batch[]>;
|
|
1281
|
+
/** Cancel a batch (`POST /v1/batches/{id}/cancel`; additive OpenAI-parity). */
|
|
1282
|
+
cancel(batchId: string): Promise<Batch>;
|
|
1283
|
+
}
|
|
922
1284
|
/**
|
|
923
1285
|
* SIE Client for embedding, scoring, and extraction.
|
|
924
1286
|
*
|
|
@@ -951,6 +1313,16 @@ declare class SIEClient {
|
|
|
951
1313
|
private readonly apiKey?;
|
|
952
1314
|
private readonly defaultWaitForCapacity;
|
|
953
1315
|
private readonly provisionTimeout;
|
|
1316
|
+
private readonly controlPlaneUrl?;
|
|
1317
|
+
private readonly org?;
|
|
1318
|
+
/** Batch class — `POST/GET /v1/jobs` on the keyed gateway. */
|
|
1319
|
+
readonly jobs: JobsNamespace;
|
|
1320
|
+
/** Org-scoped connections (connector auth by name) on the control plane. */
|
|
1321
|
+
readonly connections: ConnectionsNamespace;
|
|
1322
|
+
/** OpenAI-compatible Files API — `POST/GET /v1/files`. */
|
|
1323
|
+
readonly files: FilesNamespace;
|
|
1324
|
+
/** OpenAI-compatible Batch API — `POST/GET /v1/batches`. */
|
|
1325
|
+
readonly batches: BatchesNamespace;
|
|
954
1326
|
private readonly pools;
|
|
955
1327
|
private versionWarningLogged;
|
|
956
1328
|
/**
|
|
@@ -1189,8 +1561,10 @@ declare class SIEClient {
|
|
|
1189
1561
|
* generator throws it instead of yielding the chunk.
|
|
1190
1562
|
*
|
|
1191
1563
|
* Retry policy mirrors {@link generate}: only explicit SAFE
|
|
1192
|
-
* pre-execution capacity signals — `503 PROVISIONING
|
|
1193
|
-
* `503 MODEL_LOADING`
|
|
1564
|
+
* pre-execution capacity signals — `503 PROVISIONING`,
|
|
1565
|
+
* `503 MODEL_LOADING` and `503 RESOURCE_EXHAUSTED` (the latter only
|
|
1566
|
+
* under `waitForCapacity`) — are retried while the provision budget
|
|
1567
|
+
* remains; a `504` is post-publish and therefore terminal.
|
|
1194
1568
|
* Once the body opens we never retry (the call is non-idempotent; a
|
|
1195
1569
|
* mid-stream failure must not re-issue generation).
|
|
1196
1570
|
*
|
|
@@ -1242,12 +1616,21 @@ declare class SIEClient {
|
|
|
1242
1616
|
* @param gpus - Optional machine profile requirements for pool readiness, e.g., { "l4": 2, "l4-spot": 1 }
|
|
1243
1617
|
* @param gpuCaps - Optional maximum assigned workers per machine profile
|
|
1244
1618
|
* @param queuePool - Optional Helm/NATS queue namespace backing this logical pool. Defaults to "default".
|
|
1619
|
+
* @param options - Optional bundle filter, warm floor, and pinned models
|
|
1620
|
+
* (Python SDK `create_pool` parity)
|
|
1245
1621
|
*
|
|
1246
1622
|
* @example
|
|
1247
1623
|
* ```typescript
|
|
1248
1624
|
* // Create or update a pool with 2 L4 GPUs
|
|
1249
1625
|
* await client.createPool("eval-bench", { l4: 2 });
|
|
1250
1626
|
*
|
|
1627
|
+
* // With a bundle filter, warm floor, and pinned models
|
|
1628
|
+
* await client.createPool("eval-bench", { l4: 2 }, undefined, undefined, {
|
|
1629
|
+
* bundle: "default",
|
|
1630
|
+
* minimumWorkerCount: 1,
|
|
1631
|
+
* pinnedModels: ["bge-m3"],
|
|
1632
|
+
* });
|
|
1633
|
+
*
|
|
1251
1634
|
* // Use the pool for requests
|
|
1252
1635
|
* await client.encode("bge-m3", { text: "Hello" }, { gpu: "eval-bench/l4" });
|
|
1253
1636
|
*
|
|
@@ -1255,7 +1638,7 @@ declare class SIEClient {
|
|
|
1255
1638
|
* await client.deletePool("eval-bench");
|
|
1256
1639
|
* ```
|
|
1257
1640
|
*/
|
|
1258
|
-
createPool(name: string, gpus?: Record<string, number>, gpuCaps?: Record<string, number>, queuePool?: string): Promise<void>;
|
|
1641
|
+
createPool(name: string, gpus?: Record<string, number>, gpuCaps?: Record<string, number>, queuePool?: string, options?: CreatePoolOptions): Promise<void>;
|
|
1259
1642
|
/**
|
|
1260
1643
|
* Get information about a pool.
|
|
1261
1644
|
*
|
|
@@ -1348,6 +1731,11 @@ declare class SIEClient {
|
|
|
1348
1731
|
* Retried (capped by `provisionTimeout`):
|
|
1349
1732
|
* - 503 `PROVISIONING` when `waitForCapacity: true`
|
|
1350
1733
|
* - 503 `MODEL_LOADING` / `LORA_LOADING`
|
|
1734
|
+
* - 503 `RESOURCE_EXHAUSTED` regardless of `waitForCapacity` (bounded
|
|
1735
|
+
* exponential backoff, at most `RESOURCE_EXHAUSTED_MAX_RETRIES`)
|
|
1736
|
+
* - 504 gateway timeout when `waitForCapacity: true` — encode/score/
|
|
1737
|
+
* extract are idempotent queue paths, so a post-publish retry is safe
|
|
1738
|
+
* (unlike generate/chat, where a 504 is terminal)
|
|
1351
1739
|
* - `SIEConnectionError` with `kind === "connect"` (issue #95)
|
|
1352
1740
|
*
|
|
1353
1741
|
* `kind === "timeout"` is NOT retried — would extend the user-visible
|
|
@@ -1363,12 +1751,38 @@ declare class SIEClient {
|
|
|
1363
1751
|
* Used for endpoints that return JSON (e.g., /v1/models, /health).
|
|
1364
1752
|
*/
|
|
1365
1753
|
private requestJson;
|
|
1754
|
+
/** One JSON request over `fetch` (bearer auth reused; absolute or base-relative URL). */
|
|
1755
|
+
private jsonRequest;
|
|
1756
|
+
private jobSubmit;
|
|
1757
|
+
private jobGet;
|
|
1758
|
+
private jobList;
|
|
1759
|
+
private jobCancel;
|
|
1760
|
+
private jobResults;
|
|
1761
|
+
private jobWait;
|
|
1762
|
+
/** Retrieve a chunk's payload-store ref (http(s) URL). */
|
|
1763
|
+
private readRef;
|
|
1764
|
+
private connectionsBase;
|
|
1765
|
+
private connectionAdd;
|
|
1766
|
+
private connectionList;
|
|
1767
|
+
private connectionRevoke;
|
|
1768
|
+
/** POST a raw body and parse the JSON response (bearer auth reused). */
|
|
1769
|
+
private rawPostJson;
|
|
1770
|
+
/** GET raw bytes (bearer auth reused); used to download a file's content. */
|
|
1771
|
+
private rawGetBytes;
|
|
1772
|
+
private fileUpload;
|
|
1773
|
+
private fileRetrieve;
|
|
1774
|
+
private fileContent;
|
|
1775
|
+
private fileDelete;
|
|
1776
|
+
private batchCreate;
|
|
1777
|
+
private batchRetrieve;
|
|
1778
|
+
private batchList;
|
|
1779
|
+
private batchCancel;
|
|
1366
1780
|
private buildWsUrl;
|
|
1367
1781
|
private createWebSocket;
|
|
1368
1782
|
private detectEndpointType;
|
|
1369
1783
|
}
|
|
1370
1784
|
|
|
1371
|
-
declare const SDK_VERSION = "0.6.
|
|
1785
|
+
declare const SDK_VERSION = "0.6.17";
|
|
1372
1786
|
|
|
1373
1787
|
/**
|
|
1374
1788
|
* Helpers for converting SIE encode results to plain JavaScript types.
|
|
@@ -1584,6 +1998,30 @@ declare class ModelLoadingError extends SIEError {
|
|
|
1584
1998
|
readonly model: string | undefined;
|
|
1585
1999
|
constructor(message: string, model?: string);
|
|
1586
2000
|
}
|
|
2001
|
+
/**
|
|
2002
|
+
* Error when the server has exhausted its OOM-recovery strategies.
|
|
2003
|
+
*
|
|
2004
|
+
* Raised when:
|
|
2005
|
+
* - Server returns 503 with RESOURCE_EXHAUSTED code
|
|
2006
|
+
* - SDK retry limit is exceeded (or the next backoff would exhaust the
|
|
2007
|
+
* provision-timeout budget)
|
|
2008
|
+
*
|
|
2009
|
+
* Subclass of {@link ServerError} so callers that already catch
|
|
2010
|
+
* `ServerError` continue to behave correctly; new code can catch
|
|
2011
|
+
* `ResourceExhaustedError` specifically to react to sustained GPU
|
|
2012
|
+
* pressure (e.g., back off, route elsewhere, scale up). Mirrors the
|
|
2013
|
+
* Python SDK's `ResourceExhaustedError`.
|
|
2014
|
+
*/
|
|
2015
|
+
declare class ResourceExhaustedError extends ServerError {
|
|
2016
|
+
/** The model that was requested */
|
|
2017
|
+
readonly model: string | undefined;
|
|
2018
|
+
/** Number of retry attempts made before giving up */
|
|
2019
|
+
readonly retries: number;
|
|
2020
|
+
constructor(message: string, options?: {
|
|
2021
|
+
model?: string;
|
|
2022
|
+
retries?: number;
|
|
2023
|
+
});
|
|
2024
|
+
}
|
|
1587
2025
|
/**
|
|
1588
2026
|
* Error surfaced mid-stream from `streamChatCompletions` / `streamGenerate`.
|
|
1589
2027
|
*
|
|
@@ -1689,4 +2127,4 @@ declare function packMessage(data: unknown): Uint8Array;
|
|
|
1689
2127
|
*/
|
|
1690
2128
|
declare function unpackMessage<T = unknown>(data: Uint8Array): T;
|
|
1691
2129
|
|
|
1692
|
-
export { type CapacityInfo, type ChatChoice, type ChatChunkChoice, type ChatCompletion, type ChatCompletionChunk, type ChatCompletionRequest, type ChatDelta, type ChatFinishReason, type ChatMessage, type ChatUsage, type Classification, type ClusterStatusMessage, type ClusterSummary, type ClusterWorkerInfo, type DType, type DetectedObject, type EncodeOptions, type EncodeResult, type Entity, type ExtractOptions, type ExtractResult, type FinishReason, type GPUMetrics, type GenerateChunk, type GenerateOptions, type GenerateResult, type GenerationUsage, type ImageInput, type ImageWireFormat, InputTooLongError, type Item, LoraLoadingError, type ModelCapabilities, type ModelConfig, type ModelDims, type ModelInfo, ModelLoadFailedError, ModelLoadingError, type ModelState, type ModelStatus, type ModelSummary, type OutputType, PoolError, type PoolInfo, type PoolSpec, type PoolStatus, ProvisioningError, type Relation, RequestError, type ResponseFormat, SDK_VERSION, SIEClient, type SIEClientOptions, SIEConnectionError, SIEError, SIEStreamError, type ScoreEntry, type ScoreOptions, type ScoreResult, ServerError, type ServerInfo, type SparseResult, type SparseVector, type StatusMessage, type TimingInfo, type ToolCall, type ToolCallDelta, type ToolChoice, type ToolSpec, type WorkerInfo, type WorkerStatusMessage, denseEmbedding, detectImageFormat, multivectorEmbedding, normalizeSparseVector, packMessage, sparseEmbedding, sparseEmbeddingMap, toFloat32Array, toImageBytes, toImageWireFormat, toNumberArray, unpackMessage };
|
|
2130
|
+
export { type Batch, type BatchList, type BatchRequestCounts, type BatchesNamespace, type CapacityInfo, type ChatChoice, type ChatChunkChoice, type ChatCompletion, type ChatCompletionChunk, type ChatCompletionRequest, type ChatDelta, type ChatFinishReason, type ChatMessage, type ChatUsage, type Classification, type ClusterStatusMessage, type ClusterSummary, type ClusterWorkerInfo, type Connection, type ConnectionCreated, type ConnectionRevoked, type ConnectionsNamespace, type CreatePoolOptions, type DType, type DetectedObject, type EncodeOptions, type EncodeResult, type Entity, type ExtractOptions, type ExtractResult, type FileDeleted, type FileUploadInput, type FilesNamespace, type FinishReason, type GPUMetrics, type GenerateChunk, type GenerateOptions, type GenerateResult, type GenerationUsage, type ImageInput, type ImageWireFormat, InputTooLongError, type Item, type JobChunk, type JobFieldMap, type JobItem, type JobPreflight, type JobResultItem, type JobResults, type JobSource, type JobState, type JobStatus, type JobSubmitResult, type JobsNamespace, LoraLoadingError, type ModelCapabilities, type ModelConfig, type ModelDims, type ModelInfo, ModelLoadFailedError, ModelLoadingError, type ModelState, type ModelStatus, type ModelSummary, type OutputType, PoolError, type PoolInfo, type PoolSpec, type PoolStatus, ProvisioningError, type Relation, RequestError, ResourceExhaustedError, type ResponseFormat, SDK_VERSION, SIEClient, type SIEClientOptions, SIEConnectionError, SIEError, type File as SIEFile, SIEStreamError, type ScoreEntry, type ScoreOptions, type ScoreResult, ServerError, type ServerInfo, type SparseResult, type SparseVector, type StatusMessage, type SubmitJobOptions, TERMINAL_JOB_STATES, type TimingInfo, type ToolCall, type ToolCallDelta, type ToolChoice, type ToolSpec, type WorkerInfo, type WorkerStatusMessage, buildJobBody, connectionName, denseEmbedding, detectImageFormat, multivectorEmbedding, normalizeSparseVector, packMessage, sparseEmbedding, sparseEmbeddingMap, toFloat32Array, toImageBytes, toImageWireFormat, toNumberArray, unpackMessage };
|