@bpinhosilva/agent-orchestrator 0.0.1

package/docker-compose.yml

@@ -0,0 +1,21 @@
+version: '3.8'
+services:
+  db:
+    image: postgres:15-alpine
+    container_name: agent-orchestrator-db
+    environment:
+      POSTGRES_USER: orchestrator
+      POSTGRES_PASSWORD: orchestrator_password
+      POSTGRES_DB: agent_orchestrator
+    ports:
+      - '5432:5432'
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U orchestrator -d agent_orchestrator"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres-data:

package/eslint.config.mjs

@@ -0,0 +1,35 @@
+// @ts-check
+import eslint from '@eslint/js';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: ['eslint.config.mjs'],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  eslintPluginPrettierRecommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.jest,
+      },
+      sourceType: 'commonjs',
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-floating-promises': 'warn',
+      '@typescript-eslint/no-unsafe-argument': 'warn',
+      "prettier/prettier": ["error", { endOfLine: "auto" }],
+    },
+  },
+);

package/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@bpinhosilva/agent-orchestrator",
+  "version": "0.0.1",
+  "description": "An open-source AI agent orchestrator platform built with NestJS.",
+  "author": "bpinhosilva",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bpinhosilva/agent-orchestrator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bpinhosilva/agent-orchestrator/issues"
+  },
+  "homepage": "https://github.com/bpinhosilva/agent-orchestrator#readme",
+  "scripts": {
+    "build": "nest build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:debug": "nest start --debug --watch",
+    "start:prod": "node dist/main",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "test:e2e": "jest --config ./test/jest-e2e.json",
+    "prepare": "husky",
+    "cli:build": "tsc src/cli.ts --outDir dist --esModuleInterop --skipLibCheck --target es2020 --moduleResolution node --module commonjs --experimentalDecorators --emitDecoratorMetadata"
+  },
+  "bin": {
+    "agent-orchestrator": "./dist/cli.js"
+  },
+  "dependencies": {
+    "@google/generative-ai": "^0.24.1",
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/core": "^11.0.1",
+    "@nestjs/platform-express": "^11.0.1",
+    "@nestjs/serve-static": "^5.0.4",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "commander": "^14.0.3",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.18.0",
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/schematics": "^11.0.0",
+    "@nestjs/testing": "^11.0.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/express": "^5.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.7",
+    "@types/supertest": "^6.0.2",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.2",
+    "gitleaks": "^1.0.0",
+    "globals": "^16.0.0",
+    "husky": "^9.1.7",
+    "jest": "^30.0.0",
+    "prettier": "^3.4.2",
+    "semantic-release": "^25.0.3",
+    "source-map-support": "^0.5.21",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.2.5",
+    "ts-loader": "^9.5.2",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  }
+}

