DSPy for Elixir via SnakeBridge
Declarative LLM programming with full access to Stanford NLP's DSPy framework

Overview

DSPex brings DSPy — Stanford NLP's framework for programming language models — to Elixir. It ships with SnakeBridge-generated Dspy.* bindings that mirror DSPy's package layout (great for HexDocs + IDE navigation), plus a minimal DSPex convenience layer over SnakeBridge's Universal FFI. Use the generated modules for the full API surface or the thin FFI wrapper for direct calls.

DSPex 0.12.0 pins and generates bindings for DSPy 3.2.0.

Why DSPex?

• Two access layers — Generated Dspy.* modules + a minimal DSPex FFI wrapper
• Full DSPy access — Signatures, Predict, ChainOfThought, optimizers, and more
• Python-shaped docs — Module tree mirrors DSPy packages for clean HexDocs
• 100+ LLM providers — OpenAI, Anthropic, Google, Ollama, and anything LiteLLM supports
• Production-ready timeouts — Built-in profiles for ML inference workloads
• Elixir-native error handling — {:ok, result} / {:error, reason} everywhere

Installation

Prerequisites (one-time):

• Python 3.9+
• uv for Python package setup: curl -LsSf https://astral.sh/uv/install.sh | sh
• Optional (RLM example only): Deno runtime (external binary), install via asdf: asdf plugin add deno https://github.com/asdf-community/asdf-deno.gitasdf install (uses the pinned version in .tool-versions)

Add DSPex to your mix.exs:

def deps do
  [
    {:dspex, "~> 0.12.0"}
  ]
end

Create config/runtime.exs for Python bridge configuration:

import Config
SnakeBridge.ConfigHelper.configure_snakepit!()

Then install dependencies and set up Python:

mix deps.get
mix snakebridge.setup  # Creates managed venv + installs dspy-ai automatically

SnakeBridge manages an isolated venv under priv/snakepit/python/venv; no manual venv creation or pip installs needed. This release installs DSPy 3.2.0.

For local development against a checkout of SnakeBridge, this repo uses a path dependency (../snakebridge). If you want to use the Hex release instead, update mix.exs to depend on a versioned {:snakebridge, "~> ..."}

When SnakeBridge changes or you need to refresh generated wrappers, run:

mix snakebridge.regen

Add --clean to remove generated artifacts and metadata before regenerating.

The RLM flagship example uses DSPy’s default PythonInterpreter (Pyodide/WASM), which requires Deno on your PATH.

Quick Start

DSPex.run(fn ->
  # 1. Create and configure a language model
  lm = DSPex.lm!("gemini/gemini-flash-lite-latest")
  DSPex.configure!(lm: lm)

  # 2. Create a predictor with a signature
  predict = DSPex.predict!("question -> answer")

  # 3. Run inference
  result = DSPex.method!(predict, "forward", [], question: "What is the capital of France?")
  answer = DSPex.attr!(result, "answer")

  IO.puts(answer)  # => "Paris"
end)

Core Concepts

Signatures

DSPy signatures define input/output contracts using a simple arrow syntax:

# Single input/output
predict = DSPex.predict!("question -> answer")

# Multiple fields
predict = DSPex.predict!("context, question -> answer")

# Rich multi-field signatures
predict = DSPex.predict!("title, content -> category, keywords, sentiment")

Modules

DSPex supports all DSPy modules:

# Simple prediction
predict = DSPex.predict!("question -> answer")

# Chain-of-thought reasoning (includes intermediate steps)
cot = DSPex.chain_of_thought!("question -> answer")
result = DSPex.method!(cot, "forward", [], question: "What is 15% of 80?")
reasoning = DSPex.attr!(result, "reasoning")  # Shows step-by-step thinking
answer = DSPex.attr!(result, "answer")

Language Models

Any LiteLLM-compatible provider works out of the box:

# Google Gemini (default)
lm = DSPex.lm!("gemini/gemini-flash-lite-latest", temperature: 0.7)

# OpenAI
lm = DSPex.lm!("openai/gpt-4o-mini")

