dspy-code_act 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41e384ba71082ee6532f168cccd6103a46797153d47ed2cfde122d6c2b3dae30
-  data.tar.gz: 86ec69fbc323d38513179adf541cbc7ff60600616eeffafae0db9a9055eb7f2a
+  metadata.gz: 1e81ad2629b9d652887180a6209dc803301c39a8989317907fd92e4b0bd08c40
+  data.tar.gz: 41f24b4c59be3ee80d3eaaa329fa0d4c1ded4b44ba62f337fd36328271cb886b
 SHA512:
-  metadata.gz: 7a89397a45fe0e63a66ebe993ab26e4a7f244de52e19faaf8ae0f40b9ede20be861d0267cc029f4f5034ecd2d2f7f83229b0428dad4edeb3160400540a8739f0
-  data.tar.gz: 0f3ac179289084396771adea5c624fa71b9a029001ad5c1baa99cfa03103ba92fd1aefbfe0ed6b9356447349a1dee6239dcf20027466cfe0b4d6b78d6f40e726
+  metadata.gz: 52355d8730ca9f9f3455bfc87e6fba782a934feece0ccc418cd1adec8c4bd597191cf9975c66afded7dbfb5c41bcbc751c1bee6c2c4e0d72b569fc92d04b6ed6
+  data.tar.gz: ed2f38b62d55cf52a8f93755c432138aa6686e644b2175d74c03ab79c0812e77a62a078938b3a0e7d7908469f00e431731d77b8a75833fd1d94c096f11acd0fc

data/README.md

