Packages and capabilities

Start with dspy, then add the package that owns the provider or optional feature you use. A gem’s presence means its Ruby entry point is available. It does not mean every model or provider endpoint implements every capability.

The matrix is generated from package_capabilities.yml, the canonical package inventory.

Status labels

• supported — A public entry point with a current gemspec, repository tests, and a maintained guide or canonical package entry.

• preview — A public pre-1.0 entry point covered by repository tests; its API may change before 1.0.

• supporting — A maintained package installed mainly as a dependency of another public DSPy.rb package.

These labels describe this repository’s documentation and test posture. They do not extend the compatibility promises made by provider APIs or third-party SDKs.

Package matrix

dspy

• Install: gem 'dspy'
• Loading: Require explicitly. It best-effort loads installed optional integrations, but their own require paths remain the reliable boundary.
• Provides: Typed signatures, modules, Predict, ChainOfThought, ReAct, tools, events, persistence interfaces, and evaluation runtime.
• Boundary: Provider SDKs and separately packaged optimizers, agents, datasets, and exporters are not installed by core alone.

dspy-openai

• Install: gem 'dspy-openai'
• Loading: DSPy::LM auto-requires this path for openai, openrouter, and ollama model prefixes; explicit require is also supported.
• Provides: OpenAI SDK adapter plus OpenAI-compatible OpenRouter and Ollama adapters.
• Boundary: Structured output, vision, streaming behavior, parameters, and fallback behavior depend on the selected model and compatible endpoint.

Monorepo development only: DSPY_WITH_OPENAI=1 selects this repository’s local gemspec. Application users install the gem instead.

dspy-anthropic

• Install: gem 'dspy-anthropic'
• Loading: DSPy::LM auto-requires this path for the anthropic model prefix; explicit require is also supported.
• Provides: Anthropic SDK adapter with tool-based structured extraction and supported media handling.
• Boundary: Model and API-version support determine structured-output, tool, image, document, and streaming behavior.

Monorepo development only: DSPY_WITH_ANTHROPIC=1 selects this repository’s local gemspec. Application users install the gem instead.

dspy-gemini

• Install: gem 'dspy-gemini'
• Loading: DSPy::LM auto-requires this path for the gemini model prefix; explicit require is also supported.
• Provides: Gemini SDK adapter with schema conversion, streaming, and supported image inputs.
• Boundary: Schema, media, safety, and streaming behavior depend on the selected Gemini model and SDK/API version.

Monorepo development only: DSPY_WITH_GEMINI=1 selects this repository’s local gemspec. Application users install the gem instead.

dspy-ruby_llm

• Install: gem 'dspy-ruby_llm'
• Loading: DSPy::LM auto-requires this path for the ruby_llm prefix; explicit require is also supported.
• Provides: Delegates provider selection, model lookup, request transport, and capability discovery to RubyLLM.
• Boundary: Provider coverage is not a uniform capability promise. Registry data, explicit provider overrides, authentication, attachments, schemas, and streaming vary by underlying provider, model, RubyLLM version, and provider SDK; document input is currently restricted to Anthropic.

Monorepo development only: DSPY_WITH_RUBY_LLM=1 selects this repository’s local gemspec. Application users install the gem instead.

dspy-code_act

• Install: gem 'dspy-code_act'
• Loading: Core best-effort loads it when installed; require explicitly before referencing DSPy::CodeAct.
• Provides: Think-Code-Observe agents that synthesize and execute Ruby.
• Boundary: Generated code executes with the process’s authority. The gem does not provide a security sandbox, permission boundary, resource isolation, or safe handling of untrusted input.

Monorepo development only: DSPY_WITH_CODE_ACT=1 selects this repository’s local gemspec. Application users install the gem instead.

dspy-datasets

• Install: gem 'dspy-datasets'
• Loading: Core best-effort loads it when installed; require explicitly before using DSPy::Datasets.
• Provides: Curated dataset manifests, loaders, caching, ADE, and HotpotQA helpers.
• Boundary: Dataset licenses, availability, remote schemas, cache policy, and download cost remain external concerns; Parquet support adds native dependencies.

