AshLua.Eval (ash_lua v0.2.0)

Public runtime helpers for evaluating scripts against a scoped AshLua surface.

This module is the adapter-free layer underneath AshLua.EvalActions. Use it when a custom transport, MCP server, or in-process LLM loop wants the same scoped Lua runtime without going through a synthesized Ash action.

Each run/2 call builds a fresh Lua VM. Reuse should happen at the manifest level: resolve or preload a manifest once, then pass it as manifest: manifest for subsequent invocations.

Summary

Types

manifest_opts()

run_opts()

run_result()

Functions

docs(manifest_or_opts, args \\ [])

Returns markdown documentation for a scoped AshLua surface.

manifest(manifest)

Resolves a scoped AshLua manifest.

manifest!(manifest_or_opts)

Resolves a scoped AshLua manifest or raises.

run(script, opts)

Evaluates script against a scoped AshLua runtime.

Types

manifest_opts()

@type manifest_opts() :: [
  manifest: Ash.Info.Manifest.t(),
  eval_resource: module(),
  otp_app: atom(),
  labels: [atom()],
  action_entrypoints: [{module(), atom()}],
  cache?: boolean()
]

run_opts()

@type run_opts() :: [
  actor: term(),
  tenant: term(),
  context: map(),
  forbidden_fields: :hide | :display,
  lua: Lua.t(),
  lua_options: keyword(),
  source: String.t(),
  manifest: Ash.Info.Manifest.t(),
  eval_resource: module(),
  otp_app: atom(),
  labels: [atom()],
  action_entrypoints: [{module(), atom()}],
  cache?: boolean()
]

run_result()

@type run_result() :: %{
  result: term(),
  error: map() | nil,
  print_output: [String.t()]
}

Functions

docs(manifest_or_opts, args \\ [])

@spec docs(Ash.Info.Manifest.t() | manifest_opts(), keyword() | map()) ::
  {:ok, String.t()} | {:error, term()}

Returns markdown documentation for a scoped AshLua surface.

Pass neither :name nor :search for the compact index. Pass name: "full" for the full page, a callable/type/topic id for a focused page, or search: term for ranked search results.

manifest(manifest)

@spec manifest(Ash.Info.Manifest.t() | manifest_opts()) ::
  {:ok, Ash.Info.Manifest.t()} | {:error, term()}

Resolves a scoped AshLua manifest.

Accepted inputs:

manifest: manifest or a %Ash.Info.Manifest{} value — reuse an already resolved manifest.
eval_resource: MyApp.AgentSurface — use an AshLua.EvalActions resource's scope.
otp_app: :my_app plus optional labels: / action_entrypoints: — build a scoped surface directly from domain DSL metadata.
cache?: true with eval_resource: — cache and reuse the scoped manifest in :persistent_term.

manifest!(manifest_or_opts)

@spec manifest!(Ash.Info.Manifest.t() | manifest_opts()) :: Ash.Info.Manifest.t()

Resolves a scoped AshLua manifest or raises.

run(script, opts)

@spec run(String.t(), run_opts()) :: {:ok, run_result()} | {:error, term()}

Evaluates script against a scoped AshLua runtime.

Returns the same stable shape as the synthesized :eval action: %{result: term, error: map | nil, print_output: [String.t()]}.

The surface is resolved with manifest/1. Runtime options include :actor, :tenant, :context, :forbidden_fields, :source, :lua, and :lua_options. :lua_options is forwarded to Lua.new/1 when a prebuilt :lua VM is not supplied.