ruby_llm-registry 0.1.0

data/lib/ruby_llm/registry/filesystem_backend.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+module RubyLLM
+  module Registry
+    # Filesystem-backed registry adapter.
+    class FilesystemBackend
+      SUPPORTED_EXTENSIONS = %w[.md .prompt].freeze
+
+      def initialize(root:, manifest_path: nil)
+        @root = Pathname.new(root)
+        @manifest_path = manifest_path && Pathname.new(manifest_path)
+      end
+
+      def get(path, version: nil, label: nil)
+        prompt_dir = root.join(path)
+        raise PromptNotFoundError, "Prompt path not found: #{path}" unless prompt_dir.directory?
+
+        manifest = load_manifest
+        file_path = resolve_file_path(prompt_dir, path, version: version, label: label, manifest: manifest)
+        if file_path.nil?
+          raise PromptNotFoundError,
+                "Prompt not found: #{path}#{lookup_suffix(version: version, label: label)}"
+        end
+
+        parse_prompt(path, file_path)
+      end
+
+      def available_versions(path)
+        prompt_dir = root.join(path)
+        return [] unless prompt_dir.directory?
+
+        prompt_dir.children.select { |entry| entry.file? && versioned_prompt_file?(entry) }.map do |entry|
+          Version.parse(version_from_filename(entry.basename.to_s))
+        end.sort
+      end
+
+      def store(prompt, overwrite: false, extension: ".md")
+        prompt_dir = root.join(prompt.path)
+        prompt_dir.mkpath
+        target = prompt_dir.join("v#{prompt.version}#{extension}")
+        raise Error, "Prompt already exists: #{target}" if target.exist? && !overwrite
+
+        target.write(Exporter.new(prompt).to_markdown)
+        prompt
+      end
+
+      private
+
+      attr_reader :root, :manifest_path
+
+      def load_manifest
+        manifest_file = manifest_path || root.join("manifest.yml")
+        return {} unless manifest_file.file?
+
+        YAML.safe_load(manifest_file.read, aliases: true) || {}
+      rescue Psych::SyntaxError
+        {}
+      end
+
+      def resolve_file_path(prompt_dir, prompt_key, version:, label:, manifest:)
+        return resolve_by_version(prompt_dir, version) if version
+        return resolve_by_label(prompt_dir, prompt_key, label, manifest) if label
+
+        resolve_latest(prompt_dir)
+      end
+
+      def resolve_by_version(prompt_dir, version)
+        normalized = Version.parse(version).to_s
+        candidates = candidate_files(prompt_dir).select do |entry|
+          version_from_filename(entry.basename.to_s) == normalized
+        end
+        candidates.first
+      end
+
+      def resolve_by_label(prompt_dir, prompt_key, label, manifest)
+        label = label.to_sym
+
+        if (mapped_version = manifest_version_for(prompt_key, label, manifest))
+          return resolve_by_version(prompt_dir, mapped_version)
+        end
+
+        direct = candidate_files(prompt_dir).find do |entry|
+          entry.basename.to_s.sub(entry.extname, "") == label.to_s || entry.basename.to_s == label.to_s
+        end
+        return direct if direct
+
+        label == :latest ? resolve_latest(prompt_dir) : nil
+      end
+
+      def manifest_version_for(prompt_key, label, manifest)
+        prompt_manifest = manifest.dig("prompts", prompt_key) || manifest.dig(:prompts, prompt_key)
+        return nil unless prompt_manifest.is_a?(Hash)
+
+        aliases = prompt_manifest["aliases"] || prompt_manifest[:aliases] || {}
+        aliases[label.to_s] || aliases[label]
+      end
+
+      def resolve_latest(prompt_dir)
+        candidate_files(prompt_dir).max_by do |entry|
+          Version.parse(version_from_filename(entry.basename.to_s))
+        rescue InvalidVersionError
+          Version.parse("0.0.0")
+        end
+      end
+
+      def candidate_files(prompt_dir)
+        prompt_dir.children.select { |entry| entry.file? && versioned_prompt_file?(entry) }
+      end
+
+      def versioned_prompt_file?(entry)
+        SUPPORTED_EXTENSIONS.include?(entry.extname) && entry.basename.to_s.match?(version_file_pattern(entry.extname))
+      end
+
+      def version_from_filename(filename)
+        filename.sub(/\.(md|prompt)\z/, "").sub(/\Av/, "")
+      end
+
+      def parse_prompt(prompt_key, file_path)
+        content = file_path.read
+        metadata, body = FrontMatter.parse(content)
+        file_version = Version.parse(metadata[:version] || version_from_filename(file_path.basename.to_s))
+        labels = symbol_list(metadata[:labels] || metadata["labels"])
+        required_vars = symbol_list(metadata[:required_vars] || metadata["required_vars"])
+        prompt_metadata = metadata[:metadata] || metadata["metadata"] || {}
+
+        Prompt.new(
+          name: prompt_key.split("/").last,
+          namespace: prompt_key.split("/")[0...-1].join("/"),
+          version: file_version,
+          body: body,
+          source_path: file_path.to_s,
+          labels: labels,
+          metadata: prompt_metadata,
+          required_vars: required_vars
+        )
+      end
+
+      def symbol_list(values)
+        Array(values).map(&:to_sym)
+      end
+
+      def version_file_pattern(extension)
+        /\Av?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?#{Regexp.escape(extension)}\z/
+      end
+
+      def lookup_suffix(version:, label:)
+        if version
+          " version #{version}"
+        elsif label
+          " label #{label}"
+        else
+          ""
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/registry/front_matter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "date"
+require "yaml"
+
+module RubyLLM
+  module Registry
+    # Simple YAML front matter parser for prompt files.
+    module FrontMatter
+      module_function
+
+      def parse(content)
+        return [{}, content] unless content.start_with?("---\n")
+
+        parts = content.split("\n---\n", 2)
+        return [{}, content] if parts.length != 2
+
+        header = parts.first.sub(/\A---\n/, "")
+        body = parts.last
+        metadata = YAML.safe_load(header, permitted_classes: [Date, Time, Symbol], aliases: true) || {}
+        metadata = metadata.each_with_object({}) { |(key, value), hash| hash[key.to_sym] = value }
+        [metadata, body]
+      rescue Psych::SyntaxError
+        [{}, content]
+      end
+    end
+  end
+end

