DotPrompt

A high-performance, native Elixir compiler for the DotPrompt language.

What This Is

DotPrompt compiles .prompt files — a domain-specific language where branching, fragments, and contracts resolve at compile time. Your LLM receives only the final, flat prompt string with zero logic residue.

Unlike the TypeScript and Python clients (which talk to a runtime container), this is the native Elixir compiler — it runs in-process with no network overhead.

Website:dotprompt.run
Documentation:dotprompt.run/docs
GitHub:github.com/dot-prompt/dot-prompt

Features

• In-process compilation — no network calls, compiles directly in your BEAM VM
• Structural caching — compiled prompts cached with automatic invalidation on file changes
• Fragments — reusable prompt snippets (static, dynamic, and collection-based)
• Vary blocks — A/B testing and randomized prompt variations with deterministic seeding
• Conditional logic — if/elif/else and case blocks resolved at compile time
• Response contracts — declare expected LLM response formats as JSON schemas
• Telemetry integration — built-in :telemetry events for monitoring compile times and token counts
• Version management — major version support with archive fallback

Installation

The package can be installed by adding dot_prompt to your list of dependencies in mix.exs:

def deps do
  [
    {:dot_prompt, "~> 1.0.0"}
  ]
end

Prerequisites

Place your .prompt files in a prompts/ directory at your project root, or configure a custom path:

config :dot_prompt,
  prompts_dir: "priv/prompts"

Quick Start

# Compile a prompt with parameters
{:ok, result} = DotPrompt.compile("my_prompt", %{name: "World"})
IO.puts(result.prompt)

Full Example: Compile + Render + Validate

# Extract schema (parameters, types, contracts)
{:ok, schema} = DotPrompt.schema("teaching_prompt")
IO.inspect(schema.params)

# Compile: resolve branching, expand fragments, select variations
{:ok, compiled} = DotPrompt.compile("teaching_prompt", %{
  pattern_step: 2,
  variation: "recognition",
  answer_depth: "medium",
  skill_names: ["Milton Model"]
}, seed: 42) # deterministic variation selection

IO.puts("Template: #{compiled.prompt}")

# Render: inject runtime variables into the compiled template
{:ok, rendered} = DotPrompt.render("teaching_prompt",
  %{
    pattern_step: 2,
    variation: "recognition",
    answer_depth: "medium",
    skill_names: ["Milton Model"]
  },
  %{
    user_input: "Can you give me an example?",
    user_level: "intermediate"
  }
)

IO.puts("Final prompt: #{rendered.prompt}")

# Validate LLM response against the contract
response = Jason.encode!(%{score: 8, explanation: "Good answer"})
case DotPrompt.validate_output(response, compiled.response_contract) do
  :ok -> IO.puts("Valid response")
  {:error, reason} -> IO.puts("Invalid: #{reason}")
end

API Reference

Core Functions

Compile Options

DotPrompt.Result Struct

Cache Management

Configuration

config :dot_prompt,
  prompts_dir: "priv/prompts"

Telemetry

DotPrompt emits :telemetry events you can attach to:

:telemetry.attach(
  "dot-prompt-render",
  [:dot_prompt, :render, :stop],
  fn _event, measurements, metadata, _config ->
    IO.puts("Rendered #{metadata.prompt_name} in #{measurements.duration}ms")
    IO.puts("Tokens: #{measurements.compiled_tokens}")
    IO.puts("Cache hit: #{measurements.cache_hit}")
  end,
  []
)

Example .prompt File

This is what the compiler compiles from:

init do
  @major: 1

  params:
    @name: str -> user's name
    @mode: enum[formal, casual] = casual -> communication style

  fragments:
    {greeting}: static from: greetings
      match: @mode

end init

case @mode do
formal: Dear @name, welcome to our service.
casual: Hey @name! Great to see you.
end @mode

Into this clean string for your LLM:

Dear Sarah, welcome to our service.

No branching logic. No fragment references. Just the instruction.

Related Packages

License

Apache 2.0 — see LICENSE