self_agency 0.0.1

data/lib/self_agency/configuration.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "ruby_llm/template"
+
+module SelfAgency
+  CONFIG_MUTEX = Mutex.new
+
+  class Configuration
+    attr_accessor :provider, :model, :api_base,
+                  :request_timeout, :max_retries, :retry_interval,
+                  :template_directory, :generation_retries, :logger
+
+    def initialize
+      @provider           = :ollama
+      @model              = "qwen3-coder:30b"
+      @api_base           = "http://localhost:11434/v1"
+      @request_timeout    = 30
+      @max_retries        = 1
+      @retry_interval     = 0.5
+      @template_directory = File.join(__dir__, "prompts")
+      @generation_retries = 3
+      @logger             = nil
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      CONFIG_MUTEX.synchronize do
+        yield(configuration)
+        apply_ruby_llm_config!
+        configuration
+      end
+    end
+
+    def reset!
+      CONFIG_MUTEX.synchronize do
+        @configuration = Configuration.new
+        @configured = false
+      end
+    end
+
+    def ensure_configured!
+      raise Error, "SelfAgency.configure has not been called" unless @configured
+    end
+
+    def included(base)
+      base.extend(ClassMethods)
+      base.instance_variable_set(:@self_agency_mutex, Mutex.new)
+    end
+
+    private
+
+    def apply_ruby_llm_config!
+      cfg = configuration
+      provider_key = :"#{cfg.provider}_api_base"
+
+      RubyLLM.configure do |c|
+        c.public_send(:"#{provider_key}=", cfg.api_base) if c.respond_to?(:"#{provider_key}=")
+        c.request_timeout = cfg.request_timeout
+        c.max_retries     = cfg.max_retries
+        c.retry_interval  = cfg.retry_interval
+      end
+
+      RubyLLM::Template.configure do |c|
+        c.template_directory = cfg.template_directory
+      end
+
+      @configured = true
+    end
+  end
+end

data/lib/self_agency/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SelfAgency
+  class Error < StandardError; end
+
+  class GenerationError < Error
+    attr_reader :stage, :attempt
+
+    def initialize(message = nil, stage: nil, attempt: nil)
+      @stage   = stage
+      @attempt = attempt
+      super(message)
+    end
+  end
+
+  class ValidationError < Error
+    attr_reader :generated_code, :attempt
+
+    def initialize(message = nil, generated_code: nil, attempt: nil)
+      @generated_code = generated_code
+      @attempt        = attempt
+      super(message)
+    end
+  end
+
+  class SecurityError < Error
+    attr_reader :matched_pattern, :generated_code
+
+    def initialize(message = nil, matched_pattern: nil, generated_code: nil)
+      @matched_pattern = matched_pattern
+      @generated_code  = generated_code
+      super(message)
+    end
+  end
+end

data/lib/self_agency/generator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module SelfAgency
+  private
+
+  # Send a prompt to the configured LLM using a named template.
+  # Returns the response content string, or nil if the LLM returns empty content.
+  # Raises GenerationError wrapping the original exception on communication failure.
+  def self_agency_ask_with_template(template_name, **variables)
+    cfg  = SelfAgency.configuration
+    chat = RubyLLM.chat(model: cfg.model, provider: cfg.provider)
+    response = chat.with_template(template_name, variables).complete
+    response.content
+  rescue StandardError => e
+    raise GenerationError.new(
+      "LLM request failed (#{e.class}: #{e.message})",
+      stage: template_name.to_sym
+    )
+  end
+
+  # Pass 1: rewrite the user's casual prompt into a precise technical spec.
+  def self_agency_shape(raw_prompt, scope)
+    scope_instruction = case scope
+    when :instance  then "This will be an instance method available on all instances of the class."
+    when :singleton then "This will be a singleton method on one specific object instance only."
+    when :class     then "This will be a class method (def self.method_name)."
+    end
+
+    self_agency_ask_with_template(
+      :shape,
+      class_name:        self.class.name,
+      ivars:             instance_variables.join(", "),
+      methods:           (self.class.public_instance_methods(false) - Object.public_instance_methods).sort.join(", "),
+      scope_instruction: scope_instruction,
+      raw_prompt:        raw_prompt
+    )
+  end
+
+  # Build a Hash of introspected class context for the generate template.
+  def self_agency_generation_vars
+    {
+      class_name: self.class.name,
+      ivars:      instance_variables.join(", "),
+      methods:    (self.class.public_instance_methods(false) - Object.public_instance_methods).sort.join(", ")
+    }
+  end
+end

