tahweel 0.1.0

data/lib/tahweel/pdf_splitter.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rbconfig"
+require "securerandom"
+require "tmpdir"
+require "vips"
+
+module Tahweel
+  # Handles the logic for splitting a PDF file into individual image pages.
+  # Uses the libvips library for high-performance image processing.
+  class PdfSplitter
+    # Default DPI used when converting PDF pages to images.
+    # 150 DPI is a good balance between quality and file size for general documents.
+    DEFAULT_DPI = 150
+
+    # Convenience class method to initialize and execute the split operation in one go.
+    #
+    # @param pdf_path [String] The local file path to the PDF document.
+    # @param dpi [Integer] The resolution (Dots Per Inch) for rendering the PDF pages. Defaults to 150.
+    # @param &block [Proc] A block that will be yielded with progress info.
+    # @yield [Hash] Progress info: {
+    #   stage: :splitting,
+    #   current_page: Integer,
+    #   percentage: Float,
+    #   remaining_pages: Integer
+    # }
+    # @return [Hash] A hash containing the :folder_path (String) and :image_paths (Array<String>).
+    def self.split(pdf_path, dpi: DEFAULT_DPI, &) = new(pdf_path, dpi:).split(&)
+
+    # Initializes a new PdfSplitter instance.
+    #
+    # @param pdf_path [String] The local file path to the PDF document.
+    # @param dpi [Integer] The resolution (Dots Per Inch) to use. Defaults to 150.
+    def initialize(pdf_path, dpi: DEFAULT_DPI)
+      @pdf_path = pdf_path
+      @dpi = dpi
+      @image_paths = []
+    end
+
+    # Executes the PDF splitting process.
+    #
+    # This method performs the following steps:
+    # 1. Checks if libvips is installed (skips on Windows).
+    # 2. Validates the existence of the source PDF file.
+    # 3. Creates a unique temporary directory for output.
+    # 4. Iterates through each page of the PDF and converts it to a PNG image.
+    #
+    # @param &block [Proc] A block that will be yielded with progress info.
+    # @yield [Hash] Progress info: {
+    #   stage: :splitting,
+    #   current_page: Integer,
+    #   percentage: Float,
+    #   remaining_pages: Integer
+    # }
+    # @return [Hash] Result hash with keys:
+    #   - :folder_path [String] The absolute path to the temporary directory containing the images.
+    #   - :image_paths [Array<String>] List of absolute paths for each generated image file.
+    # @raise [RuntimeError] If the PDF file is not found or libvips is missing.
+    # @raise [Vips::Error] If the underlying VIPS library encounters an error during processing.
+    def split(&)
+      check_libvips_installed!
+      validate_file_exists!
+      setup_output_directory
+      process_pages(&)
+      result
+    end
+
+    private
+
+    attr_reader :pdf_path, :dpi, :image_paths, :output_dir
+
+    # Checks if the `vips` CLI tool is available in the system PATH.
+    # Skips this check on Windows systems, assuming the environment is managed differently.
+    # Aborts execution with an error message if vips is missing.
+    def check_libvips_installed!
+      return if /mswin|mingw|cygwin/.match?(RbConfig::CONFIG["host_os"])
+      return if system("vips --version", out: File::NULL, err: File::NULL)
+
+      abort "Error: libvips is not installed. Please install it before using Tahweel.\n" \
+            "MacOS: `brew install vips`\n" \
+            "Ubuntu: `sudo apt install libvips42`\n" \
+            "Windows: Already installed with the Tahweel gem"
+    end
+
+    # Ensures the source PDF file actually exists.
+    # @raise [RuntimeError] if the file is missing.
+    def validate_file_exists!
+      raise "File not found: #{pdf_path}" unless File.exist?(pdf_path)
+    end
+
+    # Creates a secure, unique temporary directory using UUIDs.
+    def setup_output_directory
+      @output_dir = File.join(Dir.tmpdir, "tahweel_#{SecureRandom.uuid}")
+      FileUtils.mkdir_p(@output_dir)
+    end
+
+    # Iterates through all pages and extracts them.
+    #
+    # @param &block [Proc] A block that will be yielded with progress info.
+    # @yield [Hash] Progress info: {
+    #   stage: :splitting,
+    #   current_page: Integer,
+    #   percentage: Float,
+    #   remaining_pages: Integer
+    # }
+    # @return [void]
+    def process_pages(&)
+      total_pages.times do |i|
+        extract_page(i)
+
+        next unless block_given?
+
+        yield({
+          file_path: @pdf_path, stage: :splitting,
+          current_page: i + 1,
+          percentage: (((i + 1).to_f / total_pages) * 100).round(2),
+          remaining_pages: total_pages - (i + 1)
+        })
+      end
+    end
+
+    # Calculates the total number of pages in the PDF by loading the first page metadata.
+    # @return [Integer] The page count.
+    def total_pages
+      @total_pages ||= Vips::Image.pdfload(pdf_path, page: 0, dpi: dpi, access: :sequential).get("pdf-n_pages")
+    end
+
+    # Extracts a specific page from the PDF and saves it as a PNG.
+    #
+    # @param page_num [Integer] The zero-based index of the page to extract.
+    def extract_page(page_num)
+      output_path = File.join(output_dir, "page_#{page_num + 1}.png")
+      Vips::Image.pdfload(pdf_path, page: page_num, dpi: dpi, access: :sequential).write_to_file(output_path)
+      image_paths << output_path
+    end
+
+    # Constructs the final result hash.
+    # @return [Hash]
+    def result
+      {
+        folder_path: output_dir,
+        image_paths: image_paths
+      }
+    end
+  end
+end

