documentation/dsls/DSL-AshAi.md

Select File:
documentation/dsls/DSL-AshAi.md

<!--
This file was generated by Spark. Do not edit it by hand.
-->
# AshAi

Documentation for `AshAi`.


## tools


### Nested DSLs
 * [tool](#tools-tool)
   * argument





### tools.tool
```elixir
tool name, resource, action
```


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.


### Nested DSLs
 * [argument](#tools-tool-argument)


### Examples
```
tool :list_artists, Artist, :read
```

```
tool :create_artist, Artist, :create, description: "Create a new artist"
```

```
tool :update_artist, Artist, :update, identity: :id, load: [:albums]
```

```
tool :get_board, Board, :read, _meta: %{"openai/outputTemplate" => "ui://widget/kanban-board.html", "openai/toolInvocation/invoking" => "Preparing the board…", "openai/toolInvocation/invoked" => "Board ready."}
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#tools-tool-name){: #tools-tool-name .spark-required} | `atom` |  |  |
| [`resource`](#tools-tool-resource){: #tools-tool-resource .spark-required} | `module` |  |  |
| [`action`](#tools-tool-action){: #tools-tool-action .spark-required} | `atom` |  |  |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`action_parameters`](#tools-tool-action_parameters){: #tools-tool-action_parameters } | `list(atom)` |  | 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`](#tools-tool-load){: #tools-tool-load } | `any` | `[]` | A list of relationships and calculations to load, or an anonymous function/1. 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. If a function is provided, it will be called with the tool input (a Map with **String keys**) and must return the final load list. ## Example load fn input ->   [schedule: [date: input["date"]]] # Use string keys! end |
| [`async`](#tools-tool-async){: #tools-tool-async } | `boolean` | `true` |  |
| [`description`](#tools-tool-description){: #tools-tool-description } | `String.t` |  | A description for the tool. Defaults to the action's description. |
| [`identity`](#tools-tool-identity){: #tools-tool-identity } | `atom` |  | The identity to use for update/destroy actions. Defaults to the primary key. Set to `false` to disable entirely. |
| [`_meta`](#tools-tool-_meta){: #tools-tool-_meta } | `any` | `%{}` | Optional metadata map for tool integrations. Supports provider-specific extensions like OpenAI metadata. Keys and values should be strings to comply with JSON-RPC serialization. |


### tools.tool.argument
```elixir
argument name, type
```


An argument to be passed to the tool.





### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#tools-tool-argument-name){: #tools-tool-argument-name .spark-required} | `atom` |  | The name of the argument. |
| [`type`](#tools-tool-argument-type){: #tools-tool-argument-type .spark-required} | `any` |  | The Ash type of the argument (e.g., :string, :date, :integer). |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`constraints`](#tools-tool-argument-constraints){: #tools-tool-argument-constraints } | `keyword` | `[]` | Type constraints (e.g., [max_length: 10]). These are converted to JSON Schema rules. |
| [`description`](#tools-tool-argument-description){: #tools-tool-argument-description } | `String.t` |  | A description for the Agent. |
| [`allow_nil?`](#tools-tool-argument-allow_nil?){: #tools-tool-argument-allow_nil? } | `boolean` | `true` | If set to `false`, the argument is marked as required in the generated JSON Schema. |
| [`default`](#tools-tool-argument-default){: #tools-tool-argument-default } | `any` |  | The default value if not provided. |





### Introspection

Target: `AshAi.Tool.Argument`




### Introspection

Target: `AshAi.Tool`




## vectorize


### Nested DSLs
 * [full_text](#vectorize-full_text)





### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`embedding_model`](#vectorize-embedding_model){: #vectorize-embedding_model .spark-required} | `module` |  |  |
| [`attributes`](#vectorize-attributes){: #vectorize-attributes } | `keyword` | `[]` | A keyword list of attributes to vectorize, and the name of the attribute to store the vector in |
| [`strategy`](#vectorize-strategy){: #vectorize-strategy } | `:after_action \| :manual \| :ash_oban \| :ash_oban_manual` | `:after_action` | How to compute the vector. Currently supported strategies are `:after_action`, `:manual`, and `:ash_oban`. |
| [`define_update_action_for_manual_strategy?`](#vectorize-define_update_action_for_manual_strategy?){: #vectorize-define_update_action_for_manual_strategy? } | `boolean` | `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`](#vectorize-ash_oban_trigger_name){: #vectorize-ash_oban_trigger_name } | `atom` | `:ash_ai_update_embeddings` | The name of the AshOban-trigger that will be run in order to update the record's embeddings. Defaults to `:ash_ai_update_embeddings`. |



### vectorize.full_text









### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`text`](#vectorize-full_text-text){: #vectorize-full_text-text .spark-required} | `(any -> any)` |  | 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`](#vectorize-full_text-name){: #vectorize-full_text-name } | `atom` | `:full_text_vector` | The name of the attribute to store the text vector in |
| [`used_attributes`](#vectorize-full_text-used_attributes){: #vectorize-full_text-used_attributes } | `list(atom)` |  | If set, a vector is only regenerated when these attributes are changed |





### Introspection

Target: `AshAi.FullText`




## mcp_resources


### Nested DSLs
 * [mcp_resource](#mcp_resources-mcp_resource)





### mcp_resources.mcp_resource
```elixir
mcp_resource name, uri, resource, action
```


An MCP resource to expose via the Model Context Protocol (MCP).
MCP Resources are different to Ash Resources. Here they are used to
respond to LLM models with static or dynamic assets like files, images, or JSON.

The resource description defaults to the action's description. You can override this
by providing a `description` option which takes precedence.




### Examples
```
mcp_resource :artist_card, "file://info/artist_info.txt", Artist, :artist_info
```

```
mcp_resource :artist_card, "file://ui/artist_card.html", Artist, :artist_card, mime_type: "text/html"
```

```
mcp_resource :artist_data, "file://data/artist.json", Artist, :to_json, description: "Artist metadata as JSON", mime_type: "application/json"
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#mcp_resources-mcp_resource-name){: #mcp_resources-mcp_resource-name .spark-required} | `atom` |  |  |
| [`uri`](#mcp_resources-mcp_resource-uri){: #mcp_resources-mcp_resource-uri .spark-required} | `String.t` |  | The URI where the resource can be accessed. |
| [`resource`](#mcp_resources-mcp_resource-resource){: #mcp_resources-mcp_resource-resource .spark-required} | `module` |  |  |
| [`action`](#mcp_resources-mcp_resource-action){: #mcp_resources-mcp_resource-action .spark-required} | `atom` |  |  |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`title`](#mcp_resources-mcp_resource-title){: #mcp_resources-mcp_resource-title .spark-required} | `String.t` |  | A short, human-readable title for the resource. |
| [`description`](#mcp_resources-mcp_resource-description){: #mcp_resources-mcp_resource-description } | `String.t` |  | A description of the resource. This is important for LLM to determine what the resource is and when to call it. Defaults to the Action's description if not provided. |
| [`mime_type`](#mcp_resources-mcp_resource-mime_type){: #mcp_resources-mcp_resource-mime_type } | `String.t` | `"text/plain"` | The MIME type of the resource, e.g. 'application/json', 'image/png', etc. |





### Introspection

Target: `AshAi.McpResource`





<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>