npm package: @sftech/ai-orchestrator-db
Description: 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.
Latest version: 1.0.0

# 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](#overview)
- [Installation](#installation)
- [Setup & Integration](#setup--integration)
- [Core Concepts](#core-concepts)
- [Usage Examples](#usage-examples)
  - [Agent CRUD](#agent-crud)
  - [Prompt CRUD](#prompt-crud)
  - [Prompt History CRUD](#prompt-history-crud)
- [DTOs, Presenters & Converters](#dtos-presenters--converters)
- [Extending the Library](#extending-the-library)
- [License](#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):

```bash
npm install @sftech/ai-orchestrator-db
```

Or, if using yarn:

```bash
yarn add @sftech/ai-orchestrator-db
```

## Setup & Integration

Import the module into your NestJS application:

```typescript
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):**
```typescript
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:**
```typescript
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:**
```typescript
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.