@app-studio/web 0.9.41 → 0.9.44

package/docs/adk-components.md

@@ -1,319 +0,0 @@
-# ADK Agent Components
-
-This document provides an overview of the React components created for compatibility with the ADK (Agent Development Kit) system.
-
-## Overview
-
-The ADK Agent Components are a collection of React components designed to work seamlessly with ADK agents. These components are self-contained, handling their own state and API communications, providing a complete interface for agent interaction, session management, and more.
-
-## Components
-
-### 1. AgentChat Component
-
-**Location**: `src/components/adk/AgentChat/`
-
-A comprehensive chat interface for interacting with ADK agents.
-
-#### Key Features:
-- ✅ Real-time messaging via Server-Sent Events (SSE)
-- ✅ File upload support (images, videos, audio, documents)
-- ✅ Audio recording with live waveform visualization
-- ✅ Function call visualization and execution
-- ✅ Code execution and result display
-- ✅ Agent thought process visualization
-- ✅ Evaluation and scoring support
-- ✅ Streaming and non-streaming responses
-- ✅ Fully customizable styling and theming
-- ✅ Accessibility-first design
-
-#### Usage:
-```tsx
-import { AgentChat } from '@app-studio/web';
-
-<AgentChat
-  appName="my-agent"
-  userId="user123"
-  apiBaseUrl="https://your-adk-api.com"
-  enableFileUpload={true}
-  enableAudioRecording={true}
-  enableStreaming={true}
-  enableThoughts={true}
-  onSessionCreate={(session) => console.log('Session created:', session)}
-  onMessageSent={(message) => console.log('Message sent:', message)}
-/>
-```
-
-#### Props:
-- `appName` (required): Name of the ADK agent application.
-- `userId` (required): Unique identifier for the user.
-- `sessionId`: Existing session ID to resume.
-- `apiBaseUrl`: Base URL for ADK API endpoints.
-- `enableFileUpload`: Enable file attachment functionality.
-- `enableAudioRecording`: Enable audio recording from the microphone.
-- `enableStreaming`: Enable real-time streaming responses.
-- `enableThoughts`: Show agent thought processes.
-- `views`: Custom styling options.
-
-### 2. AgentSession Component
-
-**Location**: `src/components/adk/AgentSession/`
-
-A comprehensive session management component for ADK agents.
-
-#### Key Features:
-- ✅ Session creation, listing, and selection
-- ✅ Session deletion and management
-- ✅ Import/export functionality
-- ✅ Search and filtering capabilities
-- ✅ Auto-refresh and real-time updates
-- ✅ Session metadata and tagging
-- ✅ Compact and full display modes
-- ✅ Bulk operations support
-
-#### Usage:
-```tsx
-import { AgentSession } from '@app-studio/web';
-
-<AgentSession
-  appName="my-agent"
-  userId="user123"
-  apiBaseUrl="https://your-adk-api.com"
-  showSessionHistory={true}
-  enableSessionImport={true}
-  enableSessionExport={true}
-  onSessionSelect={(session) => console.log('Selected:', session)}
-  onSessionCreate={(session) => console.log('Created:', session)}
-/>
-```
-
-#### Props:
-- `appName` (required): Name of the ADK agent application.
-- `userId` (required): Unique identifier for the user.
-- `apiBaseUrl`: Base URL for ADK API endpoints.
-- `showSessionHistory`: Show session history list.
-- `enableSessionImport`: Enable session import from JSON.
-- `enableSessionExport`: Enable session export to JSON.
-- `enableSessionSearch`: Enable search functionality.
-- `maxSessions`: Maximum number of sessions to display.
-- `views`: Custom styling options.
-
-## Architecture
-
-### Component Structure
-
-Each component follows the established app-studio pattern:
-
-```
-ComponentName/
-├── ComponentName.tsx                 # Main component file
-├── ComponentName/                    # Inner folder for core files
-│   ├── ComponentName.props.ts        # Props interface definitions
-│   ├── ComponentName.state.ts        # Custom state hook
-│   ├── ComponentName.view.tsx        # Presentational component
-│   ├── ComponentName.style.ts        # Style constants
-│   └── [SupportingComponents].tsx    # Additional components
-└── examples/                         # Usage examples
-    └── default.tsx                   # Default usage examples
-```
-
-### ADK Integration
-
-The components are self-contained and integrate directly with an ADK backend using `fetch`. You can specify the backend URL via the `apiBaseUrl` prop.
-
-#### Required Backend Endpoints:
-- `POST /sessions` - Create new agent session
-- `POST /run_sse` - Send message with streaming response
-- `POST /run` - Send message with regular response
-- `GET /sessions/:id` - Get session details
-- `DELETE /sessions/:id` - Delete session
-- `POST /sessions/import` - Import session
-
-#### Message Format:
-The components use the same message format as the original ADK system:
-
-```typescript
-interface AgentRunRequest {
-  appName: string;
-  userId: string;
-  sessionId: string;
-  newMessage: {
-    role: string;
-    parts: MessagePart[];
-  };
-  streaming?: boolean;
-}
-```
-
-### Direct API Interaction (`useAdk` Hook)
-For developers who need to interact with the ADK API without using the pre-built UI components, a `useAdk` hook is available. This hook provides functions for all core ADK operations like creating sessions, running agents, and managing responses.
-
-**Location**: `src/components/adk/useAdk.ts`
-
-```tsx
-import { useAdk } from '@app-studio/web';
-
-const { createSession, runAgent, sessions, isLoadingSessions } = useAdk();
-```
-
-### Design System Compliance
-
-All components follow the app-studio design system:
-
-- **Typography**: Inter/Geist font family with standardized sizes (xs:10, sm:12, md:14, lg:16, xl:20)
-- **Spacing**: 4px grid system for consistent spacing
-- **Colors**: app-studio color system (color.[color].[number]) instead of hardcoded values
-- **Shapes**: Consistent border radius and rounded corners
-- **Animations**: Using app-studio Animation object with proper duration and timing
-
-### Reusability
-
-The components are designed to be:
-
-- **Modular**: Each component can be used independently
-- **Customizable**: Extensive styling options via the `views` prop
-- **Accessible**: ARIA labels, keyboard navigation, and screen reader support
-- **Responsive**: Works across mobile, tablet, and desktop breakpoints
-- **Themeable**: Support for light/dark themes and custom color schemes
-
-## Examples and Documentation
-
-### Demo Pages
-
-- **AgentChat Demo**: `src/pages/agentChat.page.tsx`
-- **Component Examples**: Available in each component's `examples/` directory
-
-### Usage Examples
-
-Each component includes multiple usage examples:
-
-1. **Default Usage**: Basic implementation with minimal configuration
-2. **Minimal Usage**: Simplest possible setup
-3. **Customized Usage**: Advanced styling and configuration options
-4. **Feature Demos**: Showcasing specific features like function calls, file uploads, etc.
-
-## Integration Guide
-
-### 1. Installation
-
-The components are part of the app-studio component library and can be imported directly:
-
-```tsx
-import { AgentChat, AgentSession } from '@app-studio/web';
-```
-
-### 2. Backend Setup
-
-Ensure your ADK backend provides the required endpoints and follows the expected API format.
-
-### 3. Basic Implementation
-
-```tsx
-import React from 'react';
-import { AgentChat, AgentSession } from '@app-studio/web';
-import { View, Horizontal } from 'app-studio';
-
-const MyAgentApp = () => {
-  return (
-    <View height="100vh" padding={20}>
-      <Horizontal gap={20} height="100%">
-        {/* Session Management */}
-        <View width="300px">
-          <AgentSession
-            appName="my-agent"
-            userId="user123"
-            apiBaseUrl="https://api.example.com"
-          />
-        </View>
-        
-        {/* Chat Interface */}
-        <View flex={1}>
-          <AgentChat
-            appName="my-agent"
-            userId="user123"
-            apiBaseUrl="https://api.example.com"
-          />
-        </View>
-      </Horizontal>
-    </View>
-  );
-};
-```
-
-### 4. Advanced Configuration
-
-```tsx
-<AgentChat
-  appName="my-agent"
-  userId="user123"
-  apiBaseUrl="https://api.example.com"
-  enableFileUpload={true}
-  enableStreaming={true}
-  enableThoughts={true}
-  maxFileSize={10 * 1024 * 1024}
-  allowedFileTypes={['image/*', 'video/*', 'application/pdf']}
-  onSessionCreate={(session) => {
-    console.log('New session:', session);
-  }}
-  onMessageSent={(message) => {
-    console.log('Message sent:', message);
-  }}
-  onError={(error) => {
-    console.error('Chat error:', error);
-  }}
-  views={{
-    container: { backgroundColor: 'color.gray.50' },
-    userMessage: { backgroundColor: 'color.blue.500' },
-    botMessage: { backgroundColor: 'color.green.100' },
-  }}
-/>
-```
-
-## Complete Component Library
-
-All planned components have been successfully implemented:
-
-### ✅ **AgentTrace Component**
-- **Timeline visualization** of agent execution traces
-- **Event filtering and search** capabilities
-- **Performance metrics** and analytics
-- **Real-time trace updates** via WebSocket
-- **Multiple visualization types** (timeline, tree, table, flamegraph)
-- **Export functionality** (JSON, CSV, SVG)
-
-### ✅ **AgentEval Component**
-- **Evaluation creation and management** interface
-- **Test case execution** and monitoring
-- **Results analysis** and comparison
-- **Metrics calculation** and visualization
-- **Batch evaluation** support
-- **Template system** for reusable evaluations
-
-### ✅ **Agent Service Integration**
-- **Enhanced service layer** for backend communication
-- **React Provider pattern** for service management
-- **Utility functions** for common operations
-- **Real-time updates** via WebSocket and SSE
-- **Error handling and retry logic**
-- **Connection status monitoring**
-
-## Demo Page
-
-A comprehensive demo page showcasing all components is available at:
-- **File**: `src/pages/adkComponents.page.tsx`
-- **Features**: Interactive demos, customization examples, integration guides
-
-## Support
-
-For questions, issues, or contributions related to the ADK Agent Components, please refer to the main app-studio documentation or create an issue in the repository.
-
-## Production Ready
-
-All ADK Agent Components are **production-ready** and provide:
-- ✅ Full ADK backend compatibility
-- ✅ TypeScript support with comprehensive type definitions
-- ✅ Accessibility compliance (ARIA labels, keyboard navigation)
-- ✅ Responsive design for mobile, tablet, and desktop
-- ✅ Comprehensive error handling and loading states
-- ✅ Real-time updates and streaming support
-- ✅ Extensive customization options
-- ✅ Complete documentation and examples

