<?php
/**
 * Embedding Model Base Class.
 *
 * Abstract base class for all embedding-based language models. Defines methods
 * for generating vector representations of text.
 *
 * @package   Agenistrator
 * @since     1.0.0
 * @author    Alex Ruban <alex@maximum.guru>
 * @author    Maximum Software Inc <contact@maximum.software>
 * @license   GPL-3.0-only
 * @link      https://agenistrator.com/
 *
 * SPDX-FileCopyrightText: 2025-2026 Alex Ruban <alex@maximum.guru>
 * SPDX-FileCopyrightText: 2025-2026 Maximum Software Inc <contact@maximum.software>
 * SPDX-License-Identifier: GPL-3.0-only
 */

namespace Agenistrator;

// Direct access prevention
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * LLM_Embedding class.
 */
abstract class LLM_Embedding extends LLM {
	/**
	 * Generate embeddings for the provided texts
	 *
	 * @param      array $texts Array of text strings to embed
	 * @return     array Array of embeddings (vector representations)
	 * @since     1.0.0
	 */
	abstract public function generate_embeddings( $texts );

	/**
	 * Get the dimension of embeddings for this model
	 *
	 * @return     int Dimension size
	 * @since     1.0.0
	 */
	abstract public function get_dimension();

	/**
	 * Detect and update cached dimension based on actual embedding results
	 *
	 * This method should be called by subclasses after generating embeddings
	 * to detect dimension changes and update the cache accordingly.
	 *
	 * @param      array $embeddings Array of embedding vectors
	 * @return     void
	 * @since     1.0.0
	 */
	protected function detect_and_cache_dimension( $embeddings ) {
		if ( empty( $embeddings ) || ! is_array( $embeddings[0] ) ) {
			return;
		}

		$actual_dimension = count( $embeddings[0] );
		$llm_manager      = LLM_Manager::get_instance();
		$cached_dimension = $llm_manager->get_cached_embeddings_model_dimension( $this->model_id );

		// Update cache if dimension changed or not yet cached
		if ( $cached_dimension !== $actual_dimension ) {
			$llm_manager->cache_embeddings_model_dimension( $this->model_id, $actual_dimension );
		}
	}
}