@@ -3,60 +3,19 @@
 [![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/)
+[![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)
 
-> [!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
->
+**Build typed agents and model-backed programs in Ruby.**
 
-**Build reliable LLM applications in idiomatic Ruby using composable, type-safe modules.**
+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.
 
-DSPy.rb is the Ruby-first surgical port of Stanford's [DSPy framework](https://github.com/stanfordnlp/dspy). It delivers structured LLM programming, prompt engineering, and context engineering in the language we love. Instead of wrestling with brittle prompt strings, you define typed signatures in idiomatic Ruby and compose workflows and agents that actually behave.
+The `1.x` series is the current stable release line.
 
-**Prompts are 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/): define modular signatures and let the framework deal with the messy bits.
-
-While we implement the same signatures, predictors, and optimization algorithms as the original library, DSPy.rb leans hard into Ruby conventions with Sorbet-based typing, ReAct loops, and production-ready integrations like non-blocking OpenTelemetry instrumentation.
-
-**What you get?** Ruby LLM applications that 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:
+In a configured application, the task contract and call look like this:
 
 ```ruby
-gem 'dspy'
-```
-
-and
-
-```bash
-bundle install
-```
-
-### Your First Reliable Predictor
-
-```ruby
-require 'dspy'
-
-# Configure DSPy globally to use your fave LLM (you can override per predictor).
-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')
@@ -64,233 +23,54 @@ class Classify < DSPy::Signature
       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'
+    const :sentence, String
   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'
+    const :sentiment, Sentiment
+    const :confidence, Float
   end
 end
 
-# Wire it to the simplest prompting technique: a prediction loop.
-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
-```
-
-Save this as `examples/first_predictor.rb` and run it with:
-
-```bash
-bundle exec ruby examples/first_predictor.rb
-```
-
-### Sibling Gems
-
-DSPy.rb ships multiple gems from this monorepo so you can opt into features with heavier dependency trees (e.g., datasets pull in Polars/Arrow, MIPROv2 requires `numo-*` BLAS bindings) only when you need them. Add these alongside `dspy`:
-
-| Gem | Description | Status |
-| --- | --- | --- |
-| `dspy-schema` | Exposes `DSPy::TypeSystem::SorbetJsonSchema` for downstream reuse. (Still required by the core `dspy` gem; extraction lets other projects depend on it directly.) | **Stable** (v1.0.0) |
-| `dspy-openai` | Packages the OpenAI/OpenRouter/Ollama adapters plus the official SDK guardrails. Install whenever you call `openai/*`, `openrouter/*`, or `ollama/*`. [Adapter README](https://github.com/vicentereig/dspy.rb/blob/main/lib/dspy/openai/README.md) | **Stable** (v1.0.0) |
-| `dspy-anthropic` | Claude adapters, streaming, and structured-output helpers behind the official `anthropic` SDK. [Adapter README](https://github.com/vicentereig/dspy.rb/blob/main/lib/dspy/anthropic/README.md) | **Stable** (v1.0.0) |
-| `dspy-gemini` | Gemini adapters with multimodal + tool-call support via `gemini-ai`. [Adapter README](https://github.com/vicentereig/dspy.rb/blob/main/lib/dspy/gemini/README.md) | **Stable** (v1.0.0) |
-| `dspy-code_act` | Think-Code-Observe agents that synthesize and execute Ruby safely. (Add the gem or set `DSPY_WITH_CODE_ACT=1` before requiring `dspy/code_act`.) | **Stable** (v1.0.0) |
-| `dspy-datasets` | Dataset helpers plus Parquet/Polars tooling for richer evaluation corpora. (Toggle via `DSPY_WITH_DATASETS`.) | **Stable** (v1.0.0) |
-| `dspy-evals` | High-throughput evaluation harness with metrics, callbacks, and regression fixtures. (Toggle via `DSPY_WITH_EVALS`.) | **Stable** (v1.0.0) |
-| `dspy-miprov2` | Bayesian optimization + Gaussian Process backend for the MIPROv2 teleprompter. (Install or export `DSPY_WITH_MIPROV2=1` before requiring the teleprompter.) | **Stable** (v1.0.0) |
-| `dspy-gepa` | `DSPy::Teleprompt::GEPA`, reflection loops, experiment tracking, telemetry adapters. (Install or set `DSPY_WITH_GEPA=1`.) | **Stable** (v1.0.0) |
-| `gepa` | GEPA optimizer core (Pareto engine, telemetry, reflective proposer). | **Stable** (v1.0.0) |
-| `dspy-o11y` | Core observability APIs: `DSPy::Observability`, async span processor, observation types. (Install or set `DSPY_WITH_O11Y=1`.) | **Stable** (v1.0.0) |
-| `dspy-o11y-langfuse` | Auto-configures DSPy observability to stream spans to Langfuse via OTLP. (Install or set `DSPY_WITH_O11Y_LANGFUSE=1`.) | **Stable** (v1.0.0) |
-| `dspy-deep_search` | Production DeepSearch loop with Exa-backed search/read, token budgeting, and instrumentation (Issue #163). | **Stable** (v1.0.0) |
-| `dspy-deep_research` | Planner/QA orchestration atop DeepSearch plus the memory supervisor used by the CLI example. | **Stable** (v1.0.0) |
-| `sorbet-toon` | Token-Oriented Object Notation (TOON) codec, prompt formatter, and Sorbet mixins for BAML/TOON Enhanced Prompting. [Sorbet::Toon README](https://github.com/vicentereig/dspy.rb/blob/main/lib/sorbet/toon/README.md) | **Alpha** (v0.1.0) |
-
-**Provider adapters:** Add `dspy-openai`, `dspy-anthropic`, and/or `dspy-gemini` next to `dspy` in your Gemfile depending on which `DSPy::LM` providers you call. Each gem already depends on the official SDK (`openai`, `anthropic`, `gemini-ai`), and DSPy auto-loads the adapters when the gem is present—no extra `require` needed.
-
-Set the matching `DSPY_WITH_*` environment variables (see `Gemfile`) to include or exclude each sibling gem when running Bundler locally (for example `DSPY_WITH_GEPA=1` or `DSPY_WITH_O11Y_LANGFUSE=1`). Refer to `adr/013-dependency-tree.md` for the full dependency map and roadmap.
-### 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
+classifier = DSPy::Predict.new(Classify)
+result = classifier.call(sentence: "This book was fun to read!")
 ```
 
-## What You Get
-
-**Developer Experience:** Official clients, multimodal coverage, and observability baked in.
-<details>
-<summary>Expand for everything included</summary>
-
-- 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
-</details>
-
-**Core Building Blocks:** Predictors, agents, and pipelines wired through type-safe signatures.
-<details>
-<summary>Expand for everything included</summary>
-
-- **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
-</details>
-
-**Optimization & Evaluation:** Treat prompt optimization like a real ML workflow.
-<details>
-<summary>Expand for everything included</summary>
-
-- **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
-</details>
+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.
 
-**Production Features:** Hardened behaviors for teams shipping actual products.
-<details>
-<summary>Expand for everything included</summary>
+## Start Here
 
-- **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
-</details>
+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.
 
-## Recent Achievements
+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.
 
-DSPy.rb has gone from experimental to production-ready in three fast releases.
-<details>
-<summary>Expand for the full changelog highlights</summary>
+## Mental Model
 
-### 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
+- 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.
 
-### 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
-</details>
-
-**Current Focus Areas:** Closing the loop on production patterns and community adoption ahead of v1.0.
-<details>
-<summary>Expand for the roadmap</summary>
-
-### 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
-</details>
-
-**v1.0 Philosophy:** v1.0 lands after battle-testing, not checkbox bingo. The API is already stable; the milestone marks production confidence.
-
-
-## 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 
+### ReAct Agents
 
+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/).
 
+## Explore
 
+- [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
 
+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
 
+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
 
 ## License
-This project is licensed under the MIT License.
+
+MIT License.

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.1'
+    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
@@ -287,7 +301,7 @@ module DSPy
       build_enhanced_struct(
         { input: input_props, output: output_props },
         {
-          history: [T::Array[T::Hash[Symbol, T.untyped]], "CodeAct execution history"],
+          history: [T::Array[CodeActHistoryEntry], "CodeAct execution history"],
           iterations: [Integer, "Number of iterations executed"],
           execution_context: [T::Hash[Symbol, T.untyped], "Variables and context from code execution"]
         }
@@ -300,12 +314,17 @@ module DSPy
       output_field_name = @original_signature_class.output_struct_class.props.keys.first
 
       output_data = input_kwargs.merge({
-        history: reasoning_result[:history].map(&:to_h),
+        history: reasoning_result[:history],
         iterations: reasoning_result[:iterations],
         execution_context: reasoning_result[:execution_context]
       })
       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
 
@@ -420,41 +439,13 @@ module DSPy
         [final_result, ""]
       rescue SyntaxError => e
         [nil, "Error: #{e.message}"]
-      rescue => e
+      rescue StandardError => 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dspy-code_act
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  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.