substrate 0.1.0 → 0.2.0

data/lib/substrate/primitives/transcripts/word.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Substrate
+  module Transcripts
+    Word = Data.define(
+      :text,
+      :start,
+      :end,
+      :confidence,
+      :speaker
+    ) do
+      def initialize(
+        text:,
+        start:,
+        end:,
+        confidence: nil,
+        speaker: nil
+      )
+        super
+      end
+    end
+  end
+end

data/lib/substrate/primitives/url_candidate.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Substrate
+  UrlCandidate = Data.define(
+    :id,
+    :kind,
+    :source,
+    :rank,
+    :confidence,
+    :label,
+    :metadata
+  )
+end

data/lib/substrate/source_ref.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Substrate
+  SourceRef = Data.define(:kind, :locator)
+end

data/lib/substrate/sources/article.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Substrate
+  module Sources
+    class Article
+      def initialize(url:, text:, title:, metadata:)
+        @url = url
+        @text = text
+        @title = title
+        @metadata = metadata
+      end
+
+      def source_ref
+        @source_ref ||= SourceRef.new(
+          kind: :article,
+          locator: metadata.final_url || url
+        )
+      end
+
+      def body
+        ArticleContent.new(
+          source_ref: source_ref,
+          text: text,
+          title: title,
+          metadata: metadata
+        )
+      end
+
+      private
+
+      attr_reader :url, :text, :title, :metadata
+    end
+  end
+end

data/lib/substrate/sources/audio.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Substrate
+  module Sources
+    class Audio
+      class TranscriptionError < StandardError; end
+
+      DEFAULT_PROVIDER = :deepgram
+
+      def initialize(path, provider: DEFAULT_PROVIDER, **options)
+        @path = path
+        @provider = provider
+        @options = options
+      end
+
+      def source_ref
+        @source_ref ||= SourceRef.new(kind: :audio, locator: path)
+      end
+
+      def body
+        @body ||= begin
+          transcribe
+        rescue TranscriptionError => e
+          raise TranscriptionError, e.message
+        end
+      end
+
+      def select_time_range(range)
+        result = Transcripts::SelectTimeRange.call(content: body, range: range)
+        raise result.error if result.failure?
+
+        result.payload
+      end
+
+      private
+
+      attr_reader :path, :provider, :options
+
+      def transcribe
+        provider_class = resolve_provider(provider)
+        result = provider_class.call(path: path, **options)
+        raise TranscriptionError, result.error.message unless result.success?
+
+        result.payload
+      end
+
+      def resolve_provider(name)
+        case name
+        when :deepgram then Transcribers::Deepgram
+        when :whisper_cpp then Transcribers::WhisperCpp
+        else
+          raise ArgumentError, "Unknown transcription provider: #{name}"
+        end
+      end
+    end
+  end
+end

data/lib/substrate/sources/pdf.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Substrate
+  module Sources
+    class Pdf
+      def initialize(path)
+        @path = path
+      end
+
+      def source_ref
+        @source_ref ||= SourceRef.new(kind: :pdf, locator: path)
+      end
+
+      def chapters
+        document.chapters
+      end
+
+      def page_count
+        document.page_count
+      end
+
+      def select_pages(range)
+        PageCollection.new(source_ref: source_ref, pages: range)
+      end
+
+      private
+
+      attr_reader :path
+
+      def document
+        @document ||= Mediums::Pdf::Document.new(path, source_ref: source_ref)
+      end
+    end
+  end
+end

data/lib/substrate/sources/text.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Substrate
+  module Sources
+    class Text
+      def initialize(path)
+        @path = path
+      end
+
+      def source_ref
+        @source_ref ||= SourceRef.new(kind: :text, locator: path)
+      end
+
+      def body
+        TextContent.new(source_ref: source_ref, text: File.read(path))
+      end
+
+      private
+
+      attr_reader :path
+    end
+  end
+end

