ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/ruby_llm/providers/bedrock/models.rb

@@ -7,7 +7,10 @@ module RubyLLM
       module Models
         module_function
 
-        REGION_PREFIXES = %w[global us eu ap sa ca me af il].freeze
+        JP_REGIONS = %w[ap-northeast-1 ap-northeast-3].freeze
+        AU_REGIONS = %w[ap-southeast-2 ap-southeast-4].freeze
+
+        MANTLE_ENDPOINT = 'mantle'
 
         def models_api_base
           @config.bedrock_api_base || "https://bedrock.#{bedrock_region}.amazonaws.com"
@@ -17,24 +20,104 @@ module RubyLLM
           '/foundation-models'
         end
 
-        def parse_list_models_response(response, slug, _capabilities)
+        def mantle_models_url
+          'v1/models'
+        end
+
+        def models_dev_alias(model_id, models_dev_by_key, _provider_model = nil)
+          normalized_id = model_id.sub(/^[a-z]{2}\./, '')
+          context_override = nil
+          normalized_id = normalized_id.gsub(/:(\d+)k\b/) do
+            context_override = Regexp.last_match(1).to_i * 1000
+            ''
+          end
+          source = models_dev_by_key["bedrock:#{normalized_id}"]
+          return unless source
+
+          data = source.to_h.merge(id: model_id)
+          data[:context_window] = context_override if context_override
+          Model.new(data)
+        end
+
+        # The mantle catalog reports ids and nothing else, so entries carry
+        # only what the endpoint states. models.dev fills in limits and
+        # pricing for the ids it knows during a registry refresh.
+        def parse_mantle_models_response(response, slug)
+          Array(response.body['data']).map do |model_data|
+            Model.new(
+              id: model_data['id'],
+              name: model_data['id'],
+              provider: slug,
+              created_at: mantle_created_at(model_data['created']),
+              modalities: { input: ['text'], output: ['text'] },
+              capabilities: ['streaming'],
+              metadata: { endpoint: MANTLE_ENDPOINT }
+            )
+          end
+        end
+
+        # Models both catalogs list keep their Converse metadata and gain the
+        # mantle tag, because mantle is where RubyLLM sends them.
+        def merge_mantle_models(converse_models, mantle_models)
+          by_id = converse_models.to_h { |model| [model.id, model] }
+
+          tagged = mantle_models.map do |model|
+            listed = by_id.delete(model.id)
+            listed ? tag_mantle_endpoint(listed) : model
+          end
+
+          by_id.values + tagged
+        end
+
+        def tag_mantle_endpoint(model)
+          data = model.to_h
+          Model.new(data.merge(metadata: data[:metadata].merge(endpoint: MANTLE_ENDPOINT)))
+        end
+
+        def mantle_created_at(created)
+          Time.at(created).utc if created.is_a?(Numeric)
+        end
+
+        def parse_list_models_response(response, slug, profile_ids: [])
           Array(response.body['modelSummaries']).map do |model_data|
-            create_model_info(model_data, slug)
+            create_model_info(model_data, slug, profile_ids:)
+          end
+        end
+
+        # The region's actual cross-region inference profile ids. Some
+        # geography prefixes cannot be synthesized from the region alone:
+        # Tokyo serves both apac. and jp. profiles.
+        def inference_profile_ids
+          ids = []
+          token = nil
+
+          loop do
+            url = +'/inference-profiles?maxResults=1000&typeEquals=SYSTEM_DEFINED'
+            url << "&nextToken=#{URI.encode_www_form_component(token)}" if token
+            body = signed_get(models_api_base, url).body
+            ids.concat(Array(body['inferenceProfileSummaries']).map { |summary| summary['inferenceProfileId'] })
+            token = body['nextToken']
+            break unless token
           end
+
+          ids.compact
+        rescue StandardError => e
+          RubyLLM.logger.debug { "Error fetching Bedrock inference profiles: #{e.message}" }
+          []
         end
 
-        def create_model_info(model_data, slug, _capabilities = nil)
-          model_id = model_id_with_region(model_data['modelId'], model_data)
+        def create_model_info(model_data, slug, _capabilities = nil, profile_ids: [])
+          model_id = model_id_with_region(model_data['modelId'], model_data, profile_ids)
           converse_data = model_data['converse'] || {}
 
