self_agency 0.0.1

data/examples/03_scopes.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 03_scopes.rb — Instance, singleton, and class scopes
+#
+# Demonstrates:
+#   - scope: :instance  — available to all instances
+#   - scope: :singleton — available to only one instance
+#   - scope: :class     — available on the class itself
+#   - Singleton methods are NOT available on other instances
+#
+# Requires a running Ollama instance with the configured model.
+
+require_relative "lib/setup"
+
+class Greeter
+  include SelfAgency
+end
+
+alice = Greeter.new
+bob   = Greeter.new
+
+# --- Instance scope (default) ---
+puts "=== Instance scope ==="
+alice._("an instance method named 'hello' that returns the string 'Hello, world!'")
+puts "alice.hello = #{alice.hello}"
+puts "bob.hello   = #{bob.hello}  (available to all instances)"
+puts
+
+# --- Singleton scope ---
+puts "=== Singleton scope ==="
+alice._("an instance method named 'secret' that returns the string 'Alice only'", scope: :singleton)
+puts "alice.secret = #{alice.secret}"
+puts "bob.respond_to?(:secret) = #{bob.respond_to?(:secret)}  (NOT available on other instances)"
+puts
+
+# --- Class scope ---
+puts "=== Class scope ==="
+alice._("a class method named 'self.class_greeting' that returns 'Greetings from Greeter'", scope: :class)
+puts "Greeter.class_greeting = #{Greeter.class_greeting}"

data/examples/04_source_inspection.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 04_source_inspection.rb — Viewing generated source code
+#
+# Demonstrates:
+#   - _source_for on an instance (instance-level lookup)
+#   - _source_for on the class (class-level lookup via ClassMethods)
+#   - Original description appears as a comment header
+#   - Fallback to method_source for file-defined methods
+#
+# Requires a running Ollama instance with the configured model.
+
+require_relative "lib/setup"
+
+class MathHelper
+  include SelfAgency
+
+  # Multiplies a number by two.
+  def double(n)
+    n * 2
+  end
+end
+
+helper = MathHelper.new
+
+puts "=== Generate a method ==="
+description = "an instance method named 'square' that accepts an integer n and returns n * n"
+helper._(description)
+puts "helper.square(5) = #{helper.square(5)}"
+puts
+
+puts "=== Instance-level _source_for ==="
+puts helper._source_for(:square)
+puts
+
+puts "=== Class-level _source_for ==="
+puts MathHelper._source_for(:square)
+puts
+
+puts "=== Fallback to method_source for file-defined methods ==="
+puts helper._source_for(:double)
+puts
+
+puts "=== _source_for returns nil for unknown methods ==="
+puts helper._source_for(:nonexistent).inspect

data/examples/05_lifecycle_hook.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 05_lifecycle_hook.rb — Persisting generated methods
+#
+# Demonstrates:
+#   - Overriding on_method_generated(method_name, scope, code)
+#   - Hook fires for each method generated
+#   - Persistence pattern: saving generated code to files
+#
+# Requires a running Ollama instance with the configured model.
+
+require_relative "lib/setup"
+
+class PersistentCalculator
+  include SelfAgency
+
+  attr_reader :generation_log
+
+  def initialize
+    @generation_log = []
+  end
+
+  def on_method_generated(method_name, scope, code)
+    @generation_log << { method_name: method_name, scope: scope, code: code }
+    puts "  [hook] Generated :#{method_name} (scope: #{scope})"
+    puts "  [hook] Code preview: #{code.lines.first.chomp}..."
+  end
+end
+
+calc = PersistentCalculator.new
+
+puts "=== Generating methods (hook will fire for each) ==="
+puts
+
+calc._("an instance method named 'increment' that accepts an integer n and returns n + 1")
+puts
+
+calc._(
+  "two instance methods: " \
+  "'min_of(a, b)' returns the smaller of a and b, " \
+  "'max_of(a, b)' returns the larger of a and b"
+)
+puts
+
+puts "=== Generation log ==="
+calc.generation_log.each_with_index do |entry, i|
+  puts "#{i + 1}. :#{entry[:method_name]} (#{entry[:scope]})"
+end
+
+puts
+puts "=== Using the generated methods ==="
+puts "calc.increment(41) = #{calc.increment(41)}"
+puts "calc.min_of(3, 7)  = #{calc.min_of(3, 7)}"
+puts "calc.max_of(3, 7)  = #{calc.max_of(3, 7)}"

