telnyx 5.130.0 → 5.131.0

data/rbi/telnyx/models/ai_search_conversation_histories_params.rbi

@@ -0,0 +1,319 @@
+# typed: strong
+
+module Telnyx
+  module Models
+    class AISearchConversationHistoriesParams < Telnyx::Internal::Type::BaseModel
+      extend Telnyx::Internal::Type::RequestParameters::Converter
+      include Telnyx::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            Telnyx::AISearchConversationHistoriesParams,
+            Telnyx::Internal::AnyHash
+          )
+        end
+
+      # Natural language search query. The text is embedded into a 1024-dimensional
+      # vector and compared against indexed record chunks using kNN cosine similarity.
+      sig { returns(String) }
+      attr_accessor :q
+
+      # The type of records to search. Each record type is stored in a separate vector
+      # index.
+      sig do
+        returns(
+          Telnyx::AISearchConversationHistoriesParams::RecordType::OrSymbol
+        )
+      end
+      attr_accessor :record_type
+
+      # Filter by document identifier (exact match). Populated for knowledge_base
+      # records.
+      sig { returns(T.nilable(String)) }
+      attr_reader :filter_document_id
+
+      sig { params(filter_document_id: String).void }
+      attr_writer :filter_document_id
+
+      # Only include records ingested (chunked, embedded, and indexed) on or after this
+      # ISO 8601 timestamp.
+      sig { returns(T.nilable(Time)) }
+      attr_reader :filter_ingested_at_gte
+
+      sig { params(filter_ingested_at_gte: Time).void }
+      attr_writer :filter_ingested_at_gte
+
+      # Only include records ingested (chunked, embedded, and indexed) on or before this
+      # ISO 8601 timestamp.
+      sig { returns(T.nilable(Time)) }
+      attr_reader :filter_ingested_at_lte
+
+      sig { params(filter_ingested_at_lte: Time).void }
+      attr_writer :filter_ingested_at_lte
+
+      # Only include records whose original creation time is on or after this ISO 8601
+      # timestamp.
+      sig { returns(T.nilable(Time)) }
+      attr_reader :filter_record_created_at_gte
+
+      sig { params(filter_record_created_at_gte: Time).void }
+      attr_writer :filter_record_created_at_gte
+
+      # Only include records whose original creation time is on or before this ISO 8601
+      # timestamp.
+      sig { returns(T.nilable(Time)) }
+      attr_reader :filter_record_created_at_lte
+
+      sig { params(filter_record_created_at_lte: Time).void }
+      attr_writer :filter_record_created_at_lte
+
+      # Filter to chunks belonging to a specific parent record (exact match).
+      sig { returns(T.nilable(String)) }
+      attr_reader :filter_record_id
+
+      sig { params(filter_record_id: String).void }
+      attr_writer :filter_record_id
+
+      # Filter by the region stored on the record. Comma-separated to match multiple
+      # regions (USA, DEU, AUS, UAE). Distinct from the `region` parameter, which
+      # selects which cluster(s) are queried.
+      sig { returns(T.nilable(String)) }
+      attr_reader :filter_region_in
+
+      sig { params(filter_region_in: String).void }
+      attr_writer :filter_region_in
+
+      # Filter by retention policy (exact match). Filter-only: not returned in the
+      # response body.
+      sig { returns(T.nilable(String)) }
+      attr_reader :filter_retention
+
+      sig { params(filter_retention: String).void }
+      attr_writer :filter_retention
+
+      # Filter to records owned by a specific user (exact match).
+      sig { returns(T.nilable(String)) }
+      attr_reader :filter_user_id
+
+      sig { params(filter_user_id: String).void }
+      attr_writer :filter_user_id
+
+      # Minimum cosine similarity score threshold (0.0 to 1.0). Results below this
+      # threshold are excluded.
+      sig { returns(T.nilable(Float)) }
+      attr_reader :min_score
+
+      sig { params(min_score: Float).void }
+      attr_writer :min_score
+
+      # Restrict search to a specific region's OpenSearch cluster. When omitted, all
+      # regions are queried in parallel (fan-out) and results are merged by cosine
+      # similarity score.
+      sig do
+        returns(
+          T.nilable(
+            Telnyx::AISearchConversationHistoriesParams::Region::OrSymbol
+          )
+        )
+      end
+      attr_reader :region
+
+      sig do
+        params(
+          region: Telnyx::AISearchConversationHistoriesParams::Region::OrSymbol
+        ).void
+      end
+      attr_writer :region
+
+      # Maximum number of results to return. Defaults to 20, maximum 100.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :top_k
+
+      sig { params(top_k: Integer).void }
+      attr_writer :top_k
+
+      sig do
+        params(
+          q: String,
+          record_type:
+            Telnyx::AISearchConversationHistoriesParams::RecordType::OrSymbol,
+          filter_document_id: String,
+          filter_ingested_at_gte: Time,
+          filter_ingested_at_lte: Time,
+          filter_record_created_at_gte: Time,
+          filter_record_created_at_lte: Time,
+          filter_record_id: String,
+          filter_region_in: String,
+          filter_retention: String,
+          filter_user_id: String,
+          min_score: Float,
+          region: Telnyx::AISearchConversationHistoriesParams::Region::OrSymbol,
+          top_k: Integer,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Natural language search query. The text is embedded into a 1024-dimensional
+        # vector and compared against indexed record chunks using kNN cosine similarity.
+        q:,
+        # The type of records to search. Each record type is stored in a separate vector
+        # index.
+        record_type:,
+        # Filter by document identifier (exact match). Populated for knowledge_base
+        # records.
+        filter_document_id: nil,
+        # Only include records ingested (chunked, embedded, and indexed) on or after this
+        # ISO 8601 timestamp.
+        filter_ingested_at_gte: nil,
+        # Only include records ingested (chunked, embedded, and indexed) on or before this
+        # ISO 8601 timestamp.
+        filter_ingested_at_lte: nil,
+        # Only include records whose original creation time is on or after this ISO 8601
+        # timestamp.
+        filter_record_created_at_gte: nil,
+        # Only include records whose original creation time is on or before this ISO 8601
+        # timestamp.
+        filter_record_created_at_lte: nil,
+        # Filter to chunks belonging to a specific parent record (exact match).
+        filter_record_id: nil,
+        # Filter by the region stored on the record. Comma-separated to match multiple
+        # regions (USA, DEU, AUS, UAE). Distinct from the `region` parameter, which
+        # selects which cluster(s) are queried.
+        filter_region_in: nil,
+        # Filter by retention policy (exact match). Filter-only: not returned in the
+        # response body.
+        filter_retention: nil,
+        # Filter to records owned by a specific user (exact match).
+        filter_user_id: nil,
+        # Minimum cosine similarity score threshold (0.0 to 1.0). Results below this
+        # threshold are excluded.
+        min_score: nil,
+        # Restrict search to a specific region's OpenSearch cluster. When omitted, all
+        # regions are queried in parallel (fan-out) and results are merged by cosine
+        # similarity score.
+        region: nil,
+        # Maximum number of results to return. Defaults to 20, maximum 100.
+        top_k: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            q: String,
+            record_type:
+              Telnyx::AISearchConversationHistoriesParams::RecordType::OrSymbol,
+            filter_document_id: String,
+            filter_ingested_at_gte: Time,
+            filter_ingested_at_lte: Time,
+            filter_record_created_at_gte: Time,
+            filter_record_created_at_lte: Time,
+            filter_record_id: String,
+            filter_region_in: String,
+            filter_retention: String,
+            filter_user_id: String,
+            min_score: Float,
+            region:
+              Telnyx::AISearchConversationHistoriesParams::Region::OrSymbol,
+            top_k: Integer,
+            request_options: Telnyx::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+
+      # The type of records to search. Each record type is stored in a separate vector
+      # index.
+      module RecordType
+        extend Telnyx::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(
+              Symbol,
+              Telnyx::AISearchConversationHistoriesParams::RecordType
+            )
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        VOICE =
+          T.let(
+            :voice,
+            Telnyx::AISearchConversationHistoriesParams::RecordType::TaggedSymbol
+          )
+        MESSAGE =
+          T.let(
+            :message,
+            Telnyx::AISearchConversationHistoriesParams::RecordType::TaggedSymbol
+          )
+        AI_PIPELINE_STORAGE =
+          T.let(
+            :ai_pipeline_storage,
+            Telnyx::AISearchConversationHistoriesParams::RecordType::TaggedSymbol
+          )
+        KNOWLEDGE_BASE =
+          T.let(
+            :knowledge_base,
+            Telnyx::AISearchConversationHistoriesParams::RecordType::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              Telnyx::AISearchConversationHistoriesParams::RecordType::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
+
+      # Restrict search to a specific region's OpenSearch cluster. When omitted, all
+      # regions are queried in parallel (fan-out) and results are merged by cosine
+      # similarity score.
+      module Region
+        extend Telnyx::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(Symbol, Telnyx::AISearchConversationHistoriesParams::Region)
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        USA =
+          T.let(
+            :USA,
+            Telnyx::AISearchConversationHistoriesParams::Region::TaggedSymbol
+          )
+        DEU =
+          T.let(
+            :DEU,
+            Telnyx::AISearchConversationHistoriesParams::Region::TaggedSymbol
+          )
+        AUS =
+          T.let(
+            :AUS,
+            Telnyx::AISearchConversationHistoriesParams::Region::TaggedSymbol
+          )
+        UAE =
+          T.let(
+            :UAE,
+            Telnyx::AISearchConversationHistoriesParams::Region::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              Telnyx::AISearchConversationHistoriesParams::Region::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/models/ai_search_conversation_histories_response.rbi

@@ -0,0 +1,393 @@
+# typed: strong
+
+module Telnyx
+  module Models
+    class AISearchConversationHistoriesResponse < Telnyx::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Telnyx::Models::AISearchConversationHistoriesResponse,
+            Telnyx::Internal::AnyHash
+          )
+        end
+
+      # Ranked list of matching text chunks, sorted by cosine similarity score
+      # descending.
+      sig do
+        returns(
+          T::Array[Telnyx::Models::AISearchConversationHistoriesResponse::Data]
+        )
+      end
+      attr_accessor :data
+
+      # Pagination metadata following the standard Telnyx V2 API format.
+      sig do
+        returns(Telnyx::Models::AISearchConversationHistoriesResponse::Meta)
+      end
+      attr_reader :meta
+
+      sig do
+        params(
+          meta:
+            Telnyx::Models::AISearchConversationHistoriesResponse::Meta::OrHash
+        ).void
+      end
+      attr_writer :meta
+
+      # Search response following the standard Telnyx V2 API format.
+      sig do
+        params(
+          data:
+            T::Array[
+              Telnyx::Models::AISearchConversationHistoriesResponse::Data::OrHash
+            ],
+          meta:
+            Telnyx::Models::AISearchConversationHistoriesResponse::Meta::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Ranked list of matching text chunks, sorted by cosine similarity score
+        # descending.
+        data:,
+        # Pagination metadata following the standard Telnyx V2 API format.
+        meta:
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            data:
+              T::Array[
+                Telnyx::Models::AISearchConversationHistoriesResponse::Data
+              ],
+            meta: Telnyx::Models::AISearchConversationHistoriesResponse::Meta
+          }
+        )
+      end
+      def to_hash
+      end
+
+      class Data < Telnyx::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Telnyx::Models::AISearchConversationHistoriesResponse::Data,
+              Telnyx::Internal::AnyHash
+            )
+          end
+
+        # Unique chunk identifier.
+        sig { returns(String) }
+        attr_accessor :id
+
+        # Zero-based index of this chunk within the parent record.
+        sig { returns(Integer) }
+        attr_accessor :chunk_index
+
+        # Total number of chunks the parent record was split into.
+        sig { returns(Integer) }
+        attr_accessor :chunk_total
+
+        # Document identifier. Present only for knowledge_base records; null for all other
+        # record types.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :document_id
+
+        # When the record was chunked, embedded, and indexed (ISO 8601).
+        sig { returns(Time) }
+        attr_accessor :ingested_at
+
+        # Identifier of the organization that owns this record.
+        sig { returns(String) }
+        attr_accessor :organization_id
+
+        # When the original record was created (ISO 8601).
+        sig { returns(Time) }
+        attr_accessor :record_created_at
+
+        # Identifier of the parent record. Multiple chunks from the same record share this
+        # ID.
+        sig { returns(String) }
+        attr_accessor :record_id
+
+        # Type of the record.
+        sig do
+          returns(
+            Telnyx::Models::AISearchConversationHistoriesResponse::Data::RecordType::TaggedSymbol
+          )
+        end
+        attr_accessor :record_type
+
+        # The region where this record is stored.
+        sig do
+          returns(
+            Telnyx::Models::AISearchConversationHistoriesResponse::Data::Region::TaggedSymbol
+          )
+        end
+        attr_accessor :region
+
+        # Cosine similarity score between the query vector and this chunk's vector. Higher
+        # values indicate greater semantic relevance.
+        sig { returns(Float) }
+        attr_accessor :score
+
+        # The text content of this chunk (up to 480 tokens).
+        sig { returns(String) }
+        attr_accessor :text
+
+        # Identifier of the user who owns this record.
+        sig { returns(String) }
+        attr_accessor :user_id
+
+        # Arbitrary metadata attached to the record at ingestion time. Stored as a
+        # flat_object in OpenSearch and filterable via filter[field]=value query
+        # parameters.
+        sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+        attr_reader :metadata
+
+        sig { params(metadata: T::Hash[Symbol, T.anything]).void }
+        attr_writer :metadata
+
+        # A single search result representing one chunk of a conversation history record.
+        # Records are split into chunks of up to 480 tokens with 64-token overlap at
+        # ingestion time.
+        sig do
+          params(
+            id: String,
+            chunk_index: Integer,
+            chunk_total: Integer,
+            document_id: T.nilable(String),
+            ingested_at: Time,
+            organization_id: String,
+            record_created_at: Time,
+            record_id: String,
+            record_type:
+              Telnyx::Models::AISearchConversationHistoriesResponse::Data::RecordType::OrSymbol,
+            region:
+              Telnyx::Models::AISearchConversationHistoriesResponse::Data::Region::OrSymbol,
+            score: Float,
+            text: String,
+            user_id: String,
+            metadata: T::Hash[Symbol, T.anything]
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # Unique chunk identifier.
+          id:,
+          # Zero-based index of this chunk within the parent record.
+          chunk_index:,
+          # Total number of chunks the parent record was split into.
+          chunk_total:,
+          # Document identifier. Present only for knowledge_base records; null for all other
+          # record types.
+          document_id:,
+          # When the record was chunked, embedded, and indexed (ISO 8601).
+          ingested_at:,
+          # Identifier of the organization that owns this record.
+          organization_id:,
+          # When the original record was created (ISO 8601).
+          record_created_at:,
+          # Identifier of the parent record. Multiple chunks from the same record share this
+          # ID.
+          record_id:,
+          # Type of the record.
+          record_type:,
+          # The region where this record is stored.
+          region:,
+          # Cosine similarity score between the query vector and this chunk's vector. Higher
+          # values indicate greater semantic relevance.
+          score:,
+          # The text content of this chunk (up to 480 tokens).
+          text:,
+          # Identifier of the user who owns this record.
+          user_id:,
+          # Arbitrary metadata attached to the record at ingestion time. Stored as a
+          # flat_object in OpenSearch and filterable via filter[field]=value query
+          # parameters.
+          metadata: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              id: String,
+              chunk_index: Integer,
+              chunk_total: Integer,
+              document_id: T.nilable(String),
+              ingested_at: Time,
+              organization_id: String,
+              record_created_at: Time,
+              record_id: String,
+              record_type:
+                Telnyx::Models::AISearchConversationHistoriesResponse::Data::RecordType::TaggedSymbol,
+              region:
+                Telnyx::Models::AISearchConversationHistoriesResponse::Data::Region::TaggedSymbol,
+              score: Float,
+              text: String,
+              user_id: String,
+              metadata: T::Hash[Symbol, T.anything]
+            }
+          )
+        end
+        def to_hash
+        end
+
+        # Type of the record.
+        module RecordType
+          extend Telnyx::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                Telnyx::Models::AISearchConversationHistoriesResponse::Data::RecordType
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          VOICE =
+            T.let(
+              :voice,
+              Telnyx::Models::AISearchConversationHistoriesResponse::Data::RecordType::TaggedSymbol
+            )
+          MESSAGE =
+            T.let(
+              :message,
+              Telnyx::Models::AISearchConversationHistoriesResponse::Data::RecordType::TaggedSymbol
+            )
+          AI_PIPELINE_STORAGE =
+            T.let(
+              :ai_pipeline_storage,
+              Telnyx::Models::AISearchConversationHistoriesResponse::Data::RecordType::TaggedSymbol
+            )
+          KNOWLEDGE_BASE =
+            T.let(
+              :knowledge_base,
+              Telnyx::Models::AISearchConversationHistoriesResponse::Data::RecordType::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Telnyx::Models::AISearchConversationHistoriesResponse::Data::RecordType::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+
+        # The region where this record is stored.
+        module Region
+          extend Telnyx::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                Telnyx::Models::AISearchConversationHistoriesResponse::Data::Region
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          USA =
+            T.let(
+              :USA,
+              Telnyx::Models::AISearchConversationHistoriesResponse::Data::Region::TaggedSymbol
+            )
+          DEU =
+            T.let(
+              :DEU,
+              Telnyx::Models::AISearchConversationHistoriesResponse::Data::Region::TaggedSymbol
+            )
+          AUS =
+            T.let(
+              :AUS,
+              Telnyx::Models::AISearchConversationHistoriesResponse::Data::Region::TaggedSymbol
+            )
+          UAE =
+            T.let(
+              :UAE,
+              Telnyx::Models::AISearchConversationHistoriesResponse::Data::Region::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Telnyx::Models::AISearchConversationHistoriesResponse::Data::Region::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+
+      class Meta < Telnyx::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Telnyx::Models::AISearchConversationHistoriesResponse::Meta,
+              Telnyx::Internal::AnyHash
+            )
+          end
+
+        # Current page number (always 1 — this API does not support pagination, use top_k
+        # instead).
+        sig { returns(Integer) }
+        attr_accessor :page_number
+
+        # Number of results per page (equals the effective top_k value).
+        sig { returns(Integer) }
+        attr_accessor :page_size
+
+        # Total number of pages.
+        sig { returns(Integer) }
+        attr_accessor :total_pages
+
+        # Total number of matching results across all queried regions (before top_k
+        # truncation).
+        sig { returns(Integer) }
+        attr_accessor :total_results
+
+        # Pagination metadata following the standard Telnyx V2 API format.
+        sig do
+          params(
+            page_number: Integer,
+            page_size: Integer,
+            total_pages: Integer,
+            total_results: Integer
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # Current page number (always 1 — this API does not support pagination, use top_k
+          # instead).
+          page_number:,
+          # Number of results per page (equals the effective top_k value).
+          page_size:,
+          # Total number of pages.
+          total_pages:,
+          # Total number of matching results across all queried regions (before top_k
+          # truncation).
+          total_results:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              page_number: Integer,
+              page_size: Integer,
+              total_pages: Integer,
+              total_results: Integer
+            }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end