data/lib/ruby_llm/registry/importer.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+require "yaml"
+
+module RubyLLM
+  module Registry
+    # Deserializes prompt exports into Prompt objects.
+    class Importer
+      def initialize(payload, format: :auto, path: nil)
+        @payload = payload
+        @format = format
+        @path = path
+      end
+
+      def to_prompt
+        data, body = case normalized_format
+                     when :hash
+                       extract_hash(payload)
+                     when :json
+                       extract_json(payload)
+                     when :yaml
+                       extract_yaml(payload)
+                     when :markdown
+                       extract_markdown(payload)
+                     else
+                       infer_payload
+                     end
+
+        build_prompt(data, body)
+      end
+
+      private
+
+      attr_reader :payload, :format, :path
+
+      def normalized_format
+        format == :auto ? infer_format : format.to_sym
+      end
+
+      def infer_format
+        return :hash if payload.is_a?(Hash)
+        return :markdown if payload.to_s.start_with?("---\n")
+        return :json if payload.to_s.lstrip.start_with?("{")
+
+        :yaml
+      end
+
+      def infer_payload
+        case infer_format
+        when :hash then extract_hash(payload)
+        when :markdown then extract_markdown(payload)
+        when :json then extract_json(payload)
+        else extract_yaml(payload)
+        end
+      end
+
+      def extract_hash(value)
+        data = value.transform_keys(&:to_sym)
+        [data, data[:body] || ""]
+      end
+
+      def extract_json(value)
+        data = JSON.parse(value.to_s)
+        extract_hash(data)
+      end
+
+      def extract_yaml(value)
+        data = YAML.safe_load(value.to_s, permitted_classes: [Date, Time, Symbol], aliases: true) || {}
+        extract_hash(data)
+      end
+
+      def extract_markdown(value)
+        data, body = FrontMatter.parse(value.to_s)
+        [data, body]
+      end
+
+      def build_prompt(data, body)
+        prompt_path = path || data[:path] || data["path"]
+        namespace, name = split_path(prompt_path, data)
+        Prompt.new(
+          name: name,
+          namespace: namespace,
+          version: data[:version] || data["version"] || "0.0.0",
+          body: body,
+          source_path: data[:source_path] || data["source_path"],
+          labels: data[:labels] || data["labels"] || [],
+          metadata: data[:metadata] || data["metadata"] || {},
+          required_vars: data[:required_vars] || data["required_vars"] || []
+        )
+      end
+
+      def split_path(prompt_path, data)
+        if prompt_path && prompt_path.include?("/")
+          pieces = prompt_path.split("/")
+          [pieces[0...-1].join("/"), pieces.last]
+        else
+          namespace = data[:namespace] || data["namespace"] || ""
+          name = data[:name] || data["name"] || prompt_path || "prompt"
+          [namespace, name]
+        end
+      end
+    end
+  end
+end
+