data/lib/tahweel/processors/google_drive.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "google/apis/drive_v3"
+require "securerandom"
+require "stringio"
+
+require_relative "../authorizer"
+
+module Tahweel
+  module Processors
+    # Handles the conversion of images to text using Google Drive's OCR capabilities.
+    #
+    # This class automates the process of:
+    # 1. Uploading a local image to Google Drive as a Google Document.
+    # 2. Downloading the content of that document as plain text.
+    # 3. Cleaning up (deleting) the temporary file from Drive.
+    #
+    # It includes robust error handling with infinite retries and exponential backoff
+    # for network issues, rate limits, and server errors.
+    class GoogleDrive
+      # Initializes the Google Drive OCR service.
+      # Sets up the Google Drive API client and authorizes it using {Tahweel::Authorizer}.
+      #
+      # @note This operation performs filesystem I/O to read credentials.
+      #   For bulk processing, instantiate this once and reuse it.
+      def initialize
+        @service = Google::Apis::DriveV3::DriveService.new
+        @service.client_options.application_name = "Tahweel"
+        @service.authorization = Tahweel::Authorizer.authorize
+      end
+
+      # Extracts text from an image file using the "Upload -> Export -> Delete" flow.
+      #
+      # The method ensures that the temporary file created on Google Drive is deleted
+      # regardless of whether the download succeeds or fails.
+      #
+      # @param file_path [String] The path to the image file.
+      # @return [String] The extracted text.
+      # @raise [RuntimeError] If the file does not exist locally.
+      # @raise [Google::Apis::Error] If a non-retriable API error occurs (e.g., 401, 403, 404).
+      def extract(file_path)
+        raise "File not found: #{file_path}" unless File.exist?(file_path)
+
+        begin
+          file_id = upload_file(file_path)
+          download_text(file_id).gsub("\r\n", "\n").gsub("________________", "").strip
+        ensure
+          delete_file(file_id)
+        end
+      end
+
+      private
+
+      # Uploads the file to Google Drive with the MIME type set to 'application/vnd.google-apps.document'.
+      # This triggers Google's automatic OCR processing.
+      #
+      # @param file_path [String] Path to the local file.
+      # @return [String] The ID of the created file on Google Drive.
+      def upload_file(file_path)
+        execute_with_retry do
+          @service.create_file(
+            {
+              name: SecureRandom.uuid,
+              mime_type: "application/vnd.google-apps.document"
+            },
+            upload_source: file_path,
+            fields: "id"
+          ).id
+        end
+      end
+
+      # Exports the Google Document as plain text.
+      #
+      # @param file_id [String] The ID of the file on Google Drive.
+      # @return [String] The content of the file as a string.
+      def download_text(file_id)
+        execute_with_retry do
+          StringIO.new.tap do |dest|
+            @service.export_file(file_id, "text/plain", download_dest: dest)
+          end.string
+        end
+      end
+
+      # Deletes the temporary file from Google Drive.
+      #
+      # @param file_id [String] The ID of the file to delete.
+      # @return [void]
+      def delete_file(file_id) = execute_with_retry { @service.delete_file(file_id) }
+
+      # Executes a block with infinite retries and exponential backoff.
+      # Designed to handle transient errors (Rate Limits, Network issues, Server errors).
+      #
+      # @yield The block to execute.
+      # @raise [Google::Apis::Error] Rethrows non-retriable errors immediately.
+      def execute_with_retry
+        retries = 0
+
+        begin
+          yield
+        rescue Google::Apis::RateLimitError, Google::Apis::RequestTimeOutError,
+               Google::Apis::TransmissionError, Google::Apis::ServerError
+          sleep([1.5**retries, 15].min + rand(0..1))
+          retries += 1
+          retry
+        end
+      end
+    end
+  end
+end

