telnyx 5.168.0 → 5.170.0

data/rbi/telnyx/resources/ai/memory/namespaces/profiles/sources.rbi

@@ -0,0 +1,117 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      class Memory
+        class Namespaces
+          class Profiles
+            # What a profile stored, and what its memories came from.
+            class Sources
+              # One source and its content, as it was stored: an ingested session's payload or a
+              # remembered fact. A source whose ingest is still queued answers 404 until it has
+              # been stored.
+              sig do
+                params(
+                  source_id: String,
+                  namespace: String,
+                  profile_id: String,
+                  request_options: Telnyx::RequestOptions::OrHash
+                ).returns(
+                  Telnyx::Models::AI::Memory::Namespaces::Profiles::SourceRetrieveResponse
+                )
+              end
+              def retrieve(
+                # Identifies one source within its profile: an ingested session, or one remembered
+                # fact. Returned by `ingest` and `remember` when the write is accepted.
+                # Re-ingesting a session keeps its source id.
+                source_id,
+                # The namespace. `default` exists for every organization.
+                namespace:,
+                # The profile: your identifier for the user, caller or agent this memory is about.
+                profile_id:,
+                request_options: {}
+              )
+              end
+
+              # Everything a profile has stored and extracts memories from: each ingested
+              # session, and each remembered fact, which has no session. Content is not listed;
+              # read one source for it. A source whose ingest is still queued is not here yet.
+              # Re-ingesting a session moves it to the front, so a listing paged while sessions
+              # are written can repeat or miss one at a page boundary. A `session_id` narrows
+              # the listing to the source that session was stored as: one source or none, and
+              # none -- an empty page, not a 404 -- for a session never ingested, still queued,
+              # or another profile's.
+              sig do
+                params(
+                  profile_id: String,
+                  namespace: String,
+                  page_number: Integer,
+                  page_size: Integer,
+                  session_id: T.nilable(String),
+                  request_options: Telnyx::RequestOptions::OrHash
+                ).returns(
+                  Telnyx::Internal::DefaultFlatPagination[
+                    Telnyx::AI::Collections::Source
+                  ]
+                )
+              end
+              def list(
+                # Path param
+                profile_id,
+                # Path param
+                namespace:,
+                # Query param: The page to return, counting from 1. Bounded in depth:
+                # (page[number] - 1) \* page[size] may be at most 10000.
+                page_number: nil,
+                # Query param: How many results a page holds.
+                page_size: nil,
+                # Query param: An ingested session, by the `session_id` it was ingested with.
+                # Narrows the request to the source that session was stored as.
+                session_id: nil,
+                request_options: {}
+              )
+              end
+
+              # Deletes one source -- an ingested session or a remembered fact -- together with
+              # the memories derived from it. A memory derived from this source and others is
+              # deleted too, and derived again from what remains in the background. It answers
+              # only once the source is gone. A source that is not there -- never stored,
+              # another profile's, or already deleted -- answers 404, so on a `502` or a `504`
+              # repeat the identical request and read a 404 as done. An ingest of the same
+              # session that is still queued is not cancelled, and stores the session again when
+              # it runs. Nothing here can be undone.
+              sig do
+                params(
+                  source_id: String,
+                  namespace: String,
+                  profile_id: String,
+                  request_options: Telnyx::RequestOptions::OrHash
+                ).returns(
+                  Telnyx::Models::AI::Memory::Namespaces::Profiles::SourceDeleteResponse
+                )
+              end
+              def delete(
+                # Identifies one source within its profile: an ingested session, or one remembered
+                # fact. Returned by `ingest` and `remember` when the write is accepted.
+                # Re-ingesting a session keeps its source id.
+                source_id,
+                # The namespace. `default` exists for every organization.
+                namespace:,
+                # The profile: your identifier for the user, caller or agent this memory is about.
+                profile_id:,
+                request_options: {}
+              )
+              end
+
+              # @api private
+              sig { params(client: Telnyx::Client).returns(T.attached_class) }
+              def self.new(client:)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai/memory/namespaces/profiles.rbi

