@nebulaos/llm-gateway 0.1.0 → 0.1.1

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present, iamkun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,21 +12,27 @@ npm install @nebulaos/llm-gateway
 
 ```typescript
 import { LLMGateway } from "@nebulaos/llm-gateway";
-import { Agent } from "@nebulaos/core";
+import { Agent, BufferMemory } from "@nebulaos/core";
 
 const agent = new Agent({
+  id: "assistente",
   name: "assistente",
   model: new LLMGateway({
-    apiKey: "your-nebula-api-key",
+    apiKey: process.env.NEBULAOS_API_KEY,
     baseUrl: "https://your-nebula-instance.com",
     model: "assistente", // Route alias configured in NebulaOS
-    logLevel: "debug",
+    options: {
+      reasoning_effort: "high",  // Enable deep reasoning (Gemini)
+      temperature: 0.7,
+    },
   }),
+  memory: new BufferMemory(),
   instructions: "You are a helpful assistant.",
 });
 
 // Use the agent
-const response = await agent.generate("Hello, how can I help you?");
+const result = await agent.execute("Analyze this complex problem step by step");
+console.log(result.content);
 ```
 
 ## Configuration
@@ -37,6 +43,50 @@ const response = await agent.generate("Hello, how can I help you?");
 | `baseUrl` | `string` | No | NebulaOS instance URL (defaults to localhost:4100) |
 | `model` | `string` | Yes | Route alias configured in NebulaOS |
 | `logLevel` | `string` | No | Logger verbosity ("debug", "info", "warn", "error", "none") |
+| `options` | `object` | No | Default model options for every call (see below) |
+
+## Model Options
+
+Use `options` to configure model-specific parameters that apply to every call:
+
+```typescript
+const model = new LLMGateway({
+  apiKey: "your-api-key",
+  model: "minha-rota",
+  options: {
+    temperature: 0.7,
+    reasoning_effort: "high",  // Gemini 2.5+/3+ via LiteLLM
+    topK: 40,
+  }
+});
+```
+
+### Common Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `temperature` | `number` | Sampling temperature (0-2) |
+| `topP` | `number` | Nucleus sampling |
+| `topK` | `number` | Top-K sampling (Gemini) |
+| `maxTokens` | `number` | Max output tokens |
+
+### Provider-Specific Options
+
+These are passed directly to the provider via LiteLLM:
+
+**Gemini (via LiteLLM)**:
+| Option | Values | Description |
+|--------|--------|-------------|
+| `reasoning_effort` | `"low"`, `"medium"`, `"high"` | Controls thinking depth (Gemini 2.5+/3+) |
+| `thinking` | `{ type: "enabled", budget_tokens: N }` | Fine-grained thinking control |
+
+**OpenAI**:
+| Option | Type | Description |
+|--------|------|-------------|
+| `frequency_penalty` | `number` | Reduce repetition (-2 to 2) |
+| `presence_penalty` | `number` | Encourage new topics (-2 to 2) |
+
+Any extra options are passed through to the underlying provider.
 
 ## Routes
 

package/dist/index.d.mts

@@ -1,6 +1,16 @@
 import OpenAIClient, { ClientOptions } from 'openai';
-import { LogLevel, IModel, Message, ToolDefinitionForLLM, GenerateOptions, ProviderResponse, StreamChunk } from '@nebulaos/core';
+import { LogLevel, GenerateOptions, IModel, Message, ToolDefinitionForLLM, ProviderResponse, StreamChunk } from '@nebulaos/core';
 
+/**
+ * Custom error class for LLM Gateway errors.
+ * Provides clear, actionable error messages for developers.
+ */
+declare class LLMGatewayError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, status?: number | undefined, cause?: unknown | undefined);
+}
 /**
  * LLM Gateway Provider Configuration
  */