package/public/index.html

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Agent Orchestrator Dashboard</title>
+    <style>
+        body { font-family: sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background-color: #f4f4f9; color: #333; }
+        .container { text-align: center; padding: 2rem; background: #fff; box-shadow: 0 4px 6px rgba(0,0,0,0.1); border-radius: 8px; }
+        h1 { color: #5a67d8; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>Agent Orchestrator</h1>
+        <p>This is a placeholder for the future React SPA admin dashboard.</p>
+        <p>The API is currently serving at <code>/api/v1</code>.</p>
+    </div>
+</body>
+</html>

package/src/agents/agents.controller.spec.ts

@@ -0,0 +1,46 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { AgentsController } from './agents.controller';
+import { AgentsService } from './agents.service';
+import { AgentRequestDto } from './dto/agent-request.dto';
+import { AgentResponse } from './interfaces/agent.interface';
+
+describe('AgentsController', () => {
+  let controller: AgentsController;
+  let service: AgentsService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [AgentsController],
+      providers: [
+        {
+          provide: AgentsService,
+          useValue: {
+            processRequest: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    controller = module.get<AgentsController>(AgentsController);
+    service = module.get<AgentsService>(AgentsService);
+  });
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined();
+  });
+
+  describe('processText', () => {
+    it('should call service with the correctly validated dto', async () => {
+      const dto: AgentRequestDto = { input: 'hello AI' };
+      const expectedResponse: AgentResponse = { content: 'hello human' };
+      const processRequestSpy = jest
+        .spyOn(service, 'processRequest')
+        .mockResolvedValue(expectedResponse);
+
+      const result = await controller.processText(dto);
+
+      expect(processRequestSpy).toHaveBeenCalledWith(dto);
+      expect(result).toBe(expectedResponse);
+    });
+  });
+});

package/src/agents/agents.controller.ts

@@ -0,0 +1,17 @@
+import { Controller, Post, Body, HttpCode, HttpStatus } from '@nestjs/common';
+import { AgentsService } from './agents.service';
+import { AgentRequestDto } from './dto/agent-request.dto';
+import { AgentResponse } from './interfaces/agent.interface';
+
+@Controller('agents')
+export class AgentsController {
+  constructor(private readonly agentsService: AgentsService) {}
+
+  @Post('process')
+  @HttpCode(HttpStatus.OK)
+  async processText(
+    @Body() requestDto: AgentRequestDto,
+  ): Promise<AgentResponse> {
+    return this.agentsService.processRequest(requestDto);
+  }
+}

package/src/agents/agents.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { AgentsController } from './agents.controller';
+import { AgentsService } from './agents.service';
+import { GeminiAgent } from './implementations/gemini.agent';
+
+@Module({
+  controllers: [AgentsController],
+  providers: [AgentsService, GeminiAgent],
+  exports: [AgentsService],
+})
+export class AgentsModule {}

package/src/agents/agents.service.spec.ts

@@ -0,0 +1,44 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { AgentsService } from './agents.service';
+import { GeminiAgent } from './implementations/gemini.agent';
+
+describe('AgentsService', () => {
+  let service: AgentsService;
+  let geminiAgent: GeminiAgent;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        AgentsService,
+        {
+          provide: GeminiAgent,
+          useValue: {
+            getName: jest.fn().mockReturnValue('MockedGeminiAgent'),
+            processText: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get<AgentsService>(AgentsService);
+    geminiAgent = module.get<GeminiAgent>(GeminiAgent);
+  });
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+
+  describe('processRequest', () => {
+    it('should delegate processText to the default agent', async () => {
+      const expectedResponse = { content: 'test response' };
+      const processTextSpy = jest
+        .spyOn(geminiAgent, 'processText')
+        .mockResolvedValue(expectedResponse);
+
+      const result = await service.processRequest({ input: 'test input' });
+
+      expect(processTextSpy).toHaveBeenCalledWith('test input');
+      expect(result).toBe(expectedResponse);
+    });
+  });
+});

package/src/agents/agents.service.ts

@@ -0,0 +1,23 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { GeminiAgent } from './implementations/gemini.agent';
+import { AgentResponse, Agent } from './interfaces/agent.interface';
+import { AgentRequestDto } from './dto/agent-request.dto';
+
+@Injectable()
+export class AgentsService {
+  private readonly logger = new Logger(AgentsService.name);
+  private defaultAgent: Agent;
+
+  constructor(private readonly geminiAgent: GeminiAgent) {
+    this.defaultAgent = geminiAgent;
+    this.logger.log(
+      `Initialized AgentsService with default agent: ${this.defaultAgent.getName()}`,
+    );
+  }
+
+  async processRequest(requestDto: AgentRequestDto): Promise<AgentResponse> {
+    this.logger.debug(`Processing input using default agent`);
+    // Eventually, logic to select agent based on user request/task could go here.
+    return this.defaultAgent.processText(requestDto.input);
+  }
+}

package/src/agents/dto/agent-request.dto.ts

@@ -0,0 +1,7 @@
+import { IsString, IsNotEmpty } from 'class-validator';
+
+export class AgentRequestDto {
+  @IsString()
+  @IsNotEmpty()
+  input: string;
+}

package/src/agents/implementations/gemini.agent.spec.ts

@@ -0,0 +1,41 @@
+import { GeminiAgent } from './gemini.agent';
+
+jest.mock('@google/generative-ai', () => {
+  return {
+    GoogleGenerativeAI: jest.fn().mockImplementation(() => ({
+      getGenerativeModel: jest.fn().mockReturnValue({
+        generateContent: jest.fn().mockResolvedValue({
+          response: {
+            text: () => 'mocked text output',
+          },
+        }),
+      }),
+    })),
+  };
+});
+
+describe('GeminiAgent', () => {
+  let agent: GeminiAgent;
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...originalEnv, GEMINI_API_KEY: 'test_key' };
+    agent = new GeminiAgent();
+  });
+
+  afterAll(() => {
+    process.env = originalEnv;
+  });
+
+  it('should throw an error if API key is not set', () => {
+    delete process.env.GEMINI_API_KEY;
+    expect(() => new GeminiAgent()).toThrow('GEMINI_API_KEY is required');
+  });
+
+  it('should generate content with gemini-2.5-flash-lite', async () => {
+    const response = await agent.processText('test query');
+    expect(response.content).toBe('mocked text output');
+    expect(response.metadata?.model).toBe('gemini-2.5-flash-lite');
+  });
+});

