@antipopp/agno-react 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -2,8 +2,8 @@ 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, ChatMessage, ClientState, SessionEntry, AgentDetails, TeamDetails, ToolCall } from '@antipopp/agno-types';
-export { AgentDetails, AgnoClientConfig, ChatMessage, ClientState, RunEvent, SessionEntry, TeamDetails, ToolCall } 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';
+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';
 
 interface AgnoProviderProps {
     config: AgnoClientConfig;
@@ -19,53 +19,13 @@ declare function AgnoProvider({ config, children }: AgnoProviderProps): react_js
 declare function useAgnoClient(): AgnoClient;
 
 /**
- * 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>;
-    }) => Promise<void>;
-    clearMessages: () => void;
-    isStreaming: boolean;
-    isPaused: boolean;
-    error: string | undefined;
-    state: ClientState;
-};
-
-/**
- * Hook for session management
- */
-declare function useAgnoSession(): {
-    sessions: SessionEntry[];
-    currentSessionId: string | undefined;
-    loadSession: (sessionId: string) => Promise<ChatMessage[]>;
-    fetchSessions: () => Promise<SessionEntry[]>;
-    isLoading: boolean;
-    error: string | undefined;
-};
-
-/**
- * Hook for common actions like initialization, fetching agents/teams
+ * Tool handler function type (now supports generative UI)
  */
-declare function useAgnoActions(): {
-    initialize: () => Promise<{
-        agents: AgentDetails[];
-        teams: TeamDetails[];
-    }>;
-    checkStatus: () => Promise<boolean>;
-    fetchAgents: () => Promise<AgentDetails[]>;
-    fetchTeams: () => Promise<TeamDetails[]>;
-    updateConfig: (updates: Partial<Parameters<(updates: Partial<_antipopp_agno_types.AgnoClientConfig>) => void>[0]>) => void;
-    isInitializing: boolean;
-    error: string | undefined;
-};
-
+type ToolHandler = (args: Record<string, any>) => Promise<any>;
 /**
- * Tool handler function type
+ * Get a custom render function by key
  */
-type ToolHandler = (args: Record<string, any>) => Promise<any>;
+declare function getCustomRender(key: string): CustomRenderFunction | undefined;
 /**
  * Tool execution event payload
  */
@@ -77,7 +37,7 @@ interface ToolExecutionEvent {
 /**
  * Hook for handling frontend tool execution (HITL)
  *
- * @param handlers - Map of tool names to handler functions
+ * @param handlers - Map of tool names to handler functions (local handlers)
  * @param autoExecute - Whether to automatically execute tools when paused (default: true)
  *
  * @example
@@ -96,7 +56,7 @@ interface ToolExecutionEvent {
  * const { isPaused, isExecuting, pendingTools } = useAgnoToolExecution(toolHandlers);
  * ```
  */
-declare function useAgnoToolExecution(handlers: Record<string, ToolHandler>, autoExecute?: boolean): {
+declare function useAgnoToolExecution(handlers?: Record<string, ToolHandler>, autoExecute?: boolean): {
     /** Whether the run is currently paused awaiting tool execution */
     isPaused: boolean;
     /** Whether tools are currently being executed */
@@ -113,4 +73,338 @@ declare function useAgnoToolExecution(handlers: Record<string, ToolHandler>, aut
     executionError: string | undefined;
 };
 
-export { AgnoProvider, type AgnoProviderProps, type ToolExecutionEvent, type ToolHandler, useAgnoActions, useAgnoChat, useAgnoClient, useAgnoSession, useAgnoToolExecution };
+/**
+ * Context value for tool handler registry
+ */
+interface ToolHandlerContextValue {
+    handlers: Record<string, ToolHandler>;
+    registerHandler: (name: string, handler: ToolHandler) => void;
+    unregisterHandler: (name: string) => void;
+}
+interface ToolHandlerProviderProps {
+    handlers?: Record<string, ToolHandler>;
+    children: React.ReactNode;
+}
+/**
+ * Provider component that manages global tool handlers
+ *
+ * @example
+ * ```tsx
+ * const globalHandlers = {
+ *   fill_form: async (args) => {
+ *     // Implementation
+ *     return { success: true };
+ *   }
+ * };
+ *
+ * <ToolHandlerProvider handlers={globalHandlers}>
+ *   <App />
+ * </ToolHandlerProvider>
+ * ```
+ */
+declare function ToolHandlerProvider({ handlers: initialHandlers, children }: ToolHandlerProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access global tool handlers
+ *
+ * @returns Tool handler context value or null if not within ToolHandlerProvider
+ *
+ * @example
+ * ```tsx
+ * const { handlers, registerHandler } = useToolHandlers() || { handlers: {} };
+ * ```
+ */
+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.
+ */
+
+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;
+
+/**
+ * Component Registry for Generative UI
+ *
+ * Maps component specifications to actual React components.
+ * Allows registering custom components at runtime.
+ */
+/**
+ * Component renderer function type
+ */
+type ComponentRenderer = (props: any) => any;
+/**
+ * Component registry class
+ */
+declare class ComponentRegistry {
+    private static instance;
+    private components;
+    private constructor();
+    /**
+     * Get the singleton instance
+     */
+    static getInstance(): ComponentRegistry;
+    /**
+     * Register a component renderer
+     */
+    register(type: string, renderer: ComponentRenderer): void;
+    /**
+     * Register multiple components at once
+     */
+    registerBatch(components: Record<string, ComponentRenderer>): void;
+    /**
+     * Get a registered component renderer
+     */
+    get(type: string): ComponentRenderer | undefined;
+    /**
+     * Check if a component is registered
+     */
+    has(type: string): boolean;
+    /**
+     * Unregister a component
+     */
+    unregister(type: string): void;
+    /**
+     * Get all registered component types
+     */
+    getRegisteredTypes(): string[];
+    /**
+     * Clear all registered components
+     */
+    clear(): void;
+}
+/**
+ * Get the global component registry instance
+ */
+declare function getComponentRegistry(): ComponentRegistry;
+/**
+ * Helper to register a chart component
+ */
+declare function registerChartComponent(name: string, renderer: ComponentRenderer): void;
+/**
+ * Helper to get a chart component
+ */
+declare function getChartComponent(name: string): ComponentRenderer | undefined;
+
+/**
+ * Helper utilities for creating UI component specifications
+ *
+ * These helpers make it easy to create common UI patterns without
+ * manually constructing the full specification object.
+ */
+
+/**
+ * Chart helper options
+ */
+interface ChartHelperOptions {
+    /** Chart title */
+    title?: string;
+    /** Chart description */
+    description?: string;
+    /** Layout preference */
+    layout?: 'inline' | 'artifact';
+    /** Show legend */
+    showLegend?: boolean;
+    /** Show grid */
+    showGrid?: boolean;
+    /** Chart height */
+    height?: number | string;
+    /** Chart width */
+    width?: number | string;
+}
+/**
+ * Create a bar chart specification
+ */
+declare function createBarChart(data: any[], xKey: string, bars: Array<{
+    key: string;
+    label?: string;
+    color?: string;
+}>, 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;
+/**
+ * Create a pie chart specification
+ */
+declare function createPieChart(data: any[], 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;
+/**
+ * Card grid helper options
+ */
+interface CardGridHelperOptions {
+    title?: string;
+    description?: string;
+    layout?: 'inline' | 'artifact';
+    columns?: {
+        default?: number;
+        sm?: number;
+        md?: number;
+        lg?: number;
+        xl?: number;
+    };
+    variant?: 'default' | 'bordered' | 'elevated';
+}
+/**
+ * Create a card grid specification
+ */
+declare function createCardGrid(cards: CardData[], options?: CardGridHelperOptions): CardGridComponentSpec;
+/**
+ * Create a simple card
+ */
+declare function createCard(id: string, title: string, description?: string, options?: {
+    image?: string;
+    metadata?: Record<string, any>;
+    actions?: CardData['actions'];
+}): CardData;
+/**
+ * Table helper options
+ */
+interface TableHelperOptions {
+    title?: string;
+    description?: string;
+    layout?: 'inline' | 'artifact';
+    sortable?: boolean;
+    filterable?: boolean;
+    pagination?: {
+        pageSize?: number;
+        pageSizeOptions?: number[];
+    };
+    density?: 'comfortable' | 'compact';
+}
+/**
+ * Create a table specification
+ */
+declare function createTable(data: Record<string, any>[], 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'];
+}): TableColumn;
+/**
+ * Create a markdown specification
+ */
+declare function createMarkdown(content: string, options?: {
+    title?: string;
+    description?: string;
+    layout?: 'inline' | 'artifact';
+    syntaxHighlight?: boolean;
+}): MarkdownComponentSpec;
+/**
+ * Create an artifact container with multiple child components
+ */
+declare function createArtifact(content: UIComponentSpec[], options?: {
+    title?: string;
+    description?: string;
+    variant?: 'default' | 'bordered' | 'elevated';
+}): ArtifactComponentSpec;
+/**
+ * Smart chart creator - automatically chooses the best chart type based on data
+ */
+declare function createSmartChart(data: any[], options?: {
+    title?: string;
+    description?: string;
+    layout?: 'inline' | 'artifact';
+    xKey?: string;
+    yKeys?: string[];
+    preferredType?: 'bar' | 'line' | 'area' | 'pie';
+}): ChartComponentSpec;
+/**
+ * Wrap data and UI into a ToolHandlerResult
+ */
+declare function createToolResult(data: any, 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;
+/**
+ * Quick helper: create a tool result with a smart chart
+ */
+declare function resultWithSmartChart(data: any[], options?: Parameters<typeof createSmartChart>[1]): ToolHandlerResult;
+/**
+ * Quick helper: create a tool result with a card grid
+ */
+declare function resultWithCardGrid(cards: CardData[], options?: CardGridHelperOptions): ToolHandlerResult;
+/**
+ * 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>;
+    }) => Promise<void>;
+    clearMessages: () => void;
+    isStreaming: boolean;
+    isPaused: boolean;
+    error: string | undefined;
+    state: ClientState;
+};
+
+/**
+ * Hook for session management
+ */
+declare function useAgnoSession(): {
+    sessions: SessionEntry[];
+    currentSessionId: string | undefined;
+    loadSession: (sessionId: string) => Promise<ChatMessage[]>;
+    fetchSessions: () => Promise<SessionEntry[]>;
+    isLoading: boolean;
+    error: string | undefined;
+};
+
+/**
+ * Hook for common actions like initialization, fetching agents/teams
+ */
+declare function useAgnoActions(): {
+    initialize: () => Promise<{
+        agents: AgentDetails[];
+        teams: TeamDetails[];
+    }>;
+    checkStatus: () => Promise<boolean>;
+    fetchAgents: () => Promise<AgentDetails[]>;
+    fetchTeams: () => Promise<TeamDetails[]>;
+    updateConfig: (updates: Partial<Parameters<(updates: Partial<_antipopp_agno_types.AgnoClientConfig>) => void>[0]>) => void;
+    isInitializing: boolean;
+    error: string | undefined;
+};
+
+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 };