@superlinked/sie-sdk 0.3.4 → 0.4.0

package/dist/index.cjs

@@ -87,6 +87,21 @@ var ModelLoadingError = class extends SIEError {
     this.model = model;
   }
 };
+var SIEStreamError = class extends SIEError {
+  /** SIE-native error code (e.g. `context_exceeded`, `cancelled`). */
+  code;
+  /** OpenAI-style error type (e.g. `context_length_exceeded`, `server_error`). */
+  errorType;
+  /** Offending field name when known (chat shape only). */
+  param;
+  constructor(message, options) {
+    super(message);
+    this.name = "SIEStreamError";
+    this.code = options?.code;
+    this.errorType = options?.errorType;
+    this.param = options?.param;
+  }
+};
 var ModelLoadFailedError = class extends ServerError {
   /** The model that was requested */
   model;
@@ -326,7 +341,7 @@ function unpackMessage(data) {
 function getRetryAfter(header) {
   if (!header) return void 0;
   const seconds = Number.parseInt(header, 10);
-  if (!Number.isNaN(seconds) && seconds > 0) {
+  if (!Number.isNaN(seconds) && seconds >= 0) {
     return seconds * 1e3;
   }
   const date = new Date(header);
@@ -525,6 +540,41 @@ function parseExtractResult(data) {
 function parseExtractResults(data) {
   return data.map(parseExtractResult);
 }
+function describeType(value) {
+  if (value === null) return "null";
+  return typeof value;
+}
+function coerceTokenCount(v) {
+  return typeof v === "number" && Number.isFinite(v) ? Math.trunc(v) : 0;
+}
+function parseGenerateResult(data) {
+  const wire = data;
+  if (typeof wire.model !== "string") {
+    throw new RequestError(
+      `Generate response missing string 'model' field: got ${describeType(wire.model)}`
+    );
+  }
+  if (typeof wire.text !== "string") {
+    throw new RequestError(
+      `Generate response missing string 'text' field: got ${describeType(wire.text)}`
+    );
+  }
+  const usage = wire.usage ?? {};
+  const finish = wire.finish_reason ?? "stop";
+  return {
+    model: wire.model,
+    text: wire.text,
+    finishReason: finish,
+    usage: {
+      promptTokens: coerceTokenCount(usage.prompt_tokens),
+      completionTokens: coerceTokenCount(usage.completion_tokens),
+      totalTokens: coerceTokenCount(usage.total_tokens)
+    },
+    attemptId: wire.attempt_id,
+    ttftMs: wire.ttft_ms,
+    tpotMs: wire.tpot_ms
+  };
+}
 function parseCapacityInfo(data, gpuFilter) {
   const wire = data;
   let workers = wire.workers ?? [];
@@ -550,11 +600,208 @@ function parseCapacityInfo(data, gpuFilter) {
   };
 }
 
+// src/internal/provisioning.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withProvisioningRetry(performFetch, opts) {
+  const startTime = Date.now();
+  while (true) {
+    const response = await performFetch();
+    if (response.status === HTTP_ACCEPTED) {
+      if (!opts.waitForCapacity) {
+        throw new ProvisioningError(
+          "No capacity available. Server is provisioning.",
+          opts.gpu,
+          getRetryAfter2(response)
+        );
+      }
+      const elapsed = Date.now() - startTime;
+      if (elapsed >= opts.provisionTimeoutMs) {
+        throw new ProvisioningError(
+          `Provisioning timeout after ${elapsed}ms`,
+          opts.gpu,
+          getRetryAfter2(response)
+        );
+      }
+      const delay = getRetryAfter2(response) ?? DEFAULT_RETRY_DELAY;
+      await sleep(Math.min(delay, opts.provisionTimeoutMs - elapsed));
+      continue;
+    }
+    await throwIfModelLoadFailed(response, opts.model);
+    if (response.status === 503) {
+      const errorCode = await getErrorCode(response.clone());
+      if (errorCode === MODEL_LOADING_ERROR_CODE) {
+        const elapsed = Date.now() - startTime;
+        if (elapsed >= opts.provisionTimeoutMs) {
+          throw new ModelLoadingError(`Model loading timeout for '${opts.model}'`, opts.model);
+        }
+        const delay = getRetryAfter2(response) ?? MODEL_LOADING_DEFAULT_DELAY;
+        await sleep(Math.min(delay, opts.provisionTimeoutMs - elapsed));
+        continue;
+      }
+      if (opts.waitForCapacity) {
+        const elapsed = Date.now() - startTime;
+        if (elapsed < opts.provisionTimeoutMs) {
+          const delay = getRetryAfter2(response) ?? DEFAULT_RETRY_DELAY;
+          await sleep(Math.min(delay, opts.provisionTimeoutMs - elapsed));
+          continue;
+        }
+      }
+    }
+    if (!response.ok) {
+      await handleError(response);
+    }
+    if (response.status !== 200) {
+      throw new RequestError(`Unexpected response status ${response.status}`);
+    }
+    return response;
+  }
+}
+
+// src/sse.ts
+var SSE_DONE = "[DONE]";
+var MAX_SSE_BUFFER_CHARS = 8 * 1024 * 1024;
+async function* parseSseStream(reader, signal) {
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  let completedCleanly = false;
+  const onAbort = () => {
+    reader.cancel().catch(() => {
+    });
+  };
+  if (signal) {
+    if (signal.aborted) {
+      throw new SIEConnectionError("Stream aborted before first read", "other");
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  }
+  try {
+    while (true) {
+      if (signal?.aborted) {
+        throw new SIEConnectionError("Stream aborted by caller", "other");
+      }
+      let result;
+      try {
+        if (signal) {
+          if (signal.aborted) {
+            throw new SIEConnectionError("Stream aborted by caller", "other");
+          }
+          result = await new Promise((resolve, reject) => {
+            let settled = false;
+            const onAbortRace = () => {
+              if (settled) return;
+              settled = true;
+              signal.removeEventListener("abort", onAbortRace);
+              reject(new SIEConnectionError("Stream aborted by caller", "other"));
+            };
+            signal.addEventListener("abort", onAbortRace, { once: true });
+            reader.read().then(
+              (r) => {
+                if (settled) return;
+                settled = true;
+                signal.removeEventListener("abort", onAbortRace);
+                resolve(r);
+              },
+              (err) => {
+                if (settled) return;
+                settled = true;
+                signal.removeEventListener("abort", onAbortRace);
+                reject(err);
+              }
+            );
+          });
+        } else {
+          result = await reader.read();
+        }
+      } catch (err) {
+        if (err instanceof SIEConnectionError) throw err;
+        if (signal?.aborted) {
+          throw new SIEConnectionError("Stream aborted by caller", "other");
+        }
+        throw err;
+      }
+      if (result.done) {
+        buffer += decoder.decode();
+        break;
+      }
+      buffer += decoder.decode(result.value, { stream: true });
+      if (buffer.length > MAX_SSE_BUFFER_CHARS) {
+        throw new SIEStreamError(
+          `SSE event buffer exceeded ${MAX_SSE_BUFFER_CHARS} chars without an event terminator`
+        );
+      }
+      let sepIdx;
+      while (true) {
+        const lfIdx = buffer.indexOf("\n\n");
+        const crlfIdx = buffer.indexOf("\r\n\r\n");
+        if (lfIdx === -1 && crlfIdx === -1) break;
+        let sepLen = 2;
+        if (lfIdx === -1) {
+          sepIdx = crlfIdx;
+          sepLen = 4;
+        } else if (crlfIdx === -1) {
+          sepIdx = lfIdx;
+        } else {
+          if (lfIdx < crlfIdx) {
+            sepIdx = lfIdx;
+          } else {
+            sepIdx = crlfIdx;
+            sepLen = 4;
+          }
+        }
+        const eventBlock = buffer.slice(0, sepIdx);
+        buffer = buffer.slice(sepIdx + sepLen);
+        const payload = extractDataPayload(eventBlock);
+        if (payload === null) continue;
+        if (payload === SSE_DONE) {
+          completedCleanly = true;
+          return;
+        }
+        yield payload;
+      }
+    }
+    const tail = buffer.replace(/\r?\n$/, "");
+    if (tail !== "") {
+      const payload = extractDataPayload(tail);
+      if (payload !== null && payload !== SSE_DONE) {
+        yield payload;
+      }
+    }
+    completedCleanly = true;
+  } finally {
+    if (signal) signal.removeEventListener("abort", onAbort);
+    if (completedCleanly) {
+      try {
+        reader.releaseLock();
+      } catch {
+      }
+    } else {
+      await reader.cancel().catch(() => {
+      });
+    }
+  }
+}
+function extractDataPayload(block) {
+  const lines = block.split(/\r?\n/);
+  const parts = [];
+  for (const line of lines) {
+    if (line === "" || line.startsWith(":")) continue;
+    if (line.startsWith("data:")) {
+      let value = line.slice(5);
+      if (value.startsWith(" ")) value = value.slice(1);
+      parts.push(value);
+    }
+  }
+  if (parts.length === 0) return null;
+  return parts.join("\n");
+}
+
 // src/version.ts
-var SDK_VERSION = "0.3.4";
+var SDK_VERSION = "0.4.0";
 
 // src/client.ts
-function sleep(ms) {
+function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function abortableSleep(ms, signal) {
@@ -572,6 +819,19 @@ function abortableSleep(ms, signal) {
   });
 }
 var _LEASE_RENEWAL_MAX_RETRIES = 5;
+function extractChatChunkError(chunk) {
+  const err = chunk.error;
+  if (!err) return null;
+  return new SIEStreamError(err.message ?? "stream error", {
+    code: err.code,
+    errorType: err.type,
+    param: err.param
+  });
+}
+function extractGenerateChunkError(chunk) {
+  if (!chunk.error) return null;
+  return new SIEStreamError(chunk.error.message, { code: chunk.error.code });
+}
 var SIEClient = class {
   baseUrl;
   timeout;
@@ -791,6 +1051,427 @@ var SIEClient = class {
    * console.log(result.scores[0].itemId); // most relevant
    * ```
    */
+  /**
+   * Generate text from a prompt (walking-skeleton SDK surface).
+   *
+   * The SDK does not currently expose streaming chunks. The worker streams
+   * to the gateway, the gateway aggregates, and the SDK returns the
+   * assembled result plus SIE-native timing metadata (TTFT, TPOT,
+   * attempt id).
+   *
+   * @example
+   * ```typescript
+   * const result = await client.generate(
+   *   "Qwen__Qwen3-4B-Instruct-2507",
+   *   "Write a haiku about the sea.",
+   *   { maxNewTokens: 64, temperature: 0.7 },
+   * );
+   * console.log(result.text);
+   * console.log(`TTFT: ${result.ttftMs}ms`);
+   * ```
+   */
+  async generate(model, prompt, options) {
+    const body = {
+      prompt,
+      max_new_tokens: options.maxNewTokens,
+      temperature: options.temperature ?? 1,
+      top_p: options.topP ?? 1
+    };
+    if (options.stop !== void 0) {
+      body.stop = options.stop;
+    }
+    const { pool, gpu } = this.parseGpuParam(options.gpu);
+    const headers = {
+      Accept: "application/json",
+      "Content-Type": JSON_CONTENT_TYPE,
+      [SDK_VERSION_HEADER]: SDK_VERSION
+    };
+    if (pool) headers["X-SIE-Pool"] = pool;
+    if (gpu) headers["X-SIE-MACHINE-PROFILE"] = gpu;
+    if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+    const safeModel = model.replaceAll("/", "__");
+    const url = `${this.baseUrl}/v1/generate/${encodeURIComponent(safeModel)}`;
+    const waitForCapacity = options.waitForCapacity ?? this.defaultWaitForCapacity;
+    const response = await withProvisioningRetry(() => this.performJsonPost(url, body, headers), {
+      model,
+      gpu,
+      waitForCapacity,
+      provisionTimeoutMs: this.provisionTimeout
+    });
+    const data = await response.json();
+    if (data === null || typeof data !== "object") {
+      throw new RequestError("Unexpected generate response shape");
+    }
+    return parseGenerateResult(data);
+  }
+  /**
+   * Per-attempt JSON POST used by the non-streaming surfaces
+   * ({@link generate}, {@link chatCompletions}) inside the
+   * {@link withProvisioningRetry} loop.
+   *
+   * Translates low-level transport failures into typed errors that the
+   * retry loop will surface verbatim:
+   *   - `AbortError` → `SIEConnectionError` (per-attempt timeout)
+   *   - `TypeError`  → `SIEConnectionError` (NOT retried — generation is
+   *     non-idempotent, so a mid-flight drop must surface instead of
+   *     silently re-issuing a billable generation)
+   *
+   * Each call uses a fresh `AbortController` so concurrent retries don't
+   * share state, and the per-attempt timeout is bounded by `this.timeout`
+   * (NOT the cumulative provisioning budget).
+   */
+  async performJsonPost(url, body, headers) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new SIEConnectionError(`Request timeout after ${this.timeout}ms`, "timeout");
+      }
+      if (err instanceof TypeError) {
+        throw new SIEConnectionError(`Connection failed: ${err.message}`, "connect");
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Non-streaming chat-completion call against `/v1/chat/completions`.
+   *
+   * This is the OpenAI-compatible surface. The request body is forwarded
+   * verbatim as JSON, so any field documented at
+   * <https://platform.openai.com/docs/api-reference/chat/create> can be set;
+   * the gateway will reject fields it does not yet support with
+   * `400 unsupported_field`. SIE-native routing hints (`routing_key`,
+   * `prompt_cache_key`) are part of the same request shape.
+   *
+   * Error semantics mirror `generate()`: 4xx → `RequestError`, 5xx →
+   * `ServerError` (or the more specific `ModelLoadFailedError` for 502
+   * `MODEL_LOAD_FAILED`), connection / timeout failures →
+   * `SIEConnectionError`.
+   *
+   * If `req.stream === true`, this method throws `RequestError` immediately —
+   * use {@link streamChatCompletions} instead. We do not auto-route because
+   * the return type is fundamentally different (`Promise` vs
+   * `AsyncGenerator`) and silently flipping would mis-type the call site.
+   *
+   * @example
+   * ```typescript
+   * const reply = await client.chatCompletions({
+   *   model: "Qwen/Qwen3-4B-Instruct-2507",
+   *   messages: [{ role: "user", content: "Write a haiku about the sea." }],
+   *   max_completion_tokens: 64,
+   * });
+   * console.log(reply.choices[0]?.message.content);
+   * ```
+   */
+  async chatCompletions(req, options = {}) {
+    if (req.stream === true) {
+      throw new RequestError(
+        "chatCompletions() cannot be used with stream:true \u2014 use streamChatCompletions() instead.",
+        "invalid_request",
+        400
+      );
+    }
+    const body = { ...req, stream: false };
+    const url = `${this.baseUrl}/v1/chat/completions`;
+    const headers = this.buildChatHeaders("application/json");
+    const waitForCapacity = options.waitForCapacity ?? this.defaultWaitForCapacity;
+    const provisionTimeoutMs = options.provisionTimeoutMs ?? this.provisionTimeout;
+    const response = await withProvisioningRetry(() => this.performJsonPost(url, body, headers), {
+      model: req.model,
+      gpu: void 0,
+      waitForCapacity,
+      provisionTimeoutMs
+    });
+    this.checkServerVersion(response);
+    const data = await response.json();
+    if (data === null || typeof data !== "object") {
+      throw new RequestError("Unexpected chat.completion response shape");
+    }
+    return data;
+  }
+  /**
+   * Streaming chat-completion call against `/v1/chat/completions` with
+   * `Accept: text/event-stream`.
+   *
+   * Yields `ChatCompletionChunk` events in the order the gateway emits them.
+   * The terminal chunk carries `finish_reason`; if
+   * `req.stream_options.include_usage === true`, a final usage-only chunk
+   * (`choices: []`, populated `usage`) follows it. The generator completes
+   * cleanly on the `data: [DONE]` sentinel.
+   *
+   * Error semantics:
+   *
+   *   - HTTP 4xx / 5xx **before** the stream opens → throws `RequestError` /
+   *     `ServerError` (same as {@link chatCompletions}).
+   *   - A chunk containing `error: { ... }` mid-stream → throws
+   *     {@link SIEStreamError}. The error chunk is consumed, never yielded.
+   *   - `signal.abort()` mid-stream → the generator throws
+   *     `SIEConnectionError` and releases the underlying reader, which
+   *     fires `StreamCancelGuard` on the gateway side.
+   *
+   * `req.stream` is set to `true` automatically; any existing value is
+   * overwritten. We do not validate `req.stream === false` because the
+   * call-site intent is unambiguous.
+   *
+   * @param req     The chat-completion request. See {@link ChatCompletionRequest}.
+   * @param signal  Optional `AbortSignal` for cooperative cancellation.
+   *
+   * @example
+   * ```typescript
+   * const controller = new AbortController();
+   * try {
+   *   for await (const chunk of client.streamChatCompletions(
+   *     {
+   *       model: "Qwen/Qwen3-4B-Instruct-2507",
+   *       messages: [{ role: "user", content: "Count to ten." }],
+   *       stream_options: { include_usage: true },
+   *     },
+   *     controller.signal,
+   *   )) {
+   *     process.stdout.write(chunk.choices[0]?.delta.content ?? "");
+   *   }
+   * } catch (err) {
+   *   if (err instanceof SIEStreamError) {
+   *     console.error(`mid-stream error: ${err.code} — ${err.message}`);
+   *   } else throw err;
+   * }
+   * ```
+   */
+  async *streamChatCompletions(req, signal) {
+    const body = { ...req, stream: true };
+    const url = `${this.baseUrl}/v1/chat/completions`;
+    yield* this.consumeSseStream(
+      url,
+      body,
+      req.model,
+      signal,
+      (chunk) => extractChatChunkError(chunk)
+    );
+  }
+  /**
+   * Streaming companion to {@link generate} — opens an SSE connection to
+   * `/v1/generate/{model}` with `stream: true` and yields the SIE-native
+   * chunk shape documented in
+   * `packages/sie_gateway/src/handlers/sse.rs::build_generate_chunk_event`.
+   *
+   * The first delta carries `seq: 0` and `text_delta` populated; the
+   * terminal chunk has `done: true`, `finish_reason`, and (typically)
+   * `usage` + `ttft_ms`. The generator completes on the `data: [DONE]`
+   * sentinel.
+   *
+   * Error semantics match {@link streamChatCompletions}: pre-stream HTTP
+   * errors throw normally, mid-stream `error` chunks throw
+   * {@link SIEStreamError}.
+   *
+   * @example
+   * ```typescript
+   * for await (const chunk of client.streamGenerate(
+   *   "Qwen/Qwen3-4B-Instruct-2507",
+   *   "Write a haiku.",
+   *   { maxNewTokens: 64, temperature: 0.7 },
+   * )) {
+   *   process.stdout.write(chunk.text_delta);
+   *   if (chunk.done) console.log(`\nTTFT: ${chunk.ttft_ms}ms`);
+   * }
+   * ```
+   */
+  async *streamGenerate(model, prompt, options, signal) {
+    const body = {
+      prompt,
+      max_new_tokens: options.maxNewTokens,
+      temperature: options.temperature ?? 1,
+      top_p: options.topP ?? 1,
+      stream: true
+    };
+    if (options.stop !== void 0) body.stop = options.stop;
+    const safeModel = model.replaceAll("/", "__");
+    const url = `${this.baseUrl}/v1/generate/${encodeURIComponent(safeModel)}`;
+    const { pool, gpu } = this.parseGpuParam(options.gpu);
+    const waitForCapacity = options.waitForCapacity ?? this.defaultWaitForCapacity;
+    yield* this.consumeSseStream(
+      url,
+      body,
+      model,
+      signal,
+      (chunk) => extractGenerateChunkError(chunk),
+      { pool, gpu },
+      { waitForCapacity }
+    );
+  }
+  /**
+   * Shared SSE consumption helper for the streaming methods.
+   *
+   * Performs a pre-stream provisioning retry loop (honoring
+   * `waitForCapacity`/`provisionTimeout`), surfaces pre-stream errors via
+   * {@link handleError} (so callers see the same `RequestError` /
+   * `ServerError` hierarchy as the non-streaming endpoints), then iterates
+   * the SSE payloads via {@link parseSseStream}. Each payload is JSON-parsed;
+   * if the consumer-supplied `extractError` returns an `SIEStreamError`, the
+   * generator throws it instead of yielding the chunk.
+   *
+   * Retry policy mirrors {@link generate}: only the SAFE pre-execution
+   * capacity signals — `202` (provisioning) and `503 MODEL_LOADING` — are
+   * retried, and only while `waitForCapacity` is set and the provision
+   * budget remains. Once the body opens we never retry (the call is
+   * non-idempotent; a mid-stream failure must not re-issue generation).
+   *
+   * @internal
+   */
+  async *consumeSseStream(url, body, model, signal, extractError, routing, provisioning) {
+    const headers = this.buildChatHeaders("text/event-stream");
+    if (routing?.pool) headers["X-SIE-Pool"] = routing.pool;
+    if (routing?.gpu) headers["X-SIE-MACHINE-PROFILE"] = routing.gpu;
+    const waitForCapacity = provisioning?.waitForCapacity ?? this.defaultWaitForCapacity;
+    const gpu = routing?.gpu;
+    const controller = new AbortController();
+    const onCallerAbort = () => controller.abort();
+    if (signal) {
+      if (signal.aborted) {
+        throw new SIEConnectionError("Stream aborted before request", "other");
+      }
+      signal.addEventListener("abort", onCallerAbort, { once: true });
+    }
+    try {
+      const startTime = Date.now();
+      let response;
+      while (true) {
+        if (signal?.aborted) {
+          throw new SIEConnectionError("Stream aborted before request", "other");
+        }
+        const preStreamTimeoutId = setTimeout(() => controller.abort(), this.timeout);
+        let attemptResponse;
+        try {
+          attemptResponse = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal
+          });
+        } catch (error) {
+          if (signal?.aborted) {
+            throw new SIEConnectionError("Stream aborted before response", "other");
+          }
+          if (error instanceof Error && error.name === "AbortError") {
+            throw new SIEConnectionError(`Stream open timeout after ${this.timeout}ms`, "timeout");
+          }
+          if (error instanceof TypeError) {
+            throw new SIEConnectionError(`Connection failed: ${error.message}`, "connect");
+          }
+          throw error;
+        } finally {
+          clearTimeout(preStreamTimeoutId);
+        }
+        if (attemptResponse.status === HTTP_ACCEPTED) {
+          if (!waitForCapacity) {
+            throw new ProvisioningError(
+              "No capacity available. Server is provisioning.",
+              gpu,
+              getRetryAfter2(attemptResponse)
+            );
+          }
+          const elapsed = Date.now() - startTime;
+          if (elapsed >= this.provisionTimeout) {
+            throw new ProvisioningError(
+              `Provisioning timeout after ${elapsed}ms`,
+              gpu,
+              getRetryAfter2(attemptResponse)
+            );
+          }
+          const delay = getRetryAfter2(attemptResponse) ?? DEFAULT_RETRY_DELAY;
+          if (await abortableSleep(
+            Math.min(delay, this.provisionTimeout - elapsed),
+            controller.signal
+          )) {
+            throw new SIEConnectionError("Stream aborted while provisioning", "other");
+          }
+          continue;
+        }
+        await throwIfModelLoadFailed(attemptResponse, model);
+        if (attemptResponse.status === 503) {
+          const errorCode = await getErrorCode(attemptResponse.clone());
+          if (errorCode === MODEL_LOADING_ERROR_CODE && waitForCapacity) {
+            const elapsed = Date.now() - startTime;
+            if (elapsed >= this.provisionTimeout) {
+              throw new ModelLoadingError(`Model loading timeout for '${model}'`, model);
+            }
+            const delay = getRetryAfter2(attemptResponse) ?? MODEL_LOADING_DEFAULT_DELAY;
+            if (await abortableSleep(
+              Math.min(delay, this.provisionTimeout - elapsed),
+              controller.signal
+            )) {
+              throw new SIEConnectionError("Stream aborted while provisioning", "other");
+            }
+            continue;
+          }
+          if (waitForCapacity) {
+            const elapsed = Date.now() - startTime;
+            if (elapsed < this.provisionTimeout) {
+              const delay = getRetryAfter2(attemptResponse) ?? DEFAULT_RETRY_DELAY;
+              if (await abortableSleep(
+                Math.min(delay, this.provisionTimeout - elapsed),
+                controller.signal
+              )) {
+                throw new SIEConnectionError("Stream aborted while provisioning", "other");
+              }
+              continue;
+            }
+          }
+        }
+        if (attemptResponse.status !== 200) {
+          await handleError(attemptResponse);
+        }
+        response = attemptResponse;
+        break;
+      }
+      if (!response) {
+        throw new RequestError("Streaming request failed without producing a response");
+      }
+      this.checkServerVersion(response);
+      const bodyStream = response.body;
+      if (!bodyStream) {
+        throw new RequestError("Streaming response has no body");
+      }
+      const reader = bodyStream.getReader();
+      for await (const payload of parseSseStream(reader, signal ?? controller.signal)) {
+        let chunk;
+        try {
+          chunk = JSON.parse(payload);
+        } catch (err) {
+          throw new RequestError(
+            `Failed to parse SSE chunk as JSON: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+        const streamErr = extractError(chunk);
+        if (streamErr) throw streamErr;
+        yield chunk;
+      }
+    } finally {
+      if (signal) signal.removeEventListener("abort", onCallerAbort);
+    }
+  }
+  /**
+   * Build the standard JSON header set for the chat-completions surface.
+   * Pulled out so both the streaming and non-streaming paths agree on
+   * auth / version / content-type wiring.
+   */
+  buildChatHeaders(accept) {
+    const headers = {
+      Accept: accept,
+      "Content-Type": JSON_CONTENT_TYPE,
+      [SDK_VERSION_HEADER]: SDK_VERSION
+    };
+    if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+    return headers;
+  }
   async score(model, query, items, options = {}) {
     const body = {
       query,
@@ -882,17 +1563,18 @@ var SIEClient = class {
     this.pools.clear();
   }
   /**
-   * Create a resource pool for isolated capacity.
+   * Create or update a resource pool for isolated capacity.
    *
    * Pools provide dedicated worker capacity, isolated from other clients.
    * Workers are assigned to pools and only serve requests from that pool.
    *
    * @param name - Pool name (used in GPU param as "poolName/machineProfile")
-   * @param gpus - Machine profile requirements, e.g., { "l4": 2, "l4-spot": 1 }
+   * @param gpus - Optional machine profile requirements for pool readiness, e.g., { "l4": 2, "l4-spot": 1 }
+   * @param gpuCaps - Optional maximum assigned workers per machine profile
    *
    * @example
    * ```typescript
-   * // Create a pool with 2 L4 GPUs
+   * // Create or update a pool with 2 L4 GPUs
    * await client.createPool("eval-bench", { l4: 2 });
    *
    * // Use the pool for requests
@@ -902,11 +1584,17 @@ var SIEClient = class {
    * await client.deletePool("eval-bench");
    * ```
    */
-  async createPool(name, gpus) {
-    if (this.pools.has(name)) {
-      return;
+  async createPool(name, gpus, gpuCaps) {
+    const alreadyTracking = this.pools.has(name);
+    const requestBody = {
+      name
+    };
+    if (gpus !== void 0) {
+      requestBody.gpus = gpus;
+    }
+    if (gpuCaps) {
+      requestBody.gpu_caps = gpuCaps;
     }
-    const requestBody = { name, gpus };
     const url = `${this.baseUrl}/v1/pools`;
     const headers = {
       "Content-Type": JSON_CONTENT_TYPE,
@@ -934,6 +1622,9 @@ var SIEClient = class {
         }
         throw new PoolError(`Failed to create pool '${name}': ${errorMsg}`, name);
       }
+      if (alreadyTracking || this.pools.has(name)) {
+        return;
+      }
       const abortController = new AbortController();
       const poolState = {
         timeoutId: null,
@@ -965,7 +1656,7 @@ var SIEClient = class {
                 signal: perAttempt.signal
               });
               if (resp.ok) break;
-            } catch (error) {
+            } catch {
               if (abortController.signal.aborted) return;
             } finally {
               clearTimeout(attemptTimeout);
@@ -1202,7 +1893,7 @@ var SIEClient = class {
       }
       const remaining = timeout - elapsed;
       const delay = Math.min(pollInterval, remaining);
-      await sleep(delay);
+      await sleep2(delay);
     }
   }
   /**
@@ -1229,7 +1920,7 @@ var SIEClient = class {
           if (elapsed < this.provisionTimeout) {
             const remaining = this.provisionTimeout - elapsed;
             const delay = Math.min(DEFAULT_RETRY_DELAY, remaining);
-            await sleep(delay);
+            await sleep2(delay);
             continue;
           }
         }
@@ -1255,7 +1946,7 @@ var SIEClient = class {
         const delay = retryAfter ?? DEFAULT_RETRY_DELAY;
         const remaining = this.provisionTimeout - elapsed;
         const actualDelay = Math.min(delay, remaining);
-        await sleep(actualDelay);
+        await sleep2(actualDelay);
         continue;
       }
       await throwIfModelLoadFailed(response, model);
@@ -1275,7 +1966,7 @@ var SIEClient = class {
           }
           const retryAfter = getRetryAfter2(response);
           const delay = retryAfter ?? LORA_LOADING_DEFAULT_DELAY;
-          await sleep(delay);
+          await sleep2(delay);
           continue;
         }
         if (errorCode === MODEL_LOADING_ERROR_CODE) {
@@ -1290,7 +1981,7 @@ var SIEClient = class {
           const delay = retryAfter ?? MODEL_LOADING_DEFAULT_DELAY;
           const remaining = this.provisionTimeout - elapsed;
           const actualDelay = Math.min(delay, remaining);
-          await sleep(actualDelay);
+          await sleep2(actualDelay);
           continue;
         }
         if (waitForCapacity) {
@@ -1300,7 +1991,7 @@ var SIEClient = class {
             const delay = retryAfter ?? DEFAULT_RETRY_DELAY;
             const remaining = this.provisionTimeout - elapsed;
             const actualDelay = Math.min(delay, remaining);
-            await sleep(actualDelay);
+            await sleep2(actualDelay);
             continue;
           }
         }
@@ -1592,6 +2283,7 @@ exports.SDK_VERSION = SDK_VERSION;
 exports.SIEClient = SIEClient;
 exports.SIEConnectionError = SIEConnectionError;
 exports.SIEError = SIEError;
+exports.SIEStreamError = SIEStreamError;
 exports.ServerError = ServerError;
 exports.denseEmbedding = denseEmbedding;
 exports.detectImageFormat = detectImageFormat;