Suntropy AI Components

A React TypeScript component library for interacting with Suntropy AI agent execution API. This library provides easy-to-use components and hooks for managing AI agent threads and their execution states.

Features

• 🚀 Easy Setup: Simple provider-based configuration
• 🔄 Real-time Updates: Automatic thread status polling
• 🎨 Customizable Components: Flexible styling and behavior
• 📦 TypeScript Support: Full type safety
• 🪝 React Hooks: Powerful hooks for thread management
• ⚡ Lightweight: Minimal dependencies

Installation

npm install suntropyai-ui-components/ai-components
# or
yarn add suntropyai-ui-components/ai-components

Quick Start

1. Setup the Provider

Wrap your application with the SuntropyAIProvider:

import React from 'react';
import { SuntropyAIProvider } from 'suntropyai-ui-components/ai-components';

function App() {
  return (
    <SuntropyAIProvider
      apiKey="your-api-key"
      baseUrl="https://api.suntropy.ai"
    >
      <YourApp />
    </SuntropyAIProvider>
  );
}

2. Use Components

ThreadStateTag Component

Display the current state of an agent thread:

import React from 'react';
import { ThreadStateTag } from 'suntropyai-ui-components/ai-components';

function ThreadStatus({ threadId }) {
  return (
    <ThreadStateTag
      threadId={threadId}
      enableAutoRefresh={true}
      refreshInterval={5000}
      onStatusChange={(thread) => {
        console.log('Thread status changed:', thread.state);
      }}
    />
  );
}

3. Use Hooks

useCreateThread Hook

Create new agent threads:

import React from 'react';
import { useCreateThread } from 'suntropyai-ui-components/ai-components';

function CreateThreadExample() {
  const { createThread, isLoading, error } = useCreateThread({
    onSuccess: (response) => {
      console.log('Thread created:', response.threadId);
    },
    onError: (error) => {
      console.error('Failed to create thread:', error);
    },
  });

  const handleCreateThread = async () => {
    await createThread('agent-id', 'Hello, please help me with a task');
  };

  return (
    <div>
      <button onClick={handleCreateThread} disabled={isLoading}>
        {isLoading ? 'Creating...' : 'Create Thread'}
      </button>
      {error && <p style={{ color: 'red' }}>Error: {error}</p>}
    </div>
  );
}

useThreadStatus Hook

Monitor thread status in real-time:

import React from 'react';
import { useThreadStatus, AgentThreadState } from 'suntropyai-ui-components/ai-components';

function ThreadMonitor({ threadId }) {
  const { 
    thread, 
    isLoading, 
    error, 
    refresh, 
    startPolling, 
    stopPolling 
  } = useThreadStatus(threadId, {
    autoRefresh: true,
    refreshInterval: 5000,
    onStatusChange: (thread) => {
      if (thread.state === AgentThreadState.COMPLETED) {
        console.log('Thread completed!');
      }
    },
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!thread) return <div>No thread data</div>;

  return (
    <div>
      <h3>Thread Status: {thread.state}</h3>
      <p>Created: {new Date(thread.creationTimestampMs).toLocaleString()}</p>
      <button onClick={refresh}>Refresh</button>
      <button onClick={startPolling}>Start Auto-refresh</button>
      <button onClick={stopPolling}>Stop Auto-refresh</button>
    </div>
  );
}

API Reference

Components

ThreadStateTag

A component that displays the current state of an agent thread with visual indicators.

Props:

• threadId (string): The ID of the thread to monitor
• showIcon (boolean, optional): Whether to show status icons (default: true)
• enableAutoRefresh (boolean, optional): Enable automatic status updates (default: true)
• refreshInterval (number, optional): Refresh interval in milliseconds (default: 5000)
• onStatusChange (function, optional): Callback when thread status changes
• onActionComplete (function, optional): Callback when thread actions complete
• className (string, optional): Additional CSS classes
• style (object, optional): Inline styles

Hooks

useCreateThread

Hook for creating new agent threads.

Options:

• onSuccess (function, optional): Callback on successful thread creation
• onError (function, optional): Callback on thread creation error

Returns:

• createThread (function): Function to create a new thread
• isLoading (boolean): Loading state
• error (string | null): Error message if any
• lastResponse (object | null): Last response from the API

useThreadStatus

Hook for monitoring thread status with automatic polling.

Parameters:

• threadId (string | null): The thread ID to monitor
• options (object, optional): Configuration options

Options:

• autoRefresh (boolean): Enable automatic polling (default: false)
• refreshInterval (number): Polling interval in ms (default: 5000)
• onStatusChange (function): Callback when status changes
• onError (function): Callback on errors

Returns:

• thread (object | null): Current thread data
• isLoading (boolean): Loading state
• error (string | null): Error message if any
• refresh (function): Manual refresh function
• startPolling (function): Start automatic polling
• stopPolling (function): Stop automatic polling
• isPolling (boolean): Current polling state

Types

AgentThreadState

Enum of possible thread states:

• QUEUED: Thread is queued for processing
• PROCESSING: Thread is currently being processed
• COMPLETED: Thread has completed successfully
• FAILED: Thread execution failed
• TERMINATED: Thread was terminated
• PAUSED: Thread is paused
• PAUSED_FOR_APPROVAL: Thread is waiting for approval
• APPROVAL_REJECTED: Thread approval was rejected
• WAITING_FOR_RESPONSE: Thread is waiting for external response
• PAUSED_FOR_RESUME: Thread is scheduled to resume
• HANDED_OFF: Thread was handed off to another agent

Advanced Usage

Custom Styling

You can customize the appearance of components using CSS classes or inline styles:

<ThreadStateTag
  threadId="thread-123"
  className="my-custom-thread-tag"
  style={{
    borderRadius: '8px',
    padding: '8px 12px',
    fontWeight: 'bold',
  }}
/>

Error Handling

The library provides comprehensive error handling:

const { createThread } = useCreateThread({
  onError: (error) => {
    // Handle specific error cases
    if (error.includes('401')) {
      // Handle authentication error
    } else if (error.includes('403')) {
      // Handle authorization error
    }
  },
});

Conditional Polling

Control when to enable auto-refresh based on thread state:

const { thread } = useThreadStatus(threadId, {
  autoRefresh: thread?.state === AgentThreadState.PROCESSING,
  refreshInterval: 2000, // More frequent updates for processing threads
});

Building the Library

To build the library for distribution:

# Install dependencies
npm install

# Build the library
npm run build

# Build with watch mode
npm run build:watch

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions and support, please contact the Suntropy AI team or create an issue in the repository.