# `LedgerUI.Components.Ai`
[🔗](https://github.com/devaction-labs/ledger_ui/blob/v0.2.0/lib/ledger_ui/components/ai.ex#L1)

The assistant ("Assistente (IA)"): the conversation, its messages, the proposals the user
approves, the queries the assistant shows it made, the field to ask, the list of conversations
and the starting suggestions. The assistant proposes and the user approves; nothing changes
without a confirmation.

    <.ai_chat id="assistente" messages={@messages} user={@current_user}
      on_send="send" on_approve="approve" on_reject="reject" />

Or piece by piece (`ai_message/1`, `ai_proposal/1`, `ai_tool_trace/1`, `ai_composer/1`,
`conversation_list/1`, `prompt_suggestions/1`, `ai_insights/1`, `ai_promo/1`, `ai_greeting/1`).

A message of `ai_chat` is a map: `:id`, `:role` (`:user` or `:assistant`), `:text` (paragraphs
separated by a blank line, `**bold**` is bold), `:name` (of the user, for the avatar), `:trace`
(`%{tools: [...], duration_ms: 3000, running: false}`), `:proposal` (`%{id:, title:, status:,
changes: [%{label:, from:, to:, text:}], note:, editable:}`), `:streaming` and `:status`.
`messages` can be a list or a LiveView stream (`stream(socket, :messages, ...)`).

The composer is a form: Enter sends, Shift+Enter breaks the line (hook `LedgerUI.AiComposer`,
file `priv/static/ledger_ui/hooks/ai_composer.js`).

# `ai_chat`

The whole conversation: greeting and suggestions, the messages and the field to ask.
## Attributes

* `id` (`:string`) (required)
* `messages` (`:any`) - A list of message maps or a stream of them. Defaults to `[]`.
* `user` (`:any`) - Defaults to `nil`.
* `streaming` (`:boolean`) - Defaults to `false`.
* `context` (`:list`) - Defaults to `[]`.
* `mention` (`:boolean`) - Defaults to `false`.
* `mention_label` (`:string`) - Defaults to `"Mencionar"`.
* `variant` (`:string`) - Defaults to `"card"`. Must be one of `"card"`, `"bare"`, or `"page"`.
* `draft` (`:string`) - Defaults to `nil`.
* `greeting` (`:string`) - Defaults to `nil`.
* `start` (`:boolean`) - Shows the greeting and suggestions (or `:empty`) while a list has no messages. Defaults to `true`.
* `footnote` (`:string`) - Defaults to `nil`.
* `composer` (`:boolean`) - Defaults to `true`.
* `placeholder` (`:string`) - Defaults to `"Pergunte sobre pedidos, estoque, fiscal ou financeiro"`.
* `on_send` (`:any`) - Defaults to `nil`.
* `on_change` (`:any`) - Defaults to `nil`.
* `on_stop` (`:any`) - Defaults to `nil`.
* `on_approve` (`:any`) - Defaults to `nil`.
* `on_reject` (`:any`) - Defaults to `nil`.
* `on_undo` (`:any`) - Defaults to `nil`.
* `on_pick` (`:any`) - Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` - Extra content after the messages.
* `empty` - Shown above the messages in place of the greeting and suggestions.
* `header` - The title and subtitle of the conversation, in the header of the `card`.
* `suggestion` - A starting card; the content is its text. Accepts attributes:

  * `title` (`:string`)
  * `prompt` (`:string`)

# `ai_composer`

The field to ask the assistant: context chips, text, attachment and send (a form).
## Attributes

* `id` (`:string`) - Needed for Enter-to-send (the hook needs a stable id). Defaults to `nil`.
* `variant` (`:string`) - Defaults to `"default"`. Must be one of `"default"`, or `"canvas"`.
* `send_label` (`:string`) - Defaults to `"Enviar"`.
* `mic` (`:boolean`) - Defaults to `false`.
* `on_mic` (`:any`) - Defaults to `nil`.
* `mention` (`:boolean`) - Shows the mention (@) button. Defaults to `false`.
* `on_mention` (`:any`) - Defaults to `nil`.
* `mention_label` (`:string`) - Defaults to `"Mencionar"`.
* `field` (`Phoenix.HTML.FormField`) - Defaults to `nil`.
* `name` (`:string`) - Defaults to `nil`.
* `value` (`:string`) - Defaults to `nil`.
* `context` (`:list`) - Defaults to `[]`.
* `attachments` (`:list`) - Defaults to `[]`.
* `upload` (`:any`) - Defaults to `nil`.
* `streaming` (`:boolean`) - Defaults to `false`.
* `on_stop` (`:any`) - Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `placeholder` (`:string`) - Defaults to `"Pergunte sobre pedidos, estoque, fiscal ou financeiro"`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["autocomplete", "phx-submit", "phx-change", "phx-target"]`.
## Slots

* `chip` - A custom chip, after the context ones.

# `ai_greeting`

The greeting of the assistant: the first line in a gradient and the question under it.
## Attributes

* `name` (`:string`) - Who is greeted; `Bom dia` / `Boa tarde` / `Boa noite` by the hour. Defaults to `nil`.
* `greeting` (`:string`) - Replaces the whole first line. Defaults to `nil`.
* `tagline` (`:string`) - Defaults to `"Em que posso ajudar hoje?"`.
* `size` (`:string`) - Defaults to `"lg"`. Must be one of `"sm"`, `"md"`, or `"lg"`.
* `tone` (`:string`) - Defaults to `"brand"`. Must be one of `"brand"`, or `"warm"`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `ai_insights`

Card of AI insights: icon, title, sentence with bold numbers, impact badge and action.
## Attributes

* `insights` (`:list`) (required) - Maps `%{icon, title, text, impact, tone, action, href, navigate, patch, style}`; `**bold**` in `text` is bold.
* `variant` (`:string`) - `card` has the header; `list` is the items only. Defaults to `"card"`. Must be one of `"card"`, or `"list"`.
* `title` (`:string`) - Defaults to `"AI insights"`.
* `count` (`:integer`) - Number of new insights, as a badge in the header. Defaults to `nil`.
* `count_label` (`:string`) - Defaults to `"new"`.
* `on_chat` (`:any`) - Shows the chat button in the header; an event name or a `JS` command. Defaults to `nil`.
* `chat_label` (`:string`) - Defaults to `"Abrir chat"`.
* `target` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `ai_message`

A message of the conversation.
## Attributes

* `role` (`:string`) - Defaults to `"assistant"`. Must be one of `"user"`, or `"assistant"`.
* `variant` (`:string`) - `card` frames the assistant's content; `plain` is loose text beside the spark. Defaults to `"card"`. Must be one of `"card"`, or `"plain"`.
* `streaming` (`:boolean`) - Shows the blinking cursor (`lu-stream-cursor`) after the last paragraph. Defaults to `false`.
* `status` (`:string`) - Defaults to `"ok"`. Must be one of `"ok"`, or `"error"`.
* `name` (`:string`) - The user's name: its initials make the avatar. Defaults to `nil`.
* `actions` (`:list`) - Buttons under the content: `copy`, `useful`, `useless`, `regenerate`. Defaults to `[]`.
* `on_action` (`:any`) - Event name (payload `%{action}`) or `JS` command. Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` (required)
* `trace` - The queries the assistant made, above the content.

# `ai_promo`

Call to the assistant pinned on the sidebar, with insight count and main action.
## Attributes

* `title` (`:string`) - Defaults to `"Assistente"`.
* `count` (`:integer`) - Number of new suggestions/insights. Defaults to `nil`.
* `subtitle` (`:string`) - Replaces the default "N novas sugestões". Defaults to `nil`.
* `text` (`:string`) - A sentence under the title (card variant). Defaults to `nil`.
* `action` (`:string`) - Label of the main action button (card variant). Defaults to `nil`.
* `variant` (`:string`) - Defaults to `"card"`. Must be one of `"card"`, or `"rail"`.
* `tone` (`:string`) - Defaults to `"brand"`. Must be one of `"brand"`, or `"warm"`.
* `on_click` (`:any`) - Event name or `JS` command of the call (the action for `card`). Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `ai_proposal`

An action the assistant proposes, which only happens when the user approves.
## Attributes

* `id` (`:string`) (required)
* `title` (`:string`) (required) - What will be done.
* `heading` (`:string`) - Title of the card header. Defaults to `"Proposta"`.
* `status` (`:any`) - `pending`, `applying`, `approved`, `rejected` or `failed`, as an atom or a string. Defaults to `"pending"`.
* `pending_label` (`:string`) - Defaults to `"Aguardando você"`.
* `pending_note` (`:string`) - Defaults to `nil`.
* `layout` (`:string`) - Defaults to `"list"`. Must be one of `"list"`, `"definition"`, or `"table"`.
* `headers` (`:list`) - Column headers of the `table` layout. Defaults to `["Regra", "Atual", "Proposto"]`.
* `editable` (`:boolean`) - Defaults to `false`.
* `note` (`:string`) - Defaults to `nil`.
* `on_approve` (`:any`) - Defaults to `nil`.
* `on_reject` (`:any`) - Defaults to `nil`.
* `on_undo` (`:any`) - Defaults to `nil`.
* `on_edit` (`:any`) - Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `action` - A button in the footer of a failed proposal.
* `change` - A row of the proposal. Accepts attributes:

  * `label` (`:string`)
  * `from` (`:string`)
  * `to` (`:string`)
* `impact` - The effect in numbers. Accepts attributes:

  * `label` (`:string`)
* `preview` - A preview of the message or document. Accepts attributes:

  * `label` (`:string`)

# `ai_tool_trace`

What the assistant consulted: summary (count and time) and one row per query.
## Attributes

* `tools` (`:list`) - Maps `%{label, title, detail, ms, icon, failed, running}`. Defaults to `[]`.
* `steps` (`:list`) - The same as `tools`. Defaults to `[]`.
* `running` (`:boolean`) - The queries are still going on. Defaults to `false`.
* `expanded` (`:boolean`) - Opens the list of queries. Defaults to `false`.
* `duration_ms` (`:integer`) - The total time, shown in seconds. Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `conversation_list`

The conversations of the assistant, by day, with a button for a new one and a search.
## Attributes

* `conversations` (`:list`) (required) - Maps `%{id, title, status, day, pending, content, href, navigate, patch}`.
* `active` (`:any`) - The `id` of the open conversation. Defaults to `nil`.
* `current` (`:any`) - The same as `active`. Defaults to `nil`.
* `search` (`:string`) - Defaults to `""`.
* `group_by` (`:atom`) - Defaults to `:day`. Must be one of `:day`.
* `variant` (`:string`) - Defaults to `"card"`. Must be one of `"card"`, or `"rail"`.
* `title` (`:string`) - Defaults to `"Assistente"`.
* `shortcut` (`:string`) - Defaults to `"⌘ J"`.
* `new_label` (`:string`) - Defaults to `"Nova conversa"`.
* `on_new` (`:any`) - Defaults to `nil`.
* `on_search` (`:any`) - Defaults to `nil`.
* `on_select` (`:any`) - Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `item` - The content of an item, in place of the title and status. Accepts attributes:

  * `conversation` (`:map`)

# `prompt_suggestions`

The starting suggestions: cards, pills or a grey grid.
## Attributes

* `items` (`:list`) (required) - Maps `%{title, text, icon, tone, delay}`; a pill shows the `text`.
* `tilt` (`:boolean`) - Tilts the cards (decorative). Defaults to `true`.
* `variant` (`:string`) - Defaults to `"card"`. Must be one of `"card"`, `"pill"`, or `"grid"`.
* `on_pick` (`:any`) - Event name (payload `%{value, title}`) or `JS` command. Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
