<?php

namespace Limb_Chatbot\Includes\Interfaces;

use Limb_Chatbot\Includes\Data_Objects\Dataset;
use WP_Post;

/**
 * Contract for integration-specific CPT knowledge content providers.
 *
 * Integrations that own a particular post type implement this interface and
 * register themselves via WordPress filters so the generic CPT_Knowledge_Mapper
 * can delegate content generation entirely to them.
 *
 * Filter hook convention (registered by the integration in its init() method):
 *
 *   lbaic_cpt_knowledge_input_{post_type}
 *       Args:  (string $default_input, WP_Post $post, Dataset|null $dataset)
 *       Return: string — keyword-rich search query representing this post.
 *
 *   lbaic_cpt_knowledge_output_{post_type}
 *       Args:  (string $default_output, WP_Post $post, Dataset|null $dataset)
 *       Return: string — complete embeddable knowledge for this post.
 *
 * @since 1.2.0
 */
interface CPT_Knowledge_Provider_Interface {

	/**
	 * Return the semantic "input" (the question / search-query form) for the
	 * knowledge entry.
	 *
	 * Should be keyword-rich and capture all terms a user might search for.
	 * This text is prepended to the output in the embedding payload, so its
	 * quality directly affects retrieval accuracy.
	 *
	 * @param WP_Post      $post    Source post object.
	 * @param Dataset|null $dataset Associated dataset (carries custom-field
	 *                               key lists and other job-time metadata).
	 *
	 * @return string
	 */
	public function get_entry_input( WP_Post $post, ?Dataset $dataset ): string;

	/**
	 * Return the rich embeddable "output" (the full knowledge body) for the
	 * knowledge entry.
	 *
	 * Must contain ALL textual information about the object so that both
	 * vector similarity and hybrid keyword matching produce strong results.
	 * A single, complete, un-chunked entry per object is expected.
	 *
	 * @param WP_Post      $post    Source post object.
	 * @param Dataset|null $dataset Associated dataset.
	 *
	 * @return string
	 */
	public function get_entry_output( WP_Post $post, ?Dataset $dataset ): string;
}
