/**
 * LLM API Response Examples
 *
 * Type-safe test fixtures for validating LLM provider API responses.
 * These serve as the single source of truth for expected response structures
 * from external LLM APIs (OpenAI, Gemini, Perplexity, etc.).
 *
 * Usage:
 * - Import in backend tests for LLM integration validation
 * - Import in mocks for consistent test responses
 * - Reference for documentation and debugging
 *
 * @see backend/src/tools/*LLMTool.ts - Uses these structures for parsing
 */

/**
 * OpenAI/OpenRouter API Response Structures
 *
 * OpenRouter endpoint: /responses
 * Used by OpenAI models via OpenRouter gateway
 */

export interface OpenAIResponseUsage {
  input_tokens?: number;
  output_tokens?: number;
  total_tokens?: number;
  prompt_tokens?: number;
  completion_tokens?: number;
}

export interface OpenAIResponseTextContent {
  type?: string;
  text?: string;
}

export interface OpenAIResponseOutputItem {
  type?: string;
  text?: string;
  content?: OpenAIResponseTextContent[];
}

export interface OpenAIChatCompletionChoice {
  message?: {
    content?: string;
  };
  finish_reason?: string;
}

export interface OpenAIResponsesResult {
  output?: OpenAIResponseOutputItem[];
  output_text?: string;
  usage?: OpenAIResponseUsage;
  choices?: OpenAIChatCompletionChoice[];
  error?: {
    message?: string;
    type?: string;
  };
}

/**
 * Example OpenAI/OpenRouter successful response
 * Based on actual API response from openrouter.ai/responses endpoint
 */
export const OPENAI_OPENROUTER_SUCCESS_EXAMPLE: OpenAIResponsesResult = {
  output_text: "The capital of France is Paris.",
  output: [
    {
      type: "text",
      text: "The capital of France is Paris."
    }
  ],
  usage: {
    input_tokens: 15,
    output_tokens: 8,
    total_tokens: 23,
    prompt_tokens: 15,
    completion_tokens: 8
  },
  choices: [
    {
      message: {
        content: "The capital of France is Paris."
      },
      finish_reason: "stop"
    }
  ]
} as const;

/**
 * Example OpenAI/OpenRouter error response
 */
export const OPENAI_OPENROUTER_ERROR_EXAMPLE: OpenAIResponsesResult = {
  error: {
    message: "Invalid API key provided",
    type: "invalid_request_error"
  }
} as const;

/**
 * Cerebras API Response Structures
 *
 * Cerebras endpoint: /chat/completions
 */

export interface CerebrasStreamChunk {
  choices: Array<{
    delta: {
      content?: string;
    };
    finish_reason?: string;
  }>;
}

export interface CerebrasResponse {
  choices: Array<{
    message: {
      content: string;
      annotations?: unknown;
    };
    finish_reason: string;
  }>;
  usage: {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
  };
}

/**
 * Example Cerebras successful response
 */
export const CEREBRAS_SUCCESS_EXAMPLE: CerebrasResponse = {
  choices: [
    {
      message: {
        content: "The capital of France is Paris, which has been the capital since 987 AD.",
        annotations: undefined
      },
      finish_reason: "stop"
    }
  ],
  usage: {
    prompt_tokens: 15,
    completion_tokens: 18,
    total_tokens: 33
  }
} as const;

/**
 * Grok API Response Structures
 *
 * X.AI Grok endpoint: /chat/completions
 */

export interface GrokChatCompletion {
  choices?: Array<{
    message?: {
      content?: string;
    };
  }>;
  usage?: {
    prompt_tokens?: number;
    completion_tokens?: number;
    total_tokens?: number;
    num_sources_used?: number;
  };
  error?: {
    message?: string;
  };
}

/**
 * Example Grok successful response with web search
 */
export const GROK_SUCCESS_EXAMPLE: GrokChatCompletion = {
  choices: [
    {
      message: {
        content: "Paris is the capital and largest city of France. [Source: Wikipedia]"
      }
    }
  ],
  usage: {
    prompt_tokens: 20,
    completion_tokens: 15,
    total_tokens: 35,
    num_sources_used: 3
  }
} as const;

