openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Hugging Face Transformers Service",
    "description": "This **Local LLM server** application is a Windows service application designed to provide an interface for working with Hugging Face models, specifically catering to translation and text generation tasks.",
    "version": "2.1.0"
  },
  "paths": {
    "/v1/model/directory": {
      "get": {
        "summary": "Get Download Path",
        "description": "Retrieve the current download directory.\nIf `model_name` is provided and not empty, include it in the path.",
        "operationId": "get_download_path_v1_model_directory_get",
        "parameters": [
          {
            "name": "model_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Name of the model to include in the path",
              "title": "Model Name"
            },
            "description": "Name of the model to include in the path"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DownloadDirectoryResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/model/files": {
      "get": {
        "summary": "List Model Files",
        "description": "Retrieves the list of available files in the specified Hugging Face model repository, including each file's size when available. Only files in the root directory are listed.",
        "operationId": "list_model_files_endpoint_v1_model_files_get",
        "parameters": [
          {
            "name": "model_name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Name of the Hugging Face model repository",
              "title": "Model Name"
            },
            "description": "Name of the Hugging Face model repository"
          },
          {
            "name": "api-key",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Hugging Face API key",
              "title": "Api-Key"
            },
            "description": "Hugging Face API key"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful retrieval of model files.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListModelFilesResponse"
                },
                "example": {
                  "files": [
                    {
                      "file_name": "config.json",
                      "file_size": "15.60 KB",
                      "download_url": "https://..."
                    },
                    {
                      "file_name": "pytorch_model.bin",
                      "file_size": "350.45 MB",
                      "download_url": "https://..."
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Model not found."
          },
          "400": {
            "description": "Error due to invalid request or issues fetching model information."
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/models": {
      "get": {
        "summary": "List downloaded models",
        "description": "List all downloaded models along with their types, sizes, properties, and mounted files.",
        "operationId": "list_models_v1_models_get",
        "responses": {
          "200": {
            "description": "A list of models available in the cache.",
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ModelInfo"
                  },
                  "type": "array",
                  "title": "Response List Models V1 Models Get"
                },
                "example": [
                  {
                    "model_name": "microsoft/Phi-3.5-mini-instruct",
                    "model_type": "text-generation",
                    "model_mounted": true,
                    "model_size_bytes": "7.12 GB",
                    "properties": {
                      "src_lang": "eng_Latn",
                      "tgt_lang": "ita_Latn"
                    }
                  },
                  {
                    "model_name": "bartowski/Marco-o1-GGUF",
                    "model_type": "text-generation",
                    "model_mounted": true,
                    "model_size_bytes": "15.3 GB",
                    "properties": {},
                    "file_names": [
                      "Marco-o1-IQ2_M.gguf",
                      "Marco-o1-Another.gguf"
                    ],
                    "loaded_file_name": "Marco-o1-IQ2_M.gguf"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/v1/model/download": {
      "post": {
        "summary": "Download a Model",
        "description": "Initiates the download of a specified model from the Hugging Face Hub. If the model is already downloaded, it overwrites existing files. Users can specify which files to download. If no files are specified, all files from the model will be downloaded.",
        "operationId": "download_model_endpoint_v1_model_download_post",
        "parameters": [
          {
            "name": "api-key",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Hugging Face API key",
              "title": "Api-Key"
            },
            "description": "Hugging Face API key"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DownloadModelRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful model download initiation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "title": "Response Download Model Endpoint V1 Model Download Post"
                },
                "example": {
                  "status": "Download started.",
                  "message": "Model 'model_name' is being downloaded."
                }
              }
            }
          },
          "400": {
            "description": "Error in model download due to invalid request or existing download."
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/model/mount": {
      "post": {
        "summary": "Mount a Model",
        "description": "Mount the specified model and setup the appropriate pipeline. Supported model types: 'translation', 'text-generation'.",
        "operationId": "mount_model_v1_model_mount_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MountModelRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object",
                  "title": "Response Mount Model V1 Model Mount Post"
                },
                "example": {
                  "message": "Model 'facebook/nllb-200-distilled-600M' of type 'translation' mounted successfully.",
                  "properties": {
                    "src_lang": "eng_Latn",
                    "tgt_lang": "ita_Latn"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unsupported model type provided or invalid file_name for 'text-generation' model.",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Unsupported model type provided."
                }
              }
            }
          },
          "404": {
            "description": "Model path or specified gguf file does not exist.",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Model path does not exist."
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/model/unmount": {
      "post": {
        "summary": "Unmount Model",
        "description": "Unmount the mounted model to free up resources.",
        "operationId": "unmount_model_v1_model_unmount_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModelRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object",
                  "title": "Response Unmount Model V1 Model Unmount Post"
                },
                "example": {
                  "message": "Model unmounted successfully."
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/model/delete": {
      "delete": {
        "summary": "Delete Local Model",
        "description": "Delete the local files of a previously mounted model based on the model name.",
        "operationId": "delete_model_v1_model_delete_delete",
        "parameters": [
          {
            "name": "model_name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Name of the Hugging Face model repository",
              "title": "Model Name"
            },
            "description": "Name of the Hugging Face model repository"
          }
        ],
        "responses": {
          "200": {
            "description": "Model deleted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteModelResponse"
                },
                "example": {
                  "message": "Model 'facebook/nllb-200-distilled-600M' has been deleted successfully."
                }
              }
            }
          },
          "404": {
            "description": "Model not found."
          },
          "500": {
            "description": "Internal server error during deletion."
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/translation": {
      "post": {
        "summary": "Translate Text",
        "description": "Translate input text using the specified translation model.",
        "operationId": "translate_v1_translation_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TranslationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranslationResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/model/info": {
      "get": {
        "summary": "Retrieve model info",
        "description": "Retrieve either model configuration or model information.",
        "operationId": "get_model_info_v1_model_info_get",
        "parameters": [
          {
            "name": "model_name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "description": "The name of the Hugging Face model",
              "title": "Model Name"
            },
            "description": "The name of the Hugging Face model"
          },
          {
            "name": "return_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Specify 'config' to retrieve model configuration or 'info' to retrieve model information.",
              "default": "info",
              "title": "Return Type"
            },
            "description": "Specify 'config' to retrieve model configuration or 'info' to retrieve model information."
          },
          {
            "name": "api-key",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Hugging Face API key",
              "title": "Api-Key"
            },
            "description": "Hugging Face API key"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelInfoResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/model/fine-tune": {
      "post": {
        "summary": "Fine-Tune a Pretrained Translation Model",
        "description": "Fine-tunes a pretrained translation model with provided parameters and sends real-time progress updates via WebSocket.",
        "operationId": "fine_tune_v1_model_fine_tune_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FineTuneRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DeleteModelResponse": {
        "properties": {
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Confirmation message indicating successful deletion of the model."
          }
        },
        "type": "object",
        "required": [
          "message"
        ],
        "title": "DeleteModelResponse"
      },
      "DownloadDirectoryResponse": {
        "properties": {
          "path": {
            "type": "string",
            "title": "Path"
          }
        },
        "type": "object",
        "required": [
          "path"
        ],
        "title": "DownloadDirectoryResponse"
      },
      "DownloadModelRequest": {
        "properties": {
          "client_id": {
            "type": "string",
            "title": "Client Id",
            "description": "Unique identifier for the client"
          },
          "model_name": {
            "type": "string",
            "title": "Model Name",
            "description": "The Hugging Face model repository name"
          },
          "files_to_download": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Files To Download",
            "description": "List of specific files to download. If not provided, all files will be downloaded."
          }
        },
        "type": "object",
        "required": [
          "client_id",
          "model_name"
        ],
        "title": "DownloadModelRequest",
        "examples": [
          {
            "summary": "Download only the second gguf file (Q2)",
            "value": {
              "client_id": "unique_client_id_123",
              "files_to_download": [
                "pytorch_model.bin",
                "tokenizer.json",
                "config.json",
                "README.md"
              ],
              "model_name": "facebook/nllb-200-distilled-600M"
            }
          }
        ]
      },
      "FineTuneRequest": {
        "properties": {
          "client_id": {
            "type": "string",
            "title": "Client Id",
            "description": "Unique identifier for the client to receive progress updates."
          },
          "model_path": {
            "type": "string",
            "title": "Model Path",
            "description": "Local path to the pretrained model."
          },
          "output_dir": {
            "type": "string",
            "title": "Output Dir",
            "description": "Directory where the fine-tuned model will be saved."
          },
          "data_file": {
            "type": "string",
            "title": "Data File",
            "description": "Path to the CSV data file containing source and target texts."
          },
          "source_lang": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Lang",
            "description": "Source language code (e.g., 'en_XX'). Required for multilingual models."
          },
          "target_lang": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Target Lang",
            "description": "Target language code (e.g., 'it_IT'). Required for multilingual models."
          },
          "num_train_epochs": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Num Train Epochs",
            "description": "Number of training epochs.",
            "default": 4
          },
          "per_device_train_batch_size": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Per Device Train Batch Size",
            "description": "Batch size per device during training.",
            "default": 2
          },
          "per_device_eval_batch_size": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Per Device Eval Batch Size",
            "description": "Batch size per device during evaluation.",
            "default": 2
          },
          "learning_rate": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Learning Rate",
            "description": "Learning rate for the optimizer.",
            "default": 3e-05
          },
          "weight_decay": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Weight Decay",
            "description": "Weight decay for the optimizer.",
            "default": 0.01
          },
          "max_length": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Max Length",
            "description": "Maximum sequence length for tokenization.",
            "default": 512
          },
          "save_strategy": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Save Strategy",
            "description": "Strategy to save the model (e.g., 'no', 'steps').",
            "default": "steps"
          },
          "save_steps": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Save Steps",
            "description": "Number of steps between each model save.",
            "default": 50
          },
          "save_total_limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Save Total Limit",
            "description": "Maximum number of checkpoints to save.",
            "default": 3
          },
          "validation_file": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Validation File",
            "description": "Path to the CSV validation data file (optional)."
          }
        },
        "type": "object",
        "required": [
          "client_id",
          "model_path",
          "output_dir",
          "data_file"
        ],
        "title": "FineTuneRequest",
        "example": {
          "client_id": "client123",
          "data_file": "C:/HuggingFace/Data/data.csv",
          "learning_rate": 3e-05,
          "max_length": 512,
          "model_path": "C:/HuggingFace/Models/Helsinki-NLP--opus-mt-en-it",
          "num_train_epochs": 4,
          "output_dir": "C:/HuggingFace/Models/Helsinki-NLP--opus-mt-en-it-finetuned-it",
          "per_device_eval_batch_size": 2,
          "per_device_train_batch_size": 2,
          "save_steps": 10,
          "save_strategy": "steps",
          "save_total_limit": 2,
          "source_lang": "en_XX",
          "target_lang": "it_IT",
          "validation_file": "C:/HuggingFace/Data/validation_data.csv",
          "weight_decay": 0.01
        }
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "ListModelFilesResponse": {
        "properties": {
          "files": {
            "items": {
              "$ref": "#/components/schemas/ModelFileInfo"
            },
            "type": "array",
            "title": "Files"
          }
        },
        "type": "object",
        "required": [
          "files"
        ],
        "title": "ListModelFilesResponse"
      },
      "ModelFileInfo": {
        "properties": {
          "file_name": {
            "type": "string",
            "title": "File Name"
          },
          "file_size": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "File Size"
          },
          "download_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Download Url"
          }
        },
        "type": "object",
        "required": [
          "file_name"
        ],
        "title": "ModelFileInfo"
      },
      "ModelInfo": {
        "properties": {
          "model_name": {
            "type": "string",
            "title": "Model Name"
          },
          "model_type": {
            "type": "string",
            "title": "Model Type"
          },
          "model_mounted": {
            "type": "boolean",
            "title": "Model Mounted"
          },
          "model_size_bytes": {
            "type": "string",
            "title": "Model Size Bytes"
          },
          "properties": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object",
            "title": "Properties"
          },
          "file_names": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "File Names"
          },
          "loaded_file_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Loaded File Name"
          }
        },
        "type": "object",
        "required": [
          "model_name",
          "model_type",
          "model_mounted",
          "model_size_bytes",
          "properties"
        ],
        "title": "ModelInfo"
      },
      "ModelInfoResponse": {
        "properties": {
          "model_name": {
            "type": "string",
            "title": "Model Name"
          },
          "config": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Config"
          },
          "message": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Message"
          },
          "minimal_info": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Minimal Info"
          },
          "info": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Info"
          }
        },
        "type": "object",
        "required": [
          "model_name"
        ],
        "title": "ModelInfoResponse"
      },
      "ModelRequest": {
        "properties": {
          "model_name": {
            "type": "string",
            "title": "Model Name",
            "description": "The Hugging Face model name"
          }
        },
        "type": "object",
        "required": [
          "model_name"
        ],
        "title": "ModelRequest",
        "example": {
          "model_name": "facebook/nllb-200-distilled-600M"
        }
      },
      "MountModelRequest": {
        "properties": {
          "model_name": {
            "type": "string",
            "title": "Model Name",
            "description": "The Hugging Face model name."
          },
          "properties": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Properties",
            "description": "Optional dictionary of additional properties (e.g., src_lang, tgt_lang)."
          },
          "file_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "File Name",
            "description": "Specific *.gguf file name to mount for 'llama' model types."
          }
        },
        "type": "object",
        "required": [
          "model_name"
        ],
        "title": "MountModelRequest",
        "example": {
          "model_name": "facebook/nllb-200-distilled-600M",
          "properties": {
            "src_lang": "eng_Latn",
            "tgt_lang": "ita_Latn"
          }
        }
      },
      "TranslationRequest": {
        "properties": {
          "model_name": {
            "type": "string",
            "title": "Model Name",
            "description": "The name of the translation model to use."
          },
          "text": {
            "type": "string",
            "title": "Text",
            "description": "The source content that should be translated."
          }
        },
        "type": "object",
        "required": [
          "model_name",
          "text"
        ],
        "title": "TranslationRequest",
        "example": {
          "model_name": "facebook/nllb-200-distilled-600M",
          "text": "The cat is on the table."
        }
      },
      "TranslationResponse": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id"
          },
          "object": {
            "type": "string",
            "title": "Object"
          },
          "model": {
            "type": "string",
            "title": "Model"
          },
          "generated_text": {
            "type": "string",
            "title": "Generated Text"
          }
        },
        "type": "object",
        "required": [
          "id",
          "object",
          "model",
          "generated_text"
        ],
        "title": "TranslationResponse"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    }
  }
}