Sanad

Rewrite Elixir dari Shopify Roast, DSL untuk structured AI workflows.

Roast asli adalah gem Ruby. Workflow ditulis deklaratif, lalu "cogs" (chat, agent, cmd, map, dan lainnya) dijalankan berantai. Output satu step bisa dipakai step berikutnya. Sanad meniru model itu dengan macro Elixir dan Task, bukan terjemahan baris per baris dari file Ruby.

Kenapa Elixir

BEAM sudah kuat untuk I/O paralel. Itu bagian yang di Ruby harus dipasang gem async.

Status

MVP+ dengan divergensi yang didokumentasikan. Sudah bisa dipakai untuk workflow nyata.

Belajar dari nol

Ada tutorial sembilan bab berbahasa Indonesia di tutorial/, dari menjalankan satu langkah sampai mengerjakan banyak hal secara paralel. Semua contohnya bisa dijalankan tanpa API key, dengan contoh kasus dari berbagai bidang: administrasi, keuangan, pengajaran, customer service, riset, dan operasional.

mix sanad.execute tutorial/01_workflow_pertama/salam.exs

Install

Butuh Elixir 1.16+ dan Mix. Tambahkan ke mix.exs proyekmu:

def deps do
  [{:sanad, "~> 0.2"}]
end

Atau kerjakan langsung dari sumbernya:

git clone https://github.com/herbras/sanad
cd sanad
mix deps.get
mix test

Quickstart tanpa API key

mix sanad.execute examples/local_pipeline.exs
# atau:
mix escript.build && ./sanad examples/local_pipeline.exs

examples/local_pipeline.exs memakai cmd, elixir_cog, call_cog, map_cog (paralel), dan repeat_cog. Tidak butuh network.

examples/pi_and_claude.exs menunjukkan jalur lengkapnya: agent pi mereview tiap file yang berubah, Claude mengubah tiap review jadi satu baris putusan, dengan config per nama dan outputs per scope. Butuh binary pi di PATH dan ANTHROPIC_API_KEY.

Workflow

defmodule AnalyzeCodebase do
  use Sanad.DSL

  config do
    %{
      chat: %{provider: :openai, model: "gpt-4o-mini"},
      agent: %{provider: :pi},
      abort_on_failure: true
    }
  end

  execute do
    cmd(:recent_changes, "git diff --name-only HEAD~5..HEAD")

    agent :review do
      files = cmd!(ctx, :recent_changes).stdout
      "Review these recently changed files:\n\n#{files}"
    end

    chat :summary do
      "Summarize:\n\n#{agent!(ctx, :review).response}"
    end
  end
end

Jalankan:

mix sanad.execute examples/analyze_codebase.exs --module AnalyzeCodebase
mix sanad.execute examples/params_demo.exs --param name=world --param loud=true

Di dalam block input, ctx selalu ter-bind. Helper yang tersedia:

Cogs

cmd(:name, "shell command")                       # :cwd, :env, :timeout, :fail_on_error
cmd :name, fail_on_error: false do "..." end
elixir_cog(:name, do: 1 + 1)                      # nilai mentah, padanan `ruby`
map_cog :name, scope: :one_item, parallel: 4 do [1, 2, 3] end
call_cog :name, scope: :inner, index: 0 do some_value end
repeat_cog :name, scope: :one_iteration, max_iterations: 10 do initial_value end
chat :name do "prompt" end
agent :name do "prompt" end

Nilai balik scope

execute :review_one do
  elixir_cog(:draft, do: String.upcase(ctx.scope_value))

  outputs do
    %{item: ctx.scope_value, draft: output!(ctx, :draft)}
  end
end

Tanpa outputs, sebuah scope mengembalikan output cog terakhirnya. Dengan outputs, nilai itulah yang diterima call, tiap iterasi map, dan tiap iterasi repeat (termasuk yang diteruskan ke iterasi berikutnya).

skip! dan next! di dalam blok membuat nilainya nil; break! juga, sambil mengakhiri loop; fail! melempar Sanad.OutputsFailedError. Membaca cog yang tidak sempat jalan karena break! ditelan (nilainya nil) supaya pemanggil tidak perlu kode penjaga — pakai outputs! kalau ingin dilempar. Nama yang tidak pernah dideklarasikan di scope itu selalu melempar, karena itu typo.

Config per nama dan pola

config do
  global(abort_on_failure: true)
  chat(provider: :openai, model: "gpt-4o-mini")
  chat(~r/^review_/, temperature: 0.0)
  chat(:summary, model: "gpt-4o")
end

Urutan merge, dari paling umum ke paling khusus: global, config umum per tipe cog, semua pola yang cocok dengan nama cog (sesuai urutan penulisan), nama persis, lalu opsi step yang tetap menang. Bentuk map yang lama tetap berlaku dan tidak berubah artinya.

