Skip to main content

Quickstart Guide

Get up and running with UG Labs SDK in minutes. This guide will walk you through creating a simple conversational AI application.

Prerequisites​

Install the SDK​

npm install ug-js-sdk

Or using yarn:

yarn add ug-js-sdk

Get Your API Key​

Get your API key from the UG Labs Console

Basic Example​

Here's a simple example that creates a conversation and sends a text message:

import { ConversationManager } from 'ug-js-sdk';

// Initialize the conversation manager
const conversation = new ConversationManager({
  apiKey: 'your-api-key',
  federatedId: 'user-123' // Optional: unique identifier for the user
});

// Set up event listeners
conversation.on('text-event', (event) => {
  console.log('Assistant:', event.text);
});

conversation.on('error', (error) => {
  console.error('Error:', error);
});

// Start the conversation
async function start() {
  try {
    // Connect to the API
    await conversation.start();

    // Configure the conversation
    await conversation.setConfiguration({
      prompt: 'You are a helpful assistant.',
    });

    // Send a text message
    await conversation.sendText('Hello! How are you?');

  } catch (error) {
    console.error('Failed to start conversation:', error);
  }
}

start();

Step-by-Step Explanation​

1. Import and Initialize​

import { ConversationManager } from 'ug-js-sdk';

const conversation = new ConversationManager({
  apiKey: 'your-api-key',
  federatedId: 'user-123'
});

The ConversationManager is the main class that handles all interactions with the UG Labs API.

2. Set Up Event Listeners​

conversation.on('text-event', (event) => {
  console.log('Assistant:', event.text);
});

Listen for events to receive responses from the assistant. Key events include:

  • text-event: Streaming text from the assistant
  • audio-data: Audio chunks for playback
  • data-event: Structured data from utilities
  • error: Error messages

3. Start and Configure​

await conversation.start();

await conversation.setConfiguration({
  prompt: 'You are a helpful assistant.',
});

First, establish a connection with start(), then configure the conversation behavior with setConfiguration().

4. Send Messages​

await conversation.sendText('Hello! How are you?');

Send text messages and receive streaming responses.

Adding Voice Interaction​

To enable voice input and output:

const conversation = new ConversationManager({
  apiKey: 'your-api-key',
  audioEnabled: true // Enable audio input
});

await conversation.setConfiguration({
  prompt: 'You are a helpful voice assistant.',
  audioOutput: true // Enable audio output
});

// Start voice recording
await conversation.startRecording();

// Stop recording and process
await conversation.stopRecording();

Using Utilities​

Add structured outputs with classification or extraction utilities:

await conversation.setConfiguration({
  prompt: 'You are a sentiment analysis assistant.',
  utilities: {
    sentiment: {
      type: 'classify',
      classification_question: 'What is the sentiment: {{user_input}}',
      answers: ['positive', 'negative', 'neutral']
    }
  }
});

// Listen for utility results
conversation.on('data-event', (event) => {
  console.log('Sentiment:', event.data.sentiment);
});

Complete React Example​

Here's a complete example using React:

import React, { useEffect, useState } from 'react';
import { ConversationManager } from 'ug-js-sdk';

function ChatApp() {
  const [conversation, setConversation] = useState(null);
  const [messages, setMessages] = useState([]);
  const [input, setInput] = useState('');

  useEffect(() => {
    const conv = new ConversationManager({
      apiKey: 'your-api-key',
    });

    conv.on('text-event', (event) => {
      setMessages(prev => [...prev, {
        role: 'assistant',
        content: event.text
      }]);
    });

    conv.start().then(() => {
      conv.setConfiguration({
        prompt: 'You are a helpful assistant.',
      });
    });

    setConversation(conv);

    return () => conv.stop();
  }, []);

  const sendMessage = async () => {
    if (!input.trim() || !conversation) return;

    setMessages(prev => [...prev, {
      role: 'user',
      content: input
    }]);

    await conversation.sendText(input);
    setInput('');
  };

  return (
    <div>
      <div className="messages">
        {messages.map((msg, i) => (
          <div key={i} className={msg.role}>
            {msg.content}
          </div>
        ))}
      </div>
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        onKeyPress={(e) => e.key === 'Enter' && sendMessage()}
      />
      <button onClick={sendMessage}>Send</button>
    </div>
  );
}

export default ChatApp;

Next Steps​

Troubleshooting​

Connection Issues​

If you're having trouble connecting:

  1. Verify your API key is correct
  2. Check your network connection
  3. Ensure you're using HTTPS (WebSocket requires secure context)
  4. Check browser console for detailed error messages

Audio Not Working​

If audio input/output isn't working:

  1. Grant microphone permissions when prompted
  2. Ensure your browser supports Web Audio API and MediaRecorder
  3. Try using headphones to avoid echo
  4. Check that audioEnabled is set to true in configuration