@every-env/compound-plugin 0.2.0 → 0.5.0

package/plugins/compound-engineering/skills/dspy-ruby/SKILL.md

@@ -1,594 +1,737 @@
 ---
 name: dspy-ruby
-description: This skill should be used when working with DSPy.rb, a Ruby framework for building type-safe, composable LLM applications. Use this when implementing predictable AI features, creating LLM signatures and modules, configuring language model providers (OpenAI, Anthropic, Gemini, Ollama), building agent systems with tools, optimizing prompts, or testing LLM-powered functionality in Ruby applications.
+description: Build type-safe LLM applications with DSPy.rb — Ruby's programmatic prompt framework with signatures, modules, agents, and optimization. Use when implementing predictable AI features, creating LLM signatures and modules, configuring language model providers, building agent systems with tools, optimizing prompts, or testing LLM-powered functionality in Ruby applications.
 ---
 
-# DSPy.rb Expert
+# DSPy.rb
 
-## Overview
+> Build LLM apps like you build software. Type-safe, modular, testable.
+
+DSPy.rb brings software engineering best practices to LLM development. Instead of tweaking prompts, define what you want with Ruby types and let DSPy handle the rest.
 
-DSPy.rb is a Ruby framework that enables developers to **program LLMs, not prompt them**. Instead of manually crafting prompts, define application requirements through type-safe, composable modules that can be tested, optimized, and version-controlled like regular code.
+## Overview
 
-This skill provides comprehensive guidance on:
-- Creating type-safe signatures for LLM operations
-- Building composable modules and workflows
-- Configuring multiple LLM providers
-- Implementing agents with tools
-- Testing and optimizing LLM applications
-- Production deployment patterns
+DSPy.rb is a Ruby framework for building language model applications with programmatic prompts. It provides:
 
-## Core Capabilities
+- **Type-safe signatures** — Define inputs/outputs with Sorbet types
+- **Modular components** — Compose and reuse LLM logic
+- **Automatic optimization** — Use data to improve prompts, not guesswork
+- **Production-ready** — Built-in observability, testing, and error handling
 
-### 1. Type-Safe Signatures
+## Core Concepts
 
-Create input/output contracts for LLM operations with runtime type checking.
+### 1. Signatures
 
-**When to use**: Defining any LLM task, from simple classification to complex analysis.
+Define interfaces between your app and LLMs using Ruby types:
 
-**Quick reference**:
 ```ruby
-class EmailClassificationSignature < DSPy::Signature
-  description "Classify customer support emails"
+class EmailClassifier < DSPy::Signature
+  description "Classify customer support emails by category and priority"
+
+  class Priority < T::Enum
+    enums do
+      Low = new('low')
+      Medium = new('medium')
+      High = new('high')
+      Urgent = new('urgent')
+    end
+  end
 
   input do
-    const :email_subject, String
-    const :email_body, String
+    const :email_content, String
+    const :sender, String
   end
 
   output do
-    const :category, T.enum(["Technical", "Billing", "General"])
-    const :priority, T.enum(["Low", "Medium", "High"])
+    const :category, String
+    const :priority, Priority  # Type-safe enum with defined values
+    const :confidence, Float
   end
 end
 ```
 
-**Templates**: See `assets/signature-template.rb` for comprehensive examples including:
-- Basic signatures with multiple field types
-- Vision signatures for multimodal tasks
-- Sentiment analysis signatures
-- Code generation signatures
-
-**Best practices**:
-- Always provide clear, specific descriptions
-- Use enums for constrained outputs
-- Include field descriptions with `desc:` parameter
-- Prefer specific types over generic String when possible
+### 2. Modules
 
-**Full documentation**: See `references/core-concepts.md` sections on Signatures and Type Safety.
+Build complex workflows from simple building blocks:
 
-### 2. Composable Modules
+- **Predict** — Basic LLM calls with signatures
+- **ChainOfThought** — Step-by-step reasoning
+- **ReAct** — Tool-using agents
+- **CodeAct** — Dynamic code generation agents (install the `dspy-code_act` gem)
 
-Build reusable, chainable modules that encapsulate LLM operations.
+### 3. Tools & Toolsets
 
-**When to use**: Implementing any LLM-powered feature, especially complex multi-step workflows.
+Create type-safe tools for agents with comprehensive Sorbet support:
 
-**Quick reference**:
 ```ruby
-class EmailProcessor < DSPy::Module
-  def initialize
-    super
-    @classifier = DSPy::Predict.new(EmailClassificationSignature)
+# Enum-based tool with automatic type conversion
+class CalculatorTool < DSPy::Tools::Base
+  tool_name 'calculator'
+  tool_description 'Performs arithmetic operations with type-safe enum inputs'
+
+  class Operation < T::Enum
+    enums do
+      Add = new('add')
+      Subtract = new('subtract')
+      Multiply = new('multiply')
+      Divide = new('divide')
+    end
   end
 
-  def forward(email_subject:, email_body:)
-    @classifier.forward(
-      email_subject: email_subject,
-      email_body: email_body
-    )
+  sig { params(operation: Operation, num1: Float, num2: Float).returns(T.any(Float, String)) }
+  def call(operation:, num1:, num2:)
+    case operation
+    when Operation::Add then num1 + num2
+    when Operation::Subtract then num1 - num2
+    when Operation::Multiply then num1 * num2
+    when Operation::Divide
+      return "Error: Division by zero" if num2 == 0
+      num1 / num2
+    end
   end
 end
-```
 