data/lib/tahweel/templates/success.html

@@ -0,0 +1,192 @@
+<!DOCTYPE html>
+<html lang="ar" dir="rtl">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Tahweel Authorization</title>
+    <!-- Google Fonts: Poppins for English, Cairo for Arabic -->
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Cairo:wght@400;700&family=Poppins:wght@400;600&display=swap" rel="stylesheet">
+    <style>
+      :root {
+        --primary-color: #10b981; /* Emerald Green */
+        --primary-hover: #059669;
+        --bg-gradient: linear-gradient(135deg, #f0fdf4 0%, #d1fae5 100%);
+        --text-dark: #1f2937;
+        --text-light: #6b7280;
+        --card-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1);
+      }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        background: var(--bg-gradient);
+        font-family: 'Cairo', sans-serif; /* Default to Arabic font */
+        transition: all 0.3s ease;
+      }
+
+      /* English Font Override */
+      body.font-en {
+        font-family: 'Poppins', sans-serif;
+      }
+
+      .container {
+        background: rgba(255, 255, 255, 0.95);
+        padding: 3rem;
+        border-radius: 24px;
+        box-shadow: var(--card-shadow);
+        text-align: center;
+        max-width: 420px;
+        width: 90%;
+        position: relative;
+        backdrop-filter: blur(10px);
+        animation: fadeUp 0.6s cubic-bezier(0.16, 1, 0.3, 1);
+        border: 1px solid rgba(255,255,255,0.5);
+      }
+
+      /* Success Icon Animation */
+      .icon-wrapper {
+        width: 80px;
+        height: 80px;
+        background: #d1fae5;
+        border-radius: 50%;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        margin: 0 auto 1.5rem auto;
+        color: var(--primary-color);
+      }
+
+      .icon-wrapper svg {
+        width: 40px;
+        height: 40px;
+        stroke-width: 3;
+        stroke: currentColor;
+        fill: none;
+        stroke-linecap: round;
+        stroke-linejoin: round;
+        animation: drawCheck 0.8s ease-out forwards;
+      }
+
+      h1 {
+        color: var(--text-dark);
+        font-size: 1.5rem;
+        font-weight: 700;
+        margin: 0 0 0.5rem 0;
+      }
+
+      p {
+        color: var(--text-light);
+        font-size: 1rem;
+        line-height: 1.6;
+        margin: 0 0 1.5rem 0;
+      }
+
+      .sub-text {
+        font-size: 0.875rem;
+        opacity: 0.8;
+        margin-top: -1rem;
+      }
+
+      /* Language Toggle Button */
+      .lang-btn {
+        position: absolute;
+        top: 20px;
+        right: 20px;
+        background: white;
+        border: 1px solid #e5e7eb;
+        padding: 8px 16px;
+        border-radius: 20px;
+        font-family: inherit;
+        font-size: 0.875rem;
+        font-weight: 600;
+        color: var(--text-dark);
+        cursor: pointer;
+        box-shadow: 0 2px 5px rgba(0,0,0,0.05);
+        transition: all 0.2s ease;
+        display: flex;
+        align-items: center;
+        gap: 6px;
+      }
+
+      html[dir="ltr"] .lang-btn {
+        right: auto;
+        left: 20px;
+      }
+
+      .lang-btn:hover {
+        background: #f9fafb;
+        transform: translateY(-1px);
+        box-shadow: 0 4px 12px rgba(0,0,0,0.08);
+      }
+
+      /* Animations */
+      @keyframes fadeUp {
+        from { opacity: 0; transform: translateY(20px); }
+        to { opacity: 1; transform: translateY(0); }
+      }
+
+      @keyframes drawCheck {
+        0% { stroke-dasharray: 100; stroke-dashoffset: 100; opacity: 0; transform: scale(0.8); }
+        100% { stroke-dasharray: 100; stroke-dashoffset: 0; opacity: 1; transform: scale(1); }
+      }
+    </style>
+  </head>
+  <body>
+    <button class="lang-btn" onclick="toggleLanguage()" id="langBtn">
+    <span>🌐</span> <span id="btnText">English</span>
+    </button>
+    <div class="container">
+      <div class="icon-wrapper">
+        <!-- Simple SVG Checkmark -->
+        <svg viewBox="0 0 24 24">
+          <path d="M20 6L9 17l-5-5"></path>
+        </svg>
+      </div>
+      <h1 id="title">تمت المُصادقة بنجاح!</h1>
+      <p id="msg1">لقد قمت بتسجيل الدخول بنجاح إلى تحويل.</p>
+      <p id="msg2" class="sub-text">يمكنك إغلاق هذه النافذة والعودة إلى البرنامج.</p>
+    </div>
+    <script>
+      // Content Dictionary
+      const content = {
+        ar: {
+          btn: "English",
+          title: "تمت المُصادقة بنجاح!",
+          msg1: "لقد قمت بتسجيل الدخول بنجاح إلى تحويل.",
+          msg2: "يمكنك إغلاق هذه النافذة والعودة إلى البرنامج."
+        },
+        en: {
+          btn: "العربية",
+          title: "Authorization Successful!",
+          msg1: "You have successfully logged in to Tahweel.",
+          msg2: "You can close this window and return to your terminal."
+        }
+      };
+      
+      let currentLang = 'ar';
+      
+      function toggleLanguage() {
+        currentLang = currentLang === 'ar' ? 'en' : 'ar';
+        
+        // Toggle Direction and Lang Attribute
+        const htmlEl = document.documentElement;
+        htmlEl.lang = currentLang;
+        htmlEl.dir = currentLang === 'ar' ? 'rtl' : 'ltr';
+      
+        // Toggle Font Class (for body typography)
+        document.body.classList.toggle('font-en', currentLang === 'en');
+      
+        // Update Text
+        document.getElementById('btnText').textContent = content[currentLang].btn;
+        document.getElementById('title').textContent = content[currentLang].title;
+        document.getElementById('msg1').textContent = content[currentLang].msg1;
+        document.getElementById('msg2').textContent = content[currentLang].msg2;
+      }
+    </script>
+  </body>
+</html>