package/src/agents/implementations/gemini.agent.ts

@@ -0,0 +1,50 @@
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import { Agent, AgentResponse } from '../interfaces/agent.interface';
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class GeminiAgent implements Agent {
+  private readonly logger = new Logger(GeminiAgent.name);
+  private genAI: GoogleGenerativeAI;
+
+  constructor() {
+    const apiKey = process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+      this.logger.error('GEMINI_API_KEY environment variable is not set');
+      throw new Error('GEMINI_API_KEY is required to initialize GeminiAgent');
+    }
+    this.genAI = new GoogleGenerativeAI(apiKey);
+  }
+
+  getName(): string {
+    return 'GeminiAgent';
+  }
+
+  async processText(input: string): Promise<AgentResponse> {
+    this.logger.debug(`Processing input with GeminiAgent`);
+    try {
+      const model = this.genAI.getGenerativeModel({
+        model: 'gemini-2.5-flash-lite',
+      });
+      const result = await model.generateContent(input);
+      const output = result.response.text();
+
+      return {
+        content: output,
+        metadata: {
+          model: 'gemini-2.5-flash-lite',
+        },
+      };
+    } catch (error) {
+      if (error instanceof Error) {
+        this.logger.error(
+          `Error processing text: ${error.message}`,
+          error.stack,
+        );
+      } else {
+        this.logger.error(`Error processing text: ${String(error)}`);
+      }
+      throw error;
+    }
+  }
+}

package/src/agents/interfaces/agent.interface.ts

@@ -0,0 +1,9 @@
+export interface AgentResponse {
+  content: string;
+  metadata?: Record<string, any>;
+}
+
+export interface Agent {
+  getName(): string;
+  processText(input: string): Promise<AgentResponse>;
+}

package/src/app.controller.spec.ts

@@ -0,0 +1,22 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+
+describe('AppController', () => {
+  let appController: AppController;
+
+  beforeEach(async () => {
+    const app: TestingModule = await Test.createTestingModule({
+      controllers: [AppController],
+      providers: [AppService],
+    }).compile();
+
+    appController = app.get<AppController>(AppController);
+  });
+
+  describe('root', () => {
+    it('should return "Hello World!"', () => {
+      expect(appController.getHello()).toBe('Hello World!');
+    });
+  });
+});

package/src/app.controller.ts

@@ -0,0 +1,12 @@
+import { Controller, Get } from '@nestjs/common';
+import { AppService } from './app.service';
+
+@Controller()
+export class AppController {
+  constructor(private readonly appService: AppService) {}
+
+  @Get()
+  getHello(): string {
+    return this.appService.getHello();
+  }
+}

package/src/app.module.ts

@@ -0,0 +1,19 @@
+import { Module } from '@nestjs/common';
+import { ServeStaticModule } from '@nestjs/serve-static';
+import { join } from 'path';
+import { AgentsModule } from './agents/agents.module';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+
+@Module({
+  imports: [
+    ServeStaticModule.forRoot({
+      rootPath: join(__dirname, '..', 'public'),
+      exclude: ['/api/(.*)'],
+    }),
+    AgentsModule,
+  ],
+  controllers: [AppController],
+  providers: [AppService],
+})
+export class AppModule {}

