npm package: @sftech/ai-orchestrator-core
Description: AI Orchestrator Core is a TypeScript library designed to provide the essential building blocks for orchestrating AI agents, assistants, and large language model (LLM) workflows. It is built with modularity and extensibility in mind, following Clean Archit
Latest version: 1.0.3

# AI Orchestrator Core

AI Orchestrator Core is a TypeScript library designed to provide the essential building blocks for orchestrating AI agents, assistants, and large language model (LLM) workflows. It is built with modularity and extensibility in mind, following Clean Architecture principles, and is intended for use in advanced AI orchestration scenarios within Node.js/NestJS projects.

---

## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Getting Started](#getting-started)
- [Architecture](#architecture)
- [Core Modules & Concepts](#core-modules--concepts)
- [Usage Examples](#usage-examples)
- [Extending the Library](#extending-the-library)
- [License](#license)

---

## Overview

AI Orchestrator Core provides the foundation for building, configuring, and running AI agents and assistants. It abstracts the orchestration of LLMs, agent logic, prompt management, and tool integration, making it easy to build scalable and maintainable AI-driven applications.

## Features
- Modular orchestration of LLMs and agents
- Extensible base classes for agents, assistants, and orchestrators
- Generic and file-based agent/assistant implementations
- DTOs and controllers for REST API integration
- Clean separation of domain, application, infrastructure, and presentation layers

## Installation

Install via npm:

```bash
npm install @sftech/ai-orchestrator-core
```

Or with yarn:

```bash
yarn add @sftech/ai-orchestrator-core
```

## Getting Started

Import the module into your NestJS application:

```typescript
import { AiOrchestratorCoreModule } from '@sftech/ai-orchestrator-core';

@Module({
  imports: [
    AiOrchestratorCoreModule.register({
      // Provide orchestrator options here (see below)
    }),
  ],
})
export class AppModule {}
```

### Orchestrator Options

The `register` method expects an options object implementing `IOrchestratorOptions`. This allows you to configure the orchestrator's behavior, such as agent/assistant types, tool integrations, and more. See `src/domain/orchestrator-options.interface.ts` for all available options.

Example:
```typescript
const orchestratorOptions: IOrchestratorOptions = {
  // Define your orchestrator configuration here
};

AiOrchestratorCoreModule.register(orchestratorOptions);
```

## Architecture

The library is structured according to Clean Architecture principles:
- **Domain**: Core models, interfaces, and enums
- **Application**: Base and generic orchestrators, agents, assistants, and file-based logic
- **Infrastructure**: Mappers, seeders, and option handling
- **Presentation**: REST controllers and DTOs for API integration

## Core Modules & Concepts

- **Base Classes**: Extend `BaseOrchestrator`, `BaseAgent`, `BaseAssistant`, or `BaseLlmAssistant` to implement custom logic
- **Generic Implementations**: Use or extend `GenericLlmOrchestrator`, `GenericLlmAgent`, `GenericLlmAssistant` for LLM-based workflows
- **File Reader Agents/Assistants**: Integrate file-based input/output via `FileReaderAgent` and `FileReaderAssistant`
- **Controllers**: Use `GenericOrchestratorController` and `ToolsController` for REST API endpoints
- **DTOs**: Data transfer objects for configuration and runtime (see `src/presentation/dtos/`)

## Usage Examples

### Registering the Module
```typescript
import { AiOrchestratorCoreModule } from '@sftech/ai-orchestrator-core';
import { IOrchestratorOptions } from '@sftech/ai-orchestrator-core';

const options: IOrchestratorOptions = {
  // ...your orchestrator configuration...
};

@Module({
  imports: [AiOrchestratorCoreModule.register(options)],
})
export class AppModule {}
```

### Using the REST API
The library provides controllers for orchestrator and tool operations. Once the module is registered, endpoints such as `/orchestrator/generic` and `/tools` are available for integration.

### Extending Agents or Assistants
You can extend the base or generic classes to implement your own agent or assistant logic:

```typescript
import { BaseAgent } from '@sftech/ai-orchestrator-core';

export class MyCustomAgent extends BaseAgent {
  // Implement your custom logic here
}
```

## Extending the Library
- Add new agent or assistant types by extending the base classes
- Implement custom orchestrators for advanced workflows
- Add new controllers or DTOs for additional API endpoints
- Use the provided interfaces and enums for strong typing and consistency

## License

© 2025 SFTech. All rights reserved.