telnyx 7.22.0 → 7.23.0

package/src/resources/ai/audio.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
+import * as AudioAPI from './audio';
 import { APIPromise } from '../../core/api-promise';
 import { type Uploadable } from '../../core/uploads';
 import { RequestOptions } from '../../internal/request-options';
@@ -27,12 +28,56 @@ export class Audio extends APIResource {
   }
 }
 
+/**
+ * Word-level timing detail. Only present when using a `deepgram/*` model with
+ * `model_config` options that enable word timestamps.
+ */
+export interface AudioTranscriptionResponseWord {
+  /**
+   * End time of the word in seconds.
+   */
+  end: number;
+
+  /**
+   * Start time of the word in seconds.
+   */
+  start: number;
+
+  /**
+   * The transcribed word.
+   */
+  word: string;
+
+  /**
+   * Confidence score for the word (0.0 to 1.0).
+   */
+  confidence?: number;
+
+  /**
+   * The transcribed word with punctuation and capitalisation applied. Only present
+   * when `punctuate` or `smart_format` is enabled via `model_config`.
+   */
+  punctuated_word?: string;
+
+  /**
+   * Speaker index. Only present when diarization is enabled via `model_config`.
+   */
+  speaker?: number;
+
+  /**
+   * Confidence score for the speaker assignment (0.0 to 1.0). Only present when
+   * diarization is enabled via `model_config`.
+   */
+  speaker_confidence?: number;
+}
+
 /**
  * Response fields vary by model. `distil-whisper/distil-large-v2` returns `text`,
  * `duration`, and `segments` in `verbose_json` mode.
- * `openai/whisper-large-v3-turbo` returns `text` only. `deepgram/nova-3` returns
- * `text` and, depending on `model_config`, may include `words` with per-word
- * timestamps and speaker labels.
+ * `openai/whisper-large-v3-turbo` returns `text` only. The `deepgram/*` models
+ * return `text` and, depending on `model_config`, may include `words` with
+ * per-word timestamps and speaker labels. The Parakeet models
+ * (`nvidia/parakeet-v3`, `omi-health/omi-med-stt-v1`) return `text` only.
  */
 export interface AudioTranscribeResponse {
   /**
@@ -42,23 +87,25 @@ export interface AudioTranscribeResponse {
 
   /**
    * The duration of the audio file in seconds. Returned by
-   * `distil-whisper/distil-large-v2` and `deepgram/nova-3` when `response_format` is
-   * `verbose_json`. Not returned by `openai/whisper-large-v3-turbo`.
+   * `distil-whisper/distil-large-v2` and the `deepgram/*` models when
+   * `response_format` is `verbose_json`. Not returned by
+   * `openai/whisper-large-v3-turbo`.
    */
   duration?: number;
 
   /**
    * Segments of the transcribed text and their corresponding details. Returned by
-   * `distil-whisper/distil-large-v2` when `response_format` is `verbose_json`. Not
-   * returned by `openai/whisper-large-v3-turbo`.
+   * `distil-whisper/distil-large-v2` and the `deepgram/*` models when
+   * `response_format` is `verbose_json`; Deepgram segments also carry nested `words`
+   * and `speakers`. Not returned by `openai/whisper-large-v3-turbo`.
    */
   segments?: Array<AudioTranscribeResponse.Segment>;
 
   /**
-   * Word-level timestamps and optional speaker labels. Only returned by
-   * `deepgram/nova-3` when word-level output is enabled via `model_config`.
+   * Word-level timestamps and optional speaker labels. Only returned by the
+   * `deepgram/*` models when word-level output is enabled via `model_config`.
    */
-  words?: Array<AudioTranscribeResponse.Word>;
+  words?: Array<AudioTranscriptionResponseWord>;
 }
 
 export namespace AudioTranscribeResponse {
@@ -82,37 +129,18 @@ export namespace AudioTranscribeResponse {
      * Text content of the segment.
      */
     text: string;
-  }
-
-  /**
-   * Word-level timing detail. Only present when using `deepgram/nova-3` with
-   * `model_config` options that enable word timestamps.
-   */
-  export interface Word {
-    /**
-     * End time of the word in seconds.
-     */
-    end: number;
-
-    /**
-     * Start time of the word in seconds.
-     */
-    start: number;
-
-    /**
-     * The transcribed word.
-     */
-    word: string;
 
     /**
-     * Confidence score for the word (0.0 to 1.0).
+     * Speaker indices heard in this segment. Returned by the `deepgram/*` models when
+     * `diarize` is enabled via `model_config`.
      */
-    confidence?: number;
+    speakers?: Array<number>;
 
     /**
-     * Speaker index. Only present when diarization is enabled via `model_config`.
+     * Word-level timing detail for this segment. Returned by the `deepgram/*` models
+     * when word-level output is enabled via `model_config`.
      */
-    speaker?: number;
+    words?: Array<AudioAPI.AudioTranscriptionResponseWord>;
   }
 }
 
