DragonFly AI Chat SDK

Directory Structure

dragonfly-sdk/
├── src/
│   ├── core/
│   │   ├── index.ts
│   │   ├── DragonFlyCore.ts
│   │   ├── LLMManager.ts
│   │   ├── AssistantManager.ts
│   │   ├── ChatManager.ts
│   │   ├── TokenCalculator.ts
│   │   └── ThreadManager.ts
│   ├── ui/
│   │   ├── index.ts
│   │   ├── DragonFlyUI.ts
│   │   ├── components/
│   │   │   ├── MessageInput.tsx
│   │   │   ├── MessageList.tsx
│   │   │   ├── ModelSelector.tsx
│   │   │   └── AssistantSelector.tsx
│   │   └── hooks/
│   │       ├── useChat.ts
│   │       ├── useAssistant.ts
│   │       └── useModel.ts
│   ├── utils/
│   │   ├── AuthManager.ts
│   │   └── StorageHelper.ts
│   └── types/
│       ├── Assistant.ts
│       ├── Model.ts
│       ├── AIMessage.ts
│       └── Thread.ts
├── package.json
└── README.md

Installation

npm install dragonfly-sdk
# or
yarn add dragonfly-sdk

Core Package

Import core functionality from 'dragonfly-sdk/core':

import { 
    DragonFlyCore,
    ChatManager, 
    AssistantManager,
    LLMManager,
    ThreadManager,
    TokenCalculator 
} from 'dragonfly-sdk/core';

Initialization

// Initialize core
const core = DragonFlyCore.getInstance();
core.initialize({
    apiKey: 'your-api-key',
    defaultModel: 'gpt-4',
});

// Access managers
const chatManager = core.chatManager;
const assistantManager = core.assistantManager;

Detailed Module Reference

Core Modules

DragonFlyCore

Main entry point for the core functionality. Can be used with or without explicit initialization.

class DragonFlyCore {
    // Properties
    apiKey: string;
    defaultModel: string;

    // Methods
    static getInstance(): DragonFlyCore;
    initialize(config?: CoreConfig): void;
    private autoInitialize(): void;
    private loadEnvironmentConfig(): CoreConfig;
    
    // Managers
    get chatManager(): ChatManager;
    get assistantManager(): AssistantManager;
    get llmManager(): LLMManager;
    get threadManager(): ThreadManager;
    get tokenCalculator(): TokenCalculator;
}

interface CoreConfig {
    apiKey?: string;        // Optional if DRAGONFLY_API_KEY is set in .env
    defaultModel?: string;  // Optional if DRAGONFLY_DEFAULT_MODEL is set in .env
}

// Environment Variables
// DRAGONFLY_API_KEY=your-api-key
// DRAGONFLY_DEFAULT_MODEL=gpt-4

Using with Environment Variables

Create a .env file in your project root:

DRAGONFLY_API_KEY=your-api-key
DRAGONFLY_DEFAULT_MODEL=gpt-4

Then you can use the core directly without initialization:

import { ChatManager, AssistantManager } from 'dragonfly-sdk/core';

// Core will auto-initialize using environment variables
const core = DragonFlyCore.getInstance();
const chatManager = core.chatManager;
const assistantManager = core.assistantManager;

// Start using the managers directly
await chatManager.sendMessageStream('Hello', 'thread-id');

Mixed Usage with Environment Variables

You can also mix environment variables with explicit configuration:

const core = DragonFlyCore.getInstance();
// Only override specific settings, others will use env variables
core.initialize({
    defaultModel: 'gpt-3.5'  // Override just the model
});

Environment Variable Priorities

1. Explicitly passed configuration (highest priority)
2. Environment variables
3. Default values (lowest priority)

Default values:

• defaultModel: 'gpt-4'

LLM Manager

Handles language model configurations and interactions.

class LLMManager {
    // Properties
    model: Model[];

    // Methods
    initialize(models: Model[]): Promise<void>;
    setCurrentModel(modelId: string): void;
    getCurrentModel(): Model;
    listModels(): Model[];
    getModel(modelId: string): Model;
}

