self_agency 0.0.1

data/docs/development/contributing.md

@@ -0,0 +1,45 @@
+# Contributing
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork
+3. Install dependencies: `bin/setup`
+4. Create a feature branch: `git checkout -b my-feature`
+5. Make your changes
+6. Run the tests: `rake test`
+7. Commit and push
+8. Open a pull request
+
+## Guidelines
+
+### Code Style
+
+- Follow existing patterns in the codebase
+- All private helpers are prefixed `self_agency_` to avoid name collisions with host classes
+- Keep the gem's runtime dependency count minimal
+
+### Testing
+
+- All tests must pass offline (no LLM connection required)
+- Add tests for new features or bug fixes
+- Test validation, sanitization, and security patterns directly
+
+### Security
+
+- Any changes to `DANGEROUS_PATTERNS` or `Sandbox` must be carefully reviewed
+- New patterns should have corresponding test cases
+- The two-layer security model (static + runtime) should be maintained
+
+### Documentation
+
+- Update relevant docs pages for user-facing changes
+- Run `mkdocs serve` to preview documentation changes locally
+
+## Reporting Issues
+
+Report bugs and feature requests on [GitHub Issues](https://github.com/madbomber/self_agency/issues).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

data/docs/development/setup.md

@@ -0,0 +1,81 @@
+# Development Setup
+
+## Prerequisites
+
+- Ruby >= 3.2.0
+- Bundler
+
+## Getting Started
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/madbomber/self_agency.git
+cd self_agency
+bin/setup
+```
+
+`bin/setup` installs gem dependencies via Bundler.
+
+## Dependencies
+
+### Runtime
+
+| Gem | Purpose |
+|-----|---------|
+| `ruby_llm` | LLM provider communication |
+| `ruby_llm-template` | ERB prompt template management |
+| `method_source` | Source code retrieval for file-defined methods |
+
+### Development
+
+| Gem | Purpose |
+|-----|---------|
+| `minitest` | Test framework |
+| `rake` | Task runner |
+| `simplecov` | Code coverage |
+| `debug_me` | Debugging output |
+| `irb` | Interactive console |
+
+## Console
+
+Start an interactive console with the gem preloaded:
+
+```bash
+bin/console
+```
+
+## Project Structure
+
+```
+self_agency/
+  lib/
+    self_agency.rb              # Main module
+    self_agency/
+      version.rb                # VERSION constant
+      errors.rb                 # Error hierarchy
+      configuration.rb          # Configuration + singleton methods
+      sandbox.rb                # Runtime sandbox
+      validator.rb              # Static analysis + validation
+      generator.rb              # LLM communication
+      saver.rb                  # _save! helpers
+      prompts/                  # ERB templates
+        shape/
+          system.txt.erb
+          user.txt.erb
+        generate/
+          system.txt.erb
+          user.txt.erb
+  test/
+    test_helper.rb              # Test setup
+    test_configuration.rb       # Configuration tests
+    test_generator.rb           # Generator tests
+    test_pipeline.rb            # Pipeline tests
+    test_sandbox.rb             # Sandbox tests
+    test_save.rb                # _save! tests
+    test_source_for.rb          # Source inspection tests
+    test_templates.rb           # Template tests
+    test_validator.rb           # Validator tests
+  examples/                     # 12 example scripts
+  docs/                         # This documentation
+```

data/docs/development/testing.md

@@ -0,0 +1,70 @@
+# Testing
+
+SelfAgency uses Minitest. All tests run offline -- they exercise configuration, validation, sanitization, and sandboxing without calling an LLM.
+
+## Running Tests
+
+Run the full test suite:
+
+```bash
+rake test
+```
+
+This is the default Rake task, so `rake` alone works too:
+
+```bash
+rake
+```
+
+## Running Individual Tests
+
+Run a specific test file:
+
+```bash
+bundle exec ruby -Ilib -Itest test/test_validator.rb
+```
+
+Run a single test method:
+
+```bash
+bundle exec ruby -Ilib -Itest test/test_validator.rb -n test_method_name
+```
+
+## Test Structure
+
+| File | Tests |
+|------|-------|
+| `test_configuration.rb` | Configuration options, `reset!`, `ensure_configured!` |
+| `test_generator.rb` | Generator helper methods |
+| `test_pipeline.rb` | End-to-end pipeline logic |
+| `test_sandbox.rb` | Runtime sandbox blocks dangerous methods |
+| `test_save.rb` | `_save!` file generation |
+| `test_source_for.rb` | `_source_for` at instance and class level |
+| `test_templates.rb` | Prompt template loading |
+| `test_validator.rb` | Sanitization, validation, security patterns |
+
+## Test Design
+
+Tests define a `SampleClass` that includes `SelfAgency` for testing private helpers via `send`. This avoids needing a live LLM connection -- the tests exercise the internal machinery directly:
+
+```ruby
+class SampleClass
+  include SelfAgency
+end
+
+# Test private helpers
+obj = SampleClass.new
+obj.send(:self_agency_validate!, code)
+obj.send(:self_agency_sanitize, raw)
+```
+
+## Code Coverage
+
+SimpleCov runs automatically with every test execution. Coverage reports are generated in the `coverage/` directory after each `rake test` run:
+
+```bash
+rake test
+# Coverage report written to coverage/
+```
+
+Open `coverage/index.html` in a browser to view the detailed report.

data/docs/examples/autonomous-robots.md

@@ -0,0 +1,109 @@
+# Example 12: Autonomous Robots
+
+Three robots autonomously build a city landmarks tour pipeline. Unlike Example 11, each robot receives only a high-level **goal** -- the LLM decides method names, algorithms, and data structures.
+
+**Source:** `examples/12_autonomous_robots/`
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A[Collector] -->|landmark data| B[Analyst]
+    B -->|analyzed data| C[Planner]
+    C -->|itinerary| D[Output]
+
+    style A fill:#6366f1,color:#fff
+    style B fill:#8b5cf6,color:#fff
+    style C fill:#a855f7,color:#fff
+```
+
+| Robot | Goal | Methods |
+|-------|------|---------|
+| **Collector** | Return an Array of 8 fictional city landmarks | LLM decides |
+| **Analyst** | Analyze landmark data (statistics, ranking, grouping) | LLM decides |
+| **Planner** | Create a formatted one-day tour itinerary | LLM decides |
+
+## Three-Layer LLM Approach
+
+This example adds a third layer compared to Example 11:
+
+1. **Layer 1 (Decompose):** Ask the LLM to break a high-level goal into helper method specs. The LLM chooses method names, parameters, and algorithms
+2. **Layer 2 (Generate Helpers):** Loop through specs, call `_()` for each. SelfAgency handles shape, generate, validate, sandbox eval
+3. **Layer 3 (Generate Orchestrator):** A final `_()` call generates an `execute_task` method that wires the helpers together
+
+```mermaid
+flowchart TD
+    A[High-Level Goal] --> B["Layer 1: Decompose"]
+    B --> C["JSON specs<br/>(LLM-chosen names)"]
+    C --> D["Layer 2: Generate Helpers"]
+    D --> E["Layer 3: Generate Orchestrator"]
+    E --> F[Robot Ready]
+```
+
+## Self-Repair
+
+If `execute_task` raises at runtime, the robot attempts self-repair:
+
+1. **Identify the failing method** from the backtrace
+2. **Build a repair prompt** with the error, current source, goal context, and input data shape
+3. **Regenerate** the failing method via `_()` with `scope: :singleton`
+4. **Retry** (up to `MAX_REPAIR_ATTEMPTS = 3`)
+
+```ruby
+def perform_task(input = nil)
+  attempts = 0
+
+  begin
+    execute_task(input)
+  rescue => error
+    attempts += 1
+    if attempts < MAX_REPAIR_ATTEMPTS
+      repair_method(error, input)
+      retry
+    end
+  end
+end
+```
+
+The repair prompt includes:
+
+- The robot's overall goal
+- All generated capabilities
+- The current source code of the failing method
+- The runtime error (class, message, backtrace)
+- A description of the input data shape (class, keys, sample elements)
+
+## Key Differences from Example 11
+
+| Aspect | Example 11 (Collaborative) | Example 12 (Autonomous) |
+|--------|---------------------------|------------------------|
+| Task description | Prescriptive (exact method names, algorithms) | Goal-oriented (what, not how) |
+| LLM layers | 2 (analyze + generate) | 3 (decompose + generate + orchestrate) |
+| Method naming | Dictated by user | Chosen by LLM |
+| Error recovery | None | Self-repair with retry |
+| Scope | Instance methods | Singleton methods |
+
+## Pipeline Execution
+
+```ruby
+# Step 1: Collector builds a landmark catalog
+collector_result = collector.perform_task
+
+# Step 2: Analyst processes the catalog
+analyst_result = analyst.perform_task(analyst_input)
+
+# Step 3: Planner creates the itinerary
+final_itinerary = planner.perform_task(planner_input)
+```
+
+## Saving Robots
+
+Each robot's generated methods are saved as a subclass:
+
+```ruby
+[collector, analyst, planner].each do |robot|
+  path = robot._save!(as: robot.name)
+end
+```
+
+This captures the LLM's autonomous design decisions as permanent Ruby source files.

data/docs/examples/basic-examples.md

@@ -0,0 +1,237 @@
+# Basic Examples (01--09)
+
+These examples cover SelfAgency's core features one at a time.
+
+## 01: Basic Usage
+
+The simplest example: include `SelfAgency`, generate a single method, call it.
+
+```ruby
+class Calculator
+  include SelfAgency
+end
+
+calc = Calculator.new
+method_names = calc._("an instance method named 'add' that accepts two integer parameters a and b, and returns their sum")
+
+puts method_names.inspect  #=> [:add]
+puts calc.add(3, 7)        #=> 10
+```
+
+**Source:** `examples/01_basic_usage.rb`
+
+---
+
+## 02: Multiple Methods
+
+Generate several related methods in a single `_()` call.
+
+```ruby
+class Arithmetic
+  include SelfAgency
+end
+
+arith = Arithmetic.new
+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 method_names.inspect  #=> [:add, :subtract, :multiply, :divide]
+puts arith.multiply(10, 3) #=> 30
+```
+
+**Source:** `examples/02_multiple_methods.rb`
+
+---
+
+## 03: Scopes
+
+Demonstrates all three scopes: instance, singleton, and class.
+
+```ruby
+class Greeter
+  include SelfAgency
+end
+
+alice = Greeter.new
+bob   = Greeter.new
+
+# Instance -- available to all instances
+alice._("an instance method named 'hello' that returns 'Hello, world!'")
+bob.hello  #=> "Hello, world!"
+
+# Singleton -- available to one instance only
+alice._("a method named 'secret' that returns 'Alice only'", scope: :singleton)
+alice.secret                 #=> "Alice only"
+bob.respond_to?(:secret)     #=> false
+
+# Class -- available on the class itself
+alice._("a class method named 'self.class_greeting' that returns 'Greetings from Greeter'", scope: :class)
+Greeter.class_greeting       #=> "Greetings from Greeter"
+```
+
+**Source:** `examples/03_scopes.rb`
+
+---
+
+## 04: Source Inspection
+
+View generated source code and the fallback to `method_source` for file-defined methods.
+
+```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")
+
+# LLM-generated method (includes description as comment header)
+puts helper._source_for(:square)
+
+# File-defined method (falls back to method_source gem)
+puts helper._source_for(:double)
+
+# Unknown method
+helper._source_for(:nonexistent)  #=> nil
+```
+
+**Source:** `examples/04_source_inspection.rb`
+
+---
+
+## 05: Lifecycle Hook
+
+Override `on_method_generated` to log or persist each generated method.
+
+```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
+
+calc = PersistentCalculator.new
+calc._("an instance method named 'increment' that returns n + 1")
+# [hook] Generated :increment (scope: instance)
+```
+
+**Source:** `examples/05_lifecycle_hook.rb`
+
+---
+
+## 06: Configuration
+
+Explores all configuration options. Runs offline (no LLM required).
+
+Demonstrates:
+
+- Default values before `configure`
+- `ensure_configured!` raises before `configure`
+- Setting custom values
+- `reset!` restores defaults
+- Custom `template_directory`
+
+**Source:** `examples/06_configuration.rb`
+
+---
+
+## 07: Error Handling
+
+Exercises the error hierarchy. Runs offline (no LLM required).
+
+Demonstrates:
+
+- `SelfAgency::Error` hierarchy verification
+- Calling `_()` before `configure` raises `Error`
+- `ValidationError` for empty code, missing `def...end`, syntax errors
+- `SecurityError` for `system`, `File`, `eval`, `require` patterns
+- Catching all errors with `rescue SelfAgency::Error`
+
+**Source:** `examples/07_error_handling.rb`
+
+---
+
+## 08: Class Context
+
+Shows how the LLM receives class introspection (class name, instance variables, public methods) to generate context-aware code.
+
+```ruby
+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)
+account._(
+  "an instance method named 'summary' that returns 'Account for <owner>: $<balance>'"
+)
+
+puts account.summary  #=> "Account for Alice: $1000"
+```
+
+**Source:** `examples/08_class_context.rb`
+
+---
+
+## 09: Method Override
+
+Demonstrates that generating a method with the same name as an existing method overrides it via `Module#prepend`.
+
+```ruby
+class Formatter
+  include SelfAgency
+
+  def greet(name)
+    "Hello, #{name}"
+  end
+end
+
+fmt = Formatter.new
+puts fmt.greet("World")  #=> "Hello, World"
+
+fmt._(
+  "an instance method named 'greet' that returns 'Greetings, <name>! Welcome aboard.'"
+)
+
+puts fmt.greet("World")  #=> "Greetings, World! Welcome aboard."
+```
+
+The MRO shows the prepended module:
+
+```
+0. #<Module:0x...>  ← anonymous module with generated method
+1. Formatter
+2. SelfAgency
+3. ...
+```
+
+**Source:** `examples/09_method_override.rb`

data/docs/examples/collaborative-robots.md

@@ -0,0 +1,98 @@
+# Example 11: Collaborative Robots
+
+Three robots collaborate through a shared message bus to build a weather data pipeline. Each robot's methods are generated by the LLM based on detailed task descriptions.
+
+**Source:** `examples/11_collaborative_robots/`
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A[Atlas] -->|weather data| B[Nova]
+    B -->|analyzed data| C[Echo]
+    C -->|formatted report| D[Output]
+
+    style A fill:#6366f1,color:#fff
+    style B fill:#8b5cf6,color:#fff
+    style C fill:#a855f7,color:#fff
+```
+
+Three robots connected by a `MessageBus`:
+
+| Robot | Role | Methods Generated |
+|-------|------|-------------------|
+| **Atlas** | Data generator | `generate_weather_data`, `summarize_raw_data` |
+| **Nova** | Analyzer | `compute_basic_statistics`, `classify_conditions` |
+| **Echo** | Reporter | `format_weather_report` |
+
+## Two-Layer LLM Approach
+
+This example uses a **two-layer** approach:
+
+1. **Layer 1 (Analyze):** A direct `RubyLLM.chat().ask()` call decomposes the task description into a JSON array of method specifications
+2. **Layer 2 (Generate):** Loops through the specs and calls `_()` for each one. SelfAgency handles shape, generate, validate, and sandbox eval
+
+The task descriptions are **prescriptive** -- they dictate exact method names, parameters, algorithms, and data structures.
+
+## Robot Class
+
+The `Robot` class includes `SelfAgency` and adds:
+
+- **Task decomposition** via `analyze_task` -- asks the LLM to parse a task into method specs
+- **Pipeline execution** via `execute` -- chains generated methods by arity
+- **Message bus** -- `send_message`, `receive_message`, `broadcast`
+- **Generation logging** via `on_method_generated`
+- **Persistence** via `_save!` -- saves each robot as a subclass
+
+```ruby
+class Robot
+  include SelfAgency
+
+  attr_reader :name, :task, :bus, :inbox, :capabilities, :generation_log
+
+  def initialize(name:, task:, bus:)
+    @name = name
+    @task = task
+    @bus  = bus
+    # ... decompose task, generate methods
+  end
+
+  def execute(input = nil)
+    # Chain capabilities by arity
+  end
+end
+```
+
+## Pipeline Execution
+
+```ruby
+# Step 1: Atlas generates weather data
+atlas_result = atlas.execute
+atlas.send_message(to: "Nova", content: atlas_result)
+
+# Step 2: Nova analyzes the data
+nova_input = nova.inbox.last&.dig(:content)
+nova_result = nova.execute(nova_input)
+nova.send_message(to: "Echo", content: nova_result)
+
+# Step 3: Echo formats the report
+echo_input = echo.inbox.last&.dig(:content)
+final_report = echo.execute(echo_input)
+```
+
+## Saving Robots
+
+After the pipeline runs, each robot's generated methods are saved as a subclass file:
+
+```ruby
+[atlas, nova, echo].each do |robot|
+  path = robot._save!(as: robot.name)
+  puts "#{robot.name}: saved to #{path}"
+end
+```
+
+This produces files like `atlas.rb`, `nova.rb`, `echo.rb`, each containing a `Robot` subclass with the generated methods baked in.
+
+## Key Difference from Example 12
+
+In this example, the task descriptions **dictate** method names and algorithms. The LLM is told *exactly* what to implement. Compare with [Example 12: Autonomous Robots](autonomous-robots.md), where robots receive only a high-level goal and the LLM decides everything.