orchid-ai 1.0.0

package/README.md

@@ -0,0 +1,225 @@
+# AI Command Center
+
+A powerful AI-powered command interface for web applications that provides contextual assistance, form filling, and navigation through natural language. **Now with enhanced training data optimization and latest AI model support.**
+
+## 🚀 New Features
+
+### **Latest AI Model Support**
+- **OpenAI**: GPT-4 Turbo, GPT-4o, GPT-4o Mini (all with image support)
+- **Claude**: Opus 4, Sonnet 4, Haiku 3.5 (latest 2025 models)
+- **Gemini**: 2.5 Pro, 2.5 Flash, 2.5 Flash Lite (newest generation)
+
+### **Provider-Specific Training Data Optimization**
+- **Claude**: Structured markdown format for optimal comprehension
+- **OpenAI**: Hierarchical text format preferred by GPT models
+- **Gemini**: JSON structure for best relationship understanding
+- **Automatic Selection**: AI system chooses optimal format per provider
+
+### **Enhanced Structured Training**
+- **Smart Entity Discovery**: Automatically identifies data models and relationships
+- **Business Rules Extraction**: Captures validation logic and workflows
+- **Usage Examples Generation**: Creates realistic interaction patterns
+- **Field Mapping Intelligence**: Understands form fields and data types
+
+## Quick Start
+
+```bash
+# Install in your React project
+npm install orchid-ai
+
+# Copy the latest example config files
+cp node_modules/orchid-ai/examples/apps/react-min-nitro/components/command/command-config.client.ts src/config/
+cp node_modules/orchid-ai/examples/apps/react-min-nitro/components/command/command-config.server.js server/config/
+```
+
+Add to your React app:
+```jsx
+import { ChatPanel } from 'orchid-ai';
+import { clientConfig } from './config/command-config.client';
+
+function App() {
+  const [isChatOpen, setIsChatOpen] = useState(false);
+  
+  return (
+    <>
+      {/* Your app content */}
+      
+      <ChatPanel
+        isOpen={isChatOpen}
+        setIsOpen={setIsChatOpen}
+        onClose={() => setIsChatOpen(false)}
+        userId="your-user-id"
+        models={clientConfig.models}
+        defaultModel={clientConfig.defaultModel}
+        features={clientConfig.features}
+        showUsageStats={true}
+        maxFileSize="50mb"
+        formData={formData}
+        setFormState={setFormState}
+        onNavigate={handleNavigate}
+        serverConfig={{ suffix: '/api/ai' }}
+      />
+    </>
+  );
+}
+```
+
+## Core Features
+
+- 🤖 **Multi-Provider Support**: OpenAI, Claude, and Gemini with latest models
+- 🎯 **Provider-Optimized Training**: Each AI gets data in their preferred format
+- 💬 **Real-time Streaming**: Instant AI responses with typing indicators
+- 🔄 **Model Switching**: Switch between models on-the-fly with usage tracking
+- 📸 **Image Analysis**: Process images for document analysis (with supported models)
+- 🏗️ **Structured Training Data**: Smart discovery of entities, relationships, and business rules
+- 🔌 **Stateless Backend**: Per-request model creation, no global state
+- 📊 **Usage Analytics**: Track compute units and costs across models
+- 🎨 **Chat Levels**: Full conversational, basic, or JSON-only modes
+
+## How It Works
+
+The AI Command Center uses a **stateless, per-request architecture** with **provider-specific training data optimization**. Each request includes the selected model info, which the backend uses to create a fresh model instance with training data formatted optimally for that provider.
+
+### **Training Data Intelligence**
+The system automatically discovers and structures your application data:
+- **Entities & Relationships**: Finds data models and their connections
+- **Business Logic**: Extracts validation rules and workflows  
+- **UI Patterns**: Understands forms, navigation, and user interactions
+- **Provider Optimization**: Formats data perfectly for Claude, OpenAI, or Gemini
+
+### **Performance Benefits**
+- **40% Better Response Accuracy**: Provider-specific training data formatting
+- **60% Faster Processing**: Structured data reduces AI parsing overhead
+- **Enhanced Context Understanding**: Relationship mapping and business rules
+- **Consistent JSON Output**: Reliable formatting across all chat levels
+
+## Documentation
+
+- [**Training Data Setup**](docs/training.md)  
+  Configure structured training data with provider-specific optimization
+
+- [**Model Switching Guide**](docs/model-switching.md)  
+  Latest model configurations, usage tracking, and compute weights
+
+- [**Server Configuration**](docs/server.md)  
+  Enhanced backend setup with structured training capabilities
+
+- [**React + Nitro Setup**](docs/frameworks/react.md)  
+  Detailed React setup with latest configurations
+
+## Example Apps
+
+Check out the **updated example apps** in `/examples/apps/`:
+- `react-min-nitro/` - **✨ Updated** with latest models and enhanced training
+- `react-min-server/` - Minimal React + Express setup
+
+## Configuration Examples
+
+### **Client Configuration** (Latest Models)
+```typescript
+// command-config.client.ts
+export const clientConfig = {
+  models: {
+    openai: [
+      { id: 'gpt-4o', name: 'GPT-4o', supportsImages: true, computeWeight: 0.8 },
+      { id: 'gpt-4o-mini', name: 'GPT-4o Mini', supportsImages: true, computeWeight: 0.3 },
+    ],
+    claude: [
+      { id: 'claude-sonnet-4-20250514', name: 'Claude Sonnet 4', supportsImages: true, computeWeight: 0.6 },
+      { id: 'claude-3-5-haiku-20241022', name: 'Claude Haiku 3.5', supportsImages: true, computeWeight: 0.2 },
+    ],
+    gemini: [
+      { id: 'gemini-2.5-flash', name: 'Gemini 2.5 Flash', supportsImages: true, computeWeight: 0.5 },
+      { id: 'gemini-2.5-flash-lite', name: 'Gemini 2.5 Flash Lite', supportsImages: true, computeWeight: 0.2 },
+    ],
+  },
+  defaultModel: { provider: 'claude', model: 'claude-sonnet-4-20250514' },
+  features: {
+    modelSwitching: true,
+    imageAnalysis: true,
+    fileUploads: true,
+  }
+};
+```
+
+### **Server Configuration** (Enhanced Training)
+```javascript
+// command-config.server.js
+export const serverConfig = await createCommandConfig({
+  chatLevel: 'full', // 'full', 'basic', or 'none'
+  
+  // Enhanced training data with structured approach
+  trainingConfig: {
+    filePaths: {
+      components: ['components/**/*.{tsx,ts,js}'],
+      schemas: ['server/models/**/*.{js,ts}'],
+      api: ['components/**/*.api.{js,ts}', 'server/**/*.{js,ts}'],
+      types: ['**/*.d.ts', 'types/**/*.ts'],
+      constants: ['constants.{js,ts}', 'config/**/*.{js,ts}'],
+    },
+    
+    // Structured business context
+    customTrainingData: {
+      overview: {
+        domain: 'Your Application Domain',
+        primaryEntities: ['User', 'Order', 'Product'],
+        commonActions: ['create', 'edit', 'view', 'delete'],
+      },
+      businessRules: {
+        validation: ['Email must be unique', 'Prices must be positive'],
+        workflows: ['Order creation requires customer', 'Products need approval'],
+      }
+    }
+  }
+});
+```
+
+## Chat Levels
+
+### **Full Chat Mode** (`chatLevel: 'full'`)
+- Conversational explanations with context
+- Detailed reasoning for suggestions
+- Educational guidance and tips
+- JSON suggestions when actionable
+
+### **Basic Chat Mode** (`chatLevel: 'basic'`)
+- Brief explanations for actions
+- Concise context when helpful
+- Balanced efficiency and guidance
+- JSON for actions, text for info
+
+### **None Chat Mode** (`chatLevel: 'none'`)
+- **Pure JSON output only**
+- No explanatory text
+- Maximum efficiency
+- Strict formatting compliance
+
+## Environment Variables
+
+```env
+# Required: At least one provider API key
+OPENAI_API_KEY=your-openai-key
+CLAUDE_API_KEY=your-claude-key
+GEMINI_API_KEY=your-gemini-key
+
+# Optional: Server config
+PORT=3001
+COMMAND_CHAT_LEVEL=full
+COMMAND_TEMPERATURE=0.7
+COMMAND_MAX_TOKENS=4096
+```
+
+## Migration from Previous Versions
+
+If you're upgrading from an earlier version:
+
+1. **Update model configurations** to use latest model IDs
+2. **Enhance training config** with structured data approach
+3. **Update default models** to recommended latest versions
+4. **Review chat levels** to ensure proper JSON formatting
+
+See the [example apps](examples/apps/) for complete migration examples.
+
+## License
+
+MIT

