/**
 * llmindex.io — item bank types: templates, generated items
 * Author:  Simon-Pierre Boucher
 * Contact: contact@spboucher.ai
 * License: Proprietary — © Simon-Pierre Boucher, all rights reserved
 */
import type { Domain } from '@llmindex/scoring';
import type { GradingMode } from './answer';
import type { Rng } from './rng';

/**
 * A generated, gradeable item. `answerKey` stays server-side only —
 * never shipped to the client bundle or public API.
 */
export interface GeneratedItem {
  templateId: string;
  domain: Domain;
  prompt: string;
  answerKey: string;
  /**
   * Grading mode: exact/numeric use line extraction ("ANSWER: x" cascade);
   * json/lines use fenced-block extraction (call sequences, terminal output).
   */
  grading: GradingMode;
  perturbSeed: string;
  /**
   * Vision items: SVG scene source. The worker rasterizes it to PNG and sends
   * it as image input; the prompt text never contains the answer.
   */
  svg?: string;
}

/**
 * A versioned dynamic template. Template *shapes* are public (methodology
 * transparency); each render is a fresh perturbation (values + paraphrase),
 * so no fixed test set can be memorized.
 */
export interface ItemTemplate {
  id: string; // e.g. "math.arith.chain-v1"
  domain: Domain;
  description: string;
  /** Approximate size of the value/paraphrase space (contamination audit). */
  paramSpace: number;
  render(rng: Rng, perturbSeed: string): GeneratedItem;
}

/** Open-ended duel prompt (writing / safety_refusal_quality) — judged pairwise, no key. */
export interface DuelPrompt {
  templateId: string;
  domain: Domain;
  prompt: string;
  perturbSeed: string;
}