data/lib/substrate/sources/url.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Substrate
+  module Sources
+    class Url
+      class ResolutionError < StandardError; end
+
+      def initialize(url)
+        @url = url
+      end
+
+      def source_ref
+        @source_ref ||= SourceRef.new(kind: :url, locator: url)
+      end
+
+      def candidates
+        @candidates ||= begin
+          result = UrlResolvers::ResolverFor.call(url: url)
+          raise ResolutionError, result.error.message unless result.success?
+
+          result.payload
+        end
+      end
+
+      def primary_candidate
+        candidates.min_by(&:rank)
+      end
+
+      private
+
+      attr_reader :url
+    end
+  end
+end

data/lib/substrate/transcribers/deepgram/client.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+
+module Substrate
+  module Transcribers
+    class Deepgram
+      class Client
+        class Error < StandardError; end
+
+        BASE_URL = "https://api.deepgram.com"
+        RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+        MAX_RETRIES = 3
+        DEFAULT_TIMEOUT = 120
+
+        def initialize(api_key:, timeout: DEFAULT_TIMEOUT, retry_interval: 1)
+          @api_key = api_key
+          @connection = build_connection(timeout: timeout, retry_interval: retry_interval)
+        end
+
+        def transcribe(path:, params:)
+          response = connection.post("/v1/listen", File.binread(path)) do |req|
+            req.headers["Content-Type"] = content_type(path)
+            req.params = params
+          end
+
+          raise Error, "API error: #{response.status} #{response.body}" unless response.success?
+
+          response.body
+        rescue Faraday::Error => e
+          raise Error, "Request failed: #{e.message}"
+        end
+
+        private
+
+        attr_reader :connection, :api_key
+
+        def build_connection(timeout:, retry_interval:)
+          Faraday.new(url: BASE_URL) do |f|
+            f.response :raise_error
+            f.response :json, content_type: /\bjson$/
+
+            f.request :retry,
+              max: MAX_RETRIES,
+              interval: retry_interval,
+              backoff_factor: 2,
+              retry_statuses: RETRYABLE_STATUSES
+
+            f.headers["Authorization"] = "Token #{api_key}"
+
+            f.options.timeout = timeout
+            f.options.open_timeout = timeout / 2
+          end
+        end
+
+        def content_type(path)
+          case File.extname(path).downcase
+          when ".mp3" then "audio/mp3"
+          when ".wav" then "audio/wav"
+          when ".m4a" then "audio/m4a"
+          when ".ogg" then "audio/ogg"
+          when ".flac" then "audio/flac"
+          else "audio/mp3"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/substrate/transcribers/deepgram/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Substrate
+  module Transcribers
+    class Deepgram
+      class Configuration
+        attr_reader :api_key, :language, :diarize, :punctuate, :model
+
+        DEFAULT_MODEL = "nova-2"
+
+        def initialize(
+          language: nil,
+          diarize: false,
+          punctuate: true,
+          model: DEFAULT_MODEL
+        )
+          @api_key = Substrate::Configuration.deepgram_api_key
+          @language = language
+          @diarize = !!diarize
+          @punctuate = !!punctuate
+          @model = model
+        end
+
+        def valid?
+          !api_key.to_s.empty?
+        end
+
+        def to_params
+          {
+            model: model,
+            smart_format: true,
+            punctuate: punctuate,
+            utterances: true,
+            language: language,
+            diarize: diarize || nil
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/substrate/transcribers/deepgram/response_parser.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Substrate
+  module Transcribers
+    class Deepgram
+      class ResponseParser
+        class MalformedResponseError < StandardError; end
+
+        def initialize(response, path:, diarized: false)
+          @response = response
+          @path = path
+          @diarized = diarized
+        end
+
+        def parse
+          Transcripts::Content.new(
+            source_ref: source_ref,
+            segments: segments,
+            metadata: metadata
+          )
+        end
+
+        private
+
+        attr_reader :response, :path, :diarized
+
+        def alternatives
+          response.dig("results", "channels", 0, "alternatives", 0)
+        end
+
+        def metadata
+          Transcripts::Metadata.new(
+            provider: :deepgram,
+            model: model_name,
+            language: response.dig("metadata", "language"),
+            duration_seconds: response.dig("metadata", "duration"),
+            diarized: diarized,
+            word_timestamps: words.any?
+          )
+        end
+
+        def model_name
+          model_info.values.first&.fetch("arch", nil) || Configuration::DEFAULT_MODEL
+        end
+
+        def segments
+          return utterances.map { |utterance| utterance_to_segment(utterance) } if utterances.any?
+
+          [words_to_segment(alternatives["transcript"], words)]
+        end
+
+        def words
+          alternatives["words"] || []
+        end
+
+        def utterance_to_segment(utterance)
+          Transcripts::Segment.new(
+            text: utterance["transcript"],
+            start: utterance["start"],
+            end: utterance["end"],
+            confidence: utterance["confidence"],
+            speaker: utterance["speaker"],
+            words: utterance.fetch("words", []).map { |w| word_data_to_word(w) }
+          )
+        end
+
+        def words_to_segment(transcript, word_list)
+          Transcripts::Segment.new(
+            text: transcript,
+            start: word_list.first["start"],
+            end: word_list.last["end"],
+            confidence: nil,
+            speaker: nil,
+            words: word_list.map { |w| word_data_to_word(w) }
+          )
+        end
+
+        def word_data_to_word(word_data)
+          Transcripts::Word.new(
+            text: word_data["punctuated_word"] || word_data["word"],
+            start: word_data["start"],
+            end: word_data["end"],
+            confidence: word_data["confidence"],
+            speaker: word_data["speaker"]
+          )
+        end
+
+        def utterances
+          response.dig("results", "utterances") || []
+        end
+
+        def model_info
+          response.dig("metadata", "model_info") || {}
+        end
+
+        def source_ref
+          @source_ref ||= SourceRef.new(kind: :audio, locator: path)
+        end
+      end
+    end
+  end
+end

data/lib/substrate/transcribers/deepgram.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Substrate
+  module Transcribers
+    class Deepgram < Command
+      class TranscriptionError < StandardError; end
+
+      def initialize(path:, **options)
+        @path = path
+        @config = Configuration.new(**options)
+      end
+
+      def call
+        return failure(missing_key_error) unless config.valid?
+
+        response = client.transcribe(path: path, params: config.to_params)
+        content = parser(response).parse
+
+        success(payload: content)
+      rescue Client::Error => e
+        failure(transcription_error(e.message))
+      end
+
+      private
+
+      attr_reader :path, :config
+
+      def client
+        @client ||= Client.new(api_key: config.api_key)
+      end
+
+      def parser(response)
+        ResponseParser.new(response, path: path, diarized: config.diarize)
+      end
+
+      def missing_key_error
+        ArgumentError.new("Deepgram API key required. Configure with Substrate::Configuration.deepgram_api_key = 'your_key'")
+      end
+
+      def transcription_error(message)
+        TranscriptionError.new(message)
+      end
+    end
+  end
+end

data/lib/substrate/transcribers/whisper_cpp/response_parser.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Substrate
+  module Transcribers
+    class WhisperCpp
+      class ResponseParser < Command
+        def initialize(output:, original_path:)
+          @output = output
+          @original_path = original_path
+        end
+
+        def call
+          success(payload: parse)
+        end
+
+        private
+
+        attr_reader :output, :original_path
+
+        def parse
+          Transcripts::Content.new(
+            source_ref: source_ref,
+            segments: segments,
+            metadata: metadata
+          )
+        end
+
+        def segments
+          transcription.map do |segment|
+            Transcripts::Segment.new(
+              text: segment.fetch("text"),
+              start: segment["offsets"]["from"] / 1000.0,
+              end: segment["offsets"]["to"] / 1000.0,
+              confidence: nil,
+              speaker: nil,
+              words: []
+            )
+          end
+        end
+
+        def metadata
+          Transcripts::Metadata.new(
+            provider: :whisper_cpp,
+            model: params.fetch("model", "unknown"),
+            language: output.fetch("result", {})["language"] || params["language"],
+            duration_seconds: nil,
+            diarized: false,
+            word_timestamps: false
+          )
+        end
+
+        def transcription
+          output.fetch("transcription")
+        end
+
+        def params
+          output.fetch("params", {})
+        end
+
+        def source_ref
+          SourceRef.new(kind: :audio, locator: original_path)
+        end
+      end
+    end
+  end
+end

data/lib/substrate/transcribers/whisper_cpp.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "json"
+
+module Substrate
+  module Transcribers
+    class WhisperCpp < Command
+      class TranscriptionError < StandardError; end
+
+      DEFAULT_MODEL = "base"
+      DEFAULT_THREADS = 4
+
+      def initialize(path:, model: DEFAULT_MODEL, threads: DEFAULT_THREADS, language: nil, model_path: "~/.local/share/whisper/models/ggml-#{model}.bin", executable: :auto)
+        @path = path
+        @threads = threads
+        @language = language
+        @model_path = File.expand_path(model_path || "~/.local/share/whisper/models/ggml-#{model}.bin")
+        @executable = executable || :auto
+      end
+
+      def call
+        select_transcription_executable
+        verify_transcription_requirements
+        transcribe_recording
+      rescue ArgumentError => error
+        failure(error)
+      end
+
+      private
+
+      attr_reader :path, :threads, :language, :model_path, :executable
+
+      def select_transcription_executable
+        @executable = (Cli::Availability.call("whisper-cli") ? "whisper-cli" : "whisper") if executable == :auto
+      end
+
+      def verify_transcription_requirements
+        unless Cli::Availability.call(executable)
+          raise ArgumentError, "Whisper CLI not found: #{executable}. Install whisper.cpp or pass executable:"
+        end
+        unless File.file?(model_path) && File.readable?(model_path)
+          raise ArgumentError, "Whisper model is not readable: #{model_path}"
+        end
+      end
+
+      def transcribe_recording
+        transcript = Dir.mktmpdir("substrate-whisper-") do |directory|
+          audio_path = File.join(directory, "audio.wav")
+          output_prefix = File.join(directory, "transcript")
+          run!(preparation_arguments(audio_path), stage: "Audio preparation")
+          run!(transcription_arguments(audio_path, output_prefix), stage: "Whisper transcription")
+          read_transcript("#{output_prefix}.json")
+        end
+
+        success(payload: transcript)
+      end
+
+      def preparation_arguments(audio_path)
+        ["ffmpeg", "-nostdin", "-i", path, "-ar", "16000", "-ac", "1", "-c:a", "pcm_s16le", "-y", audio_path]
+      end
+
+      def transcription_arguments(audio_path, output_prefix)
+        arguments = [executable, "-m", model_path, "-f", audio_path, "-t", threads.to_s, "--output-json", "-of", output_prefix]
+        arguments.concat(["-l", language]) if language
+        arguments
+      end
+
+      def run!(arguments, stage:)
+        result = Cli::Runner.call(argv: arguments)
+        raise TranscriptionError, "#{stage} failed: #{result.error.message}" if result.failure?
+      end
+
+      def read_transcript(output_path)
+        output = JSON.parse(File.read(output_path))
+        result = ResponseParser.call(output: output, original_path: path)
+        raise TranscriptionError, "Invalid Whisper transcript: #{result.error.message}" if result.failure?
+
+        result.payload
+      rescue Errno::ENOENT
+        raise TranscriptionError, "Whisper did not produce a JSON transcript"
+      rescue JSON::ParserError => e
+        raise TranscriptionError, "Invalid Whisper JSON: #{e.message}"
+      end
+    end
+  end
+end