@@ -0,0 +1,196 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      class Memory
+        class Namespaces
+          class Profiles
+            # What a namespace and a profile hold.
+            sig do
+              returns(
+                Telnyx::Resources::AI::Memory::Namespaces::Profiles::Memories
+              )
+            end
+            attr_reader :memories
+
+            # What a profile stored, and what its memories came from.
+            sig do
+              returns(
+                Telnyx::Resources::AI::Memory::Namespaces::Profiles::Sources
+              )
+            end
+            attr_reader :sources
+
+            # Profiles are never created, only written to, so this lists the ones that hold a
+            # memory. A profile whose first ingest is still running is not here yet. Ordered
+            # by memory count, largest first, so a profile written to while the listing is
+            # paged can move between pages and be repeated or missed.
+            sig do
+              params(
+                namespace: String,
+                page_number: Integer,
+                page_size: Integer,
+                request_options: Telnyx::RequestOptions::OrHash
+              ).returns(
+                Telnyx::Internal::DefaultFlatPagination[
+                  Telnyx::Models::AI::Memory::Namespaces::ProfileListResponse
+                ]
+              )
+            end
+            def list(
+              namespace,
+              # The page to return, counting from 1. Bounded in depth: (page[number] - 1) \*
+              # page[size] may be at most 10000.
+              page_number: nil,
+              # How many results a page holds.
+              page_size: nil,
+              request_options: {}
+            )
+            end
+
+            # Delete everything held about one profile. A 2xx means none of its memories are
+            # left, and its summary goes with them. There is no undo.
+            sig do
+              params(
+                profile_id: String,
+                namespace: String,
+                request_options: Telnyx::RequestOptions::OrHash
+              ).returns(
+                Telnyx::Models::AI::Memory::Namespaces::ProfileDeleteResponse
+              )
+            end
+            def delete(
+              # The profile: your identifier for the user, caller or agent this memory is about.
+              profile_id,
+              # The namespace. `default` exists for every organization.
+              namespace:,
+              request_options: {}
+            )
+            end
+
+            # Store a session. Facts are extracted from whatever you send — the body is taken
+            # as any JSON value and stored whole, so a framework's own transcript shape works
+            # unchanged. `messages` of `role`/`content` is the conventional shape, not a
+            # requirement. An empty object or a null body is refused. Carry a `session_id` to
+            # name the session: re-ingesting the same one replaces what it held. Omit it and a
+            # session is opened and returned. Extraction runs asynchronously — poll the
+            # returned operation.
+            sig do
+              params(
+                profile_id: String,
+                namespace: String,
+                body:
+                  Telnyx::AI::Memory::Namespaces::ProfileIngestParams::Body::Variants,
+                session_id: T.nilable(String),
+                request_options: Telnyx::RequestOptions::OrHash
+              ).returns(
+                Telnyx::Models::AI::Memory::Namespaces::ProfileIngestResponse
+              )
+            end
+            def ingest(
+              # Path param
+              profile_id,
+              # Path param
+              namespace:,
+              # Body param: The session's messages, in whatever shape your framework produces.
+              # Any JSON value but null is accepted and stored whole, as long as it holds
+              # something to remember: a body with no content anywhere in it -- `{}`, `[]`,
+              # `""`, `{"messages": []}` -- is a 422.
+              body:,
+              # Query param: Names the session. Re-ingesting the same session replaces what it
+              # held and keeps its `source_id`. Omit it to have one derived from the content and
+              # returned. No whitespace, control characters, or any of / \ # ? %.
+              session_id: nil,
+              request_options: {}
+            )
+            end
+
+            # Ranked memories for a question. Matching runs over the profile's memories and
+            # returns them in rank order with a relevance `score`; the score is null where the
+            # deployment's reranker is a passthrough, in which case order is the only signal.
+            # No model runs in this path — recall returns facts, it does not compose an
+            # answer.
+            sig do
+              params(
+                profile_id: String,
+                namespace: String,
+                query: String,
+                top_k: T.nilable(Integer),
+                request_options: Telnyx::RequestOptions::OrHash
+              ).returns(
+                Telnyx::Models::AI::Memory::Namespaces::ProfileRecallResponse
+              )
+            end
+            def recall(
+              # Path param
+              profile_id,
+              # Path param
+              namespace:,
+              # Body param
+              query:,
+              # Body param
+              top_k: nil,
+              request_options: {}
+            )
+            end
+
+            # For a fact the agent has already distilled: `text` is stored as given, with
+            # nothing extracted from it. Send a transcript to `ingest` instead. Remembering
+            # the same text again writes the same memory rather than a second copy of it, so a
+            # retry is safe. The write runs asynchronously -- poll the returned operation.
+            sig do
+              params(
+                profile_id: String,
+                namespace: String,
+                text: String,
+                request_options: Telnyx::RequestOptions::OrHash
+              ).returns(
+                Telnyx::Models::AI::Memory::Namespaces::ProfileRememberResponse
+              )
+            end
+            def remember(
+              # Path param
+              profile_id,
+              # Path param
+              namespace:,
+              # Body param
+              text:,
+              request_options: {}
+            )
+            end
+
+            # The whole profile as one card, precomputed, with no query. Built for the start
+            # of a session, where there is no question to ask yet.
+            #
+            # A summary is generated in the background. `is_stale` tells you newer memories
+            # have arrived since it was written; that is ordinary and the card is still
+            # usable.
+            sig do
+              params(
+                profile_id: String,
+                namespace: String,
+                request_options: Telnyx::RequestOptions::OrHash
+              ).returns(
+                Telnyx::Models::AI::Memory::Namespaces::ProfileRetrieveSummaryResponse
+              )
+            end
+            def retrieve_summary(
+              # The profile: your identifier for the user, caller or agent this memory is about.
+              profile_id,
+              # The namespace. `default` exists for every organization.
+              namespace:,
+              request_options: {}
+            )
+            end
+
+            # @api private
+            sig { params(client: Telnyx::Client).returns(T.attached_class) }
+            def self.new(client:)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai/memory/namespaces/settings.rbi