interface Model {
    id: string;
    name: string;
    icon: string;
    maxTokens: number;
    ModelConfig: string[];
    contextWindow: number;
    host: string;
    position: number;
}

Assistant Manager

Manages AI assistants and their configurations.

class AssistantManager {
    // Properties
    assistant: Assistant[];

    // Methods
    setCurrentAssistant(assistantId: string): void;
    getCurrentAssistant(): Assistant;
    listAssistants(): Assistant[];
    getAssistant(assistantId: string): Assistant[];
}

interface Assistant {
    id: string;
    assistantId: string;
    name: string;
    instructions: string;
    description: string;
    image: string;
    model: string;
    systemPrompt: string;
    tools: string[];
}

Chat Manager

Handles chat interactions and message history.

class ChatManager {
    // Properties
    messages: AIMessage[];

    // Methods
    sendMessageStream(
        message: string, 
        threadId: string, 
        fileIds?: string[]
    ): Promise<void>;
    
    sendMessageNonStream(
        message: string, 
        threadId: string, 
        fileIds?: string[]
    ): Promise<void>;
    
    getChatHistory(threadId: string): ChatHistory;
    transcribeAudio(fileId: string): Promise<string>;
    resetChat(): void;
}

interface AIMessage {
    id: number;
    text: string | string[];
    sender: string;
    assistantId: string;
    timestamp: number;
    fileData: { id: string; name: string; content: string }[];
    imageData: { id: string; name: string; preview: string }[];
    toolCalls: ToolCall[];
    functionOutput: string;
    error: string;
}

Thread Manager

Manages conversation threads.

class ThreadManager {
    // Methods
    listThreads(): Thread[];
    getThread(threadId: string): Thread;
    createThread(options: CreateThreadOptions): Thread;
    exportThread(threadId: string, format: 'json' | 'txt'): string;
}

interface Thread {
    id: string;
    name: string;
    createdAt: Date;
    updatedAt: Date;
    messages: AIMessage[];
}

interface CreateThreadOptions {
    name: string;
    metadata?: Record<string, any>;
}

Token Calculator

Handles token counting

class TokenCalculator {
    // Methods
    estimateTokens(
        input: string | AIMessage | AIMessage[]
    ): number;
    
    getTokenLimit(modelId: string): number;
}

UI Modules

DragonFlyUI

Main entry point for UI components.

class DragonFlyUI {
    // Properties
    apiKey: string;

    // Methods
    static getInstance(): DragonFlyUI;
    initialize(config: UIConfig): void;
}

interface UIConfig {
    apiKey: string;
    theme?: 'light' | 'dark';
    customStyles?: UIStyles;
}

React Components

MessageInput

Input component for sending messages.

interface MessageInputProps {
    onSendMessage(text: string): void;
    onFileUpload?(files: File[]): void;
    onToolAction?(tool: string, action: string): void;
    disabled?: boolean;
    placeholder?: string;
    className?: string;
}

class MessageInput extends React.Component<MessageInputProps> {
    render(): ReactNode;
}

MessageList

Component for displaying chat messages.

interface MessageListProps {
    messages: AIMessage[];
    loading?: boolean;
    error?: string;
    onRetry?(messageId: string): void;
    onDelete?(messageId: string): void;
    className?: string;
}

class MessageList extends React.Component<MessageListProps> {
    render(): ReactNode;
}

ModelSelector

Component for selecting language models.

interface ModelSelectorProps {
    models: Model[];
    selectedId: string;
    onSelect(id: string): void;
    disabled?: boolean;
    className?: string;
}

class ModelSelector extends React.Component<ModelSelectorProps> {
    render(): ReactNode;
}

AssistantSelector

Component for selecting AI assistants.

interface AssistantSelectorProps {
    assistants: Assistant[];
    selectedId: string;
    onSelect(id: string): void;
    disabled?: boolean;
    className?: string;
}

class AssistantSelector extends React.Component<AssistantSelectorProps> {
    render(): ReactNode;
}

React Hooks

useChat

Hook for chat functionality.

interface UseChatReturn {
    messages: AIMessage[];
    loading: boolean;
    error: string | null;
    sendMessage(text: string, files?: File[]): Promise<void>;
    clearChat(): void;
}

