telnyx 7.22.0 → 7.24.0

package/src/resources/ai/memory/namespaces/settings.ts

@@ -0,0 +1,129 @@
+// 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';
+import { path } from '../../../../internal/utils/path';
+
+/**
+ * How a namespace's summaries are written.
+ */
+export class Settings extends APIResource {
+  /**
+   * What is currently set for this namespace. `instructions: null` means none are
+   * set and summaries use the neutral default.
+   *
+   * @example
+   * ```ts
+   * const namespaceSettingsResponse =
+   *   await client.ai.memory.namespaces.settings.list(
+   *     'namespace',
+   *   );
+   * ```
+   */
+  list(namespace: string, options?: RequestOptions): APIPromise<NamespaceSettingsResponse> {
+    return this._client.get(path`/ai/memory/namespaces/${namespace}/settings`, options);
+  }
+
+  /**
+   * Only the fields you send are changed; anything omitted is left as it is, so `{}`
+   * changes nothing. Sending `instructions: null`, or an empty or whitespace-only
+   * string, clears them and returns summaries to the neutral default.
+   *
+   * Instructions are capped at 2000 characters. A longer note is refused rather than
+   * truncated, because a note cut mid-sentence is a worse steer than none. A change
+   * reaches each summary the next time that summary is regenerated, not immediately.
+   *
+   * @example
+   * ```ts
+   * const namespaceSettingsResponse =
+   *   await client.ai.memory.namespaces.settings.patchAll(
+   *     'namespace',
+   *     {
+   *       summary: {
+   *         instructions:
+   *           "Lead with the customer's plan tier. Keep it under 100 words.",
+   *       },
+   *     },
+   *   );
+   * ```
+   */
+  patchAll(
+    namespace: string,
+    body: SettingPatchAllParams,
+    options?: RequestOptions,
+  ): APIPromise<NamespaceSettingsResponse> {
+    return this._client.patch(path`/ai/memory/namespaces/${namespace}/settings`, { body, ...options });
+  }
+}
+
+export interface NamespaceSettingsResponse {
+  /**
+   * A namespace's settings, grouped by what they affect.
+   */
+  data: NamespaceSettingsResponse.Data;
+}
+
+export namespace NamespaceSettingsResponse {
+  /**
+   * A namespace's settings, grouped by what they affect.
+   */
+  export interface Data {
+    /**
+     * Settings that shape this namespace's summaries.
+     */
+    summary?: Data.Summary;
+  }
+
+  export namespace Data {
+    /**
+     * Settings that shape this namespace's summaries.
+     */
+    export interface Summary {
+      /**
+       * Free-form instructions that influence how this namespace's summaries are
+       * written, shared by every profile in the namespace. How you use them is up to you
+       * -- they steer the outcome, so try a phrasing and see how the summary comes out.
+       * Advisory: they steer the summary but never override or deny a profile's own
+       * facts, and they do not affect recall. Null or empty means none are set, and
+       * summaries use the neutral default. A change reaches each summary the next time
+       * it is regenerated.
+       */
+      instructions?: string | null;
+    }
+  }
+}
+
+export interface SettingPatchAllParams {
+  /**
+   * A partial update to a namespace's summary settings.
+   *
+   * Only the fields present in the request are changed; the rest are left as they
+   * are. Sending `instructions: null` (or empty) clears the instructions.
+   */
+  summary?: SettingPatchAllParams.Summary | null;
+}
+
+export namespace SettingPatchAllParams {
+  /**
+   * A partial update to a namespace's summary settings.
+   *
+   * Only the fields present in the request are changed; the rest are left as they
+   * are. Sending `instructions: null` (or empty) clears the instructions.
+   */
+  export interface Summary {
+    /**
+     * Replace the namespace's summary instructions. Null or empty clears them and
+     * returns to the neutral default. Omit the field to leave the current instructions
+     * unchanged.
+     */
+    instructions?: string | null;
+  }
+}
+
+export declare namespace Settings {
+  export {
+    type NamespaceSettingsResponse as NamespaceSettingsResponse,
+    type SettingPatchAllParams as SettingPatchAllParams,
+  };
+}

package/src/resources/ai/memory/namespaces.ts

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

