self_agency 0.0.1

data/docs/examples/full-workflow.md

@@ -0,0 +1,100 @@
+# Example 10: Full Workflow
+
+A complete real-world workflow that combines all SelfAgency features: multiple scopes, lifecycle hooks, source inspection, and file persistence.
+
+**Source:** `examples/10_full_workflow.rb`
+
+## Overview
+
+Builds a `StatisticsCalculator` class that:
+
+1. Generates instance methods (`mean`, `median`, `standard_deviation`)
+2. Generates a class method (`self.from_range`)
+3. Generates a singleton method (`report`)
+4. Persists all generated code to files via `on_method_generated`
+5. Inspects source for all generated methods
+
+## The Class
+
+```ruby
+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
+```
+
+## What It Generates
+
+### Instance Methods
+
+```ruby
+calc = StatisticsCalculator.new([10, 20, 30, 40, 50, 60, 70, 80, 90, 100])
+
+calc._("an instance method named 'mean' that calculates the arithmetic mean of @data as a Float")
+calc._("an instance method named 'median' that returns the median value of @data as a Float")
+calc._("an instance method named 'standard_deviation' that returns the population standard deviation of @data as a Float")
+```
+
+### Class Method
+
+```ruby
+calc._(
+  "a class method named 'self.from_range' that accepts (low, high) " \
+  "and returns a new StatisticsCalculator initialized with (low..high).to_a",
+  scope: :class
+)
+
+range_calc = StatisticsCalculator.from_range(1, 5)
+range_calc.data  #=> [1, 2, 3, 4, 5]
+```
+
+### Singleton Method
+
+```ruby
+calc._(
+  "a method named 'report' that returns a multi-line summary " \
+  "of count, mean, median, and standard_deviation",
+  scope: :singleton
+)
+
+puts calc.report
+# Only available on this specific calc instance
+other = StatisticsCalculator.new([1, 2, 3])
+other.respond_to?(:report)  #=> false
+```
+
+## Generated Files
+
+The lifecycle hook saves each method to the `examples/generated/` directory:
+
+```
+examples/generated/
+  mean_instance.rb
+  median_instance.rb
+  standard_deviation_instance.rb
+  from_range_class.rb
+  report_singleton.rb
+```
+
+## Source Inspection
+
+After generation, the source for each method can be retrieved:
+
+```ruby
+[:mean, :median, :standard_deviation].each do |name|
+  puts "--- #{name} ---"
+  puts calc._source_for(name)
+end
+```

data/docs/examples/index.md

