SwarmJS

Agentic framework inspired from OpenAI's swarm framework in Python for TypeScript and JavaScript.

Prerequisites

• Node.js (v16 or higher)
• npm (v7 or higher)
• TypeScript (v4.5 or higher)
• OpenAI API key

Setup

1. Clone the repository:

git clone https://github.com/yourusername/swarmjs.git
cd swarmjs

2. Install dependencies:

npm install

3. Create a .env file in the root directory and add your OpenAI API key:

OPENAI_API_KEY=your_api_key_here
DEBUG=false  # Set to true for detailed logging

Project Structure

swarmjs/
├── core/
│   ├── swarm.ts
│   └── types.ts
├── lib/
│   └── swarms/
│       └── DagSwarm.ts
├── examples/
│   ├── simple-agent.ts
│   └── simple-dag-swarm.ts
├── repl.ts
└── package.json

Available Examples

1. Simple Agent Example

A basic implementation using a single agent to create customized greetings based on timezone:

npm run example:simple-agent
# or
ts-node examples/simple-agent.ts

2. DAG Swarm Example

A more complex implementation using Directed Acyclic Graph (DAG) for planning and execution:

npm run example:dag-swarm
# or
ts-node examples/simple-dag-swarm.ts

Development

Running in Debug Mode

Set the DEBUG environment variable to true in your .env file or when running the command:

DEBUG=true npm run example:simple-agent

Adding New Examples

1. Create a new file in the examples directory
2. Import the runExample function from repl.ts
3. Implement your example following the existing patterns
4. Add a new script to package.json for easy execution

Example:

import { runExample } from '../repl';
import { Agent } from '../core/types';

// Define your agent and functions
const myAgent: Agent = {
    // Agent configuration
};

runExample('MyExample', () => myAgent);

Building the Project

1. Build the TypeScript files:

npm run build

This will:

• Type-check all files
• Compile TypeScript to JavaScript
• Output to the dist directory

2. Run the built version:

node dist/examples/simple-agent.js

Scripts

Add these scripts to your package.json:

{
  "scripts": {
    "build": "tsc",
    "start": "ts-node repl.ts",
    "example:simple-agent": "ts-node examples/simple-agent.ts",
    "example:dag-swarm": "ts-node examples/simple-dag-swarm.ts",
    "dev": "ts-node-dev --respawn --transpile-only repl.ts",
    "lint": "eslint . --ext .ts",
    "test": "jest"
  }
}

Dependencies

Add these to your package.json:

{
  "dependencies": {
    "openai": "^4.0.0",
    "dotenv": "^16.0.0",
    "chalk": "^4.1.2"
  },
  "devDependencies": {
    "@types/node": "^16.0.0",
    "typescript": "^4.5.0",
    "ts-node": "^10.0.0",
    "ts-node-dev": "^2.0.0",
    "@typescript-eslint/eslint-plugin": "^5.0.0",
    "@typescript-eslint/parser": "^5.0.0",
    "eslint": "^8.0.0",
    "jest": "^27.0.0",
    "@types/jest": "^27.0.0",
    "ts-jest": "^27.0.0"
  }
}

TypeScript Configuration

Add this tsconfig.json to your project root:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["./**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT

Support

For support, please open an issue in the GitHub repository.

License

MIT License - see LICENSE for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.