self_agency 0.0.1

data/lib/self_agency.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require "method_source"
+require_relative "self_agency/version"
+require_relative "self_agency/errors"
+require_relative "self_agency/configuration"
+require_relative "self_agency/sandbox"
+require_relative "self_agency/validator"
+require_relative "self_agency/generator"
+require_relative "self_agency/saver"
+
+# SelfAgency — a standalone mixin that gives any class the ability to
+# generate and install methods at runtime via an LLM.
+#
+# Usage:
+#   SelfAgency.configure do |config|
+#     config.provider = :ollama
+#     config.model    = "qwen3-coder:30b"
+#     config.api_base = "http://localhost:11434/v1"
+#   end
+#
+#   class Foo
+#     include SelfAgency
+#   end
+#
+#   foo = Foo.new
+#   method_name = foo._("an instance method to add two integers, return the result")
+#   foo.send(method_name, 1, 1) #=> 2
+#
+module SelfAgency
+  # ---------------------------------------------------------------------------
+  # Class-level API — added to including classes via self.included
+  # ---------------------------------------------------------------------------
+
+  module ClassMethods
+    # Return the generated source code for +method_name+, or nil if unavailable.
+    # Checks LLM-generated source first, then falls back to method_source.
+    # LLM-generated methods include the original description as a comment header.
+    def _source_for(method_name)
+      name = method_name.to_sym
+      if (code = self_agency_class_sources[name])
+        self_agency_comment_header(self_agency_class_descriptions[name]) + code
+      else
+        self_agency_file_source(instance_method(name))
+      end
+    rescue NameError, MethodSource::SourceNotFoundError
+      nil
+    end
+
+    # Return the version history for +method_name+, or an empty array.
+    # Each entry is a Hash with keys :code, :description, :instance_id, :at.
+    def _source_versions_for(method_name)
+      self_agency_class_source_versions[method_name.to_sym] || []
+    end
+
+    def self_agency_class_sources
+      @self_agency_class_sources ||= {}
+    end
+
+    def self_agency_class_descriptions
+      @self_agency_class_descriptions ||= {}
+    end
+
+    def self_agency_class_source_versions
+      @self_agency_class_source_versions ||= {}
+    end
+
+    # Return the per-class mutex used to serialize the _() pipeline.
+    def self_agency_mutex
+      @self_agency_mutex
+    end
+
+    # Return the cached sandbox module for the given scope, creating and
+    # prepending it on first access.  Reusing a single module per scope
+    # prevents anonymous-module accumulation in the ancestor chain.
+    def self_agency_sandbox_module(scope)
+      case scope
+      when :instance
+        @self_agency_instance_sandbox ||= begin
+          mod = Module.new { include SelfAgency::Sandbox }
+          prepend(mod)
+          mod
+        end
+      when :class
+        @self_agency_class_sandbox ||= begin
+          mod = Module.new { include SelfAgency::Sandbox }
+          singleton_class.prepend(mod)
+          mod
+        end
+      end
+    end
+
+    private
+
+    def self_agency_comment_header(description)
+      return "" unless description
+      description.lines.map { |line| "# #{line.chomp}\n" }.join
+    end
+
+    def self_agency_file_source(meth)
+      comment = meth.comment.to_s
+      source  = meth.source
+      comment.empty? ? source : comment + source
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Public instance API
+  # ---------------------------------------------------------------------------
+
+  # Generate and install a method described by +description+.
+  #
+  # @param description [String] natural-language description of the method
+  # @param scope [Symbol] :instance, :singleton, or :class
+  # @return [Array<Symbol>] the names of the newly defined methods
+  # @raise [GenerationError]  if the LLM returns nil
+  # @raise [ValidationError]  if the generated code fails validation
+  # @raise [SecurityError]    if the generated code contains dangerous patterns
+  def _(description, scope: :instance)
+    self.class.self_agency_mutex.synchronize do
+      SelfAgency.ensure_configured!
+
+      self_agency_log(:shape, "Shaping prompt for #{self.class.name} (#{scope})")
+      shaped = self_agency_shape(description, scope)
+      unless shaped
+        raise GenerationError.new("Prompt shaping failed (LLM returned nil)", stage: :shape)
+      end
+      self_agency_log(:shape, "Shaped spec received")
+
+      max_attempts = SelfAgency.configuration.generation_retries
+      last_error   = nil
+      gen_vars     = self_agency_generation_vars.merge(shaped_spec: shaped, previous_error: nil, previous_code: nil)
+      code         = nil
+
+      max_attempts.times.each do |attempt|
+        self_agency_log(:generate, "Generation attempt #{attempt + 1}/#{max_attempts}")
+        raw = self_agency_ask_with_template(:generate, **gen_vars)
+        unless raw
+          raise GenerationError.new(
+            "Code generation failed (LLM returned nil)",
+            stage: :generate, attempt: attempt + 1
+          )
+        end
+        self_agency_log(:generate, "Raw code received")
+
+        code = self_agency_sanitize(raw)
+        begin
+          self_agency_validate!(code)
+          self_agency_log(:validate, "Validation passed")
+          last_error = nil
+          break
+        rescue ValidationError => e
+          self_agency_log(:validate, "Validation failed: #{e.message}")
+          last_error = ValidationError.new(e.message, generated_code: e.generated_code, attempt: attempt + 1)
+          gen_vars = gen_vars.merge(previous_error: e.message, previous_code: code)
+          self_agency_log(:retry, "Retrying due to: #{e.message}") if attempt + 1 < max_attempts
+        rescue SecurityError => e
+          self_agency_log(:validate, "Security check failed: #{e.message}")
+          last_error = SecurityError.new(e.message, matched_pattern: e.matched_pattern, generated_code: e.generated_code)
+          gen_vars = gen_vars.merge(previous_error: e.message, previous_code: code)
+          self_agency_log(:retry, "Retrying due to: #{e.message}") if attempt + 1 < max_attempts
+        end
+      end
+
+      raise last_error if last_error
+
+      self_agency_eval(code, scope)
+
+      method_blocks = self_agency_split_methods(code)
+      method_names = method_blocks.map do |name, block|
+        self_agency_sources[name] = block
+        self_agency_descriptions[name] = description
+        self.class.self_agency_class_sources[name] = block
+        self.class.self_agency_class_descriptions[name] = description
+        (self.class.self_agency_class_source_versions[name] ||= []) << {
+          code: block,
+          description: description,
+          instance_id: object_id,
+          at: Time.now
+        }
+        on_method_generated(name, scope, block)
+        name
+      end
+
+      self_agency_log(:complete, "Installed #{method_names.size} method(s): #{method_names.join(', ')}")
+      method_names
+    end
+  end
+
+  alias_method :self_agency_generate, :_
+
+  # Return the generated source code for +method_name+, or nil if unavailable.
+  # Checks LLM-generated source first, then falls back to method_source.
+  # LLM-generated methods include the original description as a comment header.
+  def _source_for(method_name)
+    name = method_name.to_sym
+    if (code = self_agency_sources[name])
+      self_agency_comment_header(self_agency_descriptions[name]) + code
+    else
+      self_agency_file_source(method(name))
+    end
+  rescue NameError, MethodSource::SourceNotFoundError
+    nil
+  end
+
+  # Save the object's generated methods as a subclass in a Ruby source file.
+  #
+  # @param as [String, Symbol] the subclass name (snake_case is converted to CamelCase)
+  # @param path [String, nil] output file path (defaults to snake_cased name + .rb)
+  # @return [String] the path written to
+  # @raise [ArgumentError] if as: is not a String or Symbol
+  # @raise [Error] if there are no generated methods to save
+  def _save!(as:, path: nil)
+    raise ArgumentError, "as: must be a String or Symbol" unless as.is_a?(String) || as.is_a?(Symbol)
+    raise Error, "no generated methods to save" if self_agency_sources.empty?
+
+    class_name  = self_agency_to_class_name(as)
+    file_path   = path || "#{self_agency_to_snake_case(class_name)}.rb"
+    parent_name = self.class.name
+    raise Error, "cannot save anonymous class" unless parent_name
+
+    parent_source = Object.const_source_location(parent_name)&.first
+
+    require_path = if parent_source
+      self_agency_relative_require(file_path, parent_source)
+    end
+
+    source = self_agency_build_subclass_source(
+      class_name, parent_name, require_path,
+      self_agency_sources, self_agency_descriptions
+    )
+
+    File.write(file_path, source)
+    file_path
+  end
+
+  # Override in your class to persist or log generated methods.
+  def on_method_generated(method_name, scope, code)
+    # no-op by default
+  end
+
+  # ---------------------------------------------------------------------------
+  # Private helpers
+  # ---------------------------------------------------------------------------
+  private
+
+  def self_agency_comment_header(description)
+    return "" unless description
+    description.lines.map { |line| "# #{line.chomp}\n" }.join
+  end
+
+  def self_agency_file_source(meth)
+    comment = meth.comment.to_s
+    source  = meth.source
+    comment.empty? ? source : comment + source
+  end
+
+  # Lazily initialized Hash storing generated source code keyed by method name.
+  def self_agency_sources
+    @self_agency_sources ||= {}
+  end
+
+  def self_agency_descriptions
+    @self_agency_descriptions ||= {}
+  end
+
+  # Split code containing one or more method definitions into
+  # an Array of [method_name_symbol, method_source_string] pairs.
+  def self_agency_split_methods(code)
+    blocks = code.scan(/^(def\s+(?:self\.)?\w+[?!=]?.*?^end)/m)
+    blocks.map do |match|
+      block = match[0]
+      name  = block.match(/\bdef\s+(self\.)?(\w+[?!=]?)/)[2].to_sym
+      [name, block]
+    end
+  end
+
+  # Evaluate the code inside the cached sandboxed module for this scope.
+  # Reuses a single module per scope to avoid MRO accumulation.
+  def self_agency_eval(code, scope)
+    case scope
+    when :instance
+      self.class.self_agency_sandbox_module(:instance).module_eval(code)
+    when :singleton
+      self_agency_singleton_sandbox_module.module_eval(code)
+    when :class
+      class_code = code.sub(/\bdef\s+self\./, "def ")
+      self.class.self_agency_sandbox_module(:class).module_eval(class_code)
+    else
+      raise ValidationError, "unknown scope: #{scope.inspect}"
+    end
+  end
+
+  # Log a pipeline event via the configured logger.
+  # Accepts a callable (receives stage, message) or a Logger-compatible object.
+  def self_agency_log(stage, message)
+    logger = SelfAgency.configuration.logger
+    return unless logger
+
+    if logger.respond_to?(:call)
+      logger.call(stage, message)
+    elsif logger.respond_to?(:debug)
+      logger.debug("[SelfAgency:#{stage}] #{message}")
+    end
+  end
+
+  # Return the cached singleton-scope sandbox module for this instance.
+  def self_agency_singleton_sandbox_module
+    @self_agency_singleton_sandbox ||= begin
+      mod = Module.new { include SelfAgency::Sandbox }
+      singleton_class.prepend(mod)
+      mod
+    end
+  end
+end

