self_agency 0.0.1

data/docs/guide/lifecycle-hooks.md

@@ -0,0 +1,86 @@
+# Lifecycle Hooks
+
+SelfAgency provides a lifecycle hook that fires each time a method is generated. Override it in your class to persist, log, or react to generated methods.
+
+## `on_method_generated`
+
+```ruby
+def on_method_generated(method_name, scope, code)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `method_name` | `Symbol` | Name of the generated method |
+| `scope` | `Symbol` | `:instance`, `:singleton`, or `:class` |
+| `code` | `String` | The generated source code |
+
+By default, `on_method_generated` is a no-op. Override it in your class:
+
+```ruby
+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})"
+  end
+end
+```
+
+## When It Fires
+
+The hook fires **once per method** after successful validation and installation. If `_()` generates multiple methods in a single call, the hook fires for each one:
+
+```ruby
+calc = PersistentCalculator.new
+
+calc._("an instance method named 'increment' that returns n + 1")
+# [hook] Generated :increment (scope: instance)
+
+calc._(
+  "two methods: 'min_of(a, b)' returns the smaller, " \
+  "'max_of(a, b)' returns the larger"
+)
+# [hook] Generated :min_of (scope: instance)
+# [hook] Generated :max_of (scope: instance)
+```
+
+## Common Patterns
+
+### Save to Files
+
+```ruby
+def on_method_generated(method_name, scope, code)
+  filepath = "generated/#{method_name}_#{scope}.rb"
+  File.write(filepath, code)
+end
+```
+
+### Log to a Database
+
+```ruby
+def on_method_generated(method_name, scope, code)
+  GeneratedMethod.create!(
+    name: method_name.to_s,
+    scope: scope.to_s,
+    source: code,
+    class_name: self.class.name
+  )
+end
+```
+
+### Collect for Later Inspection
+
+```ruby
+def on_method_generated(method_name, scope, code)
+  @generation_log << { method_name: method_name, scope: scope, code: code }
+end
+```
+
+This pattern is used in the [collaborative robots](../examples/collaborative-robots.md) and [autonomous robots](../examples/autonomous-robots.md) examples.

data/docs/guide/prompt-templates.md

@@ -0,0 +1,189 @@
+# Prompt Templates
+
+SelfAgency uses [ruby_llm-template](https://github.com/danielfriis/ruby_llm-template) for prompt management. The two-stage pipeline (shape and generate) each use a pair of ERB templates.
+
+## Default Template Layout
+
+```
+lib/self_agency/prompts/
+  shape/
+    system.txt.erb    # System prompt for the shape stage
+    user.txt.erb      # User prompt for the shape stage
+  generate/
+    system.txt.erb    # System prompt for the generate stage
+    user.txt.erb      # User prompt for the generate stage
+```
+
+## Shape Stage Templates
+
+The **shape** stage rewrites a casual language description into a precise Ruby method specification.
+
+**`shape/system.txt.erb`** -- Instructs the LLM to act as a prompt engineer, with rules for rewriting descriptions:
+
+- State the exact method name (snake_case)
+- State the method signature with parameter names, types, defaults
+- State the return type and value
+- Describe the algorithm step by step
+- Translate vague terms into concrete Ruby operations
+- Output only plain language, no code
+
+**`shape/user.txt.erb`** -- Provides class context and the user's request:
+
+```erb
+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 %>
+```
+
+### Available Variables (Shape)
+
+| Variable | Description |
+|----------|-------------|
+| `class_name` | Name of the including class |
+| `ivars` | Comma-separated list of instance variables |
+| `methods` | Comma-separated list of public instance methods |
+| `scope_instruction` | Human-readable scope description |
+| `raw_prompt` | The user's original description |
+
+## Generate Stage Templates
+
+The **generate** stage produces Ruby code from the shaped specification.
+
+**`generate/system.txt.erb`** -- Instructs the LLM to act as a Ruby code generator:
+
+- Return exactly one `def method_name ... end` block
+- Do not use dangerous methods (`system`, `exec`, `File`, `IO`, `eval`, etc.)
+- Do not wrap code in markdown fences
+- The method must be self-contained
+
+!!! note
+    The template instructs the LLM to return "exactly one" method definition. However, when describing multiple methods in a single `_()` call, some LLMs return multiple `def...end` blocks despite this instruction. SelfAgency handles this gracefully -- it splits the output into individual method blocks and installs each one separately.
+
+**`generate/user.txt.erb`** -- Passes the shaped specification. On retries, includes the previous error and code so the LLM can self-correct:
+
+```erb
+<%= 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 %>
+```
+
+### Available Variables (Generate)
+
+| Variable | Description |
+|----------|-------------|
+| `class_name` | Name of the including class |
+| `ivars` | Comma-separated list of instance variables |
+| `methods` | Comma-separated list of public instance methods |
+| `shaped_spec` | Output from the shape stage |
+| `previous_error` | Error message from the previous attempt (`nil` on first attempt) |
+| `previous_code` | Generated code from the previous attempt (`nil` on first attempt) |
+
+!!! warning
+    If you customize the generate templates, your `user.txt.erb` must handle the `previous_error` and `previous_code` variables (they are passed on every call). Use a conditional `<%% if previous_error %>` block to include them only during retries.
+
+## Custom Templates
+
+### Why Customize?
+
+The default prompts are tuned for general-purpose code generation, but different providers and models respond best to different prompt styles. You may want to customize templates when:
+
+- **Switching providers or models** -- A prompt that works well with Ollama's Qwen may produce poor results with OpenAI's GPT-4o or Anthropic's Claude. Some models need more explicit instructions; others perform better with fewer constraints. Smaller models may need step-by-step algorithmic guidance that a larger model would find redundant.
+- **Domain-specific generation** -- If your class operates in a specific domain (financial calculations, data science, text processing), you can add domain rules and conventions directly into the system prompt so every generated method follows them.
+- **Code style enforcement** -- You may want generated methods to follow your project's conventions: frozen string literals, specific naming patterns, guard clauses, or particular error handling styles.
+- **Controlling output format** -- Some models wrap output in markdown fences or include chain-of-thought reasoning despite instructions not to. Tailoring the prompt to your model's quirks reduces the sanitization needed.
+
+### Setup
+
+Start by copying the default prompts into your project:
+
+```bash
+cp -r $(bundle show self_agency)/lib/self_agency/prompts my_prompts
+```
+
+Then point SelfAgency at your copy:
+
+```ruby
+SelfAgency.configure do |config|
+  config.template_directory = File.expand_path("my_prompts", __dir__)
+  # ...
+end
+```
+
+Your custom directory must follow the same layout:
+
+```
+my_prompts/
+  shape/
+    system.txt.erb
+    user.txt.erb
+  generate/
+    system.txt.erb
+    user.txt.erb
+```
+
+All ERB variables listed above are available in your custom templates.
+
+### Example: Adapting the Generate Prompt for a Different Model
+
+The default `generate/system.txt.erb` is concise:
+
+```erb
+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.
+```
+
+A smaller or less instruction-following model might ignore the "no markdown fences" rule, or include conversational preamble before the code. You could adapt it with stronger guardrails:
+
+```erb
+TASK: Generate a Ruby method definition.
+
+CRITICAL FORMAT RULES:
+1. Your ENTIRE response must be a single `def ... end` block.
+2. Do NOT output any text before `def` or after `end`.
+3. Do NOT use ``` fences. Do NOT use <think> tags.
+4. Do NOT include comments, explanations, or notes.
+
+If you output anything other than a method definition, the parse will fail.
+
+Class: <%= class_name %>
+Instance variables: <%= ivars %>
+Existing methods: <%= methods %>
+
+FORBIDDEN constructs (will be rejected):
+system, exec, spawn, fork, backticks, File, IO, Kernel, Open3,
+Process, require, load, eval, send, __send__, remove_method, undef_method
+
+Write ONLY the def ... end block now.
+```
+
+This version uses imperative language, repeats the format constraint, and explicitly warns about parse failure -- techniques that help smaller models stay on track.

