@future-explorer/lib 1.0.5 → 1.0.7

package/README.md

@@ -33,7 +33,7 @@ const response = await client.getGenericStructuredResponse<PersonInfo>({
   model: 'grok-2-latest',
   messages: [
     { role: 'system', content: 'You are a helpful assistant.' },
-    { role: 'user', content: 'Extract data from this text...' }
+    { role: 'user', content: 'Extract data from this text...' },
   ],
   tools: [
     {
@@ -44,11 +44,11 @@ const response = await client.getGenericStructuredResponse<PersonInfo>({
         type: 'object',
         properties: {
           name: { type: 'string' },
-          age: { type: 'number' }
+          age: { type: 'number' },
         },
-        required: ['name', 'age']
-      }
-    }
+        required: ['name', 'age'],
+      },
+    },
   ],
 });
 
@@ -65,6 +65,52 @@ if (response) {
 - `maxTokens` (optional): Default max tokens (default: 4096)
 - `logger` (optional): Logger instance with `warn` and `error` methods
 
+## UnifiedAiClient
+
+Multi-provider AI client supporting OpenAI, XAI (Grok), and Google Gemini with Zod schema-based structured outputs.
+
+### Basic Usage
+
+```typescript
+import { UnifiedAiClient, Provider } from '@future-explorer/lib';
+import { z } from 'zod';
+
+// Create client with desired provider
+const client = new UnifiedAiClient(Provider.OpenAI);
+// or Provider.XAI, Provider.Gemini
+
+// Define a Zod schema for the response
+const SentimentSchema = z.object({
+  sentiment: z.enum(['positive', 'negative', 'neutral']),
+  confidence: z.number().min(0).max(1),
+  summary: z.string(),
+});
+
+// Generate structured response
+const result = await client.generateStructuredResponse(
+  SentimentSchema,
+  'I absolutely love this product!',
+  'You are a sentiment analysis expert.'
+);
+
+console.log(result.sentiment); // 'positive'
+console.log(result.confidence); // 0.95
+console.log(result.summary); // '...'
+```
+
+### Providers
+
+| Provider      | Enum Value        | Required Environment Variables                 |
+| ------------- | ----------------- | ---------------------------------------------- |
+| OpenAI        | `Provider.OpenAI` | `OPENAI_API_KEY`, `MODEL_OPEN_AI`              |
+| XAI (Grok)    | `Provider.XAI`    | `XAI_API_KEY`, `MODEL_XAI`                     |
+| Google Gemini | `Provider.Gemini` | `GOOGLE_GENERATIVE_AI_API_KEY`, `MODEL_GEMINI` |
+
+### Methods
+
+- `generateStructuredResponse<T>(schema, userPrompt, systemMessage?)`: Generates a structured response matching the Zod schema
+- `getModel()`: Returns the underlying LanguageModel instance
+
 ## Development
 
 ### Build
@@ -115,6 +161,16 @@ npm publish
 ./scripts/publish.sh [patch|minor|major]
 ```
 
+## Changelog
+
+### 1.0.7
+
+- Updated peer dependency to zod 4.2.x
+
+### 1.0.6
+
+- Added UnifiedAiClient with multi-provider support (OpenAI, XAI, Gemini)
+
 ## License
 
-ISC
+ISC

package/dist/clients/ai/clients/unified-ai-sdk/index.d.ts

@@ -0,0 +1,3 @@
+export * from './unified-ai-client';
+export * from './unified-ai-client.model';
+//# sourceMappingURL=index.d.ts.map

package/dist/clients/ai/clients/unified-ai-sdk/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/clients/ai/clients/unified-ai-sdk/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC"}

package/dist/clients/ai/clients/unified-ai-sdk/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./unified-ai-client"), exports);
+__exportStar(require("./unified-ai-client.model"), exports);

package/dist/clients/ai/clients/unified-ai-sdk/unified-ai-client.d.ts

@@ -0,0 +1,53 @@
+import { LanguageModel } from 'ai';
+import { ZodSchema } from 'zod';
+import { Provider } from './unified-ai-client.model';
+/**
+ * Unified AI Client that supports multiple AI providers (OpenAI, XAI, Gemini)
+ * and allows generating structured responses based on Zod schemas.
+ */
+export declare class UnifiedAiClient {
+    private model;
+    constructor(provider: Provider);
+    /**
+     * Generates a structured response from the AI model based on a Zod schema.
+     *
+     * @template T - The type inferred from the Zod schema
+     *
+     * @param schema - Zod schema defining the expected response structure.
+     *                 The AI model will be constrained to return data matching this schema.
+     * @param prompt - User input/message to send to the AI model (role: user)
+     * @param system - Optional system instructions that define the AI's behavior,
+     *                 persona, and task context (role: system)
+     *
+     * @returns Promise resolving to the validated object matching the schema type T
+     *
+     * @throws {Error} If the AI provider fails to generate a valid response
+     * @throws {Error} If the response doesn't match the provided schema
+     *
+     * @example
+     * // Define a schema
+     * const SentimentSchema = z.object({
+     *   sentiment: z.enum(['positive', 'negative', 'neutral']),
+     *   confidence: z.number().min(0).max(1),
+     *   summary: z.string(),
+     * });
+     *
+     * // Generate structured response
+     * const result = await service.generateStructuredResponse(
+     *   SentimentSchema,
+     *   'I absolutely love this product!',
+     *   'You are a sentiment analysis expert. Be precise with confidence scores.'
+     * );
+     *
+     * console.log(result.sentiment);   // 'positive'
+     * console.log(result.confidence);  // 0.95
+     */
+    generateStructuredResponse<T>(schema: ZodSchema<T>, userPrompt: string, systemMessage?: string): Promise<T>;
+    /**
+     * Retrieves the underlying LanguageModel instance.
+     * @returns The LanguageModel instance used by the UnifiedAiClient.
+     */
+    getModel(): LanguageModel;
+    private createModel;
+}
+//# sourceMappingURL=unified-ai-client.d.ts.map

package/dist/clients/ai/clients/unified-ai-sdk/unified-ai-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-ai-client.d.ts","sourceRoot":"","sources":["../../../../../src/clients/ai/clients/unified-ai-sdk/unified-ai-client.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,aAAa,EAAE,MAAM,IAAI,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAgB;gBAEjB,QAAQ,EAAE,QAAQ;IAI9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,0BAA0B,CAAC,CAAC,EAChC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EACpB,UAAU,EAAE,MAAM,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,CAAC,CAAC;IAWb;;;OAGG;IACH,QAAQ,IAAI,aAAa;IAIzB,OAAO,CAAC,WAAW;CAYpB"}

package/dist/clients/ai/clients/unified-ai-sdk/unified-ai-client.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnifiedAiClient = void 0;
+const google_1 = require("@ai-sdk/google");
+const openai_1 = require("@ai-sdk/openai");
+const xai_1 = require("@ai-sdk/xai");
+const ai_1 = require("ai");
+const unified_ai_client_model_1 = require("./unified-ai-client.model");
+/**
+ * Unified AI Client that supports multiple AI providers (OpenAI, XAI, Gemini)
+ * and allows generating structured responses based on Zod schemas.
+ */
+class UnifiedAiClient {
+    model;
+    constructor(provider) {
+        this.model = this.createModel(provider);
+    }
+    /**
+     * Generates a structured response from the AI model based on a Zod schema.
+     *
+     * @template T - The type inferred from the Zod schema
+     *
+     * @param schema - Zod schema defining the expected response structure.
+     *                 The AI model will be constrained to return data matching this schema.
+     * @param prompt - User input/message to send to the AI model (role: user)
+     * @param system - Optional system instructions that define the AI's behavior,
+     *                 persona, and task context (role: system)
+     *
+     * @returns Promise resolving to the validated object matching the schema type T
+     *
+     * @throws {Error} If the AI provider fails to generate a valid response
+     * @throws {Error} If the response doesn't match the provided schema
+     *
+     * @example
+     * // Define a schema
+     * const SentimentSchema = z.object({
+     *   sentiment: z.enum(['positive', 'negative', 'neutral']),
+     *   confidence: z.number().min(0).max(1),
+     *   summary: z.string(),
+     * });
+     *
+     * // Generate structured response
+     * const result = await service.generateStructuredResponse(
+     *   SentimentSchema,
+     *   'I absolutely love this product!',
+     *   'You are a sentiment analysis expert. Be precise with confidence scores.'
+     * );
+     *
+     * console.log(result.sentiment);   // 'positive'
+     * console.log(result.confidence);  // 0.95
+     */
+    async generateStructuredResponse(schema, userPrompt, systemMessage) {
+        const result = await (0, ai_1.generateObject)({
+            model: this.model,
+            schema: schema, // Option 2: Use jsonSchema instead of Zod directly: schema: jsonSchema<T>(zodToJsonSchema(schema) as any),
+            prompt: userPrompt,
+            system: systemMessage,
+        });
+        return result.object;
+    }
+    /**
+     * Retrieves the underlying LanguageModel instance.
+     * @returns The LanguageModel instance used by the UnifiedAiClient.
+     */
+    getModel() {
+        return this.model;
+    }
+    createModel(provider) {
+        switch (provider) {
+            case unified_ai_client_model_1.Provider.OpenAI:
+                return (0, openai_1.openai)(process.env.MODEL_OPEN_AI);
+            case unified_ai_client_model_1.Provider.XAI:
+                return (0, xai_1.xai)(process.env.MODEL_XAI);
+            case unified_ai_client_model_1.Provider.Gemini:
+                return (0, google_1.google)(process.env.MODEL_GEMINI);
+            default:
+                throw new Error(`Unknown provider: ${provider}`);
+        }
+    }
+}
+exports.UnifiedAiClient = UnifiedAiClient;

package/dist/clients/ai/clients/unified-ai-sdk/unified-ai-client.model.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Enum representing supported AI providers.
+ */
+export declare enum Provider {
+    /**
+     * Expects 'OPENAI_API_KEY' and 'MODEL_OPEN_AI' environment variables to be set.
+     */
+    OpenAI = "openai",
+    /**
+     * Expects 'XAI_API_KEY' and 'MODEL_XAI' environment variables to be set.
+     */
+    XAI = "xai",
+    /**
+     * Expects 'GOOGLE_GENERATIVE_AI_API_KEY' and 'MODEL_GEMINI' environment variables to be set.
+     */
+    Gemini = "gemini"
+}
+//# sourceMappingURL=unified-ai-client.model.d.ts.map

package/dist/clients/ai/clients/unified-ai-sdk/unified-ai-client.model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-ai-client.model.d.ts","sourceRoot":"","sources":["../../../../../src/clients/ai/clients/unified-ai-sdk/unified-ai-client.model.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,QAAQ;IAClB;;OAEG;IACH,MAAM,WAAW;IACjB;;OAEG;IACH,GAAG,QAAQ;IACX;;OAEG;IACH,MAAM,WAAW;CAClB"}

package/dist/clients/ai/clients/unified-ai-sdk/unified-ai-client.model.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Provider = void 0;
+/**
+ * Enum representing supported AI providers.
+ */
+var Provider;
+(function (Provider) {
+    /**
+     * Expects 'OPENAI_API_KEY' and 'MODEL_OPEN_AI' environment variables to be set.
+     */
+    Provider["OpenAI"] = "openai";
+    /**
+     * Expects 'XAI_API_KEY' and 'MODEL_XAI' environment variables to be set.
+     */
+    Provider["XAI"] = "xai";
+    /**
+     * Expects 'GOOGLE_GENERATIVE_AI_API_KEY' and 'MODEL_GEMINI' environment variables to be set.
+     */
+    Provider["Gemini"] = "gemini";
+})(Provider || (exports.Provider = Provider = {}));

package/dist/clients/ai/index.d.ts

@@ -1,3 +1,4 @@
+export * from './clients/unified-ai-sdk/unified-ai-client';
 export * from './grok';
 export * from './shared';
 //# sourceMappingURL=index.d.ts.map

package/dist/clients/ai/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/clients/ai/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/clients/ai/index.ts"],"names":[],"mappings":"AAAA,cAAc,4CAA4C,CAAC;AAC3D,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC"}

package/dist/clients/ai/index.js

@@ -14,5 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./clients/unified-ai-sdk/unified-ai-client"), exports);
 __exportStar(require("./grok"), exports);
 __exportStar(require("./shared"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@future-explorer/lib",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Shared utilities and clients for Future Explorer projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,10 +16,23 @@
   },
   "keywords": [
     "future-explorer",
+    "ai-sdk",
+    "openai",
+    "gemini",
     "grok",
-    "ai-client"
+    "xai",
+    "unified-ai"
+  ],
+  "contributors": [
+    {
+      "name": "Alexander Grigoryan",
+      "email": "agrigoryan1982@gmail.com"
+    },
+    {
+      "name": "Renat Gatin",
+      "email": "renat.gatin@gmail.com"
+    }
   ],
-  "author": "",
   "license": "ISC",
   "publishConfig": {
     "access": "public"
@@ -29,17 +42,19 @@
     "url": "https://github.com/future-explorer/future-explorer.git",
     "directory": "future-explorer-lib"
   },
+  "dependencies": {
+    "@ai-sdk/google": "^2.0.52",
+    "@ai-sdk/openai": "^2.0.89",
+    "@ai-sdk/xai": "^2.0.31",
+    "ai": "^5.0.92"
+  },
   "peerDependencies": {
-    "@ai-sdk/provider": "^2.0.0",
-    "@ai-sdk/xai": "^2.0.0"
+    "zod": "^4.2.0"
   },
   "devDependencies": {
-    "@ai-sdk/provider": "^2.0.0",
-    "@ai-sdk/xai": "^2.0.31",
     "@types/node": "^24.5.2",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
-    "ai": "^5.0.92",
     "eslint": "^9.20.1",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-prettier": "^5.2.3",