data/lib/tahweel/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tahweel
+  VERSION = "0.1.0"
+end

data/lib/tahweel/writer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "writers/txt"
+require_relative "writers/docx"
+require_relative "writers/json"
+
+module Tahweel
+  # Factory class for writing extracted text to different formats.
+  class Writer
+    AVAILABLE_FORMATS = %i[txt docx json].freeze
+
+    # Convenience method to write texts to files in the specified formats.
+    #
+    # @param texts [Array<String>] The extracted texts.
+    # @param base_path [String] The base output path (without extension).
+    # @param formats [Array<Symbol>] The output formats (default: [:txt]).
+    # @param options [Hash] Options for writers.
+    # @return [void]
+    def self.write(texts, base_path, formats: [:txt], **options)
+      formats.each { new(format: _1).write(texts, base_path, **options) }
+    end
+
+    # Initializes the Writer with a specific format strategy.
+    #
+    # @param format [Symbol] The output format.
+    # @raise [ArgumentError] If the format is unknown.
+    def initialize(format: :txt)
+      @writer = case format
+                when :txt then Writers::Txt.new
+                when :docx then Writers::Docx.new
+                when :json then Writers::Json.new
+                else raise ArgumentError, "Unknown format: #{format}"
+                end
+    end
+
+    # Writes the texts to the destination using the selected strategy.
+    # Appends the appropriate extension to the base path.
+    #
+    # @param texts [Array<String>] The extracted texts.
+    # @param base_path [String] The base output file path.
+    # @param options [Hash] Options to pass to the writer.
+    def write(texts, base_path, **options) = @writer.write(texts, "#{base_path}.#{extension}", options)
+
+    # Delegates the extension retrieval to the specific writer strategy.
+    #
+    # @return [String] The file extension.
+    def extension = @writer.extension
+  end
+end

