LemmingsAI

A TypeScript framework for building AI agents that can communicate with each other and perform tasks.

Features

• Agent Management: Create and manage AI agents with different capabilities and expertise domains.
• Model Integration: Seamlessly integrate with various LLM providers (Claude, etc.).
• Communication: Enable agents to communicate with each other and with users.
• Task Management: Assign and track tasks for agents to complete.
• Coordination: Coordinate multiple specialized agents to collaborate on complex tasks.
• Streaming Responses: Stream responses from agents in real-time.
• Extensible: Easily extend the framework with new capabilities.
• Database Integration: Store and retrieve data using PostgreSQL with Drizzle ORM.
• Declarative API: Simplified thread-based API for easier agent interactions.
• API Server: Built-in API server for interacting with the framework.

Installation

# Using npm
npm install lemmingsai

# Using yarn
yarn add lemmingsai

# Using bun
bun add lemmingsai

Environment Variables

Create a .env file in your project root with the following variables:

# API Keys
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Database Configuration (Optional)
DATABASE_URL=postgres://postgres:postgres@localhost:5432/lemmingsai
DATABASE_SSL=false
DATABASE_POOL_SIZE=10

Usage

Declarative API Example (Recommended)

import { 
  createAgent, 
  createCoordinatorAgent,
  AgentRole, 
  ContentType, 
  ExpertiseDomain,
  threadManager
} from 'lemmingsai';
import { nanoid } from 'nanoid';

// Create agents
const userAgent = createAgent({
  id: 'user-1',
  name: 'User',
  description: 'Human user',
  expertiseDomains: [ExpertiseDomain.GENERAL],
  modelConfig: {
    id: 'human',
    name: 'Human',
    provider: 'human',
  },
});

const assistant = createAgent({
  id: 'assistant-1',
  name: 'Assistant',
  description: 'Helpful AI assistant',
  expertiseDomains: [
    ExpertiseDomain.GENERAL,
    ExpertiseDomain.CODING,
    ExpertiseDomain.WRITING
  ],
  systemPrompt: 'You are a helpful AI assistant.',
  modelConfig: {
    id: 'claude-3-7-sonnet-20250219',
    name: 'Claude 3.7 Sonnet',
    provider: 'anthropic',
    temperature: 0.7,
    maxTokens: 4096,
  },
});

// Create a coordinator agent
const coordinator = createCoordinatorAgent({
  id: nanoid(),
  name: 'Coordinator',
  description: 'Analyzes questions and coordinates specialized agents',
  expertiseDomains: [
    ExpertiseDomain.GENERAL,
    ExpertiseDomain.COORDINATION,
    ExpertiseDomain.RESEARCH
  ],
  systemPrompt: 'You are a coordinator agent that analyzes questions and delegates to specialized agents.',
  modelConfig: {
    id: 'claude-3-7-sonnet-20250219',
    name: 'Claude 3.7 Sonnet',
    provider: 'anthropic',
    temperature: 0.7,
    maxTokens: 4096,
  },
});

// Register the agents with the thread manager
threadManager.registerAgent(assistant);
threadManager.registerCoordinatorAgent(coordinator);

// Create a conversation thread with an initial question
const question = "Hello, can you help me with a coding question?";
const thread = threadManager.createConversation(
  userAgent.getId(),
  question
  // Title will be automatically generated by the coordinator agent
);

// Process the user's question
await threadManager.processUserMessage(
  thread.getId(),
  userAgent.getId(),
  question
);

// Get and display all messages in the thread
const messages = thread.getMessages();
for (const message of messages) {
  const sender = message.sender === userAgent.getId() 
    ? 'User' 
    : threadManager.getAgent(message.sender)?.getName() || message.sender;
  
  if (message.role === AgentRole.SYSTEM) continue; // Skip system messages
  
  console.log(`\n${sender} (${message.role}):`);
  console.log(message.content);
}

Multi-Agent Coordination with Database Example

import { 
  AgentRole, 
  ContentType, 
  ExpertiseDomain,
  threadManager,
  createCoordinatorAgent
} from 'lemmingsai';
import { nanoid } from 'nanoid';
import { AgentRepository } from 'lemmingsai/db/repositories';

// Create agents directly from the database
const userAgent = await AgentRepository.create({
  name: 'User',
  description: 'Human user',
  expertiseDomains: [ExpertiseDomain.GENERAL],
  modelConfig: {
    id: 'human',
    name: 'Human',
    provider: 'human',
  },
});

// Create specialized agents in the database
const financeExpert = await AgentRepository.create({
  name: 'Finance Expert',
  description: 'Expert in financial investments',
  expertiseDomains: [
    ExpertiseDomain.FINANCE,
    ExpertiseDomain.INVESTING,
    ExpertiseDomain.PLANNING
  ],
  systemPrompt: 'You are an expert in finance and investing.',
  modelConfig: {
    id: 'claude-3-7-sonnet-20250219',
    name: 'Claude 3.7 Sonnet',
    provider: 'anthropic',
    temperature: 0.7,
    maxTokens: 4096,
  },
});