@@ -0,0 +1,67 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      class Memory
+        class Namespaces
+          # How a namespace's summaries are written.
+          class Settings
+            # What is currently set for this namespace. `instructions: null` means none are
+            # set and summaries use the neutral default.
+            sig do
+              params(
+                namespace: String,
+                request_options: Telnyx::RequestOptions::OrHash
+              ).returns(
+                Telnyx::AI::Memory::Namespaces::NamespaceSettingsResponse
+              )
+            end
+            def list(
+              # The namespace. `default` exists for every organization.
+              namespace,
+              request_options: {}
+            )
+            end
+
+            # 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.
+            sig do
+              params(
+                namespace: String,
+                summary:
+                  T.nilable(
+                    Telnyx::AI::Memory::Namespaces::SettingPatchAllParams::Summary::OrHash
+                  ),
+                request_options: Telnyx::RequestOptions::OrHash
+              ).returns(
+                Telnyx::AI::Memory::Namespaces::NamespaceSettingsResponse
+              )
+            end
+            def patch_all(
+              # The namespace. `default` exists for every organization.
+              namespace,
+              # 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: nil,
+              request_options: {}
+            )
+            end
+
+            # @api private
+            sig { params(client: Telnyx::Client).returns(T.attached_class) }
+            def self.new(client:)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai/memory/namespaces.rbi

@@ -0,0 +1,37 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      class Memory
+        # Whether a write has finished.
+        class Namespaces
+          sig { returns(Telnyx::Resources::AI::Memory::Namespaces::Profiles) }
+          attr_reader :profiles
+
+          # How a namespace's summaries are written.
+          sig { returns(Telnyx::Resources::AI::Memory::Namespaces::Settings) }
+          attr_reader :settings
+
+          # Whether a write has finished. Both `ingest` and `remember` return an
+          # `operation_id`, and a memory is not recallable until its operation completes —
+          # extraction, embedding and consolidation all run first.
+          sig do
+            params(
+              operation_id: String,
+              namespace: String,
+              request_options: Telnyx::RequestOptions::OrHash
+            ).returns(Telnyx::Models::AI::Memory::NamespaceRetrieveResponse)
+          end
+          def retrieve(operation_id, namespace:, request_options: {})
+          end
+
+          # @api private
+          sig { params(client: Telnyx::Client).returns(T.attached_class) }
+          def self.new(client:)
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai/memory.rbi

