imp README

The project's README from github.com/deepfates/imp. As one markdown file: README.md.

Imp

Declarative, self-improving language-model programs for Elixir.

An imp studies a hand of cards through a lens while a smaller imp springs from its tail.

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:

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

Imp is MIT licensed.

imp (deepfates/imp)

self-improving
Searching Database…

257 ·GitHub
Imp
What is this?Imp is a full port of DSPy to the BEAM: an Elixir framework for building and automatically improving language-model programs. You declare a step's inputs and outputs as a typed signature, and an optimizer tunes its prompts or examples against labeled data.
Is this a library or a framework for building apps?It's an Elixir framework/library you add to your own BEAM application: you define signatures and modules, Imp builds and parses the prompts, and agents run as supervised OTP processes alongside the rest of your code.
How do I add Imp to an Elixir project?Add Imp as a dependency in your mix.exs and fetch it with mix deps.get; the first compile needs network access because one of its native dependencies (erlexec) fetches rebar3 plugins during the build.
What do I need installed before I can run it?You need Elixir 1.19 or later plus a C and C++ compiler, because two dependencies (jaxon and erlexec) compile native code. Model access goes through ReqLLM, so you'll also need an API key for whichever LLM provider ReqLLM supports that you want to use.
Is this stable enough to build on right now?Not fully — the README flags Imp 0.8 as experimental, warns its API may still change, and says its optimizers still need large-scale benchmarking.
Do I need to already know DSPy to use this?Not necessarily — the docs include a 'Getting started' guide that builds a program from scratch, plus a 'Coming from DSPy' guide that maps DSPy's names onto Imp's for people already familiar with the Python library.
What optimizers does Imp ship with?It includes GEPA, which reflects on failures using a stronger model to rewrite instructions; LabeledFewShot and BootstrapFewShot, which pick worked examples; MIPROv2, which searches combinations of instructions and examples; SIMBA, which learns from a program's own better and worse attempts; and fine-tuning/GRPO, which trains the model's weights.
How do agent tools work?A tool is just an Elixir function; Imp.react/3 builds an agent that calls those tools repeatedly until it can answer, and Imp.startrun/3 runs that agent as its own supervised OTP process you can watch, stop, or limit.
Can Imp use existing MCP servers?Yes — Imp can import the tools of any MCP server you approve and use them like native functions, and it can also serve any Imp program as an agent to ACP clients such as Zed.
What happens to a tool call if a run is stopped mid-flight?Imp never silently retries a tool call that may have already taken effect — it's reported back as unknown instead, and model requests are cut off at a deadline you set.
What are similar projects?rrsi, awesome-rsi, adk-python, hermes-agent-self-evolution, gorilla, harness-sdk, hive, autoagent
Which topics is it in?self-improving, elixir, self-evolving, declarative, tool-calling, functional-programming, reasoning, agentic, optimization, concurrency, autonomous-agents, agent-framework
Creator
deepfates
Size
46.9 MB
Stars
257
Updated
CommitOct 18Releasev0.8.0Oct 02
Age
3mo
Commits · 90 Days