Event run

Selama workflow jalan, CLI mencetak jejaknya ke stderr:

🔥🔥🔥 Workflow Starting
cmd(:echo) Starting
cmd(:echo) ❯ hello
map(:lengths) -> {:string_length}[2] Complete
🔥🔥🔥 Workflow Complete

Untuk dibaca mesin, pakai --events jsonl (atau SANAD_EVENT_FORMAT=jsonl): satu objek JSON per baris, ke stderr, sehingga stdout tetap bersih untuk hasil workflow.

mix sanad.execute examples/local_pipeline.exs --events jsonl 2>events.jsonl
jq -r 'select(.event=="cog.stop") | "\(.duration_ms)ms \(.path)"' events.jsonl

Event dipancarkan lewat :telemetry dengan nama [:sanad, :workflow | :scope | :cog, :start | :stop | :exception] plus [:sanad, :cog, :stdout | :stderr | :block | :log]. Pasang handler sendiri lewat Sanad.Event.names/0, atau matikan renderer bawaan dengan --quiet.

Chat providers

Default provider lewat SANAD_DEFAULT_CHAT_PROVIDER. Endpoint yang kompatibel dengan OpenAI, misalnya OpenRouter atau Cloudflare Workers AI, bisa dipakai lewat config workflow:

config do
  %{chat: %{provider: :openai, model: "vendor/model",
            base_url: "https://openrouter.ai/api/v1",
            key_env: "OPENROUTER_API_KEY"}}
end

Model Claude punya alias pendek, jadi workflow tidak perlu menuliskan ID panjang:

chat :summary, provider: :claude, model: :opus do
  "Ringkas ini: #{cmd!(ctx, :diff).stdout}"
end

:opus → claude-opus-5, :sonnet → claude-sonnet-5, :haiku → claude-haiku-4-5, :fable → claude-fable-5-1. Alias yang tidak dikenal ditolak dengan daftar yang sah.

Streaming, JSON mode, dan tool calls

chat :draft, stream: true do
  "Tulis draf panjang tentang #{params(ctx).topic}"
end

chat :extract, json: true do
  "Kembalikan JSON dengan field title dan tags untuk: #{cmd!(ctx, :page).stdout}"
end

chat :maybe_tool, tools: [%{
  name: "get_weather",
  description: "Cuaca terkini sebuah kota",
  parameters: %{type: "object", properties: %{city: %{type: "string"}}}
}] do
  "Bagaimana cuaca di Bandung?"
end

stream: true memancarkan tiap delta sebagai event stdout, jadi token terlihat mengalir di terminal, dan response tetap berisi teks utuh saat step selesai. Stream tidak di-retry: mengulang berarti menayangkan ulang teks yang sudah dikirim ke pemanggil.

json: true memakai JSON mode native provider (response_format untuk OpenAI dan Perplexity, responseMimeType untuk Gemini). Anthropic tidak punya JSON mode, dan sanad mengatakannya terang-terangan alih-alih diam-diam mengabaikan — pakai tool dengan schema yang diinginkan.

Definisi tool ditulis sekali dalam bentuk netral (name, description, parameters) lalu diterjemahkan ke bentuk tiap provider. Panggilan tool dikembalikan apa adanya di chat!(ctx, :name).tool_calls sebagai %{id:, name:, arguments:} — sanad tidak menjalankan tool untukmu; workflow yang memutuskan, misalnya lewat elixir_cog lalu chat berikutnya.

Opsi per step: :provider, :model, :stream, :json, :response_format, :tools, :tool_choice, :system_prompt, :temperature, :max_tokens, :api_key, :key_env, :base_url, :timeout, :max_retries, :req_options. Request POST di-retry dengan retry: :transient. Error HTTP atau transport melempar Sanad.ChatError beserta status.

Agent providers

Output agent berisi response, session (id percakapan provider, nil untuk provider tanpa konsep session), dan stats:

out = agent!(ctx, :review)
out.session                      # "sess-42" untuk pi, session_id untuk claude
out.stats.num_turns              # jumlah giliran, nil kalau tidak dilaporkan
out.stats.usage.input_tokens     # total token, plus output/cache_read/cache_write
out.stats.usage.cost_usd         # biaya kalau provider melaporkannya
out.stats.model_usage["pi-1"]    # rincian per model (pi)

Angka yang tidak dilaporkan provider bernilai nil, bukan 0, supaya "tidak dilaporkan" tetap bisa dibedakan dari "nol".

Default provider lewat SANAD_DEFAULT_AGENT_PROVIDER. cd default-nya workflow_dir. Binary yang tidak ketemu melempar Sanad.MissingExecutableError. Opsi: :model, :system_prompt, :append_system_prompt, :session, :fork_session, :skip_permissions, :command, :env, :timeout.

