dspy-code_act 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5b0506a94a331329847db4d8a8aa0e0f8e3dfb71171d41e4e10540fa0400645
-  data.tar.gz: 29681588c29708ec9a315edb46c6e4630707b051d915968ea365130270440809
+  metadata.gz: 1e81ad2629b9d652887180a6209dc803301c39a8989317907fd92e4b0bd08c40
+  data.tar.gz: 41f24b4c59be3ee80d3eaaa329fa0d4c1ded4b44ba62f337fd36328271cb886b
 SHA512:
-  metadata.gz: 142ec9519da18ef7f4fcc8e76dfca18398bd93f5b2e0ca05fb8ecbe50eabbb65dd8db29686bc31e0c33f59ca9fcc964b2de54e1c4b3f07f7cea1d0a560d6100c
-  data.tar.gz: cb18480490094769069058aa9fb30f04771532bd35fcaeba6df635567cc46641b696ec5a0aab1c9d6576c005095f3022456dc3456773ccaaaab8d681ee5bcd17
+  metadata.gz: 52355d8730ca9f9f3455bfc87e6fba782a934feece0ccc418cd1adec8c4bd597191cf9975c66afded7dbfb5c41bcbc751c1bee6c2c4e0d72b569fc92d04b6ed6
+  data.tar.gz: ed2f38b62d55cf52a8f93755c432138aa6686e644b2175d74c03ab79c0812e77a62a078938b3a0e7d7908469f00e431731d77b8a75833fd1d94c096f11acd0fc

data/README.md

