@fragola-ai/agent 0.1.0 → 0.1.1

package/dist/src/event.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/agentContext.ts", "../../src/event.ts"],
-  "sourcesContent": ["import type { AgentOptions, AgentState, ContextRaw, SetOptionsParams } from \"./agent\";\nimport type { DefineMetaData, Fragola, Tool } from \"./fragola\";\nimport type { StoreLike } from \"./types\";\nimport type { Store } from \"./store\";\nimport type { MessagesParser } from \"./stateUtils\";\n\nexport const STOP = Symbol('stop');\nexport abstract class AgentContext<TMetaData extends DefineMetaData<any> = {}, TGlobalStore extends StoreLike<any> = {}, TStore extends StoreLike<any> = {}> {\n    /** The current state of the agent. */\n    abstract get state(): AgentState<TMetaData>;\n    /** The configuration options for the agent. */\n    abstract get options(): AgentOptions;\n    /** Raw methods for advanced context manipulation */\n    abstract get raw(): ContextRaw<TMetaData>;\n    /** Acess the agent's default local store. */\n    abstract get store(): Store<TStore>;\n    /** Live parser helpers bound to the current `state.messages`. */\n    abstract get messagesParser(): MessagesParser<TMetaData>;\n    /**\n     * Add a store that has a namespace. Can be accessed with `getStore` method.\n     * @param store - The store to add\n     */\n    abstract addStore(store: Store<any>): void;\n\n    /**\n     * Updates the agent's tool list using a callback.\n     *\n     * @param callback - Function that receives the current tools and returns the updated list.\n     *\n     * @example\n     * agent.context.updateTools(prev => [...prev, newTool]);\n     * agent.context.updateTools(prev => prev.filter(tool => tool.name !== \"oldTool\"));\n     */\n    abstract updateTools(callback: (prev: Tool[]) => Tool[]): void;\n    /**\n     * Remove a store by its namespace.\n     * @param namespace - The namespace of the store to remove\n     */\n    abstract removeStore(namespace: string): void;\n    /** Return the Fragola instance which created this agent */\n    abstract get instance(): Fragola<TGlobalStore>;\n    /**\n     * Returns the agent's local store or namespace store casted as T. Recommended when accessing the store from a hook.\n     * @param namespace - The namespace of the store to access (optional).\n     */\n    abstract getStore<T extends StoreLike<any> = {}>(namespace?: string): Store<T> | undefined;\n\n    /**\n     * Sets the current instructions for the agent.\n     * @param instructions - The new instructions as a string.\n     */\n    abstract setInstructions(instructions: string, scope?: string): void;\n\n    /**\n     * Returns the system prompt for a given scope.\n     * @param scope - The instructions scope, leave empty to get the default scope (optional)\n     */\n    abstract getInstructions(scope?: string): string | undefined;\n\n    /**\n     * Remove the system prompt for a given scope. \n     * @param scope - The instructions scope to remove\n     * @returns a boolean, true = removed, false = scope do not exist\n     */\n    abstract removeInstructions(scope: string): boolean\n    /**\n     * Updates the agent's options.\n     * **note**: the `name`, `fork` and `messages` properties are ommited\n     * @param options - The new options to set, as a SetOptionsParams object.\n     */\n    abstract setOptions(options: SetOptionsParams): void;\n    /** Stop the agent execution */\n    abstract stop(): Promise<{[STOP]: true}>;\n    /** Stop the agent execution - Sync */\n    abstract stopSync(): {[STOP]: true}\n}", "import type { AgentContext } from \"@src/agentContext\";\nimport { STOP } from \"./agentContext\";\nimport type { StoreLike, maybePromise } from \"./types\";\nimport type { DefineMetaData } from \"./fragola\";\nimport type { AgentAfterEventId } from \"./eventAfter\";\nimport type { AgentBeforeEventId } from \"./eventBefore\";\n\nexport type AgentDefaultEventId =\n   \"modelInvocation\" | \"toolCall\" | \"aiMessage\" | \"userMessage\";\n\nexport const SKIP_EVENT = Symbol.for('skip_event');\n/**\n * When returned from an event handler, the event will be ignored.\n * \n * @returns An object with the SKIP_EVENT symbol that signals the event system to skip this event\n */\nexport const skip = () => ({[SKIP_EVENT]: true});\nexport const stop = () => ({[STOP]: true});\n\nexport type eventResult<T> = T | ReturnType<typeof skip> | ReturnType<typeof stop>; //TODO: fix stop not imported\n\nexport type AgentEventId = AgentDefaultEventId | AgentAfterEventId | AgentBeforeEventId;\n\nexport type EventDefaultCallback<TMetaData extends DefineMetaData<any>, TGlobalStore extends StoreLike<any>, TStore extends StoreLike<any>> = (\n  context: AgentContext<TMetaData, TGlobalStore, TStore>\n) => maybePromise<void>;"],
+  "sourcesContent": ["import type { AgentOptions, AgentState, ContextRaw, SetOptionsParams } from \"./agent\";\nimport type { DefineMetaData, Fragola, Tool } from \"./fragola\";\nimport type { StoreLike } from \"./types\";\nimport type { Store } from \"./store\";\nimport type { MessagesParser } from \"./stateUtils\";\n\nexport const STOP = Symbol('stop');\nexport abstract class AgentContext<TMetaData extends DefineMetaData<any> = {}, TGlobalStore extends StoreLike<any> = {}, TStore extends StoreLike<any> = {}> {\n    /** The current state of the agent. */\n    abstract get state(): AgentState<TMetaData>;\n    /** The configuration options for the agent. */\n    abstract get options(): AgentOptions;\n    /** Raw methods for advanced context manipulation */\n    abstract get raw(): ContextRaw<TMetaData>;\n    /** Acess the agent's default local store. */\n    abstract get store(): Store<TStore>;\n    /** Live parser helpers bound to the current `state.messages`. */\n    abstract get messagesParser(): MessagesParser<TMetaData>;\n    /**\n     * Add a store that has a namespace. Can be accessed with `getStore` method.\n     * @param store - The store to add\n     */\n    abstract addStore(store: Store<any>): void;\n\n    /**\n     * Updates the agent's tool list using a callback.\n     *\n     * @param callback - Function that receives the current tools and returns the updated list.\n     *\n     * @example\n     * agent.context.updateTools(prev => [...prev, newTool]);\n     * agent.context.updateTools(prev => prev.filter(tool => tool.name !== \"oldTool\"));\n     */\n    abstract updateTools(callback: (prev: Tool[]) => Tool[]): void;\n    /**\n     * Remove a store by its namespace.\n     * @param namespace - The namespace of the store to remove\n     */\n    abstract removeStore(namespace: string): void;\n    /** Return the Fragola instance which created this agent */\n    abstract get instance(): Fragola<TGlobalStore>;\n    /**\n     * Returns the agent's local store or namespace store casted as T. Recommended when accessing the store from a hook.\n     * @param namespace - The namespace of the store to access (optional).\n     */\n    abstract getStore<T extends StoreLike<any> = {}>(namespace?: string): Store<T> | undefined;\n\n    /** Returns the agent system prompt exactly as sent to the llm. The system prompt is the result of all the instructions scopes merged */\n    abstract get systemPrompt(): string;\n\n    /**\n     * Sets the current instructions for the agent.\n     * @param instructions - The new instructions as a string.\n     */\n    abstract setInstructions(instructions: string, scope?: string): void;\n\n    /**\n     * Returns the instructions for a given scope.\n     * @param scope - The instructions scope, leave empty to get the default scope (optional)\n     */\n    abstract instructions(scope?: string): string | undefined;\n\n    /**\n     * Remove the instructions for a given scope. \n     * @param scope - The instructions scope to remove\n     * @returns a boolean, true = removed, false = scope do not exist\n     */\n    abstract removeInstructions(scope: string): boolean\n    /**\n     * Updates the agent's options.\n     * **note**: the `name`, `fork` and `messages` properties are ommited\n     * @param options - The new options to set, as a SetOptionsParams object.\n     */\n    abstract setOptions(options: SetOptionsParams): void;\n    /** Stop the agent execution */\n    abstract stop(): Promise<{[STOP]: true}>;\n    /** Stop the agent execution - Sync */\n    abstract stopSync(): {[STOP]: true}\n}", "import type { AgentContext } from \"@src/agentContext\";\nimport { STOP } from \"./agentContext\";\nimport type { StoreLike, maybePromise } from \"./types\";\nimport type { DefineMetaData } from \"./fragola\";\nimport type { AgentAfterEventId } from \"./eventAfter\";\nimport type { AgentBeforeEventId } from \"./eventBefore\";\n\nexport type AgentDefaultEventId =\n   \"modelInvocation\" | \"toolCall\" | \"aiMessage\" | \"userMessage\";\n\nexport const SKIP_EVENT = Symbol.for('skip_event');\n/**\n * When returned from an event handler, the event will be ignored.\n * \n * @returns An object with the SKIP_EVENT symbol that signals the event system to skip this event\n */\nexport const skip = () => ({[SKIP_EVENT]: true});\nexport const stop = () => ({[STOP]: true});\n\nexport type eventResult<T> = T | ReturnType<typeof skip> | ReturnType<typeof stop>; //TODO: fix stop not imported\n\nexport type AgentEventId = AgentDefaultEventId | AgentAfterEventId | AgentBeforeEventId;\n\nexport type EventDefaultCallback<TMetaData extends DefineMetaData<any>, TGlobalStore extends StoreLike<any>, TStore extends StoreLike<any>> = (\n  context: AgentContext<TMetaData, TGlobalStore, TStore>\n) => maybePromise<void>;"],
   "mappings": "AAMO,IAAMA,EAAO,OAAO,MAAM,ECI1B,IAAMC,EAAa,OAAO,IAAI,YAAY,EAMpCC,EAAO,KAAO,CAAC,CAACD,CAAU,EAAG,EAAI,GACjCE,EAAO,KAAO,CAAC,CAACC,CAAI,EAAG,EAAI",
   "names": ["STOP", "SKIP_EVENT", "skip", "stop", "STOP"]
 }

