DSPy.rb

Build typed agents and model-backed programs in Ruby.

DSPy.rb brings DSPy'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.

The 1.x series is the current stable release line.

In a configured application, the task contract and call look like this:

class Classify < DSPy::Signature
  class Sentiment < T::Enum
    enums do
      Positive = new('positive')
      Negative = new('negative')
      Neutral = new('neutral')
    end
  end

  input do
    const :sentence, String
  end

  output do
    const :sentiment, Sentiment
    const :confidence, Float
  end
end

classifier = DSPy::Predict.new(Classify)
result = classifier.call(sentence: "This book was fun to read!")

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.

Start Here

The Quick Start is the complete supported path: install the core and provider gems, configure a key, save a program, and run it.

Use Installation to choose a provider. The package and capability matrix records exact gem names, require behavior, support labels, and model or SDK boundaries.

Mental Model

• 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.

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 and Toolsets.

Explore

• Documentation — task-oriented guides and reference
• Examples — repository demos indexed by capability and prerequisites
• 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. For suggestions, start a discussion.

Want to contribute code? Reach out: hey at vicente.services

License

MIT License.