@@ -6,95 +6,16 @@
 [![Documentation](https://img.shields.io/badge/docs-oss.vicente.services%2Fdspy.rb-blue)](https://oss.vicente.services/dspy.rb/)
 [![Discord](https://img.shields.io/discord/1161519468141355160?label=discord&logo=discord&logoColor=white)](https://discord.gg/zWBhrMqn)
 
-**Build reliable LLM applications in idiomatic Ruby using composable, type-safe modules.**
+**Build typed agents and model-backed programs in Ruby.**
 
-DSPy.rb is the Ruby port of Stanford's [DSPy](https://dspy.ai). Instead of wrestling with brittle prompt strings, you define typed signatures and let the framework handle the rest. Prompts become functions. LLM calls become predictable.
+DSPy.rb brings [DSPy](https://dspy.ai)'s signature, module, agent, and optimizer model to Ruby, with Sorbet types and Ruby-native integrations. A signature declares a task as typed inputs and outputs. A module chooses how to execute it. Ruby composes modules into programs, while `ReAct` adds a bounded loop when the model should choose the next action. DSPy.rb builds the provider request and validates the returned shape.
 
-```ruby
-require 'dspy'
-
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
-end
-
-class Summarize < DSPy::Signature
-  description "Summarize the given text in one sentence."
-
-  input do
-    const :text, String
-  end
+The `1.x` series is the current stable release line.
 
-  output do
-    const :summary, String
-  end
-end
-
-summarizer = DSPy::Predict.new(Summarize)
-result = summarizer.call(text: "DSPy.rb brings structured LLM programming to Ruby...")
-puts result.summary
-```
-
-That's it. No prompt templates. No JSON parsing. No prayer-based error handling.
-
-## Installation
-
-```ruby
-# Gemfile
-gem 'dspy'
-gem 'dspy-openai'     # For OpenAI, OpenRouter, or Ollama
-# gem 'dspy-anthropic' # For Claude
-# gem 'dspy-gemini'    # For Gemini
-# gem 'dspy-ruby_llm'  # For 12+ providers via RubyLLM
-```
-
-```bash
-bundle install
-```
-
-## Quick Start
-
-### Configure Your LLM
-
-```ruby
-# OpenAI
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
-                      api_key: ENV['OPENAI_API_KEY'],
-                      structured_outputs: true)
-end
-
-# Anthropic Claude
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('anthropic/claude-sonnet-4-20250514',
-                      api_key: ENV['ANTHROPIC_API_KEY'])
-end
-
-# Google Gemini
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('gemini/gemini-2.5-flash',
-                      api_key: ENV['GEMINI_API_KEY'])
-end
-
-# Ollama (local, free)
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('ollama/llama3.2')
-end
-
-# OpenRouter (200+ models)
-DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openrouter/deepseek/deepseek-chat-v3.1:free',
-                      api_key: ENV['OPENROUTER_API_KEY'])
-end
-```
-
-### Define a Signature
-
-Signatures are typed contracts for LLM operations. Define inputs, outputs, and let DSPy handle the prompt:
+In a configured application, the task contract and call look like this:
 
 ```ruby
 class Classify < DSPy::Signature
-  description "Classify sentiment of a given sentence."
-
   class Sentiment < T::Enum
     enums do
       Positive = new('positive')
@@ -104,7 +25,7 @@ class Classify < DSPy::Signature
   end
 
   input do
-    const :sentence, String, description: 'The sentence to analyze'
+    const :sentence, String
   end
 
   output do
@@ -114,115 +35,39 @@ class Classify < DSPy::Signature
 end
 
 classifier = DSPy::Predict.new(Classify)
-result = classifier.call(sentence: "This book was super fun to read!")
-
-result.sentiment    # => #<Sentiment::Positive>
-result.confidence   # => 0.92
+result = classifier.call(sentence: "This book was fun to read!")
 ```
 
-### Chain of Thought
+Define a typed task contract instead of maintaining an output template. Receive validated Ruby values instead of parsing provider JSON. Handle configuration, transport, and validation errors explicitly.
 
-For complex reasoning, use `ChainOfThought` to get step-by-step explanations:
+## Start Here
 
-```ruby
-solver = DSPy::ChainOfThought.new(MathProblem)
-result = solver.call(problem: "If a train travels 120km in 2 hours, what's its speed?")
-
-result.reasoning  # => "Speed = Distance / Time = 120km / 2h = 60km/h"
-result.answer     # => "60 km/h"
-```
-
-### ReAct Agents
-
-Build agents that use tools to accomplish tasks:
-
-```ruby
-class SearchTool < DSPy::Tools::Tool
-  tool_name "search"
-  description "Search for information"
-
-  input do
-    const :query, String
-  end
-
-  output do
-    const :results, T::Array[String]
-  end
-
-  def call(query:)
-    # Your search implementation
-    { results: ["Result 1", "Result 2"] }
-  end
-end
-
-toolset = DSPy::Tools::Toolset.new(tools: [SearchTool.new])
-agent = DSPy::ReAct.new(signature: ResearchTask, tools: toolset, max_iterations: 5)
-result = agent.call(question: "What's the latest on Ruby 3.4?")
-```
-
-## What's Included
-
-**Core Modules**: Predict, ChainOfThought, ReAct agents, and composable pipelines.
-
-**Type Safety**: Sorbet-based runtime validation. Enums, unions, nested structs—all work.
-
-**Multimodal**: Image analysis with `DSPy::Image` for vision-capable models.
-
-**Observability**: Zero-config Langfuse integration via OpenTelemetry. Non-blocking, production-ready.
-
-**Optimization**: MIPROv2 (Bayesian optimization) and GEPA (genetic evolution) for prompt tuning.
-
-**Provider Support**: OpenAI, Anthropic, Gemini, Ollama, and OpenRouter via official SDKs.
-
-## Documentation
+The [Quick Start](https://oss.vicente.services/dspy.rb/getting-started/quick-start/) is the complete supported path: install the core and provider gems, configure a key, save a program, and run it.
 
-**[Full Documentation](https://oss.vicente.services/dspy.rb/)** — Getting started, core concepts, advanced patterns.
+Use [Installation](https://oss.vicente.services/dspy.rb/getting-started/installation/) to choose a provider. The [package and capability matrix](https://oss.vicente.services/dspy.rb/getting-started/packages/) records exact gem names, require behavior, support labels, and model or SDK boundaries.
 
-**[llms.txt](https://oss.vicente.services/dspy.rb/llms.txt)** — LLM-friendly reference for AI assistants.
+## Mental Model
 
-### Claude Skill
+- A `DSPy::Signature` defines the task contract.
+- `DSPy::Predict` and other modules choose an execution strategy.
+- Ordinary Ruby owns fixed sequencing, branching, persistence, permissions, and failure policy.
+- Results cross a runtime validation boundary; validation establishes shape, not factual correctness.
 
-A [Claude Skill](https://github.com/vicentereig/dspy-rb-skill) is available to help you build DSPy.rb applications:
-
-```bash
-# Claude Code
-git clone https://github.com/vicentereig/dspy-rb-skill ~/.claude/skills/dspy-rb
-```
-
-For Claude.ai Pro/Max, download the [skill ZIP](https://github.com/vicentereig/dspy-rb-skill/archive/refs/heads/main.zip) and upload via Settings > Skills.
-
-## Examples
-
-The [examples/](examples/) directory has runnable code for common patterns:
-
-- Sentiment classification
-- ReAct agents with tools
-- Image analysis
-- Prompt optimization
-
-```bash
-bundle exec ruby examples/first_predictor.rb
-```
+### ReAct Agents
 
-## Optional Gems
+Use `ReAct` when the model needs to choose among typed Ruby tools inside an iteration bound. The application still owns tool authorization, side effects, budgets, and errors. See [Predictors](https://oss.vicente.services/dspy.rb/core-concepts/predictors/) and [Toolsets](https://oss.vicente.services/dspy.rb/core-concepts/toolsets/).
 
-DSPy.rb ships sibling gems for features with heavier dependencies. Add them as needed:
+## Explore
 
-| Gem | What it does |
-| --- | --- |
-| `dspy-datasets` | Dataset helpers, Parquet/Polars tooling |
-| `dspy-evals` | Evaluation harness with metrics and callbacks |
-| `dspy-miprov2` | Bayesian optimization for prompt tuning |
-| `dspy-gepa` | Genetic-Pareto prompt evolution |
-| `dspy-o11y-langfuse` | Auto-configure Langfuse tracing |
-| `dspy-code_act` | Think-Code-Observe agents |
-| `dspy-deep_search` | Production DeepSearch with Exa |
+- [Documentation](https://oss.vicente.services/dspy.rb/) — task-oriented guides and reference
+- [Examples](examples/) — repository demos indexed by capability and prerequisites
+- [llms.txt](https://oss.vicente.services/dspy.rb/llms.txt) — generated reference for AI assistants
 
-See [the full list](https://oss.vicente.services/dspy.rb/getting-started/installation/) in the docs.
+Provider adapters, optimizers, observability exporters, datasets, and code-executing agents are separate packages when they add dependencies. Check the package matrix before selecting one; package availability does not guarantee uniform provider or model behavior.
 
 ## Contributing
 
-Feedback is invaluable. If you encounter issues, [open an issue](https://github.com/vicentereig/dspy.rb/issues). For suggestions, [start a discussion](https://github.com/vicentereig/dspy.rb/discussions).
+For bugs, [open an issue](https://github.com/vicentereig/dspy.rb/issues). For suggestions, [start a discussion](https://github.com/vicentereig/dspy.rb/discussions).
 
 Want to contribute code? Reach out: hey at vicente.services
 

data/lib/dspy/code_act/README.md

@@ -1,152 +1,77 @@
 # 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.
+`dspy-code_act` is for controlled experiments with trusted input. The current implementation evaluates model-generated Ruby inside the application process. It does not provide a sandbox, permission boundary, resource isolation, or safe handling of untrusted or multi-tenant input.
 
-## When to Use CodeAct
+See the [package and capability matrix](https://oss.vicente.services/dspy.rb/getting-started/packages/) for canonical package status and the execution-safety boundary.
 
-- 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.
+## Prerequisites
 
-## Quick Start
+- Ruby 3.3 or newer and Bundler
+- `dspy`, one provider adapter, and `dspy-code_act`
+- a provider key and model that can produce the required structured responses
+- trusted input and a controlled execution environment
+- outbound network access for the repository research example; generated Ruby calls a live HTTP API
 
-```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:
+## Install and Run the Example
 
 ```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"
+gem "dspy"
+gem "dspy-openai"
+gem "dspy-code_act"
 ```
 
-### Arbitrary Data Processing
+In an application, run `bundle install` after adding those gems. From this repository, enable the optional package while installing the monorepo bundle, then run the example:
 
-```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 }
-)
+```bash
+DSPY_WITH_CODE_ACT=1 bundle install
+export OPENAI_API_KEY="your-key"
+bundle exec ruby examples/codeact_research_agent.rb \
+  "How many stars does rails/rails have?"
 ```
 
-## Safety Checklist
+The script prints the final answer and records the generated code and observations in `result.history`. The answer can change with the live API; inspect the generated code and observation rather than treating an old count as a fixture.
 
-Executing arbitrary Ruby code is powerful but risky. Consider:
+## Define a CodeAct Task
 
-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.
+CodeAct requires a signature and an iteration bound:
 
 ```ruby
-class SafeCodeAct < DSPy::CodeAct
-  def execute_code(ruby_code)
-    Timeout.timeout(5) { super }
-  rescue Timeout::Error
-    "Code execution timed out"
-  end
+class Calculate < DSPy::Signature
+  input { const :question, String }
+  output { const :answer, String }
 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
+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(Calculate, max_iterations: 4)
+result = agent.call(question: "Return the first ten Fibonacci numbers")
+
+puts result.answer
+puts result.history.map(&:ruby_code)
 ```
 
-## Debugging
+The model chooses Ruby code, CodeAct evaluates it, and a second prediction chooses whether to continue or finish. The application owns the iteration limit and execution boundary.
 
-Enable structured logging to observe each iteration:
+## Choose CodeAct or ReAct
 
-```ruby
-DSPy.configure do |config|
-  config.logger = Dry.Logger(:dspy, formatter: :json) do |logger|
-    logger.add_backend(level: :debug, stream: $stdout)
-  end
-end
-```
+Prefer `DSPy::ReAct` when the allowed operations can be exposed as narrow typed tools. Use CodeAct only when open-ended computation is necessary and the execution environment can carry the larger authority boundary.
 
-Inspect `result.history` entry-by-entry to review generated code, observations, and errors.
+## Safety Checklist
 
-## Limitations & Roadmap
+Timeouts and forbidden-string checks do not make Ruby `eval` safe. Generated code can reach loaded constants, files, environment variables, network clients, and process APIs through many equivalent expressions.
 
-- 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.
+Before accepting untrusted input, move execution outside the application process and provide:
 
-## Best Practices
+- a disposable process, container, or virtual machine;
+- no inherited application secrets;
+- allowlisted network access;
+- read-only or ephemeral storage;
+- CPU, memory, wall-clock, and output limits; and
+- a narrow protocol for returning observations.
 
-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.
+The gem does not supply those controls. A provider error, invalid generated program, execution exception, or maximum-iteration result can stop or degrade a run; inspect `result.history` and handle those outcomes in the application.

data/lib/dspy/code_act/version.rb

@@ -2,6 +2,6 @@
 
 module DSPy
   module CodeActVersion
-    VERSION = '1.0.2'
+    VERSION = '1.0.3'
   end
 end

data/lib/dspy/code_act.rb

@@ -118,6 +118,18 @@ module DSPy
       # Create enhanced output struct with CodeAct fields
       @enhanced_output_struct = create_enhanced_output_struct(signature_class)
       enhanced_output_struct = @enhanced_output_struct
+      input_descriptors = signature_class.input_field_descriptors
+      output_descriptors = input_descriptors.merge(signature_class.output_field_descriptors).merge(
+        history: DSPy::Signature::FieldDescriptor.new(
+          T::Array[CodeActHistoryEntry],
+          "CodeAct execution history"
+        ),
+        iterations: DSPy::Signature::FieldDescriptor.new(Integer, "Number of iterations executed"),
+        execution_context: DSPy::Signature::FieldDescriptor.new(
+          T::Hash[Symbol, T.untyped],
+          "Variables and context from code execution"
+        )
+      )
 
       # Create enhanced signature class
       enhanced_signature = Class.new(DSPy::Signature) do
@@ -126,9 +138,11 @@ module DSPy
 
         # Use the same input struct
         @input_struct_class = signature_class.input_struct_class
+        @input_field_descriptors = input_descriptors
 
         # Use the enhanced output struct with CodeAct fields
         @output_struct_class = enhanced_output_struct
+        @output_field_descriptors = output_descriptors
 
         # Store original signature name
         @original_signature_name = signature_class.name
@@ -306,6 +320,11 @@ module DSPy
       })
       output_data[output_field_name] = reasoning_result[:final_answer]
 
+      @signature_class.validate_required_fields!(
+        output_data,
+        @signature_class.output_field_descriptors
+      )
+
       @enhanced_output_struct.new(**output_data)
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dspy-code_act
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
@@ -15,14 +15,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.30'
+        version: 1.0.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.30'
+        version: 1.0.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 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.