# Anthropic
lm = DSPex.lm!("anthropic/claude-3-sonnet-20240229")

# Local Ollama
lm = DSPex.lm!("ollama/llama2")

Direct LM Calls

Bypass modules and call the LM directly:

{:ok, lm} = Dspy.LM.new("gemini/gemini-flash-lite-latest", [], temperature: 0.9)

# Direct call with messages
messages = [%{"role" => "user", "content" => "Say hello in French"}]
{:ok, response} = Dspy.LM.forward(lm, [], messages: messages)

Examples

DSPex includes 20 comprehensive examples demonstrating various use cases:

Use mix run --no-start so DSPex owns the Snakepit lifecycle and closes the process registry DETS cleanly (avoids repair warnings after unclean exits).

Realistic RLM benchmark: the NYC 311 data extraction experiment uses 50,000 real records with exact, computable ground truth. On gemini/gemini-flash-lite-latest, an observed run scored RLM 100% vs Direct 0%.

For flagship walkthroughs, see:

• guides/flagship_multi_pool_gepa.md (GEPA)
• guides/flagship_multi_pool_rlm.md (RLM)

Timeout Configuration

DSPex leverages SnakeBridge's timeout architecture, designed for ML inference workloads. By default, all DSPy calls use the :ml_inference profile (10 minute timeout).

Timeout Profiles

Per-Call Timeout Override

# Use a different profile
DSPex.method!(predict, "forward", [],
  question: "Complex analysis...",
  __runtime__: [timeout_profile: :batch_job]
)

# Set exact timeout in milliseconds
DSPex.method!(predict, "forward", [],
  question: "Quick question",
  __runtime__: [timeout: 30_000]  # 30 seconds
)

# Helper functions
opts = DSPex.with_timeout([question: "test"], timeout: 60_000)
DSPex.method!(predict, "forward", [], opts)

# Profile helper
DSPex.method!(predict, "forward", [],
  Keyword.merge([question: "test"], DSPex.timeout_profile(:batch_job))
)

Global Configuration

# config/config.exs
config :snakebridge,
  runtime: [
    library_profiles: %{"dspy" => :ml_inference}
  ]

API Reference

DSPex provides a thin wrapper over SnakeBridge's Universal FFI, and the generated Dspy.* modules expose DSPy 3.2.0's public API surface (generated via SnakeBridge module_mode: :explicit):

Lifecycle

DSPy Helpers

Universal FFI

Timeout Helpers

All functions have ! variants that raise on error instead of returning {:error, reason}.

Architecture

Generated Dspy.* modules are thin wrappers over SnakeBridge.Runtime; they follow the same gRPC execution path as the DSPex convenience API.

┌─────────────────────────────────────────────────────────┐
│                    Your Elixir App                      │
├─────────────────────────────────────────────────────────┤
│                     DSPex.run/1                         │
│              (Python lifecycle wrapper)                 │
├─────────────────────────────────────────────────────────┤
│                  SnakeBridge.call/4                     │
│                   (Universal FFI)                       │
├─────────────────────────────────────────────────────────┤
│                    Snakepit gRPC                        │
│               (Python process bridge)                   │
├─────────────────────────────────────────────────────────┤
│                     Python DSPy                         │
│            (Stanford NLP's LLM framework)               │
├─────────────────────────────────────────────────────────┤
│                    LLM Providers                        │
│       (OpenAI, Anthropic, Google, Ollama, etc.)         │
└─────────────────────────────────────────────────────────┘

Key Design Principles:

• Dual API — Generated Dspy.* bindings plus the minimal DSPex wrapper
• Python-shaped docs — DSPy modules appear as a familiar package tree
• Automatic lifecycle — Snakepit manages Python processes
• Session-aware — Maintains Python state across calls
• Thread-safe — gRPC bridge handles concurrency

Requirements

• Elixir ~> 1.18
• Python 3.9+
• API Key — Set GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, etc. based on your provider

Related Projects

• DSPy — The Python framework DSPex wraps
• SnakeBridge — The Python-Elixir bridge powering DSPex
• Snakepit — Python process pool and gRPC server

License

MIT License. See LICENSE for details.