Velina Labs SDK

Powerful SDK for building next-generation AI agents with advanced reasoning, natural communication, and autonomous actions.

Features

Advanced Reasoning

Meta humans think like humans with complex problem-solving capabilities. The SDK provides a sophisticated reasoning engine that can analyze problems, evaluate options, and create actionable plans.

Natural Communication

Engage in human-like conversations with emotional intelligence. Built-in conversation management and context awareness ensure meaningful interactions.

Autonomous Actions

Enable independent decision-making and real-world task execution. Register custom actions and let your agents execute them autonomously.

Continuous Learning

Your agents evolve and adapt from every interaction and experience. Built-in memory system stores and retrieves knowledge for improved performance over time.

3D Virtual Avatar

Generate realistic 3D avatars from images using Hyper3D.ai API. Create immersive virtual representations of your AI agents with lifelike appearance and animations.

Voice Interaction

Natural voice input and speech synthesis for human-like conversations. Speak to your agent and hear responses in natural-sounding voice with adjustable parameters.

Installation

npm  install  @velina-labs/sdk

Quick Start

import { Agent } from  '@velina-labs/sdk';

  

const  agent = new  Agent({

id:  'my-agent',

name:  'Velina Assistant',

provider:  'openai', // or 'anthropic', 'xai'

});

  

await  agent.initialize();

  

const  response = await  agent.chat('Hello! How can I help you today?');

console.log(response.message);

  

await  agent.shutdown();

Configuration

Create a .env file in your project root:

# AI Provider API Keys (choose at least one)

OPENAI_API_KEY=your_openai_key

ANTHROPIC_API_KEY=your_anthropic_key

XAI_API_KEY=your_xai_key

  

# Default Provider

DEFAULT_PROVIDER=openai

  

# Optional: Custom Models

OPENAI_MODEL=gpt-4-turbo-preview

ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

XAI_MODEL=grok-beta

  

# Database (PostgreSQL Neon)

DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require

  

# Optional: Hyper3D.ai API Key (for 3D avatar generation)

HYPER3D_API_KEY=your_hyper3d_api_key

Supported AI Providers

The SDK supports three AI providers out of the box:

• OpenAI - GPT-4 and other OpenAI models

• Anthropic - Claude models

• X.AI - Grok models

You can easily switch between providers or use different providers for different agents.

Core Concepts

Agent

The main class that orchestrates all functionality. Each agent has:

• Unique ID and name

• AI provider integration

• Reasoning capabilities

• Conversation management

• Action execution

• Memory system

Reasoning Engine

Advanced problem-solving capabilities:

• Think through complex problems

• Analyze options and trade-offs

• Create strategic plans

• Learn from experiences

Conversation Manager

Handles all communication:

• Message history

• Context management

• Database persistence

• Conversation loading

Action Executor

Execute real-world tasks:

• Register custom actions

• Execute actions autonomously

• Track action history

• Log results

Memory System

Persistent knowledge storage:

• Store experiences and insights

• Search memories by keyword

• Categorize by type

• Retrieve historical data

Virtual Assistant

Enhanced agent with 3D avatar and voice capabilities:

• 3D avatar generation from images

• Natural voice synthesis

• Voice input recognition

• Animation states (idle, talking, listening, thinking)

• Event-driven architecture

Usage Examples

Basic Chat

import { Agent } from  '@velina-labs/sdk';

  

const  agent = new  Agent({

id:  'chat-agent',

provider:  'openai',

});

  

await  agent.initialize();

  

const  response = await  agent.chat('What is machine learning?');

console.log(response.message);

  

await  agent.shutdown();

Advanced Reasoning

const  agent = new  Agent({

provider:  'anthropic',

});

  

await  agent.initialize();

  

const  problem = 'How can I improve application performance?';

const  context = {

stack:  'React, Node.js, PostgreSQL',

issues: ['Slow queries', 'High memory usage'],

};

  

const  reasoning = await  agent.think(problem, context);

console.log(reasoning.reasoning);

  

const  plan = await  agent.plan('Reduce load time by 50%', context);

console.log(plan.plan);

  

await  agent.shutdown();

Custom Actions

const  agent = new  Agent({ provider:  'openai' });

await  agent.initialize();

  

agent.registerAction(

'sendNotification',

async (params) => {

// Your custom logic

console.log(`Sending notification: ${params.message}`);

return { success:  true };

},

'Sends a notification to the user'

);

  

const  result = await  agent.executeAction('sendNotification', {

message:  'Task completed!',

});

  

console.log(result);

  

await  agent.shutdown();

Learning and Memory

