AshAi

https://hexdocs.pm/ash_ai
Admin
AshAi integrates AI capabilities into the Ash framework, offering tools for chat interactions,...
Tokens:11,527
Snippets:91
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### mix ash_ai.install

Source: https://hexdocs.pm/ash_ai/api-reference

Installs `AshAi`. Call with `mix igniter.install ash_ai`. Requires igniter to run.

```APIDOC
## mix ash_ai.install

### Description
Installs `AshAi`. Call with `mix igniter.install ash_ai`. Requires igniter to run.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### AshAi Prompt with Image Analysis using Templates

Source: https://hexdocs.pm/ash_ai/AshAi.Actions

Provides an example of using `prompt/2` for image analysis, combining EEx templates with `ContentPart.image!`. This allows passing image data and contextual information, enabling the LLM to interpret images along with text prompts. The example includes `media` and `detail` options for the image.

```elixir
run prompt(
  ChatOpenAI.new!(%{model: "gpt-4o"}),
  prompt: [
    Message.new_system!("You are an expert at image analysis"),
    Message.new_user!([
      PromptTemplate.from_template!("Extra context: <%= @input.arguments.context %>"),
      ContentPart.image!( "<%= @input.arguments.image_data %>", media: :jpg, detail: "low")
    ])
  ]
)
```

--------------------------------

### Install Ash AI with Igniter

Source: https://hexdocs.pm/ash_ai/readme

Installs the Ash AI library using the Igniter tool and adds it to the project's dependencies.

```bash
mix igniter.install ash_ai

```

```elixir
def deps do
  [
    {:ash_ai, "~> 0.2"}
  ]
end

```

--------------------------------

### Install Ash AI with Igniter

Source: https://hexdocs.pm/ash_ai/index

This command installs the Ash AI library using the Igniter tool. It is a prerequisite for using Ash AI in your Elixir project.

```bash
mix igniter.install ash_ai

```

--------------------------------

### Setup Agent Interaction with AshAi

Source: https://hexdocs.pm/ash_ai/AshAi

The `setup_ash_ai` function adds necessary context and tool call capabilities to an agent, enabling it to interact with your application. It takes a LangChain instance and optional configuration as input.

```elixir
setup_ash_ai(lang_chain, opts \\ [])
```

--------------------------------

### Create New Phoenix App with Ash AI Dependencies

Source: https://hexdocs.pm/ash_ai/readme

Creates a new Phoenix application and installs necessary Ash and related libraries, including Ash AI, for chat functionality.

```bash
mix igniter.new my_app \
  --with phx.new \
  --install ash,ash_postgres,ash_phoenix \
  --install ash_authentication_phoenix,ash_oban \
  --install ash_ai@github:ash-project/ash_ai \
  --auth-strategy password

```

--------------------------------

### GET /websites/hexdocs_pm_ash_ai/settings

Source: https://hexdocs.pm/ash_ai/AshAi.Mcp

Retrieves the settings for the AshAi MCP server.

```APIDOC
## GET /websites/hexdocs_pm_ash_ai/settings

### Description
Retrieves the settings for the AshAi MCP server.

### Method
GET

### Endpoint
/websites/hexdocs_pm_ash_ai/settings

### Parameters
#### Query Parameters
- **opts** (object) - Optional - Options for retrieving settings.

### Response
#### Success Response (200)
- **settings** (object) - The server settings.

#### Response Example
```json
{
  "settings": {
    "key1": "value1",
    "key2": "value2"
  }
}
```
```

--------------------------------

### Basic AshAi Prompt Action with LangChain

Source: https://hexdocs.pm/ash_ai/AshAi.Actions

Demonstrates a basic AshAi action definition using the `prompt/2` function with a LangChain model. This example shows how to define an action, its arguments, and configure the LLM call. It specifies the model and enables tool usage.

```elixir
action :analyze_sentiment, :atom do
  constraints one_of: [:positive, :negative]

  description """
  Analyzes the sentiment of a given piece of text to determine if it is overall positive or negative.

  Does not consider swear words as inherently negative.
  """

  argument :text, :string do
    allow_nil? false
    description "The text for analysis."
  end

  run prompt(
    LangChain.ChatModels.ChatOpenAI.new!(%{ model: "gpt-4o"}),
    tools: true
  )
end
```

--------------------------------

### AshAi Prompt with System/User Tuple

Source: https://hexdocs.pm/ash_ai/AshAi.Actions

Demonstrates configuring the prompt for `prompt/2` using a {System, User} tuple. This format allows specifying distinct system instructions and user queries for the LLM, providing a structured way to define the interaction context. The example includes embedding the `:text` argument.

```elixir
run prompt(
  ChatOpenAI.new!(%{model: "gpt-4o"}),
  prompt: {"You are a sentiment analyzer", "Analyze: <%= @input.arguments.text %>"}
)
```

--------------------------------

### Oban Configuration for Ash AI Vectorization Queue

Source: https://hexdocs.pm/ash_ai/readme

Example configuration for the Oban engine in 'config.exs' to include a dedicated queue for artist vectorization, specifying limits and other Oban settings.

```elixir
config :my_app, Oban, 
  engine: Oban.Engines.Basic,
  notifier: Oban.Notifiers.Postgres,
  queues: [
    default: 10,
    chat_responses: [limit: 10],
    conversations: [limit: 10],
    artist_vectorizer: [limit: 20], 
  ],
  repo: MyApp.Repo,
  plugins: [{Oban.Plugins.Cron, []}]

