ruby_llm-contract 0.2.0

data/lib/ruby_llm/contract.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "contract/version"
+require_relative "contract/errors"
+require_relative "contract/types"
+
+module RubyLLM
+  module Contract
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+        auto_create_adapter! if configuration.default_adapter.nil?
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      # --- Eval host registry ---
+
+      def register_eval_host(klass)
+        eval_hosts << klass unless eval_hosts.include?(klass)
+      end
+
+      def eval_hosts
+        @eval_hosts ||= []
+      end
+
+      def run_all_evals(context: {})
+        live_eval_hosts.to_h do |host|
+          [host, host.run_eval(context: context)]
+        end
+      end
+
+      def reset_eval_hosts!
+        @eval_hosts = []
+      end
+
+      def load_evals!(dir = nil)
+        dirs = if dir
+                 [dir]
+               elsif defined?(::Rails)
+                 %w[app/steps/eval app/contracts/eval].filter_map do |path|
+                   full = ::Rails.root.join(path)
+                   full.to_s if full.exist?
+                 end
+               else
+                 []
+               end
+
+        return if dirs.empty?
+
+        # Clear existing eval definitions before reload to prevent stale state.
+        # Thread-local flag suppresses the "redefining" warning during reload.
+        Thread.current[:ruby_llm_contract_reloading] = true
+        eval_hosts.each do |host|
+          host.clear_eval_definitions! if host.respond_to?(:clear_eval_definitions!)
+        end
+
+        dirs.each do |d|
+          Dir[File.join(d, "**", "*_eval.rb")].each { |f| load f }
+        end
+      ensure
+        Thread.current[:ruby_llm_contract_reloading] = false
+      end
+
+      private
+
+      # Filter out GC'd anonymous classes and classes that no longer have evals
+      def live_eval_hosts
+        eval_hosts.select do |host|
+          host.respond_to?(:eval_defined?) && host.eval_defined?
+        end
+      end
+
+      def auto_create_adapter!
+        require "ruby_llm"
+        configuration.default_adapter = Adapters::RubyLLM.new
+      rescue LoadError
+        nil
+      end
+    end
+  end
+end
+
+require_relative "contract/concerns/deep_symbolize"
+require_relative "contract/concerns/eval_host"
+require_relative "contract/concerns/trace_equality"
+require_relative "contract/concerns/usage_aggregator"
+require_relative "contract/configuration"
+require_relative "contract/prompt/node"
+require_relative "contract/prompt/nodes"
+require_relative "contract/prompt/ast"
+require_relative "contract/prompt/builder"
+require_relative "contract/prompt/renderer"
+require_relative "contract/contract"
+require_relative "contract/cost_calculator"
+require_relative "contract/token_estimator"
+require_relative "contract/adapters"
+require_relative "contract/step"
+require_relative "contract/pipeline"
+require_relative "contract/eval"
+require_relative "contract/dsl"
+require_relative "contract/railtie" if defined?(Rails::Railtie)

data/ruby_llm-contract.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/ruby_llm/contract/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ruby_llm-contract"
+  spec.version = RubyLLM::Contract::VERSION
+  spec.authors = ["Justyna"]
+
+  spec.summary = "Contract-first LLM step execution for RubyLLM"
+  spec.description = "Turn RubyLLM calls into contracted, validated, testable steps with schema enforcement, " \
+                     "retry with model escalation, and eval."
+  spec.homepage = "https://github.com/justi/ruby_llm-contract"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?("spec/", "docs/", "doc/", ".ai/", ".claude/", ".git")
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "dry-types", "~> 1.7"
+  spec.add_dependency "ruby_llm", "~> 1.0"
+  spec.add_dependency "ruby_llm-schema", "~> 0.3"
+end

metadata