const  agent = new  Agent({ provider:  'openai' });

await  agent.initialize();

  

await  agent.chat('I prefer TypeScript over JavaScript', {

saveToMemory:  true,

});

  

const  experience = 'Implemented Redis caching';

const  outcome = 'Reduced response time by 60%';

  

const  insights = await  agent.learn(experience, outcome);

console.log(insights.insights);

  

const  memories = await  agent.remember('TypeScript');

console.log(memories);

  

await  agent.shutdown();

Multi-Provider Usage

const  openaiAgent = new  Agent({ provider:  'openai' });

const  anthropicAgent = new  Agent({ provider:  'anthropic' });

const  xaiAgent = new  Agent({ provider:  'xai' });

  

await  openaiAgent.initialize();

await  anthropicAgent.initialize();

await  xaiAgent.initialize();

  

// Use different providers for different tasks

const  response1 = await  openaiAgent.chat('Explain quantum computing');

const  response2 = await  anthropicAgent.chat('Write a poem about AI');

const  response3 = await  xaiAgent.chat('What is the future of technology?');

  

await  openaiAgent.shutdown();

await  anthropicAgent.shutdown();

await  xaiAgent.shutdown();

3D Virtual Assistant with Voice

import { VirtualAssistant } from  '@velina-labs/sdk';

  

const  assistant = new  VirtualAssistant({

id:  'virtual-agent',

name:  'Velina',

provider:  'openai',

voiceEnabled:  true,

voiceOptions: {

rate:  1.0,

pitch:  1.0,

volume:  1.0,

lang:  'en-US',

},

});

  

await  assistant.initialize();

  

assistant.on('speakStart', (text) => {

console.log('Speaking:', text);

});

  

assistant.on('animationChange', (animation) => {

console.log('Animation:', animation);

});

  

await  assistant.chatWithVoice('Hello! Tell me about yourself');

  

const  imageUrl = 'https://example.com/avatar.jpg';

const  avatar = await  assistant.generate3DAvatar(imageUrl, {

quality:  'high',

format:  'glb',

});

  

console.log('3D Model URL:', assistant.get3DModel());

  

await  assistant.shutdown();

Voice Interaction (Browser Only)

const  assistant = new  VirtualAssistant({

provider:  'openai',

voiceEnabled:  true,

});

  

await  assistant.initialize();

  

const { transcript } = await  assistant.listenAndRespond();

  

const  voices = assistant.getAvailableVoices();

console.log('Available voices:', voices);

  

assistant.setVoiceOptions({

rate:  1.2,

pitch:  0.9,

});

  

await  assistant.speakText('I can speak with a customized voice!');

  

await  assistant.shutdown();

API Reference

Agent

Constructor Options

new  Agent({

id:  string, // Unique agent ID

name:  string, // Agent name

provider:  string, // 'openai', 'anthropic', or 'xai'

systemPrompt:  string, // Custom system prompt

personality:  object, // Personality traits

})

Methods

initialize()

Connects to database and loads conversation history.

chat(message, options)

Send a message and receive a response.

• message (string): User message

• options.saveToMemory (boolean): Save conversation to memory

• Returns: { message, usage }

think(problem, context)

Advanced reasoning about a problem.

• problem (string): Problem to analyze

• context (object): Additional context

• Returns: { reasoning, usage }

plan(goal, currentState)

Create an action plan for a goal.

• goal (string): Goal to achieve

• currentState (object): Current situation

• Returns: { plan, usage }

executeAction(name, parameters)

Execute a registered action.

• name (string): Action name

• parameters (object): Action parameters

• Returns: { success, result, actionId }

registerAction(name, handler, description)

Register a custom action.

• name (string): Action name

• handler (function): Async function to execute

• description (string): Action description

learn(experience, outcome)

Learn from an experience.

• experience (string): What happened

• outcome (string): Result of the experience

• Returns: { insights, usage }

remember(query)

Search memories by keyword.

• query (string): Search term

• Returns: Array of memories

getMemories(type, limit)

Retrieve memories by type.

• type (string|null): Memory type or null for all

• limit (number): Maximum results

• Returns: Array of memories

getActionHistory(limit)

Get action execution history.

• limit (number): Maximum results

• Returns: Array of actions

getAvailableActions()

List all registered actions.

• Returns: Array of action definitions

clearConversation()

Clear current conversation history.

shutdown()

Save data and disconnect from database.

VirtualAssistant

Extended Agent class with 3D avatar and voice capabilities.

Constructor Options