@@ -120,37 +148,56 @@ export interface AudioTranscribeParams {
   /**
    * ID of the model to use. `distil-whisper/distil-large-v2` is lower latency but
    * English-only. `openai/whisper-large-v3-turbo` is multi-lingual but slightly
-   * higher latency. `deepgram/nova-3` supports English variants (en, en-US, en-GB,
-   * en-AU, en-NZ, en-IN) and only accepts mp3/wav files.
+   * higher latency. The `deepgram/*` models only accept mp3/wav files:
+   * `deepgram/nova-3` covers ~49 languages plus `multi` and `deepgram/nova-2` covers
+   * ~33, while the `-medical` variants are tuned for clinical vocabulary and accept
+   * English only (`en` and its regional variants, e.g. `en-US`, `en-GB`).
+   * `nvidia/parakeet-v3` is multilingual with automatic language detection;
+   * `omi-health/omi-med-stt-v1` is a medical model, English only.
    */
-  model: 'distil-whisper/distil-large-v2' | 'openai/whisper-large-v3-turbo' | 'deepgram/nova-3';
+  model:
+    | 'distil-whisper/distil-large-v2'
+    | 'openai/whisper-large-v3-turbo'
+    | 'deepgram/nova-2'
+    | 'deepgram/nova-2-medical'
+    | 'deepgram/nova-3'
+    | 'deepgram/nova-3-medical'
+    | 'nvidia/parakeet-v3'
+    | 'omi-health/omi-med-stt-v1';
 
   /**
    * The audio file object to transcribe, in one of these formats: flac, mp3, mp4,
    * mpeg, mpga, m4a, ogg, wav, or webm. File uploads are limited to 100 MB. Cannot
-   * be used together with `file_url`. Note: `deepgram/nova-3` only supports mp3 and
-   * wav formats.
+   * be used together with `file_url`. Note: the `deepgram/*` models only support mp3
+   * and wav formats.
    */
   file?: Uploadable;
 
   /**
    * Link to audio file in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a,
    * ogg, wav, or webm. Support for hosted files is limited to 100MB. Cannot be used
-   * together with `file`. Note: `deepgram/nova-3` only supports mp3 and wav formats.
+   * together with `file`. Note: the `deepgram/*` models only support mp3 and wav
+   * formats.
    */
   file_url?: string;
 
   /**
-   * The language of the audio to be transcribed. For `deepgram/nova-3`, only English
-   * variants are supported: `en`, `en-US`, `en-GB`, `en-AU`, `en-NZ`, `en-IN`. For
+   * The language of the audio to be transcribed. `deepgram/nova-3` supports ~49
+   * languages plus `multi`, and `deepgram/nova-2` supports ~33 plus `multi`; the
+   * `-medical` variants are English only (`en` and its regional variants, e.g.
+   * `en-US`, `en-GB`). Deepgram models validate on the base language and forward the
+   * full tag, so regional variants such as `de-CH` and `pt-BR` are accepted where
+   * the base language is supported; an unsupported language returns a 400. For
    * `openai/whisper-large-v3-turbo`, supports multiple languages.
    * `distil-whisper/distil-large-v2` does not support language parameter.
+   * `nvidia/parakeet-v3` detects the language automatically;
+   * `omi-health/omi-med-stt-v1` is English only.
    */
   language?: string;
 
   /**
-   * Additional model-specific configuration parameters. Only allowed with
-   * `deepgram/nova-3` model. Can include Deepgram-specific options such as
+   * Additional model-specific configuration parameters. Only allowed with the
+   * `deepgram/*` models. Can include Deepgram-specific options such as
    * `smart_format`, `punctuate`, `diarize`, `utterance`, `numerals`, and `language`.
    * If `language` is provided both as a top-level parameter and in `model_config`,
    * the top-level parameter takes precedence.
@@ -173,6 +220,7 @@ export interface AudioTranscribeParams {
 
 export declare namespace Audio {
   export {
+    type AudioTranscriptionResponseWord as AudioTranscriptionResponseWord,
     type AudioTranscribeResponse as AudioTranscribeResponse,
     type AudioTranscribeParams as AudioTranscribeParams,
   };

package/src/resources/ai/chat.ts

@@ -2,6 +2,7 @@
 
 import { APIResource } from '../../core/resource';
 import * as ChatAPI from './chat';
+import * as OpenAIChatAPI from './openai/chat';
 
 export class Chat extends APIResource {}
 
@@ -282,21 +283,11 @@ export namespace ChatCompletionRequest {
   }
 
   export interface Function {
-    function: Function.Function;
+    function: OpenAIChatAPI.FunctionDefinition;
 
     type: 'function';
   }
 
-  export namespace Function {
-    export interface Function {
-      name: string;
-
-      description?: string;
-
-      parameters?: { [key: string]: unknown };
-    }
-  }
-
   export interface Retrieval {
     retrieval: ChatAPI.BucketIDs;
 

package/src/resources/ai/index.ts

@@ -77,7 +77,12 @@ export {
   type AssistantCloneParams,
   type AssistantSendSMSParams,
 } from './assistants/index';
-export { Audio, type AudioTranscribeResponse, type AudioTranscribeParams } from './audio';
+export {
+  Audio,
+  type AudioTranscriptionResponseWord,
+  type AudioTranscribeResponse,
+  type AudioTranscribeParams,
+} from './audio';
 export { Chat, type BucketIDs, type ChatCompletionRequest } from './chat';
 export {
   Clusters,
@@ -160,3 +165,4 @@ export {
   type ToolUpdateParams,
   type SharedToolResponsesDefaultFlatPagination,
 } from './tools';
+export { Typesafe } from './typesafe/index';

package/src/resources/ai/openai/chat.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../../core/resource';
+import * as OpenAIChatAPI from './chat';
 import * as ChatAPI from '../chat';
 import { APIPromise } from '../../../core/api-promise';
 import { RequestOptions } from '../../../internal/request-options';
@@ -34,6 +35,14 @@ export class Chat extends APIResource {
   }
 }
 
+export interface FunctionDefinition {
+  name: string;
+
+  description?: string;
+
+  parameters?: { [key: string]: unknown };
+}
+
 export type ChatCreateCompletionResponse = { [key: string]: unknown };
 
 export interface ChatCreateCompletionParams {
@@ -299,21 +308,11 @@ export namespace ChatCreateCompletionParams {
   }
 
   export interface Function {
-    function: Function.Function;
+    function: OpenAIChatAPI.FunctionDefinition;
 
     type: 'function';
   }
 
-  export namespace Function {
-    export interface Function {
-      name: string;
-
-      description?: string;
-
-      parameters?: { [key: string]: unknown };
-    }
-  }
-
   export interface Retrieval {
     retrieval: ChatAPI.BucketIDs;
 
@@ -323,6 +322,7 @@ export namespace ChatCreateCompletionParams {
 
 export declare namespace Chat {
   export {
+    type FunctionDefinition as FunctionDefinition,
     type ChatCreateCompletionResponse as ChatCreateCompletionResponse,
     type ChatCreateCompletionParams as ChatCreateCompletionParams,
   };

package/src/resources/ai/openai/index.ts

@@ -1,6 +1,11 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export { Chat, type ChatCreateCompletionResponse, type ChatCreateCompletionParams } from './chat';
+export {
+  Chat,
+  type FunctionDefinition,
+  type ChatCreateCompletionResponse,
+  type ChatCreateCompletionParams,
+} from './chat';
 export {
   Embeddings,
   type EmbeddingCreateEmbeddingsResponse,

package/src/resources/ai/openai/openai.ts

@@ -3,7 +3,7 @@
 import { APIResource } from '../../../core/resource';
 import * as AIAPI from '../ai';
 import * as ChatAPI from './chat';
-import { Chat, ChatCreateCompletionParams, ChatCreateCompletionResponse } from './chat';
+import { Chat, ChatCreateCompletionParams, ChatCreateCompletionResponse, FunctionDefinition } from './chat';
 import * as EmbeddingsAPI from './embeddings';
 import {
   EmbeddingCreateEmbeddingsParams,
@@ -191,6 +191,7 @@ export declare namespace OpenAI {
 
   export {
     Chat as Chat,
+    type FunctionDefinition as FunctionDefinition,
     type ChatCreateCompletionResponse as ChatCreateCompletionResponse,
     type ChatCreateCompletionParams as ChatCreateCompletionParams,
   };

package/src/resources/ai/typesafe/index.ts

@@ -0,0 +1,4 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Typesafe } from './typesafe';
+export { V1, type V1SystemoneResponse, type V1SystemoneParams } from './v1';

package/src/resources/ai/typesafe/typesafe.ts

@@ -0,0 +1,19 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as V1API from './v1';
+import { V1, V1SystemoneParams, V1SystemoneResponse } from './v1';
+
+export class Typesafe extends APIResource {
+  v1: V1API.V1 = new V1API.V1(this._client);
+}
+
+Typesafe.V1 = V1;
+
+export declare namespace Typesafe {
+  export {
+    V1 as V1,
+    type V1SystemoneResponse as V1SystemoneResponse,
+    type V1SystemoneParams as V1SystemoneParams,
+  };
+}

package/src/resources/ai/typesafe/v1.ts

@@ -0,0 +1,298 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+
+/**
+ * Beta API for evaluating shared context with typed questions and structured answers. Telnyx manages model selection.
+ */
+export class V1 extends APIResource {
+  /**
+   * **Beta API.** Telnyx controls model selection.
+   *
+   * Evaluate shared context using named choice, noul (yes/no), and score questions.
+   * Returns TypeSafe System One-compatible answer shapes, an opaque compatibility
+   * identifier, and token usage. See the
+   * [decision model guide](https://developers.telnyx.com/docs/inference/decision-models)
+   * for examples and compatibility limits.
+   *
+   * The supported request subset requires instructions for every question, string
+   * descriptions for criteria (or null for choice descriptions), 1–64 questions, and
+   * 2–64 options for choice and score questions. The SDK-supplied model value is
+   * ignored and cannot select a model. Other unknown fields are rejected. The
+   * endpoint is synchronous and does not stream.
+   *
+   * Use the TypeSafe Python SDK with base_url set to
+   * https://api.telnyx.com/v2/ai/typesafe and a Telnyx API key. The SDK appends
+   * /v1/systemone. Compatibility covers this operation and the documented request
+   * subset; it does not include TypeSafe model listing. Scores describe relative
+   * preference, not calibrated correctness.
+   *
+   * @example
+   * ```ts
+   * const response = await client.ai.typesafe.v1.systemone({
+   *   questions: {
+   *     team: {
+   *       type: 'choice',
+   *       instructions:
+   *         'Choose the team that should handle this incident.',
+   *       criteria: {
+   *         billing: 'Payments and refunds',
+   *         technical_support:
+   *           'Service faults and technical problems',
+   *         sales: 'New purchases',
+   *       },
+   *     },
+   *     production_incident: {
+   *       type: 'noul',
+   *       instructions:
+   *         'Does the message describe an active production incident?',
+   *     },
+   *     urgency: {
+   *       type: 'score',
+   *       instructions: 'Rate operational urgency.',
+   *       criteria: ['Low', 'Normal', 'High', 'Critical'],
+   *     },
+   *   },
+   *   state:
+   *     'Our production calls are failing. Every customer is affected.',
+   * });
+   * ```
+   */
+  systemone(body: V1SystemoneParams, options?: RequestOptions): APIPromise<V1SystemoneResponse> {
+    return this._client.post('/ai/typesafe/v1/systemone', { body, ...options });
+  }
+}
+
+/**
+ * A complete synchronous evaluation. Answers are returned directly without a data
+ * wrapper.
+ */
+export interface V1SystemoneResponse {
+  /**
+   * Answers keyed by exactly the question IDs in the request. Each answer type
+   * matches its question.
+   */
+  answers: {
+    [key: string]:
+      | V1SystemoneResponse.DecisionModelChoiceAnswer
+      | V1SystemoneResponse.DecisionModelNoulAnswer
+      | V1SystemoneResponse.DecisionModelScoreAnswer;
+  };
+
+  /**
+   * Opaque Telnyx-controlled identifier retained for TypeSafe SDK response
+   * compatibility. It is not a selectable model name or a guarantee of a particular
+   * underlying model.
+   */
+  model: string;
+
+  /**
+   * Token usage for the completed evaluation.
+   */
+  usage: V1SystemoneResponse.Usage;
+}
+
+export namespace V1SystemoneResponse {
+  /**
+   * A selected option and the distribution across all supplied option keys.
+   */
+  export interface DecisionModelChoiceAnswer {
+    /**
+     * The option key with the highest relative score. Ties favor the first option in
+     * request order.
+     */
+    choice: string;
+
+    /**
+     * Normalized entropy confidence: 1 - H(p) / ln(N), where H(p) = -sum(p \* ln(p))
+     * and N is the number of options. Zero indicates a uniform distribution; one
+     * indicates concentration on one option. This is neither the winning probability
+     * nor calibrated correctness.
+     */
+    confidence: number;
+
+    /**
+     * Relative scores normalized across the supplied options, summing approximately
+     * to 1. These are not calibrated probabilities of correctness.
+     */
+    probabilities: { [key: string]: number };
+
+    /**
+     * Answer type.
+     */
+    type: 'choice';
+  }
+
+  /**
+   * A yes/no score with no separate confidence or probabilities fields.
+   */
+  export interface DecisionModelNoulAnswer {
+    /**
+     * Score of the positive outcome. Values near 1 favor yes; values near 0 favor no.
+     * This is a number, not a Boolean, and is not calibrated correctness.
+     */
+    noul: number;
+
+    /**
+     * Answer type.
+     */
+    type: 'noul';
+  }
+
+  /**
+   * An expected rating over the ordered criteria.
+   */
+  export interface DecisionModelScoreAnswer {
+    /**
+     * Normalized entropy confidence: 1 - H(p) / ln(N), where H(p) = -sum(p \* ln(p))
+     * and N is the number of options. Zero indicates a uniform distribution; one
+     * indicates concentration on one option. This is neither the winning probability
+     * nor calibrated correctness.
+     */
+    confidence: number;
+
+    /**
+     * Criterion descriptions keyed by stringified zero-based indices, such as "0",
+     * "1", and "2".
+     */
+    legend: { [key: string]: string };
+
+    /**
+     * Relative scores keyed by the same stringified indices as legend.
+     */
+    probabilities: { [key: string]: number };
+
+    /**
+     * Expected zero-based criterion index: sum(index \* probability). Ranges from 0 to
+     * N-1 for N criteria; fractional values are valid.
+     */
+    score: number;
+
+    /**
+     * Answer type.
+     */
+    type: 'score';
+  }
+
+  /**
+   * Token usage for the completed evaluation.
+   */
+  export interface Usage {
+    /**
+     * Input tokens processed, including shared-context preparation and question
+     * evaluation. This can exceed the token count of the unique input text.
+     */
+    input_tokens: number;
+
+    /**
+     * Output tokens used for the evaluation, including shared-context preparation.
+     */
+    output_tokens: number;
+  }
+}
+
+export interface V1SystemoneParams {
+  /**
+   * Between 1 and 64 named questions. Each key identifies the corresponding answer.
+   */
+  questions: {
+    [key: string]:
+      | V1SystemoneParams.DecisionModelChoiceQuestion
+      | V1SystemoneParams.DecisionModelNoulQuestion
+      | V1SystemoneParams.DecisionModelScoreQuestion;
+  };
+
+  /**
+   * Shared context evaluated by every question.
+   */
+  state: string | { [key: string]: unknown } | Array<unknown>;
+}
+
+export namespace V1SystemoneParams {
+  /**
+   * Select one of the supplied options.
+   */
+  export interface DecisionModelChoiceQuestion {
+    /**
+     * Between 2 and 64 option keys mapped to description strings or null. A null
+     * description uses the option key as its text.
+     */
+    criteria: { [key: string]: string | null };
+
+    /**
+     * Required instructions describing what to decide about the shared state.
+     */
+    instructions: string | { [key: string]: unknown } | Array<unknown>;
+
+    /**
+     * Question type.
+     */
+    type: 'choice';
+  }
+
+  /**
+   * Evaluate a yes/no question. Omit criteria to use Yes and No descriptions.
+   */
+  export interface DecisionModelNoulQuestion {
+    /**
+     * Required instructions describing what to decide about the shared state.
+     */
+    instructions: string | { [key: string]: unknown } | Array<unknown>;
+
+    /**
+     * Question type.
+     */
+    type: 'noul';
+
+    /**
+     * Optional descriptions for the positive and negative outcomes. Descriptions must
+     * be strings.
+     */
+    criteria?: DecisionModelNoulQuestion.Criteria;
+  }
+
+  export namespace DecisionModelNoulQuestion {
+    /**
+     * Optional descriptions for the positive and negative outcomes. Descriptions must
+     * be strings.
+     */
+    export interface Criteria {
+      /**
+       * Description of the negative outcome.
+       */
+      false?: string;
+
+      /**
+       * Description of the positive outcome.
+       */
+      true?: string;
+    }
+  }
+
+  /**
+   * Rate the state against an ordered rubric.
+   */
+  export interface DecisionModelScoreQuestion {
+    /**
+     * Between 2 and 64 description strings in ascending score order. Indices start at
+     * zero.
+     */
+    criteria: Array<string>;
+
+    /**
+     * Required instructions describing what to decide about the shared state.
+     */
+    instructions: string | { [key: string]: unknown } | Array<unknown>;
+
+    /**
+     * Question type.
+     */
+    type: 'score';
+  }
+}
+
+export declare namespace V1 {
+  export { type V1SystemoneResponse as V1SystemoneResponse, type V1SystemoneParams as V1SystemoneParams };
+}

package/src/resources/ai/typesafe.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './typesafe/index';