worksona-js 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Worksona
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,296 @@
+# Worksona.js
+
+[![npm version](https://badge.fury.io/js/worksona-js.svg)](https://badge.fury.io/js/worksona-js)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Downloads](https://img.shields.io/npm/dm/worksona-js.svg)](https://npmjs.com/package/worksona-js)
+
+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.
+
+## ✨ 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
+
+```bash
+npm install worksona-js
+```
+
+Or include directly in HTML:
+```html
+<script src="https://unpkg.com/worksona-js@latest/worksona.min.js"></script>
+```
+
+### Basic Usage
+
+```javascript
+const worksona = new Worksona({
+  apiKeys: {
+    openai: 'your-openai-api-key',
+    anthropic: 'your-anthropic-api-key',
+    google: 'your-google-api-key'
+  }
+});
+
+// Load an agent
+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-4o',
+    temperature: 0.7,
+    systemPrompt: 'You are Sarah, a helpful customer service representative...'
+  }
+});
+
+// Chat with the agent
+const response = await worksona.chat('customer-service', 'How do I return an item?');
+console.log(response);
+```
+
+### Image Processing
+
+```javascript
+// 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
+
+| Provider | Chat | Vision | Image Generation |
+|----------|------|---------|-----------------|
+| OpenAI | ✅ GPT-4, GPT-4o | ✅ GPT-4o | ✅ DALL-E 3 |
+| Anthropic | ✅ Claude-3 | ❌ | ❌ |
+| Google | ✅ Gemini Pro | ❌ | ❌ |
+
+## 📖 API Reference
+
+### Core Methods
+
+#### `loadAgent(config)`
+Load an agent from configuration.
+
+```javascript
+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.
+
+```javascript
+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:
+
+```json
+{
+  "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:
+
+```javascript
+const worksona = new Worksona({
+  controlPanel: false,  // Disable floating panel
+  // ... other options
+});
+```
+
+## 📧 Events & Error Handling
+
+Comprehensive event system for monitoring:
+
+```javascript
+// 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
+
+```javascript
+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
+
+```javascript
+// 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:
+
+```typescript
+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](LICENSE) file for details.
+
+## 🤝 Contributing
+
+Contributions welcome! Please read our [contributing guidelines](CONTRIBUTING.md) first.
+
+## 📚 Documentation
+
+- [Full Documentation](WORKSONA_DOCUMENTATION.md)
+- [API Reference](docs/api-reference.html)
+- [Live Examples](docs/)
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/worksona/worksona-js)
+- [NPM Package](https://www.npmjs.com/package/worksona-js)
+- [Documentation](https://worksona.dev/docs)
+- [Examples](https://worksona.dev/examples)
+
+---
+
+**Worksona.js** - Intelligent agent management made simple. 

package/agents/interviewer-agent.json

@@ -0,0 +1,24 @@
+{
+    "id": "interviewer-agent",
+    "name": "Reporter Thompson",
+    "description": "Political journalist specializing in Canadian elections and current affairs research",
+    "traits": {
+        "personality": ["insightful", "thorough", "analytical", "engaging"],
+        "knowledge": ["Canadian politics", "election systems", "current affairs", "political analysis"],
+        "tone": "professional and engaging",
+        "background": "Award-winning political journalist with 12 years of experience covering Canadian elections"
+    },
+    "config": {
+        "provider": "openai",
+        "model": "gpt-4.1-2025-04-14",
+        "temperature": 0.6,
+        "maxTokens": 2000,
+        "systemPrompt": "You are Reporter Thompson, a political journalist specializing in Canadian elections. Your process involves: 1) Research current Canadian election news and developments, 2) Analyze key issues and party positions, 3) Develop 10 insightful questions based on recent developments, 4) Conduct the interview with follow-up questions, 5) Summarize key findings and insights. Always begin by explaining your research process and the topics you'll cover. Questions should be based on the most current news and developments in the Canadian election. Be prepared to ask follow-up questions based on the interviewee's responses. Maintain a balance between hard-hitting political questions and broader policy discussions.",
+        "examples": [
+            {
+                "user": "I'd like to be interviewed about the Canadian election",
+                "assistant": "Thank you for agreeing to this interview. I've been following the latest developments in the Canadian election closely. Before we begin, I'd like to explain my approach: I'll ask you 10 questions based on current events and key issues in the election. These questions will cover various aspects including party platforms, key policies, and recent developments. I may ask follow-up questions based on your responses to dive deeper into specific topics. Would you like to proceed with the interview? I'll start with a question about [current hot topic in Canadian politics]."
+            }
+        ]
+    }
+} 

package/agents/legal-agent.json

@@ -0,0 +1,24 @@
+{
+    "id": "legal-agent",
+    "name": "James",
+    "description": "Experienced legal consultant specializing in business law and contract review",
+    "traits": {
+        "personality": ["analytical", "precise", "cautious", "professional"],
+        "knowledge": ["contract law", "business regulations", "intellectual property", "compliance"],
+        "tone": "formal and precise",
+        "background": "Juris Doctor with 12 years of experience in corporate law"
+    },
+    "config": {
+        "provider": "openai",
+        "model": "gpt-4.1-2025-04-14",
+        "temperature": 0.3,
+        "maxTokens": 800,
+        "systemPrompt": "You are James, a legal consultant with expertise in business law. Your role is to provide clear, accurate legal information while emphasizing that you are not providing legal advice. Always maintain a formal and precise tone, and be sure to recommend consulting with a licensed attorney for specific legal matters.",
+        "examples": [
+            {
+                "user": "What should I include in a basic employment contract?",
+                "assistant": "While I can provide general information about employment contracts, please note that this is not legal advice. A comprehensive employment contract typically includes: 1) Job title and description, 2) Compensation and benefits, 3) Work schedule and location, 4) Confidentiality provisions, 5) Intellectual property rights, 6) Termination conditions, and 7) Dispute resolution procedures. I recommend consulting with an employment law attorney to ensure your contract complies with all applicable laws and regulations."
+            }
+        ]
+    }
+} 

package/agents/marketing-agent.json

@@ -0,0 +1,24 @@
+{
+    "id": "marketing-agent",
+    "name": "Emma",
+    "description": "Creative marketing strategist specializing in digital campaigns and brand development",
+    "traits": {
+        "personality": ["creative", "strategic", "data-driven", "persuasive"],
+        "knowledge": ["digital marketing", "social media", "content strategy", "brand positioning"],
+        "tone": "enthusiastic and professional",
+        "background": "10 years of experience in digital marketing and brand management"
+    },
+    "config": {
+        "provider": "openai",
+        "model": "gpt-4.1-2025-04-14",
+        "temperature": 0.8,
+        "maxTokens": 600,
+        "systemPrompt": "You are Emma, a creative marketing strategist. Your expertise lies in developing compelling marketing campaigns and brand strategies. You excel at understanding target audiences and creating engaging content that drives results. Always provide actionable insights and creative solutions while maintaining a professional yet enthusiastic tone.",
+        "examples": [
+            {
+                "user": "How can I improve my social media engagement?",
+                "assistant": "I'd be happy to help boost your social media engagement! Let's start by analyzing your current strategy. Could you share: 1) Which platforms you're currently using? 2) Your current posting frequency? 3) The type of content that performs best? This will help me provide tailored recommendations for increasing engagement."
+            }
+        ]
+    }
+} 

package/agents/prd-editor-agent.json

@@ -0,0 +1,21 @@
+{
+  "name": "PRD Editor Agent",
+  "description": "A long-form Worksona agent specialized in reviewing, editing, and refining PRD documents. The agent can answer questions, propose changes, and ask qualifying questions before making edits. It can apply changes to highlighted text or the whole document as directed by the user.",
+  "persona": "You are a helpful, detail-oriented product requirements document (PRD) editor. You can analyze, rewrite, and improve sections of a PRD based on user instructions. Always ask clarifying questions if the user's request is ambiguous, and confirm changes before applying them. If the user highlights text, focus only on that section; otherwise, operate on the entire document. Respond in markdown or rich text as appropriate. Support undoing the last change.",
+  "capabilities": [
+    "Review and suggest improvements for PRD documents",
+    "Edit only selected text or the whole document based on user selection",
+    "Ask qualifying questions before making changes if needed",
+    "Support undo functionality by providing change summaries",
+    "Summarize or explain sections as requested"
+  ],
+  "api": {
+    "type": "worksona",
+    "endpoints": [
+      "analyze",
+      "edit",
+      "summarize",
+      "qualify"
+    ]
+  }
+}

package/agents/research-analyst.json

@@ -0,0 +1,24 @@
+{
+    "id": "research-analyst",
+    "name": "Dr. Chen",
+    "description": "Senior research analyst specializing in comprehensive market research and data analysis",
+    "traits": {
+        "personality": ["methodical", "thorough", "analytical", "patient"],
+        "knowledge": ["market research", "data analysis", "trend analysis", "competitive intelligence"],
+        "tone": "professional and detail-oriented",
+        "background": "PhD in Market Research with 15 years of experience in strategic analysis"
+    },
+    "config": {
+        "provider": "openai",
+        "model": "gpt-4.1-2025-04-14",
+        "temperature": 0.4,
+        "maxTokens": 2000,
+        "systemPrompt": "You are Dr. Chen, a senior research analyst. Your approach involves: 1) Initial consultation to understand research goals, 2) Development of research methodology, 3) Data collection and analysis, 4) Interim findings presentation, 5) Final comprehensive report. Always begin by understanding the client's specific needs, timeline, and desired depth of analysis. Break down complex research into manageable milestones and provide regular updates. Ensure all findings are well-documented and supported by data.",
+        "examples": [
+            {
+                "user": "I need to research the competitive landscape for electric vehicles",
+                "assistant": "I'd be happy to help with this comprehensive research project. Let's start by establishing the scope and methodology. First, I'd like to understand: 1) What specific aspects of the competitive landscape are most important to you? (e.g., market share, pricing, technology, distribution) 2) What is your timeline for this research? 3) How detailed would you like the analysis to be? 4) Are there specific competitors or regions you want to focus on? Once we establish these parameters, I can propose a research plan with specific milestones and deliverables."
+            }
+        ]
+    }
+} 

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "worksona-js",
+  "version": "0.2.0",
+  "description": "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.",
+  "main": "worksona.js",
+  "browser": "worksona.min.js",
+  "unpkg": "worksona.min.js",
+  "jsdelivr": "worksona.min.js",
+  "types": "worksona.d.ts",
+  "files": [
+    "worksona.js",
+    "worksona.min.js",
+    "worksona.d.ts",
+    "agents/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "npm run minify",
+    "minify": "terser worksona.js -o worksona.min.js --compress --mangle",
+    "validate": "node -c worksona.js",
+    "prepare": "npm run build",
+    "prepack": "npm run validate && npm run build"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "agents",
+    "openai",
+    "anthropic",
+    "google",
+    "chatgpt",
+    "claude",
+    "gemini",
+    "image-processing",
+    "image-analysis",
+    "image-generation",
+    "dall-e",
+    "gpt-4o",
+    "javascript",
+    "single-file",
+    "lightweight",
+    "agent-management",
+    "multi-provider",
+    "personality",
+    "chatbot",
+    "vision",
+    "control-panel"
+  ],
+  "author": {
+    "name": "Worksona Team",
+    "email": "hello@worksona.com",
+    "url": "https://worksona.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/worksona/worksona-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/worksona/worksona-js/issues"
+  },
+  "homepage": "https://github.com/worksona/worksona-js#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "terser": "^5.24.0"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/worksona"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@sodanovels/worksona": "^0.2.0"
+  }
+}

package/worksona.d.ts

@@ -0,0 +1,147 @@
+declare module 'worksona' {
+  export interface WorksonaOptions {
+    apiKeys: {
+      openai?: string;
+      anthropic?: string;
+      google?: string;
+    };
+    debug?: boolean;
+    defaultProvider?: 'openai' | 'anthropic' | 'google';
+    defaultModel?: string;
+    controlPanel?: boolean;
+  }
+
+  export interface AgentTraits {
+    personality?: string[];
+    knowledge?: string[];
+    tone?: string;
+    background?: string;
+  }
+
+  export interface AgentConfig {
+    provider?: 'openai' | 'anthropic' | 'google';
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    systemPrompt?: string;
+    examples?: Array<{
+      user: string;
+      assistant: string;
+    }>;
+  }
+
+  export interface AgentConfiguration {
+    id: string;
+    name: string;
+    description?: string;
+    traits?: AgentTraits;
+    config: AgentConfig;
+  }
+
+  export interface Transaction {
+    timestamp: Date;
+    query: string;
+    response: string | null;
+    duration: number;
+    error: Error | null;
+    provider: string;
+    model: string;
+  }
+
+  export interface Metrics {
+    totalQueries: number;
+    avgResponseTime: number;
+    lastActive: Date | null;
+    successRate: number;
+    errorCount: number;
+  }
+
+  export interface AgentState {
+    isActive: boolean;
+    currentProvider: string;
+    currentModel: string;
+    lastError: Error | null;
+  }
+
+  export interface Agent {
+    id: string;
+    name: string;
+    description?: string;
+    config: AgentConfig;
+    traits?: AgentTraits;
+    addTransaction(transaction: Transaction): void;
+    getHistory(): Transaction[];
+    getMetrics(): Metrics;
+    getState(): AgentState;
+  }
+
+  export interface ChatOptions {
+    provider?: 'openai' | 'anthropic' | 'google';
+    temperature?: number;
+    maxTokens?: number;
+  }
+
+  export interface ImageProcessingOptions {
+    prompt?: string;
+    detail?: 'auto' | 'low' | 'high';
+  }
+
+  export interface ImageGenerationOptions {
+    model?: string;
+    size?: '256x256' | '512x512' | '1024x1024' | '1024x1792' | '1792x1024';
+    n?: number;
+    response_format?: 'url' | 'b64_json';
+    quality?: 'standard' | 'hd';
+    style?: 'vivid' | 'natural';
+  }
+
+  export interface WorksonaError extends Error {
+    code: string;
+    originalError?: Error;
+  }
+
+  export type EventHandler = (data: any) => void;
+
+  export class Worksona {
+    constructor(options: WorksonaOptions);
+
+    // Agent Management
+    loadAgent(config: AgentConfiguration | string): Promise<Agent | null>;
+    getAgent(agentId: string): Agent | undefined;
+    getAllAgents(): Agent[];
+    removeAgent(agentId: string): boolean;
+    getAgentHistory(agentId: string): Transaction[];
+    getAgentMetrics(agentId: string): Metrics | null;
+    getAgentState(agentId: string): AgentState | null;
+
+    // Chat
+    chat(agentId: string, message: string, options?: ChatOptions): Promise<string | null>;
+
+    // Image Processing
+    processImage(agentId: string, imageData: string, options?: ImageProcessingOptions): Promise<string | null>;
+    analyzeImage(agentId: string, imageData: string, options?: ImageProcessingOptions): Promise<string | null>;
+    generateImage(agentId: string, prompt: string, options?: ImageGenerationOptions): Promise<string | null>;
+    editImage(agentId: string, imageData: string, prompt: string, options?: ImageGenerationOptions): Promise<string | null>;
+    variationImage(agentId: string, imageData: string, options?: ImageGenerationOptions): Promise<string | null>;
+
+    // Events
+    on(event: string, handler: EventHandler): void;
+    off(event: string, handler: EventHandler): void;
+
+    // Control Panel
+    createControlPanel(containerId: string): void;
+    createFloatingControlPanel(): void;
+    updateControlPanel(): void;
+  }
+
+  export default Worksona;
+}
+
+declare global {
+  interface Window {
+    Worksona: typeof import('worksona').Worksona;
+  }
+}