@falai/agent 0.5.0 → 0.5.3

package/src/providers/GeminiProvider.ts

@@ -6,8 +6,9 @@ import type {
   GoogleGenAI as GoogleGenAIType,
   GenerateContentConfig,
   GenerateContentResponse,
+  Schema,
 } from "@google/genai";
-import { GoogleGenAI } from "@google/genai";
+import { GoogleGenAI, Type } from "@google/genai";
 
 import type {
   AiProvider,
@@ -16,6 +17,7 @@ import type {
   GenerateMessageStreamChunk,
   AgentStructuredResponse,
 } from "../types/ai";
+import type { StructuredSchema } from "../types/schema";
 import { withTimeoutAndRetry } from "../utils/retry";
 
 const DEFAULT_RETRY_CONFIG = {
@@ -147,6 +149,109 @@ export class GeminiProvider implements AiProvider {
     };
   }
 
+  /**
+   * Adapt common schema format to Gemini's specific requirements.
+   * Gemini has strict validation:
+   * - OBJECT types MUST have non-empty properties
+   * - Empty objects cause 400 Bad Request errors
+   * - Uses Gemini's Schema type with Type enums
+   *
+   * @private
+   */
+  private adaptSchemaForGemini(schema: StructuredSchema): Schema {
+    const geminiSchema: Schema = {};
+
+    // Convert type
+    if (schema.type) {
+      if (Array.isArray(schema.type)) {
+        // For now, take the first type (Gemini doesn't support union types the same way)
+        geminiSchema.type = this.mapToGeminiType(schema.type[0]);
+      } else {
+        geminiSchema.type = this.mapToGeminiType(schema.type);
+      }
+    }
+
+    // Handle description
+    if (schema.description) {
+      geminiSchema.description = schema.description;
+    }
+
+    // Handle nullable
+    if (schema.nullable !== undefined) {
+      geminiSchema.nullable = schema.nullable;
+    }
+
+    // Handle enum
+    if (schema.enum) {
+      geminiSchema.enum = schema.enum as string[];
+    }
+
+    // Handle object properties - Gemini requires non-empty properties for OBJECT type
+    if (
+      geminiSchema.type === Type.OBJECT ||
+      schema.type === "object" ||
+      (Array.isArray(schema.type) && schema.type.includes("object"))
+    ) {
+      if (!schema.properties || Object.keys(schema.properties).length === 0) {
+        console.warn(
+          "[GeminiProvider] Gemini requires OBJECT types to have non-empty properties. Converting empty object to STRING."
+        );
+        geminiSchema.type = Type.STRING;
+        return geminiSchema;
+      }
+
+      // Recursively convert nested properties
+      geminiSchema.properties = {};
+      for (const [key, value] of Object.entries(schema.properties)) {
+        geminiSchema.properties[key] = this.adaptSchemaForGemini(value);
+      }
+
+      // Handle required fields
+      if (schema.required && schema.required.length > 0) {
+        geminiSchema.required = schema.required;
+      }
+    }
+
+    // Handle array items
+    if (
+      geminiSchema.type === Type.ARRAY ||
+      schema.type === "array" ||
+      (Array.isArray(schema.type) && schema.type.includes("array"))
+    ) {
+      if (schema.items) {
+        geminiSchema.items = this.adaptSchemaForGemini(schema.items);
+      }
+    }
+
+    return geminiSchema;
+  }
+
+  /**
+   * Map common JSON Schema type strings to Gemini's Type enum
+   * @private
+   */
+  private mapToGeminiType(type: string): Type {
+    switch (type.toLowerCase()) {
+      case "string":
+        return Type.STRING;
+      case "number":
+        return Type.NUMBER;
+      case "integer":
+        return Type.INTEGER;
+      case "boolean":
+        return Type.BOOLEAN;
+      case "array":
+        return Type.ARRAY;
+      case "object":
+        return Type.OBJECT;
+      default:
+        console.warn(
+          `[GeminiProvider] Unknown type "${type}", defaulting to STRING`
+        );
+        return Type.STRING;
+    }
+  }
+
   async generateMessage<
     TContext = unknown,
     TStructured = AgentStructuredResponse
@@ -239,9 +344,10 @@ export class GeminiProvider implements AiProvider {
       const configOverride: Partial<GenerateContentConfig> = { ...this.config };
       if (input.parameters?.jsonSchema) {
         configOverride.responseMimeType = "application/json";
-        // Gemini expects responseSchema. We pass through our schema as-is.
-        // A deeper mapping can be added via utils if needed.
-        configOverride.responseSchema = input.parameters.jsonSchema;
+        // Adapt common schema format to Gemini's specific requirements
+        configOverride.responseSchema = this.adaptSchemaForGemini(
+          input.parameters.jsonSchema
+        );
       }
 
       const response: GenerateContentResponse =
@@ -360,7 +466,10 @@ export class GeminiProvider implements AiProvider {
     const configOverride: Partial<GenerateContentConfig> = { ...this.config };
     if (input.parameters?.jsonSchema) {
       configOverride.responseMimeType = "application/json";
-      configOverride.responseSchema = input.parameters.jsonSchema;
+      // Adapt common schema format to Gemini's specific requirements
+      configOverride.responseSchema = this.adaptSchemaForGemini(
+        input.parameters.jsonSchema
+      );
     }
 
     const stream = await this.genAI.models.generateContentStream({

package/src/providers/OpenAIProvider.ts

@@ -12,6 +12,7 @@ import type {
   GenerateMessageStreamChunk,
   AgentStructuredResponse,
 } from "../types/ai";
+import type { StructuredSchema } from "../types/schema";
 import { withTimeoutAndRetry } from "../utils/retry";
 
 const DEFAULT_RETRY_CONFIG = {
@@ -159,6 +160,20 @@ export class OpenAIProvider implements AiProvider {
     };
   }
 
+  /**
+   * Adapt common schema format to OpenAI's format.
+   * OpenAI uses standard JSON Schema, so this is mostly a passthrough.
+   *
+   * @private
+   */
+  private adaptSchemaForOpenAI(
+    schema: StructuredSchema
+  ): Record<string, unknown> {
+    // OpenAI's responses.parse API uses standard JSON Schema
+    // Our StructuredSchema is already JSON Schema compatible
+    return schema as Record<string, unknown>;
+  }
+
   async generateMessage<
     TContext = unknown,
     TStructured = AgentStructuredResponse
@@ -279,7 +294,8 @@ export class OpenAIProvider implements AiProvider {
             format: {
               type: "json_schema",
               name: input.parameters?.schemaName || "structured_output",
-              schema: input.parameters.jsonSchema,
+              // Adapt common schema format to OpenAI's format
+              schema: this.adaptSchemaForOpenAI(input.parameters.jsonSchema),
             },
           },
         });

package/src/providers/OpenRouterProvider.ts

@@ -13,6 +13,7 @@ import type {
   GenerateMessageOutput,
   GenerateMessageStreamChunk,
 } from "../types/ai";
+import type { StructuredSchema } from "../types/schema";
 import { withTimeoutAndRetry } from "../utils/retry";
 
 const DEFAULT_RETRY_CONFIG = {
@@ -169,6 +170,20 @@ export class OpenRouterProvider implements AiProvider {
     };
   }
 
+  /**
+   * Adapt common schema format to OpenRouter's format.
+   * OpenRouter is OpenAI-compatible and uses standard JSON Schema.
+   *
+   * @private
+   */
+  private adaptSchemaForOpenRouter(
+    schema: StructuredSchema
+  ): Record<string, unknown> {
+    // OpenRouter is OpenAI-compatible and uses standard JSON Schema
+    // Our StructuredSchema is already JSON Schema compatible
+    return schema as Record<string, unknown>;
+  }
+
   async generateMessage<
     TContext = unknown,
     TStructured = AgentStructuredResponse
@@ -286,7 +301,10 @@ export class OpenRouterProvider implements AiProvider {
             format: {
               type: "json_schema",
               name: input.parameters?.schemaName || "structured_output",
-              schema: input.parameters.jsonSchema,
+              // Adapt common schema format to OpenRouter's format
+              schema: this.adaptSchemaForOpenRouter(
+                input.parameters.jsonSchema
+              ),
             },
           },
         });

package/src/types/session.ts

@@ -7,6 +7,9 @@
  * and data extracted during the route progression
  */
 export interface SessionState<TExtracted = Record<string, unknown>> {
+  /** Unique session identifier (useful for persistence) */
+  id?: string;
+
   /** Current route the conversation is in */
   currentRoute?: {
     id: string;
@@ -34,7 +37,6 @@ export interface SessionState<TExtracted = Record<string, unknown>> {
 
   /** Session metadata */
   metadata?: {
-    sessionId?: string;
     createdAt?: Date;
     lastUpdatedAt?: Date;
     [key: string]: unknown;
@@ -43,11 +45,15 @@ export interface SessionState<TExtracted = Record<string, unknown>> {
 
 /**
  * Helper to create a new session
+ * @param sessionId - Optional session ID (e.g., from database)
+ * @param metadata - Optional metadata to attach
  */
 export function createSession<TExtracted = Record<string, unknown>>(
+  sessionId?: string,
   metadata?: SessionState<TExtracted>["metadata"]
 ): SessionState<TExtracted> {
   return {
+    id: sessionId,
     extracted: {},
     routeHistory: [],
     metadata: {
@@ -172,15 +178,21 @@ export function sessionStateToData<TExtracted = Record<string, unknown>>(
 /**
  * Helper to convert database SessionData back to SessionState
  * Used when loading from database
+ * @param sessionId - The database session ID
+ * @param data - The database session data
  */
-export function sessionDataToState<TExtracted = Record<string, unknown>>(data: {
-  currentRoute?: string;
-  currentState?: string;
-  collectedData?: Record<string, unknown>;
-}): Partial<SessionState<TExtracted>> {
+export function sessionDataToState<TExtracted = Record<string, unknown>>(
+  sessionId: string,
+  data: {
+    currentRoute?: string;
+    currentState?: string;
+    collectedData?: Record<string, unknown>;
+  }
+): SessionState<TExtracted> {
   const collectedData = data.collectedData || {};
 
   return {
+    id: sessionId,
     currentRoute: data.currentRoute
       ? {
           id: data.currentRoute,

package/dist/cjs/utils/schema.d.ts

@@ -1,17 +0,0 @@
-import type { StructuredSchema } from "../types/schema";
-/**
- * Convert our StructuredSchema to the OpenAI/OpenRouter JSON schema format
- * (they already accept standard JSON Schema for responses.parse)
- */
-export declare function convertToOpenAIJsonSchema(schema: StructuredSchema): object;
-/**
- * Convert our StructuredSchema to Gemini responseSchema (Type mapping)
- * The @google/genai expects a slightly different shape
- */
-export declare function convertToGeminiSchema(schema: StructuredSchema): object;
-/**
- * Convert our StructuredSchema into Anthropic system prompt constraints.
- * Since Anthropic lacks native schema parsing, we embed a concise instruction.
- */
-export declare function convertToAnthropicConstraint(schema: StructuredSchema): string;
-//# sourceMappingURL=schema.d.ts.map

package/dist/cjs/utils/schema.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/utils/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAI1E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAItE;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAK7E"}

package/dist/cjs/utils/schema.js

@@ -1,32 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.convertToOpenAIJsonSchema = convertToOpenAIJsonSchema;
-exports.convertToGeminiSchema = convertToGeminiSchema;
-exports.convertToAnthropicConstraint = convertToAnthropicConstraint;
-/**
- * Convert our StructuredSchema to the OpenAI/OpenRouter JSON schema format
- * (they already accept standard JSON Schema for responses.parse)
- */
-function convertToOpenAIJsonSchema(schema) {
-    // For now our schema aligns well with JSON Schema draft-like structure
-    // Return as-is; callers should ensure correctness
-    return schema;
-}
-/**
- * Convert our StructuredSchema to Gemini responseSchema (Type mapping)
- * The @google/genai expects a slightly different shape
- */
-function convertToGeminiSchema(schema) {
-    // Basic passthrough. If needed, a deeper mapping can be added later.
-    // Gemini supports a similar structure (type, properties, items, enum, etc.)
-    return schema;
-}
-/**
- * Convert our StructuredSchema into Anthropic system prompt constraints.
- * Since Anthropic lacks native schema parsing, we embed a concise instruction.
- */
-function convertToAnthropicConstraint(schema) {
-    // Keep it concise to avoid context bloat
-    return `You must respond with valid JSON that matches this schema: ${JSON.stringify(schema)}`;
-}
-//# sourceMappingURL=schema.js.map

package/dist/cjs/utils/schema.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/utils/schema.ts"],"names":[],"mappings":";;AAMA,8DAIC;AAMD,sDAIC;AAMD,oEAKC;AA7BD;;;GAGG;AACH,SAAgB,yBAAyB,CAAC,MAAwB;IAChE,uEAAuE;IACvE,kDAAkD;IAClD,OAAO,MAAgB,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,MAAwB;IAC5D,qEAAqE;IACrE,4EAA4E;IAC5E,OAAO,MAAgB,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,SAAgB,4BAA4B,CAAC,MAAwB;IACnE,yCAAyC;IACzC,OAAO,8DAA8D,IAAI,CAAC,SAAS,CACjF,MAAM,CACP,EAAE,CAAC;AACN,CAAC"}

package/dist/utils/schema.d.ts

@@ -1,17 +0,0 @@
-import type { StructuredSchema } from "../types/schema";
-/**
- * Convert our StructuredSchema to the OpenAI/OpenRouter JSON schema format
- * (they already accept standard JSON Schema for responses.parse)
- */
-export declare function convertToOpenAIJsonSchema(schema: StructuredSchema): object;
-/**
- * Convert our StructuredSchema to Gemini responseSchema (Type mapping)
- * The @google/genai expects a slightly different shape
- */
-export declare function convertToGeminiSchema(schema: StructuredSchema): object;
-/**
- * Convert our StructuredSchema into Anthropic system prompt constraints.
- * Since Anthropic lacks native schema parsing, we embed a concise instruction.
- */
-export declare function convertToAnthropicConstraint(schema: StructuredSchema): string;
-//# sourceMappingURL=schema.d.ts.map

package/dist/utils/schema.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAI1E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAItE;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAK7E"}

package/dist/utils/schema.js

@@ -1,27 +0,0 @@
-/**
- * Convert our StructuredSchema to the OpenAI/OpenRouter JSON schema format
- * (they already accept standard JSON Schema for responses.parse)
- */
-export function convertToOpenAIJsonSchema(schema) {
-    // For now our schema aligns well with JSON Schema draft-like structure
-    // Return as-is; callers should ensure correctness
-    return schema;
-}
-/**
- * Convert our StructuredSchema to Gemini responseSchema (Type mapping)
- * The @google/genai expects a slightly different shape
- */
-export function convertToGeminiSchema(schema) {
-    // Basic passthrough. If needed, a deeper mapping can be added later.
-    // Gemini supports a similar structure (type, properties, items, enum, etc.)
-    return schema;
-}
-/**
- * Convert our StructuredSchema into Anthropic system prompt constraints.
- * Since Anthropic lacks native schema parsing, we embed a concise instruction.
- */
-export function convertToAnthropicConstraint(schema) {
-    // Keep it concise to avoid context bloat
-    return `You must respond with valid JSON that matches this schema: ${JSON.stringify(schema)}`;
-}
-//# sourceMappingURL=schema.js.map

package/dist/utils/schema.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAwB;IAChE,uEAAuE;IACvE,kDAAkD;IAClD,OAAO,MAAgB,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAwB;IAC5D,qEAAqE;IACrE,4EAA4E;IAC5E,OAAO,MAAgB,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAwB;IACnE,yCAAyC;IACzC,OAAO,8DAA8D,IAAI,CAAC,SAAS,CACjF,MAAM,CACP,EAAE,CAAC;AACN,CAAC"}

package/src/utils/schema.ts

@@ -1,32 +0,0 @@
-import type { StructuredSchema } from "../types/schema";
-
-/**
- * Convert our StructuredSchema to the OpenAI/OpenRouter JSON schema format
- * (they already accept standard JSON Schema for responses.parse)
- */
-export function convertToOpenAIJsonSchema(schema: StructuredSchema): object {
-  // For now our schema aligns well with JSON Schema draft-like structure
-  // Return as-is; callers should ensure correctness
-  return schema as object;
-}
-
-/**
- * Convert our StructuredSchema to Gemini responseSchema (Type mapping)
- * The @google/genai expects a slightly different shape
- */
-export function convertToGeminiSchema(schema: StructuredSchema): object {
-  // Basic passthrough. If needed, a deeper mapping can be added later.
-  // Gemini supports a similar structure (type, properties, items, enum, etc.)
-  return schema as object;
-}
-
-/**
- * Convert our StructuredSchema into Anthropic system prompt constraints.
- * Since Anthropic lacks native schema parsing, we embed a concise instruction.
- */
-export function convertToAnthropicConstraint(schema: StructuredSchema): string {
-  // Keep it concise to avoid context bloat
-  return `You must respond with valid JSON that matches this schema: ${JSON.stringify(
-    schema
-  )}`;
-}