package/src/resources/ai/memory.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './memory/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,310 @@
+// 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 using Flash or Pro.
+ */
+export class V1 extends APIResource {
+  /**
+   * **Beta API.** Choose telnyx/decision-flash for the lowest cost and latency, or
+   * telnyx/decision-pro for decisions that require long context, including inputs
+   * beyond Jev’s 32k per-decision limit. Omitted model defaults to
+   * telnyx/decision-flash.
+   *
+   * Evaluate shared context using named choice, noul (yes/no), and score questions.
+   * Returns TypeSafe System One-compatible answer shapes, the selected public model
+   * alias, 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 model field accepts only
+   * telnyx/decision-flash or telnyx/decision-pro. Unsupported model values and
+   * 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; explicitly set model to a supported Telnyx alias because its own
+   * default model is not supported. 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.',
+   *   model: 'telnyx/decision-flash',
+   * });
+   * ```
+   */
+  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;
+  };
+
+  /**
+   * Public model alias used to evaluate the request. Returns telnyx/decision-flash
+   * when model was omitted. The underlying model is managed by Telnyx.
+   */
+  model: 'telnyx/decision-flash' | 'telnyx/decision-pro';
+
+  /**
+   * 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>;
+
+  /**
+   * Public model alias. telnyx/decision-flash offers the lowest cost and latency;
+   * telnyx/decision-pro supports decisions that require long context, including
+   * inputs beyond Jev’s 32k per-decision limit. Applies to every question in the
+   * request. Other values are rejected.
+   */
+  model?: 'telnyx/decision-flash' | 'telnyx/decision-pro';
+}
+
+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';

package/src/resources/bot-challenge.ts

@@ -0,0 +1,101 @@
+// 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';
+
+/**
+ * Agentic (bot) signup for Telnyx accounts. An AI agent solves a reverse-CAPTCHA challenge designed to be easy for LLMs and hard for humans, registers an account, and signs in by consuming a magic link emailed to the account owner. All endpoints are public and unauthenticated; signup endpoints are additionally gated by the freemium feature flags and per-country availability.
+ */
+export class BotChallenge extends APIResource {
+  /**
+   * Generates a reverse-CAPTCHA challenge used to gate the bot signup flow. A random
+   * active problem is selected from the pool; math problems are returned obfuscated
+   * (case randomization, symbol injection, spacing noise) with an unobfuscated
+   * rounding instruction appended, while string and binary problems are returned
+   * as-is. The response contains a single-use nonce, the problem text, and the
+   * current terms-and-conditions and privacy-policy URLs, which must be echoed back
+   * on the signup request. Challenges expire after a short window (10 minutes by
+   * default) and can only be answered once. This endpoint is public and
+   * unauthenticated.
+   *
+   * @example
+   * ```ts
+   * const botChallenge = await client.botChallenge.create({
+   *   llm_model_name: 'claude-opus-4',
+   *   llm_parameter_count: '175B',
+   *   llm_quantization: 'int8',
+   * });
+   * ```
+   */
+  create(
+    body: BotChallengeCreateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<BotChallengeCreateResponse> {
+    return this._client.post('/v2/bot_challenge', { body, ...options });
+  }
+}
+
+export interface BotChallengeCreateResponse {
+  data: BotChallengeCreateResponse.Data;
+}
+
+export namespace BotChallengeCreateResponse {
+  export interface Data {
+    /**
+     * Type of challenge.
+     */
+    challenge_type: 'math' | 'string' | 'binary';
+
+    /**
+     * Single-use challenge identifier. Submit it as `bot_challenge_nonce` on the
+     * signup request.
+     */
+    nonce: string;
+
+    /**
+     * Current privacy-policy URL. Echo this back on the signup request.
+     */
+    privacy_policy_url: string;
+
+    /**
+     * Problem text to solve. Math problems are obfuscated and end with an unobfuscated
+     * rounding instruction; string and binary problems are returned as-is.
+     */
+    problem: string;
+
+    /**
+     * Current terms-and-conditions URL. Echo this back on the signup request.
+     */
+    terms_and_conditions_url: string;
+
+    /**
+     * Decimal places expected in the answer. Present only for math challenges.
+     */
+    precision?: number;
+  }
+}
+
+export interface BotChallengeCreateParams {
+  /**
+   * Name of the LLM the client is using.
+   */
+  llm_model_name?: string;
+
+  /**
+   * Parameter count of the client LLM.
+   */
+  llm_parameter_count?: string;
+
+  /**
+   * Quantization of the client LLM.
+   */
+  llm_quantization?: string;
+}
+
+export declare namespace BotChallenge {
+  export {
+    type BotChallengeCreateResponse as BotChallengeCreateResponse,
+    type BotChallengeCreateParams as BotChallengeCreateParams,
+  };
+}