@@ -0,0 +1,18 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      class Memory
+        # Whether a write has finished.
+        sig { returns(Telnyx::Resources::AI::Memory::Namespaces) }
+        attr_reader :namespaces
+
+        # @api private
+        sig { params(client: Telnyx::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai/typesafe/v1.rbi

@@ -0,0 +1,71 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      class Typesafe
+        # Beta API for evaluating shared context with typed questions and structured
+        # answers using Flash or Pro.
+        class V1
+          # **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.
+          sig do
+            params(
+              questions:
+                T::Hash[
+                  Symbol,
+                  T.any(
+                    Telnyx::AI::Typesafe::V1SystemoneParams::Question::Choice::OrHash,
+                    Telnyx::AI::Typesafe::V1SystemoneParams::Question::Noul::OrHash,
+                    Telnyx::AI::Typesafe::V1SystemoneParams::Question::Score::OrHash
+                  )
+                ],
+              state: Telnyx::AI::Typesafe::V1SystemoneParams::State::Variants,
+              model: Telnyx::AI::Typesafe::V1SystemoneParams::Model::OrSymbol,
+              request_options: Telnyx::RequestOptions::OrHash
+            ).returns(Telnyx::Models::AI::Typesafe::V1SystemoneResponse)
+          end
+          def systemone(
+            # Between 1 and 64 named questions. Each key identifies the corresponding answer.
+            questions:,
+            # Shared context evaluated by every question.
+            state:,
+            # 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: nil,
+            request_options: {}
+          )
+          end
+
+          # @api private
+          sig { params(client: Telnyx::Client).returns(T.attached_class) }
+          def self.new(client:)
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai/typesafe.rbi

@@ -0,0 +1,19 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      class Typesafe
+        # Beta API for evaluating shared context with typed questions and structured
+        # answers using Flash or Pro.
+        sig { returns(Telnyx::Resources::AI::Typesafe::V1) }
+        attr_reader :v1
+
+        # @api private
+        sig { params(client: Telnyx::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai.rbi

@@ -55,6 +55,12 @@ module Telnyx
       sig { returns(Telnyx::Resources::AI::Knowledge) }
       attr_reader :knowledge
 
+      sig { returns(Telnyx::Resources::AI::Typesafe) }
+      attr_reader :typesafe
+
+      sig { returns(Telnyx::Resources::AI::Memory) }
+      attr_reader :memory
+
       # Performs semantic vector search across conversation history records.
       #
       # **How it works:**

data/rbi/telnyx/resources/bot_challenge.rbi

@@ -0,0 +1,45 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    # 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.
+    class BotChallenge
+      # 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.
+      sig do
+        params(
+          llm_model_name: String,
+          llm_parameter_count: String,
+          llm_quantization: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::BotChallengeCreateResponse)
+      end
+      def create(
+        # Name of the LLM the client is using.
+        llm_model_name: nil,
+        # Parameter count of the client LLM.
+        llm_parameter_count: nil,
+        # Quantization of the client LLM.
+        llm_quantization: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Telnyx::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/bot_sessions.rbi

@@ -0,0 +1,45 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    # 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.
+    class BotSessions
+      # Consumes the one-time portal redirect (magic link) token emailed during bot
+      # signup and returns an API session. The token is a UUIDv7 that encodes its
+      # creation time; it expires after a configurable validity window (15 minutes by
+      # default) and is cleared on first use. Although the action creates a session, the
+      # route uses the GET verb because it is opened from an email link. On first use
+      # the account is also initialized. For bot signup (freemium) accounts the response
+      # is a minimal envelope containing only the `api_v2_token`; accounts that are
+      # permitted to use magic links but are not freemium accounts may instead receive
+      # an extended session payload when additional steps (such as two-factor
+      # authentication or identity verification) are required. This endpoint is public;
+      # the magic link token in the query string is the credential.
+      sig do
+        params(
+          email: String,
+          portal_redirect_token: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::BotSessionListResponse)
+      end
+      def list(
+        # Email address associated with the magic link token.
+        email:,
+        # Single-use portal redirect (magic link) token, a UUIDv7 sent to the account
+        # owner's email.
+        portal_redirect_token:,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Telnyx::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end