```

--------------------------------

### GET /websites/hexdocs_pm_ash_ai/server_version

Source: https://hexdocs.pm/ash_ai/AshAi.Mcp

Gets the version of the MCP server.

```APIDOC
## GET /websites/hexdocs_pm_ash_ai/server_version

### Description
Gets the version of the MCP server.

### Method
GET

### Endpoint
/websites/hexdocs_pm_ash_ai/server_version

### Parameters
#### Query Parameters
- **opts** (object) - Optional - Options for retrieving the server version.

### Response
#### Success Response (200)
- **server_version** (string) - The version of the MCP server.

#### Response Example
```json
{
  "server_version": "0.2.13"
}
```
```

--------------------------------

### Configure CompletionTool Adapter with Max Runs

Source: https://hexdocs.pm/ash_ai/AshAi.Actions.Prompt

This example demonstrates how to configure the CompletionTool adapter for prompt actions, specifying a maximum number of runs for the LLM. This is useful when the LLM needs to be invoked multiple times to reach a completion state.

```elixir
run prompt(%{...}, adapter: {AshAi.Actions.Prompt.Adapter.CompletionTool, max_runs: 5})
```

--------------------------------

### GET /websites/hexdocs_pm_ash_ai/session/{session_id}

Source: https://hexdocs.pm/ash_ai/AshAi.Mcp

Processes an HTTP GET request to open an SSE stream for a given session.

```APIDOC
## GET /websites/hexdocs_pm_ash_ai/session/{session_id}

### Description
Processes an HTTP GET request to open an SSE stream for a given session.

### Method
GET

### Endpoint
/websites/hexdocs_pm_ash_ai/session/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier for the session.

### Response
#### Success Response (200)
- **sse_stream** (stream) - A Server-Sent Events stream for real-time updates.

#### Response Example
```
Event: update
data: {"status": "processing"}

Event: complete
data: {"result": "success"}
```
```

--------------------------------

### GET /websites/hexdocs_pm_ash_ai/server_name

Source: https://hexdocs.pm/ash_ai/AshAi.Mcp

Gets the name of the MCP server.

```APIDOC
## GET /websites/hexdocs_pm_ash_ai/server_name

### Description
Gets the name of the MCP server.

### Method
GET

### Endpoint
/websites/hexdocs_pm_ash_ai/server_name

### Parameters
#### Query Parameters
- **opts** (object) - Optional - Options for retrieving the server name.

### Response
#### Success Response (200)
- **server_name** (string) - The name of the MCP server.

#### Response Example
```json
{
  "server_name": "AshAi-MCP-Server"
}
```
```

--------------------------------

### AshAi Prompt with String EEx Template

Source: https://hexdocs.pm/ash_ai/AshAi.Actions

Illustrates using a simple string as an EEx template for the prompt in `prompt/2`. This allows embedding action arguments directly into the prompt string for customized LLM input. The example shows how to reference the `:text` argument.

```elixir
run prompt(
  ChatOpenAI.new!(%{model: "gpt-4o"}),
  prompt: "Analyze the sentiment of: <%= @input.arguments.text %>"
)
```

--------------------------------

### Start Interactive Chat with LangChain (AshAi)

Source: https://hexdocs.pm/ash_ai/AshAi

The `iex_chat` function allows for interactive chat sessions using LangChain within an IEx environment, facilitated by AshAi. It requires a LangChain instance and optional arguments.

```elixir
iex_chat(lang_chain, opts \\ [])
```

--------------------------------

### Get AshAi Tools

Source: https://hexdocs.pm/ash_ai/AshAi

The `tools` macro in AshAi provides access to the library's utility functions or tools. It accepts a body argument, likely for context or configuration.

```elixir
tools(body)
```

--------------------------------

### Configure Langchain for Google Gemini API Key

Source: https://hexdocs.pm/ash_ai/gemini

Replace the OpenAI API key configuration with the Google Gemini API key in `config/runtime.ex`. This involves changing the module and environment variable name.

```elixir
config :langchain,
  google_ai_key: fn -> System.get_env("GEMINI_API_KEY") end

```

--------------------------------

### Prompt-Backed Action for Sentiment Analysis with Ash AI

Source: https://hexdocs.pm/ash_ai/readme

This example defines a prompt-backed action using Ash AI to analyze sentiment. The action specifies input arguments and uses a `LangChain` model to perform the analysis. The `tools: true` option allows the LLM to leverage all exposed tools in the application for a more context-aware response.

```elixir
action :analyze_sentiment, :atom do
  constraints one_of: [:positive, :negative]

  description """
  Analyzes the sentiment of a given piece of text to determine if it is overall positive or negative.
  """

  argument :text, :string do
    allow_nil? false
    description "The text for analysis"
  end

  run prompt(
    LangChain.ChatModels.ChatOpenAI.new!(%{ model: "gpt-4o"}),
    # setting `tools: true` allows it to use all exposed tools in your app
    tools: true
    # alternatively you can restrict it to only a set of tools
    # tools: [:list, :of, :tool, :names]
    # provide an optional prompt, which is an EEx template
     # prompt: "Analyze the sentiment of the following text: <%= @input.arguments.description %>",
    # adapter: {Adapter, [some: :opt]}
  )