package/dist/src/eventAfter.d.ts

@@ -1,14 +1,15 @@
 import type { maybePromise, StoreLike } from "./types";
 import type { AgentDefaultEventId, EventDefaultCallback } from "./event";
 import type { AgentContext } from "./agentContext";
-import type { ChatCompletionAssistantMessageParam, ChatCompletionMessageParam, DefineMetaData, Tool, ToolHandlerReturnTypeNonAsync } from "./fragola";
+import type { ChatCompletionAssistantMessageParam, ChatCompletionMessageParam, DefineMetaData, Tool } from "./fragola";
+import type { ToolCallPayload } from "./eventDefault";
 import type { StepOptions } from "./agent";
 export type AgentAfterEventExclusive = "after:stateUpdate" | "after:step";
 export type AgentAfterEventId = `after:${AgentDefaultEventId}` | AgentAfterEventExclusive;
 export type EventAfterStateUpdate<TMetaData extends DefineMetaData<any>, TGlobalStore extends StoreLike<any>, TStore extends StoreLike<any>> = EventDefaultCallback<TMetaData, TGlobalStore, TStore>;
 export type EventAfterStep<TMetaData extends DefineMetaData<any>, TGlobalStore extends StoreLike<any>, TStore extends StoreLike<any>> = (options: Required<StepOptions>, newMessages: ChatCompletionMessageParam<TMetaData>[], stepsTaken: number, context: AgentContext<TMetaData, TGlobalStore, TStore>) => maybePromise<void>;
 export type EventAfterModelInvocation<TMetaData extends DefineMetaData<any>, TGlobalStore extends StoreLike<any>, TStore extends StoreLike<any>> = (message: ChatCompletionAssistantMessageParam<TMetaData>, context: AgentContext<TMetaData, TGlobalStore, TStore>) => maybePromise<void>;
