find-image

/**
 * Embedding instructions
 *
 * Keep every system instruction in this one table so retrieval behavior is
 * easy to find, compare, and tune. Corpus embeddings stay neutral; only a
 * query instruction varies with the user's retrieval task.
 */
export const EMBEDDING_INSTRUCTIONS = {
  corpus: "Represent the user's input.",
  visualSimilarity: "Retrieve images visually similar to the reference image. Prioritize subjects, composition, visual style, scene layout, and spatial relationships.",
  visualAndMetadataSimilarity: "Retrieve images visually and contextually similar to the reference image. Use its generation metadata to match the creative direction, prompt intent, style, and production context.",
  fusion: "Retrieve images that satisfy the text request. Treat the reference image as a visual guideline, but consider all additions, changes, exclusions, and constraints stated in the text.",
  textRetrieval: "Retrieve images that satisfy the description. Consider all details, features, relationships, exclusions, and constraints stated in the query.",
  metadataTextSimilarity: "Retrieve images whose generation metadata and prompt intent are similar to the query. Match concepts, style, model context, and stated constraints; do not require visual similarity to a reference image.",
} as const;

export type EmbeddingInstructionKey = keyof typeof EMBEDDING_INSTRUCTIONS;
export type QueryInstructionKey = Exclude<EmbeddingInstructionKey, "corpus">;

export function selectQueryEmbeddingInstruction(options: {
  hasTargetImage: boolean;
  hasFreeText: boolean;
  includeMetadata: boolean;
  excludeImage: boolean;
}): QueryInstructionKey {
  if (options.hasTargetImage && !options.excludeImage) {
    if (options.hasFreeText) return "fusion";
    return options.includeMetadata ? "visualAndMetadataSimilarity" : "visualSimilarity";
  }

  return options.includeMetadata ? "metadataTextSimilarity" : "textRetrieval";
}

/**
 * Reranking instructions
 *
 * Keys deliberately match the query-embedding instruction table above. The
 * reranker sees one query-document pair at a time, so each text describes a
 * relevance judgment rather than a vector-retrieval task.
 */
export const RERANKING_INSTRUCTIONS: Record<QueryInstructionKey, string> = {
  visualSimilarity: "Given a reference image, retrieve candidate images that are visually similar. Prioritize subjects, composition, visual style, scene layout, and spatial relationships.",
  visualAndMetadataSimilarity: "Given a reference image and its generation metadata, retrieve candidate images that match the visual appearance, creative direction, prompt intent, style, and production context.",
  fusion: "Given a reference image and a text request, retrieve candidate images that satisfy the request. Treat the reference image as a visual guideline and consider all additions, changes, exclusions, and constraints in the text.",
  textRetrieval: "Given a description, retrieve candidate images that satisfy it. Consider all details, features, relationships, exclusions, and constraints in the query.",
  metadataTextSimilarity: "Given generation metadata and prompt intent, retrieve candidate images with similar concepts, style, model context, and stated constraints. Do not require visual similarity to a reference image.",
};

export function selectRerankingInstruction(options: {
  hasTargetImage: boolean;
  hasFreeText: boolean;
  includeMetadata: boolean;
  excludeImage: boolean;
}): QueryInstructionKey {
  return selectQueryEmbeddingInstruction(options);
}