Merge pull request #15 from hypermodeAI/mjp/manifest-v2

Update model and host docs for new manifest format

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "chrischinchilla.vale-vscode",
+    "esbenp.prettier-vscode",
+    "streetsidesoftware.code-spell-checker",
+    "unifiedjs.vscode-mdx"
+  ]
+}

.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"]
+}

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,14 +58,17 @@ 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:
 
 ```bash
 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.

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.
+
+<Note>You must include either a `baseUrl` or an `endpoint` (not both).</Note>
+
+<Warning>
+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.
+
+</Warning>
+
 ## Properties
 
-<ResponseField name="name" type="string" required>
-  Internal name of your host. Used for indicating the host of a model or for a
-  connection.
+<ResponseField name="baseUrl" type="string" required>
+  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._
+
 </ResponseField>
 
 <ResponseField name="endpoint" type="string" required>
-  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._
+
+</ResponseField>
+
+<ResponseField name="headers" type="object">
+  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.
+
+  <Accordion title="Examples">
+
+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)}}"
+}
+```
+
+  </Accordion>
+</ResponseField>
+
+<ResponseField name="queryParameters" type="object">
+  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.
+
+  <Accordion title="Example">
+
+This example specifies a query parameter named `key` provided by a secret named `API_KEY`:
+
+```json
+"queryParameters": {
+  "key": "{{API_KEY}}"
+}
+```
+
+  </Accordion>
 </ResponseField>

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.
 
-<ResponseField name="name" type="string" required>
-  Internal name of your AI model. Used for indicating the model to use in an API
-  call.
-</ResponseField>
+## Properties
 
 <ResponseField name="task" type="string" required>
-  Training intent of model, such as `classification` or `embedding`.
+  Training intent of the model. Currently, must be one of: `classification`,
+  `embedding`, or `generation`.
 </ResponseField>
 
 <ResponseField name="sourceModel" type="string" required>
-  Relative path of model within provider.
+  Original relative path of the model within the provider's repository.
 </ResponseField>
 
 <ResponseField name="provider" type="string" required>
-  Source location of model, such as `hugging-face` or `openai`.
+  Organization or directory that provided the source model, such as
+  `hugging-face` or `openai`.
 </ResponseField>
 
 <ResponseField name="host" type="string" required>
-  Runtime provider of model.
-  <Expandable title="host types">
-    <ResponseField name="hypermode" type="string">
-      Dynamically deployed models on Hypermode.
-    </ResponseField>
-    <ResponseField name="custom" type="string">
-      Fine-tuned models on Hypermode.
-    </ResponseField>
-    <ResponseField name="..." type="string">
-      Name of a project-defined [host](/define-hosts).
-    </ResponseField>
-  </Expandable>
+  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.
+
 </ResponseField>
 
 ## 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.