@@ -15,6 +25,12 @@ interface LLMGatewayConfig {
     logLevel?: LogLevel;
     /** Optional OpenAI client options */
     clientOptions?: ClientOptions;
+    /**
+     * Default model options passed to every generate() call.
+     * Supports provider-specific params like reasoning_effort, temperature, topK, etc.
+     * These can be overridden by options passed directly to generate().
+     */
+    options?: Omit<GenerateOptions, "responseFormat">;
 }
 /**
  * NebulaOS LLM Gateway Provider
@@ -29,6 +45,7 @@ declare class LLMGateway implements IModel {
     private client;
     private baseUrl;
     private logger;
+    private options?;
     capabilities: {
         readonly inputFiles: {
             readonly mimeTypes: readonly ["image/*"];
@@ -38,6 +55,25 @@ declare class LLMGateway implements IModel {
     constructor(config: LLMGatewayConfig);
     generate(messages: Message[], tools?: ToolDefinitionForLLM[], options?: GenerateOptions): Promise<ProviderResponse>;
     generateStream(messages: Message[], tools?: ToolDefinitionForLLM[], options?: GenerateOptions): AsyncGenerator<StreamChunk>;
+    /**
+     * 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)
+     */
+    private handleError;
+    /**
+     * 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.
+     */
+    private extractErrorSource;
     private extractExtraOptions;
     private buildGatewayHeaders;
     protected convertMessages(messages: Message[]): OpenAIClient.Chat.ChatCompletionMessageParam[];
@@ -47,4 +83,4 @@ declare class LLMGateway implements IModel {
     private convertContentPart;
 }
 
-export { LLMGateway, type LLMGatewayConfig };
+export { LLMGateway, type LLMGatewayConfig, LLMGatewayError };

package/dist/index.d.ts

@@ -1,6 +1,16 @@
 import OpenAIClient, { ClientOptions } from 'openai';
-import { LogLevel, IModel, Message, ToolDefinitionForLLM, GenerateOptions, ProviderResponse, StreamChunk } from '@nebulaos/core';
+import { LogLevel, GenerateOptions, IModel, Message, ToolDefinitionForLLM, ProviderResponse, StreamChunk } from '@nebulaos/core';
 
+/**
+ * Custom error class for LLM Gateway errors.
+ * Provides clear, actionable error messages for developers.
+ */
+declare class LLMGatewayError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, status?: number | undefined, cause?: unknown | undefined);
+}
 /**
  * LLM Gateway Provider Configuration
  */
@@ -15,6 +25,12 @@ interface LLMGatewayConfig {
     logLevel?: LogLevel;
     /** Optional OpenAI client options */
     clientOptions?: ClientOptions;
+    /**
+     * Default model options passed to every generate() call.
+     * Supports provider-specific params like reasoning_effort, temperature, topK, etc.
+     * These can be overridden by options passed directly to generate().
+     */
+    options?: Omit<GenerateOptions, "responseFormat">;
 }
 /**
  * NebulaOS LLM Gateway Provider
@@ -29,6 +45,7 @@ declare class LLMGateway implements IModel {
     private client;
     private baseUrl;
     private logger;
+    private options?;
     capabilities: {
         readonly inputFiles: {
             readonly mimeTypes: readonly ["image/*"];
@@ -38,6 +55,25 @@ declare class LLMGateway implements IModel {
     constructor(config: LLMGatewayConfig);
     generate(messages: Message[], tools?: ToolDefinitionForLLM[], options?: GenerateOptions): Promise<ProviderResponse>;
     generateStream(messages: Message[], tools?: ToolDefinitionForLLM[], options?: GenerateOptions): AsyncGenerator<StreamChunk>;
+    /**
+     * 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)
+     */
+    private handleError;
+    /**
+     * 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.
+     */
+    private extractErrorSource;
     private extractExtraOptions;
     private buildGatewayHeaders;
     protected convertMessages(messages: Message[]): OpenAIClient.Chat.ChatCompletionMessageParam[];
@@ -47,4 +83,4 @@ declare class LLMGateway implements IModel {
     private convertContentPart;
 }
 
-export { LLMGateway, type LLMGatewayConfig };
+export { LLMGateway, type LLMGatewayConfig, LLMGatewayError };