@@ -0,0 +1,172 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-contract
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Justyna
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+description: Turn RubyLLM calls into contracted, validated, testable steps with schema
+  enforcement, retry with model escalation, and eval.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- examples/00_basics.rb
+- examples/01_classify_threads.rb
+- examples/02_generate_comment.rb
+- examples/03_target_audience.rb
+- examples/04_real_llm.rb
+- examples/05_output_schema.rb
+- examples/07_keyword_extraction.rb
+- examples/08_translation.rb
+- examples/09_eval_dataset.rb
+- examples/10_reddit_full_showcase.rb
+- examples/README.md
+- lib/ruby_llm/contract.rb
+- lib/ruby_llm/contract/adapters.rb
+- lib/ruby_llm/contract/adapters/base.rb
+- lib/ruby_llm/contract/adapters/response.rb
+- lib/ruby_llm/contract/adapters/ruby_llm.rb
+- lib/ruby_llm/contract/adapters/test.rb
+- lib/ruby_llm/contract/concerns/deep_symbolize.rb
+- lib/ruby_llm/contract/concerns/eval_host.rb
+- lib/ruby_llm/contract/concerns/trace_equality.rb
+- lib/ruby_llm/contract/concerns/usage_aggregator.rb
+- lib/ruby_llm/contract/configuration.rb
+- lib/ruby_llm/contract/contract.rb
+- lib/ruby_llm/contract/contract/definition.rb
+- lib/ruby_llm/contract/contract/invariant.rb
+- lib/ruby_llm/contract/contract/parser.rb
+- lib/ruby_llm/contract/contract/schema_validator.rb
+- lib/ruby_llm/contract/contract/validator.rb
+- lib/ruby_llm/contract/cost_calculator.rb
+- lib/ruby_llm/contract/dsl.rb
+- lib/ruby_llm/contract/errors.rb
+- lib/ruby_llm/contract/eval.rb
+- lib/ruby_llm/contract/eval/case_result.rb
+- lib/ruby_llm/contract/eval/contract_detail_builder.rb
+- lib/ruby_llm/contract/eval/dataset.rb
+- lib/ruby_llm/contract/eval/eval_definition.rb
+- lib/ruby_llm/contract/eval/evaluation_result.rb
+- lib/ruby_llm/contract/eval/evaluator/exact.rb
+- lib/ruby_llm/contract/eval/evaluator/json_includes.rb
+- lib/ruby_llm/contract/eval/evaluator/proc_evaluator.rb
+- lib/ruby_llm/contract/eval/evaluator/regex.rb
+- lib/ruby_llm/contract/eval/model_comparison.rb
+- lib/ruby_llm/contract/eval/pipeline_result_adapter.rb
+- lib/ruby_llm/contract/eval/report.rb
+- lib/ruby_llm/contract/eval/runner.rb
+- lib/ruby_llm/contract/eval/trait_evaluator.rb
+- lib/ruby_llm/contract/pipeline.rb
+- lib/ruby_llm/contract/pipeline/base.rb
+- lib/ruby_llm/contract/pipeline/result.rb
+- lib/ruby_llm/contract/pipeline/runner.rb
+- lib/ruby_llm/contract/pipeline/trace.rb
+- lib/ruby_llm/contract/prompt/ast.rb
+- lib/ruby_llm/contract/prompt/builder.rb
+- lib/ruby_llm/contract/prompt/node.rb
+- lib/ruby_llm/contract/prompt/nodes.rb
+- lib/ruby_llm/contract/prompt/nodes/example_node.rb
+- lib/ruby_llm/contract/prompt/nodes/rule_node.rb
+- lib/ruby_llm/contract/prompt/nodes/section_node.rb
+- lib/ruby_llm/contract/prompt/nodes/system_node.rb
+- lib/ruby_llm/contract/prompt/nodes/user_node.rb
+- lib/ruby_llm/contract/prompt/renderer.rb
+- lib/ruby_llm/contract/railtie.rb
+- lib/ruby_llm/contract/rake_task.rb
+- lib/ruby_llm/contract/rspec.rb
+- lib/ruby_llm/contract/rspec/pass_eval.rb
+- lib/ruby_llm/contract/rspec/satisfy_contract.rb
+- lib/ruby_llm/contract/step.rb
+- lib/ruby_llm/contract/step/base.rb
+- lib/ruby_llm/contract/step/dsl.rb
+- lib/ruby_llm/contract/step/limit_checker.rb
+- lib/ruby_llm/contract/step/result.rb
+- lib/ruby_llm/contract/step/retry_executor.rb
+- lib/ruby_llm/contract/step/retry_policy.rb
+- lib/ruby_llm/contract/step/runner.rb
+- lib/ruby_llm/contract/step/trace.rb
+- lib/ruby_llm/contract/token_estimator.rb
+- lib/ruby_llm/contract/types.rb
+- lib/ruby_llm/contract/version.rb
+- ruby_llm-contract.gemspec
+homepage: https://github.com/justi/ruby_llm-contract
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/justi/ruby_llm-contract
+  source_code_uri: https://github.com/justi/ruby_llm-contract
+  changelog_uri: https://github.com/justi/ruby_llm-contract/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.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Contract-first LLM step execution for RubyLLM
+test_files: []