data/lib/ruby_llm/registry/prompt.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module RubyLLM
+  module Registry
+    # Represents a loaded prompt template plus its metadata.
+    class Prompt
+      attr_reader :name, :namespace, :version, :labels, :metadata, :required_vars, :body, :source_path
+
+      def initialize(name:, namespace:, version:, body:, source_path:, labels: [], metadata: {}, required_vars: [])
+        @name = name.to_s
+        @namespace = namespace.to_s
+        @version = version.is_a?(Version) ? version : Version.parse(version)
+        @body = body.to_s
+        @source_path = source_path
+        @labels = Array(labels).compact.map(&:to_sym)
+        @metadata = symbolize_keys(metadata)
+        @required_vars = Array(required_vars).compact.map(&:to_sym)
+      end
+
+      def path
+        [namespace, name].reject(&:empty?).join("/")
+      end
+
+      def render(context = nil, **kwargs)
+        values = normalize_context(context, kwargs)
+        validate_required_vars!(values)
+        ERB.new(body, trim_mode: "-").result(RenderContext.new(values).instance_eval { binding })
+      end
+
+      def to_message(role: :system, context: nil, **)
+        { role: role, content: render(context, **) }
+      end
+
+      def export(format: :markdown)
+        Exporter.new(self).public_send(exporter_method(format))
+      end
+
+      def diff(other)
+        other_prompt = other.is_a?(Prompt) ? other : Importer.new(other, format: :auto).to_prompt
+        Comparison.new(self, other_prompt)
+      end
+
+      def to_h
+        {
+          path: path,
+          namespace: namespace,
+          name: name,
+          version: version.to_s,
+          labels: labels,
+          metadata: metadata,
+          required_vars: required_vars,
+          source_path: source_path,
+          body: body
+        }
+      end
+
+      private
+
+      def normalize_context(context, kwargs)
+        if context.is_a?(Hash)
+          context.merge(kwargs)
+        elsif context.nil?
+          kwargs
+        elsif kwargs.empty?
+          context.respond_to?(:to_h) ? context.to_h : { context: context }
+        else
+          raise ArgumentError, "Pass either a context hash or keyword arguments, not both"
+        end
+      end
+
+      def validate_required_vars!(values)
+        missing = required_vars.reject { |key| values.key?(key) || values.key?(key.to_s) }
+        return if missing.empty?
+
+        raise MissingVariableError, "Missing required prompt variables: #{missing.join(", ")}"
+      end
+
+      def symbolize_keys(hash)
+        hash.each_with_object({}) do |(key, value), memo|
+          memo[key.to_sym] = value
+        end
+      end
+
+      def exporter_method(format)
+        case format.to_sym
+        when :yaml then :to_yaml
+        when :json then :to_json
+        when :markdown, :md then :to_markdown
+        when :hash then :to_h
+        else
+          raise ArgumentError, "Unsupported export format: #{format.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/registry/semver.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Registry
+    class Version
+      include Comparable
+
+      VERSION_PATTERN = /\Av?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?\z/
+
+      attr_reader :major, :minor, :patch, :prerelease
+
+      def self.parse(value)
+        match = VERSION_PATTERN.match(value.to_s)
+        raise InvalidVersionError, "Invalid semantic version: #{value.inspect}" unless match
+
+        new(
+          major: match[1].to_i,
+          minor: match[2].to_i,
+          patch: match[3].to_i,
+          prerelease: match[4]
+        )
+      end
+
+      def initialize(major:, minor:, patch:, prerelease: nil)
+        @major = major
+        @minor = minor
+        @patch = patch
+        @prerelease = prerelease
+      end
+
+      def <=>(other)
+        other = self.class.parse(other) unless other.is_a?(self.class)
+
+        [major, minor, patch, release_rank, prerelease.to_s] <=> [other.major, other.minor, other.patch, other.release_rank, other.prerelease.to_s]
+      end
+
+      def release_rank
+        prerelease.nil? ? 1 : 0
+      end
+
+      def stable?
+        prerelease.nil?
+      end
+
+      def to_s
+        base = "#{major}.#{minor}.#{patch}"
+        prerelease.nil? ? base : "#{base}-#{prerelease}"
+      end
+
+      def inspect
+        "#<#{self.class.name} #{self}>"
+      end
+    end
+  end
+end

data/lib/ruby_llm/registry/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Registry
+    VERSION = "0.1.0"
+  end
+end