end
```

--------------------------------

### AshAi Prompt with LangChain Messages for Conversations

Source: https://hexdocs.pm/ash_ai/AshAi.Actions

Shows how to use a list of LangChain messages to construct a multi-turn conversation for the LLM via `prompt/2`. This is useful for maintaining context and simulating dialogue. The example includes system, user, assistant, and user messages.

```elixir
run prompt(
  ChatOpenAI.new!(%{model: "gpt-4o"}),
  prompt: [
    Message.new_system!("You are an expert assistant"),
    Message.new_user!("Hello, how can you help me?"),
    Message.new_assistant!("I can help with various tasks"),
    Message.new_user!("Great! Please analyze this data")
  ]
)
```

--------------------------------

### Switch Embedding Model in Vectorize Block

Source: https://hexdocs.pm/ash_ai/gemini

Update the `vectorize` block configuration to use the newly created `YourApp.GoogleAiEmbeddingModel` instead of the default `YourApp.OpenAiEmbeddingModel`. This directs vectorization processes to use Google AI embeddings.

```elixir
embedding_model YourApp.GoogleAiEmbeddingModel

```

--------------------------------

### Setup Ash AI with LangChain for Chat

Source: https://hexdocs.pm/ash_ai/readme

This Elixir code sets up an interactive chat interface using LangChain and Ash AI. It defines a chatbot module that initializes an LLMChain with a specific chat model (e.g., GPT-4o) and then integrates it with Ash AI's `iex_chat` function. This allows for direct chatting with the application within an `iex` session.

```elixir
defmodule MyApp.ChatBot do
  alias LangChain.Chains.LLMChain
  alias LangChain.ChatModels.ChatOpenAI

  def iex_chat(actor \ nil) do
    %{ 
      llm: ChatOpenAI.new!(%{model: "gpt-4o", stream: true}),
      verbose: true
    }
    |> LLMChain.new!()
    |> AshAi.iex_chat(actor: actor, otp_app: :my_app)
  end
end
```

--------------------------------

### Configure Oban Queues for Ash AI Vectorization

Source: https://hexdocs.pm/ash_ai/index

Defines the Oban queues in the application's configuration. This example shows how to set up a specific queue, `artist_vectorizer`, for handling embedding updates asynchronously, including setting its worker limit.

```elixir
config :my_app, Oban, 
  engine: Oban.Engines.Basic,
  notifier: Oban.Notifiers.Postgres,
  queues: [
    default: 10,
    chat_responses: [limit: 10],
    conversations: [limit: 10],
    artist_vectorizer: [limit: 20], #set the limit of concurrent workers
  ],
  repo: MyApp.Repo,
  plugins: [{Oban.Plugins.Cron, []}]
```

--------------------------------

### Update Chat Model to ChatGoogleAI

Source: https://hexdocs.pm/ash_ai/gemini

Modify chat model aliases and instantiation in `respond.ex` and `generate_name.ex` to use `ChatGoogleAI` and the 'gemini-2.5-pro' model. This ensures the chat server utilizes Gemini.

```elixir
alias LangChain.ChatModels.ChatGoogleAI

...

llm: ChatGoogleAI.new!(%{model: "gemini-2.5-pro", stream: true}),

```

--------------------------------

### Implement Google AI Embedding Model

Source: https://hexdocs.pm/ash_ai/gemini

Create a new Elixir module `YourApp.GoogleAiEmbeddingModel` that implements the `AshAi.EmbeddingModel` behavior. This module handles embedding content using Google's Gemini embedding model.

```elixir
defmodule YourApp.GoogleAiEmbeddingModel do
  use AshAi.EmbeddingModel

  @impl true
  def dimensions(_opts), do: 3072

  @impl true
  def generate(texts, _opts) do
    parts = Enum.map(texts, fn t -> %{text: t} end)
    api_key = System.fetch_env!("GEMINI_API_KEY")

    headers = [
      {"x-goog-api-key", "#{api_key}"},
      {"Content-Type", "application/json"}
    ]

    body = %{
      "content" => %{parts: parts},
      "model" => "models/gemini-embedding-001"
    }

    response = 
      Req.post!(
        "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent",
        json: body,
        headers: headers
      )

    case response.status do
      200 ->
        {:ok, [response.body["embedding"]["values"]]}

      _status ->
        {:error, response.body}
    end
  end
end

```

--------------------------------

### Tool Data Access Levels in Ash AI

Source: https://hexdocs.pm/ash_ai/readme

This example illustrates how Ash AI manages data access for tools, distinguishing between public and private attributes. Public attributes are used for filtering, sorting, and aggregation by default. The `load` option allows inclusion of relationships, calculations, and even private attributes in responses, offering granular control over data visibility.

```elixir
tools do
  # Returns only public attributes
  tool :read_posts, MyApp.Blog.Post, :read
  
  # 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
```

--------------------------------

### mix ash_ai.gen.mcp

Source: https://hexdocs.pm/ash_ai/api-reference

Sets up an MCP server for your application.

```APIDOC
## mix ash_ai.gen.mcp

