dspy-code_act 0.29.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b678ef45c8a1fef48c4144a37ab650d16c5b80f0d32df00cc88e5dd6e1929184
+  data.tar.gz: 0e7c257bd9eac064e4be71fbc83f79fc306da6526ce938fd465d6bc0cb4303ce
+SHA512:
+  metadata.gz: 529801091e676b46348fa21e5635cd8ca4fd35a5aada9d08e459768e122d876f0b657765ffc4d62429b7876545bd6de9d32fb8c3b59bba238a8f97b585fa6d53
+  data.tar.gz: 25eccebf8fc46fdd5a91ecf1d7c5226d91ab63902f64441359376830828a0229b2844e9202ca0b048abb2aeaa690e20144743300f33cdf5339ebe6c7ce79a1b6

data/LICENSE

@@ -0,0 +1,45 @@
+MIT License
+
+Copyright (c) 2025 Vicente Services SL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This project is a Ruby port of the original Python [DSPy library](https://github.com/stanfordnlp/dspy), which is licensed under the MIT License:
+
+MIT License
+
+Copyright (c) 2023 Stanford Future Data Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,249 @@
+# DSPy.rb
+
+[![Gem Version](https://img.shields.io/gem/v/dspy)](https://rubygems.org/gems/dspy)
+[![Total Downloads](https://img.shields.io/gem/dt/dspy)](https://rubygems.org/gems/dspy)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/vicentereig/dspy.rb/ruby.yml?branch=main&label=build)](https://github.com/vicentereig/dspy.rb/actions/workflows/ruby.yml)
+[![Documentation](https://img.shields.io/badge/docs-vicentereig.github.io%2Fdspy.rb-blue)](https://vicentereig.github.io/dspy.rb/)
+
+> [!NOTE]
+> The core Prompt Engineering Framework is production-ready with
+> comprehensive documentation. I am focusing now on educational content on systematic Prompt Optimization and Context Engineering.
+> Your feedback is invaluable. if you encounter issues, please open an [issue](https://github.com/vicentereig/dspy.rb/issues). If you have suggestions, open a [new thread](https://github.com/vicentereig/dspy.rb/discussions).  
+> 
+> If you want to contribute, feel free to reach out to me to coordinate efforts: hey at vicente.services
+>
+> And, yes, this is 100% a legit project. :) 
+
+
+**Build reliable LLM applications in idiomatic Ruby using composable, type-safe modules.**
+
+The Ruby framework for programming with large language models. DSPy.rb brings structured LLM programming to Ruby developers, programmatic Prompt Engineering and Context Engineering. 
+Instead of wrestling with prompt strings and parsing responses, you define typed signatures using idiomatic Ruby to compose and decompose AI Worklows and AI Agents.
+
+**Prompts are the just Functions.** Traditional prompting is like writing code with string concatenation: it works until it doesn't. DSPy.rb brings you 
+the programming approach pioneered by [dspy.ai](https://dspy.ai/): instead of crafting fragile prompts, you define modular 
+signatures and let the framework handle the messy details.
+
+DSPy.rb is an idiomatic Ruby surgical port of Stanford's [DSPy framework](https://github.com/stanfordnlp/dspy). While implementing 
+the core concepts of signatures, predictors, and the main optimization algorithms from the original Python library, DSPy.rb embraces Ruby 
+conventions and adds Ruby-specific innovations like Sorbet-base Typed system, ReAct loops, and production-ready integrations like non-blocking Open Telemetry Instrumentation.
+
+**What you get?** Ruby LLM applications that actually scale and don't break when you sneeze.
+
+Check the [examples](examples/) and take them for a spin!
+
+## Your First DSPy Program
+### Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'dspy'
+```
+
+and
+
+```bash
+bundle install
+```
+### Your First Reliable Predictor
+
+```ruby
+
+# Configure DSPy globablly to use your fave LLM - you can override this on an instance levle. 
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
+                      api_key: ENV['OPENAI_API_KEY'],
+                      structured_outputs: true)  # Enable OpenAI's native JSON mode
+end
+
+# Define a signature for sentiment classification - instead of writing a full prompt!
+class Classify < DSPy::Signature
+  description "Classify sentiment of a given sentence." # sets the goal of the underlying prompt
+
+  class Sentiment < T::Enum
+    enums do
+      Positive = new('positive')
+      Negative = new('negative')
+      Neutral = new('neutral')
+    end
+  end
+  
+  # Structured Inputs: makes sure you are sending only valid prompt inputs to your model
+  input do
+    const :sentence, String, description: 'The sentence to analyze'
+  end
+
+  # Structured Outputs: your predictor will validate the output of the model too.
+  output do
+    const :sentiment, Sentiment, description: 'The sentiment of the sentence'
+    const :confidence, Float, description: 'A number between 0.0 and 1.0'
+  end
+end
+
+# Wire it to the simplest prompting technique - a Predictn.
+classify = DSPy::Predict.new(Classify)
+# it may raise an error if you mess the inputs or your LLM messes the outputs.
+result = classify.call(sentence: "This book was super fun to read!")
+
+puts result.sentiment    # => #<Sentiment::Positive>  
+puts result.confidence   # => 0.85
+```
+
+### Access to 200+ Models Across 5 Providers
+
+DSPy.rb provides unified access to major LLM providers with provider-specific optimizations:
+
+```ruby
+# OpenAI (GPT-4, GPT-4o, GPT-4o-mini, GPT-5, etc.)
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
+                      api_key: ENV['OPENAI_API_KEY'],
+                      structured_outputs: true)  # Native JSON mode
+end
+
+# Google Gemini (Gemini 1.5 Pro, Flash, Gemini 2.0, etc.)
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('gemini/gemini-2.5-flash',
+                      api_key: ENV['GEMINI_API_KEY'],
+                      structured_outputs: true)  # Native structured outputs
+end
+
+# Anthropic Claude (Claude 3.5, Claude 4, etc.)
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('anthropic/claude-sonnet-4-5-20250929',
+                      api_key: ENV['ANTHROPIC_API_KEY'],
+                      structured_outputs: true)  # Tool-based extraction (default)
+end
+
+# Ollama - Run any local model (Llama, Mistral, Gemma, etc.)
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('ollama/llama3.2')  # Free, runs locally, no API key needed
+end
+
+# OpenRouter - Access to 200+ models from multiple providers
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('openrouter/deepseek/deepseek-chat-v3.1:free',
+                      api_key: ENV['OPENROUTER_API_KEY'])
+end
+```
+
+## What You Get
+
+**Developer Experience:**
+- LLM provider support using official Ruby clients:
+  - [OpenAI Ruby](https://github.com/openai/openai-ruby) with vision model support
+  - [Anthropic Ruby SDK](https://github.com/anthropics/anthropic-sdk-ruby) with multimodal capabilities
+  - [Google Gemini API](https://ai.google.dev/) with native structured outputs
+  - [Ollama](https://ollama.com/) via OpenAI compatibility layer for local models
+- **Multimodal Support** - Complete image analysis with DSPy::Image, type-safe bounding boxes, vision-capable models
+- Runtime type checking with [Sorbet](https://sorbet.org/) including T::Enum and union types
+- Type-safe tool definitions for ReAct agents
+- Comprehensive instrumentation and observability
+
+**Core Building Blocks:**
+- **Signatures** - Define input/output schemas using Sorbet types with T::Enum and union type support
+- **Predict** - LLM completion with structured data extraction and multimodal support
+- **Chain of Thought** - Step-by-step reasoning for complex problems with automatic prompt optimization
+- **ReAct** - Tool-using agents with type-safe tool definitions and error recovery
+- **Module Composition** - Combine multiple LLM calls into production-ready workflows
+
+**Optimization & Evaluation:**
+- **Prompt Objects** - Manipulate prompts as first-class objects instead of strings
+- **Typed Examples** - Type-safe training data with automatic validation
+- **Evaluation Framework** - Advanced metrics beyond simple accuracy with error-resilient pipelines
+- **MIPROv2 Optimization** - Advanced Bayesian optimization with Gaussian Processes, multiple optimization strategies, auto-config presets, and storage persistence
+
+**Production Features:**
+- **Reliable JSON Extraction** - Native structured outputs for OpenAI and Gemini, Anthropic tool-based extraction, and automatic strategy selection with fallback
+- **Type-Safe Configuration** - Strategy enums with automatic provider optimization (Strict/Compatible modes)
+- **Smart Retry Logic** - Progressive fallback with exponential backoff for handling transient failures
+- **Zero-Config Langfuse Integration** - Set env vars and get automatic OpenTelemetry traces in Langfuse
+- **Performance Caching** - Schema and capability caching for faster repeated operations
+- **File-based Storage** - Optimization result persistence with versioning
+- **Structured Logging** - JSON and key=value formats with span tracking
+
+## Recent Achievements
+
+DSPy.rb has rapidly evolved from experimental to production-ready:
+
+### Foundation
+- ✅ **JSON Parsing Reliability** - Native OpenAI structured outputs with adaptive retry logic and schema-aware fallbacks
+- ✅ **Type-Safe Strategy Configuration** - Provider-optimized strategy selection and enum-backed optimizer presets
+- ✅ **Core Module System** - Predict, ChainOfThought, ReAct with type safety (add `dspy-code_act` for Think-Code-Observe agents)
+- ✅ **Production Observability** - OpenTelemetry, New Relic, and Langfuse integration
+- ✅ **Advanced Optimization** - MIPROv2 with Bayesian optimization, Gaussian Processes, and multi-mode search
+
+### Recent Advances
+- ✅ **MIPROv2 ADE Integrity (v0.29.1)** - Stratified train/val/test splits, honest precision accounting, and enum-driven `--auto` presets with integration coverage
+- ✅ **Instruction Deduplication (v0.29.1)** - Candidate generation now filters repeated programs so optimization logs highlight unique strategies
+- ✅ **GEPA Teleprompter (v0.29.0)** - Genetic-Pareto reflective prompt evolution with merge proposer scheduling, reflective mutation, and ADE demo parity
+- ✅ **Optimizer Utilities Parity (v0.29.0)** - Bootstrap strategies, dataset summaries, and Layer 3 utilities unlock multi-predictor programs on Ruby
+- ✅ **Observability Hardening (v0.29.0)** - OTLP exporter runs on a single-thread executor preventing frozen SSL contexts without blocking spans
+- ✅ **Documentation Refresh (v0.29.x)** - New GEPA guide plus ADE optimization docs covering presets, stratified splits, and error-handling defaults
+
+**Current Focus Areas:**
+
+### Production Readiness
+- 🚧 **Production Patterns** - Real-world usage validation and performance optimization
+- 🚧 **Ruby Ecosystem Integration** - Rails integration, Sidekiq compatibility, deployment patterns
+
+### Community & Adoption
+- 🚧 **Community Examples** - Real-world applications and case studies
+- 🚧 **Contributor Experience** - Making it easier to contribute and extend
+- 🚧 **Performance Benchmarks** - Comparative analysis vs other frameworks
+
+**v1.0 Philosophy:**
+v1.0 will be released after extensive production battle-testing, not after checking off features.
+The API is already stable - v1.0 represents confidence in production reliability backed by real-world validation.
+
+
+## Documentation
+
+📖 **[Complete Documentation Website](https://vicentereig.github.io/dspy.rb/)**
+
+### LLM-Friendly Documentation
+
+For LLMs and AI assistants working with DSPy.rb:
+- **[llms.txt](https://vicentereig.github.io/dspy.rb/llms.txt)** - Concise reference optimized for LLMs
+- **[llms-full.txt](https://vicentereig.github.io/dspy.rb/llms-full.txt)** - Comprehensive API documentation
+
+### Getting Started
+- **[Installation & Setup](docs/src/getting-started/installation.md)** - Detailed installation and configuration
+- **[Quick Start Guide](docs/src/getting-started/quick-start.md)** - Your first DSPy programs
+- **[Core Concepts](docs/src/getting-started/core-concepts.md)** - Understanding signatures, predictors, and modules
+
+### Prompt Engineering
+- **[Signatures & Types](docs/src/core-concepts/signatures.md)** - Define typed interfaces for LLM operations
+- **[Predictors](docs/src/core-concepts/predictors.md)** - Predict, ChainOfThought, ReAct, and more
+- **[Modules & Pipelines](docs/src/core-concepts/modules.md)** - Compose complex multi-stage workflows
+- **[Multimodal Support](docs/src/core-concepts/multimodal.md)** - Image analysis with vision-capable models
+- **[Examples & Validation](docs/src/core-concepts/examples.md)** - Type-safe training data
+- **[Rich Types](docs/src/advanced/complex-types.md)** - Sorbet type integration with automatic coercion for structs, enums, and arrays
+- **[Composable Pipelines](docs/src/advanced/pipelines.md)** - Manual module composition patterns
+
+### Prompt Optimization
+- **[Evaluation Framework](docs/src/optimization/evaluation.md)** - Advanced metrics beyond simple accuracy
+- **[Prompt Optimization](docs/src/optimization/prompt-optimization.md)** - Manipulate prompts as objects
+- **[MIPROv2 Optimizer](docs/src/optimization/miprov2.md)** - Advanced Bayesian optimization with Gaussian Processes
+- **[GEPA Optimizer](docs/src/optimization/gepa.md)** *(beta)* - Reflective mutation with optional reflection LMs
+
+### Context Engineering
+- **[Tools](docs/src/core-concepts/toolsets.md)** - Tool wieldint agents.
+- **[Agentic Memory](docs/src/core-concepts/memory.md)** - Memory Tools & Agentic Loops
+- **[RAG Patterns](docs/src/advanced/rag.md)** - Manual RAG implementation with external services
+
+### Production Features
+- **[Observability](docs/src/production/observability.md)** - Zero-config Langfuse integration with a dedicated export worker that never blocks your LLMs
+- **[Storage System](docs/src/production/storage.md)** - Persistence and optimization result storage
+- **[Custom Metrics](docs/src/advanced/custom-metrics.md)** - Proc-based evaluation logic 
+
+
+
+
+
+
+
+
+## License
+This project is licensed under the MIT License.

data/lib/dspy/code_act/README.md

@@ -0,0 +1,152 @@
+# CodeAct: Dynamic Code Generation for DSPy.rb
+
+CodeAct is a DSPy.rb module that enables agents to write and execute Ruby code dynamically. Unlike ReAct agents that rely on predefined tools, CodeAct generates tailored Ruby code on the fly to solve complex tasks.
+
+## When to Use CodeAct
+
+- Choose CodeAct when you need creative problem solving, custom data transformations, or bespoke algorithms.
+- Prefer ReAct when you have well-defined tools, must call external services, or need stricter safety guarantees.
+
+## Quick Start
+
+```ruby
+require 'dspy'
+require 'dspy/code_act'
+
+DSPy.configure do |config|
+  config.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV.fetch('OPENAI_API_KEY'))
+end
+
+agent = DSPy::CodeAct.new
+
+result = agent.forward(
+  task: "Calculate the Fibonacci sequence up to the 10th number",
+  context: "You have access to standard Ruby libraries"
+)
+
+puts result.final_answer
+# => [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
+
+result.history.each do |step|
+  puts "Step #{step.step}"
+  puts "Thought: #{step.thought}"
+  puts "Code: #{step.ruby_code}"
+  puts "Result: #{step.execution_result}"
+end
+```
+
+## Advanced Usage
+
+### Custom Execution Context
+
+Provide structured data or helper methods with the `context` argument so generated code can reference them:
+
+```ruby
+sales_data = {
+  "January" => [100, 150, 200],
+  "February" => [120, 180, 190],
+  "March" => [140, 210, 220]
+}
+
+agent = DSPy::CodeAct.new
+
+result = agent.forward(
+  task: "Calculate the average sales for each month and report the best performer",
+  context: "You have access to `sales_data`, a hash keyed by month with numeric arrays",
+  data: { sales_data: sales_data }
+)
+
+puts result.final_answer
+# => "March is the best performing month with an average of 190.0"
+```
+
+### Arbitrary Data Processing
+
+```ruby
+csv_content = <<~CSV
+  name,email,department
+  John Doe,john@gmail.com,Engineering
+  Jane Smith,jane@company.com,Marketing
+  Bob Johnson,bob@gmail.com,Sales
+CSV
+
+result = agent.forward(
+  task: "Parse the CSV data and list gmail.com addresses",
+  context: "CSV data is available in `csv_content`",
+  data: { csv_content: csv_content }
+)
+```
+
+## Safety Checklist
+
+Executing arbitrary Ruby code is powerful but risky. Consider:
+
+1. **Sandboxing & Timeouts** – wrap execution in `Timeout.timeout` and restrict accessible objects.
+2. **Input Sanitization** – scrub user input to remove shell-outs and dangerous methods.
+3. **Resource Monitoring** – track memory and CPU usage to abort runaway code.
+
+```ruby
+class SafeCodeAct < DSPy::CodeAct
+  def execute_code(ruby_code)
+    Timeout.timeout(5) { super }
+  rescue Timeout::Error
+    "Code execution timed out"
+  end
+end
+```
+
+## Example: Sales Analysis Pipeline
+
+```ruby
+class SalesAnalyzer < DSPy::Module
+  def initialize
+    @agent = DSPy::CodeAct.new
+  end
+
+  def analyze_trends(sales_data)
+    result = @agent.forward(
+      task: <<~TASK,
+        Analyze the sales data to:
+        1. Compute month-over-month growth
+        2. Identify seasonal patterns
+        3. Predict next month's sales with simple linear regression
+      TASK
+      context: "You have access to `sales_data` and standard Ruby libraries",
+      data: { sales_data: sales_data }
+    )
+
+    {
+      analysis: result.final_answer,
+      code_steps: result.history.map(&:ruby_code),
+      execution_time: result.metadata[:total_time]
+    }
+  end
+end
+```
+
+## Debugging
+
+Enable structured logging to observe each iteration:
+
+```ruby
+DSPy.configure do |config|
+  config.logger = Dry.Logger(:dspy, formatter: :json) do |logger|
+    logger.add_backend(level: :debug, stream: $stdout)
+  end
+end
+```
+
+Inspect `result.history` entry-by-entry to review generated code, observations, and errors.
+
+## Limitations & Roadmap
+
+- Basic sandboxing—do not run untrusted input without additional guards.
+- No support for external gem loading during execution.
+- Future roadmap targets hardened sandboxing, async execution, and richer explanations.
+
+## Best Practices
+
+1. Start with simple prompts before moving to complex tasks.
+2. Provide precise context and structured data for better code generation.
+3. Always validate outputs and enforce timeouts or resource caps.
+4. Capture telemetry (Observability, Langfuse) for production usage.

data/lib/dspy/code_act/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module DSPy
+  module CodeActVersion
+    VERSION = DSPy::VERSION
+  end
+end

data/lib/dspy/code_act.rb

@@ -0,0 +1,486 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require 'dspy' unless defined?(DSPy)
+require 'dspy/predict'
+require 'dspy/signature'
+require 'json'
+require 'stringio'
+require 'dspy/mixins/struct_builder'
+require 'dspy/type_serializer'
+
+module DSPy
+  # Define a simple struct for CodeAct history entries with proper type annotations
+  class CodeActHistoryEntry < T::Struct
+    const :step, Integer
+    prop :thought, T.nilable(String)
+    prop :ruby_code, T.nilable(String)
+    prop :execution_result, T.nilable(String)
+    prop :error_message, String
+
+    # Custom serialization to ensure compatibility with the rest of the code
+    def to_h
+      {
+        step: step,
+        thought: thought,
+        ruby_code: ruby_code,
+        execution_result: execution_result,
+        error_message: error_message
+      }.compact
+    end
+  end
+
+  # Defines the signature for Ruby code generation
+  class RubyCodeGeneration < DSPy::Signature
+    description "Generate Ruby code to solve the given task."
+
+    input do
+      const :task, String,
+        description: "JSON representation of all input fields for the task"
+      const :context, String,
+        description: "Available variables and previous results from code execution history"
+      const :history, T::Array[CodeActHistoryEntry],
+        description: "Previous thoughts and code executions with their results. Use this to understand what has been tried and what variables are available."
+    end
+
+    output do
+      const :thought, String,
+        description: "Reasoning about the approach to solve the task with Ruby code"
+      const :ruby_code, String,
+        description: "Ruby code to execute. This should be valid Ruby code that can be evaluated safely. Avoid system calls, file operations, or other potentially dangerous operations."
+      const :explanation, String,
+        description: "Brief explanation of what the code does and why this approach was chosen"
+    end
+  end
+
+  class CodeActNextStep < T::Enum
+    enums do
+      Continue = new("continue")
+      Finish = new("finish")
+    end
+  end
+
+  # Defines the signature for processing code execution results
+  class RubyCodeObservation < DSPy::Signature
+    description "Process the result of Ruby code execution and decide what to do next."
+
+    input do
+      const :task, String,
+        description: "JSON representation of all input fields for the task"
+      const :history, T::Array[CodeActHistoryEntry],
+        description: "Previous thoughts, code executions, and their results"
+      const :execution_result, T.nilable(String),
+        description: "The result from executing the Ruby code"
+      const :error_message, String,
+        description: "Error message if the code execution failed (empty string if no error)"
+    end
+
+    output do
+      const :observation, String,
+        description: "Analysis of the execution result and what it means for solving the task"
+      const :next_step, CodeActNextStep,
+        description: "What to do next: '#{CodeActNextStep::Continue}' to continue with more code or '#{CodeActNextStep::Finish}' if the task is complete"
+      const :final_answer, T.nilable(String),
+        description: "If next_step is 'finish', provide the final answer to the task based on the execution results"
+    end
+  end
+
+  # CodeAct Agent using Think-Code-Observe pattern
+  class CodeAct < Predict
+    extend T::Sig
+    include Mixins::StructBuilder
+
+    sig { returns(T.class_of(DSPy::Signature)) }
+    attr_reader :original_signature_class
+
+    sig { returns(T.class_of(T::Struct)) }
+    attr_reader :enhanced_output_struct
+
+    sig { returns(Integer) }
+    attr_reader :max_iterations
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    attr_reader :execution_context
+
+    sig { params(signature_class: T.class_of(DSPy::Signature), max_iterations: Integer).void }
+    def initialize(signature_class, max_iterations: 10)
+      @original_signature_class = signature_class
+      @max_iterations = max_iterations
+      @execution_context = T.let({}, T::Hash[Symbol, T.untyped])
+
+      # Create code generator using Predict to preserve field descriptions
+      @code_generator = T.let(DSPy::Predict.new(RubyCodeGeneration), DSPy::Predict)
+
+      # Create observation processor using Predict to preserve field descriptions
+      @observation_processor = T.let(DSPy::Predict.new(RubyCodeObservation), DSPy::Predict)
+
+      # Create enhanced output struct with CodeAct fields
+      @enhanced_output_struct = create_enhanced_output_struct(signature_class)
+      enhanced_output_struct = @enhanced_output_struct
+
+      # Create enhanced signature class
+      enhanced_signature = Class.new(DSPy::Signature) do
+        # Set the description
+        description signature_class.description
+
+        # Use the same input struct
+        @input_struct_class = signature_class.input_struct_class
+
+        # Use the enhanced output struct with CodeAct fields
+        @output_struct_class = enhanced_output_struct
+
+        # Store original signature name
+        @original_signature_name = signature_class.name
+
+        class << self
+          attr_reader :input_struct_class, :output_struct_class, :original_signature_name
+          
+          # Override name to return the original signature name
+          def name
+            @original_signature_name || super
+          end
+        end
+      end
+
+      # Call parent constructor with enhanced signature
+      super(enhanced_signature)
+    end
+
+    sig { override.returns(T::Array[[String, DSPy::Module]]) }
+    def named_predictors
+      pairs = T.let([], T::Array[[String, DSPy::Module]])
+      pairs << ["code_generator", @code_generator]
+      pairs << ["observation_processor", @observation_processor]
+      pairs
+    end
+
+    sig { override.returns(T::Array[DSPy::Module]) }
+    def predictors
+      named_predictors.map { |(_, predictor)| predictor }
+    end
+
+    sig { params(kwargs: T.untyped).returns(T.untyped).override }
+    def forward(**kwargs)
+      # Validate input and serialize all fields as task context
+      input_struct = @original_signature_class.input_struct_class.new(**kwargs)
+      task = DSPy::TypeSerializer.serialize(input_struct).to_json
+
+      # Execute CodeAct reasoning loop
+      reasoning_result = execute_codeact_reasoning_loop(task)
+
+      # Create enhanced output with all CodeAct data
+      create_enhanced_result(kwargs, reasoning_result)
+    end
+
+    private
+
+    # Executes the main CodeAct reasoning loop (Think-Code-Observe)
+    sig { params(task: String).returns(T::Hash[Symbol, T.untyped]) }
+    def execute_codeact_reasoning_loop(task)
+      history = T.let([], T::Array[CodeActHistoryEntry])
+      final_answer = T.let(nil, T.nilable(String))
+      iterations_count = 0
+      context = ""
+
+      while should_continue_iteration?(iterations_count, final_answer)
+        iterations_count += 1
+
+        iteration_result = execute_single_iteration(
+          task, history, context, iterations_count
+        )
+
+        if iteration_result[:should_finish]
+          final_answer = iteration_result[:final_answer]
+          break
+        end
+
+        history = iteration_result[:history]
+        context = iteration_result[:context]
+      end
+
+      handle_max_iterations_if_needed(iterations_count, final_answer, history)
+
+      {
+        history: history,
+        iterations: iterations_count,
+        final_answer: final_answer || default_no_answer_message,
+        execution_context: @execution_context
+      }
+    end
+
+    # Executes a single iteration of the Think-Code-Observe loop
+    sig { params(task: String, history: T::Array[CodeActHistoryEntry], context: String, iteration: Integer).returns(T::Hash[Symbol, T.untyped]) }
+    def execute_single_iteration(task, history, context, iteration)
+      DSPy::Context.with_span(
+        operation: 'codeact.iteration',
+        'dspy.module' => 'CodeAct',
+        'codeact.iteration' => iteration,
+        'codeact.max_iterations' => @max_iterations,
+        'codeact.history_length' => history.length
+      ) do
+        execution_state = execute_think_code_step(task, context, history, iteration)
+        
+        observation_decision = process_observation_and_decide_next_step(
+          task, execution_state[:history], execution_state[:execution_result], 
+          execution_state[:error_message], iteration
+        )
+
+        if observation_decision[:should_finish]
+          return { should_finish: true, final_answer: observation_decision[:final_answer] }
+        end
+
+        finalize_iteration(execution_state, iteration)
+      end
+    end
+
+    # Executes the Think-Code step: generates code and executes it
+    sig { params(task: String, context: String, history: T::Array[CodeActHistoryEntry], iteration: Integer).returns(T::Hash[Symbol, T.untyped]) }
+    def execute_think_code_step(task, context, history, iteration)
+      code_obj = @code_generator.forward(
+        task: task,
+        context: context.empty? ? "No previous context available." : context,
+        history: history
+      )
+
+      execution_result, error_message = execute_ruby_code_with_instrumentation(
+        code_obj.ruby_code, iteration
+      )
+
+      history << create_history_entry(
+        iteration, code_obj.thought, code_obj.ruby_code,
+        execution_result, error_message
+      )
+
+      {
+        history: history,
+        thought: code_obj.thought,
+        ruby_code: code_obj.ruby_code,
+        execution_result: execution_result,
+        error_message: error_message
+      }
+    end
+
+    # Finalizes iteration by updating context and emitting events
+    sig { params(execution_state: T::Hash[Symbol, T.untyped], iteration: Integer).returns(T::Hash[Symbol, T.untyped]) }
+    def finalize_iteration(execution_state, iteration)
+      new_context = build_context_from_history(execution_state[:history])
+
+      emit_iteration_complete_event(
+        iteration, execution_state[:thought], execution_state[:ruby_code],
+        execution_state[:execution_result], execution_state[:error_message]
+      )
+
+      {
+        should_finish: false,
+        history: execution_state[:history],
+        context: new_context
+      }
+    end
+
+    # Creates enhanced output struct with CodeAct-specific fields
+    sig { params(signature_class: T.class_of(DSPy::Signature)).returns(T.class_of(T::Struct)) }
+    def create_enhanced_output_struct(signature_class)
+      input_props = signature_class.input_struct_class.props
+      output_props = signature_class.output_struct_class.props
+
+      build_enhanced_struct(
+        { input: input_props, output: output_props },
+        {
+          history: [T::Array[T::Hash[Symbol, T.untyped]], "CodeAct execution history"],
+          iterations: [Integer, "Number of iterations executed"],
+          execution_context: [T::Hash[Symbol, T.untyped], "Variables and context from code execution"]
+        }
+      )
+    end
+
+    # Creates enhanced result struct
+    sig { params(input_kwargs: T::Hash[Symbol, T.untyped], reasoning_result: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
+    def create_enhanced_result(input_kwargs, reasoning_result)
+      output_field_name = @original_signature_class.output_struct_class.props.keys.first
+
+      output_data = input_kwargs.merge({
+        history: reasoning_result[:history].map(&:to_h),
+        iterations: reasoning_result[:iterations],
+        execution_context: reasoning_result[:execution_context]
+      })
+      output_data[output_field_name] = reasoning_result[:final_answer]
+
+      @enhanced_output_struct.new(**output_data)
+    end
+
+    # Helper methods for CodeAct logic
+    sig { params(iterations_count: Integer, final_answer: T.nilable(String)).returns(T::Boolean) }
+    def should_continue_iteration?(iterations_count, final_answer)
+      final_answer.nil? && (@max_iterations.nil? || iterations_count < @max_iterations)
+    end
+
+    sig { params(ruby_code: String, iteration: Integer).returns([T.nilable(String), String]) }
+    def execute_ruby_code_with_instrumentation(ruby_code, iteration)
+      DSPy::Context.with_span(
+        operation: 'codeact.code_execution',
+        'dspy.module' => 'CodeAct',
+        'codeact.iteration' => iteration,
+        'code.length' => ruby_code.length
+      ) do
+        execute_ruby_code_safely(ruby_code)
+      end
+    end
+
+    sig { params(step: Integer, thought: String, ruby_code: String, execution_result: T.nilable(String), error_message: String).returns(CodeActHistoryEntry) }
+    def create_history_entry(step, thought, ruby_code, execution_result, error_message)
+      CodeActHistoryEntry.new(
+        step: step,
+        thought: thought,
+        ruby_code: ruby_code,
+        execution_result: execution_result,
+        error_message: error_message
+      )
+    end
+
+    sig { params(task: String, history: T::Array[CodeActHistoryEntry], execution_result: T.nilable(String), error_message: String, iteration: Integer).returns(T::Hash[Symbol, T.untyped]) }
+    def process_observation_and_decide_next_step(task, history, execution_result, error_message, iteration)
+      observation_result = @observation_processor.forward(
+        task: task,
+        history: history,
+        execution_result: execution_result,
+        error_message: error_message
+      )
+
+      return { should_finish: false } unless observation_result.next_step == CodeActNextStep::Finish
+
+      final_answer = observation_result.final_answer || execution_result || "Task completed"
+
+      { should_finish: true, final_answer: final_answer }
+    end
+
+    sig { params(history: T::Array[CodeActHistoryEntry]).returns(String) }
+    def build_context_from_history(history)
+      context_parts = []
+      
+      history.each do |entry|
+        if entry.execution_result && !entry.execution_result.empty?
+          context_parts << "Step #{entry.step} result: #{entry.execution_result}"
+        end
+      end
+
+      context_parts.join("\n")
+    end
+
+    sig { params(iteration: Integer, thought: String, ruby_code: String, execution_result: T.nilable(String), error_message: T.nilable(String)).void }
+    def emit_iteration_complete_event(iteration, thought, ruby_code, execution_result, error_message)
+      DSPy.event('codeact.iteration_complete', {
+        'codeact.iteration' => iteration,
+        'codeact.thought' => thought,
+        'codeact.ruby_code' => ruby_code,
+        'codeact.execution_result' => execution_result,
+        'codeact.error_message' => error_message,
+        'codeact.success' => error_message.nil?
+      })
+    end
+
+    sig { params(iterations_count: Integer, final_answer: T.nilable(String), history: T::Array[CodeActHistoryEntry]).void }
+    def handle_max_iterations_if_needed(iterations_count, final_answer, history)
+      if iterations_count >= @max_iterations && final_answer.nil?
+        DSPy.event('codeact.max_iterations', {
+          'codeact.iteration_count' => iterations_count,
+          'codeact.max_iterations' => @max_iterations,
+          'codeact.final_history_length' => history.length
+        })
+      end
+    end
+
+    sig { returns(String) }
+    def default_no_answer_message
+      "No solution reached within #{@max_iterations} iterations"
+    end
+
+    # Safe Ruby code execution method - placeholder for now
+    sig { params(ruby_code: String).returns([T.nilable(String), String]) }
+    def execute_ruby_code_safely(ruby_code)
+      # TODO: Implement proper sandboxing in Phase 2
+      # For now, use basic eval with error handling
+      original_stdout = nil
+      captured_output = nil
+      
+      begin
+        # Capture stdout to get print/puts output
+        original_stdout = $stdout
+        captured_output = StringIO.new
+        $stdout = captured_output
+
+        result = eval(ruby_code, binding)
+        
+        # Get the captured output
+        output = captured_output.string
+        
+        # If there's captured output, use it, otherwise use the eval result
+        final_result = output.empty? ? result.to_s : output.chomp
+        
+        [final_result, ""]
+      rescue SyntaxError => e
+        [nil, "Error: #{e.message}"]
+      rescue => e
+        [nil, "Error: #{e.message}"]
+      ensure
+        $stdout = original_stdout if original_stdout
+      end
+    end
+
+    sig { params(output: T.untyped).void }
+    def validate_output_schema!(output)
+      # Validate that output is an instance of the enhanced output struct
+      unless output.is_a?(@enhanced_output_struct)
+        raise "Output must be an instance of #{@enhanced_output_struct}, got #{output.class}"
+      end
+
+      # Validate original signature output fields are present
+      @original_signature_class.output_struct_class.props.each do |field_name, _prop|
+        unless output.respond_to?(field_name)
+          raise "Missing required field: #{field_name}"
+        end
+      end
+
+      # Validate CodeAct-specific fields
+      unless output.respond_to?(:history) && output.history.is_a?(Array)
+        raise "Missing or invalid history field"
+      end
+
+      unless output.respond_to?(:iterations) && output.iterations.is_a?(Integer)
+        raise "Missing or invalid iterations field"
+      end
+
+      unless output.respond_to?(:execution_context) && output.execution_context.is_a?(Hash)
+        raise "Missing or invalid execution_context field"
+      end
+    end
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def generate_example_output
+      # Create a base example structure
+      example = {}
+      
+      # Add CodeAct-specific example data
+      example[:history] = [
+        {
+          step: 1,
+          thought: "I need to write Ruby code to solve this task...",
+          ruby_code: "result = 2 + 2",
+          execution_result: "4",
+          error_message: nil
+        }
+      ]
+      example[:iterations] = 1
+      example[:execution_context] = { result: 4 }
+      example
+    end
+  end
+end
+
+require_relative 'code_act/version'
+
+module DSPy
+  class CodeAct
+    VERSION = DSPy::CodeActVersion::VERSION unless const_defined?(:VERSION)
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: dspy-code_act
+version: !ruby/object:Gem::Version
+  version: 0.29.1
+platform: ruby
+authors:
+- Vicente Reig Rincón de Arellano
+bindir: bin
+cert_chain: []
+date: 2025-10-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dspy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.29.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.29.1
+description: CodeAct provides Think-Code-Observe agents that synthesize and execute
+  Ruby code dynamically. Ship DSPy.rb workflows that write custom Ruby code while
+  tracking execution history, observations, and safety signals.
+email:
+- hey@vicente.services
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/dspy/code_act.rb
+- lib/dspy/code_act/README.md
+- lib/dspy/code_act/version.rb
+homepage: https://github.com/vicentereig/dspy.rb
+licenses:
+- MIT
+metadata:
+  github_repo: git@github.com:vicentereig/dspy.rb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.5
+specification_version: 4
+summary: Dynamic code generation agents for DSPy.rb.
+test_files: []