data/examples/06_configuration.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 06_configuration.rb — Configuration options
+#
+# Demonstrates:
+#   - All configurable options with their defaults
+#   - Changing provider, model, timeouts, retries
+#   - SelfAgency.reset! and SelfAgency.ensure_configured!
+#   - Custom template_directory configuration
+#
+# This example does NOT require a running Ollama instance for
+# the configuration inspection parts. Only the final generation
+# call requires a live LLM.
+
+require_relative "../lib/self_agency"
+
+puts "=== Default configuration (before configure) ==="
+SelfAgency.reset!
+cfg = SelfAgency.configuration
+puts <<~DEFAULTS
+  provider:           #{cfg.provider.inspect}
+  model:              #{cfg.model.inspect}
+  api_base:           #{cfg.api_base.inspect}
+  request_timeout:    #{cfg.request_timeout}
+  max_retries:        #{cfg.max_retries}
+  retry_interval:     #{cfg.retry_interval}
+  template_directory: #{cfg.template_directory}
+DEFAULTS
+
+puts "=== ensure_configured! before configure ==="
+begin
+  SelfAgency.ensure_configured!
+rescue SelfAgency::Error => e
+  puts "Caught expected error: #{e.message}"
+end
+puts
+
+puts "=== Configuring with custom values ==="
+SelfAgency.configure do |config|
+  config.provider        = :ollama
+  config.model           = "qwen3-coder:30b"
+  config.api_base        = "http://localhost:11434/v1"
+  config.request_timeout = 60
+  config.max_retries     = 3
+  config.retry_interval  = 1.0
+end
+
+cfg = SelfAgency.configuration
+puts <<~CUSTOM
+  provider:           #{cfg.provider.inspect}
+  model:              #{cfg.model.inspect}
+  api_base:           #{cfg.api_base.inspect}
+  request_timeout:    #{cfg.request_timeout}
+  max_retries:        #{cfg.max_retries}
+  retry_interval:     #{cfg.retry_interval}
+  template_directory: #{cfg.template_directory}
+CUSTOM
+
+puts "=== ensure_configured! after configure ==="
+SelfAgency.ensure_configured!
+puts "No error — configuration is active."
+puts
+
+puts "=== reset! restores defaults ==="
+SelfAgency.reset!
+cfg = SelfAgency.configuration
+puts "provider after reset: #{cfg.provider.inspect}"
+puts "model after reset:    #{cfg.model.inspect}"
+puts
+
+begin
+  SelfAgency.ensure_configured!
+rescue SelfAgency::Error => e
+  puts "ensure_configured! after reset: #{e.message}"
+end
+puts
+
+puts "=== Custom template directory ==="
+SelfAgency.configure do |config|
+  config.provider           = :ollama
+  config.model              = "qwen3-coder:30b"
+  config.api_base           = "http://localhost:11434/v1"
+  config.template_directory = "/tmp/my_custom_prompts"
+end
+puts "template_directory: #{SelfAgency.configuration.template_directory}"
+puts
+
+# Restore standard config for any follow-up usage
+SelfAgency.reset!
+SelfAgency.configure do |config|
+  config.provider = :ollama
+  config.model    = "qwen3-coder:30b"
+  config.api_base = "http://localhost:11434/v1"
+end
+puts "=== Configuration restored for live usage ==="
+puts "Ready to generate methods (requires running Ollama)."

