alt_text 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 74c7e9c622b606ca65db9350ee5a3f662f07c6c24c93b0989b6d7e64c2cb93e9
+  data.tar.gz: 12cf5e8099bd768c53334eb2a00a84d1c1f9bf3715032a04f8846f4cab7725f6
+SHA512:
+  metadata.gz: 7d47cd62ff68eb4e9678e5d58af2d75e827e238990104e35ce93dd3eaf304b3334715dd89df1fd4ea82714f3050877d3410585dcb9d2bfd41d7761332239257c
+  data.tar.gz: ac4bc91f0ee83fae79bea43ed7bbc8d4020bc1596afd2ee61b4905634d7ddabb2caafebb1d0c138da46ff1161fae698ee3a06ccb556e7cc6c0cacd0154127e49

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Penn State University Libraries
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,79 @@
+## Alt Text Generator
+
+This uses Ruby's AWS SDK to send images and a prompt to an LLM in Amazon's Bedrock to generate Alt Text for the images.
+
+### Ruby Client Usage
+
+This gem uses imagemagick to resize large images, so you will need to install imagemagick:
+
+Mac:
+
+```
+brew install imagemagick
+```
+
+Ubuntu:
+
+```
+apt-get update
+apt-get install imagemagick
+```
+
+Then, add the gem to your project:
+
+In the Gemfile:
+```
+# Gemfile
+gem 'alt_text'
+```
+```
+bundle install
+```
+
+Or, via `gem install`:
+
+```
+gem install alt_text
+```
+
+Instantiate the client with injected AWS credentials:
+
+```
+client = AltText::Client.new {
+  access_key_id: ENV['YOUR_ACCESS_KEY_ID'],
+  secret_access_key: ENV['YOUR_SECRET_ACCESS_KEY'],
+  region: 'us-east-1'
+}
+```
+
+Call the `#process_image` method with the image path, prompt, and LLM ID as arguments:
+
+```
+client.process_image('folder/image.png', 'Please generate alt text', 'sonnet3.51`)
+```
+
+*Note: A sample prompt can be found in `prompt.txt`.*
+
+### CLI Usage
+
+Copy the `.env.sample` file to `.env` and add your AWS credentials.
+
+```
+cp .env.sample .env
+```
+
+General CLI command to generate Alt Text for images in the `images/` directory:
+
+```
+bundle exec bin/alt_text \
+  -s output/output.txt \
+  -l default \
+  -d images \
+  -p prompt.txt
+```
+
+Run this for help:
+
+```
+bundle exec bin/alt_text -h
+```

data/bin/alt_text

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+require_relative "../lib/alt_text"
+require "dotenv/load"
+require "optparse"
+
+# ---------- Defaults ----------
+options = {
+  save_file: 'output/output.txt',
+  model: 'default',
+  prompt_file: 'prompt.txt',
+  folder: 'images/'
+}
+
+# ---------- CLI Parsing ----------
+OptionParser.new do |opts|
+  opts.banner = "Usage: bundle exec bin/alt_text.rb [options]"
+
+  opts.on('-s FILE', '--save FILE', 'Save output file path') { |v| options[:save_file] = v }
+  opts.on('-l MODEL', '--llm MODEL', "Model name (#{AltText::LLMRegistry.available.join(', ')})") { |v| options[:model] = v }
+  opts.on('-d FOLDER', '--dir FOLDER', 'Folder to process') { |v| options[:folder] = v }
+  opts.on('-p FILE', '--prompt FILE', 'Prompt file path') { |v| options[:prompt_file] = v }
+end.parse!
+
+# ---------- Helpers ----------
+def list_files_scandir(path='.', str_exclude='pdf')
+  Dir.glob(File.join(path, '**', '*'))
+    .select { |f| File.file?(f) && !f.downcase.end_with?(str_exclude) }
+end
+
+# ---------- Setup ----------
+File.delete(options[:save_file]) if File.exist?(options[:save_file])
+output_file = File.open(options[:save_file], 'w')
+model_id = options[:model]
+prompt_string = File.read(options[:prompt_file])
+files = list_files_scandir(options[:folder])
+
+Dotenv.load('.env')
+
+client = AltText::Client.new(
+  access_key: ENV['AWS_ACCESS_KEY_ID'],
+  secret_key: ENV['AWS_SECRET_ACCESS_KEY'],
+  region: ENV['AWS_REGION']
+)
+
+# ---------- Process Images ----------
+files.each_with_index do |file, index|
+  puts "Processing image #{index + 1} of #{files.size}: #{file}"
+  begin
+    output = client.process_image(file, prompt: prompt_string, model_id: model_id)
+  rescue StandardError => e
+    output = "Processing error: #{e.message}"
+  ensure
+    output_file.puts("#{file}: \t#{output}")
+  end
+end

data/lib/alt_text/client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-bedrockruntime'
+require 'mini_magick'
+require 'base64'
+
+module AltText
+  class Client
+    def initialize(access_key:, secret_key:, region:)
+      @client = Aws::BedrockRuntime::Client.new(
+        access_key_id: access_key,
+        secret_access_key: secret_key,
+        region: region
+      )
+    end
+
+    def process_image(image_path, prompt:, model_id:)
+      model_id = AltText::LLMRegistry.resolve(model_id)
+      tmp_image = resize_if_needed(image_path)
+
+      encoded_image = Base64.strict_encode64(File.binread(tmp_image))
+      tmp_image.close! if tmp_image.is_a?(Tempfile)
+
+      payload = {
+        messages: [
+          { role: 'user',
+            content: [
+              { type: 'image',
+                source:
+                  { type: 'base64',
+                    media_type: 'image/jpeg',
+                    data: encoded_image } },
+              { type: 'text',
+                text: prompt }
+            ] }
+        ],
+        max_tokens: 10_000,
+        anthropic_version: 'bedrock-2023-05-31'
+      }
+
+      response = @client.invoke_model(model_id: model_id,
+                                      content_type: 'application/json',
+                                      body: payload.to_json)
+      JSON.parse(response.body.read)['content'][0]['text']
+    end
+
+    private
+
+      def resize_if_needed(file)
+        if File.size(file) < 4_000_000
+          file
+        else
+          tmp = Tempfile.new("#{file}_tmp.jpg")
+          image = MiniMagick::Image.open(file)
+          image.resize '800x'
+          image.write tmp.path
+          tmp
+        end
+      end
+  end
+end

data/lib/alt_text/llm_registry.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module AltText
+  class LLMRegistry
+    LLM_MAP = {
+      'default' => 'anthropic.claude-3-5-sonnet-20240620-v1:0',
+      'sonnet3.51' => 'anthropic.claude-3-5-sonnet-20240620-v1:0',
+      'sonnet3.52' => 'anthropic.claude-3-5-sonnet-20241022-v2:0',
+      'sonnet3.571' => 'us.anthropic.claude-3-7-sonnet-20250219-v1:0',
+      'novapro' => 'us.amazon.nova-pro-v1:0'
+    }.freeze
+
+    def self.resolve(key)
+      LLM_MAP[key] or raise ArgumentError, "Unsupported LLM: #{key}"
+    end
+
+    def self.available
+      LLM_MAP.keys
+    end
+  end
+end

data/lib/alt_text.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'alt_text/client'
+require_relative 'alt_text/llm_registry'
+
+module AltText
+end

data/prompt.txt

@@ -0,0 +1,22 @@
+You are a professional technical writer trained in crafting image alternative text for accessibility purposes. Your task is to describe the visual content of uploaded images in clear, concise, and objective language that supports screen reader users. Describe the visual content of the image in one concise, objective sentence (≤100 characters).
+When given an image, follow these guidelines to create appropriate and effective alternative text descriptions.
+1.	Technical guidelines:
+  - Descriptions should not exceed 100 characters.
+  - Use precise, simple language and clear terminology.
+  - Use bias-free language: avoid assumptions about gender, ability, race, or age.
+2.	Language guidelines:
+  - Do not use ambiguous adjectives (e.g., “tranquil,” “vintage,” “rural”).
+  - Do not use subjective adjectives (e.g., "traditional," "rustic")
+  - Avoid assumptions or guessing unclear elements.
+  - Do not include “image of,” “photo of,” or similar phrases.
+  - Focus only on the visible, essential elements in the image.
+3.	Output guidelines:
+  - Assume one image per input and respond with one alt text string.
+Please see the examples provided to help guide your description structure.
+<examples>
+"A lighthouse on a rocky coast under a cloudy sky."
+"Three people walking along a path surrounded by green trees."
+“A person wearing a beret and glasses eating from a bowl.”
+</examples>
+Generate the alt text description following these rules.
+

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: alt_text
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alex Kiessling
+bindir: bin
+cert_chain: []
+date: 2025-09-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-bedrockruntime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.55.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.55.0
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.8
+- !ruby/object:Gem::Dependency
+  name: mini_magick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.3.0
+description: AltText helps with accessibility by generating alt text for images.
+email:
+- ajk5603@psu.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- bin/alt_text
+- lib/alt_text.rb
+- lib/alt_text/client.rb
+- lib/alt_text/llm_registry.rb
+- prompt.txt
+homepage: https://github.com/psu-libraries/alt_text
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Generates alt text
+test_files: []