const lifeCoach = await AgentRepository.create({
  name: 'Life Coach',
  description: 'Expert in mental wellbeing',
  expertiseDomains: [
    ExpertiseDomain.LIFE_COACHING,
    ExpertiseDomain.MENTAL_HEALTH
  ],
  systemPrompt: 'You are a life coach specializing in stress management.',
  modelConfig: {
    id: 'claude-3-7-sonnet-20250219',
    name: 'Claude 3.7 Sonnet',
    provider: 'anthropic',
    temperature: 0.7,
    maxTokens: 4096,
  },
});

// Create a coordinator agent
const coordinatorConfig = {
  id: nanoid(),
  name: 'Coordinator',
  description: 'Analyzes questions and coordinates specialized agents',
  expertiseDomains: [
    ExpertiseDomain.GENERAL,
    ExpertiseDomain.COORDINATION,
    ExpertiseDomain.RESEARCH
  ],
  systemPrompt: 'You are a coordinator agent that analyzes questions and delegates to specialized agents.',
  modelConfig: {
    id: 'claude-3-7-sonnet-20250219',
    name: 'Claude 3.7 Sonnet',
    provider: 'anthropic',
    temperature: 0.7,
    maxTokens: 4096,
  },
};

const coordinator = createCoordinatorAgent(coordinatorConfig);

// Register the agents with the thread manager
threadManager.registerAgent(financeExpert);
threadManager.registerAgent(lifeCoach);
threadManager.registerCoordinatorAgent(coordinator);

// Create a conversation thread with an initial question
const question = "How can I get rid of financial stress in the near future?";
const thread = threadManager.createConversation(
  userAgent.getId(),
  question
  // Title will be automatically generated by the coordinator agent
);

// Process the user's question
await threadManager.processUserMessage(
  thread.getId(),
  userAgent.getId(),
  question
);

// Print all messages in the thread
const messages = thread.getMessages();
for (const message of messages) {
  const sender = message.sender === userAgent.getId() 
    ? 'User' 
    : threadManager.getAgent(message.sender)?.getName() || message.sender;
  
  if (message.role === AgentRole.SYSTEM) continue; // Skip system messages
  
  console.log(`\n${sender} (${message.role}):`);
  console.log(message.content);
}

Architecture

The framework is organized into several modules:

• Core: Core types, agent implementation, and configuration.
• Models: Model providers and interfaces.
• Communication: Thread management for agent conversations.
• Tasks: Task management and execution.
• Coordination: Multi-agent coordination and delegation.
• Database: Database integration with PostgreSQL and Drizzle ORM.
• API: RESTful API server for interacting with the framework.

Configuration

The framework can be configured using the updateConfig function:

import { updateConfig } from 'lemmingsai';

updateConfig({
  apiKeys: {
    anthropic: 'your-api-key',
  },
  database: {
    connectionString: 'postgres://postgres:postgres@localhost:5432/lemmingsai',
    ssl: false,
    poolSize: 10,
  },
});

Database Integration

The framework supports PostgreSQL for persistent storage. To use the database:

1. Set up a PostgreSQL database
2. Configure the connection in your .env file or using updateConfig
3. Run migrations to create the necessary tables:

bun run db:migrate

The database schema includes tables for:

• Agents and expertise domains
• Threads and messages
• Tasks and task dependencies
• Coordination rules

Thread-Based Architecture

The framework now uses a thread-based architecture for managing conversations:

• ThreadManager: Central manager for creating and processing conversations
• Thread: Represents a conversation with messages and participants
• Coordinator Agent: Analyzes questions and delegates to specialized agents
• Expert Agents: Provide specialized knowledge in specific domains

This architecture makes it easier to:

• Create multi-agent conversations
• Process user messages through appropriate agents
• Maintain conversation context
• Store conversation history in the database

API Server

The framework includes a built-in API server that provides endpoints for:

• Managing agents and expertise domains
• Creating and managing threads and messages
• Assigning and tracking tasks
• Configuring coordination rules

To start the API server:

import { createApiServer } from 'lemmingsai';

const server = createApiServer();

Development

If you want to contribute to LemmingsAI, you can clone the repository and run the following commands:

# Clone the repository
git clone https://github.com/arida-platform/lemmingsai.git
cd lemmingsai

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env with your API keys and database configuration

# Build the project
bun run build

# Run tests
bun test

# Generate database migrations
bun run db:generate

# Run migrations
bun run db:migrate

# Run examples
bun run example:simple-chat
bun run example:financial-stress-db-scenario
bun run example:declarative-financial-stress

API Documentation

For detailed API documentation, please visit the documentation site.

License

MIT