data/examples/07_error_handling.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 07_error_handling.rb — Error classes and rescue patterns
+#
+# Demonstrates:
+#   - The SelfAgency error hierarchy
+#   - Rescuing GenerationError, ValidationError, SecurityError
+#   - Calling _() before configure raises SelfAgency::Error
+#   - Defensive usage patterns
+#
+# This example does NOT require a running Ollama instance.
+
+require_relative "../lib/self_agency"
+
+puts "=== Error hierarchy ==="
+puts <<~HIERARCHY
+  SelfAgency::Error          < StandardError
+  SelfAgency::GenerationError < SelfAgency::Error
+  SelfAgency::ValidationError < SelfAgency::Error
+  SelfAgency::SecurityError   < SelfAgency::Error
+HIERARCHY
+
+puts "Verification:"
+puts "  GenerationError < Error: #{SelfAgency::GenerationError < SelfAgency::Error}"
+puts "  ValidationError < Error: #{SelfAgency::ValidationError < SelfAgency::Error}"
+puts "  SecurityError   < Error: #{SelfAgency::SecurityError < SelfAgency::Error}"
+puts "  Error < StandardError:   #{SelfAgency::Error < StandardError}"
+puts
+
+# --- Calling _() before configure ---
+puts "=== Calling _() before configure ==="
+SelfAgency.reset!
+
+class Widget
+  include SelfAgency
+end
+
+begin
+  Widget.new._("a method")
+rescue SelfAgency::Error => e
+  puts "Caught SelfAgency::Error: #{e.message}"
+end
+puts
+
+# --- Validation errors via private helpers ---
+puts "=== ValidationError examples ==="
+SelfAgency.configure do |config|
+  config.provider = :ollama
+  config.model    = "qwen3-coder:30b"
+  config.api_base = "http://localhost:11434/v1"
+end
+
+widget = Widget.new
+
+# Empty code
+begin
+  widget.send(:self_agency_validate!, "")
+rescue SelfAgency::ValidationError => e
+  puts "Empty code:    #{e.class} — #{e.message}"
+end
+
+# Missing def...end
+begin
+  widget.send(:self_agency_validate!, "puts 'hello'")
+rescue SelfAgency::ValidationError => e
+  puts "No def...end:  #{e.class} — #{e.message}"
+end
+
+# Syntax error
+begin
+  widget.send(:self_agency_validate!, "def broken\n  if true\nend")
+rescue SelfAgency::ValidationError => e
+  puts "Syntax error:  #{e.class} — #{e.message}"
+end
+puts
+
+# --- Security errors ---
+puts "=== SecurityError examples ==="
+
+dangerous_samples = {
+  "system call" => "def hack\n  system('ls')\nend",
+  "File access" => "def hack\n  File.read('/etc/passwd')\nend",
+  "eval usage"  => "def hack\n  eval('1+1')\nend",
+  "require"     => "def hack\n  require 'socket'\nend",
+}
+
+dangerous_samples.each do |label, code|
+  begin
+    widget.send(:self_agency_validate!, code)
+  rescue SelfAgency::SecurityError => e
+    puts "#{label.ljust(14)}: #{e.class} — #{e.message}"
+  end
+end
+puts
+
+# --- Catching all SelfAgency errors with a single rescue ---
+puts "=== Catching all errors with rescue SelfAgency::Error ==="
+begin
+  raise SelfAgency::SecurityError, "example security violation"
+rescue SelfAgency::Error => e
+  puts "Caught via base class: #{e.class} — #{e.message}"
+end

data/examples/08_class_context.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 08_class_context.rb — Instance variable and method awareness
+#
+# Demonstrates:
+#   - The LLM receives class context (class name, ivars, public methods)
+#   - Generated methods can reference existing instance variables
+#   - Class introspection drives smarter code generation
+#
+# Requires a running Ollama instance with the configured model.
+
+require_relative "lib/setup"
+
+class BankAccount
+  include SelfAgency
+
+  attr_reader :owner, :balance
+
+  def initialize(owner, balance)
+    @owner   = owner
+    @balance = balance
+  end
+
+  def deposit(amount)
+    @balance += amount
+  end
+end
+
+account = BankAccount.new("Alice", 1000)
+
+# Show what the LLM will see as context
+vars = account.send(:self_agency_generation_vars)
+puts "=== Class context sent to LLM ==="
+puts "  class_name: #{vars[:class_name]}"
+puts "  ivars:      #{vars[:ivars]}"
+puts "  methods:    #{vars[:methods]}"
+puts
+
+puts "=== Generating a method that uses existing instance variables ==="
+account._(
+  "an instance method named 'summary' that returns a string like " \
+  "'Account for <owner>: $<balance>' using the @owner and @balance instance variables"
+)
+
+puts account.summary
+puts
+
+puts "=== Generating a method that complements existing methods ==="
+account._(
+  "an instance method named 'withdraw' that accepts an amount, " \
+  "raises a RuntimeError with 'Insufficient funds' if amount > @balance, " \
+  "otherwise decreases @balance by amount and returns the new balance"
+)
+
+puts "Balance before withdraw: $#{account.balance}"
+puts "Withdrawing $200..."
+puts "Balance after withdraw:  $#{account.withdraw(200)}"
+
+begin
+  account.withdraw(999_999)
+rescue RuntimeError => e
+  puts "Caught expected error: #{e.message}"
+end