### Description
Sets up an MCP server for your application.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### AshAi.Actions.Prompt.Adapter run Callback Definition

Source: https://hexdocs.pm/ash_ai/AshAi.Actions.Prompt

This code snippet shows the Elixir callback definition for the `run` function within the AshAi.Actions.Prompt.Adapter. It outlines the expected parameters (`data` and `opts`) and the possible return types (`{:ok, term}` or `{:error, term}`).

```elixir
@callback run(data :: AshAi.Actions.Prompt.Adapter.Data.t(), opts :: Keyword.t()) ::
  {:ok, term()} | {:error, term()}
```

--------------------------------

### AshAi.Actions.Prompt.Adapter.CompletionTool

Source: https://hexdocs.pm/ash_ai/api-reference

An adapter that provides a "complete_request" tool that the LLM must call within `max_runs` messages to complete the request.

```APIDOC
## AshAi.Actions.Prompt.Adapter.CompletionTool

### Description
An adapter that provides a "complete_request" tool that the LLM must call within `max_runs` messages to complete the request.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Default Prompt Template for EEx and LangChain

Source: https://hexdocs.pm/ash_ai/AshAi.Actions

This code snippet shows the default prompt template used for processing EEx templates and LangChain messages. It includes placeholders for action details, descriptions, and arguments, utilizing EEx syntax for dynamic content insertion. It also demonstrates how to format action inputs using `Ash.ActionInput.fetch_argument` and `Ash.Type.dump_to_embedded`.

```elixir
{
  "You are responsible for performing the <%= @input.action.name %> action.\n\n<%= if @input.action.description do %>\n# Description\n<%= @input.action.description %>\n<% end %>\n\n## Inputs\n<%= for argument <- @input.action.arguments do %>\n- <%= argument.name %><%= if argument.description do %>: <%= argument.description %>\n<% end %>\n<% end %>\n",
  "# Action Inputs\n\n<%= for argument <- @input.action.arguments,\n    {:ok, value} = Ash.ActionInput.fetch_argument(@input, argument.name),\n    {:ok, value} = Ash.Type.dump_to_embedded(argument.type, value, argument.constraints) do %>\n  - <%= argument.name %>: <%= Jason.encode!(value) %>\n<% end %>\n"
}
```

--------------------------------

### Ash Resource Actions Implementation: run/3

Source: https://hexdocs.pm/ash_ai/AshAi.Actions

This code represents the callback implementation for `Ash.Resource.Actions.Implementation.run/3`. This function is central to executing actions defined within Ash resources, allowing for dynamic generation of results based on input and context.

```elixir
def run(input, opts, context)
# Callback implementation for `Ash.Resource.Actions.Implementation.run/3`.
```

--------------------------------

### Dynamic LLM Model Configuration with AshAi Prompt

Source: https://hexdocs.pm/ash_ai/AshAi.Actions

Shows how to dynamically configure the LangChain model for the `prompt/2` function at runtime. This is achieved by passing a 2-arity function as the first argument to `prompt/2`, allowing for environment variable-based configuration of API keys and endpoints.

```elixir
run prompt(
  fn _input, _context ->
    LangChain.ChatModels.ChatOpenAI.new!(%{  
      model: "gpt-4o",
      api_key: System.get_env("OPENAI_API_KEY"),
      endpoint: System.get_env("OPENAI_ENDPOINT")
    })
  end,
  tools: false
)
```

--------------------------------

### mix ash_ai.gen.chat

Source: https://hexdocs.pm/ash_ai/api-reference

Generates the resources and views for a conversational UI backed by `ash_postgres` and `ash_oban`.

```APIDOC
## mix ash_ai.gen.chat

### Description
Generates the resources and views for a conversational UI backed by `ash_postgres` and `ash_oban`.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### AshAi.Actions.Prompt.Adapter.RequestJson

Source: https://hexdocs.pm/ash_ai/api-reference

This adapter is designed for LLMs that don't support native tool calling or structured outputs. It embeds the JSON schema in the system prompt and uses LangChain's JsonProcessor to extract the JSON response from markdown code blocks.

```APIDOC
## AshAi.Actions.Prompt.Adapter.RequestJson

### Description
This adapter is designed for LLMs that don't support native tool calling or structured outputs. It embeds the JSON schema in the system prompt and uses LangChain's JsonProcessor to extract the JSON response from markdown code blocks.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Expose Ash Actions as AI Tools

Source: https://hexdocs.pm/ash_ai/index

Defines how to expose Ash resource actions as callable tools for AI agents. This allows an LLM to interact with your data layer by calling predefined actions like reading or creating posts. Ensure actions and their arguments/return data are configured for appropriate access levels (public/private).

```elixir
defmodule MyApp.Blog do
  use Ash.Domain, extensions: [AshAi]

  tools do
    tool :read_posts, MyApp.Blog.Post, :read
    tool :create_post, MyApp.Blog.Post, :create
    tool :publish_post, MyApp.Blog.Post, :publish
    tool :read_comments, MyApp.Blog.Comment, :read
  end
end
```

```elixir
tools do
  # Returns only public attributes
  tool :read_posts, MyApp.Blog.Post, :read
  
  # 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