-export type EventAfterToolCall<TParams = Record<any, any>, TMetaData extends DefineMetaData<any> = {}, TGlobalStore extends StoreLike<any> = {}, TStore extends StoreLike<any> = {}> = (result: ToolHandlerReturnTypeNonAsync, params: TParams, tool: Tool<any>, context: AgentContext<TMetaData, TGlobalStore, TStore>) => maybePromise<void>;
+export type EventAfterToolCall<TParams = Record<any, any>, TMetaData extends DefineMetaData<any> = {}, TGlobalStore extends StoreLike<any> = {}, TStore extends StoreLike<any> = {}> = (result: ToolCallPayload, params: TParams, tool: Tool<any>, context: AgentContext<TMetaData, TGlobalStore, TStore>) => maybePromise<void>;
 export type callbackMap<TMetaData extends DefineMetaData<any>, TGlobalStore extends StoreLike<any>, TStore extends StoreLike<any>> = {
     [K in AgentAfterEventId]: K extends "after:stateUpdate" ? EventAfterStateUpdate<TMetaData, TGlobalStore, TStore> : K extends "after:step" ? EventAfterStep<TMetaData, TGlobalStore, TStore> : K extends "after:modelInvocation" ? EventAfterModelInvocation<TMetaData, TGlobalStore, TStore> : K extends "after:toolCall" ? EventAfterToolCall<any, TMetaData, TGlobalStore, TStore> : never;
 };

