# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

from __future__ import annotations

from typing import Dict, Union, Iterable, Optional
from typing_extensions import Literal, Required, TypeAlias, TypedDict

from ..._types import SequenceNotStr
from ..shared_params.chat_message import ChatMessage
from ..shared_params.chat_completion_tool import ChatCompletionTool

__all__ = [
    "CompletionCreateParamsBase",
    "FunctionCall",
    "FunctionCallFunctionNameSpec",
    "Function",
    "Prediction",
    "PredictionPredictedOutput",
    "PredictionPredictedOutputContentUnionMember1",
    "PredictionPredictedOutputContentUnionMember1ImageURL",
    "ResponseFormat",
    "ToolChoice",
    "ToolChoiceFunctionSelection",
    "ToolChoiceFunctionSelectionFunction",
    "CompletionCreateParamsNonStreaming",
    "CompletionCreateParamsStreaming",
]


class CompletionCreateParamsBase(TypedDict, total=False):
    messages: Required[Iterable[ChatMessage]]
    """A list of messages comprising the conversation so far."""

    model: Required[str]
    """The name of the model to use.

    Example: `"accounts/fireworks/models/kimi-k2-instruct-0905"`
    """

    context_length_exceeded_behavior: Literal["error", "truncate"]
    """
    What to do if the token count of prompt plus `max_tokens` exceeds the model's
    context window.

    Passing `truncate` limits the `max_tokens` to at most
    `context_window_length - prompt_length`. This is the default.

    Passing `error` would trigger a request error.

    The default of `'truncate'` is selected as it allows to ask for high
    `max_tokens` value while respecting the context window length without having to
    do client-side prompt tokenization.

    Note, that it differs from OpenAI's behavior that matches that of `error`.
    """

    echo: Optional[bool]
    """Echo back the prompt in addition to the completion."""

    echo_last: Optional[int]
    """Echo back the last N tokens of the prompt in addition to the completion.

    This is useful for obtaining logprobs of the prompt suffix but without
    transferring too much data. Passing `echo_last=len(prompt)` is the same as
    `echo=True`
    """

    frequency_penalty: Optional[float]
    """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.

    Reasonable value is around 0.1 to 1 if the aim is to just reduce repetitive
    samples somewhat. If the aim is to strongly suppress repetition, then one can
    increase the coefficients up to 2, but this can noticeably degrade the quality
    of samples. Negative values can be used to increase the likelihood of
    repetition.

    See also `presence_penalty` for penalizing tokens that have at least one
    appearance at a fixed rate.

    OpenAI compatible (follows OpenAI's conventions for handling token frequency and
    repetition penalties).

    Required range: `-2 <= x <= 2`
    """

    function_call: Optional[FunctionCall]
    """Deprecated in OpenAI.

    Use 'tool_choice' instead. This will be automatically transformed to
    tool_choice.
    """

    functions: Iterable[Function]
    """Deprecated in OpenAI.

    Use 'tools' instead. This will be automatically transformed to tools.
    """

    ignore_eos: bool
    """
    This setting controls whether the model should ignore the End of Sequence (EOS)
    token. When set to `True`, the model will continue generating tokens even after
    the EOS token is produced. By default, it stops when the EOS token is reached.
    """

    logit_bias: Optional[Dict[str, float]]
    """Modify the likelihood of specified tokens appearing in the completion.

    Accepts a json object that maps tokens (specified by their token ID in the
    tokenizer) to an associated bias value from -100 to 100. Mathematically, the
    bias is added to the logits generated by the model prior to sampling.
    """

    logprobs: Union[int, bool, None]
    """Include log probabilities in the response.

    This accepts either a boolean or an integer:

    If set to `true`, log probabilities are included and the number of alternatives
    can be controlled via `top_logprobs` (OpenAI-compatible behavior).

    If set to an integer N (0-5), include log probabilities for up to N most likely
    tokens per position in the legacy format.

    The API will always return the logprob of the sampled token, so there may be up
    to `logprobs+1` elements in the response when an integer is used. The maximum
    value for the integer form is 5.
    """

    max_completion_tokens: Optional[int]
    """Alias for max_tokens. Cannot be specified together with max_tokens."""

    max_tokens: Optional[int]
    """The maximum number of tokens to generate in the completion.

    If the token count of your prompt plus max_tokens exceeds the model's context
    length, the behavior depends on context_length_exceeded_behavior. By default,
    max_tokens will be lowered to fit in the context window instead of returning an
    error.
    """

    metadata: Optional[Dict[str, str]]
    """Additional metadata to store with the request for tracing/distillation."""

    min_p: Optional[float]
    """Minimum probability threshold for token selection.

    Only tokens with probability >= min_p are considered for selection. This is an
    alternative to `top_p` and `top_k` sampling.

    Required range: `0 <= x <= 1`
    """

    mirostat_lr: Optional[float]
    """
    Specifies the learning rate for the Mirostat sampling algorithm, which controls
    how quickly the model adjusts its token distribution to maintain the target
    perplexity. A smaller value slows down the adjustments, leading to more stable
    but gradual shifts, while higher values speed up corrections at the cost of
    potential instability.
    """

    mirostat_target: Optional[float]
    """Defines the target perplexity for the Mirostat algorithm.

    Perplexity measures the unpredictability of the generated text, with higher
    values encouraging more diverse and creative outputs, while lower values
    prioritize predictability and coherence. The algorithm dynamically adjusts the
    token selection to maintain this target during text generation.

    If not specified, Mirostat sampling is disabled.
    """

    n: int
    """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`.

    Required range: `1 <= x <= 128`

    Example: `1`
    """

    parallel_tool_calls: Optional[bool]
    """Enable parallel function calling."""

    perf_metrics_in_response: Optional[bool]
    """Whether to include performance metrics in the response body.

    **Non-streaming requests:** Performance metrics are always included in response
    headers (e.g., `fireworks-prompt-tokens`,
    `fireworks-server-time-to-first-token`). Setting this to `true` additionally
    includes the same metrics in the response body under the `perf_metrics` field.

    **Streaming requests:** Performance metrics are only included in the response
    body under the `perf_metrics` field in the final chunk (when `finish_reason` is
    set). This is because headers may not be accessible during streaming.

    The response body `perf_metrics` field contains the following metrics:

    **Basic Metrics (all deployments):**

    - `prompt-tokens`: Number of tokens in the prompt
    - `server-time-to-first-token`: Time from request start to first token (in
      seconds)
    - `server-processing-time`: Total processing time (in seconds, only for
      completed requests)

    **Predicted Outputs Metrics:**

    - `speculation-prompt-tokens`: Number of speculative prompt tokens
    - `speculation-prompt-matched-tokens`: Number of matched speculative prompt
      tokens (for completed requests)

    **Dedicated Deployment Only Metrics:**

    - `speculation-generated-tokens`: Number of speculative generated tokens (for
      completed requests)
    - `speculation-acceptance`: Speculation acceptance rates by position
    - `cached-prompt-tokens`: Number of cached prompt tokens
    - `backend-host`: Hostname of the backend server
    - `num-concurrent-requests`: Number of concurrent requests
    - `deployment`: Deployment name
    - `tokenizer-queue-duration`: Time spent in tokenizer queue
    - `tokenizer-duration`: Time spent in tokenizer
    - `prefill-queue-duration`: Time spent in prefill queue
    - `prefill-duration`: Time spent in prefill
    - `generation-queue-duration`: Time spent in generation queue
    """

    prediction: Optional[Prediction]
    """OpenAI-compatible predicted output for speculative decoding.

    Can be a PredictedOutput object or a simple string. Automatically transformed to
    speculation.
    """

    presence_penalty: Optional[float]
    """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.

    Reasonable value is around 0.1 to 1 if the aim is to just reduce repetitive
    samples somewhat. If the aim is to strongly suppress repetition, then one can
    increase the coefficients up to 2, but this can noticeably degrade the quality
    of samples. Negative values can be used to increase the likelihood of
    repetition.

    See also `frequency_penalty` for penalizing tokens at an increasing rate
    depending on how often they appear.

    OpenAI compatible (follows OpenAI's conventions for handling token frequency and
    repetition penalties).

    Required range: `-2 <= x <= 2`
    """

    prompt_cache_isolation_key: Optional[str]
    """Isolation key for prompt caching to separate cache entries."""

    prompt_cache_max_len: Optional[int]
    """Maximum length of the prompt to cache."""

    prompt_truncate_len: Optional[int]
    """The size (in tokens) to which to truncate chat prompts.

    This includes the system prompt (if any), previous user/assistant messages, and
    the current user message. Earlier user/assistant messages will be evicted first
    to fit the prompt into this length. The system prompt is preserved whenever
    possible and only truncated as a last resort.

    This should usually be set to a number much smaller << than the model's maximum
    context size, to allow enough remaining tokens for generating a response.

    If omitted, you may receive "prompt too long" errors in your responses as
    conversations grow. Note that even with this set, you may still receive "prompt
    too long" errors if individual messages (such as a very long system prompt or
    user message) exceed the model's context window on their own.
    """

    raw_output: Optional[bool]
    """Return raw output from the model."""

    reasoning_effort: Union[Literal["low", "medium", "high", "none"], int, bool, None]
    """Controls reasoning behavior for supported models.

    When enabled, the model's reasoning appears in the `reasoning_content` field of
    the response, separate from the final answer in `content`.

    **Accepted values:**

    - **String** (OpenAI-compatible): `'low'`, `'medium'`, or `'high'` to enable
      reasoning with varying effort levels; `'none'` to disable reasoning.
    - **Boolean** (Fireworks extension): `true` to enable reasoning, `false` to
      disable it.
    - **Integer** (Fireworks extension): A positive integer to set a hard token
      limit on reasoning output (only effective for grammar-based reasoning models).

    **Important:** Boolean values are normalized internally: `true` becomes
    `'medium'`, and `false` becomes `'none'`. This normalization happens before
    model-specific validation, so if a model doesn't support `'none'`, passing
    `false` will produce an error referencing `'none'`.

    **Model-specific behavior:**

    - **Qwen3 (e.g., Qwen3-8B)**: Grammar-based reasoning. Default reasoning on. Use
      `'none'` or `false` to disable. Supports integer token limits to cap reasoning
      output. `'low'` maps to a default token limit (~3000 tokens).
    - **DeepSeek V3.1, DeepSeek V3.2**: Binary on/off reasoning. Default reasoning
      off. Any value except `'none'`/`false`/`null` enables reasoning; effort levels
      and integers have no additional effect.
    - **GLM 4.5, GLM 4.5 Air, GLM 4.6**: Binary on/off reasoning. Default reasoning
      on. Use `'none'` or `false` to disable; effort levels and integers have no
      additional effect.
    - **Harmony (OpenAI GPT-OSS 120B, GPT-OSS 20B)**: Accepts only `'low'`,
      `'medium'`, or `'high'`. Does not support `'none'`, `false`, or integer
      values—using these will return an error (e.g., "Invalid reasoning effort:
      none"). When omitted, defaults to `'medium'`. Lower effort produces faster
      responses with shorter reasoning.
    """

    repetition_penalty: Optional[float]
    """Applies a penalty to repeated tokens to discourage or encourage repetition.

    A value of `1.0` means no penalty, allowing free repetition. Values above `1.0`
    penalize repetition, reducing the likelihood of repeating tokens. Values between
    `0.0` and `1.0` reward repetition, increasing the chance of repeated tokens. For
    a good balance, a value of `1.2` is often recommended. Note that the penalty is
    applied to both the generated output and the prompt in decoder-only models.

    Required range: `0 <= x <= 2`
    """

    response_format: Optional[ResponseFormat]
    """Allows to force the model to produce specific output format.

    Setting to `{ "type": "json_object" }` enables JSON mode, which guarantees the
    message the model generates is valid JSON.

    If `"type"` is `"json_schema"`, a JSON schema must be provided. E.g.,
    `response_format = {"type": "json_schema", "json_schema": <json_schema>}`.

    Important: when using JSON mode, it's crucial to also instruct the model to
    produce JSON via a system or user message. Without this, the model may generate
    an unending stream of whitespace until the generation reaches the token limit,
    resulting in a long-running and seemingly "stuck" request.

    Also note that the message content may be partially cut off if
    `finish_reason="length"`, which indicates the generation exceeded `max_tokens`
    or the conversation exceeded the max context length. In this case the return
    value might not be a valid JSON.
    """

    return_token_ids: Optional[bool]
    """Return token IDs alongside text to avoid retokenization drift."""

    seed: Optional[int]
    """Random seed for deterministic sampling."""

    speculation: Union[str, Iterable[int], None]
    """Speculative decoding prompt or token IDs to speed up generation."""

    stop: Union[str, SequenceNotStr[str], None]
    """Up to 4 sequences where the API will stop generating further tokens.

    The returned text will NOT contain the stop sequence.
    """

    temperature: Optional[float]
    """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.

    Required range: `0 <= x <= 2`

    Example: `1`
    """

    tool_choice: ToolChoice
    """Controls which (if any) tool is called by the model.

    - `none`: the model will not call any tool and instead generates a message.
    - `auto`: the model can pick between generating a message or calling one or more
      tools.
    - `required` (alias: `any`): the model must call one or more tools. To force a
      specific function, pass an object of the form
      `{ "type": "function", "name": "my_function" }` or
      `{ "type": "function", "function": { "name": "my_function" } }` for OpenAI
      compatibility.
    """

    tools: Iterable[ChatCompletionTool]
    """A list of tools the model may call.

    Currently, only functions are supported as a tool.

    Use this to provide a list of functions the model may generate JSON inputs for.

    See the our
    [model library](https://app.fireworks.ai/models/?filter=LLM&functionCalling=true)
    for the list of supported models
    """

    top_k: Optional[int]
    """
    Top-k sampling is another sampling method where the k most probable next tokens
    are filtered and the probability mass is redistributed among only those k next
    tokens. The value of k controls the number of candidates for the next token at
    each step during text generation. Must be between 0 and 100.

    Required range: `0 <= x <= 100`

    Example: `50`
    """

    top_logprobs: Optional[int]
    """
    An integer between 0 and 5 specifying the number of most likely tokens to return
    at each token position, each with an associated log probability. The minimum
    value is 0 and the maximum value is 5.

    When `logprobs` is set, `top_logprobs` can be used to modify how many top log
    probabilities are returned. If `top_logprobs` is not set, the API will return up
    to `logprobs` tokens per position.

    Required range: `0 <= x <= 5`
    """

    top_p: Optional[float]
    """
    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.

    Required range: `0 <= x <= 1`

    Example: `1`
    """

    typical_p: Optional[float]
    """Typical-p sampling is an alternative to nucleus sampling.

    It considers the most typical tokens whose cumulative probability is at most
    typical_p.

    Required range: `0 <= x <= 1`
    """

    user: Optional[str]
    """
    A unique identifier representing your end-user, which can help monitor and
    detect abuse.
    """