data/mkdocs.yml

@@ -0,0 +1,156 @@
+# MkDocs Configuration for SelfAgency Documentation
+site_name: SelfAgency
+site_description: LLM-powered runtime method generation for Ruby classes
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/self_agency
+copyright: Copyright © 2025 Dewayne VanHoozer
+
+# Repository information
+repo_name: madbomber/self_agency
+repo_url: https://github.com/madbomber/self_agency
+edit_uri: edit/main/docs/
+
+# Configuration
+theme:
+  name: material
+
+  palette:
+    - scheme: default
+      primary: deep purple
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    - scheme: slate
+      primary: deep purple
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  icon:
+    repo: fontawesome/brands/github
+
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - navigation.footer
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+# Plugins
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+  - tags
+
+# Extensions
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: madbomber
+      repo: self_agency
+      normalize_issue_symbols: true
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.snippets:
+      check_paths: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+# Social media and extra configuration
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/madbomber/self_agency
+      name: SelfAgency on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/self_agency
+      name: SelfAgency on RubyGems
+
+# Navigation
+nav:
+  - Home:
+      - Overview: index.md
+  - Getting Started:
+      - Installation: getting-started/installation.md
+      - Quick Start: getting-started/quick-start.md
+  - Guide:
+      - How to Use: guide/how-to-use.md
+      - Generating Methods: guide/generating-methods.md
+      - Scopes: guide/scopes.md
+      - Source Inspection: guide/source-inspection.md
+      - Saving Methods: guide/saving-methods.md
+      - Lifecycle Hooks: guide/lifecycle-hooks.md
+      - Configuration: guide/configuration.md
+      - Prompt Templates: guide/prompt-templates.md
+  - Architecture:
+      - Overview: architecture/overview.md
+      - Security: architecture/security.md
+  - API Reference:
+      - api/index.md
+      - SelfAgency Module: api/self-agency-module.md
+      - Configuration: api/configuration.md
+      - Errors: api/errors.md
+  - Examples:
+      - examples/index.md
+      - "Basic (01\u201309)": examples/basic-examples.md
+      - "Full Workflow (10)": examples/full-workflow.md
+      - "Collaborative Robots (11)": examples/collaborative-robots.md
+      - "Autonomous Robots (12)": examples/autonomous-robots.md
+  - Development:
+      - Setup: development/setup.md
+      - Testing: development/testing.md
+      - Contributing: development/contributing.md