-**Templates**: See `assets/module-template.rb` for comprehensive examples including:
-- Basic modules with single predictors
-- Multi-step pipelines that chain modules
-- Modules with conditional logic
-- Error handling and retry patterns
-- Stateful modules with history
-- Caching implementations
+# Multi-tool toolset with rich types
+class DataToolset < DSPy::Tools::Toolset
+  toolset_name "data_processing"
 
-**Module composition**: Chain modules together to create complex workflows:
-```ruby
-class Pipeline < DSPy::Module
-  def initialize
-    super
-    @step1 = Classifier.new
-    @step2 = Analyzer.new
-    @step3 = Responder.new
+  class Format < T::Enum
+    enums do
+      JSON = new('json')
+      CSV = new('csv')
+      XML = new('xml')
+    end
   end
 
-  def forward(input)
-    result1 = @step1.forward(input)
-    result2 = @step2.forward(result1)
-    @step3.forward(result2)
+  tool :convert, description: "Convert data between formats"
+  tool :validate, description: "Validate data structure"
+
+  sig { params(data: String, from: Format, to: Format).returns(String) }
+  def convert(data:, from:, to:)
+    "Converted from #{from.serialize} to #{to.serialize}"
+  end
+
+  sig { params(data: String, format: Format).returns(T::Hash[String, T.any(String, Integer, T::Boolean)]) }
+  def validate(data:, format:)
+    { valid: true, format: format.serialize, row_count: 42, message: "Data validation passed" }
   end
 end
 ```
 
-**Full documentation**: See `references/core-concepts.md` sections on Modules and Module Composition.
+### 4. Type System & Discriminators
+
+DSPy.rb uses sophisticated type discrimination for complex data structures:
+
+- **Automatic `_type` field injection** — DSPy adds discriminator fields to structs for type safety
+- **Union type support** — `T.any()` types automatically disambiguated by `_type`
+- **Reserved field name** — Avoid defining your own `_type` fields in structs
+- **Recursive filtering** — `_type` fields filtered during deserialization at all nesting levels
+
+### 5. Optimization
 
-### 3. Multiple Predictor Types
+Improve accuracy with real data:
 
-Choose the right predictor for your task:
+- **MIPROv2** — Advanced multi-prompt optimization with bootstrap sampling and Bayesian optimization
+- **GEPA** — Genetic-Pareto Reflective Prompt Evolution with feedback maps, experiment tracking, and telemetry
+- **Evaluation** — Comprehensive framework with built-in and custom metrics, error handling, and batch processing
+
+## Quick Start
 
-**Predict**: Basic LLM inference with type-safe inputs/outputs
 ```ruby
-predictor = DSPy::Predict.new(TaskSignature)
-result = predictor.forward(input: "data")
+# Install
+gem 'dspy'
+
+# Configure
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
+end
+
+# Define a task
+class SentimentAnalysis < DSPy::Signature
+  description "Analyze sentiment of text"
+
+  input do
+    const :text, String
+  end
+
+  output do
+    const :sentiment, String  # positive, negative, neutral
+    const :score, Float       # 0.0 to 1.0
+  end
+end
+
+# Use it
+analyzer = DSPy::Predict.new(SentimentAnalysis)
+result = analyzer.call(text: "This product is amazing!")
+puts result.sentiment  # => "positive"
+puts result.score      # => 0.92
 ```
 
-**ChainOfThought**: Adds automatic reasoning for improved accuracy
+## Provider Adapter Gems
+
+Two strategies for connecting to LLM providers:
+
+### Per-provider adapters (direct SDK access)
+
 ```ruby
-predictor = DSPy::ChainOfThought.new(TaskSignature)
-result = predictor.forward(input: "data")
-# Returns: { reasoning: "...", output: "..." }
+# Gemfile
+gem 'dspy'
+gem 'dspy-openai'    # OpenAI, OpenRouter, Ollama
+gem 'dspy-anthropic' # Claude
+gem 'dspy-gemini'    # Gemini
 ```
 
-**ReAct**: Tool-using agents with iterative reasoning
+Each adapter gem pulls in the official SDK (`openai`, `anthropic`, `gemini-ai`).
+
+### Unified adapter via RubyLLM (recommended for multi-provider)
+
 ```ruby
-predictor = DSPy::ReAct.new(
-  TaskSignature,
-  tools: [SearchTool.new, CalculatorTool.new],
-  max_iterations: 5
-)
+# Gemfile
+gem 'dspy'
+gem 'dspy-ruby_llm'  # Routes to any provider via ruby_llm
+gem 'ruby_llm'
 ```
 
-**CodeAct**: Dynamic code generation (requires `dspy-code_act` gem)
+RubyLLM handles provider routing based on the model name. Use the `ruby_llm/` prefix:
+
 ```ruby
-predictor = DSPy::CodeAct.new(TaskSignature)
-result = predictor.forward(task: "Calculate factorial of 5")
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('ruby_llm/gemini-2.5-flash', structured_outputs: true)
+  # c.lm = DSPy::LM.new('ruby_llm/claude-sonnet-4-20250514', structured_outputs: true)
+  # c.lm = DSPy::LM.new('ruby_llm/gpt-4o-mini', structured_outputs: true)
+end
 ```
 
