@antipopp/agno-react 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -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, ToolCall, ChatMessage, ClientState, SessionEntry, AgentDetails, TeamDetails } 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,9 +19,13 @@ declare function AgnoProvider({ config, children }: AgnoProviderProps): react_js
 declare function useAgnoClient(): AgnoClient;
 
 /**
- * Tool handler function type
+ * Tool handler function type (now supports generative UI)
  */
 type ToolHandler = (args: Record<string, any>) => Promise<any>;
+/**
+ * Get a custom render function by key
+ */
+declare function getCustomRender(key: string): CustomRenderFunction | undefined;
 /**
  * Tool execution event payload
  */
@@ -111,6 +115,254 @@ 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.
+ */
+
+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
@@ -155,4 +407,4 @@ declare function useAgnoActions(): {
     error: string | undefined;
 };
 
-export { AgnoProvider, type AgnoProviderProps, type ToolExecutionEvent, type ToolHandler, type ToolHandlerContextValue, ToolHandlerProvider, type ToolHandlerProviderProps, 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, 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 };

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, ToolCall, ChatMessage, ClientState, SessionEntry, AgentDetails, TeamDetails } 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,9 +19,13 @@ declare function AgnoProvider({ config, children }: AgnoProviderProps): react_js
 declare function useAgnoClient(): AgnoClient;
 
 /**
- * Tool handler function type
+ * Tool handler function type (now supports generative UI)
  */
 type ToolHandler = (args: Record<string, any>) => Promise<any>;
+/**
+ * Get a custom render function by key
+ */
+declare function getCustomRender(key: string): CustomRenderFunction | undefined;
 /**
  * Tool execution event payload
  */
@@ -111,6 +115,254 @@ 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.
+ */
+
+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
@@ -155,4 +407,4 @@ declare function useAgnoActions(): {
     error: string | undefined;
 };
 
-export { AgnoProvider, type AgnoProviderProps, type ToolExecutionEvent, type ToolHandler, type ToolHandlerContextValue, ToolHandlerProvider, type ToolHandlerProviderProps, 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, 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 };