package/dist/src/eventBefore.d.ts

@@ -1,7 +1,8 @@
 import type { AgentDefaultEventId, eventResult } from "./event";
 import type { maybePromise, StoreLike } from "./types";
 import type { AgentContext } from "./agentContext";
-import type { OpenaiClientOptions, DefineMetaData, Tool, ChatCompletionAssistantMessageParam, ToolHandlerReturnTypeNonAsync } from "./fragola";
+import type { OpenaiClientOptions, DefineMetaData, Tool, ChatCompletionAssistantMessageParam } from "./fragola";
+import type { ToolCallPayload } from "./eventDefault";
 import type { CreateAgentOptions, StepOptions } from "./agent";
 import type OpenAI from "openai";
 import type { APIPromise } from "openai";
@@ -22,7 +23,7 @@ export type EventBeforeModelInvocation<TMetaData extends DefineMetaData<any>, TG
 export type ToolCallConfig<TParams = Record<any, any>> = {
     params: TParams;
 } | {
-    injectResult: ToolHandlerReturnTypeNonAsync;
+    injectConfig: ToolCallPayload;
 };
 export type EventBeforeToolCall<TParams = Record<any, any>, TMetaData extends DefineMetaData<any> = {}, TGlobalStore extends StoreLike<any> = {}, TStore extends StoreLike<any> = {}> = (config: ToolCallConfig<TParams>, tool: Tool<any>, context: AgentContext<TMetaData, TGlobalStore, TStore>) => maybePromise<ToolCallConfig<TParams>>;
 export type callbackMap<TMetaData extends DefineMetaData<any>, TGlobalStore extends StoreLike<any>, TStore extends StoreLike<any>> = {

package/dist/src/eventDefault.d.ts

@@ -40,8 +40,17 @@ export type ModelInvocationPayload<TMetaData extends DefineMetaData<any>> = Mode
     kind: "completion";
     data: ChatCompletionAssistantMessageParam<TMetaData>;
 };
+export type ToolCallPayload = {
+    success: false;
+    isValidationError?: boolean;
+    error?: unknown;
+    data: ToolHandlerReturnTypeNonAsync;
+} | {
+    success: true;
+    data: ToolHandlerReturnTypeNonAsync;
+};
 export type EventModelInvocation<TMetaData extends DefineMetaData<any>, TGlobalStore extends StoreLike<any>, TStore extends StoreLike<any>> = (payload: ModelInvocationPayload<TMetaData>, context: AgentContext<TMetaData, TGlobalStore, TStore>) => maybePromise<eventResult<ModelInvocationChunkResult | ChatCompletionAssistantMessageParam<TMetaData>>>;