package/docs/adk-quick-start.md

@@ -1,268 +0,0 @@
-# ADK Components Quick Start Guide
-
-Get up and running with ADK Agent Components in minutes.
-
-## Installation
-
-The ADK components are part of the app-studio component library:
-
-```bash
-npm install @app-studio/web
-```
-
-## Basic Setup
-
-### 1. Import Components
-
-```tsx
-import { 
-  AgentChat, 
-  AgentSession, 
-  AgentTrace, 
-  AgentEval 
-} from '@app-studio/web';
-```
-
-### 2. Use Components
-
-The ADK components are self-contained and handle their own API communications. Simply add them to your application and provide the necessary props.
-
-```tsx
-function YourApp() {
-  return (
-    <div style={{ display: 'flex', height: '100vh' }}>
-      {/* Session Management */}
-      <div style={{ width: '300px' }}>
-        <AgentSession
-          appName="my-agent"
-          userId="user123"
-          apiBaseUrl="https://your-adk-api.com"
-        />
-      </div>
-      
-      {/* Chat Interface */}
-      <div style={{ flex: 1 }}>
-        <AgentChat
-          appName="my-agent"
-          userId="user123"
-          apiBaseUrl="https://your-adk-api.com"
-          enableFileUpload={true}
-          enableStreaming={true}
-        />
-      </div>
-    </div>
-  );
-}
-```
-
-## Component Overview
-
-### AgentChat
-**Purpose**: Real-time chat interface with ADK agents
-**Key Features**: File uploads, audio recording, streaming, function calls, code execution
-
-```tsx
-<AgentChat
-  appName="my-agent"
-  userId="user123"
-  enableFileUpload={true}
-  enableAudioRecording={true}
-  enableStreaming={true}
-  enableThoughts={true}
-  onMessageSent={(message) => console.log(message)}
-/>
-```
-
-### AgentSession
-**Purpose**: Session management and organization
-**Key Features**: Create, list, import/export, search sessions
-
-```tsx
-<AgentSession
-  appName="my-agent"
-  userId="user123"
-  showSessionHistory={true}
-  enableSessionImport={true}
-  enableSessionExport={true}
-/>
-```
-
-### AgentTrace
-**Purpose**: Visualize agent execution traces
-**Key Features**: Timeline view, performance metrics, real-time updates
-
-```tsx
-<AgentTrace
-  sessionId="session-123"
-  userId="user123"
-  appName="my-agent"
-  showTimeline={true}
-  showMetrics={true}
-  enableFiltering={true}
-/>
-```
-
-### AgentEval
-**Purpose**: Run and manage agent evaluations
-**Key Features**: Test creation, execution monitoring, results analysis
-
-```tsx
-<AgentEval
-  appName="my-agent"
-  userId="user123"
-  enableBatchEvaluation={true}
-  enableMetricsComparison={true}
-  enableResultExport={true}
-/>
-```
-
-## Common Patterns
-
-### 1. Complete Agent Interface
-
-```tsx
-import { Tabs } from 'app-studio';
-
-function AgentInterface() {
-  return (
-    <Tabs defaultValue="chat">
-      <Tabs.List>
-        <Tabs.Trigger value="chat">Chat</Tabs.Trigger>
-        <Tabs.Trigger value="sessions">Sessions</Tabs.Trigger>
-        <Tabs.Trigger value="trace">Trace</Tabs.Trigger>
-        <Tabs.Trigger value="eval">Evaluation</Tabs.Trigger>
-      </Tabs.List>
-
-      <Tabs.Content value="chat">
-        <AgentChat appName="my-agent" userId="user123" />
-      </Tabs.Content>
-
-      <Tabs.Content value="sessions">
-        <AgentSession appName="my-agent" userId="user123" />
-      </Tabs.Content>
-
-      <Tabs.Content value="trace">
-        <AgentTrace sessionId="current-session" userId="user123" appName="my-agent" />
-      </Tabs.Content>
-
-      <Tabs.Content value="eval">
-        <AgentEval appName="my-agent" userId="user123" />
-      </Tabs.Content>
-    </Tabs>
-  );
-}
-```
-
-### 2. Custom Styling
-
-```tsx
-<AgentChat
-  appName="my-agent"
-  userId="user123"
-  views={{
-    container: { backgroundColor: 'color.blue.50' },
-    userMessage: { backgroundColor: 'color.blue.500' },
-    botMessage: { backgroundColor: 'color.green.100' },
-    inputField: { borderColor: 'color.blue.300' },
-  }}
-/>
-```
-
-### 3. Event Handling
-
-```tsx
-function MyComponent() {
-  const handleSessionCreate = (session) => {
-    console.log('New session created:', session);
-  };
-
-  const handleMessageSent = (message) => {
-    console.log('Message sent:', message);
-  };
-
-  const handleError = (error) => {
-    console.error('Error:', error);
-  };
-
-  return (
-    <AgentChat
-      appName="my-agent"
-      userId="user123"
-      onSessionCreate={handleSessionCreate}
-      onMessageSent={handleMessageSent}
-      onError={handleError}
-    />
-  );
-}
-```
-
-## Backend Requirements
-
-Your ADK backend must provide these endpoints:
-
-### Session Management
-- `POST /sessions` - Create session
-- `GET /sessions` - List sessions
-- `GET /sessions/:id` - Get session
-- `DELETE /sessions/:id` - Delete session
-
-### Messaging
-- `POST /run` - Send message (non-streaming)
-- `POST /run_sse` - Send message (streaming)
-
-### Tracing (Optional)
-- `GET /trace/events` - Get trace events
-- `GET /trace/spans` - Get trace spans
-- `GET /trace/metrics` - Get trace metrics
-
-### Evaluation (Optional)
-- `POST /evaluations` - Create evaluation
-- `GET /evaluations` - List evaluations
-- `POST /evaluations/:id/start` - Start evaluation
-
-## Environment Variables
-
-```bash
-# .env
-REACT_APP_AGENT_API_URL=https://your-adk-api.com
-REACT_APP_AGENT_API_KEY=your-api-key
-```
-
-## TypeScript Support
-
-All components include comprehensive TypeScript definitions:
-
-```tsx
-import type { 
-  AgentChatProps,
-  AgentSessionProps,
-  AgentTraceProps,
-  AgentEvalProps,
-  AgentMessage,
-  AgentSession,
-  TraceEvent,
-  EvaluationRun
-} from '@app-studio/web';
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1.  **API errors**: Check the `apiBaseUrl` prop and ensure your backend URL and API endpoints are correct.
-2.  **Styling issues**: Verify you're using the app-studio color system.
-3.  **TypeScript errors**: Import types from the correct package.
-
-## Next Steps
-
-- Explore the [complete documentation](./adk-components.md)
-- Check out the [demo page](../src/pages/adkComponents.page.tsx)
-- View component examples in each component's `examples/` directory
-- Customize components using the `views` prop system
-
-## Support
-
-For questions or issues:
-- Check the component documentation
-- Review the example implementations
-- Create an issue in the repository