export type ExplorePhase = "explore" | "generate" | "repair" | "done";

export type ExploreTool =
  | "search_wikipedia"
  | "search_hf_papers"
  | "search_arxiv"
  | "search_scholar"
  | "fetch_docs"
  | "search_hf_hub";

export type GenerateFormat = "marimo" | "manim";

export interface TopChunk {
  rank?: number;
  source?: string;
  title?: string;
  url?: string;
  score?: number | string;
  snippet?: string;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  [k: string]: any;
}

export interface ExplainerObservation {
  done: boolean;
  reward: number | null;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  metadata: Record<string, any>;
  topic: string;
  content: string;
  tier: "beginner" | "intermediate" | "advanced" | string;
  keywords: string;
  data_available: boolean;
  difficulty: "easy" | "medium" | "hard" | string;
  phase: ExplorePhase;
  feedback: string;
  search_results: string;
  top_chunks: TopChunk[];
  explored_context: string;
  explore_steps_left: number;
  repair_attempts_left: number;
  last_errors: string;
  available_tools: string[];
}

export interface ExplainerAction {
  action_type: "explore" | "generate" | "repair";
  tool?: ExploreTool | null;
  query?: string;
  intent?: string;
  format?: GenerateFormat | null;
  code?: string;
  narration?: string;
  repair_notes?: string;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  metadata?: Record<string, any>;
}

export interface StepResult {
  observation: ExplainerObservation;
  reward: number | null;
  done: boolean;
}

export interface ParsedExplore {
  kind: "explore";
  tool: ExploreTool;
  query: string;
  intent: string;
  skip?: boolean;
}

export interface ParsedGenerate {
  kind: "generate" | "repair";
  format: GenerateFormat;
  code: string;
  narration: string;
}

export type ParsedAction = ParsedExplore | ParsedGenerate;

export interface RewardEntry {
  step: number;
  phase: string;
  total: number | null;
  components: Record<string, number | string>;
}

export interface LogEntry {
  ts: number;
  tag: "START" | "LLM" | "STEP" | "END" | "WARN" | "ERROR" | "INFO";
  message: string;
}