-**When to use each**:
-- **Predict**: Simple tasks, classification, extraction
-- **ChainOfThought**: Complex reasoning, analysis, multi-step thinking
-- **ReAct**: Tasks requiring external tools (search, calculation, API calls)
-- **CodeAct**: Tasks best solved with generated code
-
-**Full documentation**: See `references/core-concepts.md` section on Predictors.
+## Events System
 
-### 4. LLM Provider Configuration
+DSPy.rb ships with a structured event bus for observing runtime behavior.
 
-Support for OpenAI, Anthropic Claude, Google Gemini, Ollama, and OpenRouter.
+### Module-Scoped Subscriptions (preferred for agents)
 
-**Quick configuration examples**:
 ```ruby
-# OpenAI
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
-    api_key: ENV['OPENAI_API_KEY'])
-end
+class MyAgent < DSPy::Module
+  subscribe 'lm.tokens', :track_tokens, scope: :descendants
 
-# Anthropic Claude
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('anthropic/claude-3-5-sonnet-20241022',
-    api_key: ENV['ANTHROPIC_API_KEY'])
+  def track_tokens(_event, attrs)
+    @total_tokens += attrs.fetch(:total_tokens, 0)
+  end
 end
+```
 
-# Google Gemini
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('gemini/gemini-1.5-pro',
-    api_key: ENV['GOOGLE_API_KEY'])
-end
+### Global Subscriptions (for observability/integrations)
 
-# Local Ollama (free, private)
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('ollama/llama3.1')
+```ruby
+subscription_id = DSPy.events.subscribe('score.create') do |event, attrs|
+  Langfuse.export_score(attrs)
 end
+
+# Wildcards supported
+DSPy.events.subscribe('llm.*') { |name, attrs| puts "[#{name}] tokens=#{attrs[:total_tokens]}" }
 ```
 
-**Templates**: See `assets/config-template.rb` for comprehensive examples including:
-- Environment-based configuration
-- Multi-model setups for different tasks
-- Configuration with observability (OpenTelemetry, Langfuse)
-- Retry logic and fallback strategies
-- Budget tracking
-- Rails initializer patterns
+Event names use dot-separated namespaces (`llm.generate`, `react.iteration_complete`). Every event includes module metadata (`module_path`, `module_leaf`, `module_scope.ancestry_token`) for filtering.
 
-**Provider compatibility matrix**:
+## Lifecycle Callbacks
 
-| Feature | OpenAI | Anthropic | Gemini | Ollama |
-|---------|--------|-----------|--------|--------|
-| Structured Output | ✅ | ✅ | ✅ | ✅ |
-| Vision (Images) | ✅ | ✅ | ✅ | ⚠️ Limited |
-| Image URLs | ✅ | ❌ | ❌ | ❌ |
-| Tool Calling | ✅ | ✅ | ✅ | Varies |
+Rails-style lifecycle hooks ship with every `DSPy::Module`:
 
-**Cost optimization strategy**:
-- Development: Ollama (free) or gpt-4o-mini (cheap)
-- Testing: gpt-4o-mini with temperature=0.0
-- Production simple tasks: gpt-4o-mini, claude-3-haiku, gemini-1.5-flash
-- Production complex tasks: gpt-4o, claude-3-5-sonnet, gemini-1.5-pro
+- **`before`** — Runs ahead of `forward` for setup (metrics, context loading)
+- **`around`** — Wraps `forward`, calls `yield`, and lets you pair setup/teardown logic
+- **`after`** — Fires after `forward` returns for cleanup or persistence
 
-**Full documentation**: See `references/providers.md` for all configuration options, provider-specific features, and troubleshooting.
+```ruby
+class InstrumentedModule < DSPy::Module
+  before :setup_metrics
+  around :manage_context
+  after :log_metrics
 
-### 5. Multimodal & Vision Support
+  def forward(question:)
+    @predictor.call(question: question)
+  end
 
-Process images alongside text using the unified `DSPy::Image` interface.
+  private
 
-**Quick reference**:
-```ruby
-class VisionSignature < DSPy::Signature
-  description "Analyze image and answer questions"
+  def setup_metrics
+    @start_time = Time.now
+  end
 
-  input do
-    const :image, DSPy::Image
-    const :question, String
+  def manage_context
+    load_context
+    result = yield
+    save_context
+    result
   end
 
-  output do
-    const :answer, String
+  def log_metrics
+    duration = Time.now - @start_time
+    Rails.logger.info "Prediction completed in #{duration}s"
   end
 end
-
-predictor = DSPy::Predict.new(VisionSignature)
-result = predictor.forward(
-  image: DSPy::Image.from_file("path/to/image.jpg"),
-  question: "What objects are visible?"
-)
 ```
 
-**Image loading methods**:
-```ruby
-# From file
-DSPy::Image.from_file("path/to/image.jpg")
+Execution order: before → around (before yield) → forward → around (after yield) → after. Callbacks are inherited from parent classes and execute in registration order.
 
-# From URL (OpenAI only)
-DSPy::Image.from_url("https://example.com/image.jpg")
+## Fiber-Local LM Context
 