package/src/app.service.ts

@@ -0,0 +1,8 @@
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class AppService {
+  getHello(): string {
+    return 'Hello World!';
+  }
+}

package/src/cli.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+const program = new Command();
+
+program
+  .name('agent-orchestrator')
+  .description('An open-source AI agent orchestrator platform')
+  .version('0.0.1');
+
+program
+  .command('run')
+  .description('Start the orchestrator server')
+  .action(async () => {
+    console.log('Starting Agent Orchestrator...');
+    const app = await NestFactory.create(AppModule);
+    await app.listen(process.env.PORT ?? 3000);
+    console.log(`Orchestrator is running on: ${await app.getUrl()}`);
+  });
+
+program.parse(process.argv);

package/src/main.ts

@@ -0,0 +1,18 @@
+import { NestFactory } from '@nestjs/core';
+import { ValidationPipe } from '@nestjs/common';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, {
+    logger: ['log', 'error', 'warn', 'debug', 'verbose'],
+  });
+
+  app.setGlobalPrefix('api/v1');
+  app.useGlobalPipes(new ValidationPipe({ transform: true, whitelist: true }));
+
+  await app.listen(process.env.PORT ?? 3000);
+}
+bootstrap().catch((err) => {
+  console.error('Application failed to start', err);
+  process.exit(1);
+});

package/test/app.e2e-spec.ts

@@ -0,0 +1,56 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { INestApplication, ValidationPipe } from '@nestjs/common';
+import request from 'supertest';
+import { App } from 'supertest/types';
+import { AppModule } from './../src/app.module';
+import { AgentsService } from '../src/agents/agents.service';
+import { GeminiAgent } from '../src/agents/implementations/gemini.agent';
+
+describe('AppController (e2e)', () => {
+  let app: INestApplication<App>;
+  const originalEnv = process.env;
+
+  beforeAll(() => {
+    process.env = { ...originalEnv, GEMINI_API_KEY: 'test_key' };
+  });
+
+  afterAll(() => {
+    process.env = originalEnv;
+  });
+
+  beforeEach(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    })
+      .overrideProvider(GeminiAgent)
+      .useValue({
+        getName: () => 'MockedGeminiAgent',
+        processText: () =>
+          Promise.resolve({ content: 'mocked agent response' }),
+      })
+      .compile();
+
+    app = moduleFixture.createNestApplication();
+    app.setGlobalPrefix('api/v1');
+    app.useGlobalPipes(
+      new ValidationPipe({ transform: true, whitelist: true }),
+    );
+    await app.init();
+  });
+
+  it('/api/v1/agents/process (POST)', () => {
+    // We mock Gemini agent response since providing a fake api key still attempts a real network request.
+    const agentsService = app.get(AgentsService);
+    jest
+      .spyOn(agentsService, 'processRequest')
+      .mockResolvedValue({ content: 'mocked output from e2e' });
+
+    return request(app.getHttpServer())
+      .post('/api/v1/agents/process')
+      .send({ input: 'hello' })
+      .expect(200)
+      .expect((res) => {
+        expect(res.body).toEqual({ content: 'mocked output from e2e' });
+      });
+  });
+});

package/test/jest-e2e.json

@@ -0,0 +1,9 @@
+{
+  "moduleFileExtensions": ["js", "json", "ts"],
+  "rootDir": ".",
+  "testEnvironment": "node",
+  "testRegex": ".e2e-spec.ts$",
+  "transform": {
+    "^.+\\.(t|j)s$": "ts-jest"
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "resolvePackageJsonExports": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "declaration": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "allowSyntheticDefaultImports": true,
+    "target": "ES2023",
+    "sourceMap": true,
+    "outDir": "./dist",
+    "baseUrl": "./",
+    "incremental": true,
+    "skipLibCheck": true,
+    "strictNullChecks": true,
+    "forceConsistentCasingInFileNames": true,
+    "noImplicitAny": false,
+    "strictBindCallApply": false,
+    "noFallthroughCasesInSwitch": false
+  }
+}