```

--------------------------------

### Expose Actions as Tool Calls with Ash AI

Source: https://hexdocs.pm/ash_ai/readme

This snippet demonstrates how to expose Ecto actions as tools that can be used by Ash AI. By defining tools within the `tools` block of an Ash.Domain, you make Ecto actions available for LLM-driven operations. These tools can then be utilized by functions like `AshAi.setup_ash_ai/2` or `AshAi.iex_chat/2`.

```elixir
defmodule MyApp.Blog do
  use Ash.Domain, extensions: [AshAi]

  tools do
    tool :read_posts, MyApp.Blog.Post, :read
    tool :create_post, MyApp.Blog.Post, :create
    tool :publish_post, MyApp.Blog.Post, :publish
    tool :read_comments, MyApp.Blog.Comment, :read
  end
end
```

--------------------------------

### Generate Chat Feature with Ash AI

Source: https://hexdocs.pm/ash_ai/readme

Generates a chat feature for Ash & Phoenix applications using `ash_oban`, `ash_postgres`, and `pub_sub`. The `--live` flag generates liveviews.

```bash
mix ash_ai.gen.chat --live

```

--------------------------------

### Configure Full-Text Vectorization (AshAi.Vectorize)

Source: https://hexdocs.pm/ash_ai/dsl-ashai

This snippet details the configuration for full-text vectorization. It allows specifying the embedding model, attributes to vectorize, the strategy for vector computation (e.g., after action, manual, or using Ash Oban), and options for defining update actions. It also covers how to specify the text source for vectorization.

```elixir
# Example for vectorize.full_text configuration
vectorize do
  full_text do
    embedding_model Application.get_env(:my_app, :embedding_model)
    attributes(name: :text_vector, columns: [:content, :summary])
    strategy :after_action
    define_update_action_for_manual_strategy? true
  end
end
```

--------------------------------

### Monitor Tool Execution with Callbacks in Ash AI

Source: https://hexdocs.pm/ash_ai/readme

This snippet shows how to monitor tool execution in real-time using callbacks with `AshAi.setup_ash_ai/2`. The `on_tool_start` and `on_tool_end` callbacks receive event data, enabling actions like progress indication, logging, metrics collection, or debugging during tool execution.

```elixir
chain
|> AshAi.setup_ash_ai(
  actor: current_user,
  on_tool_start: fn %AshAi.ToolStartEvent{} = event ->
    # event includes: tool_name, action, resource, arguments, actor, tenant
    IO.puts("Starting #{event.tool_name}...")
  end,
  on_tool_end: fn %AshAi.ToolEndEvent{} = event ->
    # event includes: tool_name, result ({:ok, ...} or {:error, ...})
    IO.puts("Completed #{event.tool_name}")
  end
)
```

--------------------------------

### Configure Dev MCP Server Plug

Source: https://hexdocs.pm/ash_ai/index

This Elixir code configures the development Model Context Protocol (MCP) server by adding `AshAi.Mcp.Dev` plug to your endpoint module's `code_reloading?` block. It specifies the protocol version and the OTP app.

```elixir
if code_reloading? do
  socket "/phoenix/live_reload/socket", Phoenix.LiveReloader.Socket

  plug AshAi.Mcp.Dev,
    # see the note below on protocol versions below
    protocol_version_statement: "2024-11-05",
    otp_app: :your_app
end

```

--------------------------------

### Configure Dev MCP Server Plug

Source: https://hexdocs.pm/ash_ai/readme

Adds the AshAi.Mcp.Dev plug to the Phoenix endpoint for the development MCP server. The server is typically accessible at http://localhost:4000/ash_ai/mcp.

```elixir
if code_reloading? do
    socket "/phoenix/live_reload/socket", Phoenix.LiveReloader.Socket

    plug AshAi.Mcp.Dev,
      # see the note below on protocol versions below
      protocol_version_statement: "2024-11-05",
      otp_app: :your_app
end

```

--------------------------------

### Generate Chat Resources with Ash AI

Source: https://hexdocs.pm/ash_ai/Mix.Tasks.AshAi.Gen

Generates conversational UI resources (`Conversation` and `Message`) using `ash_ai`, backed by `ash_postgres` and `ash_oban`. It supports specifying a user resource and domain for placement. Extensions can be passed through to `mix ash.gen.resource`.

```mix
mix ash_ai.gen.chat --user Your.User.Resource --live
```

--------------------------------

### Add Ash AI Dependency to Mix Project

Source: https://hexdocs.pm/ash_ai/index

This code snippet shows how to add Ash AI as a project dependency in your `mix.exs` file. Ensure you use a compatible version.

```elixir
def deps do
  [
    {:ash_ai, "~> 0.2"}
  ]
end

```

--------------------------------

### AshAi.Mcp.Router

Source: https://hexdocs.pm/ash_ai/api-reference

MCP Router implementing the RPC functionality over HTTP.

```APIDOC
## AshAi.Mcp.Router

### Description
MCP Router implementing the RPC functionality over HTTP.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Expose Ash Action as LLM Tool (AshAi.Tool)

Source: https://hexdocs.pm/ash_ai/dsl-ashai

This snippet demonstrates how to expose an Ash action as a tool callable by LLMs. It allows configuration of parameters, loading of attributes (including private ones), async execution, and identity management. Private attributes can be loaded but not used for filtering or sorting.