data/lib/tahweel/writers/docx.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "caracal"
+
+module Tahweel
+  module Writers
+    # Writer class for outputting text to a .docx file.
+    class Docx
+      # Returns the file extension for this writer.
+      #
+      # @return [String] The file extension.
+      def extension = "docx"
+
+      # Writes the extracted texts to a file.
+      #
+      # It applies several transformations to the text before writing:
+      # 1. Normalizes line endings to `\n`.
+      # 2. Collapses consecutive identical whitespace characters.
+      # 3. Compacts the text by merging short lines if the page is too long (> 40 lines).
+      # 4. Determines text alignment (RTL/LTR) based on content.
+      #
+      # @param texts [Array<String>] The extracted texts (one per page).
+      # @param destination [String] The output file path.
+      # @param options [Hash] Options for writing (unused for now).
+      # @return [void]
+      def write(texts, destination, options = {}) # rubocop:disable Lint/UnusedMethodArgument
+        Caracal::Document.save(destination) do |docx|
+          texts.each_with_index do |text, index|
+            text = text.gsub(/(\r\n)+/, "\n").gsub(/(\s)\1+/, '\1').strip
+            text = compact_shortest_lines(text) while expected_lines_in_page(text) > 40
+
+            docx.p text, size: 20, align: alignment_for(text)
+
+            docx.page if index < texts.size - 1
+          end
+        end
+      end
+
+      private
+
+      # Determines the text alignment based on the ratio of Arabic to non-Arabic characters.
+      #
+      # @param text [String] The text to analyze.
+      # @return [Symbol] :right if Arabic characters dominate, :left otherwise.
+      def alignment_for(text)
+        arabic_chars_count = text.scan(/\p{Arabic}/).count
+        other_chars_count = text.scan(/[^\p{Arabic}\p{P}\d\s]/).count
+
+        arabic_chars_count >= other_chars_count ? :right : :left
+      end
+
+      # Estimates the number of lines the text will occupy on a page.
+      #
+      # Assumes a line wraps if it exceeds 80 characters.
+      #
+      # @param text [String] The text to analyze.
+      # @return [Integer] The estimated line count.
+      def expected_lines_in_page(text) = text.count("\n") + 1 + text.split("\n").count { _1.length > 80 }
+
+      # Compacts the text by merging the two shortest adjacent lines.
+      #
+      # @param text [String] The text to compact.
+      # @return [String] The compacted text.
+      def compact_shortest_lines(text)
+        lines = text.split("\n")
+        return text if lines.size < 2
+
+        index = find_merge_index(lines)
+        lines[index] = "#{lines[index]} #{lines[index + 1]}"
+        lines.delete_at(index + 1)
+
+        lines.join("\n")
+      end
+
+      # Finds the index of the first line in the pair of adjacent lines with the minimum combined length.
+      #
+      # @param lines [Array<String>] The lines to analyze.
+      # @return [Integer] The index of the first line in the optimal pair.
+      def find_merge_index(lines) = (0...(lines.size - 1)).min_by { lines[_1].length + lines[_1 + 1].length }
+    end
+  end
+end

