hyrum 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6af9ff6689127c74e41729fbd056dadf9a811ec19a74f14ccd6a61413d2b3c0b
+  data.tar.gz: 900a08d6f56ad8e8cdf70f60fcf5782859b78420c95c9afaf0c86f78815ab449
+SHA512:
+  metadata.gz: 14adcecb5a38a2fe356e5c9eb27e5fc254d1ce45953bfe32d595ad909813a49ea5a641a99f9b64daae75f3322f09f0bfa8891d9885990f8b1159d7f6f40fbead
+  data.tar.gz: 19537c266190bcf175f8a340d8828fd354f974fbdb80639018e0d8862103a81bd792967b144afa4e2f5bc2cad78fd94e185bc30f7044cf8db62c1c004278cf55

data/README.md

@@ -0,0 +1,154 @@
+# Hyrum's Message Generator
+
+✨ A multi-language code generator to cope with Hyrum's law ✨
+
+Hyrum's message generator (hyrum) generates a method in the chosen language that
+returns one of several variations of a provided message at random.
+
+![Tests](https://github.com/grymoire7/hyrum/actions/workflows/ruby.yml/badge.svg?branch=main)
+![Ruby Version](https://img.shields.io/badge/Ruby-3.3.5-green?logo=Ruby&logoColor=red&label=Ruby%20version&color=green)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/grymoire7/hyrum/blob/main/LICENSE.txt)
+
+## Explanation
+[Hyrum's law][hd] states that all observable behaviors of your system will be
+depended on by somebody. Some nice examples can be found [here][he].
+
+One example that seems a little more difficult to handle is the case where a
+status/error message is being returned to the user. How can you vary the message
+so the user doesn't become dependent on the exact wording of the message?
+Also, we don't want to spend a lot of time writing variations of the same message.
+
+This is the use case Hyrum tries to solve. It uses an AI service (openai,
+ollama, etc.) to generate variations of a provided message. The generated
+variations are also formatted in the language/format of your choice (ruby,
+json, etc.).
+
+## Example
+
+```bash
+hyrum --service openai --key e418 --format ruby \
+      --message "The server refuses the attempt to brew coffee with a teapot"
+```
+
+```ruby
+# frozen_string_literal: true
+
+module Messages
+  MESSAGES = {
+    e418: [
+      "Invalid Brewing Method",
+      "Teapot not designed for coffee brewing",
+      "Please use a suitable brewing device",
+      "Coffee and tea are two distinct beverages with different requirements",
+      "Check your equipment and try again"
+    ]
+  }.freeze
+
+  def self.message(key)
+    MESSAGES[key].sample
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  puts Messages.message(ARGV[0].to_sym)
+end
+```
+
+## Usage
+
+```
+❯ hyrum --help # OR from the repo as `./exe/hyrum --help`
+Usage: hyrum [options]
+    -v, --[no-]verbose               Run verbosely
+    -f, --format FORMAT              Output format. Supported formats are:
+                                     ruby, javascript, python, java, text, json
+    -m, --message MESSAGE            Status message
+    -k, --key KEY                    Message key
+    -s, --service SERVICE            AI service: one of openai, ollama, fake
+    -d, --model MODEL                AI model: must be a valid model for the selected service
+    -h, --help                       Show this message
+        --version                    Show version
+```
+
+## Installation
+NOTE: This gem is not yet available on rubygems.org. You can install it from the
+repository with `bundle exec rake install`.  In the future, you can...
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add hyrum
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install hyrum
+
+## Run without configuration
+Hyrum normally requires configuration to access an AI service provider. However,
+if you want to see output quickly, you can use the `-s fake` option to use a fake
+service provider that will generate stock responses.
+
+```bash
+hyrum -s fake -f ruby -m "anything here"
+```
+
+You don't even need to install the gem to use Hyrum, fake service provider or not.
+You can run the executable directly from a cloned repository.
+
+```bash
+./exec/hyrum -s fake -f ruby -m "anything here"
+```
+
+## Configruation
+
+### OpenAI (`--service openai`)
+Hyrum requires an OpenAI API token to access the language models. The API token should be
+set as an environment variable as shown below.
+
+```bash
+export OPENAI_ACCESS_TOKEN=your_open_ai_token
+```
+
+If you specify the `openai` service but no model, Hyrum will use the `gpt-o4-mini`.
+
+### Ollama (`--service ollama`)
+If you specify the `ollama` service, Hyrum will attempt to use the Ollama API
+running at `http://localhost:11434`. You can set the `OLLAMA_URL` environment
+variable to specify a different URL.
+
+Make sure your ollama server is running before using the `ollama` service.
+
+```bash
+ollama serve
+```
+
+Use `ollama list` to see the available models. For more information on using
+ollama and downloading models, see the [ollama repository](http://ollama.com).
+
+## Supported formats and AI services
+
+See [Usage](#usage) for a list of supported formats and AI services.
+
+## Compatibility
+
+This gem is compatible with Ruby 3.1 or greater.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/grymoire7/hyrum. This project is intended to be a safe,
+welcoming space for collaboration, and contributors are expected to adhere to the
+[code of conduct](https://github.com/grymoire7/hyrum/blob/main/CODE_OF_CONDUCT.md).
+
+[hd]: https://www.laws-of-software.com/laws/hyrum/
+[he]: https://abenezer.org/blog/hyrum-law-in-golang

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'hyrum'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/hyrum

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'bundler/setup'
+require 'hyrum'
+
+# Hyrum::CLI.start(ARGV)
+Hyrum.run(ARGV)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/hyrum/formats/formatter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Hyrum
+  module Formats
+    FORMATS = %i[ruby javascript python java text json].freeze
+
+    class Formatter
+      attr_reader :options
+
+      def initialize(options)
+        @options = options
+      end
+
+      def format(messages)
+        template_file = File.join(__dir__, 'templates', "#{options[:format]}.erb")
+        template = ERB.new(File.read(template_file), trim_mode: '-')
+        template.result_with_hash(messages: messages)
+      end
+    end
+  end
+end

data/lib/hyrum/formats/templates/java.erb

@@ -0,0 +1,30 @@
+import java.util.HashMap;
+import java.util.List;
+import java.util.Random;
+
+public class Messages {
+    private static final HashMap<String, List<String>> MESSAGES = new HashMap<>();
+
+    static {
+<% messages.each do |key, values| -%>
+        MESSAGES.put("<%= key %>", List.of(
+            <%= values.map { |message| "\"#{message}\"" }.join(",\n            ") %>
+        ));
+<% end -%>
+    }
+
+    public static String message(String key) {
+        List<String> messages = MESSAGES.get(key);
+        if (messages != null && !messages.isEmpty()) {
+            Random random = new Random();
+            return messages.get(random.nextInt(messages.size()));
+        }
+        return null;
+    }
+
+    public static void main(String[] args) {
+        if (args.length > 0) {
+            System.out.println(message(args[0]));
+        }
+    }
+}

data/lib/hyrum/formats/templates/javascript.erb

@@ -0,0 +1,19 @@
+const Messages = {
+  MESSAGES: {
+<% messages.each do |key, values| -%>
+    <%= key %>: [
+      <%= values.map { |message| "\"#{message}\"" }.join(",\n      ") %>
+    ]<%= "," unless key == messages.keys.last %>
+<% end -%>
+  },
+
+  message(key) {
+    const messages = this.MESSAGES[key];
+    return messages[Math.floor(Math.random() * messages.length)];
+  }
+};
+
+if (require.main === module) {
+  const key = process.argv[2];
+  console.log(Messages.message(key));
+}

data/lib/hyrum/formats/templates/json.erb

@@ -0,0 +1 @@
+<%= JSON.pretty_generate(messages) %>

data/lib/hyrum/formats/templates/python.erb

@@ -0,0 +1,18 @@
+import random
+import sys
+
+class Messages:
+    MESSAGES = {
+<% messages.each do |key, values| -%>
+        '<%= key %>': [
+            <%= values.map { |message| "\"#{message}\"" }.join(",\n            ") %>
+        ]<%= "," unless key == messages.keys.last %>
+<% end -%>
+    }
+
+    @staticmethod
+    def message(key):
+        return random.choice(Messages.MESSAGES[key])
+
+if __name__ == "__main__":
+    print(Messages.message(sys.argv[1]))

data/lib/hyrum/formats/templates/ruby.erb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Messages
+  MESSAGES = {
+<% messages.each do |key, values| -%>
+    <%= key %>: [
+      <%= values.map { |message| "\"#{message}\"" }.join(",\n      ") %>
+    ]<%= "," unless key == messages.keys.last %>
+<% end -%>
+  }.freeze
+
+  def self.message(key)
+    MESSAGES[key].sample
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  puts Messages.message(ARGV[0].to_sym)
+end

data/lib/hyrum/formats/templates/text.erb

@@ -0,0 +1,6 @@
+<% messages.each do |key, values| -%>
+Messages for <%= key %>:
+  <% values.each do |msg| -%>
+  - <%= msg %>
+  <% end %>
+<% end %>

data/lib/hyrum/generators/fake_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Hyrum
+  module Generators
+    class FakeGenerator
+      FAKE_MESSAGES = %(
+        {
+          "e404": [
+            "We couldn't locate the resource you were looking for.",
+            "The resource you requested is not available at this time.",
+            "Unfortunately, we were unable to find the specified resource.",
+            "It seems the resource you're searching for does not exist.",
+            "The item you are trying to access is currently missing."
+          ],
+          "e418": [
+            "I'm a teapot",
+            "The server refuses the attempt to brew coffee with a teapot",
+            "Coffee brewing denied: a teapot is not suitable for this operation.",
+            "Request failed: the server cannot process coffee with a teapot.",
+            "Brewing error: teapots are incompatible with coffee preparation.",
+            "Action halted: using a teapot to brew coffee is not permitted.",
+            "Invalid request: please use a coffee maker instead of a teapot."
+          ],
+          "e500": [
+            "Internal Server Error",
+            "An unexpected condition was encountered"
+          ],
+          "e503": [
+            "Service Unavailable",
+            "The server is currently unavailable"
+          ],
+          "e504": [
+            "Gateway Timeout",
+            "The server is currently unavailable"
+          ]
+        }
+      )
+
+      attr_reader :options
+
+      def initialize(options)
+        @options = options
+        @ai_service = options[:ai_service]
+      end
+
+      def generate
+        JSON.parse(FAKE_MESSAGES)
+      end
+    end
+  end
+end

data/lib/hyrum/generators/message_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Hyrum
+  module Generators
+    AI_SERVICES = %i[openai ollama fake].freeze
+
+    AI_MODEL_DEFAULTS = {
+      openai: :'gpt-4o-mini',
+      ollama: :llama3,
+      fake: :fake
+    }.freeze
+
+    GENERATOR_CLASSES = {
+      openai: OpenaiGenerator,
+      ollama: OpenaiGenerator,
+      fake: FakeGenerator
+    }.freeze
+
+    class MessageGenerator
+      def self.create(options)
+        generator_class = GENERATOR_CLASSES[options[:ai_service].to_sym]
+
+        # Add error handling for invalid format
+        generator_class.new(options)
+      end
+    end
+  end
+end

data/lib/hyrum/generators/openai_generator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'openai'
+require 'json'
+require 'erb'
+
+module Hyrum
+  module Generators
+    class OpenaiGenerator
+      attr_reader :options
+
+      def initialize(options)
+        @options = options
+        configure
+        @client = OpenAI::Client.new
+      end
+
+      def generate
+        if options[:ai_model] == :fake
+          return JSON.parse(canned_content)
+        end
+
+        response = get_response(prompt)
+        puts "Response: #{JSON.pretty_generate(response)}" if options[:verbose]
+        content = response.dig('choices', 0, 'message', 'content')
+        JSON.parse(content)
+      end
+
+      private
+
+      def prompt
+        prompt = <<~PROMPT
+          Please provide 5 alternative status messages for the following message:
+          `<%= message %>`. The messages should be unique and informative. The messages
+          should be returned as json in the format: `{ "<%= key %>": ['list', 'of', 'messages']}`
+          The key should be `"<%= key %>"` followed by the list of messages.
+        PROMPT
+        erb_hash = { key: options[:key], message: options[:message] }
+        template = ERB.new(prompt, trim_mode: '-')
+        template.result_with_hash(erb_hash)
+      end
+
+      def get_response(prompt)
+        @client.chat(
+          parameters: {
+            model: options[:ai_model],
+            response_format: { type: 'json_object' },
+            messages: [{ role: 'user', content: prompt}],
+            temperature: 0.7
+          }
+        )
+      rescue OpenAI::Error => e
+        puts "OpenAI::Error: #{e.message}"
+        exit
+      rescue Faraday::Error => e
+        puts "Faraday::Error: #{e.message}"
+        puts "Please check that the #{options[:ai_model]} model is valid."
+        exit
+      end
+
+      def configure
+        OpenAI.configure do |config|
+          config.access_token = ENV.fetch('OPENAI_ACCESS_TOKEN') if options[:ai_service] == :openai
+          # config.log_errors = true # Use for development
+          config.organization_id = ENV['OPENAI_ORGANIZATION_ID'] if ENV['OPENAI_ORGANIZATION_ID']
+          config.request_timeout = 240
+          if options[:ai_service] == :ollama
+            config.uri_base = ENV['OLLAMA_URL'] || 'http://localhost:11434'
+          end
+        end
+      rescue KeyError => e
+        puts "Error: #{e.message}"
+        puts "Please set the OPENAI_ACCESS_TOKEN environment variable."
+        exit
+      end
+
+      def canned_content
+        FakeGenerator::FAKE_MESSAGES
+      end
+    end
+  end
+end

data/lib/hyrum/script_options.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Hyrum
+  class ScriptOptions
+    MANDATORY_OPTIONS = %i[message].freeze
+
+    attr_reader :options
+
+    def initialize(args)
+      @options = {}
+      @args = args
+    end
+
+    def parse
+      OptionParser.new do |parser|
+        define_options(parser)
+        parser.parse!(@args)
+      end
+      enforce_mandatory_options
+      options
+    rescue OptionParser::InvalidOption => e
+      err = "Invalid option: #{e.message}"
+    rescue OptionParser::MissingArgument => e
+      err = "Missing argument for option: #{e.message}"
+    rescue OptionParser::InvalidArgument => e
+      err = "Invalid argument for option: #{e.message}"
+    ensure
+      if err
+        puts err
+        exit
+      end
+    end
+
+    private
+
+    def enforce_mandatory_options
+      missing = MANDATORY_OPTIONS.select { |param| options[param].nil? }
+      return if missing.empty?
+
+      raise OptionParser::MissingArgument, missing.join(', ')
+    end
+
+    def define_options(parser)
+      parser.banner = 'Usage: hyrum [options]'
+
+      verbosity_options(parser)
+      format_options(parser)
+      message_options(parser)
+      message_key_options(parser)
+      ai_service_options(parser)
+      on_tail_options(parser)
+    end
+
+    def on_tail_options(parser)
+      parser.on_tail('-h', '--help', 'Show this message') do
+        puts parser
+        exit
+      end
+
+      parser.on_tail('--version', 'Show version') do
+        puts Hyrum::VERSION
+        exit
+      end
+    end
+
+    def ai_service_options(parser)
+      description = "AI service: one of #{Generators::AI_SERVICES.join(', ')}"
+      parser.on('-s SERVICE', '--service SERVICE', Generators::AI_SERVICES, description) do |service|
+        options[:ai_service] = service.to_sym
+      end
+      options[:ai_service] ||= :fake
+
+      default_model = Generators::AI_MODEL_DEFAULTS[options[:ai_service]]
+      description = 'AI model: must be a valid model for the selected service'
+      parser.on('-d MODEL', '--model MODEL', description) do |model|
+        options[:ai_model] = model.to_sym
+      end
+      options[:ai_model] ||= default_model
+    end
+
+    def message_key_options(parser)
+      parser.on('-k KEY', '--key KEY', 'Message key') do |key|
+        options[:key] = key
+      end
+      options[:key] ||= 'status'
+    end
+
+    def message_options(parser)
+      parser.on('-m MESSAGE', '--message MESSAGE', 'Status message') do |message|
+        options[:message] = message
+      end
+    end
+
+    def verbosity_options(parser)
+      parser.on('-v', '--[no-]verbose', 'Run verbosely') do |v|
+        options[:verbose] = v
+      end
+    end
+
+    def format_options(parser)
+      formats = Formats::FORMATS
+      description = 'Output format. Supported formats are:'
+      supported   = formats.join(', ')
+      parser.on('-f FORMAT', '--format FORMAT', formats, description, supported) do |format|
+        options[:format] = format
+      end
+      options[:format] ||= :text
+    end
+  end
+end

data/lib/hyrum/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hyrum
+  VERSION = '0.0.1'
+end

data/lib/hyrum.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'zeitwerk'
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module Hyrum
+  def self.run(args)
+    options = ScriptOptions.new(args).parse
+    generator_opts = options.slice(:message, :key, :ai_service, :ai_model, :verbose)
+    formatter_opts = options.slice(:format, :verbose)
+
+    puts "Options: #{options.inspect}" if options[:verbose]
+    formatter = Formats::Formatter.new(formatter_opts)
+    message_generator = Generators::MessageGenerator.create(generator_opts)
+    messages = message_generator.generate
+    output = formatter.format(messages)
+    puts output
+  end
+end
+
+loader.eager_load

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: hyrum
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Tracy Atteberry
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-12-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby-openai
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.3'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: A multi-language code generator to cope with Hyrum's law
+email:
+- tracy@tracyatteberry.com
+executables:
+- hyrum
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- bin/console
+- bin/hyrum
+- bin/setup
+- lib/hyrum.rb
+- lib/hyrum/formats/formatter.rb
+- lib/hyrum/formats/templates/java.erb
+- lib/hyrum/formats/templates/javascript.erb
+- lib/hyrum/formats/templates/json.erb
+- lib/hyrum/formats/templates/python.erb
+- lib/hyrum/formats/templates/ruby.erb
+- lib/hyrum/formats/templates/text.erb
+- lib/hyrum/generators/fake_generator.rb
+- lib/hyrum/generators/message_generator.rb
+- lib/hyrum/generators/openai_generator.rb
+- lib/hyrum/script_options.rb
+- lib/hyrum/version.rb
+homepage: https://github.com/grymoire7/hyrum
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  changelog_uri: https://github.com/grymoire7/hyrum/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options:
+- "--title"
+- Hyrum - Hyrum's Law Code Generator
+- "--main"
+- README.md
+- "--line-numbers"
+- "--inline-source"
+- "--quiet"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key:
+specification_version: 4
+summary: A simple Ruby gem
+test_files: []