data/lib/self_agency/prompts/generate/system.txt.erb

@@ -0,0 +1,15 @@
+You are a Ruby code generator. You MUST respond with ONLY a Ruby method
+definition — nothing else. No explanation, no markdown fences, no comments
+outside the method, no extra text.
+
+Context for the class you are writing a method for:
+- Class name: <%= class_name %>
+- Instance variables: <%= ivars %>
+- Public methods: <%= methods %>
+
+Rules:
+- Return exactly one `def method_name ... end` block.
+- Use the EXACT method name, parameter names, and Hash key names from the specification. Do NOT rename or abbreviate any identifier.
+- Do NOT use any of these forbidden patterns: system, exec, spawn, fork, abort, exit, backticks, %x, File., IO., Kernel., Open3., Process., require, load, __send__, eval, send, public_send, method(), const_get, class_eval, module_eval, instance_eval, instance_variable_set, instance_variable_get, define_method, Binding, BasicObject, remove_method, undef_method.
+- Do NOT wrap the code in markdown fences.
+- The method must be self-contained.

data/lib/self_agency/prompts/generate/user.txt.erb

@@ -0,0 +1,13 @@
+<%= shaped_spec %>
+<% if previous_error %>
+
+Your previous attempt produced this code:
+
+<%= previous_code %>
+
+It failed with the following error:
+
+<%= previous_error %>
+
+Please fix the issue and generate corrected code.
+<% end %>

data/lib/self_agency/prompts/shape/system.txt.erb

@@ -0,0 +1,26 @@
+You are a prompt engineer specializing in Ruby code generation.
+Your job is to take a casual, natural-language request and rewrite it
+into a precise, unambiguous technical specification for a Ruby method.
+
+Rules for the rewritten prompt:
+- State the exact method name (snake_case). If the user didn't name one,
+  infer a clear name from the description.
+- State the method signature: parameter names, types, defaults.
+- State the return type and value.
+- Describe the algorithm step by step.
+- Translate vague terms into concrete Ruby operations. Examples:
+    "print in random places on the terminal" →
+      "Use ANSI escape codes (\e[row;colH) to move the cursor to
+       randomly chosen row/col positions within an 80×24 terminal grid,
+       then print the text at each position."
+    "returns a random direction" →
+      "Return one of the four cardinal direction symbols
+       [:north, :south, :east, :west] chosen with Array#sample."
+- If the request mentions visual output, specify the exact mechanism
+  (ANSI escapes, $stdout.write, puts, etc.).
+- If the request mentions randomness, specify using Ruby's rand / sample.
+- Preserve every concrete detail the user gave — method names, parameter names,
+  Hash key names, return types, thresholds, formulas, counts, and strings.
+  Do NOT rename, abbreviate, or paraphrase any identifier.
+- Do NOT generate Ruby code. Output ONLY the rewritten specification
+  as plain English paragraphs. No markdown fences, no code blocks.

data/lib/self_agency/prompts/shape/user.txt.erb

@@ -0,0 +1,10 @@
+Rewrite the following casual request into a precise Ruby method specification.
+
+Class context:
+- Class name: <%= class_name %>
+- Instance variables: <%= ivars %>
+- Public methods: <%= methods %>
+- Scope: <%= scope_instruction %>
+
+User request:
+<%= raw_prompt %>

