diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 00000000..569da39a
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,8 @@
+{
+ "recommendations": [
+ "chrischinchilla.vale-vscode",
+ "esbenp.prettier-vscode",
+ "streetsidesoftware.code-spell-checker",
+ "unifiedjs.vscode-mdx"
+ ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 00000000..9f62ddd9
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,15 @@
+{
+ "editor.formatOnSave": true,
+ "files.insertFinalNewline": true,
+ "files.trimFinalNewlines": true,
+ "[json]": {
+ "editor.defaultFormatter": "esbenp.prettier-vscode"
+ },
+ "[jsonc]": {
+ "editor.defaultFormatter": "esbenp.prettier-vscode"
+ },
+ "[mdx]": {
+ "editor.defaultFormatter": "unifiedjs.vscode-mdx"
+ },
+ "cSpell.enableFiletypes": ["mdx"]
+}
diff --git a/README.md b/README.md
index c621b240..bcaa6068 100644
--- a/README.md
+++ b/README.md
@@ -28,16 +28,20 @@ npm i -g mintlify
Validate alignment of changes with style guide.
+MacOS:
+
```bash
-npm i -D @ocular-d/vale-bin
+brew install vale
```
+[Full Installation Docs](https://vale.sh/docs/vale-cli/installation/)
+
### Trunk CLI
Format and lint changes for easy merging.
```bash
-npm i -D @trunkio/launcher
+npm i -g @trunkio/launcher
```
## Writing
@@ -54,7 +58,7 @@ mintlify dev
Consistency is important in any documentation experience. Beyond Markdown’s opinionated structure, we adhere to a consistent style for Hypermode.
-We have adopted [Google’s Developer Documentation Style Guide](https://developers.google.com/style/) as a baseline, with Hypermode-specific terms [stored in a vocabulary file](https://github.com/hypermodeAI/docs/blob/9b3f5c88a4274c549d65288339a4f7c5a7d6ae2a/styles/config/vocabularies/general/accept.txt).
+We have adopted [Google’s Developer Documentation Style Guide](https://developers.google.com/style/) as a baseline, with Hypermode-specific terms [stored in a vocabulary file](./styles/config/vocabularies/general/accept.txt).
[Vale](https://vale.sh/) has been implemented in the repo for easy alignment. Vale is implemented within CI/CD, but also executable locally with:
@@ -62,6 +66,9 @@ We have adopted [Google’s Developer Documentation Style Guide](https://develop
vale --glob='*.{mdx}' *
```
+A [Vale VS Code extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) is also available,
+and is included in the recommended extensions for this repo.
+
### Iconography
When icons are required, select from [Font Awesome](https://fontawesome.com/icons)’s catalog for easy rendering with Mintlify.
@@ -81,3 +88,10 @@ To run lint checks, run:
```bash
trunk check # appending --all will run checks beyond changes on the current branch
```
+
+Note that Trunk also has a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Trunk.io) you can install.
+
+However, when installing it please be aware of the `trunk.autoInit` setting, which is `true` (enabled) by default
+This controls whether to auto-initialize trunk in non-trunk repositories - meaning _any_ folder you open with VS Code will get
+configured with a `.trunk` subfolder, and will start using Trunk. You should probably set this to `false` in your VS Code user settings,
+to not interfere with other projects you may be working on.
diff --git a/define-hosts.mdx b/define-hosts.mdx
index 21014320..cac61297 100644
--- a/define-hosts.mdx
+++ b/define-hosts.mdx
@@ -3,27 +3,107 @@ title: Define Hosts
description: "Securely connect to your data"
---
-Hosts establish connectivity for AI models and other external endpoints. The [project manifest](/manifest) allows you to define hosts for secure access from within a function.
+Hosts establish connectivity for AI models and other external endpoints.
+The `hosts` object in the [project manifest](/manifest) allows you to define hosts, for secure access from within a function.
```json hypermode.json
{
- "hosts": [
- {
- "name": "openai",
- "endpoint": "https://api.openai.com/v1",
- "authHeader": "Authorization"
+ "hosts": {
+ "openai": {
+ "baseUrl": "https://api.openai.com/",
+ "headers": {
+ "Authorization": "Bearer {{API_KEY}}"
+ }
}
- ]
+ }
}
```
+Each host requires a unique name, specified as a key, containing only alphanumeric characters and hyphens.
+
+You must include either a `baseUrl` or an `endpoint` (not both).
+
+
+Don't include secrets directly in the manifest!
+
+If your host requires authentication, you can specify `headers` and/or `queryParameters` properties.
+Those values can include _placeholders_ which resolve to their respective secrets at runtime.
+Set the actual secrets via the Hypermode Console, where they're securely stored until needed.
+
+
+
## Properties
-
- Internal name of your host. Used for indicating the host of a model or for a
- connection.
+
+ Base URL for connections to the host.
+ - Must end with a trailing slash.
+ - May contain path segments if necessary.
+
+Example: `"https://api.example.com/v1/"`
+
+_If providing the entire URL, use the `endpoint` field instead._
+
- URL and base path for connections to the host.
+ Full URL endpoint for connections to the host.
+
+Example: `"https://models.example.com/v1/classifier"`
+
+_If providing only the base of the URL, use the `baseUrl` field instead._
+
+
+
+
+ If provided, requests to the host include these headers. Each key-value pair is a header name and value.
+
+Values may include variables using the `{{VARIABLE}}` template syntax, which resolve at runtime to secrets
+provided for each host, via the Hypermode Console.
+
+
+
+This example specifies a header named `Authorization` that uses the `Bearer` scheme. A secret named `AUTH_TOKEN` provides the token:
+
+```json
+"headers": {
+ "Authorization": "Bearer {{AUTH_TOKEN}}"
+}
+```
+
+This example specifies a header named `X-API-Key` provided by a secret named `API_KEY`:
+
+```json
+"headers": {
+ "X-API-Key": "{{API_KEY}}"
+}
+```
+
+You can use a special syntax for hosts that require [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
+In this example, secrets named `USERNAME` and `PASSWORD` combined and then are base64-encoded to form a compliant `Authorization` header value:
+
+```json
+"headers": {
+ "Authorization": "Basic {{base64(USERNAME:PASSWORD)}}"
+}
+```
+
+
+
+
+
+ If provided, requests to the host include these query parameters, appended to the URL. Each key-value pair is a parameter name and value.
+
+Values may include variables using the `{{VARIABLE}}` template syntax, which resolve at runtime to secrets provided for each host, via the Hypermode Console.
+
+
+
+This example specifies a query parameter named `key` provided by a secret named `API_KEY`:
+
+```json
+"queryParameters": {
+ "key": "{{API_KEY}}"
+}
+```
+
+
diff --git a/define-models.mdx b/define-models.mdx
index c13dc87b..b1b4e323 100644
--- a/define-models.mdx
+++ b/define-models.mdx
@@ -3,56 +3,50 @@ title: Define Models
description: "Try a new model with a few lines of code"
---
-AI models are a core resource for inferencing. The [project manifest](/manifest) allows you to easily define models whether hosted by Hypermode or another host.
+AI models are a core resource for inferencing.
+The `models` object in the [project manifest](/manifest) allows you to easily define models, whether hosted by Hypermode or another host.
```json hypermode.json
{
- "models": [
- {
- "name": "sentiment-classifier",
+ "models": {
+ "sentiment-classifier": {
"task": "classification",
"sourceModel": "distilbert/distilbert-base-uncased-finetuned-sst-2-english",
"provider": "hugging-face",
"host": "hypermode"
}
- ]
+ }
}
```
-## Properties
+Each model requires a unique name, specified as a key, containing only alphanumeric characters and hyphens.
-
- Internal name of your AI model. Used for indicating the model to use in an API
- call.
-
+## Properties
- Training intent of model, such as `classification` or `embedding`.
+ Training intent of the model. Currently, must be one of: `classification`,
+ `embedding`, or `generation`.
- Relative path of model within provider.
+ Original relative path of the model within the provider's repository.
- Source location of model, such as `hugging-face` or `openai`.
+ Organization or directory that provided the source model, such as
+ `hugging-face` or `openai`.
- Runtime provider of model.
-
-
- Dynamically deployed models on Hypermode.
-
-
- Fine-tuned models on Hypermode.
-
-
- Name of a project-defined [host](/define-hosts).
-
-
+ Host for the model instance.
+
+- Specify `"hypermode"` for models that are automatically deployed by Hypermode.
+- Otherwise, specify a name that matches a host defined in the [`hosts`](/define-hosts) section of the manifest.
+
## Auto-deployed models
-When using `hugging-face` as the `provider` and `hypermode` as the `host`, Hypermode automatically deploys a dedicated instance of the defined `sourceModel` when deploying your project. Your project's functions securely connect to the hosted model, with no further configuration required.
+When using `hugging-face` as the `provider` and `hypermode` as the `host`, Hypermode automatically deploys a dedicated
+instance of the defined `sourceModel` when deploying your project. Your project's functions securely connect to the
+hosted model, with no further configuration required.