data/lib/tahweel/writers/json.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Tahweel
+  module Writers
+    # Writer class for outputting text to a .json file.
+    class Json
+      # Returns the file extension for this writer.
+      #
+      # @return [String] The file extension.
+      def extension = "json"
+
+      # Writes the extracted texts to a file.
+      #
+      # @param texts [Array<String>] The extracted texts (one per page).
+      # @param destination [String] The output file path.
+      # @param options [Hash] Options for writing (unused for now).
+      # @return [void]
+      def write(texts, destination, options = {}) # rubocop:disable Lint/UnusedMethodArgument
+        structured_data = texts.map.with_index do |text, index|
+          {
+            page: index + 1,
+            content: text.strip
+          }
+        end
+
+        File.write(destination, JSON.pretty_generate(structured_data))
+      end
+    end
+  end
+end

data/lib/tahweel/writers/txt.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Tahweel
+  module Writers
+    # Writer class for outputting text to a .txt file.
+    class Txt
+      PAGE_SEPARATOR = "\n\nPAGE_SEPARATOR\n\n"
+
+      # Returns the file extension for this writer.
+      #
+      # @return [String] The file extension.
+      def extension = "txt"
+
+      # Writes the extracted texts to a file.
+      #
+      # @param texts [Array<String>] The extracted texts (one per page).
+      # @param destination [String] The output file path.
+      # @param options [Hash] Options for writing.
+      # @option options [String] :page_separator (PAGE_SEPARATOR) Separator between pages.
+      # @return [void]
+      def write(texts, destination, options = {})
+        separator = options[:page_separator] || PAGE_SEPARATOR
+        File.write(destination, texts.map(&:strip).join(separator))
+      end
+    end
+  end
+end

data/lib/tahweel.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "tahweel/version"
+require_relative "tahweel/authorizer"
+require_relative "tahweel/pdf_splitter"
+require_relative "tahweel/ocr"
+require_relative "tahweel/converter"
+require_relative "tahweel/writer"
+require_relative "tahweel/cli/file_processor"
+require_relative "tahweel/cli/file_collector"
+require_relative "tahweel/cli/options"
+
+module Tahweel # rubocop:disable Style/Documentation
+  class Error < StandardError; end
+
+  # Converts a PDF file to text by splitting it into images and running OCR on each page.
+  #
+  # @param pdf_path [String] Path to the PDF file.
+  # @param dpi [Integer] DPI for PDF to image conversion (default: 150).
+  # @param processor [Symbol] OCR processor to use (default: :google_drive).
+  # @param concurrency [Integer] Max concurrent OCR operations (default: 12).
+  # @return [Array<String>] An array containing the text of each page.
+  def self.convert(
+    pdf_path,
+    dpi: PdfSplitter::DEFAULT_DPI,
+    processor: :google_drive,
+    concurrency: Converter::DEFAULT_CONCURRENCY,
+    &
+  ) = Converter.convert(pdf_path, dpi:, processor:, concurrency:, &)
+
+  # Extracts text from an image file using the specified OCR processor.
+  #
+  # @param image_path [String] Path to the image file.
+  # @param processor [Symbol] OCR processor to use (default: :google_drive).
+  # @return [String] The extracted text.
+  def self.extract(image_path, processor: :google_drive) = Ocr.extract(image_path, processor:)
+end

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.4.7"