AI Orchestrator DB

A powerful TypeScript library for managing and persisting AI agent, prompt, and prompt history data in the context of the AI Orchestrator ecosystem. Built with Clean Architecture principles and designed for seamless integration with NestJS projects.

Table of Contents

• Overview
• Installation
• Setup & Integration
• Core Concepts
• Usage Examples
  • Agent CRUD
  • Prompt CRUD
  • Prompt History CRUD
• DTOs, Presenters & Converters
• Extending the Library
• License

Overview

ai-orchestrator-db provides a robust, modular, and extensible database layer for AI Orchestrator applications. It supports CRUD operations for agents, prompts, and prompt histories, and exposes RESTful controllers for easy API integration. The library is structured for testability, scalability, and maintainability.

Installation

Install via npm (from your monorepo root):

npm install @sftech/ai-orchestrator-db

Or, if using yarn:

yarn add @sftech/ai-orchestrator-db

Setup & Integration

Import the module into your NestJS application:

import { AiOrchestratorDbModule } from '@sftech/ai-orchestrator-db';

@Module({
  imports: [
    AiOrchestratorDbModule.register({
      // Provide your DB configuration and options here
    }),
  ],
})
export class AppModule {}

Core Concepts

• Domain Layer: Contains core models (Agent, Prompt, PromptHistory) and interfaces for repositories and use cases.
• Application Layer: Implements business logic via bundles and use cases (e.g., AgentCrudBundle, PromptCrudBundle).
• Infrastructure Layer: Handles database entities, mappers, and repository implementations.
• Presentation Layer: Exposes REST controllers, DTOs for request/response, presenters for formatting, and converters for mapping between DTOs and domain models.

Main Bundles & Controllers

• AgentCrudBundle, PromptCrudBundle, PromptHistoryCrudBundle: Provide programmatic access to CRUD operations.
• AgentCrudController, PromptCrudController, PromptHistoryCrudController: Expose REST endpoints for each entity.

Usage Examples

Agent CRUD

Create an Agent (programmatically):

import { IAgentCrudBundle } from '@sftech/ai-orchestrator-db';

@Injectable()
constructor(private agentCrudBundle: IAgentCrudBundle) {}

async createAgent() {
  const agent = await this.agentCrudBundle.createAgent({
    name: 'My Agent',
    description: 'Performs advanced tasks',
    // ...other properties
  });
  return agent;
}

REST API Example:

• POST /agent with body matching AgentCreateRequestDto
• GET /agent/:id
• PUT /agent/:id
• DELETE /agent/:id

Prompt CRUD

Create a Prompt:

await this.promptCrudBundle.createPrompt({
  agentId: '...',
  content: 'What is the weather today?',
  // ...other properties
});

REST API Example:

• POST /prompt with body matching PromptCreateRequestDto

Prompt History CRUD

Add to Prompt History:

await this.promptHistoryCrudBundle.createPromptHistory({
  agentId: '...',
  promptId: '...',
  response: 'It is sunny.',
  // ...other properties
});

REST API Example:

• POST /prompt-history with body matching PromptHistoryCreateRequestDto

DTOs, Presenters & Converters

• DTOs: Define the shape of data for requests and responses (see src/presentation/dtos/).
• Presenters: Format domain models for API responses (see src/presentation/presenters/).
• Converters: Map between DTOs and domain models (see src/presentation/converters/).

Extending the Library

• Add new entities by following the Clean Architecture structure: define models and interfaces in domain/, implement use cases in application/, create DB entities/mappers/repositories in infrastructure/, and expose via controllers/DTOs in presentation/.
• You can override or extend existing bundles and controllers by providing your own implementations in your application module.

License

© 2025 SFTech. All rights reserved.