// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
//
// Based on https://github.com/64bit/async-openai/ by Himanshu Neema
// Original Copyright (c) 2022 Himanshu Neema
// Licensed under MIT License (see ATTRIBUTIONS-Rust.md)
//
// Modifications Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES.
// Licensed under Apache 2.0
use std::{collections::HashMap, pin::Pin};
use derive_builder::Builder;
use futures::Stream;
use serde::{Deserialize, Serialize};
use utoipa::ToSchema;
use crate::error::OpenAIError;
use super::{ChatCompletionStreamOptions, Choice, CompletionUsage, Prompt, Stop};
/// Custom deserializer for the echo parameter that only accepts booleans.
/// Rejects integers and strings with clear error messages.
fn deserialize_echo_bool<'de, D>(deserializer: D) -> Result<Option<bool>, D::Error>
where
D: serde::Deserializer<'de>,
{
// Outer visitor: handles Option semantics (Some/None/null)
struct StrictBoolVisitor;
impl<'de> serde::de::Visitor<'de> for StrictBoolVisitor {
type Value = Option<bool>;
// Required by Visitor trait
fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
formatter.write_str("echo parameter to be a boolean (true or false) or null")
}
fn visit_some<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
where
D: serde::Deserializer<'de>,
{
deserializer.deserialize_any(BoolOnlyVisitor)
}
fn visit_none<E>(self) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(None)
}
fn visit_unit<E>(self) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(None)
}
}
// Inner visitor: validates type is boolean, rejects integers and strings
struct BoolOnlyVisitor;
impl<'de> serde::de::Visitor<'de> for BoolOnlyVisitor {
type Value = Option<bool>;
fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
formatter.write_str("echo parameter to be a boolean (true or false) or null")
}
fn visit_bool<E>(self, value: bool) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(Some(value))
}
// Explicitly reject strings (including "null", "true", "false")
fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Err(E::invalid_type(
serde::de::Unexpected::Str(value),
&"echo parameter to be a boolean (true or false) or null",
))
}
}
deserializer.deserialize_option(StrictBoolVisitor)
}
#[derive(ToSchema, Clone, Serialize, Deserialize, Default, Debug, Builder, PartialEq)]
#[builder(name = "CreateCompletionRequestArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option), default)]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct CreateCompletionRequest {
/// ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models/overview) for descriptions of them.
pub model: String,
/// The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.
///
/// Note that <|endoftext|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document.
pub prompt: Prompt,
/// Base64-encoded PyTorch tensor containing pre-computed embeddings.
/// At least one of prompt or prompt_embeds is required.
/// If both are provided, prompt_embeds takes precedence.
/// Maximum size: 10MB decoded.
#[serde(skip_serializing_if = "Option::is_none")]
pub prompt_embeds: Option<String>,
/// The suffix that comes after a completion of inserted text.
///
/// This parameter is only supported for `gpt-3.5-turbo-instruct`.
#[serde(skip_serializing_if = "Option::is_none")]
pub suffix: Option<String>, // default: null
/// The maximum number of [tokens](https://platform.openai.com/tokenizer) that can be generated in the completion.
///
/// The token count of your prompt plus `max_tokens` cannot exceed the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens.
#[serde(skip_serializing_if = "Option::is_none")]
pub max_tokens: Option<u32>,
/// What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
///
/// We generally recommend altering this or `top_p` but not both.
#[serde(skip_serializing_if = "Option::is_none")]
pub temperature: Option<f32>, // min: 0, max: 2, default: 1,
/// An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
///
/// We generally recommend altering this or `temperature` but not both.
#[serde(skip_serializing_if = "Option::is_none")]
pub top_p: Option<f32>, // min: 0, max: 1, default: 1
/// How many completions to generate for each prompt.
/// **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`.
///
#[serde(skip_serializing_if = "Option::is_none")]
pub n: Option<u8>, // min:1 max: 128, default: 1
/// Whether to stream back partial progress. If set, tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format)
/// as they become available, with the stream terminated by a `data: [DONE]` message.
#[serde(skip_serializing_if = "Option::is_none")]
pub stream: Option<bool>, // nullable: true
#[serde(skip_serializing_if = "Option::is_none")]
pub stream_options: Option<ChatCompletionStreamOptions>,
/// Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the `logprob` of the sampled token, so there may be up to `logprobs+1` elements in the response.
///
/// The maximum value for `logprobs` is 5.
#[serde(skip_serializing_if = "Option::is_none")]
pub logprobs: Option<u8>, // min:0 , max: 5, default: null, nullable: true
/// Echo back the prompt in addition to the completion
#[serde(skip_serializing_if = "Option::is_none")]
#[serde(default, deserialize_with = "deserialize_echo_bool")]
pub echo: Option<bool>,
/// Up to 32 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
#[serde(skip_serializing_if = "Option::is_none")]
pub stop: Option<Stop>,
/// Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
///
/// [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation/parameter-details)
#[serde(skip_serializing_if = "Option::is_none")]
pub presence_penalty: Option<f32>, // min: -2.0, max: 2.0, default 0
/// Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
///
/// [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation/parameter-details)
#[serde(skip_serializing_if = "Option::is_none")]
pub frequency_penalty: Option<f32>, // min: -2.0, max: 2.0, default: 0
/// Generates `best_of` completions server-side and returns the "best" (the one with the highest log probability per token). Results cannot be streamed.
///
/// When used with `n`, `best_of` controls the number of candidate completions and `n` specifies how many to return – `best_of` must be greater than `n`.
///
/// **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`.
#[serde(skip_serializing_if = "Option::is_none")]
pub best_of: Option<u8>, //min: 0, max: 20, default: 1
/// Modify the likelihood of specified tokens appearing in the completion.
///
/// Accepts a json object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this [tokenizer tool](/tokenizer?view=bpe) (which works for both GPT-2 and GPT-3) to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.
///
/// As an example, you can pass `{"50256": -100}` to prevent the <|endoftext|> token from being generated.
#[serde(skip_serializing_if = "Option::is_none")]
pub logit_bias: Option<HashMap<String, serde_json::Value>>, // default: null
/// A unique identifier representing your end-user, which will help OpenAI to monitor and detect abuse. [Learn more](https://platform.openai.com/docs/usage-policies/end-user-ids).
#[serde(skip_serializing_if = "Option::is_none")]
pub user: Option<String>,
/// If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result.
///
/// Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend.
#[serde(skip_serializing_if = "Option::is_none")]
pub seed: Option<i64>,
}
#[derive(ToSchema, Debug, Deserialize, Clone, PartialEq, Serialize)]
pub struct CreateCompletionResponse {
/// A unique identifier for the completion.
pub id: String,
pub choices: Vec<Choice>,
/// The Unix timestamp (in seconds) of when the completion was created.
pub created: u32,
/// The model used for completion.
pub model: String,
/// This fingerprint represents the backend configuration that the model runs with.
///
/// Can be used in conjunction with the `seed` request parameter to understand when backend changes have been
/// made that might impact determinism.
pub system_fingerprint: Option<String>,
/// The object type, which is always "text_completion"
pub object: String,
pub usage: Option<CompletionUsage>,
/// NVIDIA extension field for response metadata (worker IDs, etc.)
#[serde(skip_serializing_if = "Option::is_none")]
pub nvext: Option<serde_json::Value>,
}
/// Parsed server side events stream until an \[DONE\] is received from server.
pub type CompletionResponseStream =
Pin<Box<dyn Stream<Item = Result<CreateCompletionResponse, OpenAIError>> + Send>>;
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn echo_rejects_integer() {
let json = r#"{"model": "test_model", "prompt": "test", "echo": 1}"#;
let result: Result<CreateCompletionRequest, _> = serde_json::from_str(json);
assert!(result.is_err());
let err_msg = result.unwrap_err().to_string();
assert!(err_msg.contains("invalid type"));
assert!(err_msg.contains("integer"));
assert!(err_msg.contains("echo parameter"));
}
#[test]
fn echo_rejects_string() {
let json = r#"{"model": "test_model", "prompt": "test", "echo": "null"}"#;
let result: Result<CreateCompletionRequest, _> = serde_json::from_str(json);
assert!(result.is_err());
let err_msg = result.unwrap_err().to_string();
assert!(err_msg.contains("invalid type"));
assert!(err_msg.contains("string"));
assert!(err_msg.contains("echo parameter"));
}
}