-# From base64
-DSPy::Image.from_base64(base64_data, mime_type: "image/jpeg")
-```
+Override the language model temporarily using fiber-local storage:
 
-**Provider support**:
-- OpenAI: Full support including URLs
-- Anthropic, Gemini: Base64 or file loading only
-- Ollama: Limited multimodal depending on model
+```ruby
+fast_model = DSPy::LM.new("openai/gpt-4o-mini", api_key: ENV['OPENAI_API_KEY'])
 
-**Full documentation**: See `references/core-concepts.md` section on Multimodal Support.
+DSPy.with_lm(fast_model) do
+  result = classifier.call(text: "test")  # Uses fast_model inside this block
+end
+# Back to global LM outside the block
+```
 
-### 6. Testing LLM Applications
+**LM resolution hierarchy**: Instance-level LM → Fiber-local LM (`DSPy.with_lm`) → Global LM (`DSPy.configure`).
 
-Write standard RSpec tests for LLM logic.
+Use `configure_predictor` for fine-grained control over agent internals:
 
-**Quick reference**:
 ```ruby
-RSpec.describe EmailClassifier do
-  before do
-    DSPy.configure do |c|
-      c.lm = DSPy::LM.new('openai/gpt-4o-mini',
-        api_key: ENV['OPENAI_API_KEY'])
-    end
-  end
+agent = DSPy::ReAct.new(MySignature, tools: tools)
+agent.configure { |c| c.lm = default_model }
+agent.configure_predictor('thought_generator') { |c| c.lm = powerful_model }
+```
 
-  it 'classifies technical emails correctly' do
-    classifier = EmailClassifier.new
-    result = classifier.forward(
-      email_subject: "Can't log in",
-      email_body: "Unable to access account"
-    )
+## Evaluation Framework
 
-    expect(result[:category]).to eq('Technical')
-    expect(result[:priority]).to be_in(['High', 'Medium', 'Low'])
-  end
-end
+Systematically test LLM application performance with `DSPy::Evals`:
+
+```ruby
+metric = DSPy::Metrics.exact_match(field: :answer, case_sensitive: false)
+evaluator = DSPy::Evals.new(predictor, metric: metric)
+result = evaluator.evaluate(test_examples, display_table: true)
+puts "Pass Rate: #{(result.pass_rate * 100).round(1)}%"
 ```
 
-**Testing patterns**:
-- Mock LLM responses for unit tests
-- Use VCR for deterministic API testing
-- Test type safety and validation
-- Test edge cases (empty inputs, special characters, long texts)
-- Integration test complete workflows
+Built-in metrics: `exact_match`, `contains`, `numeric_difference`, `composite_and`. Custom metrics return `true`/`false` or a `DSPy::Prediction` with `score:` and `feedback:` fields.
 
-**Full documentation**: See `references/optimization.md` section on Testing.
+Use `DSPy::Example` for typed test data and `export_scores: true` to push results to Langfuse.
 
-### 7. Optimization & Improvement
+## GEPA Optimization
 
-Automatically improve prompts and modules using optimization techniques.
+GEPA (Genetic-Pareto Reflective Prompt Evolution) uses reflection-driven instruction rewrites:
 
-**MIPROv2 optimization**:
 ```ruby
-require 'dspy/mipro'
-
-# Define evaluation metric
-def accuracy_metric(example, prediction)
-  example[:expected_output][:category] == prediction[:category] ? 1.0 : 0.0
-end
+gem 'dspy-gepa'
 
-# Prepare training data
-training_examples = [
-  {
-    input: { email_subject: "...", email_body: "..." },
-    expected_output: { category: 'Technical' }
-  },
-  # More examples...
-]
-
-# Run optimization
-optimizer = DSPy::MIPROv2.new(
-  metric: method(:accuracy_metric),
-  num_candidates: 10
+teleprompter = DSPy::Teleprompt::GEPA.new(
+  metric: metric,
+  reflection_lm: DSPy::ReflectionLM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY']),
+  feedback_map: feedback_map,
+  config: { max_metric_calls: 600, minibatch_size: 6 }
 )
 
-optimized_module = optimizer.compile(
-  EmailClassifier.new,
-  trainset: training_examples
-)
+result = teleprompter.compile(program, trainset: train, valset: val)
+optimized_program = result.optimized_program
 ```
 
-**A/B testing different approaches**:
+The metric must return `DSPy::Prediction.new(score:, feedback:)` so the reflection model can reason about failures. Use `feedback_map` to target individual predictors in composite modules.
+
+## Typed Context Pattern
+
+Replace opaque string context blobs with `T::Struct` inputs. Each field gets its own `description:` annotation in the JSON schema the LLM sees:
+
 ```ruby
-# Test ChainOfThought vs ReAct
-approach_a_score = evaluate_approach(ChainOfThoughtModule, test_set)
-approach_b_score = evaluate_approach(ReActModule, test_set)
+class NavigationContext < T::Struct
+  const :workflow_hint, T.nilable(String),
+        description: "Current workflow phase guidance for the agent"
+  const :action_log, T::Array[String], default: [],
+        description: "Compact one-line-per-action history of research steps taken"
+  const :iterations_remaining, Integer,
+        description: "Budget remaining. Each tool call costs 1 iteration."
+end
+
+class ToolSelectionSignature < DSPy::Signature
+  input do
+    const :query, String
+    const :context, NavigationContext  # Structured, not an opaque string
+  end
+
+  output do
+    const :tool_name, String
+    const :tool_args, String, description: "JSON-encoded arguments"
+  end
+end
 ```
 
-**Full documentation**: See `references/optimization.md` section on Optimization.
+Benefits: type safety at compile time, per-field descriptions in the LLM schema, easy to test as value objects, extensible by adding `const` declarations.
 
-### 8. Observability & Monitoring
+## Schema Formats (BAML / TOON)
 
-Track performance, token usage, and behavior in production.
+Control how DSPy describes signature structure to the LLM:
 
-**OpenTelemetry integration**:
-```ruby
-require 'opentelemetry/sdk'
+- **JSON Schema** (default) — Standard format, works with `structured_outputs: true`
+- **BAML** (`schema_format: :baml`) — 84% token reduction for Enhanced Prompting mode. Requires `sorbet-baml` gem.
+- **TOON** (`schema_format: :toon, data_format: :toon`) — Table-oriented format for both schemas and data. Enhanced Prompting mode only.
 
-OpenTelemetry::SDK.configure do |c|
-  c.service_name = 'my-dspy-app'
-  c.use_all
-end
+BAML and TOON apply only when `structured_outputs: false`. With `structured_outputs: true`, the provider receives JSON Schema directly.
 
-# DSPy automatically creates traces
-```
+## Storage System
 
-**Langfuse tracing**:
-```ruby
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
-    api_key: ENV['OPENAI_API_KEY'])
+Persist and reload optimized programs with `DSPy::Storage::ProgramStorage`:
 
