> For the complete documentation index, see [llms.txt](https://boinc-ai.gitbook.io/transformers.js/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boinc-ai.gitbook.io/transformers.js/api-reference/utilities/hub.md).

# Hub

## utils/hub

Utility functions to interact with the BOINC AI Hub ([https://boincai.com/models](https://huggingface.co/models))

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

***

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

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

**Kind**: static method of [`utils/hub`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_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]) ⇒ \<code> Promise \</code>

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`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_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`            |         | <p>This can be either:</p><ul><li>a string, the <em>model id</em> of a model repo on boincai.com.</li><li>a path to a <em>directory</em> potentially containing the file.</li></ul> |
| 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])`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub.getModelFile) ⇒ `Promise`
  * [`~cacheKey`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub.getModelFile..cacheKey) : `string`
  * [`~response`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub.getModelFile..response) : `Response` | `FileResponse` | `undefined`

***

#### getModelFile\~cacheKey : \<code> string \</code>

**Kind**: inner property of [`getModelFile`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub.getModelFile)

***

#### getModelFile\~response : \<code> Response \</code> | \<code> FileResponse \</code> | \<code> undefined \</code>

**Kind**: inner property of [`getModelFile`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub.getModelFile)

***

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

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

**Kind**: static method of [`utils/hub`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_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`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub)

* [\~FileResponse](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileResponse)
  * [`new FileResponse(filePath)`](https://huggingface.co/docs/transformers.js/api/utils/hub#new_module_utils/hub..FileResponse_new)
  * [`._CONTENT_TYPE_MAP`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileResponse+_CONTENT_TYPE_MAP)
  * [`.updateContentType()`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileResponse+updateContentType) ⇒ `void`
  * [`.clone()`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileResponse+clone) ⇒ `FileResponse`
  * [`.arrayBuffer()`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileResponse+arrayBuffer) ⇒ `Promise.<ArrayBuffer>`
  * [`.blob()`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileResponse+blob) ⇒ `Promise.<Blob>`
  * [`.text()`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileResponse+text) ⇒ `Promise.<string>`
  * [`.json()`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileResponse+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`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileResponse)

***

#### fileResponse.updateContentType() ⇒ \<code> void \</code>

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`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileResponse)

***

#### fileResponse.clone() ⇒ \<code> FileResponse \</code>

Clone the current FileResponse object.

**Kind**: instance method of [`FileResponse`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileResponse)\
**Returns**: `FileResponse` - A new FileResponse object with the same properties as the current object.

***

#### fileResponse.arrayBuffer() ⇒ \<code> Promise. < ArrayBuffer > \</code>

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`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..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() ⇒ \<code> Promise. < Blob > \</code>

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`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..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() ⇒ \<code> Promise. < string > \</code>

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`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..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() ⇒ \<code> Promise. < Object > \</code>

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`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..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`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub)

* [\~FileCache](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileCache)
  * [`new FileCache(path)`](https://huggingface.co/docs/transformers.js/api/utils/hub#new_module_utils/hub..FileCache_new)
  * [`.match(request)`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileCache+match) ⇒ `Promise.<(FileResponse|undefined)>`
  * [`.put(request, response)`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileCache+put) ⇒ `Promise.<void>`

***

#### new FileCache(path)

Instantiate a `FileCache` object.

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

***

#### fileCache.match(request) ⇒ \<code> Promise. < (FileResponse|undefined) > \</code>

Checks whether the given request is in the cache.

**Kind**: instance method of [`FileCache`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileCache)

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

***

#### fileCache.put(request, response) ⇒ \<code> Promise. < void > \</code>

Adds the given response to the cache.

**Kind**: instance method of [`FileCache`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub..FileCache)

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

***

### utils/hub\~isValidHttpUrl(string, \[validHosts]) ⇒ \<code> boolean \</code>

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

**Kind**: inner method of [`utils/hub`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_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) ⇒ \<code> null \</code>

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

**Kind**: inner method of [`utils/hub`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_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) ⇒ \<code> Promise. < (FileResponse|Response|undefined) > \</code>

**Kind**: inner method of [`utils/hub`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_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) ⇒ \<code> Promise. < Uint8Array > \</code>

Read and track progress when reading a Response object

**Kind**: inner method of [`utils/hub`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_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) ⇒ \<code> string \</code>

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

**Kind**: inner method of [`utils/hub`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub)\
**Returns**: `string` - A string representing the joined path.

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

***

### utils/hub\~PretrainedOptions : \<code> Object \</code>

Options for loading a pretrained model.

**Kind**: inner typedef of [`utils/hub`](https://huggingface.co/docs/transformers.js/api/utils/hub#module_utils/hub)\
**Properties**

| Name                  | Type       | Default    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------- | ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \[quantized]          | `boolean`  | `true`     | Whether to load the 8-bit quantized version of the model (only applicable when loading model files).                                                                                                                                                                                                                                                                                                                                                                         |
| \[progress\_callback] | `function` |            | If specified, this function will be called during model construction, to provide the user with progress updates.                                                                                                                                                                                                                                                                                                                                                             |
| \[config]             | `Object`   |            | <p>Configuration for the model to use instead of an automatically loaded configuration. Configuration can be automatically loaded when:</p><ul><li>The model is a model provided by the library (loaded with the <em>model id</em> string of a pretrained model).</li><li>The model is loaded by supplying a local directory as <code>pretrained\_model\_name\_or\_path</code> and a configuration JSON file named <em>config.json</em> is found in the directory.</li></ul> |
| \[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.                                                                                                                                                                                                                                                                                                                                          |
| \[local\_files\_only] | `boolean`  | `false`    | Whether or not to only look at local files (e.g., not try downloading the model).                                                                                                                                                                                                                                                                                                                                                                                            |
| \[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 boincai.com, so `revision` can be any identifier allowed by git. NOTE: This setting is ignored for local requests.                                                                                                                                                                                         |
| \[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.                                                                                                                                                                                                                                                                                                                                          |