NexusAI

Build AI workflows by orchestrating multiple LLM agents that work together to solve complex problems.

Features

• Multi-LLM Support: OpenAI GPT and Anthropic Claude models with seamless switching
• Three Agent Types: ReAct, Planner-Executor, and Reflexion agents
• Pipeline Architecture: Modular, configurable pipeline with pluggable steps
• Intent Detection: Intelligent analysis of user prompts to determine optimal agent configuration
• Parallel Execution: Concurrent agent execution with proper resource management
• Tool Registry: Extensible tool system with built-in implementations
• REST API: Complete API with validation, error handling, and rate limiting
• Developer Ready: Docker support, health checks, metrics, and graceful shutdown

Quick Start

Prerequisites

• Node.js 18+
• OpenAI API key OR Anthropic API key (or both)
• Docker (optional)

Installation

git clone <repository-url>
cd nexus-ai
pnpm install
cp .env.example .env

Edit .env with your API keys:

# Choose your preferred LLM provider
LLM_PROVIDER=openai  # or "anthropic"

# OpenAI Configuration (if using OpenAI)
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4

# Anthropic Configuration (if using Claude)
ANTHROPIC_API_KEY=your_anthropic_api_key_here
ANTHROPIC_MODEL=claude-3-sonnet-20240229

Development

pnpm run dev

Production

pnpm run build
pnpm start

Docker

docker-compose up -d

API Reference

📖 Complete API Documentation: See API.md for comprehensive endpoint documentation with examples.

Base URL: http://localhost:3000/api/v1

Orchestration

Core Endpoints

• POST /orchestrate - Execute multi-agent orchestration
• GET /sessions - List orchestration sessions
• GET /sessions/{id} - Get session details
• DELETE /sessions/{id} - Cancel running session
• GET /agents/types - List available agent types
• GET /tools - List registered tools
• POST /tools/register - Register new tool
• POST /tools/{toolName}/execute - Execute tool
• GET /health - Health check
• GET /metrics - System metrics
• GET /version - Version info

Agent Types

• ReAct Agent: Reasoning and Acting in iterative loops. Think → Act → Observe cycles for complex problem-solving.
• Planner Agent: Creates detailed plans before systematic execution. Best for structured tasks.
• Reflexion Agent: Self-evaluation and iteration to improve response quality through reflection.

LLM Provider Support

The system supports both OpenAI and Anthropic Claude models with seamless switching:

Supported Models

OpenAI:

• gpt-4 (default)
• gpt-4-turbo
• gpt-3.5-turbo

Anthropic:

• claude-3-sonnet-20240229 (default)
• claude-3-opus-20240229
• claude-3-haiku-20240307

Provider Selection

1. Server Default: Set LLM_PROVIDER environment variable
2. Per-Request: Include llmProvider in API requests to override default

{
  "prompt": "Your request here",
  "agentType": "react",
  "llmProvider": "anthropic"
}

3. Auto-Discovery: The system will use available API keys if no provider is specified

Configuration

Key environment variables:

# Provider Selection
LLM_PROVIDER=openai # or "anthropic"

# API Keys (configure based on provider)
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key

# Server Settings
PORT=3000
MAX_PARALLEL_AGENTS=5
MAX_TOKENS=4096
TEMPERATURE=0.7

See .env.example for complete configuration options.

Pipeline Configuration

The pipeline consists of modular steps that can be configured:

{
  "enabledSteps": [
    "intent_detection",
    "agent_selection",
    "tool_assignment",
    "parallel_execution",
    "result_aggregation",
    "quality_check"
  ],
  "parallelExec": true,
  "stepConfig": {
    "maxAgents": 3,
    "qualityThreshold": 0.8
  }
}

Available Steps

• intent_detection: Analyzes prompt to determine required tools and complexity
• agent_selection: Chooses optimal agents based on detected intent
• tool_assignment: Assigns relevant tools to each agent
• parallel_execution: Runs agents concurrently
• result_aggregation: Combines outputs from multiple agents
• quality_check: Validates and scores results
• reflection: Self-evaluation and potential re-execution

Built-in Tools

• web_search: Search the internet for information
• calculator: Perform mathematical calculations
• code_executor: Execute code in various languages
• file_reader: Read and analyze files
• data_analyzer: Analyze structured data (CSV, JSON, XML)

Development

Scripts

• pnpm run dev - Start development server with hot reload
• pnpm run build - Build TypeScript to JavaScript
• pnpm run start - Start production server
• pnpm run test - Run test suite
• pnpm run lint - Lint code with Biome
• pnpm run format - Format code with Biome
• pnpm run typecheck - Run TypeScript type checking

Architecture

src/
├── agents/           # Agent implementations and orchestrator
├── api/              # HTTP API routes and handlers
│   ├── handlers/     # Request handlers
│   └── middleware/   # Koa middleware
├── config/           # Configuration management
├── llm/              # LLM clients (OpenAI, Anthropic) and prompts
│   ├── client.ts     # Factory and OpenAI client
│   ├── anthropicClient.ts # Anthropic Claude client
│   └── prompts.ts    # System prompts
├── pipeline/         # Pipeline framework
├── tools/            # Tool registry and implementations
├── types/            # TypeScript types and schemas
└── server.ts         # Main application entry point

Adding Custom Tools

1. Define the tool schema:

const myTool: Tool = {
  name: "my_custom_tool",
  description: "Does something useful",
  parameters: [
    {
      name: "input",
      type: "string",
      description: "Input parameter",
      required: true,
    },
  ],
  enabled: true,
};

2. Implement the tool function:

const myToolFunction: ToolFunction = async (params) => {
  const { input } = params;
  try {
    const result = await performOperation(input);
    return { success: true, result };
  } catch (error) {
    return { success: false, result: null, error: error.message };
  }
};

3. Register the tool:

toolRegistry.register(myTool, myToolFunction);

Monitoring

Health Checks

• GET /api/v1/health - Application health status
• GET /api/v1/metrics - Performance metrics
• GET /api/v1/status - System resource usage

Metrics Available

• Total/active/completed/failed sessions
• Average execution time
• Total tokens consumed
• Memory and CPU usage

Error Handling

The API provides structured error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "prompt",
        "message": "Prompt is required"
      }
    ],
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Rate Limiting

Default rate limiting: 100 requests per minute per IP.

Security

• Helmet.js for security headers
• CORS configuration
• Request validation with Zod schemas
• Rate limiting
• Timeout protection

License

MIT

Testing

Quick API Test

# Start server
pnpm start

# Health check
curl http://localhost:3000/api/v1/health

# Test orchestration (requires API keys)
curl -X POST http://localhost:3000/api/v1/orchestrate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is 2+2?",
    "agentType": "react"
  }'

Unit Tests

pnpm test
pnpm run test:coverage

📋 Complete Testing Guide: See the Testing section in API.md for comprehensive testing examples, scripts, and load testing instructions.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run linting and type checking
6. Submit a pull request