```elixir
tool name, resource, action
```

--------------------------------

### AshAi.Checks.ActorIsAshAi: prefer_expanded_description? Callback Implementation

Source: https://hexdocs.pm/ash_ai/AshAi.Checks

Implements the `prefer_expanded_description?/0` callback for Ash.Policy.Check. This function specifies whether a more detailed, expanded description of the policy check is preferred. This can be useful for generating more informative documentation or logs.

```elixir
def prefer_expanded_description?(), do: false
# Callback implementation for `Ash.Policy.Check.prefer_expanded_description?/0`.
```

--------------------------------

### Configure API Key Authentication for MCP

Source: https://hexdocs.pm/ash_ai/readme

Sets up an API key authentication strategy for the MCP pipeline using AshAuthentication. This allows for optional authentication by setting `required?: false`.

```elixir
pipeline :mcp do
  plug AshAuthentication.Strategy.ApiKey.Plug,
    resource: YourApp.Accounts.User,
    # Use `required?: false` to allow unauthenticated
    # users to connect, for example if some tools
    # are publicly accessible.
    required?: false
end

```

--------------------------------

### AshAi.Checks.ActorIsAshAi: describe Callback Implementation

Source: https://hexdocs.pm/ash_ai/AshAi.Checks

Implements the `describe/1` callback for Ash.Policy.Check. This function is used to provide a human-readable description of the policy check, aiding in debugging and understanding policy rules. It takes an argument representing the check's configuration.

```elixir
def describe(_), do: ""
# Callback implementation for `Ash.Policy.Check.describe/1`.
```

--------------------------------

### AshAi Tool API

Source: https://hexdocs.pm/ash_ai/dsl-ashai

Exposes an Ash action as a tool that can be called by LLMs, allowing them to interact with your application by calling specific actions on resources.

```APIDOC
## POST /websites/hexdocs_pm_ash_ai/tools/tool

### Description
Expose an Ash action as a tool that can be called by LLMs. Tools allow LLMs to interact with your application by calling specific actions on resources. Only public attributes can be used for filtering, sorting, and aggregation, but the `load` option allows including private attributes in the response data.

### Method
POST

### Endpoint
`/websites/hexdocs_pm_ash_ai/tools/tool`

### Parameters
#### Path Parameters

#### Query Parameters

#### Request Body
- **name** (atom) - Required - The name of the tool.
- **resource** (module) - Required - The Ash resource to interact with.
- **action** (atom) - Required - The Ash action to expose.
- **action_parameters** (list(atom)) - Optional - A list of action specific parameters to allow for the underlying action. Only relevant for reads, and defaults to allowing `[:sort, :offset, :limit, :result_type, :filter]`.
- **load** (any) - Optional - A list of relationships and calculations to load on the returned records. Note that loaded fields can include private attributes, which will then be included in the tool's response. However, private attributes cannot be used for filtering, sorting, or aggregation.
- **async** (boolean) - Optional - Defaults to `true`.
- **description** (String.t) - Optional - A description for the tool. Defaults to the action's description.
- **identity** (atom) - Optional - The identity to use for update/destroy actions. Defaults to the primary key. Set to `false` to disable entirely.

### Request Example
```json
{
  "name": "list_users",
  "resource": "User",
  "action": ":read",
  "action_parameters": [":sort", ":limit"],
  "load": [":posts"],
  "description": "List available users with their posts."
}
```

### Response
#### Success Response (200)
- **tool_name** (string) - The name of the tool that was created.
- **resource** (string) - The resource the tool is associated with.
- **action** (string) - The action the tool performs.

#### Response Example
```json
{
  "tool_name": "list_users",
  "resource": "User",
  "action": "read"
}
```
```

--------------------------------

### Add Production MCP Server to Router

Source: https://hexdocs.pm/ash_ai/readme

Integrates the AshAi.Mcp.Router into the Phoenix application's router for the production MCP server. It supports specifying a list of tools and a protocol version statement.

```elixir
scope "/mcp" do
  pipe_through :mcp

  forward "/", AshAi.Mcp.Router,
    tools: [
      :list,
      :of,
      :tools
    ],
    # For many tools, you will need to set the `protocol_version_statement` to the older version.
    protocol_version_statement: "2024-11-05",
    otp_app: :my_app
end

```

--------------------------------

### Create PostgreSQL Vector Index using HNSW

Source: https://hexdocs.pm/ash_ai/index

Provides a PostgreSQL configuration snippet for creating a HNSW (Hierarchical Navigable Small Worlds) index on a vector column within the 'embeddings' table. This optimizes vector search performance at the cost of increased memory and build time. It requires a `MyApp.Repo` definition.

```elixir
postgres do
    table "embeddings"
    repo MyApp.Repo

    custom_statements do
      statement :vector_idx do
        up "CREATE INDEX vector_idx ON embeddings USING hnsw (vectorized_body vector_cosine_ops) WITH (m = 16, ef_construction = 64)"
        down "DROP INDEX vector_idx;"
      end
    end
  end
```

--------------------------------

### Specify OpenAI API Key Environment Variable

Source: https://hexdocs.pm/ash_ai/index

This indicates how to set your OpenAI API key as an environment variable, which is required for the default LLM provider used by `mix ash_ai.gen.chat`.