-  c.langfuse = {
-    public_key: ENV['LANGFUSE_PUBLIC_KEY'],
-    secret_key: ENV['LANGFUSE_SECRET_KEY']
-  }
-end
+```ruby
+storage = DSPy::Storage::ProgramStorage.new(storage_path: "./dspy_storage")
+storage.save_program(result.optimized_program, result, metadata: { optimizer: 'MIPROv2' })
 ```
 
-**Custom monitoring**:
-- Token tracking
-- Performance monitoring
-- Error rate tracking
-- Custom logging
+Supports checkpoint management, optimization history tracking, and import/export between environments.
 
-**Full documentation**: See `references/optimization.md` section on Observability.
+## Rails Integration
 
-## Quick Start Workflow
+### Directory Structure
 
-### For New Projects
+Organize DSPy components using Rails conventions:
 
-1. **Install DSPy.rb and provider gems**:
-```bash
-gem install dspy dspy-openai  # or dspy-anthropic, dspy-gemini
 ```
+app/
+  entities/          # T::Struct types shared across signatures
+  signatures/        # DSPy::Signature definitions
+  tools/             # DSPy::Tools::Base implementations
+    concerns/        # Shared tool behaviors (error handling, etc.)
+  modules/           # DSPy::Module orchestrators
+  services/          # Plain Ruby services that compose DSPy modules
+config/
+  initializers/
+    dspy.rb          # DSPy + provider configuration
+    feature_flags.rb # Model selection per role
+spec/
+  signatures/        # Schema validation tests
+  tools/             # Tool unit tests
+  modules/           # Integration tests with VCR
+  vcr_cassettes/     # Recorded HTTP interactions
+```
+
+### Initializer
 
-2. **Configure LLM provider** (see `assets/config-template.rb`):
 ```ruby
-require 'dspy'
+# config/initializers/dspy.rb
+Rails.application.config.after_initialize do
+  next if Rails.env.test? && ENV["DSPY_ENABLE_IN_TEST"].blank?
+
+  RubyLLM.configure do |config|
+    config.gemini_api_key = ENV["GEMINI_API_KEY"] if ENV["GEMINI_API_KEY"].present?
+    config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"] if ENV["ANTHROPIC_API_KEY"].present?
+    config.openai_api_key = ENV["OPENAI_API_KEY"] if ENV["OPENAI_API_KEY"].present?
+  end
 
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
-    api_key: ENV['OPENAI_API_KEY'])
+  model = ENV.fetch("DSPY_MODEL", "ruby_llm/gemini-2.5-flash")
+  DSPy.configure do |config|
+    config.lm = DSPy::LM.new(model, structured_outputs: true)
+    config.logger = Rails.logger
+  end
+
+  # Langfuse observability (optional)
+  if ENV["LANGFUSE_PUBLIC_KEY"].present? && ENV["LANGFUSE_SECRET_KEY"].present?
+    DSPy::Observability.configure!
+  end
 end
 ```
 
-3. **Create a signature** (see `assets/signature-template.rb`):
+### Feature-Flagged Model Selection
+
+Use different models for different roles (fast/cheap for classification, powerful for synthesis):
+
 ```ruby
