unit MLCoreABC;

interface

uses LinearAlgebraML;

type
/// Базовый интерфейс шага конвейера машинного обучения.
/// Используется для объединения всех типов шагов
/// (DataFrame-преобразователей, матричных трансформеров и моделей)
/// в единую последовательность выполнения внутри различных Pipeline
  IPipelineStep = interface end;
  
/// Интерфейс шага конвейера, работающего в числовом (матричном) пространстве.
/// Реализуется трансформерами и моделями, которые принимают на вход Matrix и Vector
/// и используются в Matrix-уровне Pipeline
  IMatrixStep = interface(IPipelineStep) 
  end;
  
  /// Интерфейс шага конвейера, работающего на уровне DataFrame.
  /// Реализуется препроцессорами, которые выполняют преобразования табличных данных
  ///   до перехода в числовое (Matrix) представление
  IDataStep = interface(IPipelineStep) 
  end;

  /// Интерфейс шага конвейера, привязанного к одной колонке DataFrame.
  /// Используется для препроцессоров, выполняющих преобразование конкретной колонки
  /// (например, кодирование категориальных признаков).
  /// Позволяет DataPipeline централизованно контролировать операции над колонками
  /// (в частности, запрещать изменение целевой переменной).  
  IColumnBoundStep = interface
    /// Имя колонки, к которой применяется преобразование.
    /// Должно соответствовать существующей колонке DataFrame.
    /// Используется для валидации (например, запрет преобразования target).
    property ColumnName: string read;
  end;
  
  /// Интерфейс шага конвейера, работающего с несколькими колонками DataFrame.
  /// Используется для препроцессоров, выполняющих преобразования над набором колонок
  /// (например, заполнение пропусков, масштабирование или кодирование нескольких признаков).
  /// Позволяет DataPipeline контролировать операции над колонками
  /// (в частности, предотвращать изменение целевой переменной).
  IColumnsBoundStep = interface
    /// Список колонок, к которым применяется преобразование.
    /// Каждое имя должно соответствовать существующей колонке DataFrame.
    /// Используется для валидации (например, запрет преобразования target).
    property Columns: array of string read;
  end;

  /// Базовый интерфейс модели машинного обучения
  IModel = interface(IMatrixStep)
    function Clone: IModel;
    function Name: string;
    property IsFitted: boolean read;
  end;
  
  /// Интерфейс модели без учителя.
  /// Наследуется от базового интерфейса IModel.
  /// Предназначен для алгоритмов, обучающихся только по признакам X
  /// без использования целевых значений y.
  IUnsupervisedModel = interface(IModel)
    function Fit(X: Matrix): IUnsupervisedModel;
  end;

  /// Интерфейс алгоритма кластеризации.
  /// Предназначен для моделей, разбивающих объекты на кластеры
  /// без использования целевой переменной.
  /// Основной сценарий использования — FitPredict, возвращающий
  /// номер кластера для каждого объекта обучающей выборки.
  ///
  /// Важно:
  ///   • номер кластера — это внутренний идентификатор алгоритма;
  ///   • он не связан с внешними метками классов, как в классификации;
  ///   • одинаковые по смыслу кластеры в разных запусках могут получить
  ///     разные номера.
  IClusterer = interface(IUnsupervisedModel)
    /// Выполняет кластеризацию данных и возвращает массив номеров кластеров
    /// (0,1,2,...) для каждого объекта. Значение -1 может использоваться
    /// для обозначения шума (например, в DBSCAN).
    ///
    /// Возвращаемые значения являются внутренними номерами кластеров,
    /// а не внешними метками, заданными пользователем.
    function FitPredict(X: Matrix): array of integer;
  end;
  
  /// Интерфейс кластеризатора, поддерживающего предсказание для новых данных.
  /// Используется для алгоритмов, задающих явное отображение X → кластер
  /// (например, KMeans через ближайший центр кластера).
  IPredictiveClusterer = interface(IClusterer)
    /// Возвращает номер кластера для каждого объекта из X
    /// без повторного обучения модели.
    /// Требует предварительного вызова Fit или FitPredict.
    ///
    /// Возвращаемые значения являются внутренними номерами кластеров,
    /// а не внешними метками классов.
    function Predict(X: Matrix): array of integer;
  end;  
  
  /// Интерфейс древовидной модели машинного обучения.
  /// Используется для моделей, которые умеют вычислять важность признаков.
  ITreeModel = interface(IModel)
    function FeatureImportances: Vector;
  end;

  /// Интерфейс классификатора.
  /// Наследуется от IModel.
  /// Предназначен для моделей, выполняющих классификацию.
  IClassifier = interface(IModel)
    /// Обучает модель классификации на матрице признаков X
    /// и целевых метках классов y.
    function Fit(X: Matrix; y: array of integer): IClassifier;

    /// Возвращает метку класса для одного объекта X
    /// в том же виде, в каком метки были поданы модели при обучении.
    function PredictOne(X: Vector): integer;

    /// Возвращает метки классов в том же виде, в каком они были поданы модели при обучении.
    function Predict(X: Matrix): array of integer;

    /// Возвращает исходные строковые метки классов для объектов из X.
    function PredictLabels(X: Matrix): array of string;
    
    /// Возвращает строковые метки классов в порядке столбцов матрицы PredictProba.
    function GetClassLabels: array of string;
  end;
  
  IClassifierInternal = interface
    procedure SetClassLabels(classes: array of string);
  end;
  
  /// Интерфейс классификатора, возвращающего вероятности.
  /// Расширяет IClassifier.
  /// Используется для моделей, которые умеют оценивать
  /// вероятность принадлежности к классу.
  /// Позволяет получать значения в диапазоне (0, 1)
  /// вместо только итогового решения.
  IProbabilisticClassifier = interface(IClassifier)
    /// Возвращает вектор вероятностей классов для одного объекта X.
    /// Порядок элементов соответствует GetClassLabels.
    function PredictProbaOne(X: Vector): Vector;

    /// Возвращает матрицу вероятностей классов для всех объектов из X.
    /// Размер результата: nSamples × nClasses, где:
    /// - nSamples — число объектов в X;
    /// - nClasses — число классов модели.
    /// Элемент [i, k] содержит вероятность того, что объект i принадлежит классу k.
    /// Сумма вероятностей в каждой строке равна 1.
    function PredictProba(X: Matrix): Matrix;
  end;

  /// Интерфейс регрессионной модели.
  /// Наследуется от IModel.
  /// Предназначен для моделей, предсказывающих числовые значения.
  IRegressor = interface(IModel)
    /// Обучает модель регрессии на матрице признаков X
    /// и векторе целевых значений y.
    function Fit(X: Matrix; y: Vector): IRegressor;

    /// Возвращает числовое предсказание для одного объекта X.
    function PredictOne(X: Vector): real;

    function Predict(X: Matrix): Vector;
  end;
  
  /// Базовый интерфейс преобразования признаков.
  /// Используется для масштабирования, отбора,
  /// уменьшения размерности и других преобразований данных
  ITransformer = interface(IMatrixStep)
    /// Применяет обученное преобразование к данным.
    /// Возвращает новую матрицу признаков.
    function Transform(X: Matrix): Matrix;
    function Clone: ITransformer;
  end;
  
  /// Интерфейс преобразования признаков с учётом целевой переменной.
  /// Используется для методов отбора признаков и других процедур,
  /// в которых при обучении требуется вектор целевых значений
  ISupervisedTransformer = interface(ITransformer)
    /// Обучает преобразование на данных с использованием
    /// как признаков X, так и целевой переменной y.
    /// Запоминает необходимые параметры, которые будут использоваться при Transform.
    function Fit(X: Matrix; y: Vector): ISupervisedTransformer;
    function FitTransform(X: Matrix; y: Vector): Matrix;
  end;
  
  /// Интерфейс преобразования признаков без учёта целевой переменной.
  /// Используется для методов отбора признаков и других процедур,
  /// в которых при обучении не требуется вектор целевых значений
  IUnsupervisedTransformer = interface(ITransformer)
    /// Обучает преобразование на данных с использованием признаков X
    /// Запоминает необходимые параметры, которые будут использоваться при Transform.
    function Fit(X: Matrix): IUnsupervisedTransformer;
    function FitTransform(X: Matrix): Matrix;
  end;
  
  IColumnExpander = interface
    function GetExpandedColumns(sourceColumn: string): array of string;
  end;
  
implementation  

end.