/**
 * Perplexity API Response Structures
 *
 * Perplexity endpoint: /chat/completions
 * Similar to OpenAI format with citations
 */

export interface PerplexityMessage {
  role: string;
  content: string;
}

export interface PerplexityCitation {
  url: string;
  title?: string;
  text?: string;
}

export interface PerplexityUsage {
  prompt_tokens: number;
  completion_tokens: number;
  total_tokens: number;
}

export interface PerplexityResponse {
  id: string;
  model: string;
  object: string;
  created: number;
  choices: Array<{
    index: number;
    message: PerplexityMessage;
    finish_reason: string;
  }>;
  usage: PerplexityUsage;
  citations?: PerplexityCitation[];
}

/**
 * Example Perplexity successful response with citations
 */
export const PERPLEXITY_SUCCESS_EXAMPLE: PerplexityResponse = {
  id: "cmpl-123abc",
  model: "sonar-pro",
  object: "chat.completion",
  created: 1704067200,
  choices: [
    {
      index: 0,
      message: {
        role: "assistant",
        content: "Paris has been the capital of France since 987 AD, when Hugh Capet established it as the seat of royal power."
      },
      finish_reason: "stop"
    }
  ],
  usage: {
    prompt_tokens: 18,
    completion_tokens: 25,
    total_tokens: 43
  },
  citations: [
    {
      url: "https://en.wikipedia.org/wiki/Paris",
      title: "Paris - Wikipedia",
      text: "Paris is the capital and largest city of France..."
    },
    {
      url: "https://www.britannica.com/place/Paris",
      title: "Paris | History, Map, Population, & Facts | Britannica"
    }
  ]
} as const;

/**
 * Gemini API Response Structures
 *
 * Google GenerativeModel API (via @google/generative-ai SDK)
 * Note: Gemini uses SDK objects, not raw JSON responses
 */

export interface GeminiCandidate {
  content: {
    parts: Array<{ text: string }>;
    role: string;
  };
  finishReason?: string;
  index?: number;
  safetyRatings?: Array<{
    category: string;
    probability: string;
  }>;
}

export interface GeminiGenerateContentResponse {
  candidates?: GeminiCandidate[];
  promptFeedback?: {
    blockReason?: string;
    safetyRatings?: Array<{
      category: string;
      probability: string;
    }>;
  };
}

/**
 * Example Gemini successful response
 * Note: Actual SDK returns GenerateContentResult with .response.text() method
 */
export const GEMINI_SUCCESS_EXAMPLE: GeminiGenerateContentResponse = {
  candidates: [
    {
      content: {
        parts: [
          {
            text: "Paris is the capital city of France, located in the north-central part of the country."
          }
        ],
        role: "model"
      },
      finishReason: "STOP",
      index: 0,
      safetyRatings: [
        {
          category: "HARM_CATEGORY_HATE_SPEECH",
          probability: "NEGLIGIBLE"
        }
      ]
    }
  ]
} as const;

/**
 * All LLM response examples indexed by provider
 */
export const LLM_RESPONSE_EXAMPLES = {
  'openai-openrouter-success': OPENAI_OPENROUTER_SUCCESS_EXAMPLE,
  'openai-openrouter-error': OPENAI_OPENROUTER_ERROR_EXAMPLE,
  'cerebras-success': CEREBRAS_SUCCESS_EXAMPLE,
  'grok-success': GROK_SUCCESS_EXAMPLE,
  'perplexity-success': PERPLEXITY_SUCCESS_EXAMPLE,
  'gemini-success': GEMINI_SUCCESS_EXAMPLE
} as const;

/**
 * Type helper to get the example for a specific provider
 */
export type LLMResponseExample<T extends keyof typeof LLM_RESPONSE_EXAMPLES> = typeof LLM_RESPONSE_EXAMPLES[T];