```bash
OPEN_API_KEY=sk_...

```

--------------------------------

### Ash AI: Ash Oban Strategy for Asynchronous Vectorization

Source: https://hexdocs.pm/ash_ai/readme

Configures the 'ash_oban' strategy for asynchronous embedding updates. This requires the 'ash_oban' dependency and specifies how to integrate Oban triggers for embedding updates.

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

  vectorize do
    full_text do
      # ... text and used_attributes configuration ...
    end

    strategy :ash_oban
    ash_oban_trigger_name :my_vectorize_trigger
    # ... other vectorize options ...
  end

  oban do
    triggers do
      trigger :my_vectorize_trigger do
        action :ash_ai_update_embeddings
        queue :artist_vectorizer
        worker_read_action :read
        worker_module_name __MODULE__.AshOban.Worker.UpdateEmbeddings
        scheduler_module_name __MODULE__.AshOban.Scheduler.UpdateEmbeddings
        scheduler_cron false
        list_tenants MyApp.ListTenants
      end
    end
  end
end
```

--------------------------------

### Dynamic LangChain Messages via Function in AshAi Prompt

Source: https://hexdocs.pm/ash_ai/AshAi.Actions

Demonstrates generating LangChain messages dynamically using a function within `prompt/2`. This function processes conversation history from input arguments to construct the message list, enabling flexible and context-aware LLM interactions. It maps role-based messages from input to LangChain's message format.

```elixir
run prompt(
  ChatOpenAI.new!(%{model: "gpt-4o"}),
  prompt: fn input, context ->
    base = [Message.new_system!("You are helpful")]

    history = input.arguments.conversation_history
    |> Enum.map(fn %{"role" => role, "content" => content} ->
      case role do
        "user" -> Message.new_user!(content)
        "assistant" -> Message.new_assistant!(content)
      end
    end)

    base ++ history
  end
)
```

--------------------------------

### AshAi Vectorize API

Source: https://hexdocs.pm/ash_ai/dsl-ashai

Configure vectorization for data within Ash, allowing for efficient similarity searches and retrieval.

```APIDOC
## POST /websites/hexdocs_pm_ash_ai/vectorize

### Description
Configure vectorization for data within Ash, allowing for efficient similarity searches and retrieval. This API allows defining how data should be vectorized and stored.

### Method
POST

### Endpoint
`/websites/hexdocs_pm_ash_ai/vectorize`

### Parameters
#### Path Parameters

#### Query Parameters

#### Request Body
- **embedding_model** (module) - Required - The embedding model to use for vectorization.
- **attributes** (keyword) - Required - A keyword list of attributes to vectorize, and the name of the attribute to store the vector in.
- **strategy** (:after_action | :manual | :ash_oban | :ash_oban_manual) - Optional - Defaults to `:after_action`. How to compute the vector. Currently supported strategies are `:after_action`, `:manual`, and `:ash_oban`.
- **define_update_action_for_manual_strategy?** (boolean) - Optional - Defaults to `true`. If true, an `ash_ai_update_embeddings` update action will be defined, which will automatically update the embeddings when run.
- **ash_oban_trigger_name** (atom) - Optional - Defaults to `:ash_ai_update_embeddings`. The name of the AshOban-trigger that will be run in order to update the record's embeddings.

### Request Example
```json
{
  "embedding_model": "MyEmbeddingModel",
  "attributes": {
    "content": ":content_vector"
  },
  "strategy": ":after_action"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the vectorization configuration was applied.

#### Response Example
```json
{
  "message": "Vectorization configured successfully."
}
```
```

