worksona-js

v0.3.0

Published

5 months ago

A lightweight, single-file JavaScript library for creating and managing AI agents with distinct personalities across multiple LLM providers. Features comprehensive image processing, real-time control panel, and event-driven architecture.

Downloads

Worksona.js

Last Updated: January 19, 2026 Version: 0.3.0

A lightweight, single-file JavaScript library for creating and managing AI agents with distinct personalities across multiple LLM providers. Now supporting the latest frontier models including GPT-5, Claude Opus 4.5, and Claude Sonnet 4.5.

🆕 What's New in v0.3.0

📚 Complete Documentation Suite - Interactive demos, code examples, visual workflow builder
🔌 REST API Server - Production-ready Express server with 32+ endpoints
🛠️ Tool System - DALL-E image generation, web scraper, text-to-speech
🎨 Agent Personality System - Rich configuration with traits, knowledge, tone
📄 Document Processing - OCR, PDF/DOCX/XLSX parsing built-in
✨ Latest Frontier Models - Full support for GPT-5, Claude Opus 4.5, o3
🔗 Multi-Agent Workflows - Build and execute complex agent delegation chains

✨ Features

🤖 Multi-Provider LLM Support - OpenAI, Anthropic, Google
🖼️ Complete Image Pipeline - Analysis, generation, editing, variations
👥 Agent Personality System - Rich configuration with traits and examples
📊 Real-time Control Panel - Monitor agents, metrics, and transactions
⚡ Event-Driven Architecture - Comprehensive event system
📦 Single File Deployment - No dependencies, easy integration
🎯 Production Ready - Built-in error handling and monitoring

🚀 Quick Start

Installation

Via NPM:

npm i worksona-js

Via CDN:

<script src="https://unpkg.com/worksona-js@latest/worksona.min.js"></script>

NPM Package: https://www.npmjs.com/package/worksona-js

Live Documentation: The complete documentation site is available at docs/www-api/ and can be deployed to any static hosting provider (Netlify, Vercel, GitHub Pages, etc.)

Basic Usage

const worksona = new Worksona({
  apiKeys: {
    openai: 'your-openai-api-key',
    anthropic: 'your-anthropic-api-key',
    google: 'your-google-api-key'
  }
});

// Load an agent with latest GPT-5 model
await worksona.loadAgent({
  id: 'customer-service',
  name: 'Sarah',
  description: 'Customer service representative',
  traits: {
    personality: ['empathetic', 'patient', 'solution-oriented'],
    knowledge: ['product catalog', 'return policies'],
    tone: 'friendly and professional'
  },
  config: {
    provider: 'openai',
    model: 'gpt-5', // Or 'gpt-5-mini', 'gpt-5-nano', 'o3', 'gpt-4o'
    temperature: 0.7,
    systemPrompt: 'You are Sarah, a helpful customer service representative...'
  }
});

// Load an agent with Claude Opus 4.5
await worksona.loadAgent({
  id: 'technical-writer',
  name: 'Alex',
  description: 'Technical documentation specialist',
  config: {
    provider: 'anthropic',
    model: 'claude-opus-4-5-20251101', // Or 'claude-sonnet-4-5-20250929'
    temperature: 0.5,
    systemPrompt: 'You are Alex, an expert technical writer...'
  }
});

// Chat with the agent
const response = await worksona.chat('customer-service', 'How do I return an item?');
console.log(response);

Image Processing

// Analyze an image
const analysis = await worksona.processImage('agent-id', imageUrl, {
  prompt: 'What do you see in this image?'
});

// Generate an image
const imageUrl = await worksona.generateImage('agent-id', 
  'A futuristic cityscape at sunset');

// Edit an image
const editedUrl = await worksona.editImage('agent-id', imageData, 
  'Add a rainbow in the sky');

🎯 Use Cases

Customer Support - Intelligent chatbots with personality
Content Creation - AI writers with specific styles
Image Analysis - Visual content processing
Technical Support - Specialized troubleshooting agents
Sales Assistance - Personalized product recommendations
Creative Projects - AI-powered image generation and editing

🔧 Provider Support

Latest Frontier Models