-class MySignature < DSPy::Signature
-  description "Clear description of task"
+# config/initializers/feature_flags.rb
+module FeatureFlags
+  SELECTOR_MODEL = ENV.fetch("DSPY_SELECTOR_MODEL", "ruby_llm/gemini-2.5-flash-lite")
+  SYNTHESIZER_MODEL = ENV.fetch("DSPY_SYNTHESIZER_MODEL", "ruby_llm/gemini-2.5-flash")
+end
+```
 
-  input do
-    const :input_field, String, desc: "Description"
-  end
+Then override per-tool or per-predictor:
 
-  output do
-    const :output_field, String, desc: "Description"
+```ruby
+class ClassifyTool < DSPy::Tools::Base
+  def call(query:)
+    predictor = DSPy::Predict.new(ClassifyQuery)
+    predictor.configure { |c| c.lm = DSPy::LM.new(FeatureFlags::SELECTOR_MODEL, structured_outputs: true) }
+    predictor.call(query: query)
   end
 end
 ```
 
-4. **Create a module** (see `assets/module-template.rb`):
+## Schema-Driven Signatures
+
+**Prefer typed schemas over string descriptions.** Let the type system communicate structure to the LLM rather than prose in the signature description.
+
+### Entities as Shared Types
+
+Define reusable `T::Struct` and `T::Enum` types in `app/entities/` and reference them across signatures:
+
 ```ruby
-class MyModule < DSPy::Module
-  def initialize
-    super
-    @predictor = DSPy::Predict.new(MySignature)
+# app/entities/search_strategy.rb
+class SearchStrategy < T::Enum
+  enums do
+    SingleSearch = new("single_search")
+    DateDecomposition = new("date_decomposition")
   end
+end
 
-  def forward(input_field:)
-    @predictor.forward(input_field: input_field)
-  end
+# app/entities/scored_item.rb
+class ScoredItem < T::Struct
+  const :id, String
+  const :score, Float, description: "Relevance score 0.0-1.0"
+  const :verdict, String, description: "relevant, maybe, or irrelevant"
+  const :reason, String, default: ""
 end
 ```
 
-5. **Use the module**:
+### Schema vs Description: When to Use Each
+
+**Use schemas (T::Struct/T::Enum)** for:
+- Multi-field outputs with specific types
+- Enums with defined values the LLM must pick from
+- Nested structures, arrays of typed objects
+- Outputs consumed by code (not displayed to users)
+
+**Use string descriptions** for:
+- Simple single-field outputs where the type is `String`
+- Natural language generation (summaries, answers)
+- Fields where constraint guidance helps (e.g., `description: "YYYY-MM-DD format"`)
+
+**Rule of thumb**: If you'd write a `case` statement on the output, it should be a `T::Enum`. If you'd call `.each` on it, it should be `T::Array[SomeStruct]`.
+
+## Tool Patterns
+
+### Tools That Wrap Predictions
+
+A common pattern: tools encapsulate a DSPy prediction, adding error handling, model selection, and serialization:
+
 ```ruby
-module_instance = MyModule.new
-result = module_instance.forward(input_field: "test")
-puts result[:output_field]
+class RerankTool < DSPy::Tools::Base
+  tool_name "rerank"
+  tool_description "Score and rank search results by relevance"
+
+  MAX_ITEMS = 200
+  MIN_ITEMS_FOR_LLM = 5
+
+  sig { params(query: String, items: T::Array[T::Hash[Symbol, T.untyped]]).returns(T::Hash[Symbol, T.untyped]) }
+  def call(query:, items: [])
+    return { scored_items: items, reranked: false } if items.size < MIN_ITEMS_FOR_LLM
+
+    capped_items = items.first(MAX_ITEMS)
+    predictor = DSPy::Predict.new(RerankSignature)
+    predictor.configure { |c| c.lm = DSPy::LM.new(FeatureFlags::SYNTHESIZER_MODEL, structured_outputs: true) }
+
+    result = predictor.call(query: query, items: capped_items)
+    { scored_items: result.scored_items, reranked: true }
+  rescue => e
+    Rails.logger.warn "[RerankTool] LLM rerank failed: #{e.message}"
+    { error: "Rerank failed: #{e.message}", scored_items: items, reranked: false }
+  end
+end
 ```
 
-6. **Add tests** (see `references/optimization.md`):
+**Key patterns:**
+- Short-circuit LLM calls when unnecessary (small data, trivial cases)
+- Cap input size to prevent token overflow
+- Per-tool model selection via `configure`
+- Graceful error handling with fallback data
+
+### Error Handling Concern
+
 ```ruby
-RSpec.describe MyModule do
-  it 'produces expected output' do
-    result = MyModule.new.forward(input_field: "test")
-    expect(result[:output_field]).to be_a(String)
+module ErrorHandling
+  extend ActiveSupport::Concern
+
+  private
+
+  def safe_predict(signature_class, **inputs)
+    predictor = DSPy::Predict.new(signature_class)
+    yield predictor if block_given?
+    predictor.call(**inputs)
+  rescue Faraday::Error, Net::HTTPError => e
+    Rails.logger.error "[#{self.class.name}] API error: #{e.message}"
+    nil
+  rescue JSON::ParserError => e
+    Rails.logger.error "[#{self.class.name}] Invalid LLM output: #{e.message}"
+    nil
   end
 end
 ```
 
-### For Rails Applications
+## Observability
+
+### Tracing with DSPy::Context
+
+Wrap operations in spans for Langfuse/OpenTelemetry visibility:
 
-1. **Add to Gemfile**:
 ```ruby