```APIDOC
## POST /websites/hexdocs_pm_ash_ai/vectorize/full_text

### Description
Configure full-text vectorization for specific text fields.

### Method
POST

### Endpoint
`/websites/hexdocs_pm_ash_ai/vectorize/full_text`

### Parameters
#### Path Parameters

#### Query Parameters

#### Request Body
- **text** ((any -> any)) - Required - A function or expr that takes a list of records and computes a full text string that will be vectorized. If given an expr, use `atomic_ref` to refer to new values, as this is set as an atomic update.
- **name** (atom) - Optional - Defaults to `:full_text_vector`. The name of the attribute to store the text vector in.
- **used_attributes** (list(atom)) - Optional - If set, a vector is only regenerated when these attributes are changed.

### Request Example
```json
{
  "text": "fn(records) -> Enum.map(records, fn r -> r.title <> " " <> r.body end)",
  "name": ":full_text_vector",
  "used_attributes": [":title", ":body"]
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the full-text vectorization was configured.

#### Response Example
```json
{
  "message": "Full-text vectorization configured successfully."
}
```
```

--------------------------------

### POST /websites/hexdocs_pm_ash_ai/session/{session_id}

Source: https://hexdocs.pm/ash_ai/AshAi.Mcp

Processes an HTTP POST request containing JSON-RPC messages for a given session.

```APIDOC
## POST /websites/hexdocs_pm_ash_ai/session/{session_id}

### Description
Processes an HTTP POST request containing JSON-RPC messages for a given session.

### Method
POST

### Endpoint
/websites/hexdocs_pm_ash_ai/session/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier for the session.

#### Query Parameters
- **opts** (object) - Optional - Options for processing the request.

#### Request Body
- **messages** (array) - Required - An array of JSON-RPC messages to be processed.
  - **message** (object) - A single JSON-RPC message.
    - **jsonrpc** (string) - Required - The version of JSON-RPC (e.g., "2.0").
    - **method** (string) - Required - The method to be invoked.
    - **params** (object) - Optional - Parameters for the method.
    - **id** (string|number) - Required - The identifier for the request.

### Request Example
```json
{
  "messages": [
    {
      "jsonrpc": "2.0",
      "method": "process_data",
      "params": {"input": "example data"},
      "id": "req-123"
    }
  ]
}
```

### Response
#### Success Response (200)
- **responses** (array) - An array of JSON-RPC responses corresponding to the processed messages.
  - **response** (object) - A single JSON-RPC response.
    - **jsonrpc** (string) - The version of JSON-RPC.
    - **result** (any) - The result of the method execution (if successful).
    - **error** (object) - An error object (if an error occurred).
      - **code** (number) - The error code.
      - **message** (string) - The error message.
    - **id** (string|number) - The identifier for the response.

#### Response Example
```json
{
  "responses": [
    {
      "jsonrpc": "2.0",
      "result": "processed data",
      "id": "req-123"
    }
  ]
}
```
```

--------------------------------

### Add Source Pointer to Built Error (AshAi)

Source: https://hexdocs.pm/ash_ai/AshAi

The `with_source_pointer` function associates a source pointer with a built error. This can be helpful for debugging and tracking the origin of errors.

```elixir
with_source_pointer(built_error, arg2)
```

--------------------------------

### Generate Chat Feature with Custom User Resource

Source: https://hexdocs.pm/ash_ai/index

This command generates a chat feature, allowing you to specify a custom user resource if it's not named `<YourApp>.Accounts.User`.

```bash
mix ash_ai.gen.chat --user YourApp.CustomUser

```

--------------------------------

### AshAi.Checks.ActorIsAshAi: match? Callback Implementation

Source: https://hexdocs.pm/ash_ai/AshAi.Checks

Implements the `match?/3` callback for Ash.Policy.SimpleCheck. This function is used to determine if a given actor, context, and options match the criteria defined by the simple check. It's a fundamental part of Ash's simple policy checking capabilities.

```elixir
def match?(arg1, _, _) do
  # Callback implementation for `Ash.Policy.SimpleCheck.match?/3`.
end
```

--------------------------------

### AshAi.Changes.VectorizeAfterAction change/3 Callback

Source: https://hexdocs.pm/ash_ai/AshAi.Changes

Callback implementation for `Ash.Resource.Change.change/3`. This function is part of the Ash framework and is used for handling changes to resources.

```Elixir
change(changeset, opts, context)
```

--------------------------------

### Querying Vector Data with Ash AI

Source: https://hexdocs.pm/ash_ai/readme

This Elixir code demonstrates how to query data based on vector similarity using Ash AI. It defines a read action that takes a query string, generates a vector embedding for it using a specified embedding model, and then filters and sorts the results based on cosine distance. It requires an embedding model to be configured.

```elixir
read :search do
  argument :query, :string, allow_nil?: false

  prepare before_action(fn query, context ->
    case YourEmbeddingModel.generate([query.arguments.query], []) do
      {:ok, [search_vector]} ->
        Ash.Query.filter(
          query,
          vector_cosine_distance(full_text_vector, ^search_vector) < 0.5
        )
        |> Ash.Query.sort(
          {calc(vector_cosine_distance(full_text_vector, ^search_vector),
             type: :float
           ), :asc}
        )
        |> Ash.Query.limit(10)

      {:error, error} ->
        {:error, error}
    end
  end)
end
```

--------------------------------

### Using Custom Types for Structured Outputs in Ash AI

Source: https://hexdocs.pm/ash_ai/readme

This snippet demonstrates how to use custom types, like `Ash.TypedStruct`, for structured outputs in prompt-backed actions with Ash AI. The action `parse_job` is defined to return a `JobListing` struct, ensuring that the LLM output conforms to the specified schema, making data parsing more robust.

```elixir
defmodule JobListing do
  use Ash.TypedStruct

  typed_struct do
    field :title, :string, allow_nil?: false
    field :company, :string, allow_nil?: false
    field :location, :string
    field :requirements, {:array, :string}
  end
end

action :parse_job, JobListing do
  argument :raw_content, :string, allow_nil?: false

  run prompt(
    LangChain.ChatModels.ChatOpenAI.new!(%{model: "gpt-4o-mini"}),
    prompt: "Parse this job listing: <%= @input.arguments.raw_content %>",
    tools: false
  )
end
```

--------------------------------

### Ash AI: Configure Full Text Vectorization

Source: https://hexdocs.pm/ash_ai/readme

Defines how to vectorize full text content for AI features. It specifies the text extraction logic, attributes to use for embedding, the vectorization strategy, and the embedding model.

```elixir
vectorize do
  full_text do
    text(fn record ->
      """
      Name: #{record.name}
      Biography: #{record.biography}
      """
    end)

    used_attributes [:name, :biography]
  end

  strategy :after_action
  attributes(name: :vectorized_name, biography: :vectorized_biography)

  embedding_model MyApp.OpenAiEmbeddingModel
end
```
Tokens:
Raw