| Provider | Latest Models | Chat | Vision | Image Generation | |----------|--------------|------|---------|-----------------| | OpenAI | GPT-5, GPT-5-mini, GPT-5-nano, o3, o1, GPT-4o | ✅ | ✅ | ✅ DALL-E 3 | | Anthropic | Claude Opus 4.5, Claude Sonnet 4.5, Claude 3.5 Sonnet | ✅ | ❌ | ❌ | | Google | Gemini Pro | ✅ | ❌ | ❌ |

Supported Models by Provider

OpenAI:

GPT-5 series: gpt-5, gpt-5-mini, gpt-5-nano 🆕
Reasoning models: o3, o3-mini, o1, o1-mini, o1-preview 🆕
GPT-4 series: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4, gpt-4-32k
GPT-3.5 series: gpt-3.5-turbo, gpt-3.5-turbo-16k
Image generation: dall-e-3, dall-e-2

Anthropic:

Claude 4.5: claude-opus-4-5-20251101, claude-sonnet-4-5-20250929 🆕
Claude 3.5: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022
Claude 3: claude-3-opus-20240229, claude-3-sonnet-20240229, claude-3-haiku-20240307
Legacy: claude-2.1, claude-2.0, claude-instant-1.2

Google:

Gemini: gemini-pro, gemini-pro-vision

📖 API Reference

Core Methods

`loadAgent(config)`

Load an agent from configuration.

const agent = await worksona.loadAgent({
  id: 'tech-support',
  name: 'Alex',
  description: 'Technical support specialist',
  config: {
    provider: 'openai',
    model: 'gpt-4o',
    temperature: 0.5
  }
});

`chat(agentId, message, options)`

Send a message to an agent.

const response = await worksona.chat('tech-support', 'My computer won\'t start', {
  temperature: 0.3,
  maxTokens: 800
});

Image Processing Methods

processImage(agentId, imageData, options) - Analyze images
generateImage(agentId, prompt, options) - Generate images from text
editImage(agentId, imageData, prompt, options) - Edit existing images
variationImage(agentId, imageData, options) - Create image variations

Agent Management

getAgent(agentId) - Retrieve an agent
getAllAgents() - Get all loaded agents
removeAgent(agentId) - Remove an agent
getAgentHistory(agentId) - Get conversation history
getAgentMetrics(agentId) - Get performance metrics

🎨 Agent Configuration

Agents are configured using JSON with rich personality traits:

{
  "id": "creative-writer",
  "name": "Maya",
  "description": "Creative writing specialist",
  "traits": {
    "personality": ["creative", "empathetic", "detail-oriented"],
    "knowledge": ["storytelling", "character development", "plot structure"],
    "tone": "inspiring and supportive",
    "background": "Professional writer with 15 years of experience"
  },
  "config": {
    "provider": "openai",
    "model": "gpt-4o",
    "temperature": 0.8,
    "maxTokens": 1000,
    "systemPrompt": "You are Maya, a creative writing coach...",
    "examples": [
      {
        "user": "Help me develop a character",
        "assistant": "I'd love to help you create a compelling character! Let's start with their core motivation..."
      }
    ]
  }
}

📊 Built-in Control Panel

Worksona includes a floating control panel for development and monitoring:

Real-time agent monitoring
API key management
Transaction history
Performance metrics
Provider status indicators

The control panel appears as a floating button and can be disabled:

const worksona = new Worksona({
  controlPanel: false,  // Disable floating panel
  // ... other options
});

📧 Events & Error Handling

Comprehensive event system for monitoring:

// Agent events
worksona.on('agent-loaded', (data) => {
  console.log(`Agent ${data.name} loaded`);
});

// Chat events
worksona.on('chat-complete', ({ agentId, response, duration }) => {
  console.log(`Chat completed in ${duration}ms`);
});

// Image processing events
worksona.on('image-generation-complete', ({ result }) => {
  console.log('Image generated:', result);
});

// Error handling
worksona.on('error', (error) => {
  console.error('Error:', error.message);
});

🔧 Advanced Usage

Error Recovery

