---@meta

--- OpenAI types form OpenAPI specification ------------------------------------

---@class ChatMessage
---@field role string The role of the message sender, e.g., "user", "system", or "assistant"
---@field content string The content of the message

---@class ChatChoice
---@field index integer The index of this choice in the list
---@field message ChatMessage The message generated by the model
---@field finish_reason string The reason the completion finished (e.g., "stop")

---@class TokenUsage
---@field prompt_tokens integer The number of tokens used for the prompt
---@field completion_tokens integer The number of tokens generated for the completion
---@field total_tokens integer The total number of tokens used

---Represents a chat completion request to be sent to the model.
---Reference: https://platform.openai.com/docs/api-reference/chat/create
---Some API providers does not support all the fields.
---Consult the provider documentation for a list of supported fields.
---@class RequestObject
---@field model string The model to use (e.g., "gpt-4")
---@field messages ChatMessage[] A list of chat messages that form the conversation
---@field temperature? number The temperature for completion generation
---@field max_tokens? integer Maximum number of tokens to generate
---@field stream? boolean Whether to stream responses back (default is false)

---Represents a chat completion response returned by model, based on the provided input.
---Reference: https://platform.openai.com/docs/api-reference/chat/object
---@class ChatCompletionObject
---@field id string The unique identifier for the completion
---@field object string The object type (always "chat.completion")
---@field created integer The timestamp when the completion was created
---@field model string The model used for the completion
---@field choices ChatChoice[] The possible choices generated by the model
---@field usage? TokenUsage Token usage statistics (optional)

---Represents a streamed chunk of a chat completion response returned by model, based on the provided input.
---Reference: https://platform.openai.com/docs/api-reference/chat/streaming
---@class ChatCompletionChunkObject
---@field id string The unique identifier for the completion
---@field object string The object type (always "chat.completion.chunk")
---@field created integer The timestamp when the chunk was created
---@field model string The model used for generating this chunk
---@field choices ChatChunkChoice[] The list of chunked responses

---@class ChatChunkChoice
---@field delta ChunkDelta The incremental part of the response
---@field index integer The index of this chunk in the list
---@field finish_reason? string The reason this chunk finished (optional)

---@class ChunkDelta
---@field role? string The role of the message (optional)
---@field content? string The incremental content of the message

--- lua/ai/init.lua ------------------------------------------------------------

---@class AiClient
---@field base_url string The base URL for all API requests.
---@field api_key string The API key used for authentication.

--- lua/ai/config.lua ----------------------------------------------------------

---@class AiOptions
---@field api_key string: enviroment variable used for API authentication.
---@field base_url? string: base url for all API requests
---@field copilot boolean Whether to use setup GitHub Copilot as provider.