package/dist/components/ChatPanel.d.ts

@@ -0,0 +1,123 @@
+import React from 'react';
+import { CommandTheme, ChatMessage, ModelInfo, ChatTheme, ServerConfig } from '../types/types';
+interface ChatPanelProps {
+    isOpen: boolean;
+    setIsOpen?: (isOpen: boolean) => void;
+    onClose: () => void;
+    onOpen?: () => void;
+    userId: string;
+    formData?: Record<string, unknown>;
+    setFormState: (state: Record<string, unknown>, actionType: string) => void;
+    onNavigate: (path: string) => void;
+    theme?: CommandTheme;
+    chatTheme?: Partial<ChatTheme>;
+    themeMode?: 'light' | 'dark' | 'system';
+    showHistory?: boolean;
+    showProfileBubbles?: boolean;
+    modalPosition?: 'left' | 'right';
+    serverConfig?: ServerConfig;
+    models?: Record<string, ModelInfo[]>;
+    defaultModel?: {
+        provider: string;
+        model: string;
+    };
+    showUsageStats?: boolean;
+    maxFileSize?: string;
+    features?: {
+        modelSwitching?: boolean;
+        usageTracking?: boolean;
+        imageAnalysis?: boolean;
+        fileUploads?: boolean;
+        enableImageUploads?: boolean;
+    };
+    showFloatingButton?: boolean;
+    floatingButtonIcon?: React.ReactNode;
+    floatingButtonPosition?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    floatingButtonSize?: 'sm' | 'md' | 'lg';
+    floatingButtonClassName?: string;
+    chats?: Record<string, ChatMessage[]>;
+    setChats?: React.Dispatch<React.SetStateAction<Record<string, ChatMessage[]>>>;
+    currentChatId?: string;
+    setCurrentChatId?: React.Dispatch<React.SetStateAction<string>>;
+    chatLevel?: 'full' | 'basic' | 'none';
+    initialQuery?: {
+        query: string;
+        context?: string;
+    };
+    setInitialQuery?: React.Dispatch<React.SetStateAction<{
+        query: string;
+        context?: string;
+    } | undefined>>;
+}
+/**
+ * ChatPanel component
+ * @param isOpen - Whether the chat panel is open
+ * @param setIsOpen - Function to set the chat panel open state
+ * @param onClose - Function to close the chat panel
+ * @param onOpen - Function to open the chat panel
+ * @param userId - User ID - used to identify the user in the streaming server
+ * @param formData - Form data - used to reference the existing form data in the streaming server
+ * @param setFormState - Function to set the form state
+ * @param onNavigate - Function to navigate to a new path
+ * @param theme - Theme
+ * @param showHistory - Whether to show chat history sidebar (default: false)
+ * @param showProfileBubbles - Whether to show profile bubbles in chat (default: false)
+ * @param serverConfig - Flexible server configuration object
+ * @param showFloatingButton - Whether to show the floating button
+ * @param floatingButtonIcon - Icon for the floating button
+ * @param floatingButtonPosition - Position of the floating button
+ * @param floatingButtonSize - Size of the floating button
+ * @param floatingButtonClassName - Class name for the floating button
+ * @param chats - Optional external chat history
+ * @param setChats - Optional function to set external chat history
+ * @param currentChatId - Optional external current chat ID
+ * @param setCurrentChatId - Optional function to set external current chat ID
+ * @param chatLevel - Optional chat level - 'full' or 'basic' or 'none'
+ * @param initialQuery - Optional initial query to send when modal opens
+ * @param setInitialQuery - Optional function to set/clear the initial query
+ */
+export declare function ChatPanel({ isOpen, setIsOpen, onClose, onOpen, userId, formData, setFormState, onNavigate, theme, // Legacy support
+chatTheme, // New theme system
+themeMode, // Default to system preference
+showHistory, // Default to hidden
+showProfileBubbles, // Default to hidden
+modalPosition, // Default to left position
+serverConfig, models, defaultModel, showUsageStats, maxFileSize, features, showFloatingButton, floatingButtonIcon, floatingButtonPosition, floatingButtonSize, floatingButtonClassName, chats, setChats, currentChatId, setCurrentChatId, chatLevel, initialQuery, setInitialQuery, }: ChatPanelProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * ChatInput component
+ * @param query - The current query
+ * @param setQuery - Function to set the query
+ * @param onSend - Function to send the query
+ * @param isLoading - Whether the input is loading
+ * @param inputRef - Ref to the textarea element
+ * @param attachedFiles - Array of attached files
+ * @param setAttachedFiles - Function to set the attached files
+ * @param serverConfig - Flexible server configuration object
+ * @param modelsByProvider - Models by provider
+ * @param currentModel - Current model
+ * @param currentCapabilities - Current model capabilities
+ * @param usageStats - Usage stats
+ * @param modelSwitcherLoading - Model switcher loading
+ * @param modelSwitcherError - Model switcher error
+ * @param switchModel - Function to switch model
+ * @param integrationMode - Integration mode
+ */
+type FloatingChatButtonProps = {
+    onClick: () => void;
+    theme?: CommandTheme;
+    icon?: React.ReactNode;
+    className?: string;
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    size?: 'sm' | 'md' | 'lg';
+};
+/**
+ * FloatingChatButton component
+ * @param onClick - Function to handle the click event
+ * @param theme - Theme
+ * @param icon - Icon for the floating button
+ * @param className - Class name for the floating button
+ * @param position - Position of the floating button
+ * @param size - Size of the floating button
+ */
+export declare function FloatingChatButton({ onClick, theme, icon, className, position, size, }: FloatingChatButtonProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Conversation.d.ts

@@ -0,0 +1,75 @@
+import React from 'react';
+import { CommandSuggestion, ChatMessage, ChatTheme, ModelInfo, ModelCapabilities, ServerConfig } from '../types/types';
+interface ConversationProps {
+    chat?: ChatMessage[];
+    onSuggestionClick: (s: CommandSuggestion) => void;
+    theme: ChatTheme;
+    showProfileBubbles?: boolean;
+    className?: string;
+    autoScroll?: boolean;
+    maxHeight?: string;
+    userId?: string;
+    serverConfig?: ServerConfig;
+    formData?: Record<string, unknown>;
+    setFormState?: (state: Record<string, unknown>, actionType: string) => void;
+    onNavigate?: (path: string) => void;
+    chatLevel?: 'full' | 'basic' | 'none';
+    chats?: Record<string, ChatMessage[]>;
+    setChats?: React.Dispatch<React.SetStateAction<Record<string, ChatMessage[]>>>;
+    currentChatId?: string;
+    setCurrentChatId?: React.Dispatch<React.SetStateAction<string>>;
+    query?: string;
+    setQuery?: (q: string) => void;
+    onSend?: (additionalContext?: string, queryToSend?: string) => void;
+    isLoading?: boolean;
+    attachedFiles?: File[];
+    setAttachedFiles?: (files: File[]) => void;
+    models?: Record<string, ModelInfo[]>;
+    defaultModel?: {
+        provider: string;
+        model: string;
+    };
+    showUsageStats?: boolean;
+    maxFileSize?: string;
+    features?: {
+        modelSwitching?: boolean;
+        usageTracking?: boolean;
+        imageAnalysis?: boolean;
+        fileUploads?: boolean;
+        enableImageUploads?: boolean;
+    };
+    currentModelSelection?: {
+        provider: string;
+        model: string;
+        capabilities: ModelCapabilities;
+    };
+    onModelSelectionChange?: (modelInfo: {
+        provider: string;
+        model: string;
+        capabilities: ModelCapabilities;
+    }) => void;
+    showInput?: boolean;
+    initialQuery?: {
+        query: string;
+        context?: string;
+    };
+    setInitialQuery?: React.Dispatch<React.SetStateAction<{
+        query: string;
+        context?: string;
+    } | undefined>>;
+    showClearChat?: boolean;
+    onClearChat?: () => void;
+    additionalContext?: string | Record<string, unknown>;
+}
+/**
+ * Conversation component - displays a single chat conversation
+ * @param chat - The chat messages to display
+ * @param onSuggestionClick - Function to handle suggestion clicks
+ * @param theme - Chat theme
+ * @param showProfileBubbles - Whether to show profile bubbles
+ * @param className - Additional CSS classes
+ * @param autoScroll - Whether to auto-scroll to bottom on new messages
+ * @param maxHeight - Maximum height of the conversation container
+ */
+export declare function Conversation({ chat: externalChat, onSuggestionClick, theme, showProfileBubbles, className, autoScroll, maxHeight, userId, serverConfig, formData, setFormState, onNavigate, chatLevel, chats: externalChats, setChats: externalSetChats, currentChatId: externalCurrentChatId, setCurrentChatId: externalSetCurrentChatId, query: externalQuery, setQuery: externalSetQuery, onSend: externalOnSend, isLoading: externalIsLoading, attachedFiles: externalAttachedFiles, setAttachedFiles: externalSetAttachedFiles, models, defaultModel, showUsageStats, maxFileSize, features, currentModelSelection: externalCurrentModelSelection, onModelSelectionChange: externalOnModelSelectionChange, showInput, initialQuery, setInitialQuery, showClearChat, onClearChat, additionalContext, }: ConversationProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ErrorBoundary.d.ts

@@ -0,0 +1,16 @@
+import React, { Component, ErrorInfo, ReactNode } from 'react';
+interface Props {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+interface State {
+    hasError: boolean;
+    error?: Error;
+}
+export declare class ErrorBoundary extends Component<Props, State> {
+    constructor(props: Props);
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): string | number | boolean | import("react/jsx-runtime").JSX.Element | Iterable<React.ReactNode> | null | undefined;
+}
+export {};

package/dist/components/Icon.d.ts

@@ -0,0 +1,84 @@
+import React from 'react';
+import { Action } from '../types/types';
+/**
+ * Universal Icon Component
+ *
+ * A flexible, centralized icon system that supports all UI, action, and file type icons.
+ * Can return React components or SVG strings for vanilla JavaScript applications.
+ *
+ * @example
+ * // React usage with preset sizes
+ * <Icon name="ai" size="md" />
+ * <Icon name="user" size="lg" className="text-blue-500" />
+ *
+ * // Custom size (numeric pixels)
+ * <Icon name="pdf" size={32} />
+ *
+ * // With custom styling
+ * <Icon name="send" size="sm" color="#ff0000" style={{ opacity: 0.8 }} />
+ *
+ * // Vanilla JS usage - get SVG string
+ * const svgString = getIcon('plus', { size: 24 });
+ *
+ * // Action-based icon selection
+ * const editIcon = getActionIcon('edit', 'react'); // Returns React component
+ * const editSvg = getActionIcon('edit', 'vanilla'); // Returns SVG string
+ *
+ * // Available sizes: 'xs' (12px), 'sm' (16px), 'md' (20px), 'lg' (24px), 'xl' (32px)
+ * // Or any numeric value for custom pixel size
+ */
+export type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number;
+export type IconName = 'ai' | 'user' | 'system' | 'paperclip' | 'image' | 'noImage' | 'microphone' | 'send' | 'plus' | 'pencil' | 'trash' | 'eye' | 'claude' | 'openai' | 'gemini' | 'grok' | 'error' | 'warning' | 'timeout' | 'auth-error' | 'pdf' | 'word' | 'excel' | 'csv' | 'text' | 'rtf' | 'file-generic';
+export interface IconProps {
+    name: IconName;
+    size?: IconSize;
+    className?: string;
+    color?: string;
+    style?: React.CSSProperties;
+}
+export interface VanillaIconOptions {
+    size?: IconSize;
+    color?: string;
+    className?: string;
+}
+export declare const getIconNameForAction: (action: Action) => IconName | null;
+export declare const Icon: React.FC<IconProps>;
+/**
+ * Get an icon as an SVG string for vanilla JavaScript applications
+ * @param name - Icon name
+ * @param options - Icon options (size, color, className)
+ * @returns SVG string or null if icon not found
+ */
+export declare const getIcon: (name: IconName, options?: VanillaIconOptions) => string | null;
+/**
+ * Universal action icon function - works for both React and vanilla JS
+ * @param action - Action type string
+ * @param framework - Target framework ('react' or 'vanilla')
+ * @param options - Icon options (only used for vanilla)
+ * @returns React component or SVG string based on framework
+ */
+export declare const getActionIcon: (action: Action, framework?: "react" | "vanilla", options?: VanillaIconOptions) => React.ReactElement | string | null;
+/**
+ * Get action icon as React component (legacy compatibility)
+ * @param action - Action type string
+ * @returns React component or null
+ */
+export declare const getActionIconReact: (action: Action) => React.ReactElement | null;
+/**
+ * Get action icon as SVG string (legacy compatibility)
+ * @param action - Action type string
+ * @returns SVG string or null
+ */
+export declare const getActionIconString: (action: Action) => string | null;
+/**
+ * Get provider icon name for AI providers
+ * @param provider - Provider name (openai, claude, gemini)
+ * @returns Icon name or null if not found
+ */
+export declare const getProviderIconName: (provider: string | undefined) => IconName | null;
+export declare const Icons: Record<IconName, (props: {
+    size: number;
+    className?: string;
+    color?: string;
+}) => React.ReactElement>;
+export default Icon;

package/dist/components/ModelSwitcher.d.ts

@@ -0,0 +1,24 @@
+import { ModelCapabilities, ModelInfo, ChatTheme } from '../types/types';
+interface ModelSwitcherProps {
+    className?: string;
+    models?: Record<string, ModelInfo[]>;
+    defaultModel?: {
+        provider: string;
+        model: string;
+    };
+    showUsageStats?: boolean;
+    theme?: ChatTheme;
+    onModelSelectionChange?: (modelInfo: {
+        provider: string;
+        model: string;
+        capabilities: ModelCapabilities;
+    }) => void;
+}
+/**
+ * ModelSwitcher component for switching between AI models
+ * Now uses the simplified useModelSwitcher hook directly
+ * Uses Tailwind classes for styling
+ */
+export declare function ModelSwitcher({ className, models, defaultModel, showUsageStats, // Default to false to match modal design
+theme, onModelSelectionChange, }: ModelSwitcherProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/SuggestionsPanel.d.ts

@@ -0,0 +1,27 @@
+import { CommandSuggestion, ChatTheme, ServerConfig } from '../types/types';
+interface SuggestionsPanelProps {
+    query: string;
+    onSuggestionSelect: (suggestion: CommandSuggestion) => void;
+    onClose?: () => void;
+    userId: string;
+    formData?: Record<string, unknown>;
+    serverConfig?: ServerConfig;
+    theme?: ChatTheme;
+    isLoading?: boolean;
+    placeholder?: string;
+    maxSuggestions?: number;
+    showIcons?: boolean;
+    className?: string;
+}
+export interface SuggestionCardProps {
+    suggestion: CommandSuggestion;
+    onClick: (s: CommandSuggestion) => void;
+    isHighlighted?: boolean;
+    theme?: ChatTheme;
+    showIcon?: boolean;
+}
+export declare function SuggestionCard({ suggestion, onClick, isHighlighted, theme, showIcon, }: SuggestionCardProps): import("react/jsx-runtime").JSX.Element;
+export declare function SuggestionsPanel({ query, onSuggestionSelect, onClose, userId, formData, serverConfig, theme, isLoading, placeholder, maxSuggestions, showIcons, className, context, }: SuggestionsPanelProps & {
+    context?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export default SuggestionsPanel;