Monorepo development only: DSPY_WITH_DATASETS=1 selects this repository’s local gemspec. Application users install the gem instead.

dspy-evals

• Install: gem 'dspy-evals'
• Loading: Core already requires the overlapping evaluation runtime files; requiring dspy/evals explicitly addresses the same constants rather than an isolated implementation.
• Provides: Evaluation concurrency, callbacks, aggregation, and tabular export helpers.
• Boundary: Evaluation computes declared metrics; it does not establish factual correctness or generalization beyond the sampled data. The core gem currently ships the same dspy/evals files, so this package is not an isolated implementation.

Monorepo development only: DSPY_WITH_EVALS=1 selects this repository’s local gemspec. Application users install the gem instead.

dspy-miprov2

• Install: gem 'dspy-miprov2'
• Loading: Core best-effort loads it when installed; require explicitly before referencing MIPROv2 constants.
• Provides: MIPROv2 teleprompter and numerical Bayesian-optimization support.
• Boundary: Requires Numo numerical dependencies, an explicit metric and datasets, and held-out evaluation; optimization does not guarantee generalization.

Monorepo development only: DSPY_WITH_MIPROV2=1 selects this repository’s local gemspec. Application users install the gem instead.

dspy-gepa

• Install: gem 'dspy-gepa'
• Loading: Core best-effort loads it when installed; require explicitly before referencing DSPyTelepromptGEPA.
• Provides: DSPy integration for GEPA reflective optimization, experiment tracking, and telemetry.
• Boundary: Installs the lower-level gepa package transitively; requires a metric, evaluation budget, and held-out checks.

Monorepo development only: DSPY_WITH_GEPA=1 selects this repository’s local gemspec. Application users install the gem instead.

gepa

• Install: Installed by gem 'dspy-gepa'; direct use: gem 'gepa'
• Loading: Require explicitly only for the lower-level optimizer API; DSPy.rb users should normally load dspy/gepa through dspy-gepa.
• Provides: Lower-level GEPA engine, proposers, selection strategies, Pareto utilities, logging, and telemetry.
• Boundary: Direct use bypasses the DSPy teleprompter integration and its canonical guide.

Monorepo development only: DSPY_WITH_GEPA=1 selects this repository’s local gemspec. Application users install the gem instead.

dspy-o11y

• Install: gem 'dspy-o11y'
• Loading: Core uses it when installed and otherwise supplies a no-op observability boundary; require explicitly for observability classes.
• Provides: OpenTelemetry span lifecycle, observation types, context hooks, and asynchronous processing.
• Boundary: Export and backend configuration are separate; telemetry queues, shutdown, credentials, sampling, and data policy remain application concerns.

Monorepo development only: DSPY_WITH_O11Y=1 selects this repository’s local gemspec. Application users install the gem instead.

dspy-o11y-langfuse

• Install: gem 'dspy-o11y-langfuse'
• Loading: Core best-effort requires it when installed; its entry point registers Langfuse configuration.
• Provides: Langfuse OTLP auto-configuration and score export on top of dspy-o11y.
• Boundary: Requires Langfuse credentials and compatible OpenTelemetry dependencies; installation alone does not establish retention, privacy, delivery, or shutdown policy.

Monorepo development only: DSPY_WITH_O11Y_LANGFUSE=1 selects this repository’s local gemspec. Application users install the gem instead.

dspy-deep_search

• Install: gem 'dspy-deep_search'
• Loading: Require explicitly; core does not auto-load this package.
• Provides: Search-read-reason loop primitives, token budgets, queues, and an Exa client.
• Boundary: Requires Exa and its credentials for the bundled client; retrieval quality, source policy, and external service behavior remain application concerns.

dspy-deep_research

• Install: gem 'dspy-deep_research'
• Loading: Require explicitly; it loads dspy-deep_search through its dependency.
• Provides: Planning, section queues, and coherence orchestration layered on dspy-deep_search.
• Boundary: Installs an exactly matched dspy-deep_search release; model behavior, search quality, budgets, citations, and output review remain application concerns.

dspy-schema

