<?php
if (!defined('ABSPATH')) {
    exit;
}

/**
 * Vector Database Interface
 *
 * Defines the generic operations used by the Knowledge Base module.
 *
 * @package    Kitsune_AI_Platform
 * @subpackage Kitsune_AI_Platform/includes/vector-db
 */

interface Kitsune_AI_Platform_Vector_DB_Interface {

    /**
     * List records from the vector database.
     *
     * @param array $args Optional arguments such as limit/offset.
     * @return array
     */
    public function list_records($args = array());

    /**
     * Perform a semantic/vector search.
     *
     * @param string $query Search query.
     * @param array  $args  Optional arguments such as limit.
     * @return array
     */
    public function vector_search($query, $args = array());

    /**
     * Insert a record into the vector database.
     *
     * @param array $record Record payload.
     * @return array
     */
    public function insert_record($record);

    /**
     * Delete a record from the vector database.
     *
     * @param string|int $record_id Record identifier.
     * @param array      $args      Optional arguments.
     * @return array
     */
    public function delete_record($record_id, $args = array());

    /**
     * Provision a fresh collection so that dimension constraints from a previous
     * embedding model do not carry over.
     *
     * The old collection is left intact in the vector database. The caller is
     * responsible for updating its stored config with the returned name and UUID.
     *
     * @return array {
     *   success: bool,
     *   collection?: string,   // new collection name
     *   collectionId?: string, // new collection UUID
     *   message?: string
     * }
     */
    public function reset_collection();
}