data/docs/guide/saving-methods.md

@@ -0,0 +1,84 @@
+# Saving Methods
+
+`_save!` writes an object's generated methods as a subclass in a Ruby source file. This lets you capture LLM-generated methods as permanent, version-controlled code.
+
+## Basic Usage
+
+```ruby
+foo = Foo.new
+foo._("an instance method to add two integers")
+foo._("an instance method to subtract two integers")
+
+foo._save!(as: :calculator)
+```
+
+This writes `calculator.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require_relative "foo"
+
+class Calculator < Foo
+  # an instance method to add two integers
+  def add(a, b)
+    a + b
+  end
+
+  # an instance method to subtract two integers
+  def subtract(a, b)
+    a - b
+  end
+end
+```
+
+## The `as:` Parameter
+
+`as:` is required. It sets the subclass name and (by default) the output filename. It accepts a String or Symbol.
+
+Snake case is automatically converted to CamelCase:
+
+```ruby
+foo._save!(as: :weather_analyst)
+# Writes weather_analyst.rb with class WeatherAnalyst < Foo
+
+foo._save!(as: "WeatherAnalyst")
+# Same result
+```
+
+## Custom File Path
+
+Override the default file path with `path:`:
+
+```ruby
+foo._save!(as: :calculator, path: "lib/calculator.rb")
+```
+
+## Require Path
+
+The generated file includes a `require_relative` pointing back to the parent class source file. The path is computed relative to the output file location.
+
+## Multiple Instances, Different Methods
+
+Each instance of a class can have different generated methods. `_save!` captures only the methods generated on that specific instance:
+
+```ruby
+collector = Robot.new(name: "Collector")
+analyst   = Robot.new(name: "Analyst")
+
+# Each robot generates different methods via _()
+collector._save!(as: collector.name)  # collector.rb with class Collector < Robot
+analyst._save!(as: analyst.name)      # analyst.rb   with class Analyst < Robot
+```
+
+## Description Comments
+
+Each method in the saved file includes the original natural language description as a comment header, so the intent behind the generated code is preserved.
+
+## Errors
+
+| Error | Condition |
+|-------|-----------|
+| `ArgumentError` | `as:` is not a String or Symbol |
+| `SelfAgency::Error` | No generated methods to save |
+| `SelfAgency::Error` | Parent class is anonymous (no name) |