data/examples/09_method_override.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 09_method_override.rb — Overriding existing methods
+#
+# Demonstrates:
+#   - Defining a class with an existing method
+#   - Generating a method with the same name overrides the original
+#   - Prepend-based MRO means the generated method takes priority
+#   - _source_for returns the new (generated) source
+#
+# Requires a running Ollama instance with the configured model.
+
+require_relative "lib/setup"
+
+class Formatter
+  include SelfAgency
+
+  def greet(name)
+    "Hello, #{name}"
+  end
+end
+
+fmt = Formatter.new
+
+puts "=== Before override ==="
+puts "fmt.greet('World') = #{fmt.greet('World')}"
+puts
+puts "Source (from file):"
+puts fmt._source_for(:greet)
+puts
+
+puts "=== Generating a replacement method with the same name ==="
+fmt._(
+  "an instance method named 'greet' that accepts a name parameter " \
+  "and returns the string 'Greetings, <name>! Welcome aboard.' " \
+  "(this should override the existing greet method)"
+)
+
+puts
+puts "=== After override ==="
+puts "fmt.greet('World') = #{fmt.greet('World')}"
+puts
+puts "Source (now LLM-generated):"
+puts fmt._source_for(:greet)
+puts
+
+puts "=== MRO shows prepended module ==="
+puts "Formatter ancestors:"
+Formatter.ancestors.first(5).each_with_index do |ancestor, i|
+  puts "  #{i}. #{ancestor}"
+end

data/examples/10_full_workflow.rb

@@ -0,0 +1,118 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 10_full_workflow.rb — Complete real-world workflow
+#
+# Demonstrates:
+#   - Building a domain class with multiple generated methods
+#   - Using different scopes (instance, singleton, class)
+#   - Lifecycle hook to save generated code to files
+#   - Source inspection for all generated methods
+#   - End-to-end usage combining all features
+#
+# Requires a running Ollama instance with the configured model.
+
+require "fileutils"
+require_relative "lib/setup"
+
+# Output directory for persisted generated code
+GENERATED_DIR = File.join(__dir__, "generated")
+FileUtils.mkdir_p(GENERATED_DIR)
+
+class StatisticsCalculator
+  include SelfAgency
+
+  attr_reader :data
+
+  def initialize(data = [])
+    @data = data.dup
+  end
+
+  def on_method_generated(method_name, scope, code)
+    filename = "#{method_name}_#{scope}.rb"
+    filepath = File.join(GENERATED_DIR, filename)
+    File.write(filepath, code)
+    puts "  [saved] #{filepath}"
+  end
+end
+
+puts "=== Building a StatisticsCalculator ==="
+calc = StatisticsCalculator.new([10, 20, 30, 40, 50, 60, 70, 80, 90, 100])
+puts "Data: #{calc.data.inspect}"
+puts
+
+# --- Instance methods ---
+puts "--- Generating instance methods ---"
+
+calc._(
+  "an instance method named 'mean' that calculates and returns the " \
+  "arithmetic mean of the @data array as a Float"
+)
+
+calc._(
+  "an instance method named 'median' that returns the median value " \
+  "of the @data array (sort the array, return the middle element for " \
+  "odd length, or average of two middle elements for even length) as a Float"
+)
+
+calc._(
+  "an instance method named 'standard_deviation' that calculates and " \
+  "returns the population standard deviation of @data as a Float " \
+  "(square root of the mean of squared differences from the mean)"
+)
+puts
+
+# --- Class method ---
+puts "--- Generating a class method ---"
+calc._(
+  "a class method named 'self.from_range' that accepts two integers " \
+  "(low, high) and returns a new StatisticsCalculator instance " \
+  "initialized with (low..high).to_a",
+  scope: :class
+)
+puts
+
+# --- Singleton method ---
+puts "--- Generating a singleton method ---"
+calc._(
+  "an instance method named 'report' that returns a multi-line string " \
+  "with the data count (data.length), mean (call self.mean), " \
+  "median (call self.median), and standard_deviation (call self.standard_deviation)",
+  scope: :singleton
+)
+puts
+
+# --- Use the generated methods ---
+puts "=== Using generated methods ==="
+puts "Mean:               #{calc.mean}"
+puts "Median:             #{calc.median}"
+puts "Standard deviation: #{calc.standard_deviation}"
+puts
+
+puts "=== Class method ==="
+range_calc = StatisticsCalculator.from_range(1, 5)
+puts "StatisticsCalculator.from_range(1, 5).data = #{range_calc.data.inspect}"
+puts "Mean of 1..5: #{range_calc.mean}"
+puts
+
+puts "=== Singleton report (only on this instance) ==="
+puts calc.report
+puts
+
+other = StatisticsCalculator.new([1, 2, 3])
+puts "other.respond_to?(:report) = #{other.respond_to?(:report)}  (singleton — not available)"
+puts
+
+# --- Inspect source ---
+puts "=== Source inspection ==="
+[:mean, :median, :standard_deviation].each do |name|
+  puts "--- #{name} ---"
+  puts calc._source_for(name)
+  puts
+end
+
+# --- List saved files ---
+puts "=== Saved generated code ==="
+Dir.glob(File.join(GENERATED_DIR, "*.rb")).sort.each do |path|
+  puts "  #{path}"
+end