new  VirtualAssistant({

...Agent  options,

voiceEnabled:  boolean, // Enable voice features

voiceOptions: {

rate:  number, // Speech rate (0.1-10)

pitch:  number, // Voice pitch (0-2)

volume:  number, // Volume (0-1)

lang:  string, // Language code

},

hyper3dApiKey:  string, // Hyper3D API key

})

Additional Methods

chatWithVoice(message, options)

Chat with automatic voice response.

• Returns: { message, usage }

listenAndRespond(options)

Listen to voice input and respond with voice.

• Returns: { message, usage }

generate3DAvatar(imageUrl, options)

Generate 3D model from image.

• imageUrl (string): URL to source image

• options.quality (string): 'low', 'medium', 'high'

• options.format (string): 'glb', 'obj', 'fbx'

• Returns: Job result with model URL

speakText(text, options)

Speak text with voice synthesis.

stopSpeaking()

Stop current speech output.

stopListening()

Stop voice input.

getAvailableVoices()

List available voice options.

setVoiceOptions(options)

Update voice parameters.

get3DModel()

Get current 3D model URL.

on(event, callback)

Register event listener.

Events:

• speakStart - Voice output started

• speakEnd - Voice output finished

• listenStart - Voice input started

• listenEnd - Voice input finished

• transcript - Voice transcription received

• animationChange - Avatar animation changed

Database Schema

The SDK automatically creates the following tables:

agent_memories

Stores agent memories and learned information.

• id - Primary key

• agent_id - Agent identifier

• content - Memory content

• type - Memory category

• metadata - Additional data (JSON)

• created_at - Creation timestamp

• updated_at - Update timestamp

agent_conversations

Stores conversation history.

• id - Primary key

• agent_id - Agent identifier

• role - Message role (user/assistant)

• content - Message content

• metadata - Additional data (JSON)

• created_at - Creation timestamp

agent_actions

Logs action executions.

• id - Primary key

• agent_id - Agent identifier

• action_type - Action name

• parameters - Action parameters (JSON)

• result - Execution result (JSON)

• status - Execution status

• created_at - Start timestamp

• completed_at - Completion timestamp

Examples

Check the examples/ directory for complete working examples:

• basic-chat.js - Simple conversation

• reasoning.js - Advanced reasoning and planning

• actions.js - Custom action registration and execution

• learning.js - Memory and learning capabilities

• multi-provider.js - Using multiple AI providers

• virtual-assistant.js - 3D avatar and voice interaction

Demo Web Interface

A complete web demo is available in the public/ directory:

npm  install

npm  run  dev

Open your browser to see the interactive 3D virtual assistant with:

• Real-time chat interface

• Voice input and output

• 3D avatar visualization

• Animation states

• Beautiful modern UI

Best Practices

1. Initialize agents - Always call initialize() before using an agent

2. Shutdown properly - Always call shutdown() to save data

3. Use memory wisely - Save important conversations with saveToMemory: true

4. Register actions early - Register all actions after creating the agent

5. Handle errors - Wrap agent calls in try-catch blocks

6. Choose the right provider - Different providers excel at different tasks

7. Set meaningful IDs - Use descriptive agent IDs for better tracking

Architecture

velina/

├── src/                         # SDK source
│
│ ├── agent/
│ │   └── Agent.js
│
│ ├── providers/
│ │   ├── base.js
│ │   ├── openai.js
│ │   ├── anthropic.js
│ │   ├── xai.js
│ │   └── index.js
│
│ ├── reasoning/
│ │   └── engine.js
│
│ ├── communication/
│ │   └── conversation.js
│
│ ├── actions/
│ │   └── executor.js
│
│ ├── learning/
│ │   └── memory.js
│
│ ├── database/
│ │   └── client.js
│
│ ├── virtual/
│ │   ├── VirtualAssistant.js
│ │   ├── voice-service.js
│ │   └── hyper3d-service.js
│
│ ├── config/
│ │   └── index.js
│
│ └── index.js                  # SDK entry point
│
├── examples/                   # SDK usage demos
│ ├── basic-chat.js
│ ├── reasoning.js
│ ├── learning.js
│ ├── action.js
│ ├── multi-provider.js
│ └── virtual-assistant.js
│
├── demo/                       # Frontend demo (Vite)
│ ├── index.html
│ ├── main.js
│ └── styles.css
│
├── public/                     # Static assets
│
├── .env.example
├── package.json
├── vite.config.js
└── README.md

Requirements

• Node.js >= 18.0.0

• PostgreSQL database (Neon recommended)

• At least one AI provider API key

License

MIT

Support

For issues, questions, or contributions, please visit our repository or contact Velina Labs.

Built with ❤️ by Velina Labs