data/docs/guide/scopes.md

@@ -0,0 +1,74 @@
+# Scopes
+
+SelfAgency supports three scopes for generated methods: `:instance`, `:singleton`, and `:class`. The scope is passed as the `scope:` keyword argument to `_()`.
+
+## Instance Scope (Default)
+
+Instance methods are available on **all instances** of the class. This is the default scope.
+
+```ruby
+class Greeter
+  include SelfAgency
+end
+
+alice = Greeter.new
+bob   = Greeter.new
+
+alice._("an instance method named 'hello' that returns the string 'Hello, world!'")
+
+alice.hello  #=> "Hello, world!"
+bob.hello    #=> "Hello, world!" -- available to all instances
+```
+
+Internally, SelfAgency creates an anonymous module containing the generated method and uses `prepend` to add it to the class. This means the method appears on all current and future instances.
+
+## Singleton Scope
+
+Singleton methods are available on **only one specific instance**. Other instances of the same class do not have the method.
+
+```ruby
+alice._("a method named 'secret' that returns 'Alice only'", scope: :singleton)
+
+alice.secret                    #=> "Alice only"
+bob.respond_to?(:secret)       #=> false
+```
+
+Internally, singleton-scoped methods are prepended to the instance's singleton class.
+
+## Class Scope
+
+Class methods are available on the **class itself**, not on instances.
+
+```ruby
+alice._("a class method named 'self.class_greeting' that returns 'Greetings from Greeter'", scope: :class)
+
+Greeter.class_greeting  #=> "Greetings from Greeter"
+```
+
+!!! note
+    For class methods, the LLM generates `def self.method_name`. SelfAgency strips the `self.` prefix before evaluating, since it prepends the method to the class's singleton class.
+
+## Scope Comparison
+
+| Scope | Keyword | Available On | Mechanism |
+|-------|---------|-------------|-----------|
+| Instance | `scope: :instance` | All instances of the class | `self.class.prepend(module)` |
+| Singleton | `scope: :singleton` | One specific instance | `singleton_class.prepend(module)` |
+| Class | `scope: :class` | The class itself | `self.class.singleton_class.prepend(module)` |
+
+## Combining Scopes
+
+You can mix scopes freely on the same class:
+
+```ruby
+calc = StatisticsCalculator.new([10, 20, 30])
+
+# Instance methods -- available to all instances
+calc._("an instance method named 'mean' ...")
+
+# Class method -- available on StatisticsCalculator itself
+calc._("a class method named 'self.from_range' ...", scope: :class)
+
+# Singleton method -- available only on this calc instance
+calc._("a method named 'report' ...", scope: :singleton)
+```