data/examples/11_collaborative_robots/atlas.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "robot"
+
+class Atlas < Robot
+  # Method named 'generate_weather_data' that takes no parameters. It must return an Array of 24 Hashes (one per hour, index 0..23). Each Hash has these keys (all Symbols): :hour => the integer hour (0..23), :temperature => a Float computed as 20.0 + 8.0 * Math.sin((hour - 6) * Math::PI / 12.0), :humidity => a Float computed as 60.0 + 20.0 * Math.cos((hour - 14) * Math::PI / 12.0), :wind_speed => a Float computed as 10.0 + 5.0 * Math.sin((hour * 7) * Math::PI / 24.0). Do NOT use random numbers. Use only the deterministic formulas above.
+  def generate_weather_data
+    weather_data = []
+    (0..23).each do |hour|
+      temperature = 20.0 + 8.0 * Math.sin(((hour - 6) * Math::PI) / 12.0)
+      humidity = 60.0 + 20.0 * Math.cos(((hour - 14) * Math::PI) / 12.0)
+      wind_speed = 10.0 + 5.0 * Math.sin(((hour * 7) * Math::PI) / 24.0)
+      weather_data << {
+        hour: hour,
+        temperature: temperature,
+        humidity: humidity,
+        wind_speed: wind_speed
+      }
+    end
+    weather_data
+  end
+
+  # Method named 'summarize_raw_data' that takes one parameter (data), an Array of Hashes as described above. It returns a Hash with: :readings_count => data.size, :raw_data => data, :source => "Atlas"
+  def summarize_raw_data(data)
+    {
+      readings_count: data.size,
+      raw_data: data,
+      source: "Atlas"
+    }
+  end
+end

data/examples/11_collaborative_robots/echo.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "robot"
+
+class Echo < Robot
+  # Return a formatted multi-line String report like: "=== Weather Report ===\n" + "Source: #{data[:source]} | Readings: #{data[:readings]}\n" + "Temperature: #{data[:avg_temp]}°  (min: #{data[:min_temp]}°, max: #{data[:max_temp]}°) [#{data[:temperature_class]}]\n" + "Humidity:    #{data[:avg_humidity]}% [#{data[:humidity_class]}]\n" + "Wind:        #{data[:avg_wind]} km/h [#{data[:wind_class]}]\n" + "======================". Use string interpolation. Return the String, do not print it.
+  def weather_report
+    data = {
+      source: "Weather Station 42",
+      readings: "24 hr",
+      avg_temp: 22.5,
+      min_temp: 18.2,
+      max_temp: 28.7,
+      temperature_class: "Mild",
+      avg_humidity: 65,
+      humidity_class: "Moderate",
+      avg_wind: 12.3,
+      wind_class: "Light Breeze"
+    }
+
+    report = "=== Weather Report ===\n"
+    report += "Source: #{data[:source]} | Readings: #{data[:readings]}\n"
+    report += "Temperature: #{data[:avg_temp]}°  (min: #{data[:min_temp]}°, max: #{data[:max_temp]}°) [#{data[:temperature_class]}]\n"
+    report += "Humidity:    #{data[:avg_humidity]}% [#{data[:humidity_class]}]\n"
+    report += "Wind:        #{data[:avg_wind]} km/h [#{data[:wind_class]}]\n"
+    report += "======================"
+
+    report
+  end
+end