-gem 'dspy'
-gem 'dspy-openai'  # or other provider
+result = DSPy::Context.with_span(
+  operation: "tool_selector.select",
+  "dspy.module" => "ToolSelector",
+  "tool_selector.tools" => tool_names.join(",")
+) do
+  @predictor.call(query: query, context: context, available_tools: schemas)
+end
 ```
 
-2. **Create initializer** at `config/initializers/dspy.rb` (see `assets/config-template.rb` for full example):
-```ruby
-require 'dspy'
+### Setup for Langfuse
 
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
-    api_key: ENV['OPENAI_API_KEY'])
-end
+```ruby
+# Gemfile
+gem 'dspy-o11y'
+gem 'dspy-o11y-langfuse'
+
+# .env
+LANGFUSE_PUBLIC_KEY=pk-...
+LANGFUSE_SECRET_KEY=sk-...
+DSPY_TELEMETRY_BATCH_SIZE=5
 ```
 
-3. **Create modules in** `app/llm/` directory:
+Every `DSPy::Predict`, `DSPy::ReAct`, and tool call is automatically traced when observability is configured.
+
+### Score Reporting
+
+Report evaluation scores to Langfuse:
+
 ```ruby
-# app/llm/email_classifier.rb
-class EmailClassifier < DSPy::Module
-  # Implementation here
-end
+DSPy.score(name: "relevance", value: 0.85, trace_id: current_trace_id)
 ```
 
-4. **Use in controllers/services**:
+## Testing
+
+### VCR Setup for Rails
+
 ```ruby
-class EmailsController < ApplicationController
-  def classify
-    classifier = EmailClassifier.new
-    result = classifier.forward(
-      email_subject: params[:subject],
-      email_body: params[:body]
-    )
-    render json: result
-  end
+VCR.configure do |config|
+  config.cassette_library_dir = "spec/vcr_cassettes"
+  config.hook_into :webmock
+  config.configure_rspec_metadata!
+  config.filter_sensitive_data('<GEMINI_API_KEY>') { ENV['GEMINI_API_KEY'] }
+  config.filter_sensitive_data('<OPENAI_API_KEY>') { ENV['OPENAI_API_KEY'] }
 end
 ```
 
-## Common Patterns
+### Signature Schema Tests
 
-### Pattern: Multi-Step Analysis Pipeline
+Test that signatures produce valid schemas without calling any LLM:
 
 ```ruby
-class AnalysisPipeline < DSPy::Module
-  def initialize
-    super
-    @extract = DSPy::Predict.new(ExtractSignature)
-    @analyze = DSPy::ChainOfThought.new(AnalyzeSignature)
-    @summarize = DSPy::Predict.new(SummarizeSignature)
+RSpec.describe ClassifyResearchQuery do
+  it "has required input fields" do
+    schema = described_class.input_json_schema
+    expect(schema[:required]).to include("query")
   end
 
-  def forward(text:)
-    extracted = @extract.forward(text: text)
-    analyzed = @analyze.forward(data: extracted[:data])
-    @summarize.forward(analysis: analyzed[:result])
+  it "has typed output fields" do
+    schema = described_class.output_json_schema
+    expect(schema[:properties]).to have_key(:search_strategy)
   end
 end
 ```
 
-### Pattern: Agent with Tools
+### Tool Tests with Mocked Predictions
 
 ```ruby
-class ResearchAgent < DSPy::Module
-  def initialize
-    super
-    @agent = DSPy::ReAct.new(
-      ResearchSignature,
-      tools: [
-        WebSearchTool.new,
-        DatabaseQueryTool.new,
-        SummarizerTool.new
-      ],
-      max_iterations: 10
-    )
-  end
+RSpec.describe RerankTool do
+  let(:tool) { described_class.new }
 
-  def forward(question:)
-    @agent.forward(question: question)
+  it "skips LLM for small result sets" do
+    expect(DSPy::Predict).not_to receive(:new)
+    result = tool.call(query: "test", items: [{ id: "1" }])
+    expect(result[:reranked]).to be false
   end
-end
 
-class WebSearchTool < DSPy::Tool
-  def call(query:)
-    results = perform_search(query)
-    { results: results }
+  it "calls LLM for large result sets", :vcr do
+    items = 10.times.map { |i| { id: i.to_s, title: "Item #{i}" } }
+    result = tool.call(query: "relevant items", items: items)
+    expect(result[:reranked]).to be true
   end
 end
 ```
 