Control flow

elixir_cog :maybe do
  skip!()   # step ditandai :skipped, workflow lanjut
end

elixir_cog :checked do
  fail!("data invalid")   # abort kalau abort_on_failure: true (default)
end

• skip! tidak menghasilkan output, statusnya :skipped, workflow lanjut.
• fail! menandai :failed lalu abort bila abort_on_failure aktif (step opts lebih dulu, lalu config, default true). Error lain selalu abort.
• next! mengakhiri scope saat ini tanpa pesan.
• break! mengakhiri scope dan membatalkan sibling yang masih jalan di map. Hasil yang sudah selesai dipertahankan, slot yang tidak jalan berisi nil. Di scope teratas, step selanjutnya berhenti.

Nested scopes

execute :review_one do
  elixir_cog(:upper, do: String.upcase(ctx.scope_value))
end

execute do
  map_cog :reviewed, scope: :review_one, parallel: 2 do
    ["a", "b", "c"]
  end

  call_cog :one, scope: :review_one do "x" end

  elixir_cog :report do
    upper = from(output!(ctx, :one), fn child -> output!(child, :upper) end)
    collected = collect(output!(ctx, :reviewed))
    reduced = reduce(output!(ctx, :reviewed), "", fn acc, item -> acc <> item end)
    {upper, collected, reduced}
  end
end

Setiap scope nested jalan di Context anak yang terisolasi. Output di dalam tidak terlihat dari luar, dan sebaliknya. Aksesnya lewat from/2, collect/1,2, dan reduce/3. scope_value dan scope_index meneruskan item dan index. map_cog mendukung parallel: false | true | 0 | n, :timeout, dan :initial_index. repeat_cog meneruskan output akhir iterasi ke iterasi berikutnya, dengan guard default 1000 iterasi. Isi nil atau :infinity untuk mematikan guard.

CLI

mix sanad.execute path/to/workflow.exs [--module M] [--param key=value ...]
mix escript.build               # menghasilkan binary ./sanad
cp sanad ~/.local/bin/sanad     # taruh di PATH, pakai dari project mana pun
sanad path/to/workflow.exs --param key=value

Output berisi ringkasan (status dan durasi per cog) lalu inspect output lengkap. Workflow gagal menghasilkan exit code non-zero beserta pesan errornya.

Testing

mix test

Semua tes offline:

• DSL, runner, control flow, nested engine: unit dan integrasi tanpa network.
• Chat: Req.Test (plug test-only) untuk 4 provider, error HTTP/transport, dan override config.
• Agent: stub executable pi, claude, opencode, agy.
• E2E: subprocess mix sanad.execute untuk pipeline penuh, scope, params, control flow, dan jalur gagal.
• Regresi contoh: tiap berkas di examples/ dijalankan lewat escript hasil build, plus pemeriksaan bentuk %MapResult{}, %Repeat{}, dan %Call{} yang dipakai README. Contoh yang butuh provider dikenali dari manifest langkahnya sendiri, bukan dari daftar yang gampang basi.

Tes yang memanggil CLI agent sungguhan tidak ikut jalan secara bawaan, karena butuh binary terpasang dan token sungguhan:

mix test --include live_providers   # atau SANAD_LIVE=1 mix test

Provider yang binary-nya tidak ada di PATH tidak menghasilkan tes sama sekali; kalau tidak ada satu pun, suite itu melaporkan satu tes ter-skip, bukan lulus tanpa menguji apa-apa.

Divergensi yang didokumentasikan

• ruby diganti elixir_cog yang mengembalikan nilai mentah. Tidak ada evaluasi string Ruby.
• Agent satu prompt per step. Upstream bisa multi-prompt dan merantai sesi. Opsi :fork_session untuk claude tersedia, default true saat :session diisi.
• Chat menambah system_prompt, max_tokens, temperature, retry, timeout, PERPLEXITY_API_BASE, dan override base_url/api_key/key_env. Upstream lebih minim.
• Event dipancarkan lewat :telemetry, bukan satu proses monitor dengan antrean. Konsekuensinya tidak ada urutan global: event dari iterasi map paralel saling menyela, dan hanya event satu path yang terurut penuh. Span cog di dalam iterasi yang di-kill break! tidak tertutup; scope di atasnya ditutup dengan control: :cancelled.
• Config per-nama memakai chat(:x, model: "..."), bukan blok chat(:x) do ... end — Elixir tidak punya receiver implisit, dan instance_eval tidak diport (keputusan D2).
• Heuristik MaxTokensExceededError dari upstream tidak direplikasi.
• cmd :timeout adalah tambahan Sanad, upstream tidak punya.

Lisensi

MIT. Port ini juga MIT. API dan ide workflow milik upstream, Shopify/roast.