class FunctionCallFunctionNameSpec(TypedDict, total=False):
    name: Required[str]


FunctionCall: TypeAlias = Union[Literal["auto", "none"], FunctionCallFunctionNameSpec]


class Function(TypedDict, total=False):
    name: Required[str]
    """The name of the function to be called.

    Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length
    of 64.
    """

    description: Optional[str]
    """
    A description of what the function does, used by the model to choose when and
    how to call the function.
    """

    parameters: Dict[str, object]
    """The parameters the function accepts, described as a JSON Schema object.

    The JSON Schema object should have the following structure:

    ```json
    {
      "type": "object",
      "required": ["param1", "param2"],
      "properties": {
        "param1": {
          "type": "string",
          "description": "..."
        },
        "param2": {
          "type": "number",
          "description": "..."
        }
      }
    }
    ```

    - The `type` field must be `"object"`.
    - The `required` field is an array of strings indicating which parameters are
      required.
    - The `properties` field is a map of property names to their definitions, where
      each property is an object with `type` (string) and `description` (string)
      fields.

    To describe a function that accepts no parameters, provide the value:

    ```json
    { "type": "object", "properties": {} }
    ```
    """

    strict: Optional[bool]


class PredictionPredictedOutputContentUnionMember1ImageURL(TypedDict, total=False):
    url: Required[str]

    detail: Optional[str]


