@future-explorer/lib 1.0.9 → 1.0.11

package/README.md

@@ -87,11 +87,10 @@ const SentimentSchema = z.object({
 });
 
 // Generate structured response
-const result = await client.generateStructuredResponse(
-  SentimentSchema,
-  'I absolutely love this product!',
-  'You are a sentiment analysis expert.'
-);
+const result = await client.generateStructuredResponse(SentimentSchema, {
+  prompt: 'I absolutely love this product!',
+  system: 'You are a sentiment analysis expert.',
+});
 
 console.log(result.sentiment); // 'positive'
 console.log(result.confidence); // 0.95
@@ -108,7 +107,7 @@ console.log(result.summary); // '...'
 
 ### Methods
 
-- `generateStructuredResponse<T>(schema, userPrompt, systemMessage?)`: Generates a structured response matching the Zod schema
+- `generateStructuredResponse<T>(schema: ZodSchema<T>, params: GenerateObjectParams<T>)`: Generates a structured response matching the Zod schema. Accepts `prompt`, `system`, plus any additional options
 - `getModel()`: Returns the underlying LanguageModel instance
 
 ## Development

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

@@ -1,6 +1,6 @@
 import { LanguageModel } from 'ai';
 import { ZodSchema } from 'zod';
-import { Provider } from './unified-ai-client.model';
+import { GenerateObjectParams, 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.
@@ -15,9 +15,8 @@ export declare class UnifiedAiClient {
      *
      * @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)
+     * @param params - Configuration object with prompt, system message, and any additional options.
+     *                 See {@link GenerateObjectParams} for all available options.
      *
      * @returns Promise resolving to the validated object matching the schema type T
      *
@@ -33,16 +32,15 @@ export declare class UnifiedAiClient {
      * });
      *
      * // 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.'
-     * );
+     * const result = await service.generateStructuredResponse(SentimentSchema, {
+     *   prompt: 'I absolutely love this product!',
+     *   system: '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>;
+    generateStructuredResponse<T>(schema: ZodSchema<T>, params: GenerateObjectParams<T>): Promise<T>;
     /**
      * Retrieves the underlying LanguageModel instance.
      * @returns The LanguageModel instance used by the UnifiedAiClient.

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

@@ -1 +1 @@
-{"version":3,"file":"unified-ai-client.d.ts","sourceRoot":"","sources":["../../../../src/clients/ai/unified/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"}
+{"version":3,"file":"unified-ai-client.d.ts","sourceRoot":"","sources":["../../../../src/clients/ai/unified/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,oBAAoB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE3E;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAgB;gBAEjB,QAAQ,EAAE,QAAQ;IAI9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,0BAA0B,CAAC,CAAC,EAChC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EACpB,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC;IAcb;;;OAGG;IACH,QAAQ,IAAI,aAAa;IAIzB,OAAO,CAAC,WAAW;CAYpB"}

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

@@ -22,9 +22,8 @@ class UnifiedAiClient {
      *
      * @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)
+     * @param params - Configuration object with prompt, system message, and any additional options.
+     *                 See {@link GenerateObjectParams} for all available options.
      *
      * @returns Promise resolving to the validated object matching the schema type T
      *
@@ -40,21 +39,22 @@ class UnifiedAiClient {
      * });
      *
      * // 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.'
-     * );
+     * const result = await service.generateStructuredResponse(SentimentSchema, {
+     *   prompt: 'I absolutely love this product!',
+     *   system: '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) {
+    async generateStructuredResponse(schema, params) {
+        const { prompt, system, ...rest } = params;
         const result = await (0, ai_1.generateObject)({
+            ...rest,
             model: this.model,
             schema: schema, // Option 2: Use jsonSchema instead of Zod directly: schema: jsonSchema<T>(zodToJsonSchema(schema) as any),
-            prompt: userPrompt,
-            system: systemMessage,
+            prompt: prompt,
+            system: system,
         });
         return result.object;
     }

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

@@ -1,3 +1,20 @@
+/**
+ * Options for generating a structured response from the AI model.
+ *
+ * Includes the core params (`prompt`, `system`) plus any additional options
+ * (e.g. `mode`, `schemaName`, `schemaDescription`, `maxTokens`, `temperature`, etc.).
+ * Extra properties are passed through as-is.
+ *
+ * Note: The Zod `schema` is passed as a separate argument to `generateStructuredResponse()`.
+ */
+export interface GenerateObjectParams<T> {
+    /** User input/message to send to the AI model (role: user). */
+    prompt: string;
+    /** Optional system instructions that define the AI's behavior, persona, and task context (role: system). */
+    system?: string;
+    /** Any additional options are passed through to the underlying AI call. */
+    [key: string]: unknown;
+}
 /**
  * Enum representing supported AI providers.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"unified-ai-client.model.d.ts","sourceRoot":"","sources":["../../../../src/clients/ai/unified/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"}
+{"version":3,"file":"unified-ai-client.model.d.ts","sourceRoot":"","sources":["../../../../src/clients/ai/unified/unified-ai-client.model.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,4GAA4G;IAC5G,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,oBAAY,QAAQ;IAClB;;OAEG;IACH,MAAM,WAAW;IACjB;;OAEG;IACH,GAAG,QAAQ;IACX;;OAEG;IACH,MAAM,WAAW;CAClB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@future-explorer/lib",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "Shared utilities and clients for Future Explorer projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -52,14 +52,17 @@
     "zod": "^4.2.0"
   },
   "devDependencies": {
-    "@types/node": "^24.5.2",
+    "@types/node": "^24.10.12",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
+    "dotenv": "^17.2.4",
     "eslint": "^9.20.1",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-prettier": "^5.2.3",
     "prettier": "^3.5.1",
     "rimraf": "^6.0.1",
-    "typescript": "^5.6.3"
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.3",
+    "zod": "4.2.0"
   }
 }