@nebulaos/llm-gateway 0.1.0 → 0.1.2

package/dist/index.js

@@ -30,18 +30,29 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  LLMGateway: () => LLMGateway
+  LLMGateway: () => LLMGateway,
+  LLMGatewayError: () => LLMGatewayError
 });
 module.exports = __toCommonJS(index_exports);
 var import_openai = __toESM(require("openai"));
 var import_node_crypto = require("crypto");
 var import_core = require("@nebulaos/core");
+var LLMGatewayError = class extends Error {
+  constructor(message, code, status, cause) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.cause = cause;
+    this.name = "LLMGatewayError";
+  }
+};
 var LLMGateway = class {
   providerName = "llm-gateway";
   modelName;
   client;
   baseUrl;
   logger;
+  options;
   capabilities = {
     inputFiles: {
       mimeTypes: ["image/*"],
@@ -58,58 +69,134 @@ var LLMGateway = class {
       baseURL,
       ...config.clientOptions
     });
+    this.options = config.options;
   }
   async generate(messages, tools, options) {
+    const mergedOptions = { ...this.options, ...options };
     const model = `route:${this.modelName}`;
-    const headers = this.buildGatewayHeaders();
-    this.logger.debug("LLM Gateway request", {
-      model,
-      baseUrl: this.baseUrl,
-      stream: false,
-      messageCount: messages.length,
-      toolCount: tools?.length ?? 0
-    });
-    try {
-      const response = await this.client.chat.completions.create(
-        {
+    const messagesPreview = messages.map((m) => ({
+      role: m.role,
+      content: typeof m.content === "string" ? m.content.length > 500 ? m.content.slice(0, 500) + "..." : m.content : Array.isArray(m.content) ? `[${m.content.length} parts]` : String(m.content)
+    }));
+    const toolsPreview = tools?.map((t) => ({
+      name: t.function.name,
+      description: t.function.description?.slice(0, 200)
+    }));
+    return import_core.Tracing.withSpan(
+      {
+        kind: "llm",
+        name: `llm:${this.modelName}`,
+        data: {
+          provider: this.providerName,
+          model: this.modelName,
+          messagesCount: messages.length,
+          toolsCount: tools?.length ?? 0,
+          responseFormat: mergedOptions?.responseFormat,
+          messages: messagesPreview,
+          tools: toolsPreview
+        }
+      },
+      async (llmSpan) => {
+        const headers = this.buildGatewayHeaders();
+        this.logger.debug("LLM Gateway request", {
           model,
-          messages: this.convertMessages(messages),
-          tools: this.convertTools(tools),
-          response_format: options?.responseFormat?.type === "json" ? options.responseFormat.schema ? {
-            type: "json_schema",
-            json_schema: { name: "response", schema: options.responseFormat.schema }
-          } : { type: "json_object" } : void 0,
-          ...this.extractExtraOptions(options)
-        },
-        { headers }
-      );
-      this.logger.debug("LLM Gateway response", {
-        model,
-        finishReason: response.choices?.[0]?.finish_reason,
-        hasUsage: Boolean(response.usage)
-      });
-      const choice = response.choices[0];
-      const message = choice.message;
-      return {
-        content: message.content || "",
-        toolCalls: message.tool_calls?.map((tc) => ({
-          id: tc.id,
-          type: "function",
-          function: {
-            name: tc.function.name,
-            arguments: tc.function.arguments
-          }
-        })),
-        finishReason: this.mapFinishReason(choice.finish_reason),
-        usage: this.mapUsage(response.usage)
-      };
-    } catch (error) {
-      this.logger.error("LLM Gateway request failed", error, void 0, void 0);
-      throw error;
-    }
+          baseUrl: this.baseUrl,
+          stream: false,
+          messageCount: messages.length,
+          toolCount: tools?.length ?? 0
+        });
+        try {
+          const { data: response, response: httpResponse } = await this.client.chat.completions.create(
+            {
+              model,
+              messages: this.convertMessages(messages),
+              tools: this.convertTools(tools),
+              response_format: mergedOptions?.responseFormat?.type === "json" ? mergedOptions.responseFormat.schema ? {
+                type: "json_schema",
+                json_schema: { name: "response", schema: mergedOptions.responseFormat.schema }
+              } : { type: "json_object" } : void 0,
+              ...this.extractExtraOptions(mergedOptions)
+            },
+            { headers }
+          ).withResponse();
+          this.logger.debug("LLM Gateway response", {
+            model,
+            finishReason: response.choices?.[0]?.finish_reason,
+            hasUsage: Boolean(response.usage)
+          });
+          const choice = response.choices[0];
+          const message = choice.message;
+          const usage = this.mapUsage(response.usage);
+          const finishReason = this.mapFinishReason(choice.finish_reason);
+          const enrichment = this.extractEnrichmentFromHeaders(httpResponse.headers);
+          await llmSpan.end({
+            status: "success",
+            data: {
+              usage: enrichment.usage ?? usage,
+              finishReason,
+              toolCallsCount: message.tool_calls?.length ?? 0,
+              outputPreview: message.content?.slice(0, 200),
+              // Enrichment from backend gateway
+              modelActual: enrichment.modelActual,
+              fallbackUsed: enrichment.fallbackUsed,
+              cost: enrichment.cost
+            }
+          });
+          return {
+            content: message.content || "",
+            toolCalls: message.tool_calls?.map((tc) => ({
+              id: tc.id,
+              type: "function",
+              function: {
+                name: tc.function.name,
+                arguments: tc.function.arguments
+              }
+            })),
+            finishReason,
+            usage: enrichment.usage ?? usage
+          };
+        } catch (error) {
+          this.logger.error("LLM Gateway request failed", error, void 0, void 0);
+          const gatewayError = this.handleError(error);
+          await llmSpan.end({
+            status: "error",
+            data: {
+              error: {
+                message: gatewayError.message,
+                code: gatewayError.code,
+                status: gatewayError.status
+              }
+            }
+          });
+          throw gatewayError;
+        }
+      }
+    );
   }
   async *generateStream(messages, tools, options) {
+    const mergedOptions = { ...this.options, ...options };
     const model = `route:${this.modelName}`;
+    const messagesPreview = messages.map((m) => ({
+      role: m.role,
+      content: typeof m.content === "string" ? m.content.length > 500 ? m.content.slice(0, 500) + "..." : m.content : Array.isArray(m.content) ? `[${m.content.length} parts]` : String(m.content)
+    }));
+    const toolsPreview = tools?.map((t) => ({
+      name: t.function.name,
+      description: t.function.description?.slice(0, 200)
+    }));
+    const llmSpan = await import_core.Tracing.startSpan({
+      kind: "llm",
+      name: `llm:${this.modelName}`,
+      data: {
+        provider: this.providerName,
+        model: this.modelName,
+        messagesCount: messages.length,
+        toolsCount: tools?.length ?? 0,
+        responseFormat: mergedOptions?.responseFormat,
+        messages: messagesPreview,
+        tools: toolsPreview
+      }
+    });
     const headers = this.buildGatewayHeaders();
     this.logger.debug("LLM Gateway stream request", {
       model,
@@ -127,43 +214,66 @@ var LLMGateway = class {
           tools: this.convertTools(tools),
           stream: true,
           stream_options: { include_usage: true },
-          response_format: options?.responseFormat?.type === "json" ? options.responseFormat.schema ? {
+          response_format: mergedOptions?.responseFormat?.type === "json" ? mergedOptions.responseFormat.schema ? {
             type: "json_schema",
-            json_schema: { name: "response", schema: options.responseFormat.schema }
+            json_schema: { name: "response", schema: mergedOptions.responseFormat.schema }
           } : { type: "json_object" } : void 0,
-          ...this.extractExtraOptions(options)
+          ...this.extractExtraOptions(mergedOptions)
         },
         { headers }
       );
     } catch (error) {
       this.logger.error("LLM Gateway stream request failed", error, void 0, void 0);
-      throw error;
+      const gatewayError = this.handleError(error);
+      if (llmSpan) {
+        await llmSpan.end({
+          status: "error",
+          data: {
+            error: {
+              message: gatewayError.message,
+              code: gatewayError.code,
+              status: gatewayError.status
+            }
+          }
+        });
+      }
+      throw gatewayError;
     }
+    let finalUsage;
+    let finalFinishReason;
+    let toolCallsCount = 0;
+    let outputPreview = "";
     try {
       for await (const chunk of stream) {
         if (chunk.usage) {
+          finalUsage = this.mapUsage(chunk.usage);
           yield {
             type: "finish",
             reason: "stop",
-            usage: this.mapUsage(chunk.usage)
+            usage: finalUsage
           };
         }
         const choice = chunk.choices?.[0];
         if (!choice) continue;
         if (choice.finish_reason) {
+          finalFinishReason = this.mapFinishReason(choice.finish_reason);
           yield {
             type: "finish",
-            reason: this.mapFinishReason(choice.finish_reason)
+            reason: finalFinishReason
           };
         }
         const delta = choice.delta;
         if (!delta) continue;
         if (delta.content) {
+          if (outputPreview.length < 200) {
+            outputPreview += delta.content.slice(0, 200 - outputPreview.length);
+          }
           yield { type: "content_delta", delta: delta.content };
         }
         if (delta.tool_calls) {
           for (const tc of delta.tool_calls) {
             if (tc.id && tc.function?.name) {
+              toolCallsCount++;
               yield {
                 type: "tool_call_start",
                 index: tc.index,
@@ -181,10 +291,199 @@ var LLMGateway = class {
           }
         }
       }
+      if (llmSpan) {
+        await llmSpan.end({
+          status: "success",
+          data: {
+            usage: finalUsage,
+            finishReason: finalFinishReason,
+            toolCallsCount,
+            outputPreview
+          }
+        });
+      }
     } catch (error) {
       this.logger.error("LLM Gateway stream failed", error, void 0, void 0);
-      throw error;
+      const gatewayError = this.handleError(error);
+      if (llmSpan) {
+        await llmSpan.end({
+          status: "error",
+          data: {
+            error: {
+              message: gatewayError.message,
+              code: gatewayError.code,
+              status: gatewayError.status
+            }
+          }
+        });
+      }
+      throw gatewayError;
+    }
+  }
+  // ==========================================================================
+  // Error Handling
+  // ==========================================================================
+  /**
+   * Transforms raw errors into actionable LLMGatewayError with clear messages.
+   * This ensures developers get specific guidance on how to resolve issues.
+   *
+   * Differentiates between:
+   * - Gateway errors: LLM Gateway API key issues (check NEBULAOS_API_KEY env var)
+   * - Provider errors: LLM provider API key issues (check route config in dashboard)
+   */
+  handleError(error) {
+    if (error instanceof import_openai.APIError) {
+      const status = error.status;
+      const originalMessage = error.message;
+      const errorSource = this.extractErrorSource(error);
+      if (status === 401) {
+        if (errorSource === "gateway") {
+          return new LLMGatewayError(
+            `LLM Gateway authentication failed: Your LLM Gateway API key is invalid or expired. Please verify your NEBULAOS_API_KEY environment variable or check your LLM Gateway API key in the NebulaOS dashboard. Original error: ${originalMessage}`,
+            "GATEWAY_AUTH_ERROR",
+            status,
+            error
+          );
+        } else {
+          return new LLMGatewayError(
+            `LLM Provider authentication failed: The API key configured for your LLM provider (OpenAI, Azure, etc.) is invalid or expired. Please verify the provider API key in your route configuration in the NebulaOS dashboard. Original error: ${originalMessage}`,
+            "PROVIDER_AUTH_ERROR",
+            status,
+            error
+          );
+        }
+      }
+      if (status === 403) {
+        if (errorSource === "gateway") {
+          return new LLMGatewayError(
+            `LLM Gateway access denied: Your LLM Gateway API key does not have permission to access this route. Please verify the route is allowed for your LLM Gateway API key in the NebulaOS dashboard. Original error: ${originalMessage}`,
+            "GATEWAY_FORBIDDEN",
+            status,
+            error
+          );
+        } else {
+          return new LLMGatewayError(
+            `LLM Provider access denied: The provider API key does not have permission for this operation. Please verify the provider API key permissions in the NebulaOS dashboard. Original error: ${originalMessage}`,
+            "PROVIDER_FORBIDDEN",
+            status,
+            error
+          );
+        }
+      }
+      if (status === 429) {
+        return new LLMGatewayError(
+          `LLM Gateway rate limit exceeded: Too many requests to the LLM provider. Please wait before retrying or check your rate limit configuration. Original error: ${originalMessage}`,
+          "LLM_GATEWAY_RATE_LIMIT",
+          status,
+          error
+        );
+      }
+      if (status === 400) {
+        return new LLMGatewayError(
+          `LLM Gateway request error: Invalid request parameters. Please check your request configuration (model, messages, tools). Original error: ${originalMessage}`,
+          "LLM_GATEWAY_BAD_REQUEST",
+          status,
+          error
+        );
+      }
+      if (status === 404) {
+        return new LLMGatewayError(
+          `LLM Gateway route not found: The specified model or route does not exist. Please verify the route alias '${this.modelName}' is correct and provisioned. Original error: ${originalMessage}`,
+          "LLM_GATEWAY_NOT_FOUND",
+          status,
+          error
+        );
+      }
+      if (status === 408 || status === 504) {
+        return new LLMGatewayError(
+          `LLM Gateway timeout: The request took too long to complete. This may be due to high load or a complex request. Please try again. Original error: ${originalMessage}`,
+          "LLM_GATEWAY_TIMEOUT",
+          status,
+          error
+        );
+      }
+      if (status && status >= 500) {
+        return new LLMGatewayError(
+          `LLM Gateway server error: The LLM provider returned an error (${status}). This is typically a temporary issue. Please try again later. Original error: ${originalMessage}`,
+          "LLM_GATEWAY_SERVER_ERROR",
+          status,
+          error
+        );
+      }
+      return new LLMGatewayError(
+        `LLM Gateway error (${status}): ${originalMessage}`,
+        "LLM_GATEWAY_ERROR",
+        status,
+        error
+      );
+    }
+    if (error instanceof Error) {
+      const msg = error.message.toLowerCase();
+      if (msg.includes("econnrefused") || msg.includes("enotfound") || msg.includes("network")) {
+        return new LLMGatewayError(
+          `LLM Gateway connection failed: Unable to connect to the LLM Gateway at ${this.baseUrl}. Please verify the gateway is running and accessible. Original error: ${error.message}`,
+          "LLM_GATEWAY_CONNECTION_ERROR",
+          void 0,
+          error
+        );
+      }
+      if (msg.includes("timeout") || msg.includes("timed out") || msg.includes("etimedout")) {
+        return new LLMGatewayError(
+          `LLM Gateway timeout: The connection timed out. Please check network connectivity and try again. Original error: ${error.message}`,
+          "LLM_GATEWAY_TIMEOUT",
+          void 0,
+          error
+        );
+      }
+      return new LLMGatewayError(
+        `LLM Gateway error: ${error.message}`,
+        "LLM_GATEWAY_ERROR",
+        void 0,
+        error
+      );
     }
+    return new LLMGatewayError(
+      `LLM Gateway error: An unexpected error occurred. Details: ${String(error)}`,
+      "LLM_GATEWAY_UNKNOWN_ERROR",
+      void 0,
+      error
+    );
+  }
+  /**
+   * Extracts the error source from an APIError.
+   * The backend sets X-Error-Source header or includes source in the error body
+   * to differentiate between gateway errors (LLM Gateway API key) and provider errors.
+   *
+   * @returns "gateway" if the error is from LLM Gateway authentication,
+   *          "provider" if the error is from the upstream LLM provider,
+   *          undefined if the source cannot be determined.
+   */
+  extractErrorSource(error) {
+    const headers = error.headers;
+    if (headers) {
+      const errorSource = headers["x-error-source"] || headers["X-Error-Source"];
+      if (errorSource === "gateway" || errorSource === "provider") {
+        return errorSource;
+      }
+    }
+    const errorBody = error.error;
+    if (errorBody && typeof errorBody === "object") {
+      const nestedError = errorBody.error;
+      if (nestedError && typeof nestedError === "object" && nestedError.source) {
+        const source = nestedError.source;
+        if (source === "gateway" || source === "provider") {
+          return source;
+        }
+      }
+      if (errorBody.source === "gateway" || errorBody.source === "provider") {
+        return errorBody.source;
+      }
+    }
+    const msg = error.message.toLowerCase();
+    if (msg.includes("llm gateway api key") || msg.includes("llm gateway")) {
+      return "gateway";
+    }
+    return void 0;
   }
   // ==========================================================================
   // Helpers (copied from OpenAI provider)
@@ -212,6 +511,46 @@ var LLMGateway = class {
     }
     return headers;
   }
+  /**
+   * Extracts enrichment data from backend HTTP headers.
+   * Backend returns this data so SDK can enrich its own span (avoiding duplicate spans).
+   */
+  extractEnrichmentFromHeaders(headers) {
+    const result = {};
+    const modelActual = headers.get("x-llm-model-actual");
+    if (modelActual) {
+      result.modelActual = modelActual;
+    }
+    const fallbackUsed = headers.get("x-llm-fallback-used");
+    if (fallbackUsed) {
+      result.fallbackUsed = fallbackUsed === "true";
+    }
+    const usageRaw = headers.get("x-llm-usage");
+    if (usageRaw) {
+      try {
+        const usage = JSON.parse(usageRaw);
+        result.usage = {
+          promptTokens: usage.prompt_tokens,
+          completionTokens: usage.completion_tokens,
+          totalTokens: usage.total_tokens,
+          reasoningTokens: usage.completion_tokens_details?.reasoning_tokens,
+          // Preserve any additional token fields from provider
+          ...usage
+        };
+      } catch {
+        this.logger.warn("Failed to parse x-llm-usage header", { usageRaw });
+      }
+    }
+    const cost = headers.get("x-llm-cost");
+    const costAvailable = headers.get("x-llm-cost-available");
+    if (cost) {
+      result.cost = {
+        amountUsd: cost,
+        available: costAvailable === "true"
+      };
+    }
+    return result;
+  }
   convertMessages(messages) {
     const allowedToolCallIds = /* @__PURE__ */ new Set();
     return messages.flatMap((m) => {
@@ -313,6 +652,7 @@ var LLMGateway = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  LLMGateway
+  LLMGateway,
+  LLMGatewayError
 });
 //# sourceMappingURL=index.js.map