<?php

declare(strict_types=1);

namespace App\Services\Recommendations\VectorSimilarity;

/**
 * Contract for vector-similarity adapters (pgvector, Pinecone, etc.).
 *
 * Each adapter can query nearest-neighbor artworks for a given artwork ID
 * and return an ordered list of (artwork_id, score) pairs.
 */
interface VectorAdapterInterface
{
    /**
     * Find the most visually similar artworks.
     *
     * @param  int  $artworkId  Source artwork
     * @param  int  $topK       Max neighbors to return
     * @return list<array{artwork_id: int, score: float}>  Ordered by score descending
     */
    public function querySimilar(int $artworkId, int $topK = 100): array;

    /**
     * Upsert an artwork embedding into the vector store.
     *
     * @param  int    $artworkId
     * @param  array  $embedding  Raw float vector
     * @param  array  $metadata   Optional metadata (category, author, etc.)
     */
    public function upsertEmbedding(int $artworkId, array $embedding, array $metadata = []): void;

    /**
     * Delete an artwork embedding from the vector store.
     */
    public function deleteEmbedding(int $artworkId): void;
}