openapi: 3.0.3
info:
  title: GenieX Server
  version: 0.0.0
  description: |
    GenieX Server - OpenAI compatible API endpoints

paths:
  /v1/chat/completions:
    post:
      summary: Creates a model response for the given chat conversation
      description: This endpoint generates a model response for a given conversation, which can include text and images. It supports both single-turn and multi-turn conversations and can be used for various tasks like question answering, code generation, and function calling.
      operationId: PostV1ChatCompletions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatCompletionRequest"
      responses:
        "200":
          description: Successful response for non-streaming requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatCompletionResponse"

  /v1/logits:
    post:
      summary: Raw logits from a single prefill-only forward pass
      description: |
        Runs one non-autoregressive forward pass over pre-tokenized input and
        returns the raw LM-head logits. This is NOT the OpenAI generative
        logprobs semantics — no sampling or decode loop runs. Intended for
        on-target accuracy metrics (perplexity, MMLU, MMMU). Input is
        pre-tokenized (`input_ids`); the server does not tokenize text here.
      operationId: PostV1Logits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForwardLogitsRequest"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForwardLogitsResponse"

  /v1/models:
    get:
      summary: Lists the currently available models
      description: Lists the currently available models, and provides basic information about each one such as the owner and availability
      operationId: GetV1Models
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelsListResponse"

  /v1/models/{model}:
    get:
      summary: Retrieves a model instance
      description: Retrieves a model instance, providing basic information about the model such as the owner and permissioning
      operationId: GetV1ModelsModel
      parameters:
        - name: model
          in: path
          required: true
          description: The ID of the model to use for this request
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelResponse"
        "404":
          description: Model not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  schemas:
    # ---------- Logits ----------
    ForwardLogitsRequest:
      type: object
      required: [model, input_ids]
      example:
        model: "qualcomm/Qwen3-4B-Instruct-2507"
        input_ids: [1, 2, 3, 4]
        last_only: false
        top_n: 20
      properties:
        model:
          type: string
        input_ids:
          type: array
          items:
            type: integer
          description: Pre-tokenized token ids; the caller owns any special tokens.
        last_only:
          type: boolean
          description: "false (default): every position. true: last token's row only."
        top_n:
          type: integer
          description: "Keep only the top-N logits per row (default 20). 0 returns the full vocabulary per row."
        nctx:
          type: integer
        ngl:
          type: integer
        compute:
          type: string
    ForwardLogitsResponse:
      type: object
      properties:
        model:
          type: string
        n_rows:
          type: integer
        vocab_size:
          type: integer
        top_n:
          type: integer
          description: Effective top-N used (0 means full vocabulary per row).
        rows:
          type: array
          description: One entry per emitted position.
          items:
            type: object
            properties:
              token_ids:
                type: array
                items:
                  type: integer
                description: Token id per logit; omitted when top_n is 0 (column index is the token id).
              logits:
                type: array
                items:
                  type: number
                description: top_n > 0 — top logits sorted descending; top_n == 0 — full vocab in token-id order.

    # ---------- Chat ----------
    ChatCompletionRequest:
      type: object
      required: [model, messages]
      example:
        model: "qualcomm/Qwen3-4B-Instruct-2507"
        messages:
          - role: "user"
            content: "Hello! Briefly introduce yourself."
        nctx: 0
        max_completion_tokens: 2048
        temperature: 0.8
        top_p: 0.95
        stream: false
        enable_json: false
        enable_think: true
      properties:
        model:
          type: string
          description: ID of the model to use
          default: "qualcomm/Qwen3-4B-Instruct-2507"
        messages:
          type: array
          items:
            $ref: "#/components/schemas/ChatMessage"
          description: A list of messages comprising the conversation so far
        nctx:
          type: integer
          minimum: 1
          description: Context window size (llama_cpp only). Omit to use the server default set via `geniex serve --nctx` / `GENIEX_NCTX` (4096 out of the box).
        max_completion_tokens:
          type: integer
          minimum: 1
          description: An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens.
          default: 2048
        temperature:
          type: number
          format: float
          minimum: 0
          maximum: 2
          default: 0.8
          description: What sampling temperature to use, between 0 and 2
        top_p:
          type: number
          format: float
          minimum: 0
          maximum: 1
          default: 0.95
          description: An alternative to sampling with temperature, called nucleus sampling
        stream:
          type: boolean
          description: If set, partial message deltas will be sent
          default: false
        stream_options:
          type: object
          description: Options for streaming responses. Only used when stream is true.
          properties:
            include_usage:
              type: boolean
              description: If set, an additional chunk will be streamed with token usage statistics for the entire request
        presence_penalty:
          type: number
          format: float
          minimum: -2
          maximum: 2
          description: Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far
        frequency_penalty:
          type: number
          format: float
          minimum: -2
          maximum: 2
          description: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far
        tools:
          type: array
          items:
            $ref: "#/components/schemas/ChatCompletionTool"
          description: A list of tools the model may call
        enable_json:
          type: boolean
          description: Whether to enable JSON response generation
          default: false
        enable_think:
          type: boolean
          description: Whether to enable thinking mode for the model
          default: true
        top_k:
          type: integer
          minimum: 0
          description: An alternative to sampling with temperature, called top-k sampling
        min_p:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: An alternative to sampling with temperature, called nucleus sampling
        repetition_penalty:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: The parameter for repetition penalty. 1.0 means no penalty
        grammar_path:
          type: string
          description: Path to the grammar file for structured output
        grammar_string:
          type: string
          description: Grammar string for structured output
        ngl:
          type: integer
          description: Number of GPU/NPU layers to offload (llama_cpp only). Omit to use the server default set via `geniex serve --ngl` / `GENIEX_NGL` (999 out of the box); the server chooses the correct layout per backend.
        compute:
          type: string
          enum: [cpu, gpu, npu, hybrid]
          description: Compute unit to run on. Omit to use the server default set via `geniex serve --compute` / `GENIEX_COMPUTE`. QAIRT is NPU-only; other aliases are coerced with a warning.
        image_max_length:
          type: integer
          description: Maximum length for image processing (VLM only)
        spec_type:
          type: string
          enum: [draft-mtp, draft-eagle3, draft-simple, ngram-simple, ngram-map-k, ngram-map-k4v, ngram-mod, ngram-cache]
          description: Speculative decoding type (llama_cpp only). Omit or set to empty to disable. `draft-*` variants require `spec_draft_model`; `ngram-*` variants are self-speculative.
        spec_draft_model:
          type: string
          description: Draft/MTP model for `draft-*` spec types (llama_cpp only). Catalogue name `org/repo[:precision]` (must be pulled via `geniex pull` beforehand — the server does NOT auto-download) or absolute path to a local GGUF file.
        spec_n_max:
          type: integer
          minimum: 1
          description: Max draft tokens per verification step (llama_cpp only). Default 3 when omitted.
        spec_n_min:
          type: integer
          minimum: 0
          description: Min draft tokens per verification step (llama_cpp only). 0 = llama.cpp default.
        spec_p_min:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Min greedy draft probability (llama_cpp only). 0 = llama.cpp default.

    ChatMessage:
      type: object
      required: [role, content]
      default:
        { "role": "user", "content": "Hello! Briefly introduce yourself." }
      properties:
        role:
          type: string
          enum: [system, user, assistant, tool]
          description: The role of the author of this message
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: "#/components/schemas/ChatMessageContent"
          description: The contents of the message
        name:
          type: string
          description: The name of the author of this message
        tool_calls:
          type: array
          items:
            $ref: "#/components/schemas/ChatCompletionMessageToolCall"
          description: The tool calls generated by the model
        function_call:
          $ref: "#/components/schemas/ChatCompletionMessageFunctionCall"
          description: Deprecated and replaced by tool_calls

    ChatMessageContent:
      type: object
      properties:
        type:
          type: string
          enum: [text, image_url, input_audio]
        text:
          type: string
        image_url:
          $ref: "#/components/schemas/ChatMessageImageURL"
        input_audio:
          $ref: "#/components/schemas/ChatMessageAudioURL"

    ChatMessageImageURL:
      type: object
      properties:
        url:
          type: string
        detail:
          type: string
          enum: [low, high, auto]

    ChatMessageAudioURL:
      type: object
      properties:
        data:
          type: string
          description: The audio data (base64 encoded or URL)

    ChatCompletionTool:
      type: object
      properties:
        type:
          type: string
          enum: [function]
        function:
          $ref: "#/components/schemas/ChatCompletionToolFunction"

    ChatCompletionToolFunction:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: The name of the function to be called
        description:
          type: string
          description: A description of what the function does
        parameters:
          type: object
          description: The parameters the functions accepts

    ChatCompletionToolChoice:
      type: object
      properties:
        type:
          type: string
          enum: [function]
        function:
          type: object
          properties:
            name:
              type: string

    ChatCompletionMessageToolCall:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tool call
        type:
          type: string
          enum: [function]
          description: The type of the tool
        function:
          $ref: "#/components/schemas/ChatCompletionMessageToolCallFunction"

    ChatCompletionMessageToolCallFunction:
      type: object
      properties:
        name:
          type: string
          description: The name of the function to call
        arguments:
          type: string
          description: The arguments to call the function with, as generated by the model in JSON format

    ChatCompletionMessageFunctionCall:
      type: object
      properties:
        name:
          type: string
          description: The name of the function to call
        arguments:
          type: string
          description: The arguments to call the function with, as generated by the model in JSON format

    ChatCompletionResponse:
      type: object
      required: [choices]
      properties:
        id:
          type: string
          description: A unique identifier for the chat completion
        object:
          type: string
          description: The object type, which is always "chat.completion"
        created:
          type: integer
          description: The Unix timestamp (in seconds) of when the chat completion was created
        model:
          type: string
          description: The model used for the chat completion
        choices:
          type: array
          items:
            $ref: "#/components/schemas/ChatChoice"
          description: A list of chat completion choices
        usage:
          $ref: "#/components/schemas/TokenUsage"

    ChatChoice:
      type: object
      properties:
        index:
          type: integer
          description: The index of the choice in the list of choices
        message:
          $ref: "#/components/schemas/ChatMessage"
          description: A chat completion message generated by the model
        finish_reason:
          type: string
          enum: [stop, length, tool_calls, content_filter, function_call]
          description: The reason the model stopped generating tokens
        logprobs:
          $ref: "#/components/schemas/ChatCompletionChoiceLogprobs"

    ChatCompletionChoiceLogprobs:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/ChatCompletionTokenLogprob"

    ChatCompletionTokenLogprob:
      type: object
      properties:
        token:
          type: string
        logprob:
          type: number
        bytes:
          type: array
          items:
            type: integer
        top_logprobs:
          type: array
          items:
            $ref: "#/components/schemas/ChatCompletionTokenLogprobTopLogprob"

    ChatCompletionTokenLogprobTopLogprob:
      type: object
      properties:
        token:
          type: string
        logprob:
          type: number
        bytes:
          type: array
          items:
            type: integer

    # ---------- Common ----------
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong

    TokenUsage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          description: Number of tokens in the prompt
        completion_tokens:
          type: integer
          description: Number of tokens in the generated completion
        total_tokens:
          type: integer
          description: Total number of tokens used in the request

    # ---------- Models ----------
    ModelsListResponse:
      type: object
      properties:
        object:
          type: string
          description: The object type, which is always "list"
        data:
          type: array
          items:
            $ref: "#/components/schemas/Model"

    ModelResponse:
      type: object
      properties:
        id:
          type: string
          description: The model identifier
        object:
          type: string
          description: The object type, which is always "model"
        owned_by:
          type: string
          description: The organization that owns the model
        created:
          type: integer
          description: The Unix timestamp (in seconds) of when the model was created
        permission:
          type: array
          items:
            type: object
          description: The permissions associated with the model

    Model:
      type: object
      properties:
        id:
          type: string
          description: The model identifier
        owned_by:
          type: string
          description: The organization that owns the model