Restructure as hints, a list of records

Author: jspahrsummers

docs/spec/sampling.md

@@ -37,7 +37,7 @@ Message content can be either text or images, allowing for multimodal interactio
 
 ### Model Preferences
 
-Servers can express preferences for model selection using the `ModelPreferences` object. This allows servers to indicate priorities for factors like cost, speed, and intelligence, as well as provide name hints for specific models.
+Servers can express preferences for model selection using the `ModelPreferences` object. This allows servers to indicate priorities for factors like cost, speed, and intelligence, as well as provide hints for specific models.
 
 ## Use Cases
 
@@ -61,7 +61,11 @@ A server requesting a chat response with model preferences:
   "maxTokens": 100,
   "temperature": 0.7,
   "modelPreferences": {
-    "nameHints": ["claude-3-sonnet"],
+    "hints": [
+      {
+        "name": "claude-3-sonnet"
+      }
+    ],
     "intelligencePriority": 0.8,
     "speedPriority": 0.5
   }
@@ -93,7 +97,14 @@ A server requesting analysis of an image:
   ],
   "maxTokens": 200,
   "modelPreferences": {
-    "nameHints": ["claude-3-opus", "claude-3-sonnet"],
+    "hints": [
+      {
+        "name": "claude-3-opus"
+      },
+      {
+        "name": "claude-3-sonnet"
+      }
+    ],
     "intelligencePriority": 1.0
   }
 }
@@ -168,7 +179,14 @@ Example:
     "temperature": 0.7,
     "includeContext": "none",
     "modelPreferences": {
-      "nameHints": ["claude-3-sonnet", "claude-3-opus"],
+      "hints": [
+        {
+          "name": "claude-3-sonnet"
+        },
+        {
+          "name": "claude-3-opus"
+        }
+      ],
       "intelligencePriority": 0.9,
       "speedPriority": 0.6
     }

schema/schema.json

@@ -907,19 +907,19 @@
                     "minimum": 0,
                     "type": "number"
                 },
+                "hints": {
+                    "description": "Optional string hints to use for model selection. How these hints are\ninterpreted depends on the key(s) in each record:\n\n- If the record contains a `name` key:\n   - The client SHOULD treat this as a substring of a model name; for example:\n       - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022`\n       - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc.\n       - `claude` should match any Claude model\n   - The client MAY also map the string to a different provider's model name or a different model family, as long as it fills a similar niche; for example:\n       - `gemini-1.5-flash` could match `claude-3-haiku-20240307`\n\nAll other keys are currently left unspecified by the spec and are up to the\nclient to interpret.\n\nIf multiple hints are specified, the client MUST evaluate them in order\n(such that the first match is taken).\n\nThe client SHOULD prioritize these hints over the numeric priorities, but\nMAY still use the priorities to select from ambiguous matches.",
+                    "items": {
+                        "$ref": "#/definitions/Record<string,string>"
+                    },
+                    "type": "array"
+                },
                 "intelligencePriority": {
                     "description": "How much to prioritize intelligence and capabilities when selecting a\nmodel. A value of 0 means intelligence is not important, while a value of 1\nmeans intelligence is the most important factor.",
                     "maximum": 1,
                     "minimum": 0,
                     "type": "number"
                 },
-                "nameHints": {
-                    "description": "Optional string hints to use for model selection.\n\nThe client SHOULD treat these as substrings of model names; for example:\n - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022`\n - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc.\n - `claude` should match any Claude model\n\nThe client MAY also map hints to a different provider's model or a\ndifferent model family, as long as it fills a similar niche; for example:\n - `gemini-1.5-flash` could match `claude-3-haiku-20240307`\n\nIf multiple hints are specified, the client MUST evaluate them in order\n(such that the first match is taken).\n\nThe client SHOULD prioritize these string hints over the numeric\npriorities, but MAY still use the priorities to select from ambiguous\nmatches.",
-                    "items": {
-                        "type": "string"
-                    },
-                    "type": "array"
-                },
                 "speedPriority": {
                     "description": "How much to prioritize sampling speed (latency) when selecting a model. A\nvalue of 0 means speed is not important, while a value of 1 means speed is\nthe most important factor.",
                     "maximum": 1,
@@ -1196,6 +1196,9 @@
             ],
             "type": "object"
         },
+        "Record<string,string>": {
+            "type": "object"
+        },
         "Request": {
             "properties": {
                 "method": {

schema/schema.ts

@@ -747,32 +747,34 @@ export interface ImageContent {
  * faster but less capable, others are more capable but more expensive, and so
  * on. This interface allows servers to express their priorities across multiple
  * dimensions to help clients make an appropriate selection for their use case.
- * 
+ *
  * These preferences are always advisory. The client MAY ignore them. It is also
  * up to the client to decide how to interpret these preferences and how to
  * balance them against other considerations.
  */
 export interface ModelPreferences {
   /**
-   * Optional string hints to use for model selection.
+   * Optional string hints to use for model selection. How these hints are
+   * interpreted depends on the key(s) in each record:
    *
-   * The client SHOULD treat these as substrings of model names; for example:
-   *  - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022`
-   *  - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc.
-   *  - `claude` should match any Claude model
+   * - If the record contains a `name` key:
+   *    - The client SHOULD treat this as a substring of a model name; for example:
+   *        - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022`
+   *        - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc.
+   *        - `claude` should match any Claude model
+   *    - The client MAY also map the string to a different provider's model name or a different model family, as long as it fills a similar niche; for example:
+   *        - `gemini-1.5-flash` could match `claude-3-haiku-20240307`
    *
-   * The client MAY also map hints to a different provider's model or a
-   * different model family, as long as it fills a similar niche; for example:
-   *  - `gemini-1.5-flash` could match `claude-3-haiku-20240307`
+   * All other keys are currently left unspecified by the spec and are up to the
+   * client to interpret.
    *
    * If multiple hints are specified, the client MUST evaluate them in order
    * (such that the first match is taken).
    *
-   * The client SHOULD prioritize these string hints over the numeric
-   * priorities, but MAY still use the priorities to select from ambiguous
-   * matches.
+   * The client SHOULD prioritize these hints over the numeric priorities, but
+   * MAY still use the priorities to select from ambiguous matches.
    */
-  nameHints?: string[];
+  hints?: Record<"name" | string, string>[];
 
   /**
    * How much to prioritize cost when selecting a model. A value of 0 means cost