# 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.                                                                                                                                                                                                                                                                                                                                          |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://boinc-ai.gitbook.io/transformers.js/api-reference/utilities/hub.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.