symposium 0.12.8 → 0.12.10

package/README.md

@@ -0,0 +1,150 @@
+# Symposium
+
+Symposium is an npm library designed to simplify the deployment and management of AI agents. Its modular and flexible architecture makes it easy to create agents that can interact with users, execute functions through integrated tools, and manage complex conversation threads—all while supporting multiple language models from various providers.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Architecture](#architecture)
+- [Supported Models](#supported-models)
+- [Extending Symposium](#extending-symposium)
+- [Examples](#examples)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Overview
+
+Symposium provides a robust framework for deploying AI agents with ease. It handles message threading, state management, logging, and even conversation summarization to keep interactions within token limits. With built-in support for multiple AI models and a plugin-like system for tools, Symposium enables developers to quickly build sophisticated agent-based applications.
+
+---
+
+## Features
+
+- **Agent Management**: Create and manage agents that process user messages and execute actions.
+- **Tool Integration**: Extend your agents’ capabilities by integrating custom tools with defined functions.
+- **Thread & Memory Handling**: Manage conversation state and threads seamlessly, with automatic summarization support.
+- **Multi-Agent Coordination**: Support for multi-agent systems to allow agents to collaborate and share tasks.
+- **Flexible Model Support**: Out-of-the-box compatibility with various models including OpenAI, Anthropic, Groq, and DeepSeek.
+- **Structured Function Calls**: Enable agents to call functions using structured output, ensuring clarity and consistency.
+
+---
+
+## Installation
+
+Install Symposium via npm:
+
+```bash
+npm install symposium
+```
+
+---
+
+## Usage
+
+Below is a basic example of how to create a custom agent using Symposium:
+
+```js
+import { Symposium, Agent } from 'symposium';
+
+class MyAgent extends Agent {
+  constructor(options = {}) {
+    super(options);
+    this.name = 'MyAgent';
+  }
+
+  async doInitThread(thread) {
+    await thread.addMessage('system', 'Welcome! How can I assist you today?');
+  }
+}
+
+(async () => {
+  const myAgent = new MyAgent();
+  await myAgent.init();
+  
+  const thread = await myAgent.getThread('example-thread');
+  await myAgent.message(thread, 'default', 'Hello, agent!');
+})();
+```
+
+---
+
+## Architecture
+
+Symposium is built around several core components:
+
+- **Agent**: The base class for creating agents. Agents process messages, manage threads, and interact with tools.
+- **Tool**: Extend functionality by integrating custom functions. Tools define their own functions and provide implementations through the `callFunction` method.
+- **Thread**: Represents a conversation, handling message storage, state management, and persistence.
+- **Logger & MemoryHandler**: Utilities for logging events and managing conversation memory, respectively.
+- **Summarizer**: A specialized memory handler that summarizes conversation threads to maintain context within token limits.
+- **Interface**: Abstracts output and error handling, enabling custom integrations with external systems.
+
+---
+
+## Supported Models
+
+Symposium supports a variety of AI models, allowing you to switch between them based on your needs:
+
+- **OpenAI Models**:
+    - GPT-3.5-turbo
+    - GPT-4, GPT-4Turbo, GPT-4o
+    - GPT-o1, GPT-o1 mini
+- **Anthropic Models**:
+    - Claude3 variants (Haiku, Sonnet, Opus, and 3.5 Sonnet)
+- **Groq Models**:
+    - Llama3, Mixtral8
+- **DeepSeek Models**:
+    - DeepSeekChat, DeepSeekReasoner
+- **Other Models**:
+    - Whisper (for speech-to-text)
+
+These models are encapsulated in their own modules, and you can easily switch the active model by updating the conversation thread state.
+
+---
+
+## Extending Symposium
+
+Symposium is designed to be extended and customized:
+
+- **Creating Custom Agents**: Inherit from the `Agent` class and override methods like `doInitThread` and `message` to implement custom behavior.
+- **Implementing Tools**: Build your own tools by extending the `Tool` class. Define the functions your tool exposes and provide implementations via `callFunction`.
+- **Custom Memory Handlers & Loggers**: Implement your own memory or logging strategies by creating classes that adhere to the respective interfaces.
+- **Defining Interfaces**: Customize output and error handling by implementing your own `Interface` classes.
+
+---
+
+## Examples
+
+The repository includes an `examples` folder with sample implementations demonstrating:
+
+- **ChatAgent**: A basic conversational agent.
+- **MultiAgent**: An agent that coordinates with other agents via internal interfaces.
+- **TitlerAgent**: An agent that generates concise titles for conversations.
+- **Tools**: Examples like `GenericTool` and `MultiAgentTool` show how to integrate custom functionality.
+
+> **Important:** The content in the `examples` folder is provided solely for demo purposes and will not be part of the exported npm package. You can use these examples as a guide for building your own implementations.
+
+---
+
+## Contributing
+
+Contributions to Symposium are welcome! If you have ideas, improvements, or bug fixes, please fork the repository and submit a pull request.
+
+---
+
+## License
+
+Symposium is released under the ISC License.
+
+---
+
+Developed by **Domenico Giambra**
+
+For more details or to report issues, please refer to the repository's issue tracker. Enjoy building your AI-driven applications with Symposium!

package/examples/ChatAgent.js

@@ -0,0 +1,21 @@
+import {Agent, Symposium} from "symposium";
+import GenericTool from "./Tools/GenericTool.js";
+
+export default class ChatAgent extends Agent {
+	default_model = 'gpt-4o';
+
+	constructor(options = {}) {
+		super(options);
+
+		this.name = 'ChatAgent';
+
+		this.addTool(new GenericTool());
+	}
+
+	async doInitThread(thread) {
+		await thread.addMessage('system',
+			`You are a helpful assistant, assist the user using the tools you are provided with.
+			Current time is: ${(new Date()).toLocaleDateString()}`
+		);
+	}
+}

package/examples/MultiAgent.js

@@ -0,0 +1,115 @@
+import {Agent, Symposium} from "symposium";
+import MultiAgentTool from "./Tools/MultiAgentTool.js";
+
+export default class MultiAgent extends Agent {
+	default_model = 'gpt-4o';
+
+	constructor(options = {}) {
+		options = {
+			agents: [],
+			...options,
+		};
+
+		super(options);
+		this.name = 'Multi Agent';
+
+		this.internalInterface = {
+			name: 'agent-vs-agent',
+			promises: [],
+			init: async () => {
+			},
+			message: async (thread, msg) => {
+			},
+			output: async (thread, msg) => {
+			},
+			error: async (thread, error) => {
+			},
+		};
+
+		this.addTool(new MultiAgentTool(this.options.agents));
+	}
+
+	async init() {
+		await super.init();
+
+		for (let agent of this.options.agents) {
+			agent.options.interfaces = [this.internalInterface];
+			await agent.init();
+		}
+	}
+
+	async reset(thread) {
+		await super.reset(thread);
+
+		for (let agent of this.options.agents) {
+			const sub_thread = await agent.getThread(thread.id, 'agent-vs-agent');
+			await agent.reset(sub_thread);
+		}
+	}
+
+	async doInitThread(thread) {
+		const memory = await this.tools.get('Memory').get();
+
+		await thread.addMessage('system',
+			`You are a helpful assistant, assist the user using the tools you are provided with.
+			In order to do so, you have a series of agents at your service, with which you can communicate behind the scenes to provide the user with what they asked for. You can communicate with them through their respective tools that you have.
+			You can talk to the agents in natural language, and also respond to them multiple times if necessary. Try to use clear and direct language with precise instructions when talking to an agent.
+			
+			At the end of each task, when the agent has completed its function, remember to reset the conversation with the agent to save memory. You can do this using the "reset" function.
+			
+			Interrogate them only if the user asks to perform tasks that concern them, otherwise you can rely on your knowledge to respond directly.
+			
+			Current time is: ${(new Date()).toLocaleDateString()}`,
+		);
+
+		for (let agent of this.options.agents) {
+			const sub_thread = await agent.getThread(thread.id, 'agent-vs-agent');
+			if (sub_thread) {
+				await sub_thread.flush();
+				await agent.initThread(sub_thread);
+			}
+		}
+	}
+
+	async beforeExecute(thread) {
+		if (this.options.reasoning) {
+			let reasoning = await this.generateCompletion(thread, {
+				functions: [
+					{
+						name: 'ragionamento',
+						description: 'Before responding to the user, ask yourself what needs to be done and if you need to ask for more info.',
+						parameters: {
+							type: 'object',
+							properties: {
+								ragionamento: {
+									type: 'string',
+									description: 'Reflect on the request just made. What do you need to do to fulfill the user\'s request? These are your thoughts and the user cannot see them.',
+								}
+							},
+							required: ['ragionamento'],
+						}
+					},
+					...(await this.getFunctions()),
+				],
+				force_function: 'ragionamento',
+			});
+
+			if (reasoning) {
+				reasoning = Symposium.extractFunctionsFromResponse(reasoning)[0];
+				await this.log('reasoning', reasoning);
+				thread.addMessage('assistant', "[Thinking] " + reasoning.ragionamento + "\n");
+			}
+		}
+
+		return thread;
+	}
+
+	async getPromptWordsForTranscription(thread) {
+		let words = [this.name];
+		for (let agent of this.options.agents) {
+			const sub_thread = await agent.getThread(thread.id, 'agent-vs-agent');
+			words = [...words, ...(await agent.getPromptWordsForTranscription(sub_thread))];
+		}
+		return words;
+	}
+}

package/examples/TitlerAgent.js

@@ -0,0 +1,25 @@
+import {Agent} from "symposium";
+
+export default class TitlerAgent extends Agent {
+	default_model = 'gpt-4o';
+
+	constructor(options) {
+		super(options);
+		this.name = 'Titler';
+	}
+
+	async init() {
+		await super.init();
+
+		this.utility = {
+			type: 'text',
+		};
+	}
+
+	async doInitThread(thread) {
+		await thread.addMessage('system',
+			`Your task is to observe the following message, which represents the beginning of a conversation from the user, and give a title of a few words (maximum 30 characters) that describes it as accurately as possible. Even a single word is fine, if necessary.
+			Do not write anything else in your message, but only and exclusively the title.`
+		);
+	}
+}

package/examples/Tools/GenericTool.js

@@ -0,0 +1,42 @@
+import {Tool} from "symposium";
+
+export default class GenericTool extends Tool {
+	name = 'GenericTool';
+
+	async getFunctions() {
+		return [
+			{
+				name: `create_todo`,
+				description: `Create a new TODO`,
+				parameters: {
+					type: 'object',
+					properties: {
+						title: {
+							type: 'string',
+							description: 'Title of the TODO',
+						},
+						description: {
+							type: 'string',
+							description: 'Description of the TODO',
+						},
+						due_date: {
+							type: 'string',
+							description: 'Due date of the TODO',
+						},
+					},
+					required: ['title', 'description', 'due_date'],
+				},
+			}
+		];
+	}
+
+	async callFunction(thread, name, payload) {
+		try {
+			// Implement your function here
+
+			throw new Error(`Unknown function: ${name}`);
+		} catch (error) {
+			return {error: error.response?.body || error};
+		}
+	}
+}

package/examples/Tools/MultiAgentTool.js

@@ -0,0 +1,77 @@
+import {Tool} from "symposium";
+
+export default class MultiAgentTool extends Tool {
+	name = 'MultiAgentTool';
+	agents;
+
+	constructor(agents) {
+		super();
+		this.agents = agents;
+	}
+
+	async getFunctions() {
+		return [
+			...this.agents.map(a => ({
+				name: a.name,
+				description: a.description,
+				parameters: {
+					type: 'object',
+					properties: {
+						message: {
+							type: 'string',
+							description: 'The message to send to the agent'
+						}
+					}
+				}
+			})),
+			{
+				name: 'reset',
+				description: 'Reset an agent\'s memory to start the conversation again',
+				parameters: {
+					type: 'object',
+					properties: {
+						agent: {
+							type: 'string',
+							description: 'The name of the agent to reset'
+						}
+					}
+				}
+			}
+		];
+	}
+
+	async callFunction(thread, name, payload) {
+		try {
+			if (name === 'reset') {
+				const agent = this.agents.find(a => a.name === payload.agent);
+				if (!agent)
+					throw new Error('No agent named "' + payload.agent + '"');
+
+				const sub_thread = await agent.getThread(thread.id, 'agent-vs-agent');
+
+				await agent.reset(sub_thread);
+
+				return {success: true};
+			} else {
+				const agent = this.agents.find(a => a.name === name);
+				if (!agent)
+					throw new Error('No agent named "' + name + '"');
+
+				return await (new Promise(async (resolve, reject) => {
+					try {
+						const sub_thread = await agent.getThread(thread.id, 'agent-vs-agent');
+
+						await agent.message(sub_thread, 'agent-vs-agent', payload.message, msg => {
+							resolve({reply: msg});
+						});
+					} catch (e) {
+						console.error(JSON.stringify(e));
+						reject(e);
+					}
+				}));
+			}
+		} catch (error) {
+			return {error};
+		}
+	}
+}

package/package.json

@@ -1,14 +1,14 @@
 {
   "type": "module",
   "name": "symposium",
-  "version": "0.12.8",
+  "version": "0.12.10",
   "description": "Agents",
   "main": "index.js",
   "author": "Domenico Giambra",
   "license": "ISC",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.36.0",
-    "groq-sdk": "^0.13.0",
+    "groq-sdk": "^0.15.0",
     "openai": "^4.12.1",
     "tiktoken": "^1.0.10"
   }