Imp
Declarative, self-improving language-model programs for Elixir.
Imp is a full port of DSPy to the BEAM. You describe what
each language-model step takes and returns, choose how it thinks, and let an
optimizer improve it against examples of what good looks like. You get
signatures, modules, optimizers, agent loops and retrieval, running with the
reliability and concurrency of OTP.
DSPy makes each call to a model a declared, typed function that you can
measure and improve. On the BEAM, an agent is a process: it keeps its own
state, receives messages, and runs under a supervisor alongside the rest
of your application. With both, you can build anything from one typed call
to many long-running agents, and improve each part by measuring it.
Declare a task
lm = Imp.req_llm("openai:gpt-5.4-mini", api_key: System.fetch_env!("OPENAI_API_KEY"))
triage =
"issue -> kind: enum[bug,feature,question], summary"
|> Imp.signature("Triage a GitHub issue.")
|> Imp.predict(lm: lm)
{:ok, prediction} =
Imp.call(triage, %{issue: "App crashes on startup since 0.4 with ** (KeyError) key :lm not found"})
{Imp.get(prediction, :kind), Imp.get(prediction, :summary)}
#=> {"bug", "App crashes on startup since version 0.4 with a KeyError for `:lm` not found."}
You never write a prompt or a parser. Imp builds the prompt from the
signature, checks the reply against it, and gives you typed fields: kind is
always one of the three values, or the call returns an error. To make the
same task reason first, use Imp.chain_of_thought/2; to give it tools, use
Imp.react/3. The signature stays the same.
Measure it and improve it
Give Imp labeled examples and a metric, and it scores the program and
optimizes it. You need three lists of issues you have already labeled:
trainset, which the optimizer learns from; valset, which it uses to choose
between the programs it tries; and testset, which you score on before and
after. strong_lm is a more capable model that GEPA uses to read failures and
write new instructions.
# Each set is a list of labeled issues like this one:
example =
Imp.example(%{issue: "Please add a dark mode to the dashboard", kind: "feature"})
|> Imp.with_inputs([:issue])
metric = Imp.exact_match(:kind)
Imp.evaluate(triage, testset, metric).score
optimizer = Imp.Optimizer.GEPA.new(metric, reflection_lm: strong_lm, max_metric_calls: 300)
improved = Imp.optimize!(triage, optimizer, trainset, valset)
Imp.evaluate(improved, testset, metric).score
GEPA runs the program, reads where it failed, and rewrites its instructions.
Other optimizers choose worked examples (LabeledFewShot, BootstrapFewShot),
search over combinations of instructions and examples (MIPROv2), learn rules
and examples from the program's own better and worse attempts (SIMBA), or
train the model's weights (fine-tuning, GRPO). The result is a new program
whose instructions and examples you can read, save as JSON, and review as a
diff.
Build agents
A tool is an Elixir function. Imp.react/3 builds an agent that calls tools
until it can answer. This one reads web pages with Req. Imp depends on Req;
if your own code calls it, as this tool does, add {:req, "~> 0.6"} to your
dependencies:
fetch =
Imp.tool(:fetch, "Read a web page as text.", fn %{"url" => url} -> Req.get!(url).body end,
schema: %{"type" => "object", "properties" => %{"url" => %{"type" => "string"}}, "required" => ["url"]}
)
researcher = Imp.react("question -> answer", [fetch], lm: lm)
question =
"What version does https://raw.githubusercontent.com/elixir-lang/elixir/v1.18.0/VERSION say? " <>
"Reply with just the version."
{:ok, prediction} = Imp.call(researcher, %{question: question})
Imp.get(prediction, :answer)
#=> "1.18.0"
Run agents as processes
Imp.call/2 runs a program in your process. Imp.start_run/3 runs it as its
own supervised process instead, so you can watch it, stop it, and decide
which tool calls it may make:
{:ok, run} =
Imp.start_run(researcher, %{question: question},
authorize: fn call ->
url = call.arguments["url"] || ""
if String.starts_with?(url, "https://raw.githubusercontent.com/"),
do: :allow,
else: {:deny, :untrusted_host}
end
)
{:ok, prediction} = Task.await(run.task, :infinity)
for event <- Imp.Run.events(run), do: event.kind
#=> [:run_started, :tools_sent, :model_request, :model_response, :tool_call,
# :tool_result, :model_request, :model_response, :run_finished]
Imp also includes:
- MCP: import the tools of any MCP server you approve, and they work like
your own.
- ACP: serve any Imp program as an agent to Zed and other ACP clients.
- OTP: a run is a process you can watch, stop and limit, and a run ends
when the process that started it does. Model requests are cut to a
deadline you set. A tool call that may already have taken effect is
reported as unknown, never silently retried.
- More shapes: RLM for inputs far larger than a context window, CodeAct
and program of thought, which compute with small sandboxed expressions, and your own modules
composed from these.
The optimizers work on agents too. GEPA reflects on whole agent runs and
rewrites the instructions that steer them. Optimize Anything rewrites any
text or JSON you can score, such as an agent's tool descriptions.
Install
{:imp, "~> 0.8"}
Imp needs Elixir 1.19 or later and a C and C++ compiler, for the native code
in two dependencies (jaxon and erlexec). The first compile needs network
access, because erlexec's build fetches rebar3 plugins. It reaches models through
ReqLLM, so any provider ReqLLM supports
works.
Imp 0.8 is experimental. Its API may still change, and its optimizers need
large-scale benchmarking. Bug reports and pull requests are welcome.
Learn
- Getting started builds one program step by
step, from the first call to a supervised server, with real scores.
- Coming from DSPy maps DSPy's names to Imp's.
- Tutorials are Livebook notebooks
you can run offline or with a key.
- The cheatsheet has the common calls on one page.
Imp is MIT licensed.
Imp 是 DSPy 在 BEAM 上的完整移植：一个用于构建并自动改进语言模型程序的 Elixir 框架。你把一个步骤的输入和输出声明为带类型的签名，优化器再根据标注数据调整它的提示词或示例。