@aigne/core 1.58.3 → 1.59.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.59.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.58.3...core-v1.59.0) (2025-09-09)
+
+
+### Features
+
+* support custom prefer input file type ([#469](https://github.com/AIGNE-io/aigne-framework/issues/469)) ([db0161b](https://github.com/AIGNE-io/aigne-framework/commit/db0161bbac52542c771ee2f40f361636b0668075))
+
 ## [1.58.3](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.58.2...core-v1.58.3) (2025-09-08)
 
 

package/lib/cjs/agents/chat-model.d.ts

@@ -3,6 +3,10 @@ import { type PromiseOrValue } from "../utils/type-utils.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessResult, type AgentResponse, type AgentResponseStream, type Message } from "./agent.js";
 export declare class StructuredOutputError extends Error {
 }
+export interface ChatModelOptions extends Omit<AgentOptions<ChatModelInput, ChatModelOutput>, "inputSchema" | "outputSchema"> {
+    model?: string;
+    modelOptions?: Omit<ModelOptions, "model">;
+}
 /**
  * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
  *
@@ -27,8 +31,9 @@ export declare class StructuredOutputError extends Error {
  * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelOutput> {
+    options?: ChatModelOptions | undefined;
     tag: string;
-    constructor(options?: Omit<AgentOptions<ChatModelInput, ChatModelOutput>, "inputSchema" | "outputSchema">);
+    constructor(options?: ChatModelOptions | undefined);
     get credential(): PromiseOrValue<{
         url?: string;
         apiKey?: string;
@@ -145,7 +150,7 @@ export interface ChatModelInput extends Message {
     /**
      * Model-specific configuration options
      */
-    modelOptions?: ChatModelOptions;
+    modelOptions?: ModelOptions;
 }
 /**
  * Message role types
@@ -578,7 +583,7 @@ export type Modality = "text" | "image" | "audio";
  *
  * Contains various parameters for controlling model behavior, such as model name, temperature, etc.
  */
-export interface ChatModelOptions {
+export interface ModelOptions {
     /**
      * Model name or version
      */
@@ -604,6 +609,7 @@ export interface ChatModelOptions {
      */
     parallelToolCalls?: boolean;
     modalities?: Modality[];
+    preferFileInputType?: "file" | "url";
 }
 /**
  * Output message format for ChatModel

package/lib/cjs/agents/chat-model.js

@@ -76,10 +76,11 @@ exports.StructuredOutputError = StructuredOutputError;
  * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 class ChatModel extends agent_js_1.Agent {
+    options;
     tag = "ChatModelAgent";
     constructor(options) {
         if (options)
-            (0, type_utils_js_1.checkArguments)("ChatModel", agent_js_1.agentOptionsSchema, options);
+            (0, type_utils_js_1.checkArguments)("ChatModel", chatModelOptionsSchema, options);
         const retryOnError = options?.retryOnError === false
             ? false
             : options?.retryOnError === true
@@ -94,6 +95,7 @@ class ChatModel extends agent_js_1.Agent {
             outputSchema: chatModelOutputSchema,
             retryOnError,
         });
+        this.options = options;
     }
     get credential() {
         return {};
@@ -188,6 +190,18 @@ class ChatModel extends agent_js_1.Agent {
                             mimeType: item.mimeType || ChatModel.getMimeType(item.filename || item.path),
                         };
                     }
+                    if ((input.modelOptions?.preferFileInputType ||
+                        this.options?.modelOptions?.preferFileInputType) !== "url") {
+                        if (item.type === "url") {
+                            return {
+                                ...item,
+                                type: "file",
+                                data: Buffer.from(await (await this.downloadFile(item.url)).arrayBuffer()).toString("base64"),
+                                url: undefined,
+                                mimeType: item.mimeType || ChatModel.getMimeType(item.filename || item.url),
+                            };
+                        }
+                    }
                     return item;
                 })),
             };
@@ -379,7 +393,7 @@ const chatModelInputToolChoiceSchema = zod_1.z.union([
     zod_1.z.literal("required"),
     chatModelInputToolSchema,
 ]);
-const chatModelOptionsSchema = zod_1.z.object({
+const modelOptionsSchema = zod_1.z.object({
     model: zod_1.z.string().optional(),
     temperature: zod_1.z.number().optional(),
     topP: zod_1.z.number().optional(),
@@ -388,12 +402,16 @@ const chatModelOptionsSchema = zod_1.z.object({
     parallelToolCalls: zod_1.z.boolean().optional().default(true),
     modalities: zod_1.z.array(zod_1.z.enum(["text", "image", "audio"])).optional(),
 });
+const chatModelOptionsSchema = agent_js_1.agentOptionsSchema.extend({
+    model: zod_1.z.string().optional(),
+    modelOptions: modelOptionsSchema.optional(),
+});
 const chatModelInputSchema = zod_1.z.object({
     messages: zod_1.z.array(chatModelInputMessageSchema),
     responseFormat: chatModelInputResponseFormatSchema.optional(),
     tools: zod_1.z.array(chatModelInputToolSchema).optional(),
     toolChoice: chatModelInputToolChoiceSchema.optional(),
-    modelOptions: chatModelOptionsSchema.optional(),
+    modelOptions: modelOptionsSchema.optional(),
 });
 var FileOutputType;
 (function (FileOutputType) {

package/lib/cjs/agents/image-model.d.ts

@@ -32,14 +32,14 @@ export declare const imageModelInputSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     prompt: string;
     model?: string | undefined;
-    responseFormat?: "base64" | "url" | undefined;
     image?: string | string[] | undefined;
+    responseFormat?: "base64" | "url" | undefined;
     n?: number | undefined;
 }, {
     prompt: string;
     model?: string | undefined;
-    responseFormat?: "base64" | "url" | undefined;
     image?: string | string[] | undefined;
+    responseFormat?: "base64" | "url" | undefined;
     n?: number | undefined;
 }>;
 export interface ImageModelOutput extends Message {

package/lib/dts/agents/chat-model.d.ts

@@ -3,6 +3,10 @@ import { type PromiseOrValue } from "../utils/type-utils.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessResult, type AgentResponse, type AgentResponseStream, type Message } from "./agent.js";
 export declare class StructuredOutputError extends Error {
 }
+export interface ChatModelOptions extends Omit<AgentOptions<ChatModelInput, ChatModelOutput>, "inputSchema" | "outputSchema"> {
+    model?: string;
+    modelOptions?: Omit<ModelOptions, "model">;
+}
 /**
  * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
  *
@@ -27,8 +31,9 @@ export declare class StructuredOutputError extends Error {
  * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelOutput> {
+    options?: ChatModelOptions | undefined;
     tag: string;
-    constructor(options?: Omit<AgentOptions<ChatModelInput, ChatModelOutput>, "inputSchema" | "outputSchema">);
+    constructor(options?: ChatModelOptions | undefined);
     get credential(): PromiseOrValue<{
         url?: string;
         apiKey?: string;
@@ -145,7 +150,7 @@ export interface ChatModelInput extends Message {
     /**
      * Model-specific configuration options
      */
-    modelOptions?: ChatModelOptions;
+    modelOptions?: ModelOptions;
 }
 /**
  * Message role types
@@ -578,7 +583,7 @@ export type Modality = "text" | "image" | "audio";
  *
  * Contains various parameters for controlling model behavior, such as model name, temperature, etc.
  */
-export interface ChatModelOptions {
+export interface ModelOptions {
     /**
      * Model name or version
      */
@@ -604,6 +609,7 @@ export interface ChatModelOptions {
      */
     parallelToolCalls?: boolean;
     modalities?: Modality[];
+    preferFileInputType?: "file" | "url";
 }
 /**
  * Output message format for ChatModel

package/lib/dts/agents/image-model.d.ts

@@ -32,14 +32,14 @@ export declare const imageModelInputSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     prompt: string;
     model?: string | undefined;
-    responseFormat?: "base64" | "url" | undefined;
     image?: string | string[] | undefined;
+    responseFormat?: "base64" | "url" | undefined;
     n?: number | undefined;
 }, {
     prompt: string;
     model?: string | undefined;
-    responseFormat?: "base64" | "url" | undefined;
     image?: string | string[] | undefined;
+    responseFormat?: "base64" | "url" | undefined;
     n?: number | undefined;
 }>;
 export interface ImageModelOutput extends Message {

package/lib/esm/agents/chat-model.d.ts

@@ -3,6 +3,10 @@ import { type PromiseOrValue } from "../utils/type-utils.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessResult, type AgentResponse, type AgentResponseStream, type Message } from "./agent.js";
 export declare class StructuredOutputError extends Error {
 }
+export interface ChatModelOptions extends Omit<AgentOptions<ChatModelInput, ChatModelOutput>, "inputSchema" | "outputSchema"> {
+    model?: string;
+    modelOptions?: Omit<ModelOptions, "model">;
+}
 /**
  * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
  *
@@ -27,8 +31,9 @@ export declare class StructuredOutputError extends Error {
  * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelOutput> {
+    options?: ChatModelOptions | undefined;
     tag: string;
-    constructor(options?: Omit<AgentOptions<ChatModelInput, ChatModelOutput>, "inputSchema" | "outputSchema">);
+    constructor(options?: ChatModelOptions | undefined);
     get credential(): PromiseOrValue<{
         url?: string;
         apiKey?: string;
@@ -145,7 +150,7 @@ export interface ChatModelInput extends Message {
     /**
      * Model-specific configuration options
      */
-    modelOptions?: ChatModelOptions;
+    modelOptions?: ModelOptions;
 }
 /**
  * Message role types
@@ -578,7 +583,7 @@ export type Modality = "text" | "image" | "audio";
  *
  * Contains various parameters for controlling model behavior, such as model name, temperature, etc.
  */
-export interface ChatModelOptions {
+export interface ModelOptions {
     /**
      * Model name or version
      */
@@ -604,6 +609,7 @@ export interface ChatModelOptions {
      */
     parallelToolCalls?: boolean;
     modalities?: Modality[];
+    preferFileInputType?: "file" | "url";
 }
 /**
  * Output message format for ChatModel

package/lib/esm/agents/chat-model.js

@@ -36,10 +36,11 @@ export class StructuredOutputError extends Error {
  * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export class ChatModel extends Agent {
+    options;
     tag = "ChatModelAgent";
     constructor(options) {
         if (options)
-            checkArguments("ChatModel", agentOptionsSchema, options);
+            checkArguments("ChatModel", chatModelOptionsSchema, options);
         const retryOnError = options?.retryOnError === false
             ? false
             : options?.retryOnError === true
@@ -54,6 +55,7 @@ export class ChatModel extends Agent {
             outputSchema: chatModelOutputSchema,
             retryOnError,
         });
+        this.options = options;
     }
     get credential() {
         return {};
@@ -148,6 +150,18 @@ export class ChatModel extends Agent {
                             mimeType: item.mimeType || ChatModel.getMimeType(item.filename || item.path),
                         };
                     }
+                    if ((input.modelOptions?.preferFileInputType ||
+                        this.options?.modelOptions?.preferFileInputType) !== "url") {
+                        if (item.type === "url") {
+                            return {
+                                ...item,
+                                type: "file",
+                                data: Buffer.from(await (await this.downloadFile(item.url)).arrayBuffer()).toString("base64"),
+                                url: undefined,
+                                mimeType: item.mimeType || ChatModel.getMimeType(item.filename || item.url),
+                            };
+                        }
+                    }
                     return item;
                 })),
             };
@@ -338,7 +352,7 @@ const chatModelInputToolChoiceSchema = z.union([
     z.literal("required"),
     chatModelInputToolSchema,
 ]);
-const chatModelOptionsSchema = z.object({
+const modelOptionsSchema = z.object({
     model: z.string().optional(),
     temperature: z.number().optional(),
     topP: z.number().optional(),
@@ -347,12 +361,16 @@ const chatModelOptionsSchema = z.object({
     parallelToolCalls: z.boolean().optional().default(true),
     modalities: z.array(z.enum(["text", "image", "audio"])).optional(),
 });
+const chatModelOptionsSchema = agentOptionsSchema.extend({
+    model: z.string().optional(),
+    modelOptions: modelOptionsSchema.optional(),
+});
 const chatModelInputSchema = z.object({
     messages: z.array(chatModelInputMessageSchema),
     responseFormat: chatModelInputResponseFormatSchema.optional(),
     tools: z.array(chatModelInputToolSchema).optional(),
     toolChoice: chatModelInputToolChoiceSchema.optional(),
-    modelOptions: chatModelOptionsSchema.optional(),
+    modelOptions: modelOptionsSchema.optional(),
 });
 export var FileOutputType;
 (function (FileOutputType) {

package/lib/esm/agents/image-model.d.ts

@@ -32,14 +32,14 @@ export declare const imageModelInputSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     prompt: string;
     model?: string | undefined;
-    responseFormat?: "base64" | "url" | undefined;
     image?: string | string[] | undefined;
+    responseFormat?: "base64" | "url" | undefined;
     n?: number | undefined;
 }, {
     prompt: string;
     model?: string | undefined;
-    responseFormat?: "base64" | "url" | undefined;
     image?: string | string[] | undefined;
+    responseFormat?: "base64" | "url" | undefined;
     n?: number | undefined;
 }>;
 export interface ImageModelOutput extends Message {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.58.3",
+  "version": "1.59.0",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -92,8 +92,8 @@
     "yaml": "^2.8.0",
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/platform-helpers": "^0.6.2",
-    "@aigne/observability-api": "^0.10.2"
+    "@aigne/observability-api": "^0.10.2",
+    "@aigne/platform-helpers": "^0.6.2"
   },
   "devDependencies": {
     "@types/bun": "^1.2.18",