package ai.dynamixs.rag.cluster;

/**
 * Represents a single result from a semantic search operation in the RAG
 * (Retrieval-Augmented Generation) system.
 * 
 * This immutable data class encapsulates the information about a document that
 * was retrieved based on semantic similarity to a query. Each result contains
 * the document's unique identifier, the content of the best matching chunk, and
 * the similarity score that indicates how well the document matches the search
 * query.
 * 
 * <p>
 * The similarity score is typically a cosine similarity value between the query
 * embedding and the document's content embedding, where higher values indicate
 * better matches.
 * </p>
 * 
 * <p>
 * <strong>Usage Example:</strong>
 * </p>
 * 
 * <pre>{@code
 * List<RetrievalResult> results = searchEmbeddings(queryVector);
 * for (RetrievalResult result : results) {
 *     System.out.println("Document: " + result.getUniqueId() +
 *             " (Score: " + result.getScore() + ")");
 *     System.out.println("Content: " + result.getContent());
 * }
 * }</pre>
 * 
 * @author Your Name
 * @version 1.0
 * @since 1.0
 * @see #getUniqueId()
 * @see #getContent()
 * @see #getScore()
 */
public class RetrievalResult {
    private final String uniqueId;
    private final String content;
    private final Float score;

    public RetrievalResult(String uniqueID, String content, Float score) {
        this.uniqueId = uniqueID;
        this.content = content;
        this.score = score;
    }

    public String getUniqueId() {
        return uniqueId;
    }

    public String getContent() {
        return content;
    }

    public Float getScore() {
        return score;
    }

    @Override
    public String toString() {
        return "RetrievalResult{" +
                "$uniqueId='" + uniqueId + '\'' +
                ", score=" + score +
                ", content='" + content.substring(0, Math.min(50, content.length())) + "...'" +
                '}';
    }
}