class PredictionPredictedOutputContentUnionMember1(TypedDict, total=False):
    type: Required[str]

    image_url: Optional[PredictionPredictedOutputContentUnionMember1ImageURL]

    text: Optional[str]


class PredictionPredictedOutput(TypedDict, total=False):
    """OpenAI-compatible struct for the "speculation" field."""

    content: Required[Union[str, Iterable[PredictionPredictedOutputContentUnionMember1]]]

    type: Literal["content"]


Prediction: TypeAlias = Union[PredictionPredictedOutput, str]


class ResponseFormat(TypedDict, total=False):
    """Allows to force the model to produce specific output format.

    Setting to `{ "type": "json_object" }` enables JSON mode, which guarantees the message the model generates is valid JSON.

    If `"type"` is `"json_schema"`, a JSON schema must be provided. E.g., `response_format = {"type": "json_schema", "json_schema": <json_schema>}`.

    Important: when using JSON mode, it's crucial to also instruct the model to produce JSON via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request.

    Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. In this case the return value might not be a valid JSON.
    """

    type: Required[Literal["json_object", "json_schema", "grammar", "text"]]

    grammar: Optional[str]

    json_schema: Union[str, Dict[str, object], None]

    schema: Union[str, Dict[str, object], None]


class ToolChoiceFunctionSelectionFunction(TypedDict, total=False):
    name: Required[str]


class ToolChoiceFunctionSelection(TypedDict, total=False):
    type: Required[Literal["function"]]

    function: Optional[ToolChoiceFunctionSelectionFunction]


ToolChoice: TypeAlias = Union[Literal["auto", "none", "any", "required"], ToolChoiceFunctionSelection]


class CompletionCreateParamsNonStreaming(CompletionCreateParamsBase, total=False):
    stream: Optional[Literal[False]]
    """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.
    """


class CompletionCreateParamsStreaming(CompletionCreateParamsBase):
    stream: Required[Literal[True]]
    """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.
    """


CompletionCreateParams = Union[CompletionCreateParamsNonStreaming, CompletionCreateParamsStreaming]
