#
utils/hub

Utility functions to interact with the Hugging Face Hub (https://huggingface.co/models)

- utils/hub
  - static
    - `.getFile(urlOrPath)` ⇒ `Promise.<(FileResponse|Response)>`
    - `.getModelFile(path_or_repo_id, filename, [fatal], [options])` ⇒ `Promise`
      - `~cacheKey` : `string`
      - `~responseToCache` : `Response` | `undefined`
      - `~response` : `Response` | `FileResponse` | `undefined`
    - `.getModelJSON(modelPath, fileName, [fatal], [options])` ⇒ `Promise.<Object>`
  - inner
    - ~FileResponse
      - `new FileResponse(filePath)`
      - `._CONTENT_TYPE_MAP`
      - `.updateContentType()` ⇒ `void`
      - `.clone()` ⇒ `FileResponse`
      - `.arrayBuffer()` ⇒ `Promise.<ArrayBuffer>`
      - `.blob()` ⇒ `Promise.<Blob>`
      - `.text()` ⇒ `Promise.<string>`
      - `.json()` ⇒ `Promise.<Object>`
    - ~FileCache
      - `new FileCache(path)`
      - `.match(request)` ⇒ `Promise.<(FileResponse|undefined)>`
      - `.put(request, response)` ⇒ `Promise.<void>`
    - `~isValidHttpUrl(string, [validHosts])` ⇒ `boolean`
    - `~handleError(status, remoteURL, fatal)` ⇒ `null`
    - `~tryCache(cache, ...names)` ⇒ `Promise.<(FileResponse|Response|undefined)>`
    - `~readResponse(response, progress_callback)` ⇒ `Promise.<Uint8Array>`
    - `~pathJoin(...parts)` ⇒ `string`
    - `~PretrainedOptions` : `Object`

##
`utils/hub.getFile(urlOrPath)` ⇒ `Promise.<(FileResponse|Response)>`

Helper function to get a file, using either the Fetch API or FileSystem API.

Kind: static method of `utils/hub`
Returns: `Promise.<(FileResponse|Response)>` - A promise that resolves to a FileResponse object (if the file is retrieved using the FileSystem API), or a Response object (if the file is retrieved using the Fetch API).

Param | Type | Description
--- | --- | ---
urlOrPath | `URL` | `string` | The URL/path of the file to get.

##
`utils/hub.getModelFile(path_or_repo_id, filename, [fatal], [options])` ⇒ `Promise`

Retrieves a file from either a remote URL using the Fetch API or from the local file system using the FileSystem API. If the filesystem is available and `env.useCache = true`, the file will be downloaded and cached.

Kind: static method of `utils/hub`
Returns: `Promise` - A Promise that resolves with the file content as a buffer.
Throws:

- Will throw an error if the file is not found and `fatal` is true.

Param | Type | Default | Description
--- | --- | --- | ---
path_or_repo_id | `string` |  | This can be either: a string, the model id of a model repo on huggingface.co. a path to a directory potentially containing the file.
filename | `string` |  | The name of the file to locate in `path_or_repo`.
[fatal] | `boolean` | `true` | Whether to throw an error if the file is not found.
[options] | `PretrainedOptions` |  | An object containing optional parameters.

- `.getModelFile(path_or_repo_id, filename, [fatal], [options])` ⇒ `Promise`
  - `~cacheKey` : `string`
  - `~responseToCache` : `Response` | `undefined`
  - `~response` : `Response` | `FileResponse` | `undefined`

###
`getModelFile~cacheKey` : `string`

Kind: inner property of `getModelFile`

###
`getModelFile~responseToCache` : `Response` | `undefined`

Kind: inner property of `getModelFile`

###
`getModelFile~response` : `Response` | `FileResponse` | `undefined`

Kind: inner property of `getModelFile`

##
`utils/hub.getModelJSON(modelPath, fileName, [fatal], [options])` ⇒ `Promise.<Object>`

Fetches a JSON file from a given path and file name.

Kind: static method of `utils/hub`
Returns: `Promise.<Object>` - The JSON data parsed into a JavaScript object.
Throws:

- Will throw an error if the file is not found and `fatal` is true.

Param | Type | Default | Description
--- | --- | --- | ---
modelPath | `string` |  | The path to the directory containing the file.
fileName | `string` |  | The name of the file to fetch.
[fatal] | `boolean` | `true` | Whether to throw an error if the file is not found.
[options] | `PretrainedOptions` |  | An object containing optional parameters.

##
utils/hub~FileResponse

Kind: inner class of `utils/hub`

- ~FileResponse
  - `new FileResponse(filePath)`
  - `._CONTENT_TYPE_MAP`
  - `.updateContentType()` ⇒ `void`
  - `.clone()` ⇒ `FileResponse`
  - `.arrayBuffer()` ⇒ `Promise.<ArrayBuffer>`
  - `.blob()` ⇒ `Promise.<Blob>`
  - `.text()` ⇒ `Promise.<string>`
  - `.json()` ⇒ `Promise.<Object>`

###
`new FileResponse(filePath)`

Creates a new `FileResponse` object.

Param | Type
--- | ---
filePath | `string` | `URL`

###
`fileResponse._CONTENT_TYPE_MAP`

Mapping from file extensions to MIME types.

Kind: instance property of `FileResponse`

###
`fileResponse.updateContentType()` ⇒ `void`

Updates the ‘content-type’ header property of the response based on the extension of the file specified by the filePath property of the current object.

Kind: instance method of `FileResponse`

###
`fileResponse.clone()` ⇒ `FileResponse`

Clone the current FileResponse object.

Kind: instance method of `FileResponse`
Returns: `FileResponse` - A new FileResponse object with the same properties as the current object.

###
`fileResponse.arrayBuffer()` ⇒ `Promise.<ArrayBuffer>`

Reads the contents of the file specified by the filePath property and returns a Promise that resolves with an ArrayBuffer containing the file’s contents.

Kind: instance method of `FileResponse`
Returns: `Promise.<ArrayBuffer>` - A Promise that resolves with an ArrayBuffer containing the file’s contents.
Throws:

- `Error` If the file cannot be read.

###
`fileResponse.blob()` ⇒ `Promise.<Blob>`

Reads the contents of the file specified by the filePath property and returns a Promise that resolves with a Blob containing the file’s contents.

Kind: instance method of `FileResponse`
Returns: `Promise.<Blob>` - A Promise that resolves with a Blob containing the file’s contents.
Throws:

- `Error` If the file cannot be read.

###
`fileResponse.text()` ⇒ `Promise.<string>`

Reads the contents of the file specified by the filePath property and returns a Promise that resolves with a string containing the file’s contents.

Kind: instance method of `FileResponse`
Returns: `Promise.<string>` - A Promise that resolves with a string containing the file’s contents.
Throws:

- `Error` If the file cannot be read.

###
`fileResponse.json()` ⇒ `Promise.<Object>`

Reads the contents of the file specified by the filePath property and returns a Promise that resolves with a parsed JavaScript object containing the file’s contents.

Kind: instance method of `FileResponse`
Returns: `Promise.<Object>` - A Promise that resolves with a parsed JavaScript object containing the file’s contents.
Throws:

- `Error` If the file cannot be read.

##
utils/hub~FileCache

Kind: inner class of `utils/hub`

- ~FileCache
  - `new FileCache(path)`
  - `.match(request)` ⇒ `Promise.<(FileResponse|undefined)>`
  - `.put(request, response)` ⇒ `Promise.<void>`

###
`new FileCache(path)`

Instantiate a `FileCache` object.

Param | Type
--- | ---
path | `string`

###
`fileCache.match(request)` ⇒ `Promise.<(FileResponse|undefined)>`

Checks whether the given request is in the cache.

Kind: instance method of `FileCache`

Param | Type
--- | ---
request | `string`

###
`fileCache.put(request, response)` ⇒ `Promise.<void>`

Adds the given response to the cache.

Kind: instance method of `FileCache`

Param | Type
--- | ---
request | `string`
response | `Response` | `FileResponse`

##
`utils/hub~isValidHttpUrl(string, [validHosts])` ⇒ `boolean`

Determines whether the given string is a valid HTTP or HTTPS URL.

Kind: inner method of `utils/hub`
Returns: `boolean` - True if the string is a valid HTTP or HTTPS URL, false otherwise.

Param | Type | Default | Description
--- | --- | --- | ---
string | `string` | `URL` |  | The string to test for validity as an HTTP or HTTPS URL.
[validHosts] | `Array.<string>` | `` | A list of valid hostnames. If specified, the URL's hostname must be in this list.

##
`utils/hub~handleError(status, remoteURL, fatal)` ⇒ `null`

Helper method to handle fatal errors that occur while trying to load a file from the Hugging Face Hub.

Kind: inner method of `utils/hub`
Returns: `null` - Returns `null` if `fatal = true`.
Throws:

- `Error` If `fatal = false`.

Param | Type | Description
--- | --- | ---
status | `number` | The HTTP status code of the error.
remoteURL | `string` | The URL of the file that could not be loaded.
fatal | `boolean` | Whether to raise an error if the file could not be loaded.

##
`utils/hub~tryCache(cache, ...names)` ⇒ `Promise.<(FileResponse|Response|undefined)>`

Kind: inner method of `utils/hub`
Returns: `Promise.<(FileResponse|Response|undefined)>` - The item from the cache, or undefined if not found.

Param | Type | Description
--- | --- | ---
cache | `FileCache` | `Cache` | The cache to search
...names | `Array.<string>` | The names of the item to search for

##
`utils/hub~readResponse(response, progress_callback)` ⇒ `Promise.<Uint8Array>`

Read and track progress when reading a Response object

Kind: inner method of `utils/hub`
Returns: `Promise.<Uint8Array>` - A Promise that resolves with the Uint8Array buffer

Param | Type | Description
--- | --- | ---
response | `any` | The Response object to read
progress_callback | `function` | The function to call with progress updates

##
`utils/hub~pathJoin(...parts)` ⇒ `string`

Joins multiple parts of a path into a single path, while handling leading and trailing slashes.

Kind: inner method of `utils/hub`
Returns: `string` - A string representing the joined path.

Param | Type | Description
--- | --- | ---
...parts | `string` | Multiple parts of a path.

##
`utils/hub~PretrainedOptions` : `Object`

Options for loading a pretrained model.

Kind: inner typedef of `utils/hub`
Properties

Name | Type | Default | Description
--- | --- | --- | ---
[options.quantized] | `boolean` | `true` | Whether to load the 8-bit quantized version of the model (only applicable when loading model files).
[options.progress_callback] | `function` | `` | If specified, this function will be called during model construction, to provide the user with progress updates.
[options.config] | `Object` | `` | Configuration for the model to use instead of an automatically loaded configuration. Configuration can be automatically loaded when: The model is a model provided by the library (loaded with the model id string of a pretrained model). The model is loaded by supplying a local directory as `pretrained_model_name_or_path` and a configuration JSON file named config.json is found in the directory.
[options.cache_dir] | `string` | `null` | Path to a directory in which a downloaded pretrained model configuration should be cached if the standard cache should not be used.
[options.local_files_only] | `boolean` | `false` | Whether or not to only look at local files (e.g., not try downloading the model).
[options.revision] | `string` | `"'main'"` | The specific model version to use. It can be a branch name, a tag name, or a commit id, since we use a git-based system for storing models and other artifacts on huggingface.co, so `revision` can be any identifier allowed by git. NOTE: This setting is ignored for local requests.
[options.model_file_name] | `string` | `null` | If specified, load the model with this name (excluding the .onnx suffix). Currently only valid for encoder- or decoder-only models.