data/lib/ruby_llm/registry.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "registry/version"
+require_relative "registry/errors"
+require_relative "registry/semver"
+require_relative "registry/front_matter"
+require_relative "registry/context"
+require_relative "registry/prompt"
+require_relative "registry/comparison"
+require_relative "registry/exporter"
+require_relative "registry/importer"
+require_relative "registry/adapters"
+require_relative "registry/filesystem_backend"
+
+module RubyLLM
+  module Registry
+    class Configuration
+      attr_accessor :root, :manifest_path, :default_adapter, :default_database_adapter
+
+      def initialize
+        @root = nil
+        @manifest_path = nil
+        @default_adapter = :filesystem
+        @default_database_adapter = :sqlite
+      end
+    end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset!
+        @configuration = nil
+      end
+
+      def get(path, version: nil, label: nil, root: nil, manifest_path: nil)
+        backend(root: root, manifest_path: manifest_path).get(path, version: version, label: label)
+      end
+
+      def backend(type = nil, **options)
+        type = (type || configuration.default_adapter).to_sym
+
+        case type
+        when :filesystem
+          FilesystemBackend.new(
+            root: options[:root] || configuration.root || default_root,
+            manifest_path: options[:manifest_path] || configuration.manifest_path
+          )
+        when :sqlite, :active_record, :ar, :mongo, :mongodb, :s3
+          Adapters.build(type, **options)
+        else
+          raise ArgumentError, "Unknown backend type: #{type.inspect}"
+        end
+      end
+
+      def database_backend(type = nil, **options)
+        backend(type || configuration.default_database_adapter, **options)
+      end
+
+      def export(prompt_or_path, format: :markdown, backend: nil, version: nil, label: nil, **options)
+        prompt = if prompt_or_path.is_a?(Prompt)
+                   prompt_or_path
+                 elsif backend
+                   backend.get(prompt_or_path, version: version, label: label)
+                 else
+                   get(prompt_or_path, version: version, label: label, **options)
+                 end
+        Exporter.new(prompt).public_send(exporter_method(format))
+      end
+
+      def import(payload, format: :auto, backend: nil, **options)
+        prompt = Importer.new(payload, format: format, **options).to_prompt
+        backend&.store(prompt)
+        prompt
+      end
+
+      def diff(left, right)
+        left_prompt = left.respond_to?(:body) ? left : Importer.new(left, format: :auto).to_prompt
+        right_prompt = right.respond_to?(:body) ? right : Importer.new(right, format: :auto).to_prompt
+        Comparison.new(left_prompt, right_prompt)
+      end
+
+      def default_root
+        local_candidates = %w[prompts app/prompts].map { |relative| File.join(Dir.pwd, relative) }
+        local_candidates.find { |candidate| Dir.exist?(candidate) } || File.join(Dir.pwd, "prompts")
+      end
+
+      private
+
+      def exporter_method(format)
+        case format.to_sym
+        when :yaml then :to_yaml
+        when :json then :to_json
+        when :markdown, :md then :to_markdown
+        when :hash then :to_h
+        else
+          raise ArgumentError, "Unsupported export format: #{format.inspect}"
+        end
+      end
+    end
+  end
+end

data/sig/ruby_llm/registry.rbs

@@ -0,0 +1,6 @@
+module RubyLlm
+  module Registry
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-registry
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sal Scotto
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Local-first, versioned prompt storage and rendering for RubyLLM applications.
+email:
+- sal.scotto@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".idea/.gitignore"
+- ".idea/inspectionProfiles/Project_Default.xml"
+- ".idea/jsLibraryMappings.xml"
+- ".idea/misc.xml"
+- ".idea/modules.xml"
+- ".idea/ruby_llm-registry.iml"
+- ".idea/vcs.xml"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- build_release.sh
+- lib/ruby_llm/registry.rb
+- lib/ruby_llm/registry/adapters.rb
+- lib/ruby_llm/registry/adapters/active_record.rb
+- lib/ruby_llm/registry/adapters/base.rb
+- lib/ruby_llm/registry/adapters/mongo.rb
+- lib/ruby_llm/registry/adapters/s3.rb
+- lib/ruby_llm/registry/adapters/sqlite.rb
+- lib/ruby_llm/registry/comparison.rb
+- lib/ruby_llm/registry/context.rb
+- lib/ruby_llm/registry/errors.rb
+- lib/ruby_llm/registry/exporter.rb
+- lib/ruby_llm/registry/filesystem_backend.rb
+- lib/ruby_llm/registry/front_matter.rb
+- lib/ruby_llm/registry/importer.rb
+- lib/ruby_llm/registry/prompt.rb
+- lib/ruby_llm/registry/semver.rb
+- lib/ruby_llm/registry/version.rb
+- sig/ruby_llm/registry.rbs
+homepage: https://github.com/washu/ruby_llm-registry
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/washu/ruby_llm-registry
+  source_code_uri: https://github.com/washu/ruby_llm-registry
+  changelog_uri: https://github.com/washu/ruby_llm-registry/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Production-grade prompt lifecycle management for RubyLLM
+test_files: []