• Install: Installed by gem 'dspy'; direct use: gem 'dspy-schema'
• Loading: Installed transitively by core; require explicitly when using the converter outside DSPy.rb.
• Provides: Sorbet-to-JSON-Schema conversion without loading the full DSPy runtime.
• Boundary: Schema conversion describes shape and runtime validation; it does not prove semantic correctness or provider support. Core currently ships the same schema files despite depending on this gem, so adding both does not create separate implementations.

Monorepo development only: DSPY_WITH_SCHEMA=1 selects this repository’s local gemspec. Application users install the gem instead.

sorbet-toon

• Install: Installed by gem 'dspy'; direct use: gem 'sorbet-toon'
• Loading: Core depends on and loads the TOON integration; require explicitly for the standalone codec API.
• Provides: TOON encoding, decoding, normalization, reconstruction, and Sorbet extensions.
• Boundary: Pre-1.0 API; token or prompt-size gains depend on the actual data shape and model tokenizer.

Current gem file overlaps

These are packaging facts, not separate implementations. The validator compares every tracked gemspec pair and fails if this list drifts.

• dspy + dspy-evals: The core gem currently ships the evaluation runtime files also packaged by dspy-evals; installing dspy-evals does not isolate a different implementation. Overlapping files: lib/dspy/evals.rb, lib/dspy/evals/version.rb.

• dspy + dspy-ruby_llm: The core gem currently contains RubyLLM adapter files, while dspy-ruby_llm supplies the required RubyLLM dependency and the same entry point. Overlapping files: lib/dspy/ruby_llm.rb, lib/dspy/ruby_llm/lm/adapters/ruby_llm_adapter.rb, lib/dspy/ruby_llm/version.rb.

• dspy + dspy-schema: The core gem currently ships the schema files also packaged by dspy-schema; direct dspy-schema installation avoids the rest of core, but adding it beside dspy does not create a separate implementation. Overlapping files: lib/dspy/schema.rb, lib/dspy/schema/sorbet_json_schema.rb, lib/dspy/schema/sorbet_toon_adapter.rb, lib/dspy/schema/version.rb.

• dspy-deep_research + dspy-deep_search: dspy-deep_research currently packages DeepSearch implementation files and also depends on the exactly matched dspy-deep_search gem. Overlapping files: lib/dspy/deep_search/clients/exa_client.rb, lib/dspy/deep_search/gap_queue.rb, lib/dspy/deep_search/module.rb, lib/dspy/deep_search/signatures.rb, lib/dspy/deep_search/token_budget.rb, lib/dspy/deep_search/version.rb.

• dspy-o11y + dspy-o11y-langfuse: dspy-o11y currently packages the Langfuse files also shipped by dspy-o11y-langfuse; the latter declares exporter dependencies and is the direct Langfuse installation entry. Overlapping files: lib/dspy/o11y/langfuse.rb, lib/dspy/o11y/langfuse/scores_exporter.rb, lib/dspy/o11y/langfuse/version.rb.

Provider capability boundary

• Availability: A provider prefix is available only when its adapter gem and SDK dependencies are installed.
• Capability: Structured output, streaming, images, documents, tools, and request options vary by adapter, model, provider endpoint, and SDK version.
• Verification: Check the detailed adapter guide and the selected model’s current provider documentation, then exercise the exact request in tests.

RubyLLM is deliberately one row, not a promise that all of its underlying providers behave alike. Its registry and SDK determine model discovery; DSPy.rb still applies narrower boundaries where the adapter has them. For example, document inputs through RubyLLM currently require an Anthropic model.

Renamed packages

• Do not install dspy-deepsearch. Use dspy-deep_search.

• Do not install dspy-deepresearch. Use dspy-deep_research.

CodeAct safety boundary

dspy-code_act executes model-generated Ruby with the process’s authority. Installing it does not add a sandbox, resource isolation, a permission system, or safe handling for untrusted input. Put execution behind an isolation boundary appropriate to the data and side effects involved; the application owns that boundary.

Monorepo flags are not application configuration

DSPY_WITH_* flags only select local gemspecs while developing or testing this monorepo. Application users install the named gems in their Gemfile and do not set these flags. Packages without a flag are not selected by a DSPY_WITH_* switch.