data/docs/guide/source-inspection.md

@@ -0,0 +1,96 @@
+# Source Inspection
+
+`_source_for` returns the source code for any method -- both LLM-generated and file-defined methods.
+
+## Instance-Level Inspection
+
+Call `_source_for` on an instance to retrieve source code:
+
+```ruby
+class MathHelper
+  include SelfAgency
+
+  # Multiplies a number by two.
+  def double(n)
+    n * 2
+  end
+end
+
+helper = MathHelper.new
+helper._("an instance method named 'square' that accepts an integer n and returns n * n")
+```
+
+For LLM-generated methods, `_source_for` returns the code with the original description as a comment header:
+
+```ruby
+puts helper._source_for(:square)
+# >> # an instance method named 'square' that accepts an integer n and returns n * n
+# >> def square(n)
+# >>   n * n
+# >> end
+```
+
+## Class-Level Inspection
+
+`_source_for` is also available as a class method:
+
+```ruby
+puts MathHelper._source_for(:square)
+# >> # an instance method named 'square' that accepts an integer n and returns n * n
+# >> def square(n)
+# >>   n * n
+# >> end
+```
+
+Both instance and class level lookups return the same source for LLM-generated methods.
+
+## File-Defined Methods
+
+For methods defined in source files (not generated by the LLM), `_source_for` falls back to the `method_source` gem. It includes any comments directly above the method definition:
+
+```ruby
+puts helper._source_for(:double)
+# >> # Multiplies a number by two.
+# >> def double(n)
+# >>   n * 2
+# >> end
+```
+
+## Unknown Methods
+
+If a method doesn't exist or its source is unavailable, `_source_for` returns `nil`:
+
+```ruby
+helper._source_for(:nonexistent)  #=> nil
+```
+
+## Version History
+
+When a method is regenerated (e.g., with a refined description), SelfAgency tracks each version. Use `_source_versions_for` at the class level to retrieve the history:
+
+```ruby
+helper._("an instance method named 'square' that accepts n and returns n * n")
+helper._("an instance method named 'square' that accepts n, raises ArgumentError if n < 0, and returns n * n")
+
+versions = MathHelper._source_versions_for(:square)
+versions.size  #=> 2
+
+versions.each do |v|
+  puts "#{v[:at]} — #{v[:description]}"
+  puts v[:code]
+  puts
+end
+```
+
+Each version entry is a Hash with keys `:code`, `:description`, `:instance_id`, and `:at`.
+
+Returns an empty array if no versions exist for the method.
+
+## How It Works
+
+`_source_for` checks two sources in order:
+
+1. **LLM-generated source** -- Stored in an internal hash when `_()` creates the method
+2. **File source** -- Falls back to `method_source` gem for methods defined in `.rb` files
+
+If both lookups fail (method doesn't exist or source file can't be located), `nil` is returned.

data/docs/index.md