-          Model::Info.new(
+          Model.new(
             id: model_id,
             name: model_data['modelName'],
             provider: slug,
             family: model_data['modelFamily'] || model_data['providerName']&.downcase,
             created_at: nil,
             context_window: parse_context_window(model_data),
-            max_output_tokens: converse_data['maxTokensDefault'] || converse_data['maxTokensMaximum'],
+            max_output_tokens: converse_data['maxTokensMaximum'] || converse_data['maxTokensDefault'],
             modalities: {
               input: normalize_modalities(model_data['inputModalities']),
               output: normalize_modalities(model_data['outputModalities'])
@@ -50,36 +133,123 @@ module RubyLLM
           )
         end
 
-        def model_id_with_region(model_id, model_data)
+        def model_id_with_region(model_id, model_data, profile_ids = [])
           inference_types = Array(model_data['inferenceTypesSupported'])
-          normalize_inference_profile_id(model_id, inference_types, @config.bedrock_region)
+          return model_id unless inference_profile_only?(inference_types)
+
+          listed_profile_id(model_id, profile_ids) || with_region_prefix(model_id, @config.bedrock_region)
+        end
+
+        def listed_profile_id(model_id, profile_ids)
+          candidates = profile_ids.select { |profile_id| profile_id.end_with?(".#{model_id}") }
+          preferred = region_prefix_candidates(@config.bedrock_region).filter_map do |prefix|
+            candidates.find { |profile_id| profile_id == "#{prefix}.#{model_id}" }
+          end.first
+
+          preferred || candidates.first
+        end
+
+        # Which endpoint serves a model is a fact about the catalogs, not
+        # about the id: mantle spells some Converse models differently and
+        # lists models Converse has never heard of. The registry records it,
+        # so ask the registry first and read the id only for models it does
+        # not list.
+        #
+        # Claude is the exception. Converse only ever serves it under a dated
+        # and versioned id, so a bare anthropic. id means mantle even on
+        # accounts whose catalog listing hides Claude behind the AWS Sales
+        # agreement.
+        def mantle_model?(model_id, models)
+          return mantle_model_id?(model_id) if model_id.start_with?('anthropic.')
+
+          listed = registered_model(model_id, models)
+          return listed.metadata[:endpoint].to_s == MANTLE_ENDPOINT if listed
+
+          mantle_model_id?(model_id)
+        end
+
+        def registered_model(model_id, models)
+          models.all_including_unlisted.find { |model| model.provider == 'bedrock' && model.id == model_id }
+        end
+
+        # The bedrock-mantle endpoint serves bare vendor.model ids under
+        # exactly that id. Converse ids carry a date or :N version suffix, a
+        # cross-region inference prefix, or both.
+        def mantle_model_id?(model_id)
+          return false if model_id.include?(':') || model_id.match?(/\d{8}/)
+          return false if region_prefixed?(model_id)
+
+          model_id.include?('.')
+        end
+
+        def resolve_registry_id(model_id, models, config)
+          region = config.bedrock_region.to_s
+          return model_id if region.empty?
+          return model_id if mantle_model_id?(model_id)
+
+          candidate = registered_profile_candidate(model_id, models, region)
+          return model_id unless candidate
+
+          inference_types = Array(candidate.metadata[:inference_types] || candidate.metadata['inference_types'])
+          inference_profile_only?(inference_types) ? candidate.id : model_id
+        end
+
+        def registered_profile_candidate(model_id, models, region)
+          region_prefix_candidates(region).each do |prefix|
+            prefixed = prefixed_with(model_id, prefix)
+            next if prefixed == model_id
+
+            candidate = models.all_including_unlisted.find { |m| m.provider == 'bedrock' && m.id == prefixed }
+            return candidate if candidate
+          end
+
+          nil
+        end
+
+        def inference_profile_only?(inference_types)
+          inference_types.include?('INFERENCE_PROFILE') && !inference_types.include?('ON_DEMAND')
         end
 
         def normalize_inference_profile_id(model_id, inference_types, region)
-          return model_id unless inference_types.include?('INFERENCE_PROFILE')
-          return model_id if inference_types.include?('ON_DEMAND')
+          return model_id unless inference_profile_only?(inference_types)
 
           with_region_prefix(model_id, region)
         end
 
         def with_region_prefix(model_id, region)
-          prefix = region_prefix(region)
+          prefixed_with(model_id, region_prefix(region))
+        end
 
+        def prefixed_with(model_id, prefix)
           if region_prefixed?(model_id)
-            model_id.sub(/\A(?:#{REGION_PREFIXES.join('|')})\./, "#{prefix}.")
+            model_id.sub(/\A(?:#{Protocols::Converse::REGION_PREFIXES.join('|')})\./, "#{prefix}.")
           else
             "#{prefix}.#{model_id}"
           end
         end
 
+        # Inference profile ids use geography prefixes, not region name
+        # segments: ap-* regions are apac., GovCloud is us-gov.
         def region_prefix(region)
-          prefix = region.to_s.split('-').first
-          prefix = '' if prefix.nil?
-          prefix.empty? ? 'us' : prefix
+          region = region.to_s
+          return 'us' if region.empty?
+          return 'us-gov' if region.start_with?('us-gov')
+
+          geography = region.split('-').first
+          geography == 'ap' ? 'apac' : geography
+        end
+
+        # Countries with their own residency-preserving profiles come before
+        # the broad geography, so Tokyo prefers jp. over apac. Some models
+        # ship with only a global. profile, so that is the last resort.
+        def region_prefix_candidates(region)
+          region = region.to_s
+          specific = ('jp' if JP_REGIONS.include?(region)) || ('au' if AU_REGIONS.include?(region))
+          [specific, region_prefix(region), 'global'].compact
         end
 
         def region_prefixed?(model_id)
-          model_id.match?(/\A(?:#{REGION_PREFIXES.join('|')})\./)
+          model_id.match?(/\A(?:#{Protocols::Converse::REGION_PREFIXES.join('|')})\./)
         end
 
         def normalize_modalities(modalities)
@@ -93,40 +263,22 @@ module RubyLLM
           end
         end
 
+        # A summary's converse block is metadata Bedrock fills in for some
+        # models, not a statement that Converse serves them: Nova Lite,
+        # Llama 3.3 and Mistral Large take tool calls without one. Whether
+        # Converse accepts the model at all is the closest thing the listing
+        # has to a tool-use flag.
         def parse_capabilities(model_data)
           capabilities = []
           capabilities << 'streaming' if model_data['responseStreamingSupported']
 
           converse = model_data['converse'] || {}
-          capabilities << 'function_calling' if converse.is_a?(Hash)
+          capabilities << 'function_calling' if model_data.dig('inferenceAPIsSupported', 'converse', 'sync')
           capabilities << 'reasoning' if converse.dig('reasoningSupported', 'embedded')
-          capabilities << 'structured_output' if supports_structured_output?(model_data['modelId'])
 
           capabilities
         end
 
-        # Structured output supported on Claude 4.5+ and assumed for future major versions.
-        # Bedrock IDs look like: us.anthropic.claude-haiku-4-5-20251001-v1:0
-        # Must handle optional region prefix (us./eu./global.) and anthropic. prefix.
-        def supports_structured_output?(model_id)
-          return false unless model_id
-
-          normalized = model_id.sub(/\A(?:#{REGION_PREFIXES.join('|')})\./, '').delete_prefix('anthropic.')
-          match = normalized.match(/claude-(?:opus|sonnet|haiku)-(\d+)-(\d{1,2})(?:\b|-)/)
-          return false unless match
-
-          major = match[1].to_i
-          minor = match[2].to_i
-          major > 4 || (major == 4 && minor >= 5)
-        end
-
-        def reasoning_embedded?(model)
-          metadata = RubyLLM::Utils.deep_symbolize_keys(model.metadata || {})
-          converse = metadata[:converse] || {}
-          reasoning_supported = converse[:reasoningSupported] || {}
-          reasoning_supported[:embedded] || false
-        end
-
         def parse_context_window(model_data)
           value = model_data.dig('description', 'maxContextWindow')
           return unless value.is_a?(String)

data/lib/ruby_llm/providers/bedrock.rb

@@ -2,97 +2,268 @@
 
 module RubyLLM
   module Providers
-    # AWS Bedrock Converse API integration.
+    # AWS Bedrock integration.
     class Bedrock < Provider
       include Bedrock::Auth
-      include Bedrock::Chat
-      include Bedrock::Media
       include Bedrock::Models
-      include Bedrock::Streaming
+
+      protocol :converse, Protocols::Converse, batches: Protocols::Converse::Batches
+      protocol :mantle_anthropic, Bedrock::Mantle::Anthropic
+      protocol :mantle_responses, Bedrock::Mantle::Responses
+      protocol :mantle_chat_completions, Bedrock::Mantle::ChatCompletions
+      protocol :voxtral_transcription, Bedrock::Mantle::Voxtral
+      protocol :titan_text_embeddings, Protocols::InvokeModel::TitanTextEmbeddings,
+               batches: Protocols::InvokeModel::EmbeddingBatches
+      protocol :titan_multimodal_embeddings, Protocols::InvokeModel::TitanMultimodalEmbeddings,
+               batches: Protocols::InvokeModel::EmbeddingBatches
+      protocol :cohere_embeddings, Protocols::InvokeModel::CohereEmbeddings
+      protocol :nova_embeddings, Protocols::InvokeModel::NovaEmbeddings
+      protocol :stability_images, Protocols::InvokeModel::StabilityImages
+      protocol :rerank, Protocols::Bedrock::Rerank
+      protocol :guardrails, Protocols::Bedrock::Guardrails
+      protocol :async_videos, Protocols::Bedrock::AsyncVideos
+      protocol :files, Protocols::Bedrock::Files
+
+      def self.capabilities
+        Bedrock::Capabilities
+      end
+
+      def self.resolve_registry_id(model_id, models, config = RubyLLM.config)
+        Models.resolve_registry_id(model_id, models, config)
+      end
+
+      def self.models_dev_alias(...)
+        Models.models_dev_alias(...)
+      end
+
+      def protocol_for(model, operation: nil, **)
+        return protocols[:guardrails] if operation == :moderate
+
+        model_id = model_id_for(model)
+        return embedding_protocol_for(model_id) if operation == :embed
+        return image_protocol_for(model_id) if operation == :paint
+        return protocols[:rerank] if operation == :rerank
+        return video_protocol_for(model_id) if operation == :animate
+        return protocols[:voxtral_transcription] if voxtral_transcription?(operation, model_id)
+        return mantle_protocol_for(model_id) if mantle_model?(model_id)
+
+        super
+      end
+
+      # Un-versioned ids such as anthropic.claude-sonnet-5 and
+      # openai.gpt-oss-20b are served by the bedrock-mantle endpoint rather
+      # than by Converse.
+      def mantle_model?(model_id)
+        Models.mantle_model?(model_id, RubyLLM.models)
+      end
+
+      def mantle_api_base
+        @config.bedrock_mantle_api_base || "https://bedrock-mantle.#{bedrock_region}.api.aws"
+      end
+
+      def mantle_connection
+        @mantle_connection ||= Transport::Connection.new(self, @config, api_base: mantle_api_base)
+      end
 
       def api_base
         @config.bedrock_api_base || "https://bedrock-runtime.#{bedrock_region}.amazonaws.com"
       end
 
+      def control_api_base
+        @config.bedrock_api_base || "https://bedrock.#{bedrock_region}.amazonaws.com"
+      end
+
+      def agent_api_base # :nodoc:
+        @config.bedrock_api_base || "https://bedrock-agent-runtime.#{bedrock_region}.amazonaws.com"
+      end
+
+      def agent_connection # :nodoc:
+        @agent_connection ||= Transport::Connection.new(self, @config, api_base: agent_api_base)
+      end
+
+      def rerank_model_arn(model_id) # :nodoc:
+        return model_id if model_id.start_with?('arn:')
+
+        unless %w[amazon.rerank-v1:0 cohere.rerank-v3-5:0].include?(model_id)
+          raise Error, "Bedrock reranking is not supported for #{model_id.inspect}"
+        end
+
+        "arn:aws:bedrock:#{bedrock_region}::foundation-model/#{model_id}"
+      end
+
       def headers
         {}
       end
 
-      # rubocop:disable Metrics/ParameterLists
-      def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, thinking: nil,
-                   tool_prefs: nil, &)
-        normalized_params = normalize_params(params, model:)
+      def guardrail_url # :nodoc:
+        identifier = @config.bedrock_guardrail_id
+        version = @config.bedrock_guardrail_version
+        if identifier.to_s.empty? || version.to_s.empty?
+          raise ConfigurationError, 'Bedrock moderation requires bedrock_guardrail_id and bedrock_guardrail_version'
+        end
+
+        identifier = URI.encode_www_form_component(identifier)
+        version = URI.encode_www_form_component(version)
+        "/guardrail/#{identifier}/version/#{version}/apply"
+      end
+
+      def batch_cost_multiplier(**) = 0.5
 
-        super(
-          messages,
-          tools: tools,
-          tool_prefs: tool_prefs,
-          temperature: temperature,
-          model: model,
-          params: normalized_params,
-          headers: headers,
-          schema: schema,
-          thinking: thinking,
-          &
-        )
+      def embedding_batch_protocol(model_id) # :nodoc:
+        case model_id
+        when 'amazon.titan-embed-text-v2:0' then protocols[:titan_text_embeddings]
+        when 'amazon.titan-embed-image-v1' then protocols[:titan_multimodal_embeddings]
+        end
       end
-      # rubocop:enable Metrics/ParameterLists
 
       def parse_error(response)
-        return if response.body.nil? || response.body.empty?
+        body = parse_error_body(response)
+        return unless body
+        return super unless body.is_a?(Hash)
 
-        body = try_parse_json(response.body)
-        return body if body.is_a?(String)
+        body['message'] || body['Message'] || nested_error_message(body) || body['__type'] || super
+      end
 
-        body['message'] || body['Message'] || body['error'] || body['__type'] || super
+      # bedrock-mantle nests code, message, and type under "error" rather
+      # than answering with a bare string.
+      def nested_error_message(body)
+        error = body['error']
+        error.is_a?(Hash) ? error['message'] || error : error
       end
 
       def list_models
-        response = signed_get(models_api_base, models_url)
-        parse_list_models_response(response, slug, capabilities)
+        merge_mantle_models(list_converse_models, list_mantle_models)
       end
 
       class << self
         def configuration_options
-          %i[bedrock_api_key bedrock_secret_key bedrock_region bedrock_session_token bedrock_api_base]
+          %i[
+            bedrock_api_key
+            bedrock_secret_key
+            bedrock_region
+            bedrock_session_token
+            bedrock_credential_provider
+            bedrock_api_base
+            bedrock_mantle_api_base
+            bedrock_batch_s3_uri
+            bedrock_batch_role_arn
+            bedrock_video_s3_uri
+            bedrock_guardrail_id
+            bedrock_guardrail_version
+          ]
         end
 
         def configuration_requirements
-          %i[bedrock_api_key bedrock_secret_key bedrock_region]
+          %i[bedrock_region]
+        end
+
+        def model_required?(operation:)
+          operation != :moderate
+        end
+
+        def configured?(config)
+          !!(config.bedrock_region && credentials_configured?(config))
+        end
+
+        def credentials_configured?(config)
+          return credential_provider?(config) if config.bedrock_credential_provider
+
+          !!(config.bedrock_api_key && config.bedrock_secret_key)
         end
+
+        private
+
+        def credential_provider?(config)
+          config.bedrock_credential_provider&.respond_to?(:credentials)
+        end
+      end
+
+      def ensure_configured!
+        return if configured?
+
+        missing = []
+        missing << :bedrock_region unless @config.bedrock_region
+        missing << bedrock_credentials_requirement unless self.class.credentials_configured?(@config)
+
+        raise ConfigurationError, "Missing configuration for Bedrock: #{missing.join(', ')}"
       end
 
       private
 
+      def voxtral_transcription?(operation, model_id)
+        operation == :transcribe && model_id == 'mistral.voxtral-small-24b-2507'
+      end
+
+      def batch_protocol_for(requests)
+        return super unless requests.any? { |request| request.key?(:text) }
+
+        kinds = requests.map { |request| embedding_batch_protocol(request.fetch(:model)) }.uniq
+        unless requests.all? { |request| request.key?(:text) } && kinds.one? && kinds.first
+          raise Error, 'Bedrock embedding batches require one supported Titan embedding model'
+        end
+
+        kinds.first
+      end
+
       def bedrock_region
         @config.bedrock_region
       end
 
-      def sync_response(connection, payload, additional_headers = {})
-        signed_post(connection, completion_url, payload, additional_headers)
+      def bedrock_credentials_requirement
+        if @config.bedrock_credential_provider
+          'bedrock_credential_provider responding to #credentials'
+        else
+          'bedrock_credential_provider or bedrock_api_key + bedrock_secret_key'
+        end
+      end
+
+      def list_converse_models
+        parse_list_models_response(signed_get(models_api_base, models_url), slug, profile_ids: inference_profile_ids)
+      end
+
+      def list_mantle_models
+        response = signed_get(mantle_api_base, mantle_models_url, service: Bedrock::Mantle::SIGNING_SERVICE)
+        parse_mantle_models_response(response, slug)
       end
 
-      def normalize_params(params, model:)
-        normalized = RubyLLM::Utils.deep_symbolize_keys(params || {})
-        additional_fields = normalized[:additionalModelRequestFields] || {}
+      def mantle_protocol_for(model_id)
+        return protocols[:mantle_anthropic] if model_id.start_with?('anthropic.')
+        return protocols[:mantle_responses] if Bedrock::Mantle::RESPONSES_MODELS.include?(model_id)
+
+        protocols[:mantle_chat_completions]
+      end
 
-        top_k = normalized.delete(:top_k)
-        if !top_k.nil? && model_supports_top_k?(model)
-          additional_fields = RubyLLM::Utils.deep_merge(additional_fields, { top_k: top_k })
+      def embedding_protocol_for(model_id)
+        case model_id
+        when bedrock_model_id_pattern('amazon.titan-embed-image')
+          protocols[:titan_multimodal_embeddings]
+        when bedrock_model_id_pattern('amazon.titan-embed-g1-text'),
+             bedrock_model_id_pattern('amazon.titan-embed-text')
+          protocols[:titan_text_embeddings]
+        when bedrock_model_id_pattern('cohere.embed')
+          protocols[:cohere_embeddings]
+        when bedrock_model_id_pattern('amazon.nova-2-multimodal-embeddings')
+          protocols[:nova_embeddings]
+        else
+          raise Error, "Bedrock embeddings are not supported for #{model_id.inspect}"
         end
+      end
 
-        normalized[:additionalModelRequestFields] = additional_fields unless additional_fields.empty?
-        normalized
+      def image_protocol_for(model_id)
+        base_id = model_id.sub(/\A(?:#{Protocols::Converse::REGION_PREFIXES.join('|')})\./, '')
+        return protocols[:stability_images] if Protocols::InvokeModel::StabilityImages::MODELS.include?(base_id)
+
+        raise Error, "Bedrock image generation is not supported for #{model_id.inspect}"
       end
 
-      def model_supports_top_k?(model)
-        Bedrock::Models.reasoning_embedded?(model)
+      def video_protocol_for(model_id)
+        return protocols[:async_videos] if model_id == 'luma.ray-v2:0'
+
+        raise Error, "Bedrock video generation is not supported for #{model_id.inspect}"
       end
 
-      def api_payload(payload)
-        cleaned = RubyLLM::Utils.deep_symbolize_keys(RubyLLM::Utils.deep_dup(payload))
-        cleaned.delete(:tools)
-        cleaned
+      def bedrock_model_id_pattern(prefix)
+        /\A(?:(?:#{Protocols::Converse::REGION_PREFIXES.join('|')})\.)?#{Regexp.escape(prefix)}/
       end
     end
   end

data/lib/ruby_llm/providers/cohere.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # Cohere API integration.
+    class Cohere < Provider
+      protocol :cohere, Protocols::Cohere
+      protocol :files, Protocols::Cohere::Datasets
+
+      def api_base
+        @config.cohere_api_base || 'https://api.cohere.com'
+      end
+
+      def headers
+        {
+          'Authorization' => "Bearer #{@config.cohere_api_key}"
+        }
+      end
+
+      class << self
+        def configuration_options
+          %i[cohere_api_key cohere_api_base]
+        end
+
+        def configuration_requirements
+          %i[cohere_api_key]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/deepgram.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # Integrates Deepgram transcription and speech synthesis.
+    class Deepgram < Provider
+      protocol :deepgram, Protocols::Deepgram
+
+      def api_base
+        @config.deepgram_api_base || 'https://api.deepgram.com'
+      end
+
+      def headers
+        { 'Authorization' => "Token #{@config.deepgram_api_key}" }
+      end
+
+      # Deepgram reports failures as an err_msg alongside an err_code, which
+      # the generic error parser does not know to look for.
+      def parse_error(response)
+        body = parse_error_body(response)
+        return super unless body.is_a?(Hash)
+
+        body['err_msg'] || super
+      end
+
+      class << self
+        def configuration_options
+          %i[deepgram_api_key deepgram_api_base]
+        end
+
+        def configuration_requirements
+          %i[deepgram_api_key]
+        end
+      end
+    end
+  end
+end