function useChat(): UseChatReturn;

useAssistant

Hook for assistant management.

interface UseAssistantReturn {
    assistant: Assistant | null;
    assistants: Assistant[];
    setAssistant(id: string): void;
    loading: boolean;
    error: string | null;
}

function useAssistant(): UseAssistantReturn;

useModel

Hook for model management.

interface UseModelReturn {
    model: Model | null;
    models: Model[];
    setModel(id: string): void;
    loading: boolean;
    error: string | null;
}

function useModel(): UseModelReturn;

UI Package

Import UI components and hooks from 'dragonfly-sdk/ui':

import { 
    DragonFlyUI,
    ModelSelector, 
    AssistantSelector, 
    MessageList,
    MessageInput,
    useChat,
    useAssistant,
    useModel 
} from 'dragonfly-sdk/ui';

Components

function ChatApp() {
    const { messages, sendMessage, loading } = useChat();
    const { assistant, setAssistant } = useAssistant();
    const { model, setModel } = useModel();

    return (
        <div>
            <ModelSelector
                models={models}
                selectedId={model?.id}
                onSelect={setModel}
            />
            <AssistantSelector
                assistants={assistants}
                selectedId={assistant?.id}
                onSelect={setAssistant}
            />
            <MessageList messages={messages} loading={loading} />
            <MessageInput onSendMessage={sendMessage} />
        </div>
    );
}

React Hooks

useChat

const { 
    messages,
    loading,
    error,
    sendMessage,
    clearChat 
} = useChat();

useAssistant

const {
    assistant,
    assistants,
    setAssistant
} = useAssistant();

useModel

const {
    model,
    models,
    setModel
} = useModel();

Direct Usage Example with Environment Variables

Here's how to use the core package directly with environment variables:

import { DragonFlyCore, ChatManager, AssistantManager } from 'dragonfly-sdk/core';

async function main() {
    // Core will auto-initialize using environment variables
    const core = DragonFlyCore.getInstance();
    const chatManager = core.chatManager;
    const assistantManager = core.assistantManager;
    const llmManager = core.llmManager;

    try {
        // Start using managers directly
        const assistants = assistantManager.listAssistants();
        
        // Send a message
        await chatManager.sendMessageStream(
            'Hello, how can you help me today?',
            'thread-id'
        );

        // Get current model (will use DRAGONFLY_DEFAULT_MODEL from .env)
        const currentModel = llmManager.getCurrentModel();
        console.log('Using model:', currentModel.name);

    } catch (error) {
        console.error('Error:', error);
    }
}

main().catch(console.error);

Core-Only Usage Example

Here's an example of how to use just the core package without the UI components:

import { 
    DragonFlyCore,
    ChatManager,
    AssistantManager,
    LLMManager,
    ThreadManager,
    TokenCalculator
} from 'dragonfly-sdk/core';

async function main() {
    // Initialize core
    const core = DragonFlyCore.getInstance();
    await core.initialize({
        apiKey: 'your-api-key',
        defaultModel: 'gpt-4',
    });

    // Get manager instances
    const chatManager = core.chatManager;
    const assistantManager = core.assistantManager;
    const llmManager = core.llmManager;
    const threadManager = core.threadManager;
    const tokenCalculator = core.tokenCalculator;

    // Configure LLM
    await llmManager.initialize([
        {
            id: 'gpt-4',
            name: 'GPT-4',
            maxTokens: 8000,
            contextWindow: 8000,
            // ... other model config
        }
    ]);
    llmManager.setCurrentModel('gpt-4');

    // Set up assistant
    const assistants = assistantManager.listAssistants();
    assistantManager.setCurrentAssistant(assistants[0].id);

    // Create a new conversation thread
    const thread = threadManager.createThread({
        name: 'New Conversation'
    });

    // Send messages and get responses
    try {
        // Send a message with streaming response
        await chatManager.sendMessageStream(
            'Hello, how can you help me today?',
            thread.id
        );

        // Send a message with files
        const fileIds = ['file1', 'file2'];
        await chatManager.sendMessageNonStream(
            'Please analyze these files',
            thread.id,
            fileIds
        );

        // Get chat history
        const history = chatManager.getChatHistory(thread.id);
        console.log('Chat history:', history);

        // Calculate tokens
        const tokens = tokenCalculator.estimateTokens(history);
        console.log('Total tokens:', tokens);

        // Export thread
        const exportedThread = threadManager.exportThread(thread.id, 'json');
        console.log('Exported thread:', exportedThread);

    } catch (error) {
        console.error('Error:', error);
    }
}