data/lib/self_agency/sandbox.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SelfAgency
+  # Sandbox — shadows dangerous Kernel methods so generated code cannot
+  # call them.  Included in an anonymous module that wraps every generated
+  # method, placing these shadows ahead of Kernel in Ruby's MRO.
+  module Sandbox
+    private
+
+    def system(*)  = raise(::SecurityError, "system() blocked by SelfAgency sandbox")
+    def exec(*)    = raise(::SecurityError, "exec() blocked by SelfAgency sandbox")
+    def spawn(*)   = raise(::SecurityError, "spawn() blocked by SelfAgency sandbox")
+    def fork(*)    = raise(::SecurityError, "fork() blocked by SelfAgency sandbox")
+    def `(*)       = raise(::SecurityError, "backtick execution blocked by SelfAgency sandbox")
+    def open(*)    = raise(::SecurityError, "open() blocked by SelfAgency sandbox")
+  end
+end

data/lib/self_agency/saver.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module SelfAgency
+  private
+
+  # Convert a String or Symbol to a CamelCase class name.
+  #   :collector       → "Collector"
+  #   "weather_analyst" → "WeatherAnalyst"
+  #   "WeatherAnalyst"  → "WeatherAnalyst"
+  def self_agency_to_class_name(value)
+    str = value.to_s
+    return str if str.match?(/\A[A-Z]/)
+
+    str.split("_").map(&:capitalize).join
+  end
+
+  # Convert a CamelCase class name to snake_case.
+  #   "WeatherAnalyst" → "weather_analyst"
+  def self_agency_to_snake_case(class_name)
+    class_name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+  end
+
+  # Compute the require_relative path from the output file to the parent source.
+  def self_agency_relative_require(output_path, source_path)
+    output_dir = File.dirname(File.expand_path(output_path))
+    source_abs = File.expand_path(source_path)
+
+    Pathname.new(source_abs)
+      .relative_path_from(Pathname.new(output_dir))
+      .to_s
+      .sub(/\.rb\z/, "")
+  end
+
+  # Build the Ruby source string for a subclass file.
+  def self_agency_build_subclass_source(class_name, parent_class, require_path, sources, descriptions)
+    output = +"# frozen_string_literal: true\n\n"
+    output << "require_relative \"#{require_path}\"\n\n" if require_path
+    output << "class #{class_name} < #{parent_class}\n"
+
+    sources.each_with_index do |(name, code), index|
+      output << "\n" if index > 0
+
+      if (desc = descriptions[name])
+        desc.each_line { |line| output << "  # #{line.chomp}\n" }
+      end
+
+      code.each_line do |line|
+        if line.chomp.empty?
+          output << "\n"
+        else
+          output << "  #{line}"
+        end
+      end
+      output << "\n" unless output.end_with?("\n")
+    end
+
+    output << "end\n"
+    output
+  end
+end

data/lib/self_agency/validator.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module SelfAgency
+  # Static-analysis patterns that must never appear in generated code
+  DANGEROUS_PATTERNS = /
+    \b(system|exec|spawn|fork|abort|exit)\b |
+    `[^`]*`                                 |
+    %x\{                                    |
+    %x\[                                    |
+    %x\(                                    |
+    \bFile\.\b                              |
+    \bIO\.\b                                |
+    \bKernel\.\b                            |
+    \bOpen3\.\b                             |
+    \bProcess\.\b                           |
+    \brequire\b                             |
+    \bload\b                                |
+    \b__send__\b                            |
+    \beval\b                                |
+    \bsend\b                                |
+    \bpublic_send\b                         |
+    \bmethod\s*\(                           |
+    \bconst_get\b                           |
+    \bclass_eval\b                          |
+    \bmodule_eval\b                         |
+    \binstance_eval\b                       |
+    \binstance_variable_set\b               |
+    \binstance_variable_get\b               |
+    \bdefine_method\b                       |
+    \bBinding\b                             |
+    \bBasicObject\b                         |
+    \bremove_method\b                       |
+    \bundef_method\b
+  /x
+
+  private
+
+  # Strip markdown fences, <think> blocks, and leading/trailing whitespace.
+  def self_agency_sanitize(raw)
+    text = raw.to_s.strip
+    text = text.sub(/\A```\w*\n?/, "").sub(/\n?```\s*\z/, "")
+    text = text.gsub(/<think>.*?<\/think>/m, "")
+    text.strip
+  end
+
+  # Validate the sanitized code. Raises on problems.
+  def self_agency_validate!(code)
+    raise ValidationError.new("code is empty", generated_code: code) if code.empty?
+    unless code.match?(/\bdef\s+\S+.*?\bend\b/m)
+      raise ValidationError.new("missing def...end structure", generated_code: code)
+    end
+    if (match = code.match(DANGEROUS_PATTERNS))
+      raise SecurityError.new(
+        "dangerous pattern detected: #{match[0].strip}",
+        matched_pattern: match[0].strip,
+        generated_code:  code
+      )
+    end
+
+    RubyVM::InstructionSequence.compile(code)
+  rescue SyntaxError => e
+    raise ValidationError.new("syntax error: #{e.message}", generated_code: code)
+  end
+end

data/lib/self_agency/version.rb

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