data/sig/self_agency.rbs

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

metadata

@@ -0,0 +1,163 @@
+--- !ruby/object:Gem::Specification
+name: self_agency
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Dewayne VanHoozer
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: method_source
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm-template
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A mixin that gives any Ruby class the ability to generate and install
+  methods at runtime via an LLM. Describe what you want in plain English and get a
+  working method back.
+email:
+- dewayne@vanhoozer.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".envrc"
+- ".github/workflows/deploy-github-pages.yml"
+- ".irbrc"
+- CHANGELOG.md
+- COMMITS.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/api/configuration.md
+- docs/api/errors.md
+- docs/api/index.md
+- docs/api/self-agency-module.md
+- docs/architecture/overview.md
+- docs/architecture/security.md
+- docs/assets/images/self_agency.gif
+- docs/assets/images/self_agency.mp4
+- docs/development/contributing.md
+- docs/development/setup.md
+- docs/development/testing.md
+- docs/examples/autonomous-robots.md
+- docs/examples/basic-examples.md
+- docs/examples/collaborative-robots.md
+- docs/examples/full-workflow.md
+- docs/examples/index.md
+- docs/getting-started/installation.md
+- docs/getting-started/quick-start.md
+- docs/guide/configuration.md
+- docs/guide/generating-methods.md
+- docs/guide/how-to-use.md
+- docs/guide/lifecycle-hooks.md
+- docs/guide/prompt-templates.md
+- docs/guide/saving-methods.md
+- docs/guide/scopes.md
+- docs/guide/source-inspection.md
+- docs/index.md
+- examples/01_basic_usage.rb
+- examples/02_multiple_methods.rb
+- examples/03_scopes.rb
+- examples/04_source_inspection.rb
+- examples/05_lifecycle_hook.rb
+- examples/06_configuration.rb
+- examples/07_error_handling.rb
+- examples/08_class_context.rb
+- examples/09_method_override.rb
+- examples/10_full_workflow.rb
+- examples/11_collaborative_robots/atlas.rb
+- examples/11_collaborative_robots/echo.rb
+- examples/11_collaborative_robots/main.rb
+- examples/11_collaborative_robots/nova.rb
+- examples/11_collaborative_robots/robot.rb
+- examples/12_autonomous_robots/analyst.rb
+- examples/12_autonomous_robots/collector.rb
+- examples/12_autonomous_robots/main.rb
+- examples/12_autonomous_robots/planner.rb
+- examples/12_autonomous_robots/robot.rb
+- examples/generated/from_range_class.rb
+- examples/generated/mean_instance.rb
+- examples/generated/median_instance.rb
+- examples/generated/report_singleton.rb
+- examples/generated/standard_deviation_instance.rb
+- examples/lib/message_bus.rb
+- examples/lib/setup.rb
+- lib/self_agency.rb
+- lib/self_agency/configuration.rb
+- lib/self_agency/errors.rb
+- lib/self_agency/generator.rb
+- lib/self_agency/prompts/generate/system.txt.erb
+- lib/self_agency/prompts/generate/user.txt.erb
+- lib/self_agency/prompts/shape/system.txt.erb
+- lib/self_agency/prompts/shape/user.txt.erb
+- lib/self_agency/sandbox.rb
+- lib/self_agency/saver.rb
+- lib/self_agency/validator.rb
+- lib/self_agency/version.rb
+- mkdocs.yml
+- sig/self_agency.rbs
+homepage: https://github.com/madbomber/self_agency
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/madbomber/self_agency
+  source_code_uri: https://github.com/madbomber/self_agency
+  changelog_uri: https://github.com/madbomber/self_agency/blob/main/CHANGELOG.md
+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: 4.0.5
+specification_version: 4
+summary: LLM-powered runtime method generation for Ruby classes
+test_files: []