@antipopp/agno-react 0.9.0 → 0.11.0

package/README.md

@@ -38,6 +38,10 @@ function App() {
         },
         params: {           // Optional: Global query params for all requests
           locale: 'en-US'
+        },
+        dependencies: {     // Optional: Global run dependencies for sendMessage
+          tenantId: 'tenant-1',
+          locale: 'en-US'
         }
       }}
     >
@@ -133,9 +137,14 @@ await sendMessage('Hello!');
 // Send with FormData (for file uploads)
 const formData = new FormData();
 formData.append('message', 'Hello!');
-formData.append('file', file);
+formData.append('files', file);
 await sendMessage(formData);
 
+// Send with files option
+await sendMessage('Hello!', {
+  files: [file]
+});
+
 // Send with custom headers
 await sendMessage('Hello!', {
   headers: { 'X-Custom': 'value' }
@@ -151,6 +160,14 @@ await sendMessage('Hello!', {
   headers: { 'X-Request-ID': '12345' },
   params: { debug: 'true' }
 });
+
+// Send with per-request dependencies (merged with/override provider config)
+await sendMessage('Hello!', {
+  dependencies: {
+    locale: 'fr-FR', // overrides global dependency
+    feature: 'rag'   // merged as a new dependency key
+  }
+});
 ```
 
 #### `clearMessages()`

package/dist/index.d.mts

@@ -1,16 +1,37 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import React from 'react';
-import { AgnoClient } from '@antipopp/agno-client';
 import * as _antipopp_agno_types from '@antipopp/agno-types';
-import { AgnoClientConfig, ToolCall, CustomRenderFunction, UIComponentSpec, ChartComponentSpec, CardData, CardGridComponentSpec, TableColumn, TableComponentSpec, MarkdownComponentSpec, ArtifactComponentSpec, ToolHandlerResult, ChatMessage, ClientState, SessionEntry, AgentDetails, TeamDetails } from '@antipopp/agno-types';
+import { UIComponentSpec, AgnoClientConfig, ToolCall, CustomRenderFunction, AgentDetails, TeamDetails, ChatMessage, ClientState, SessionEntry, ChartComponentSpec, ArtifactComponentSpec, CardData, CardGridComponentSpec, TableColumn, MarkdownComponentSpec, TableComponentSpec, ToolHandlerResult } from '@antipopp/agno-types';
 export { AgentDetails, AgnoClientConfig, ArtifactComponentSpec, CardData, CardGridComponentSpec, ChartComponentSpec, ChartSeries, ChatMessage, ClientState, CustomComponentSpec, GenerativeUIData, MarkdownComponentSpec, RunEvent, SessionEntry, TableColumn, TableComponentSpec, TeamDetails, ToolCall, ToolHandlerResult, UIComponentSpec } from '@antipopp/agno-types';
+import React, { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { AgnoClient } from '@antipopp/agno-client';
+
+/**
+ * Generative UI Renderer
+ *
+ * Renders UI components based on specifications from the agent.
+ * Supports both registry-based components and custom render functions.
+ */
+
+interface GenerativeUIRendererProps {
+    /** The UI component specification to render */
+    spec: UIComponentSpec;
+    /** Optional className for styling */
+    className?: string;
+    /** Error boundary fallback */
+    onError?: (error: Error) => void;
+}
+/**
+ * Main Generative UI Renderer component
+ */
+declare function GenerativeUIRenderer({ spec, className, onError, }: GenerativeUIRendererProps): React.ReactElement;
 
 interface AgnoProviderProps {
     config: AgnoClientConfig;
     children: React.ReactNode;
 }
 /**
- * Provider component that creates and manages an AgnoClient instance
+ * Provider component that creates and manages an AgnoClient instance.
+ * Handles cleanup of all module-level registries on unmount to prevent memory leaks.
  */
 declare function AgnoProvider({ config, children }: AgnoProviderProps): react_jsx_runtime.JSX.Element;
 /**
@@ -21,11 +42,16 @@ declare function useAgnoClient(): AgnoClient;
 /**
  * Tool handler function type (now supports generative UI)
  */
-type ToolHandler = (args: Record<string, any>) => Promise<any>;
+type ToolHandler = (args: Record<string, unknown> | string) => Promise<unknown>;
 /**
  * Get a custom render function by key
  */
 declare function getCustomRender(key: string): CustomRenderFunction | undefined;
+/**
+ * Clear all custom render functions from the registry.
+ * Call this during cleanup (e.g., when AgnoProvider unmounts) to prevent memory leaks.
+ */
+declare function clearCustomRenderRegistry(): void;
 /**
  * Tool execution event payload
  */
@@ -108,7 +134,7 @@ interface ToolHandlerProviderProps {
  * </ToolHandlerProvider>
  * ```
  */
-declare function ToolHandlerProvider({ handlers: initialHandlers, children }: ToolHandlerProviderProps): react_jsx_runtime.JSX.Element;
+declare function ToolHandlerProvider({ handlers: initialHandlers, children, }: ToolHandlerProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access global tool handlers
  *
@@ -122,24 +148,62 @@ declare function ToolHandlerProvider({ handlers: initialHandlers, children }: To
 declare function useToolHandlers(): ToolHandlerContextValue | null;
 
 /**
- * Generative UI Renderer
- *
- * Renders UI components based on specifications from the agent.
- * Supports both registry-based components and custom render functions.
+ * Hook for common actions like initialization, fetching agents/teams
  */
+declare function useAgnoActions(): {
+    initialize: (options?: {
+        params?: Record<string, string>;
+    }) => Promise<{
+        agents: AgentDetails[];
+        teams: TeamDetails[];
+    }>;
+    checkStatus: (options?: {
+        params?: Record<string, string>;
+    }) => Promise<boolean>;
+    fetchAgents: (options?: {
+        params?: Record<string, string>;
+    }) => Promise<AgentDetails[]>;
+    fetchTeams: (options?: {
+        params?: Record<string, string>;
+    }) => Promise<TeamDetails[]>;
+    updateConfig: (updates: Partial<Parameters<(updates: Partial<_antipopp_agno_types.AgnoClientConfig>) => void>[0]>) => void;
+    isInitializing: boolean;
+    error: string | undefined;
+};
 
-interface GenerativeUIRendererProps {
-    /** The UI component specification to render */
-    spec: UIComponentSpec;
-    /** Optional className for styling */
-    className?: string;
-    /** Error boundary fallback */
-    onError?: (error: Error) => void;
-}
 /**
- * Main Generative UI Renderer component
+ * Main hook for chat interactions
+ * Provides messages, state, and methods to interact with the agent
  */
-declare function GenerativeUIRenderer({ spec, className, onError, }: GenerativeUIRendererProps): React.ReactElement;
+declare function useAgnoChat(): {
+    messages: ChatMessage[];
+    sendMessage: (message: string | FormData, options?: Parameters<(message: string | FormData, options?: _antipopp_agno_types.SendMessageOptions) => Promise<void>>[1]) => Promise<void>;
+    clearMessages: () => void;
+    cancelRun: () => Promise<void>;
+    isStreaming: boolean;
+    isRefreshing: boolean;
+    isPaused: boolean;
+    isCancelling: boolean;
+    currentRunId: string | undefined;
+    error: string | undefined;
+    state: ClientState;
+};
+
+/**
+ * Hook for session management
+ */
+declare function useAgnoSession(): {
+    sessions: SessionEntry[];
+    currentSessionId: string | undefined;
+    loadSession: (sessionId: string, options?: {
+        params?: Record<string, string>;
+    }) => Promise<ChatMessage[]>;
+    fetchSessions: (options?: {
+        params?: Record<string, string>;
+    }) => Promise<SessionEntry[]>;
+    isLoading: boolean;
+    error: string | undefined;
+};
 
 /**
  * Component Registry for Generative UI
@@ -147,16 +211,17 @@ declare function GenerativeUIRenderer({ spec, className, onError, }: GenerativeU
  * Maps component specifications to actual React components.
  * Allows registering custom components at runtime.
  */
+
 /**
  * Component renderer function type
  */
-type ComponentRenderer = (props: any) => any;
+type ComponentRenderer = (props: Record<string, unknown>) => ReactNode;
 /**
  * Component registry class
  */
 declare class ComponentRegistry {
     private static instance;
-    private components;
+    private readonly components;
     private constructor();
     /**
      * Get the singleton instance
@@ -190,6 +255,12 @@ declare class ComponentRegistry {
      * Clear all registered components
      */
     clear(): void;
+    /**
+     * Reset the singleton instance.
+     * Call this during cleanup (e.g., when AgnoProvider unmounts) to prevent memory leaks.
+     * After calling this, getInstance() will create a fresh instance.
+     */
+    static resetInstance(): void;
 }
 /**
  * Get the global component registry instance
@@ -211,6 +282,12 @@ declare function getChartComponent(name: string): ComponentRenderer | undefined;
  * manually constructing the full specification object.
  */
 
+type DataRow = Record<string, unknown>;
+type SeriesInput = Array<{
+    key: string;
+    label?: string;
+    color?: string;
+}>;
 /**
  * Chart helper options
  */
@@ -220,7 +297,7 @@ interface ChartHelperOptions {
     /** Chart description */
     description?: string;
     /** Layout preference */
-    layout?: 'inline' | 'artifact';
+    layout?: "inline" | "artifact";
     /** Show legend */
     showLegend?: boolean;
     /** Show grid */
@@ -233,40 +310,28 @@ interface ChartHelperOptions {
 /**
  * Create a bar chart specification
  */
-declare function createBarChart(data: any[], xKey: string, bars: Array<{
-    key: string;
-    label?: string;
-    color?: string;
-}>, options?: ChartHelperOptions): ChartComponentSpec;
+declare function createBarChart(data: DataRow[], xKey: string, bars: SeriesInput, options?: ChartHelperOptions): ChartComponentSpec;
 /**
  * Create a line chart specification
  */
-declare function createLineChart(data: any[], xKey: string, lines: Array<{
-    key: string;
-    label?: string;
-    color?: string;
-}>, options?: ChartHelperOptions): ChartComponentSpec;
+declare function createLineChart(data: DataRow[], xKey: string, lines: SeriesInput, options?: ChartHelperOptions): ChartComponentSpec;
 /**
  * Create a pie chart specification
  */
-declare function createPieChart(data: any[], dataKey: string, nameKey: string, options?: ChartHelperOptions & {
+declare function createPieChart(data: DataRow[], dataKey: string, nameKey: string, options?: ChartHelperOptions & {
     showLabel?: boolean;
 }): ChartComponentSpec;
 /**
  * Create an area chart specification
  */
-declare function createAreaChart(data: any[], xKey: string, areas: Array<{
-    key: string;
-    label?: string;
-    color?: string;
-}>, options?: ChartHelperOptions): ChartComponentSpec;
+declare function createAreaChart(data: DataRow[], xKey: string, areas: SeriesInput, options?: ChartHelperOptions): ChartComponentSpec;
 /**
  * Card grid helper options
  */
 interface CardGridHelperOptions {
     title?: string;
     description?: string;
-    layout?: 'inline' | 'artifact';
+    layout?: "inline" | "artifact";
     columns?: {
         default?: number;
         sm?: number;
@@ -274,7 +339,7 @@ interface CardGridHelperOptions {
         lg?: number;
         xl?: number;
     };
-    variant?: 'default' | 'bordered' | 'elevated';
+    variant?: "default" | "bordered" | "elevated";
 }
 /**
  * Create a card grid specification
@@ -285,8 +350,8 @@ declare function createCardGrid(cards: CardData[], options?: CardGridHelperOptio
  */
 declare function createCard(id: string, title: string, description?: string, options?: {
     image?: string;
-    metadata?: Record<string, any>;
-    actions?: CardData['actions'];
+    metadata?: Record<string, unknown>;
+    actions?: CardData["actions"];
 }): CardData;
 /**
  * Table helper options
@@ -294,27 +359,27 @@ declare function createCard(id: string, title: string, description?: string, opt
 interface TableHelperOptions {
     title?: string;
     description?: string;
-    layout?: 'inline' | 'artifact';
+    layout?: "inline" | "artifact";
     sortable?: boolean;
     filterable?: boolean;
     pagination?: {
         pageSize?: number;
         pageSizeOptions?: number[];
     };
-    density?: 'comfortable' | 'compact';
+    density?: "comfortable" | "compact";
 }
 /**
  * Create a table specification
  */
-declare function createTable(data: Record<string, any>[], columns: TableColumn[], options?: TableHelperOptions): TableComponentSpec;
+declare function createTable(data: DataRow[], columns: TableColumn[], options?: TableHelperOptions): TableComponentSpec;
 /**
  * Create a table column definition
  */
 declare function createColumn(key: string, header: string, options?: {
     width?: number | string;
     sortable?: boolean;
-    cellType?: 'text' | 'number' | 'date' | 'badge' | 'link';
-    format?: TableColumn['format'];
+    cellType?: "text" | "number" | "date" | "badge" | "link";
+    format?: TableColumn["format"];
 }): TableColumn;
 /**
  * Create a markdown specification
@@ -322,7 +387,7 @@ declare function createColumn(key: string, header: string, options?: {
 declare function createMarkdown(content: string, options?: {
     title?: string;
     description?: string;
-    layout?: 'inline' | 'artifact';
+    layout?: "inline" | "artifact";
     syntaxHighlight?: boolean;
 }): MarkdownComponentSpec;
 /**
@@ -331,35 +396,31 @@ declare function createMarkdown(content: string, options?: {
 declare function createArtifact(content: UIComponentSpec[], options?: {
     title?: string;
     description?: string;
-    variant?: 'default' | 'bordered' | 'elevated';
+    variant?: "default" | "bordered" | "elevated";
 }): ArtifactComponentSpec;
 /**
  * Smart chart creator - automatically chooses the best chart type based on data
  */
-declare function createSmartChart(data: any[], options?: {
+declare function createSmartChart(data: DataRow[], options?: {
     title?: string;
     description?: string;
-    layout?: 'inline' | 'artifact';
+    layout?: "inline" | "artifact";
     xKey?: string;
     yKeys?: string[];
-    preferredType?: 'bar' | 'line' | 'area' | 'pie';
+    preferredType?: "bar" | "line" | "area" | "pie";
 }): ChartComponentSpec;
 /**
  * Wrap data and UI into a ToolHandlerResult
  */
-declare function createToolResult(data: any, ui: UIComponentSpec): ToolHandlerResult;
+declare function createToolResult(data: unknown, ui: UIComponentSpec): ToolHandlerResult;
 /**
  * Quick helper: create a tool result with a bar chart
  */
-declare function resultWithBarChart(data: any[], xKey: string, bars: Array<{
-    key: string;
-    label?: string;
-    color?: string;
-}>, options?: ChartHelperOptions): ToolHandlerResult;
+declare function resultWithBarChart(data: DataRow[], xKey: string, bars: SeriesInput, options?: ChartHelperOptions): ToolHandlerResult;
 /**
  * Quick helper: create a tool result with a smart chart
  */
-declare function resultWithSmartChart(data: any[], options?: Parameters<typeof createSmartChart>[1]): ToolHandlerResult;
+declare function resultWithSmartChart(data: DataRow[], options?: Parameters<typeof createSmartChart>[1]): ToolHandlerResult;
 /**
  * Quick helper: create a tool result with a card grid
  */
@@ -367,64 +428,6 @@ declare function resultWithCardGrid(cards: CardData[], options?: CardGridHelperO
 /**
  * Quick helper: create a tool result with a table
  */
-declare function resultWithTable(data: Record<string, any>[], columns: TableColumn[], options?: TableHelperOptions): ToolHandlerResult;
-
-/**
- * Main hook for chat interactions
- * Provides messages, state, and methods to interact with the agent
- */
-declare function useAgnoChat(): {
-    messages: ChatMessage[];
-    sendMessage: (message: string | FormData, options?: {
-        headers?: Record<string, string>;
-        params?: Record<string, string>;
-    }) => Promise<void>;
-    clearMessages: () => void;
-    isStreaming: boolean;
-    isRefreshing: boolean;
-    isPaused: boolean;
-    error: string | undefined;
-    state: ClientState;
-};
-
-/**
- * Hook for session management
- */
-declare function useAgnoSession(): {
-    sessions: SessionEntry[];
-    currentSessionId: string | undefined;
-    loadSession: (sessionId: string, options?: {
-        params?: Record<string, string>;
-    }) => Promise<ChatMessage[]>;
-    fetchSessions: (options?: {
-        params?: Record<string, string>;
-    }) => Promise<SessionEntry[]>;
-    isLoading: boolean;
-    error: string | undefined;
-};
-
-/**
- * Hook for common actions like initialization, fetching agents/teams
- */
-declare function useAgnoActions(): {
-    initialize: (options?: {
-        params?: Record<string, string>;
-    }) => Promise<{
-        agents: AgentDetails[];
-        teams: TeamDetails[];
-    }>;
-    checkStatus: (options?: {
-        params?: Record<string, string>;
-    }) => Promise<boolean>;
-    fetchAgents: (options?: {
-        params?: Record<string, string>;
-    }) => Promise<AgentDetails[]>;
-    fetchTeams: (options?: {
-        params?: Record<string, string>;
-    }) => Promise<TeamDetails[]>;
-    updateConfig: (updates: Partial<Parameters<(updates: Partial<_antipopp_agno_types.AgnoClientConfig>) => void>[0]>) => void;
-    isInitializing: boolean;
-    error: string | undefined;
-};
+declare function resultWithTable(data: DataRow[], columns: TableColumn[], options?: TableHelperOptions): ToolHandlerResult;
 
-export { AgnoProvider, type AgnoProviderProps, type CardGridHelperOptions, type ChartHelperOptions, ComponentRegistry, type ComponentRenderer, GenerativeUIRenderer, type GenerativeUIRendererProps, type TableHelperOptions, type ToolExecutionEvent, type ToolHandler, type ToolHandlerContextValue, ToolHandlerProvider, type ToolHandlerProviderProps, createAreaChart, createArtifact, createBarChart, createCard, createCardGrid, createColumn, createLineChart, createMarkdown, createPieChart, createSmartChart, createTable, createToolResult, getChartComponent, getComponentRegistry, getCustomRender, registerChartComponent, resultWithBarChart, resultWithCardGrid, resultWithSmartChart, resultWithTable, useAgnoActions, useAgnoChat, useAgnoClient, useAgnoSession, useAgnoToolExecution, useToolHandlers };
+export { AgnoProvider, type AgnoProviderProps, type CardGridHelperOptions, type ChartHelperOptions, ComponentRegistry, type ComponentRenderer, GenerativeUIRenderer, type GenerativeUIRendererProps, type TableHelperOptions, type ToolExecutionEvent, type ToolHandler, type ToolHandlerContextValue, ToolHandlerProvider, type ToolHandlerProviderProps, clearCustomRenderRegistry, createAreaChart, createArtifact, createBarChart, createCard, createCardGrid, createColumn, createLineChart, createMarkdown, createPieChart, createSmartChart, createTable, createToolResult, getChartComponent, getComponentRegistry, getCustomRender, registerChartComponent, resultWithBarChart, resultWithCardGrid, resultWithSmartChart, resultWithTable, useAgnoActions, useAgnoChat, useAgnoClient, useAgnoSession, useAgnoToolExecution, useToolHandlers };