notdiamond 2.0.0-rc2 → 2.0.0-rc4

package/src/resources/model-router.ts

@@ -0,0 +1,356 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as AdaptAPI from './prompt/adapt';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+export class ModelRouter extends APIResource {
+  /**
+   * Openhands Model Select
+   *
+   * @example
+   * ```ts
+   * const response = await client.modelRouter.openHandsSelect({
+   *   llm_providers: [
+   *     { model: 'gpt-4o', provider: 'openai' },
+   *     {
+   *       model: 'claude-sonnet-4-5-20250929',
+   *       provider: 'anthropic',
+   *     },
+   *     { model: 'gemini-1.5-pro', provider: 'google' },
+   *   ],
+   *   messages: [
+   *     {
+   *       content: 'You are a helpful assistant.',
+   *       role: 'system',
+   *     },
+   *     { content: 'Explain quantum computing', role: 'user' },
+   *   ],
+   * });
+   * ```
+   */
+  openHandsSelect(body: ModelRouterOpenHandsSelectParams, options?: RequestOptions): APIPromise<unknown> {
+    return this._client.post('/v2/modelRouter/openHandsRouter', { body, ...options });
+  }
+
+  /**
+   * Select the optimal LLM to handle your query based on Not Diamond's routing
+   * algorithm.
+   *
+   * This endpoint analyzes your messages and returns the best-suited model from your
+   * specified providers. The router considers factors like query complexity, model
+   * capabilities, cost, and latency based on your preferences.
+   *
+   * **Key Features:**
+   *
+   * - Intelligent routing across multiple LLM providers
+   * - Support for custom routers trained on your evaluation data
+   * - Optional cost/latency optimization
+   * - Function calling support for compatible models
+   * - Privacy-preserving content hashing
+   *
+   * **Usage:**
+   *
+   * 1. Pass your messages in OpenAI format (array of objects with 'role' and
+   *    'content')
+   * 2. Specify which LLM providers you want to route between
+   * 3. Optionally provide a preference_id for personalized routing
+   * 4. Receive a recommended model and session_id
+   * 5. Use the session_id to submit feedback and improve routing
+   *
+   * **Related Endpoints:**
+   *
+   * - `POST /v2/preferences/userPreferenceCreate` - Create a preference ID for
+   *   personalized routing
+   * - `POST /v2/report/metrics/feedback` - Submit feedback on routing decisions
+   * - `POST /v2/pzn/trainCustomRouter` - Train a custom router on your evaluation
+   *   data
+   *
+   * @example
+   * ```ts
+   * const response = await client.modelRouter.selectModel({
+   *   llm_providers: [
+   *     { provider: 'openai', model: 'gpt-4o' },
+   *     {
+   *       provider: 'anthropic',
+   *       model: 'claude-sonnet-4-5-20250929',
+   *     },
+   *     { provider: 'google', model: 'gemini-1.5-pro' },
+   *   ],
+   *   messages: [
+   *     {
+   *       role: 'system',
+   *       content: 'You are a helpful assistant.',
+   *     },
+   *     {
+   *       role: 'user',
+   *       content: 'Explain quantum computing in simple terms',
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  selectModel(
+    params: ModelRouterSelectModelParams,
+    options?: RequestOptions,
+  ): APIPromise<ModelRouterSelectModelResponse> {
+    const { type, ...body } = params;
+    return this._client.post('/v2/modelRouter/modelSelect', { query: { type }, body, ...options });
+  }
+}
+
+export type ModelRouterOpenHandsSelectResponse = unknown;
+
+/**
+ * Response from model selection endpoint.
+ */
+export interface ModelRouterSelectModelResponse {
+  /**
+   * List containing the selected provider
+   */
+  providers: Array<ModelRouterSelectModelResponse.Provider>;
+
+  /**
+   * Unique session ID for this routing decision
+   */
+  session_id: string;
+}
+
+export namespace ModelRouterSelectModelResponse {
+  /**
+   * Selected LLM provider information from model selection endpoints.
+   *
+   * Part of ModelSelectResponse. Contains the provider and model that Not Diamond's
+   * routing algorithm selected as optimal for your query. Use these values to make
+   * your LLM API call to the recommended model.
+   */
+  export interface Provider {
+    /**
+     * Model identifier for the selected model (e.g., 'gpt-4o',
+     * 'claude-3-opus-20240229')
+     */
+    model: string;
+
+    /**
+     * Provider name for the selected model (e.g., 'openai', 'anthropic', 'google')
+     */
+    provider: string;
+  }
+}
+
+export interface ModelRouterOpenHandsSelectParams {
+  /**
+   * List of LLM providers to route between. Specify at least one provider in format
+   * {provider, model}
+   */
+  llm_providers: Array<AdaptAPI.RequestProvider | ModelRouterOpenHandsSelectParams.OpenRouterProvider>;
+
+  /**
+   * Array of message objects in OpenAI format (with 'role' and 'content' keys)
+   */
+  messages: Array<{ [key: string]: string | Array<unknown> }> | string;
+
+  /**
+   * Whether to hash message content for privacy
+   */
+  hash_content?: boolean;
+
+  /**
+   * Maximum number of models to consider for routing. If not specified, considers
+   * all provided models
+   */
+  max_model_depth?: number | null;
+
+  /**
+   * Optimization metric for model selection
+   */
+  metric?: string;
+
+  /**
+   * Preference ID for personalized routing. Create one via POST
+   * /v2/preferences/userPreferenceCreate
+   */
+  preference_id?: string | null;
+
+  /**
+   * Previous session ID to link related requests
+   */
+  previous_session?: string | null;
+
+  /**
+   * OpenAI-format function calling tools
+   */
+  tools?: Array<{ [key: string]: unknown }> | null;
+
+  /**
+   * Optimization tradeoff strategy. Use 'cost' to prioritize cost savings or
+   * 'latency' to prioritize speed
+   */
+  tradeoff?: string | null;
+}
+
+export namespace ModelRouterOpenHandsSelectParams {
+  /**
+   * Model for specifying an LLM provider using OpenRouter format.
+   *
+   * Used in model routing requests when you want to specify providers using the
+   * OpenRouter naming convention (combined 'provider/model' format). This is an
+   * alternative to the standard RequestProvider which uses separate provider and
+   * model fields.
+   *
+   * **When to use:**
+   *
+   * - When working with OpenRouter-compatible systems
+   * - When you prefer the unified 'provider/model' format
+   * - For models accessed via OpenRouter proxy
+   */
+  export interface OpenRouterProvider {
+    /**
+     * OpenRouter model identifier in 'provider/model' format (e.g., 'openai/gpt-4o',
+     * 'anthropic/claude-sonnet-4-5-20250929')
+     */
+    model: string;
+
+    /**
+     * Maximum context length for the model (required for custom models)
+     */
+    context_length?: number | null;
+
+    /**
+     * Input token price per million tokens in USD (required for custom models)
+     */
+    input_price?: number | null;
+
+    /**
+     * Whether this is a custom model not in Not Diamond's supported model list
+     */
+    is_custom?: boolean;
+
+    /**
+     * Average latency in seconds (required for custom models)
+     */
+    latency?: number | null;
+
+    /**
+     * Output token price per million tokens in USD (required for custom models)
+     */
+    output_price?: number | null;
+  }
+}
+
+export interface ModelRouterSelectModelParams {
+  /**
+   * Body param: List of LLM providers to route between. Specify at least one
+   * provider in format {provider, model}
+   */
+  llm_providers: Array<AdaptAPI.RequestProvider | ModelRouterSelectModelParams.OpenRouterProvider>;
+
+  /**
+   * Body param: Array of message objects in OpenAI format (with 'role' and 'content'
+   * keys)
+   */
+  messages: Array<{ [key: string]: string | Array<unknown> }> | string;
+
+  /**
+   * Query param: Optional format type. Use 'openrouter' to accept and return
+   * OpenRouter-format model identifiers
+   */
+  type?: string | null;
+
+  /**
+   * Body param: Whether to hash message content for privacy
+   */
+  hash_content?: boolean;
+
+  /**
+   * Body param: Maximum number of models to consider for routing. If not specified,
+   * considers all provided models
+   */
+  max_model_depth?: number | null;
+
+  /**
+   * Body param: Optimization metric for model selection
+   */
+  metric?: string;
+
+  /**
+   * Body param: Preference ID for personalized routing. Create one via POST
+   * /v2/preferences/userPreferenceCreate
+   */
+  preference_id?: string | null;
+
+  /**
+   * Body param: Previous session ID to link related requests
+   */
+  previous_session?: string | null;
+
+  /**
+   * Body param: OpenAI-format function calling tools
+   */
+  tools?: Array<{ [key: string]: unknown }> | null;
+
+  /**
+   * Body param: Optimization tradeoff strategy. Use 'cost' to prioritize cost
+   * savings or 'latency' to prioritize speed
+   */
+  tradeoff?: string | null;
+}
+
+export namespace ModelRouterSelectModelParams {
+  /**
+   * Model for specifying an LLM provider using OpenRouter format.
+   *
+   * Used in model routing requests when you want to specify providers using the
+   * OpenRouter naming convention (combined 'provider/model' format). This is an
+   * alternative to the standard RequestProvider which uses separate provider and
+   * model fields.
+   *
+   * **When to use:**
+   *
+   * - When working with OpenRouter-compatible systems
+   * - When you prefer the unified 'provider/model' format
+   * - For models accessed via OpenRouter proxy
+   */
+  export interface OpenRouterProvider {
+    /**
+     * OpenRouter model identifier in 'provider/model' format (e.g., 'openai/gpt-4o',
+     * 'anthropic/claude-sonnet-4-5-20250929')
+     */
+    model: string;
+
+    /**
+     * Maximum context length for the model (required for custom models)
+     */
+    context_length?: number | null;
+
+    /**
+     * Input token price per million tokens in USD (required for custom models)
+     */
+    input_price?: number | null;
+
+    /**
+     * Whether this is a custom model not in Not Diamond's supported model list
+     */
+    is_custom?: boolean;
+
+    /**
+     * Average latency in seconds (required for custom models)
+     */
+    latency?: number | null;
+
+    /**
+     * Output token price per million tokens in USD (required for custom models)
+     */
+    output_price?: number | null;
+  }
+}
+
+export declare namespace ModelRouter {
+  export {
+    type ModelRouterOpenHandsSelectResponse as ModelRouterOpenHandsSelectResponse,
+    type ModelRouterSelectModelResponse as ModelRouterSelectModelResponse,
+    type ModelRouterOpenHandsSelectParams as ModelRouterOpenHandsSelectParams,
+    type ModelRouterSelectModelParams as ModelRouterSelectModelParams,
+  };
+}

package/src/resources/models.ts

@@ -36,6 +36,11 @@ export class Models extends APIResource {
    * **Caching:**
    *
    * - Response is cacheable for 1 hour (model list rarely changes)
+   *
+   * @example
+   * ```ts
+   * const models = await client.models.list();
+   * ```
    */
   list(
     query: ModelListParams | null | undefined = {},
@@ -46,50 +51,64 @@ export class Models extends APIResource {
 }
 
 /**
- * Response for models list endpoint.
+ * Response model for a single LLM model from GET /v2/models endpoint.
+ *
+ * Contains metadata about a supported text generation model including pricing,
+ * context limits, and availability information.
  */
-export interface ModelListResponse {
-  deprecated_models: Array<ModelListResponse.DeprecatedModel>;
-
-  models: Array<ModelListResponse.Model>;
-
-  total: number;
-}
-
-export namespace ModelListResponse {
+export interface Model {
   /**
-   * Response model for a single LLM provider.
+   * Maximum context window size in tokens
    */
-  export interface DeprecatedModel {
-    context_length: number;
-
-    input_price: number;
+  context_length: number;
 
-    model: string;
-
-    output_price: number;
-
-    provider: string;
+  /**
+   * Price per million input tokens in USD
+   */
+  input_price: number;
 
-    openrouter_model?: string | null;
-  }
+  /**
+   * Model identifier (e.g., 'gpt-4', 'claude-3-opus-20240229')
+   */
+  model: string;
 
   /**
-   * Response model for a single LLM provider.
+   * Price per million output tokens in USD
    */
-  export interface Model {
-    context_length: number;
+  output_price: number;
 
-    input_price: number;
+  /**
+   * Provider name (e.g., 'openai', 'anthropic', 'google')
+   */
+  provider: string;
 
-    model: string;
+  /**
+   * OpenRouter model identifier if available, null if not supported via OpenRouter
+   */
+  openrouter_model?: string | null;
+}
 
-    output_price: number;
+/**
+ * Response model for GET /v2/models endpoint.
+ *
+ * Returns a list of all supported text generation models with their metadata,
+ * separated into active and deprecated models.
+ */
+export interface ModelListResponse {
+  /**
+   * List of deprecated models that are no longer recommended but may still work
+   */
+  deprecated_models: Array<Model>;
 
-    provider: string;
+  /**
+   * List of active/supported text generation models with their metadata
+   */
+  models: Array<Model>;
 
-    openrouter_model?: string | null;
-  }
+  /**
+   * Total count of active models in the response
+   */
+  total: number;
 }
 
 export interface ModelListParams {
@@ -106,5 +125,9 @@ export interface ModelListParams {
 }
 
 export declare namespace Models {
-  export { type ModelListResponse as ModelListResponse, type ModelListParams as ModelListParams };
+  export {
+    type Model as Model,
+    type ModelListResponse as ModelListResponse,
+    type ModelListParams as ModelListParams,
+  };
 }

package/src/resources/preferences.ts

@@ -7,29 +7,6 @@ import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
 export class Preferences extends APIResource {
-  /**
-   * Get User Preference By Id
-   *
-   * @example
-   * ```ts
-   * const preference = await client.preferences.retrieve(
-   *   'preference_id',
-   *   { user_id: 'user_id', 'x-token': 'x-token' },
-   * );
-   * ```
-   */
-  retrieve(
-    preferenceID: string,
-    params: PreferenceRetrieveParams,
-    options?: RequestOptions,
-  ): APIPromise<unknown> {
-    const { user_id, 'x-token': xToken } = params;
-    return this._client.get(path`/v2/preferences/${user_id}/${preferenceID}`, {
-      ...options,
-      headers: buildHeaders([{ 'x-token': xToken }, options?.headers]),
-    });
-  }
-
   /**
    * Create a new preference ID for personalized LLM routing.
    *
@@ -58,30 +35,30 @@ export class Preferences extends APIResource {
    *
    * @example
    * ```ts
-   * const response =
-   *   await client.preferences.createUserPreference();
+   * const preference = await client.preferences.create();
    * ```
    */
-  createUserPreference(
-    body: PreferenceCreateUserPreferenceParams,
-    options?: RequestOptions,
-  ): APIPromise<PreferenceCreateUserPreferenceResponse> {
+  create(body: PreferenceCreateParams, options?: RequestOptions): APIPromise<PreferenceCreateResponse> {
     return this._client.post('/v2/preferences/userPreferenceCreate', { body, ...options });
   }
 
   /**
-   * Delete User Preference
+   * Get User Preference
    *
    * @example
    * ```ts
-   * const response =
-   *   await client.preferences.deleteUserPreference(
-   *     'preference_id',
-   *   );
+   * const preference = await client.preferences.retrieve(
+   *   'user_id',
+   *   { 'x-token': 'x-token' },
+   * );
    * ```
    */
-  deleteUserPreference(preferenceID: string, options?: RequestOptions): APIPromise<unknown> {
-    return this._client.delete(path`/v2/preferences/userPreferenceDelete/${preferenceID}`, options);
+  retrieve(userID: string, params: PreferenceRetrieveParams, options?: RequestOptions): APIPromise<unknown> {
+    const { 'x-token': xToken } = params;
+    return this._client.get(path`/v2/preferences/${userID}`, {
+      ...options,
+      headers: buildHeaders([{ 'x-token': xToken }, options?.headers]),
+    });
   }
 
   /**
@@ -89,57 +66,71 @@ export class Preferences extends APIResource {
    *
    * @example
    * ```ts
-   * const response =
-   *   await client.preferences.updateUserPreference({
-   *     preference_id: 'preference_id',
-   *   });
+   * const preference = await client.preferences.update({
+   *   preference_id: 'preference_id',
+   * });
    * ```
    */
-  updateUserPreference(
-    body: PreferenceUpdateUserPreferenceParams,
-    options?: RequestOptions,
-  ): APIPromise<unknown> {
+  update(body: PreferenceUpdateParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.put('/v2/preferences/userPreferenceUpdate', { body, ...options });
   }
-}
 
-export type PreferenceRetrieveResponse = unknown;
+  /**
+   * Delete User Preference
+   *
+   * @example
+   * ```ts
+   * const preference = await client.preferences.delete(
+   *   'preference_id',
+   * );
+   * ```
+   */
+  delete(preferenceID: string, options?: RequestOptions): APIPromise<unknown> {
+    return this._client.delete(path`/v2/preferences/userPreferenceDelete/${preferenceID}`, options);
+  }
+}
 
 /**
- * Response from preference creation endpoint.
+ * Response model for POST /v2/preferences/userPreferenceCreate endpoint.
+ *
+ * Returns the newly created preference ID which can be used to enable personalized
+ * LLM routing. Store this ID and include it in subsequent model_select() calls to
+ * activate personalized routing based on your feedback and usage patterns.
+ *
+ * **Next steps after creation:**
+ *
+ * 1. Use the preference_id in POST /v2/modelRouter/modelSelect requests
+ * 2. Submit feedback on routing decisions to improve accuracy
+ * 3. Optionally train a custom router using your evaluation data
  */
-export interface PreferenceCreateUserPreferenceResponse {
+export interface PreferenceCreateResponse {
   /**
-   * The newly created preference ID. Use this in model_select() calls for
-   * personalized routing
+   * Unique identifier for the newly created preference. Use this in the
+   * 'preference_id' parameter of model_select() calls to enable personalized routing
    */
   preference_id: string;
 }
 
-export type PreferenceDeleteUserPreferenceResponse = unknown;
+export type PreferenceRetrieveResponse = unknown;
 
-export type PreferenceUpdateUserPreferenceResponse = unknown;
+export type PreferenceUpdateResponse = unknown;
 
-export interface PreferenceRetrieveParams {
-  /**
-   * Path param:
-   */
-  user_id: string;
+export type PreferenceDeleteResponse = unknown;
 
+export interface PreferenceCreateParams {
   /**
-   * Header param:
+   * Optional name for the preference. If not provided, an auto-generated timestamp
+   * will be used. Use descriptive names like 'Production API' or 'Customer Support
+   * Bot' for easy identification
    */
-  'x-token': string;
+  name?: string | null;
 }
 
-export interface PreferenceCreateUserPreferenceParams {
-  /**
-   * Optional name for the preference
-   */
-  name?: string | null;
+export interface PreferenceRetrieveParams {
+  'x-token': string;
 }
 
-export interface PreferenceUpdateUserPreferenceParams {
+export interface PreferenceUpdateParams {
   preference_id: string;
 
   name?: string | null;
@@ -147,12 +138,12 @@ export interface PreferenceUpdateUserPreferenceParams {
 
 export declare namespace Preferences {
   export {
+    type PreferenceCreateResponse as PreferenceCreateResponse,
     type PreferenceRetrieveResponse as PreferenceRetrieveResponse,
-    type PreferenceCreateUserPreferenceResponse as PreferenceCreateUserPreferenceResponse,
-    type PreferenceDeleteUserPreferenceResponse as PreferenceDeleteUserPreferenceResponse,
-    type PreferenceUpdateUserPreferenceResponse as PreferenceUpdateUserPreferenceResponse,
+    type PreferenceUpdateResponse as PreferenceUpdateResponse,
+    type PreferenceDeleteResponse as PreferenceDeleteResponse,
+    type PreferenceCreateParams as PreferenceCreateParams,
     type PreferenceRetrieveParams as PreferenceRetrieveParams,
-    type PreferenceCreateUserPreferenceParams as PreferenceCreateUserPreferenceParams,
-    type PreferenceUpdateUserPreferenceParams as PreferenceUpdateUserPreferenceParams,
+    type PreferenceUpdateParams as PreferenceUpdateParams,
   };
 }