import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/ru/scripts/Classes/AiAbstract - Абстрактный базовый класс AI'/>

# Класс AiAbstract

Абстрактный базовый класс, предназначенный для обеспечения общей механики различных интеграций с ИИ. Он управляет накоплением промптов, выбором моделей и предоставляет унифицированный рабочий процесс для получения ответов от различных провайдеров ИИ.

## Ключевые особенности

- **Накопление промптов** — механизмы для сбора и компоновки контекста запроса перед его отправкой в модель.
- **Управление моделями** — простое переключение между различными моделями ИИ в рамках одного экземпляра.
- **Унифицированный процесс** — стандартизированный метод `generate`, который нормализует процесс получения ответа.
- **Поддержка изображений и контента** — встроенные методы для накопления изображений и дополнительного текстового содержимого для мультимодальных моделей.
- **Chainable API** — большинство методов настройки поддерживают цепочку вызовов (чейнинг) для удобства разработки.
- **Точки расширения** — четкие хуки реализации (`init`, `response`, `toImages`, `toContents`) для конкретных сервисов ИИ (например, OpenAI, Anthropic).

## Инициализация

Поскольку `AiAbstract` является абстрактным классом, его нельзя инициализировать напрямую. Вы должны использовать конкретную реализацию (например, `AiOpenAI` или `AiAnthropic`).

**Параметры конструктора:**
- `key: string` — API-ключ для сервиса ИИ.
- `model: string` — начальный идентификатор модели (например, 'gpt-4o').

```typescript
// Пример использования конкретной реализации
const ai = new AiOpenAI(process.env.OPENAI_API_KEY, 'gpt-4o')

// Добавление контекста
ai.addPrompt('Вы — полезный помощник.')
  .addContent('Объясните квантовую физику простыми словами.')

// Генерация ответа
const response = await ai.generate('Сделайте акцент на корпускулярно-волновом дуализме.')
```

## Методы

### Информационные

- `getImages(): AiImageList` — Возвращает список накопленных изображений.
- `getContents(): string[]` — Возвращает список накопленного дополнительного содержимого.

### Настройка (Сеттеры)

Методы этой группы поддерживают цепочку вызовов.

- `setKey(key: string): this` — Устанавливает или переключает API-ключ. Переинициализирует клиент, если он уже активен.
- `setModel(model: string): this` — Переключает текущую модель для генерации.
- `addPrompt(prompt: string): void` — Добавляет новую строку в постоянный буфер промпта.
- `addImage(image: AiImageItem): this` — Добавляет изображение в список накопления.
- `addContent(content: string): this` — Добавляет текстовый контент в список накопления.

### Управление

- `generate(contents: string): Promise<string>` — Основной метод для запуска генерации ИИ. Объединяет накопленный промпт с переданной строкой и вызывает конкретную реализацию.
- `resetImages(): this` — Очищает список накопленных изображений.
- `resetContents(): this` — Очищает список накопленного содержимого.
- `resetPrompt(): void` — Полностью очищает постоянный префикс промпта.

## Абстрактные методы (Для реализации)

При наследовании от `AiAbstract` необходимо реализовать следующие защищенные методы:

- `init(): void` — Обработка инициализации клиента, аутентификации и настройки транспорта.
- `toImages(): void` — Логика преобразования накопленных изображений в формат, специфичный для провайдера.
- `toContents(): void` — Логика преобразования накопленного содержимого в формат, специфичный для провайдера.
- `response(model: string, contents: string): Promise<string>` — Основная логика вызова конкретной модели ИИ и возврата результата в виде строки.

## Типы

### AiImageList
Массив объектов `AiImageItem`.
```typescript
type AiImageList = AiImageItem[]
```

### AiImageItem
Представляет изображение в формате base64.
- `mime: string` — MIME-тип изображения (например, 'image/png').
- `base64: string` — данные изображения в кодировке base64.
```typescript
type AiImageItem = {
  mime: string
  base64: string
}
```