async function robustChat(agentId, message, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await worksona.chat(agentId, message);
    } catch (error) {
      if (error.code === 'PROVIDER_ERROR' && i < retries - 1) {
        // Try fallback provider
        const agent = worksona.getAgent(agentId);
        const fallbackProvider = agent.config.provider === 'openai' ? 'anthropic' : 'openai';
        return await worksona.chat(agentId, message, { provider: fallbackProvider });
      }
      if (i === retries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
    }
  }
}

Multi-Agent Workflows

// Research -> Write -> Fact-check workflow
const research = await worksona.chat('research-analyst', 'Research renewable energy trends');
const article = await worksona.chat('content-writer', `Write an article: ${research}`);
const factCheck = await worksona.chat('fact-checker', `Verify: ${article}`);

🛠️ Development

TypeScript Support

TypeScript definitions are included:

import Worksona from 'worksona-js';

const worksona = new Worksona({
  apiKeys: { openai: 'your-key' }
});

Browser Compatibility

Modern browsers (ES2018+)
Node.js 14+
CDN distribution available

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions welcome! Please read our contributing guidelines first.

📚 Documentation & Resources

The complete documentation site is available in docs/www-api/ and includes:

🎯 Quick Links

Documentation

📖 Documentation Hub - Central documentation portal
🔌 API Reference (Swagger) - Interactive API documentation
💻 Code Examples - 60+ copy/paste examples

Interactive Demos

🎮 Demos Home - All interactive demos
🔌 Endpoint API Demo - Test all REST endpoints
📚 Library Demo - Direct library usage
🔗 Delegation Workflow - Visual multi-agent workflows

Vibe Coding (AI-Assisted Development)

🎵 Vibe Coding Home - AI coding assistant support
📝 AI Coding Prompt - Prompts for Claude, ChatGPT, Copilot
💡 Examples - Chatbot, content pipeline, workflow builder

Downloads

📦 worksona.min.js - Minified library (51KB)
📦 worksona.js - Full source (80KB)
📦 worksona-server.js - REST API server
📦 worksona.d.ts - TypeScript definitions
📦 Complete Package (.zip) - All files bundled

🌐 Deploying the Documentation Site

The documentation site in docs/www-api/ is a standalone static site that can be deployed anywhere:

Netlify (Recommended)

# Deploy from repository root
netlify deploy --dir=docs/www-api --prod

# Or use the included netlify.toml configuration
cd docs/www-api
netlify deploy --prod

Vercel

cd docs/www-api
vercel --prod

GitHub Pages

# Push to gh-pages branch
git subtree push --prefix docs/www-api origin gh-pages

Any Static Host Simply upload the contents of docs/www-api/ to your web server or CDN.

📖 Documentation Structure

docs/www-api/
├── index.html              # Landing page
├── overview.html           # Project overview
├── assets/                 # Shared CSS and JS
│   ├── css/
│   │   └── navigation.css  # Unified navigation styles
│   └── js/
│       └── navigation.js   # Navigation functionality
├── docs/                   # Documentation section
│   ├── index.html
│   ├── api-reference-swagger.html
│   └── code-examples-hub.html
├── demos/                  # Interactive demos
│   ├── index.html
│   ├── endpoint-api-demo.html
│   ├── library-internal-demo.html
│   ├── delegation-demo.html
│   └── examples/
├── vibe-coding/           # AI coding assistant support
│   ├── index.html
│   ├── AI_CODING_PROMPT.md
│   ├── README.md
│   └── examples/
├── marketing/             # Marketing site
│   └── index.html
├── downloads/             # Downloadable files
│   ├── worksona.min.js
│   ├── worksona.js
│   ├── worksona-server.js
│   ├── worksona.d.ts
│   └── *.zip
└── netlify.toml           # Netlify configuration

🎨 Features of the Documentation Site

Unified Left Rail Navigation - Persistent navigation on desktop, hamburger menu on mobile
Responsive Design - Optimized for all screen sizes
Interactive Demos - Test all features directly in browser
Code Examples - Copy/paste ready examples in multiple languages
AI Coding Support - Full Vibe Coding integration for AI assistants
Downloadable Files - All library files available for offline use
SEO Optimized - Proper meta tags and structure

→ Start here: docs/index.html

🔗 Links

Worksona.js - Intelligent agent management made simple.