-export type EventToolCall<TParams = Record<any, any>, TMetaData extends DefineMetaData<any> = {}, TGlobalStore extends StoreLike<any> = {}, TStore extends StoreLike<any> = {}> = (result: ToolHandlerReturnTypeNonAsync, params: TParams, tool: Tool<any>, context: AgentContext<TMetaData, TGlobalStore, TStore>) => maybePromise<eventResult<ToolHandlerReturnTypeNonAsync>>;
+export type EventToolCall<TParams = Record<any, any>, TMetaData extends DefineMetaData<any> = {}, TGlobalStore extends StoreLike<any> = {}, TStore extends StoreLike<any> = {}> = (result: ToolCallPayload, params: TParams, tool: Tool<any>, context: AgentContext<TMetaData, TGlobalStore, TStore>) => maybePromise<eventResult<ToolCallPayload>>;
 export type EventAiMessage<TMetaData extends DefineMetaData<any>, TGlobalStore extends StoreLike<any> = {}, TStore extends StoreLike<any> = {}> = (message: ChatCompletionAssistantMessageParam<TMetaData>, finish_reason: OpenAI.Chat.Completions.ChatCompletionChunk.Choice['finish_reason'], usage: OpenAI.Chat.Completions.ChatCompletionChunk['usage'], context: AgentContext<TMetaData, TGlobalStore, TStore>) => maybePromise<eventResult<ChatCompletionAssistantMessageParam>>;
 export type EventUserMessage<TMetaData extends DefineMetaData<any>, TGlobalStore extends StoreLike<any> = {}, TStore extends StoreLike<any> = {}> = (message: ChatCompletionUserMessageParam<TMetaData>, context: AgentContext<TMetaData, TGlobalStore, TStore>) => maybePromise<eventResult<ChatCompletionUserMessageParam>>;
 export type callbackMap<TMetaData extends DefineMetaData<any>, TGlobalStore extends StoreLike<any>, TStore extends StoreLike<any>> = {

package/dist/src/fragola.d.ts

@@ -55,6 +55,34 @@ export interface Tool<T extends z.ZodType<any, any> | string = any> {
      */
     schema?: T;
 }
+/**
+ * Create a tool for your agent using Zod schema or JSON schema.
+ *
+ * @example
+ * // Example: Weather tool using Zod schema
+ * import z from "zod";
+ * import { tool } from "./fragola";
+ *
+ * const getWeather = tool({
+ *   name: "getWeather",
+ *   description: "Get the current weather for a city.",
+ *   schema: z.object({ city: z.string() }),
+ *   handler: async ({ city }) => {
+ *     // Replace with real API call
+ *     return { city, temperature: 22, unit: "C" };
+ *   },
+ * });
+ *
+ * // Example: Weather tool using JSON schema string
+ * const getWeatherStringSchema = tool({
+ *   name: "getWeather",
+ *   description: "Get the current weather for a city.",
+ *   schema: '{ "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] }',
+ *   handler: async ({ city }: { city: string }) => {
+ *     return { city, temperature: 22, unit: "C" };
+ *   },
+ * });
+ */
 export declare const tool: <T extends z.ZodType<any, any> | string>(params: Tool<T>) => Tool<T>;
 export declare function stripMeta<T extends object>(data: (T & {
     meta?: any;
@@ -103,6 +131,7 @@ export interface FragolaEvents {
 export type ClientOptions = OpenaiClientOptions & PreferedModel & {
     events?: FragolaEvents;
 };
+/** Creates a fragola instance */
 export declare class Fragola<TGlobalStore extends StoreLike<any> = {}> {
     #private;
     private clientOptions;