Ash AI

Read tools (without get_by) mirror Ash.read/2 behavior. If the action is paginated, the tool returns a page instead of a bare array.

• Offset Pagination: Returns results, limit, offset, has_more, and next_offset (which is null on the last page).
• Keyset Pagination: Returns results, limit, has_more, start_keyset, and end_keyset. To move through pages, pass end_keyset as the after argument or start_keyset as the before argument.
• Defaults: Actions supporting both kinds of pagination use keyset pagination by default. Passing a positive offset switches to offset pagination.
• Count: The count field is included only if the action is configured with countable: :by_default. Otherwise, the LLM can request result_type: "count".

When using AshAi.ToolLoop.run/2, the raw result in the on_tool_end callback is the Ash.Page.Offset or Ash.Page.Keyset struct for paginated actions.

The prompt option in run prompt(...) supports several formats:

1. EEx String: Uses @input and @context. Example: "Analyze: <%= @input.arguments.text %>".
2. System/User Tuple: Both parts can be EEx templates. Example: {"System prompt", "User prompt: <%= @input.arguments.text %>"}.
3. ReqLLM.Context: The canonical form for complex prompts (e.g., multi-modal). Requires import ReqLLM.Context.
4. List of Messages: A list of ReqLLM.Message structs or %{role: "user", content: "..."} maps. Static strings in these lists are EEx-templated.
5. Function: fn input, context -> ... end. Note: Content returned by a function is used verbatim and is not EEx-evaluated, which is a security best practice for user-supplied text.

import ReqLLM.Context

# Using ReqLLM.Context for multi-modal prompts
run prompt(fn input, _ctx ->
  ReqLLM.Context.new([
    system("You are an OCR expert"),
    user([
      ReqLLM.Message.ContentPart.text("Extract the text from this image"),
      ReqLLM.Message.ContentPart.image_url(input.arguments.image_url)
    ])
  ])
end)

When exposing Ash actions as tools, access is governed by attribute visibility and the load option:

• Filtering/Sorting/Aggregation: Only public attributes (public?: true) can be used.
• Single-record lookup: Use get_by on read tools to look up one record by filterable fields.
• Arguments: Only public action arguments are exposed.
• Response data: Public attributes are returned by default.
• Loading data: Use the load option to include relationships, calculations, or additional attributes (including private ones) in responses.

Key Distinction: Private attributes cannot be used for filtering, sorting, or aggregation, but they CAN be included in responses when using the load option.

tools do
  # Returns only public attributes
  tool :read_posts, MyApp.Blog.Post, :read

  # Returns one post by ID instead of a list of results
  tool :get_post_by_id, MyApp.Blog.Post, :read, get_by: :id

  # Returns public attributes AND loaded relationships/calculations
  # Note: loaded fields can include private attributes
  tool :read_posts_with_details, MyApp.Blog.Post, :read,
    load: [:author, :comment_count, :internal_notes]
end

To use the :ash_oban strategy, ensure your resource uses both AshAi and AshOban extensions. You must define an ash_oban_trigger_name and configure an oban trigger block within the resource to handle the :ash_ai_update_embeddings action. Finally, ensure the corresponding queue is added to your Oban configuration in config.exs.

defmodule MyApp.Artist do
  use Ash.Resource, extensions: [AshAi, AshOban]

  vectorize do
    full_text do
      text(fn record -> record.name end)
    end

    strategy :ash_oban
    ash_oban_trigger_name :my_vectorize_trigger
    embedding_model MyApp.OpenAiEmbeddingModel
  end

  oban do
    triggers do
      trigger :my_vectorize_trigger do
        action :ash_ai_update_embeddings
        queue :artist_vectorizer
        worker_module_name __MODULE__.AshOban.Worker.UpdateEmbeddings
        scheduler_module_name __MODULE__.AshOban.Scheduler.UpdateEmbeddings
      end
    end
  end
end

The ash_ai development MCP server exposes tools that allow AI coding assistants (like Claude Code) to automatically discover and read usage-rules.md files from your project's Elixir dependencies. This helps the AI follow package-specific best practices and avoid common pitfalls.

Two primary tools are available via the MCP server:

1. list_packages_with_rules: Returns a list of package names in your current project that contain a usage-rules.md file.
2. get_usage_rules: Retrieves the actual markdown content of the usage rules for a specific list of packages.

These tools are read-only and use Mix.Project.deps_paths() to locate the files on your file system.

# Conceptual API usage via MCP tools:

# 1. List available packages with rules
# Returns: ["ash", "ash_postgres", "igniter", ...]
list_packages_with_rules()

# 2. Get rules for specific packages
# Argument: packages: ["ash", "igniter"]
# Returns: [%{package: "ash", rules: "...markdown content..."}, ...]
get_usage_rules(packages: ["ash", "igniter"])