-### Pattern: Conditional Routing
+## Resources
+
+- [core-concepts.md](./references/core-concepts.md) — Signatures, modules, predictors, type system deep-dive
+- [toolsets.md](./references/toolsets.md) — Tools::Base, Tools::Toolset DSL, type safety, testing
+- [providers.md](./references/providers.md) — Provider adapters, RubyLLM, fiber-local LM context, compatibility matrix
+- [optimization.md](./references/optimization.md) — MIPROv2, GEPA, evaluation framework, storage system
+- [observability.md](./references/observability.md) — Event system, dspy-o11y gems, Langfuse, score reporting
+- [signature-template.rb](./assets/signature-template.rb) — Signature scaffold with T::Enum, Date/Time, defaults, union types
+- [module-template.rb](./assets/module-template.rb) — Module scaffold with .call(), lifecycle callbacks, fiber-local LM
+- [config-template.rb](./assets/config-template.rb) — Rails initializer with RubyLLM, observability, feature flags
+
+## Key URLs
+
+- Homepage: https://oss.vicente.services/dspy.rb/
+- GitHub: https://github.com/vicentereig/dspy.rb
+- Documentation: https://oss.vicente.services/dspy.rb/getting-started/
+
+## Guidelines for Claude
+
+When helping users with DSPy.rb:
+
+1. **Schema over prose** — Define output structure with `T::Struct` and `T::Enum` types, not string descriptions
+2. **Entities in `app/entities/`** — Extract shared types so signatures stay thin
+3. **Per-tool model selection** — Use `predictor.configure { |c| c.lm = ... }` to pick the right model per task
+4. **Short-circuit LLM calls** — Skip the LLM for trivial cases (small data, cached results)
+5. **Cap input sizes** — Prevent token overflow by limiting array sizes before sending to LLM
+6. **Test schemas without LLM** — Validate `input_json_schema` and `output_json_schema` in unit tests
+7. **VCR for integration tests** — Record real HTTP interactions, never mock LLM responses by hand
+8. **Trace with spans** — Wrap tool calls in `DSPy::Context.with_span` for observability
+9. **Graceful degradation** — Always rescue LLM errors and return fallback data
+
+### Signature Best Practices
+
+**Keep description concise** — The signature `description` should state the goal, not the field details:
 
 ```ruby
-class SmartRouter < DSPy::Module
-  def initialize
-    super
-    @classifier = DSPy::Predict.new(ClassifySignature)
-    @simple_handler = SimpleModule.new
-    @complex_handler = ComplexModule.new
-  end
+# Good — concise goal
+class ParseOutline < DSPy::Signature
+  description 'Extract block-level structure from HTML as a flat list of skeleton sections.'
 
-  def forward(input:)
-    classification = @classifier.forward(text: input)
+  input do
+    const :html, String, description: 'Raw HTML to parse'
+  end
 
-    if classification[:complexity] == 'Simple'
-      @simple_handler.forward(input: input)
-    else
-      @complex_handler.forward(input: input)
-    end
+  output do
+    const :sections, T::Array[Section], description: 'Block elements: headings, paragraphs, code blocks, lists'
   end
 end
 ```
 
-### Pattern: Retry with Fallback
+**Use defaults over nilable arrays** — For OpenAI structured outputs compatibility:
 
 ```ruby
-class RobustModule < DSPy::Module
-  MAX_RETRIES = 3
-
-  def forward(input, retry_count: 0)
-    begin
-      @predictor.forward(input)
-    rescue DSPy::ValidationError => e
-      if retry_count < MAX_RETRIES
-        sleep(2 ** retry_count)
-        forward(input, retry_count: retry_count + 1)
-      else
-        # Fallback to default or raise
-        raise
-      end
-    end
-  end
+# Good — works with OpenAI structured outputs
+class ASTNode < T::Struct
+  const :children, T::Array[ASTNode], default: []
 end
 ```
 
-## Resources
+### Recursive Types with `$defs`
+
+DSPy.rb supports recursive types in structured outputs using JSON Schema `$defs`:
+
+```ruby
+class TreeNode < T::Struct
+  const :value, String
+  const :children, T::Array[TreeNode], default: []  # Self-reference
+end
+```
 
-This skill includes comprehensive reference materials and templates:
+The schema generator automatically creates `#/$defs/TreeNode` references for recursive types, compatible with OpenAI and Gemini structured outputs.
 
-### References (load as needed for detailed information)
+### Field Descriptions for T::Struct
 
-- [core-concepts.md](./references/core-concepts.md): Complete guide to signatures, modules, predictors, multimodal support, and best practices
-- [providers.md](./references/providers.md): All LLM provider configurations, compatibility matrix, cost optimization, and troubleshooting
-- [optimization.md](./references/optimization.md): Testing patterns, optimization techniques, observability setup, and monitoring
+DSPy.rb extends T::Struct to support field-level `description:` kwargs that flow to JSON Schema:
 
-### Assets (templates for quick starts)
+```ruby
+class ASTNode < T::Struct
+  const :node_type, NodeType, description: 'The type of node (heading, paragraph, etc.)'
+  const :text, String, default: "", description: 'Text content of the node'
+  const :level, Integer, default: 0  # No description — field is self-explanatory
+  const :children, T::Array[ASTNode], default: []
+end
+```
 
-- [signature-template.rb](./assets/signature-template.rb): Examples of signatures including basic, vision, sentiment analysis, and code generation
-- [module-template.rb](./assets/module-template.rb): Module patterns including pipelines, agents, error handling, caching, and state management
-- [config-template.rb](./assets/config-template.rb): Configuration examples for all providers, environments, observability, and production patterns
+**When to use field descriptions**: complex field semantics, enum-like strings, constrained values, nested structs with ambiguous names. **When to skip**: self-explanatory fields like `name`, `id`, `url`, or boolean flags.
 
-## When to Use This Skill
+## Version
 
-Trigger this skill when:
-- Implementing LLM-powered features in Ruby applications
-- Creating type-safe interfaces for AI operations
-- Building agent systems with tool usage
-- Setting up or troubleshooting LLM providers
-- Optimizing prompts and improving accuracy
-- Testing LLM functionality
-- Adding observability to AI applications
-- Converting from manual prompt engineering to programmatic approach
-- Debugging DSPy.rb code or configuration issues
+Current: 0.34.3