// Advanced usage example with audio transcription and token management
async function advancedExample() {
    const core = DragonFlyCore.getInstance();
    const chatManager = core.chatManager;
    const tokenCalculator = core.tokenCalculator;

    // Transcribe audio
    const audioFileId = 'audio1';
    const transcription = await chatManager.transcribeAudio(audioFileId);

    // Split long text into chunks based on token limit
    const maxTokens = tokenCalculator.getTokenLimit('gpt-4');
    const tokens = tokenCalculator.estimateTokens(transcription);

    await chatManager.sendMessageStream(transcription, 'thread-id');

}

// Error handling example
async function errorHandlingExample() {
    const core = DragonFlyCore.getInstance();
    const chatManager = core.chatManager;
    const threadManager = core.threadManager;

    try {
        // Check if thread exists
        const thread = threadManager.getThread('thread-id');
        if (!thread) {
            throw new Error('Thread not found');
        }

        // Send message with timeout and retry
        let retries = 3;
        while (retries > 0) {
            try {
                await Promise.race([
                    chatManager.sendMessageStream('Hello', thread.id),
                    new Promise((_, reject) => 
                        setTimeout(() => reject(new Error('Timeout')), 5000)
                    )
                ]);
                break;
            } catch (error) {
                retries--;
                if (retries === 0) throw error;
                console.log('Retrying...', retries, 'attempts left');
            }
        }

    } catch (error) {
        console.error('Error in chat operation:', error);
        // Handle specific error types
        if (error.message === 'Thread not found') {
            // Handle thread not found
        } else if (error.message === 'Timeout') {
            // Handle timeout
        }
    }
}

main().catch(console.error);

Complete UI Example

Here's a complete example showing how to use both core and UI packages:

// Core initialization
import { 
    DragonFlyUI
    ModelSelector, 
    AssistantSelector, 
    MessageList,
    MessageInput,
    useChat,
    useAssistant,
    useModel 
} from 'dragonfly-sdk/ui';

// Initialize core
const core = DragonFlyUI.getInstance();
core.initialize({apiKey: 'your-api-key'});

function ChatApp() {
    const { messages, sendMessage, loading } = useChat();
    const { assistant, setAssistant, assistants } = useAssistant();
    const { model, setModel, models } = useModel();

    const handleSendMessage = async (message: string) => {
        try {
            await sendMessage(message);
        } catch (error) {
            console.error('Error sending message:', error);
        }
    };

    return (
        <div>
            <ModelSelector
                models={models}
                selectedId={model?.id}
                onSelect={setModel}
            />
            <AssistantSelector
                assistants={assistants}
                selectedId={assistant?.id}
                onSelect={setAssistant}
            />
            <MessageList messages={messages} loading={loading} />
            <MessageInput onSendMessage={handleSendMessage} />
        </div>
    );
}

export default ChatApp;

Interface Definitions

Core Types

interface Model {
    id: string;
    name: string;
    icon: string;
    maxTokens: number;
    ModelConfig: string[];
    contextWindow: number;
    host: string;
    position: number;
}

interface Assistant {
    id: string;
    assistantId: string;
    name: string;
    instructions: string;
    description: string;
    image: string;
    model: string;
    systemPrompt: string;
    tools: string[];
}

interface AIMessage {
    id: number;
    text: string | string[];
    sender: string;
    assistantId: string;
    timestamp: number;
    fileData: { id: string; name: string; content: string }[];
    imageData: { id: string; name: string; preview: string }[];
    toolCalls: ToolCall[];
    functionOutput: string;
    error: string;
}

interface Thread {
    id: string;
    name: string;
    createdAt: Date;
    updatedAt: Date;
    messages: AIMessage[];
}