@@ -0,0 +1,36 @@
+# Examples
+
+SelfAgency ships with 12 examples that progressively demonstrate its features. All examples live in the `examples/` directory.
+
+## Running Examples
+
+Most examples require a running LLM. The default configuration targets Ollama:
+
+```bash
+# Start Ollama
+ollama serve
+
+# Run an example
+bundle exec ruby examples/01_basic_usage.rb
+```
+
+Examples 06 and 07 run offline (no LLM required) as they only exercise configuration and error handling.
+
+## Example Index
+
+| # | Name | Features | LLM Required |
+|---|------|----------|:---:|
+| 01 | [Basic Usage](basic-examples.md#01-basic-usage) | `_()`, single method generation | Yes |
+| 02 | [Multiple Methods](basic-examples.md#02-multiple-methods) | Multiple methods from one call | Yes |
+| 03 | [Scopes](basic-examples.md#03-scopes) | Instance, singleton, class scopes | Yes |
+| 04 | [Source Inspection](basic-examples.md#04-source-inspection) | `_source_for`, file fallback | Yes |
+| 05 | [Lifecycle Hook](basic-examples.md#05-lifecycle-hook) | `on_method_generated` | Yes |
+| 06 | [Configuration](basic-examples.md#06-configuration) | All config options, `reset!`, `ensure_configured!` | No |
+| 07 | [Error Handling](basic-examples.md#07-error-handling) | Error hierarchy, rescue patterns | No |
+| 08 | [Class Context](basic-examples.md#08-class-context) | Instance variables, method awareness | Yes |
+| 09 | [Method Override](basic-examples.md#09-method-override) | Replacing existing methods | Yes |
+| 10 | [Full Workflow](full-workflow.md) | Complete real-world workflow | Yes |
+| 11 | [Collaborative Robots](collaborative-robots.md) | Multi-robot pipeline, message bus | Yes |
+| 12 | [Autonomous Robots](autonomous-robots.md) | Three-layer LLM, self-repair | Yes |
+
+Examples 01--09 are covered in [Basic Examples](basic-examples.md). Examples 10--12 each have their own deep-dive page.

data/docs/getting-started/installation.md

@@ -0,0 +1,71 @@
+# Installation
+
+## Requirements
+
+- Ruby >= 3.2.0
+- An LLM provider (Ollama recommended for local development)
+
+## Add to Your Project
+
+Add SelfAgency to your Gemfile:
+
+```ruby
+gem "self_agency"
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install self_agency
+```
+
+## Dependencies
+
+SelfAgency depends on:
+
+| Gem | Purpose |
+|-----|---------|
+| `ruby_llm` | LLM provider communication |
+| `ruby_llm-template` | ERB prompt template management |
+| `method_source` | Source code retrieval for file-defined methods |
+
+These are installed automatically when you install the gem.
+
+## LLM Provider Setup
+
+SelfAgency uses [ruby_llm](https://github.com/crmne/ruby_llm) under the hood, which supports multiple providers. The default configuration targets a local Ollama instance.
+
+### Ollama (Default)
+
+Install Ollama and pull a model:
+
+```bash
+# Install Ollama (macOS)
+brew install ollama
+
+# Start the server
+ollama serve
+
+# Pull a model
+ollama pull qwen3-coder:30b
+```
+
+### Other Providers
+
+Any provider supported by ruby_llm works. Set the `provider`, `model`, and `api_base` in your configuration:
+
+```ruby
+SelfAgency.configure do |config|
+  config.provider = :openai
+  config.model    = "gpt-4o"
+  config.api_base = "https://api.openai.com/v1"
+end
+```
+
+See [Configuration](../guide/configuration.md) for all options.

data/docs/getting-started/quick-start.md

@@ -0,0 +1,94 @@
+# Quick Start
+
+This guide walks through a complete example from configuration to using generated methods.
+
+## 1. Configure SelfAgency
+
+Before generating any methods, call `SelfAgency.configure`:
+
+```ruby
+require "self_agency"
+
+SelfAgency.configure do |config|
+  config.provider = :ollama
+  config.model    = "qwen3-coder:30b"
+  config.api_base = "http://localhost:11434/v1"
+end
+```
+
+Configuration is mandatory. Calling `_()` before `configure` raises `SelfAgency::Error`.
+
+## 2. Include the Module
+
+Add `include SelfAgency` to any class:
+
+```ruby
+class Calculator
+  include SelfAgency
+end
+
+calc = Calculator.new
+```
+
+## 3. Generate a Method
+
+Call `_()` with a natural language description:
+
+```ruby
+names = calc._("an instance method named 'add' that accepts two integer parameters a and b, and returns their sum")
+#=> [:add]
+```
+
+`_()` always returns an Array of Symbol method names.
+
+## 4. Use the Method
+
+The generated method is available immediately:
+
+```ruby
+calc.add(3, 7)   #=> 10
+calc.add(-1, 1)  #=> 0
+```
+
+Instance methods (the default scope) are available on all instances of the class:
+
+```ruby
+other = Calculator.new
+other.add(100, 200)  #=> 300
+```
+
+## 5. View the Source
+
+Inspect what the LLM generated:
+
+```ruby
+puts calc._source_for(:add)
+# >> # an instance method named 'add' that accepts two integer
+# >> # parameters a and b, and returns their sum
+# >> def add(a, b)
+# >>   a + b
+# >> end
+```
+
+## 6. Generate Multiple Methods
+
+A single `_()` call can produce several methods:
+
+```ruby
+names = calc._(
+  "create add, subtract, multiply, and divide methods for two integers"
+)
+#=> [:add, :subtract, :multiply, :divide]
+
+calc.subtract(10, 3)  #=> 7
+calc.multiply(4, 5)   #=> 20
+calc.divide(10, 3)    #=> 3.333...
+```
+
+## Next Steps
+
+- [How to Use SelfAgency](../guide/how-to-use.md) -- Where SelfAgency fits in your design workflow
+- [Scopes](../guide/scopes.md) -- Generate singleton and class methods
+- [Source Inspection](../guide/source-inspection.md) -- View and retrieve generated source
+- [Saving Methods](../guide/saving-methods.md) -- Persist generated methods to files
+- [Configuration](../guide/configuration.md) -- All configuration options

data/docs/guide/configuration.md

@@ -0,0 +1,113 @@
+# Configuration
+
+SelfAgency must be configured before generating any methods. Call `SelfAgency.configure` with a block:
+
+```ruby
+SelfAgency.configure do |config|
+  config.provider = :ollama
+  config.model    = "qwen3-coder:30b"
+  config.api_base = "http://localhost:11434/v1"
+end
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `provider` | `Symbol` | `:ollama` | RubyLLM provider name |
+| `model` | `String` | `"qwen3-coder:30b"` | LLM model identifier |
+| `api_base` | `String` | `"http://localhost:11434/v1"` | Provider API endpoint |
+| `request_timeout` | `Integer` | `30` | Request timeout in seconds |
+| `max_retries` | `Integer` | `1` | Number of retries on failure |
+| `retry_interval` | `Float` | `0.5` | Seconds between retries |
+| `template_directory` | `String` | `lib/self_agency/prompts` | Path to ERB prompt templates |
+| `generation_retries` | `Integer` | `3` | Max retry attempts when validation or security checks fail |
+| `logger` | `Proc`, `Logger`, or `nil` | `nil` | Logger for pipeline events (see [Logging](#logging) below) |
+
+## Configuration Is Mandatory
+
+Calling `_()` before `configure` raises `SelfAgency::Error`:
+
+```ruby
+SelfAgency.reset!
+
+class Widget
+  include SelfAgency
+end
+
+Widget.new._("a method")
+#=> SelfAgency::Error: SelfAgency.configure has not been called
+```
+
+## Applying Configuration
+
+`SelfAgency.configure` delegates to `RubyLLM.configure` and `RubyLLM::Template.configure` under the hood:
+
+- `provider` + `api_base` set the provider-specific API base on RubyLLM. The `api_base` value is assigned to the RubyLLM config key `<provider>_api_base`. For example, `:openai` maps to `openai_api_base`, `:ollama` maps to `ollama_api_base`.
+- `request_timeout`, `max_retries`, and `retry_interval` map directly to RubyLLM settings
+- `template_directory` is passed to `RubyLLM::Template`
+
+## Resetting Configuration
+
+`SelfAgency.reset!` restores all defaults and marks the gem as unconfigured:
+
+```ruby
+SelfAgency.reset!
+
+SelfAgency.ensure_configured!
+#=> SelfAgency::Error: SelfAgency.configure has not been called
+```
+
+## Checking Configuration
+
+`SelfAgency.ensure_configured!` raises if `configure` has not been called:
+
+```ruby
+SelfAgency.ensure_configured!  # raises or succeeds silently
+```
+
+## Logging
+
+Set `logger` to observe each stage of the pipeline. It accepts either a callable (receives `stage` and `message`) or a `Logger`-compatible object (uses `.debug`):
+
+```ruby
+# Callable logger
+SelfAgency.configure do |config|
+  config.logger = ->(stage, message) { puts "[#{stage}] #{message}" }
+  # ...
+end
+
+# Standard library Logger
+require "logger"
+SelfAgency.configure do |config|
+  config.logger = Logger.new($stdout)
+  # ...
+end
+```
+
+Logged stages: `:shape`, `:generate`, `:validate`, `:retry`, `:complete`.
+
+## Example: Custom Timeouts
+
+For complex method generation that takes longer:
+
+```ruby
+SelfAgency.configure do |config|
+  config.provider        = :ollama
+  config.model           = "qwen3-coder:30b"
+  config.api_base        = "http://localhost:11434/v1"
+  config.request_timeout = 120
+  config.max_retries     = 3
+  config.retry_interval  = 1.0
+end
+```
+
+## Example: OpenAI
+
+```ruby
+SelfAgency.configure do |config|
+  config.provider = :openai
+  config.model    = "gpt-4o"
+  config.api_base = "https://api.openai.com/v1"
+end
+```

data/docs/guide/generating-methods.md

@@ -0,0 +1,146 @@
+# Generating Methods
+
+The `_()` method is the core API of SelfAgency. It takes a natural language description and generates one or more Ruby methods at runtime.
+
+## Single Method
+
+```ruby
+names = calc._("an instance method named 'add' that accepts two integer parameters a and b, and returns their sum")
+#=> [:add]
+
+calc.add(3, 7)  #=> 10
+```
+
+## Multiple Methods
+
+Describe several methods in one call:
+
+```ruby
+names = calc._(
+  "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)"
+)
+#=> [:add, :subtract, :multiply, :divide]
+```
+
+`_()` always returns an Array of Symbol method names, even for a single method.
+
+## Return Value
+
+The return value is always an `Array<Symbol>` containing the names of all methods defined by that call:
+
+```ruby
+method_names = calc._("a method to double a number")
+method_names        #=> [:double]
+method_names.class  #=> Array
+```
+
+## Class Context
+
+The LLM receives introspection context about your class when generating methods:
+
+- **Class name** -- So it can reference the correct class
+- **Instance variables** -- Current instance variables on the calling object
+- **Public methods** -- Methods defined directly on your class (excludes inherited `Object` methods)
+
+This means generated methods can work with your class's existing state:
+
+```ruby
+class BankAccount
+  include SelfAgency
+
+  attr_reader :owner, :balance
+
+  def initialize(owner, balance)
+    @owner   = owner
+    @balance = balance
+  end
+end
+
+account = BankAccount.new("Alice", 1000)
+account._(
+  "an instance method named 'summary' that returns a string like " \
+  "'Account for <owner>: $<balance>' using the @owner and @balance instance variables"
+)
+
+account.summary  #=> "Account for Alice: $1000"
+```
+
+## Method Overrides
+
+Generating a method with the same name as an existing method overrides it. SelfAgency uses `Module#prepend`, so the generated method takes priority in Ruby's method resolution order (MRO):
+
+```ruby
+class Formatter
+  include SelfAgency
+
+  def greet(name)
+    "Hello, #{name}"
+  end
+end
+
+fmt = Formatter.new
+fmt.greet("World")  #=> "Hello, World"
+
+fmt._(
+  "an instance method named 'greet' that accepts a name parameter " \
+  "and returns 'Greetings, <name>! Welcome aboard.'"
+)
+
+fmt.greet("World")  #=> "Greetings, World! Welcome aboard."
+```
+
+## Automatic Retries
+
+When validation or security checks fail, SelfAgency automatically retries code generation. On each retry, the previous error message and failed code are fed back to the LLM so it can self-correct.
+
+The number of attempts is controlled by `generation_retries` (default: `3`):
+
+```ruby
+SelfAgency.configure do |config|
+  config.generation_retries = 5  # try up to 5 times
+  # ...
+end
+```
+
+If all attempts fail, the last `ValidationError` or `SecurityError` is raised. The error includes an `attempt` attribute indicating which attempt produced it.
+
+!!! note
+    Only validation and security failures trigger retries. If the LLM returns `nil` (a `GenerationError`), the error is raised immediately with no retry.
+
+## Error Handling
+
+`_()` can raise three types of errors. Each error class carries additional attributes for programmatic inspection:
+
+```ruby
+begin
+  calc._("a method to do something")
+rescue SelfAgency::GenerationError => e
+  e.stage    #=> :shape or :generate
+  e.attempt  #=> Integer (attempt number, if during retry)
+rescue SelfAgency::ValidationError => e
+  e.generated_code  #=> String (the code that failed)
+  e.attempt         #=> Integer (attempt number, if during retry)
+rescue SelfAgency::SecurityError => e
+  e.matched_pattern  #=> String (the pattern that triggered the error)
+  e.generated_code   #=> String (the code that failed)
+end
+```
+
+Or catch all SelfAgency errors at once:
+
+```ruby
+begin
+  calc._("a method to do something")
+rescue SelfAgency::Error => e
+  puts "Generation failed: #{e.message}"
+end
+```
+
+!!! note
+    LLM communication failures (network errors, timeouts, API errors) are wrapped and re-raised as `GenerationError` with a message like `"LLM request failed (Faraday::TimeoutError: timeout)"`. The original exception class and message are preserved in the error message. If generation consistently fails, verify your LLM provider is running and reachable.
+
+See [Errors](../api/errors.md) for the full error hierarchy.

data/docs/guide/how-to-use.md

@@ -0,0 +1,144 @@
+# How to Use SelfAgency
+
+## Two Schools of Software Design
+
+Software architects have long worked with two complementary approaches to building systems. The names change over the decades — structured vs. exploratory, waterfall vs. iterative, specification-first vs. prototype-first — but the underlying concepts remain the same: **Top-Down** and **Bottom-Up**.
+
+### Top-Down Design
+
+Top-Down design begins at the highest level of abstraction. You define the overall system architecture, decompose it into subsystems, decompose those into modules, and continue refining until you arrive at the concrete methods and functions that do the actual work.
+
+```
+System
+  └── Subsystem A
+  │     └── Module A1
+  │     │     └── method_x
+  │     │     └── method_y
+  │     └── Module A2
+  │           └── method_z
+  └── Subsystem B
+        └── ...
+```
+
+This approach excels at maintaining coherence across large systems. You know the shape of the whole before you write a line of implementation code.
+
+### Bottom-Up Design
+
+Bottom-Up design starts at the opposite end. You write the lowest-level functions first — the critical algorithms, the core transformations, the essential business logic — and then compose those pieces into higher-level abstractions.
+
+```
+method_x + method_y  →  Module A1
+Module A1 + Module A2  →  Subsystem A
+Subsystem A + Subsystem B  →  System
+```
+
+This approach excels at producing battle-tested components. Each building block is proven through direct experimentation before it is wired into a larger structure.
+
+### The Pragmatic Architect
+
+A skilled architect does not choose one approach exclusively. The most effective strategy combines both:
+
+- **Top-Down** to establish the overall architecture, define interfaces, and ensure the system hangs together coherently.
+- **Bottom-Up** to experiment with the critical pieces, validate assumptions, and build confidence that the low-level logic actually works.
+
+The two approaches meet in the middle. Top-Down gives you the map. Bottom-Up gives you proven ground truth.
+
+## Where SelfAgency Fits
+
+SelfAgency is a Bottom-Up experimentation tool. It lives in the space where you are exploring an idea, testing a hypothesis, or prototyping a piece of business logic — before you commit to a full architectural design.
+
+The typical workflow looks like this:
+
+### 1. Start an IRB Session
+
+```bash
+bin/console
+# or
+bundle exec irb -r self_agency
+```
+
+### 2. Configure Your LLM
+
+```ruby
+SelfAgency.configure do |config|
+  config.provider = :ollama
+  config.model    = "qwen3-coder:30b"
+  config.api_base = "http://localhost:11434/v1"
+end
+```
+
+### 3. Sketch a Class Around Your Domain
+
+You do not need a complete design. Start with the concept:
+
+```ruby
+class PricingEngine
+  include SelfAgency
+
+  def initialize(base_rate:, discount_tiers:)
+    @base_rate = base_rate
+    @discount_tiers = discount_tiers
+  end
+end
+
+engine = PricingEngine.new(
+  base_rate: 100.0,
+  discount_tiers: { silver: 0.05, gold: 0.10, platinum: 0.15 }
+)
+```
+
+### 4. Generate and Experiment
+
+Describe the behavior you need in plain language. Try it. Refine the description. Try again.
+
+```ruby
+engine._("calculate the discounted price for a given tier and quantity")
+engine.calculate_discounted_price(:gold, 5)
+#=> 450.0
+
+# Not quite what you wanted? Inspect the source:
+puts engine._source_for(:calculate_discounted_price)
+
+# Refine and regenerate:
+engine._(
+  "calculate the discounted price: multiply base_rate by quantity, " \
+  "then subtract the tier's discount percentage from discount_tiers. " \
+  "Raise ArgumentError if the tier is not recognized."
+)
+```
+
+Each iteration gives you a working method you can call immediately. You see the generated source, test it with real inputs, and adjust your description until the logic is right.
+
+### 5. Save What Works
+
+Once a method behaves correctly, persist it:
+
+```ruby
+engine._save!(:calculate_discounted_price)
+# Writes the method source to a file you can incorporate into your codebase
+```
+
+### 6. Build Up
+
+With proven components in hand, you can now make informed architectural decisions. You know what the critical methods look like, what their interfaces are, and how they behave. Wire them into your Top-Down design with confidence.
+
+## The Experimentation Loop
+
+The core value of SelfAgency is shortening the feedback loop during Bottom-Up exploration:
+
+```
+Describe  →  Generate  →  Test  →  Inspect  →  Refine
+    ↑                                              │
+    └──────────────────────────────────────────────┘
+```
+
+You stay in IRB the entire time. No file switching, no boilerplate, no deploy cycle. Just describe what you need, see if it works, and iterate until it does.
+
+This makes SelfAgency particularly useful for:
+
+- **Prototyping business rules** — "calculate the late fee given these conditions"
+- **Exploring algorithms** — "sort these records by weighted score using these criteria"
+- **Validating data transformations** — "parse this CSV row into a normalized hash"
+- **Building up a utility class** — generate methods one at a time, test each, save the keepers
+
+When you are done experimenting, you have real, tested Ruby methods — not pseudocode or diagrams. Those methods become the foundation your architecture is built on.