@@ -0,0 +1,77 @@
+<div align="center">
+  <h1>SelfAgency</h1>
+  Describe what you want in plain language, get working methods back.<br/>
+  SelfAgency is a mixin module that gives any Ruby class the ability to<br/>
+  generate and install methods at runtime via an LLM.<br/>
+  <br/>
+  <img src="assets/images/self_agency.gif" alt="SelfAgency Demo" width="100%">
+  <h2>Key Features</h2>
+</div>
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <ul>
+        <li><strong>Natural language to Ruby methods</strong> — describe what you want, get working code</li>
+        <li><strong>Multiple methods at once</strong> — generate related methods in a single call</li>
+        <li><strong>Three scopes</strong> — instance, singleton, and class methods</li>
+        <li><strong>Two-stage LLM pipeline</strong> — shape the prompt, then generate code</li>
+      </ul>
+    </td>
+    <td width="50%" valign="top">
+      <ul>
+        <li><strong>Security by default</strong> — 26 static patterns + runtime sandbox</li>
+        <li><strong>Automatic retries</strong> — self-corrects on validation failure</li>
+        <li><strong>Source inspection &amp; versioning</strong> — view code and track history</li>
+        <li><strong>Provider agnostic</strong> — any LLM via <a href="https://github.com/crmne/ruby_llm">ruby_llm</a></li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+> [!CAUTION]
+> This is an experiment. It may not be fit for any specific purpose.  Its micro-prompting.  Instead of asking Claude Code, CodeX or Gemini to create an entire application, you can use SelfAgency to generate individual methods.  So far the experiments are showing good success with methods that perform math stuff on its input.
+
+
+## Quick Example
+
+```ruby
+require "self_agency"
+
+SelfAgency.configure do |config|
+  config.provider = :ollama
+  config.model    = "qwen3-coder:30b"
+  config.api_base = "http://localhost:11434/v1"
+end
+
+class Calculator
+  include SelfAgency
+end
+
+calc = Calculator.new
+calc._("an instance method to add two integers, return the result")
+#=> [:add]
+
+calc.add(3, 7)
+#=> 10
+```
+
+## How It Works
+
+Your casual description is first "shaped" into a precise Ruby method specification, then passed through a multi-stage pipeline:
+
+1. **Shape** -- Rewrites your casual description into a precise Ruby method specification
+2. **Generate** -- Produces `def...end` block(s) from the shaped spec
+3. **Sanitize** -- Strips markdown fences and `<think>` blocks
+4. **Validate** -- Checks for empty code, missing `def...end`, syntax errors, and dangerous patterns
+5. **Retry** -- On validation/security failure, feeds the error back to the LLM for self-correction (up to `generation_retries` attempts)
+6. **Sandbox Eval** -- Evaluates code inside a cached sandbox module that shadows dangerous Kernel methods
+
+## Requirements
+
+- Ruby >= 3.2.0
+- An LLM provider (Ollama by default, or any provider supported by ruby_llm)
+
+## Getting Started
+
+Head to the [Installation](getting-started/installation.md) guide to add SelfAgency to your project, then follow the [Quick Start](getting-started/quick-start.md) for a complete walkthrough. For a broader perspective on where SelfAgency fits in your development process, see [How to Use SelfAgency](guide/how-to-use.md).

data/examples/01_basic_usage.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 01_basic_usage.rb — Single method generation
+#
+# Demonstrates:
+#   - include SelfAgency
+#   - _() to generate a method from a description
+#   - Calling the generated method
+#
+# Requires a running Ollama instance with the configured model.
+
+require_relative "lib/setup"
+
+class Calculator
+  include SelfAgency
+end
+
+calc = Calculator.new
+
+puts "Generating a method to add two integers..."
+method_names = calc._("an instance method named 'add' that accepts two integer parameters a and b, and returns their sum")
+
+puts "Generated methods: #{method_names.inspect}"
+puts "calc.add(3, 7) = #{calc.add(3, 7)}"
+puts "calc.add(-1, 1) = #{calc.add(-1, 1)}"
+puts "calc.add(100, 200) = #{calc.add(100, 200)}"

data/examples/02_multiple_methods.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 02_multiple_methods.rb — Multiple methods from one call
+#
+# Demonstrates:
+#   - Generating several related methods in a single _() call
+#   - _() returns an Array of Symbols
+#   - Calling each generated method
+#
+# Requires a running Ollama instance with the configured model.
+
+require_relative "lib/setup"
+
+class Arithmetic
+  include SelfAgency
+end
+
+arith = Arithmetic.new
+
+puts "Generating four arithmetic methods in a single call..."
+method_names = arith._(
+  "create four instance methods: " \
+  "'add(a, b)' returns a + b, " \
+  "'subtract(a, b)' returns a - b, " \
+  "'multiply(a, b)' returns a * b, " \
+  "'divide(a, b)' returns a.to_f / b (raises ZeroDivisionError if b is zero)"
+)
+
+puts "_() returned: #{method_names.inspect}"
+puts "Type: #{method_names.class}"
+puts "Count: #{method_names.length} methods generated"
+puts
+
+method_names.each do |name|
+  puts "  #{name} is now defined"
+end
+
+puts
+puts "arith.add(10, 3)      = #{arith.add(10, 3)}"
+puts "arith.subtract(10, 3) = #{arith.subtract(10, 3)}"
+puts "arith.multiply(10, 3) = #{arith.multiply(10, 3)}"
+puts "arith.divide(10, 3)   = #{arith.divide(10, 3)}"