feat: convert LLM markdown to Telegram HTML

[T0ha]

Summary

• Add Bodhi.Telegram.Formatter module that parses LLM markdown via MDEx AST and renders Telegram-compatible HTML (<b>, <i>, <code>, <pre>, <a>, <blockquote>, <s>)
• Messages are sent with parse_mode: "HTML" and automatically split at block boundaries when exceeding Telegram's 4096 char limit
• Update send_message behaviour/adapter to accept optional opts keyword list for passing parse_mode and other Telegram API options

Test plan

• 28 unit tests for Bodhi.Telegram.Formatter (format + split)
• All existing webhook handler and periodic message tests updated for 3-arg send_message
• mix compile — no new warnings
• mix dialyzer — 0 errors
• mix format — clean

🤖 Generated with Claude Code

[claude]

test

[claude]

PR Review: feat/telegram-markdown

Overall a well-structured addition. Clean module design, correct HTML escaping, and solid test coverage. A few issues worth addressing before merge.

Bug: LLM response record created before send succeeds

File: lib/bodhi/tg_webhook_handler.ex

Previously maybe_create_llm_response ran inside the with block, only on a successful send. Now it runs unconditionally before Enum.reduce_while. If all Telegram API calls fail, an orphaned LLM response record is created with no corresponding message. This is a regression from the previous behaviour.

Fix: move maybe_create_llm_response(metadata) inside the {:ok, message} branch — only the first chunk needs it.

Hard split does not handle single lines over 4096 chars

File: lib/bodhi/telegram/formatter.ex

hard_split/1 splits at newlines then packs lines into chunks. But if a single line exceeds 4096 chars (e.g. a long base64 blob or a code block with no internal newlines), chunk_lines includes it as-is with no length check, violating Telegram limit. A fallback that byte-splits lines exceeding @max_length is needed.

Unnecessary default arg on @impl functions

In telegex_adapter.ex and telegram.ex the behaviour callback is send_message/3, but the default opts param silently creates a send_message/2 outside the behaviour contract. Since every call site passes 3 args, remove the default to keep implementations strictly matching callback arity.

periodic_messages_test assertion may be fragile

The test asserts text == prompt_text but text is now the HTML-formatted version. It passes today because the test prompt contains no markdown. Any prompt with bold, inline code, or other markdown will cause a mismatch. Consider asserting against elem(Formatter.format(prompt_text), 0) instead.

Minor: escape_attr/1 is a transparent alias for escape/1

Fine as a semantic placeholder for potential future URL-specific encoding. A short comment explaining the intent would help future maintainers.

Positives

• HTML escaping is correctly applied in all render paths including attribute values
• Block-boundary splitting before line-level fallback is the right strategy
• Fallback to escape(markdown) on MDEx parse error is safe and correct
• 28 unit tests cover edge cases well: nil input, nested formatting, oversized blocks
• Typespec on format/1 correctly reflects the return shape

[claude]

This is a web application written using the Phoenix web framework.

Project Structure

Key Features

Daily Dialog Summarization System

The application includes an automatic dialog summarization system to optimize AI context and reduce API costs:

Database Schema:

• Migration: priv/repo/migrations/20260127085112_create_message_summaries.exs
• message_summaries table stores daily summaries with fields:
  • chat_id (references chats, on_delete: :delete_all) - Which chat
  • summary_text (text, not null) - AI-generated summary
  • summary_date (date, not null) - Date being summarized
  • message_count (integer, default: 0) - Number of messages
  • start_time, end_time (naive_datetime) - Temporal boundaries
  • ai_model (string) - Which AI backend generated the summary
  • inserted_at, updated_at (timestamps)
• Indexes:
  • Unique index on (chat_id, summary_date) for idempotency
  • Index on chat_id for fast lookups
  • Index on summary_date for date-based queries

Core Modules:

• Bodhi.Chats.Summary (lib/bodhi/chats/summary.ex) - Ecto schema for message_summaries table
• Bodhi.Chats (lib/bodhi/chats.ex) - Extended with summary functions:
  • get_chat_context_for_ai/2 - Main context assembly function (line ~168)
  • get_summaries_before_date/2, get_recent_messages/2 - Query helpers
  • get_active_chats_for_date/1, get_messages_for_date/2 - Date-based queries
  • create_summary/1, get_summary/2 - CRUD operations
  • build_context/3 (private) - Context builder
• Bodhi.Chats.Summarizer (lib/bodhi/chats/summarizer.ex) - Shared summarization logic
  • generate_and_store/3 - Calls AI and persists summary
  • build_summarization_prompt/1 - Builds prompt for AI
  • current_ai_model/0 - Returns configured AI model name
• Bodhi.Workers.DailyChatSummarizer (lib/bodhi/workers/daily_chat_summarizer.ex) - Oban worker
  • Runs daily at 2 AM UTC via Oban Cron plugin
  • Processes all active chats sequentially
  • Creates summaries for previous day's messages
  • Refactored to reduce nesting depth (credo compliant)
• Bodhi.Release (lib/bodhi/release.ex) - Release tasks including:
  • backfill_summaries/1 - Migration tool for historical data (line ~26)
  • Supports dry-run, date ranges, and chat filtering
• Bodhi.TgWebhookHandler (lib/bodhi/tg_webhook_handler.ex) - Updated at line ~130
  • Uses get_chat_context_for_ai/2 instead of get_chat_messages/1

Context Assembly:

• Bodhi.Chats.get_chat_context_for_ai/2 assembles context from:
  • Summaries for messages older than 7 days (configurable)
  • Full messages from last 7 days
• Used by TgWebhookHandler.get_answer/2 instead of get_chat_messages/1
• Gracefully falls back to recent messages when no summaries exist

Configuration:

# config/config.exs
config :bodhi, :summarization, recent_days: 7

config :bodhi, Oban,
  plugins: [
    {Oban.Plugins.Cron,
     crontab: [{"0 2 * * *", Bodhi.Workers.DailyChatSummarizer}]}
  ]

Documentation:

• docs/SUMMARIZATION.md - Implementation details and usage
• docs/DEPLOYMENT.md - Deployment and backfill procedures

Key Guidelines:

• Summaries are idempotent - safe to regenerate
• Worker processes chats sequentially to respect rate limits
• Backfill tool supports dry-run mode for cost estimation
• Summary messages use user_id: -1 as a special marker

Project guidelines

• Use mix precommit alias when you are done with all changes and fix any pending issues
• Use the already included and available :req (Req) library for HTTP requests, avoid :httpoison, :tesla, and :httpc. Req is included by default and is the preferred HTTP client for Phoenix apps

Phoenix v1.8 guidelines

• Always begin your LiveView templates with <Layouts.app flash={@flash} ...> which wraps all inner content
• The MyAppWeb.Layouts module is aliased in the my_app_web.ex file, so you can use it without needing to alias it again
• Anytime you run into errors with no current_scope assign:
  • You failed to follow the Authenticated Routes guidelines, or you failed to pass current_scope to <Layouts.app>
  • Always fix the current_scope error by moving your routes to the proper live_session and ensure you pass current_scope as needed
• Phoenix v1.8 moved the <.flash_group> component to the Layouts module. You are forbidden from calling <.flash_group> outside of the layouts.ex module
• Out of the box, core_components.ex imports an <.icon name="hero-x-mark" class="w-5 h-5"/> component for for hero icons. Always use the <.icon> component for icons, never use Heroicons modules or similar
• Always use the imported <.input> component for form inputs from core_components.ex when available. <.input> is imported and using it will will save steps and prevent errors
• If you override the default input classes (<.input class="myclass px-2 py-1 rounded-lg">)) class with your own values, no default classes are inherited, so your
  custom classes must fully style the input

JS and CSS guidelines

• Use Tailwind CSS classes and custom CSS rules to create polished, responsive, and visually stunning interfaces.

• Tailwindcss v4 no longer needs a tailwind.config.js and uses a new import syntax in app.css:

  @import "tailwindcss" source(none);
  @source "../css";
  @source "../js";
  @source "../../lib/my_app_web";
  

• Always use and maintain this import syntax in the app.css file for projects generated with phx.new

• Never use @apply when writing raw css

• Always manually write your own tailwind-based components instead of using daisyUI for a unique, world-class design

• Out of the box only the app.js and app.css bundles are supported

  • You cannot reference an external vendor'd script src or link href in the layouts
  • You must import the vendor deps into app.js and app.css to use them
  • Never write inline <script>custom js</script> tags within templates

UI/UX & design guidelines

• Produce world-class UI designs with a focus on usability, aesthetics, and modern design principles
• Implement subtle micro-interactions (e.g., button hover effects, and smooth transitions)
• Ensure clean typography, spacing, and layout balance for a refined, premium look
• Focus on delightful details like hover effects, loading states, and smooth page transitions

phoenix:ecto usage

Ecto Guidelines

• Always preload Ecto associations in queries when they'll be accessed in templates, ie a message that needs to reference the message.user.email
• Remember import Ecto.Query and other supporting modules when you write seeds.exs
• Ecto.Schema fields always use the :string type, even for :text, columns, ie: field :name, :string
• Ecto.Changeset.validate_number/2 DOES NOT SUPPORT the :allow_nil option. By default, Ecto validations only run if a change for the given field exists and the change value is not nil, so such as option is never needed
• You must use Ecto.Changeset.get_field(changeset, :field) to access changeset fields
• Fields which are set programatically, such as user_id, must not be listed in cast calls or similar for security purposes. Instead they must be explicitly set when creating the struct
• Always invoke mix ecto.gen.migration migration_name_using_underscores when generating migration files, so the correct timestamp and conventions are applied

phoenix:elixir usage

Elixir guidelines

• Elixir lists do not support index based access via the access syntax

  Never do this (invalid):

  i = 0
  mylist = ["blue", "green"]
  mylist[i]
  

  Instead, always use Enum.at, pattern matching, or List for index based list access, ie:

  i = 0
  mylist = ["blue", "green"]
  Enum.at(mylist, i)
  

• Elixir variables are immutable, but can be rebound, so for block expressions like if, case, cond, etc
  you must bind the result of the expression to a variable if you want to use it and you CANNOT rebind the result inside the expression, ie:

  # INVALID: we are rebinding inside the `if` and the result never gets assigned
  if connected?(socket) do
    socket = assign(socket, :val, val)
  end
  
  # VALID: we rebind the result of the `if` to a new variable
  socket =
    if connected?(socket) do
      assign(socket, :val, val)
    end
  

• Never nest multiple modules in the same file as it can cause cyclic dependencies and compilation errors

• Never use map access syntax (changeset[:field]) on structs as they do not implement the Access behaviour by default. For regular structs, you must access the fields directly, such as my_struct.field or use higher level APIs that are available on the struct if they exist, Ecto.Changeset.get_field/2 for changesets

• Elixir's standard library has everything necessary for date and time manipulation. Familiarize yourself with the common Time, Date, DateTime, and Calendar interfaces by accessing their documentation as necessary. Never install additional dependencies unless asked or for date/time parsing (which you can use the date_time_parser package)

• Don't use String.to_atom/1 on user input (memory leak risk)

• Predicate function names should not start with is_ and should end in a question mark. Names like is_thing should be reserved for guards

• Elixir's builtin OTP primitives like DynamicSupervisor and Registry, require names in the child spec, such as {DynamicSupervisor, name: MyApp.MyDynamicSup}, then you can use DynamicSupervisor.start_child(MyApp.MyDynamicSup, child_spec)

• Use Task.async_stream(collection, callback, options) for concurrent enumeration with back-pressure. The majority of times you will want to pass timeout: :infinity as option

Mix guidelines

• Read the docs and options before using tasks (by using mix help task_name)
• To debug test failures, run tests in a specific file with mix test test/my_test.exs or run all previously failed tests with mix test --failed
• mix deps.clean --all is almost never needed. Avoid using it unless you have good reason

Test guidelines

• Always use start_supervised!/1 to start processes in tests as it guarantees cleanup between tests
• Avoid Process.sleep/1 and Process.alive?/1 in tests

  • Instead of sleeping to wait for a process to finish, always use Process.monitor/1 and assert on the DOWN message:

    ref = Process.monitor(pid)
    assert_receive {:DOWN, ^ref, :process, ^pid, :normal}

  • Instead of sleeping to synchronize before the next call, always use _ = :sys.get_state/1 to ensure the process has handled prior messages

phoenix:html usage

Phoenix HTML guidelines

• Phoenix templates always use ~H or .html.heex files (known as HEEx), never use ~E

• Always use the imported Phoenix.Component.form/1 and Phoenix.Component.inputs_for/1 function to build forms. Never use Phoenix.HTML.form_for or Phoenix.HTML.inputs_for as they are outdated

• When building forms always use the already imported Phoenix.Component.to_form/2 (assign(socket, form: to_form(...)) and <.form for={@form} id="msg-form">), then access those forms in the template via @form[:field]

• Always add unique DOM IDs to key elements (like forms, buttons, etc) when writing templates, these IDs can later be used in tests (<.form for={@form} id="product-form">)

• For "app wide" template imports, you can import/alias into the my_app_web.ex's html_helpers block, so they will be available to all LiveViews, LiveComponent's, and all modules that do use MyAppWeb, :html (replace "my_app" by the actual app name)

• Elixir supports if/else but does NOT support if/else if or if/elsif. Never use else if or elseif in Elixir, always use cond or case for multiple conditionals.

  Never do this (invalid):

  <%= if condition do %>
    ...
  <% else if other_condition %>
    ...
  <% end %>
  

  Instead always do this:

  <%= cond do %>
    <% condition -> %>
      ...
    <% condition2 -> %>
      ...
    <% true -> %>
      ...
  <% end %>
  

• HEEx require special tag annotation if you want to insert literal curly's like { or }. If you want to show a textual code snippet on the page in a <pre> or <code> block you must annotate the parent tag with phx-no-curly-interpolation:

  <code phx-no-curly-interpolation>
    let obj = {key: "val"}
  </code>
  

  Within phx-no-curly-interpolation annotated tags, you can use { and } without escaping them, and dynamic Elixir expressions can still be used with <%= ... %> syntax

• HEEx class attrs support lists, but you must always use list [...] syntax. You can use the class list syntax to conditionally add classes, always do this for multiple class values:

  <a class={[
    "px-2 text-white",
    @some_flag && "py-5",
    if(@other_condition, do: "border-red-500", else: "border-blue-100"),
    ...
  ]}>Text</a>
  

  and always wrap if's inside {...} expressions with parens, like done above (if(@other_condition, do: "...", else: "..."))

  and never do this, since it's invalid (note the missing [ and ]):

  <a class={
    "px-2 text-white",
    @some_flag && "py-5"
  }> ...
  => Raises compile syntax error on invalid HEEx attr syntax
  

• Never use <% Enum.each %> or non-for comprehensions for generating template content, instead always use <%= for item <- @collection do %>

• HEEx HTML comments use <%!-- comment --%>. Always use the HEEx HTML comment syntax for template comments (<%!-- comment --%>)

• HEEx allows interpolation via {...} and <%= ... %>, but the <%= %> only works within tag bodies. Always use the {...} syntax for interpolation within tag attributes, and for interpolation of values within tag bodies. Always interpolate block constructs (if, cond, case, for) within tag bodies using <%= ... %>.

  Always do this:

  <div id={@id}>
    {@my_assign}
    <%= if @some_block_condition do %>
      {@another_assign}
    <% end %>
  </div>
  

  and Never do this – the program will terminate with a syntax error:

  <%!-- THIS IS INVALID NEVER EVER DO THIS --%>
  <div id="<%= @invalid_interpolation %>">
    {if @invalid_block_construct do}
    {end}
  </div>
  

phoenix:liveview usage

Phoenix LiveView guidelines

• Never use the deprecated live_redirect and live_patch functions, instead always use the <.link navigate={href}> and <.link patch={href}> in templates, and push_navigate and push_patch functions LiveViews
• Avoid LiveComponent's unless you have a strong, specific need for them
• LiveViews should be named like AppWeb.WeatherLive, with a Live suffix. When you go to add LiveView routes to the router, the default :browser scope is already aliased with the AppWeb module, so you can just do live "/weather", WeatherLive

LiveView streams

• Always use LiveView streams for collections for assigning regular lists to avoid memory ballooning and runtime termination with the following operations:

  • basic append of N items - stream(socket, :messages, [new_msg])
  • resetting stream with new items - stream(socket, :messages, [new_msg], reset: true) (e.g. for filtering items)
  • prepend to stream - stream(socket, :messages, [new_msg], at: -1)
  • deleting items - stream_delete(socket, :messages, msg)

• When using the stream/3 interfaces in the LiveView, the LiveView template must 1) always set phx-update="stream" on the parent element, with a DOM id on the parent element like id="messages" and 2) consume the @streams.stream_name collection and use the id as the DOM id for each child. For a call like stream(socket, :messages, [new_msg]) in the LiveView, the template would be:

  <div id="messages" phx-update="stream">
    <div :for={{id, msg} <- @streams.messages} id={id}>
      {msg.text}
    </div>
  </div>
  

• LiveView streams are not enumerable, so you cannot use Enum.filter/2 or Enum.reject/2 on them. Instead, if you want to filter, prune, or refresh a list of items on the UI, you must refetch the data and re-stream the entire stream collection, passing reset: true:

  def handle_event("filter", %{"filter" => filter}, socket) do
    # re-fetch the messages based on the filter
    messages = list_messages(filter)
  
    {:noreply,
     socket
     |> assign(:messages_empty?, messages == [])
     # reset the stream with the new messages
     |> stream(:messages, messages, reset: true)}
  end
  

• LiveView streams do not support counting or empty states. If you need to display a count, you must track it using a separate assign. For empty states, you can use Tailwind classes:

  <div id="tasks" phx-update="stream">
    <div class="hidden only:block">No tasks yet</div>
    <div :for={{id, task} <- @stream.tasks} id={id}>
      {task.name}
    </div>
  </div>
  

  The above only works if the empty state is the only HTML block alongside the stream for-comprehension.

• When updating an assign that should change content inside any streamed item(s), you MUST re-stream the items
  along with the updated assign:

  def handle_event("edit_message", %{"message_id" => message_id}, socket) do
    message = Chat.get_message!(message_id)
    edit_form = to_form(Chat.change_message(message, %{content: message.content}))
  
    # re-insert message so @editing_message_id toggle logic takes effect for that stream item
    {:noreply,
     socket
     |> stream_insert(:messages, message)
     |> assign(:editing_message_id, String.to_integer(message_id))
     |> assign(:edit_form, edit_form)}
  end
  

  And in the template:

  <div id="messages" phx-update="stream">
    <div :for={{id, message} <- @streams.messages} id={id} class="flex group">
      {message.username}
      <%= if @editing_message_id == message.id do %>
        <%!-- Edit mode --%>
        <.form for={@edit_form} id="edit-form-#{message.id}" phx-submit="save_edit">
          ...
        </.form>
      <% end %>
    </div>
  </div>
  

• Never use the deprecated phx-update="append" or phx-update="prepend" for collections

LiveView JavaScript interop

• Remember anytime you use phx-hook="MyHook" and that JS hook manages its own DOM, you must also set the phx-update="ignore" attribute
• Always provide an unique DOM id alongside phx-hook otherwise a compiler error will be raised

LiveView hooks come in two flavors, 1) colocated js hooks for "inline" scripts defined inside HEEx,
and 2) external phx-hook annotations where JavaScript object literals are defined and passed to the LiveSocket constructor.

Inline colocated js hooks

Never write raw embedded <script> tags in heex as they are incompatible with LiveView.
Instead, always use a colocated js hook script tag (:type={Phoenix.LiveView.ColocatedHook})
when writing scripts inside the template:

<input type="text" name="user[phone_number]" id="user-phone-number" phx-hook=".PhoneNumber" />
<script :type={Phoenix.LiveView.ColocatedHook} name=".PhoneNumber">
  export default {
    mounted() {
      this.el.addEventListener("input", e => {
        let match = this.el.value.replace(/\D/g, "").match(/^(\d{3})(\d{3})(\d{4})$/)
        if(match) {
          this.el.value = `${match[1]}-${match[2]}-${match[3]}`
        }
      })
    }
  }
</script>

• colocated hooks are automatically integrated into the app.js bundle
• colocated hooks names MUST ALWAYS start with a . prefix, i.e. .PhoneNumber

External phx-hook

External JS hooks (<div id="myhook" phx-hook="MyHook">) must be placed in assets/js/ and passed to the
LiveSocket constructor:

const MyHook = {
  mounted() { ... }
}
let liveSocket = new LiveSocket("/live", Socket, {
  hooks: { MyHook }
});

Pushing events between client and server

Use LiveView's push_event/3 when you need to push events/data to the client for a phx-hook to handle.
Always return or rebind the socket on push_event/3 when pushing events:

# re-bind socket so we maintain event state to be pushed
socket = push_event(socket, "my_event", %{...})

# or return the modified socket directly:
def handle_event("some_event", _, socket) do
  {:noreply, push_event(socket, "my_event", %{...})}
end

Pushed events can then be picked up in a JS hook with this.handleEvent:

mounted() {
  this.handleEvent("my_event", data => console.log("from server:", data));
}

Clients can also push an event to the server and receive a reply with this.pushEvent:

mounted() {
  this.el.addEventListener("click", e => {
    this.pushEvent("my_event", { one: 1 }, reply => console.log("got reply from server:", reply));
  })
}

Where the server handled it via:

def handle_event("my_event", %{"one" => 1}, socket) do
  {:reply, %{two: 2}, socket}
end

LiveView tests

• Phoenix.LiveViewTest module and LazyHTML (included) for making your assertions

• Form tests are driven by Phoenix.LiveViewTest's render_submit/2 and render_change/2 functions

• Come up with a step-by-step test plan that splits major test cases into small, isolated files. You may start with simpler tests that verify content exists, gradually add interaction tests

• Always reference the key element IDs you added in the LiveView templates in your tests for Phoenix.LiveViewTest functions like element/2, has_element/2, selectors, etc

• Never tests again raw HTML, always use element/2, has_element/2, and similar: assert has_element?(view, "#my-form")

• Instead of relying on testing text content, which can change, favor testing for the presence of key elements

• Focus on testing outcomes rather than implementation details

• Be aware that Phoenix.Component functions like <.form> might produce different HTML than expected. Test against the output HTML structure, not your mental model of what you expect it to be

• When facing test failures with element selectors, add debug statements to print the actual HTML, but use LazyHTML selectors to limit the output, ie:

  html = render(view)
  document = LazyHTML.from_fragment(html)
  matches = LazyHTML.filter(document, "your-complex-selector")
  IO.inspect(matches, label: "Matches")
  

Form handling

Creating a form from params

If you want to create a form based on handle_event params:

def handle_event("submitted", params, socket) do
  {:noreply, assign(socket, form: to_form(params))}
end

When you pass a map to to_form/1, it assumes said map contains the form params, which are expected to have string keys.

You can also specify a name to nest the params:

def handle_event("submitted", %{"user" => user_params}, socket) do
  {:noreply, assign(socket, form: to_form(user_params, as: :user))}
end

Creating a form from changesets

When using changesets, the underlying data, form params, and errors are retrieved from it. The :as option is automatically computed too. E.g. if you have a user schema:

defmodule MyApp.Users.User do
  use Ecto.Schema
  ...
end

And then you create a changeset that you pass to to_form:

%MyApp.Users.User{}
|> Ecto.Changeset.change()
|> to_form()

Once the form is submitted, the params will be available under %{"user" => user_params}.

In the template, the form form assign can be passed to the <.form> function component:

<.form for={@form} id="todo-form" phx-change="validate" phx-submit="save">
  <.input field={@form[:field]} type="text" />
</.form>

Always give the form an explicit, unique DOM ID, like id="todo-form".

Avoiding form errors

Always use a form assigned via to_form/2 in the LiveView, and the <.input> component in the template. In the template always access forms this:

<%!-- ALWAYS do this (valid) --%>
<.form for={@form} id="my-form">
  <.input field={@form[:field]} type="text" />
</.form>

And never do this:

<%!-- NEVER do this (invalid) --%>
<.form for={@changeset} id="my-form">
  <.input field={@changeset[:field]} type="text" />
</.form>

• You are FORBIDDEN from accessing the changeset in the template as it will cause errors
• Never use <.form let={f} ...> in the template, instead always use <.form for={@form} ...>, then drive all form references from the form assign as in @form[:field]. The UI should always be driven by a to_form/2 assigned in the LiveView module that is derived from a changeset

phoenix:phoenix usage

Phoenix guidelines

• Remember Phoenix router scope blocks include an optional alias which is prefixed for all routes within the scope. Always be mindful of this when creating routes within a scope to avoid duplicate module prefixes.

• You never need to create your own alias for route definitions! The scope provides the alias, ie:

  scope "/admin", AppWeb.Admin do
    pipe_through :browser
  
    live "/users", UserLive, :index
  end
  

  the UserLive route would point to the AppWeb.Admin.UserLive module

• Phoenix.View no longer is needed or included with Phoenix, don't use it

igniter usage

A code generation and project patching framework

Rules for working with Igniter

Understanding Igniter

Igniter is a code generation and project patching framework that enables semantic manipulation of Elixir codebases. It provides tools for creating intelligent generators that can both create new files and modify existing ones safely. Igniter works with AST (Abstract Syntax Trees) through Sourceror.Zipper to make precise, context-aware changes to your code.

Available Modules

Project-Level Modules (Igniter.Project.*)

• Igniter.Project.Application - Working with Application modules and application configuration
• Igniter.Project.Config - Modifying Elixir config files (config.exs, runtime.exs, etc.)
• Igniter.Project.Deps - Managing dependencies declared in mix.exs
• Igniter.Project.Formatter - Interacting with .formatter.exs files
• Igniter.Project.IgniterConfig - Managing .igniter.exs configuration files
• Igniter.Project.MixProject - Updating project configuration in mix.exs
• Igniter.Project.Module - Creating and managing modules with proper file placement
• Igniter.Project.TaskAliases - Managing task aliases in mix.exs
• Igniter.Project.Test - Working with test and test support files

Code-Level Modules (Igniter.Code.*)

• Igniter.Code.Common - General purpose utilities for working with Sourceror.Zipper
• Igniter.Code.Function - Working with function definitions and calls
• Igniter.Code.Keyword - Manipulating keyword lists
• Igniter.Code.List - Working with lists in AST
• Igniter.Code.Map - Manipulating maps
• Igniter.Code.Module - Working with module definitions and usage
• Igniter.Code.String - Utilities for string literals
• Igniter.Code.Tuple - Working with tuples

[claude]

defmodule Bodhi.MixProject do
use Mix.Project

def project do
[
app: :bodhi,
version: "0.1.0",
elixir: "~> 1.12",
elixirc_paths: elixirc_paths(Mix.env()),
compilers: [:phoenix_live_view] ++ Mix.compilers(),
start_permanent: Mix.env() == :prod,
listeners: [Phoenix.CodeReloader],
aliases: aliases(),
deps: deps(),
usage_rules: usage_rules(),
dialyzer: [
ignore_warnings: ".dialyzer_ignore.exs",
plt_add_apps: [
:mix
]
]
]
end

Configuration for the OTP application.

Type mix help compile.app for more information.

def application do
[
mod: {Bodhi.Application, []},
extra_applications: [:logger]
]
end

Specifies which paths to compile per environment.

defp elixirc_paths(:test), do: ["lib", "test/support"]
defp elixirc_paths(_), do: ["lib"]

Specifies your project dependencies.

Type mix help deps for examples and options.

defp deps do
[
{:tidewave, "> 0.5", only: [:dev]},
{:phoenix, "> 1.8.0"},
{:phoenix_ecto, "> 4.5"},
{:ecto_sql, "> 3.10"},
{:postgrex, ">= 0.0.0"},
{:phoenix_html, "> 4.1"},
{:phoenix_live_reload, "> 1.2", only: :dev},
{:phoenix_live_view, "> 1.0"},
{:floki, ">= 0.30.0", only: :test},
{:phoenix_live_dashboard, "> 0.8.3"},
{:esbuild, "> 0.8", runtime: Mix.env() == :dev},
{:heroicons,
github: "tailwindlabs/heroicons",
tag: "v2.1.1",
sparse: "optimized",
app: false,
compile: false,
depth: 1},
{:swoosh, "> 1.5"},
{:finch, "> 0.13"},
{:telemetry_metrics, "> 1.0"},
{:telemetry_poller, "> 1.0"},
{:gettext, "> 0.26"},
{:jason, "> 1.2"},
{:dns_cluster, "> 0.1.1"},
{:bandit, "> 1.5"},
{:req, "> 0.5"},
{:tailwind, "> 0.2", runtime: Mix.env() == :dev},
{:lazy_html, ">= 0.1.0", only: :test},
{:live_debugger, "> 0.3.1", only: :dev},
{:telegex, "> 1.8"},
{:multipart, "> 0.4.0"},
{:oban, "> 2.17"},
{:oban_web, "> 2.11.1"},
{:igniter, "> 0.5", only: [:dev]},
{:usage_rules, "> 1.2", only: [:dev]},
{:posthog, "> 2.0"},
{:nebulex, "> 2.6"},
{:decorator, "> 1.4"},
{:mdex, "> 0.9.0"},
{:credo, "> 1.7", runtime: false},
{:dialyxir, "> 1.4", runtime: false},
{:faker, "> 0.18.0", only: [:test]},
{:ex_machina, "> 2.8", only: [:test]},
{:mox, "> 1.0", only: [:test]},
{:excoveralls, "> 0.14", only: [:test], runtime: false}
]
end

defp usage_rules do
[
file: "AGENTS.md",
usage_rules: [
"phoenix:all",
:igniter
]
]
end

Aliases are shortcuts or tasks specific to the current project.

For example, to install project dependencies and perform other setup tasks, run:

$ mix setup

See the documentation for Mix for more info on aliases.

defp aliases do
[
precommit: ["format", "credo --strict", "dialyzer", "test"],
setup: ["deps.get", "ecto.setup"],
"ecto.setup": ["ecto.create", "ecto.migrate", "run priv/repo/seeds.exs"],
"ecto.reset": ["ecto.drop", "ecto.setup"],
test: ["ecto.create --quiet", "ecto.migrate --quiet", "test"],
"assets.setup": ["tailwind.install --if-missing", "esbuild.install --if-missing"],
"assets.build": ["compile", "tailwind bodhi", "esbuild bodhi"],
"assets.deploy": [
"tailwind bodhi --minify",
"esbuild bodhi --minify",
"phx.digest"
]
]
end
end

[claude]

PR Review: feat/telegram-markdown

Overall this is a solid, well-structured feature with good test coverage. The three-level splitting strategy and clean module separation are commendable. A few issues worth addressing before merge:

[claude]

PR Review: feat/telegram-markdown

Overall this is a solid, well-structured feature with good test coverage. The three-level splitting strategy and clean module separation are commendable. A few issues worth addressing before merge:

BUG: Chunk ordering when first block requires hard-splitting

File: lib/bodhi/telegram/formatter.ex

In chunk_blocks/2, the empty-accumulator clause handles an oversized block via:

defp chunk_blocks([block | rest], []) do
  ...
  hard_split(block) ++ chunk_blocks(rest, [])
  ...
end

The problem: hard_split/1 returns chunks in reversed order (because chunk_lines builds its accumulator reversed and returns it as-is). chunk_blocks(rest, []) also returns in reversed order. Concatenating two independently-reversed lists and then calling Enum.reverse/1 once at the split/1 level does not restore correct order.

Example: first block hard-splits into ["last_chunk", "first_chunk"] (reversed), rest = ["B"]:

• Combined: ["last_chunk", "first_chunk", "B"]
• After Enum.reverse/1: ["B", "first_chunk", "last_chunk"]
• Expected: ["first_chunk", "last_chunk", "B"]

The other call site in chunk_blocks([block | rest], [current | done]) is correct because the reversed chunks are pushed into the accumulator (also reversed), and a single final Enum.reverse/1 restores correct order for everything at once.

Fix: Reverse hard_split/1 output before concatenating in the empty-acc clause:

defp chunk_blocks([block | rest], []) do
  if String.length(block) <= @max_length do
    chunk_blocks(rest, [block])
  else
    Enum.reverse(hard_split(block)) ++ chunk_blocks(rest, [])
  end
end

This scenario occurs when an LLM response begins with a large code block (> 4096 chars) followed by more content - realistic in practice. There is no test covering "first block needs hard-split AND there are subsequent blocks"; adding one would catch regressions.

---

MINOR: CodeBlock info string should use only the first word as language

File: lib/bodhi/telegram/formatter.ex

CommonMark allows arbitrary text in the fenced code block info string (e.g., backtick-backtick-backtick python title="example.py" or backtick-backtick-backtick elixir iex). Passing the full string as the CSS class produces an invalid class name (language-elixir iex).

Fix - extract only the language token:

defp render_node(%MDEx.CodeBlock{info: info, literal: text}) do
  lang = info |> String.split(" ", parts: 2) |> List.first()
  if lang != "" do
    "<pre><code class=\"language-#{escape(lang)}\">" <>
      escape(text) <> "</code></pre>"
  else
    "<pre><code>" <> escape(text) <> "</code></pre>"
  end
end

---

MINOR: ^text pin in webhook handler test may be fragile

File: test/bodhi/tg_webhook_handler_test.exs

The expectation fn ^chat_id, ^text, _opts -> pins the pre-formatted text, but send_message/3 now HTML-escapes text before sending. If the fixture text ever contains &, <, >, or ", the pin will fail. Should pin against the formatted value, as was done in periodic_messages_test.exs:

{expected_html, _} = Bodhi.Telegram.Formatter.format(text)
expect(Bodhi.TelegramMock, :send_message, fn ^chat_id, ^expected_html, _opts ->

---

What's done well

• Lazy LLM response creation: llm_id = llm_id || maybe_create_llm_response(metadata) correctly creates the record only after the first successful send and reuses it for subsequent chunks.
• HTML escaping: Applied consistently in all render paths including URL attributes and code block info strings.
• Graceful MDEx fallback: {:error, _} -> escape(markdown) is safe and correct.
• Split strategy: Block to line to grapheme fallback is the right hierarchy.
• Test coverage: 28 tests cover important edge cases; split/1 tests are especially thorough.
• escape_attr/1: The comment explaining future intent is helpful for maintainers.

[claude]

PR Review: feat: convert LLM markdown to Telegram HTML

Overall this is a solid, well-structured feature. The approach (MDEx AST → Telegram HTML subset, block-boundary splitting, deferred LLM response record) is sensible and the test coverage is good. Below are my observations, grouped by severity.

---

Issues / Bugs

1. chunk_lines/2 accumulates chunks in reverse but never reverses them

hard_split/1 calls chunk_lines(lines, []) and returns the accumulator directly. Like chunk_blocks/2, items are prepended with [line, current | done], so the final list is in reverse order. chunk_blocks/2 calls Enum.reverse() at the call site (split/1), but hard_split/1 is also used inside chunk_blocks/2 where its result is immediately prepended onto the done list—effectively reversing it again by accident. There is a test that partially catches this ("first block hard-split preserves order with subsequent blocks"), but the test only checks List.last(chunks) =~ "tail" and String.length <= 4096, not the internal ordering of the hard-split chunks. A multi-line block that gets hard-split will have its lines reversed.

# hard_split should reverse its accumulator before returning:
defp hard_split(text) do
  text
  |> String.split("\n")
  |> chunk_lines([])
  |> Enum.reverse()   # <-- missing
end

2. split_long_line/1 also returns chunks in reverse

split_long_line does |> Enum.reverse() explicitly, which means after chunk_lines prepends these reversed chunks onto the accumulator, an outer Enum.reverse() (from split/1) will re-reverse them to the correct order for chunk_blocks, but if hard_split is the one calling chunk_lines, the reversal chain is inconsistent. The two reversal strategies (explicit in split_long_line, implicit-via-prepend in chunk_lines) are easy to confuse and should be made uniform.

---

Code Quality / Style

3. send_message/3 in tg_webhook_handler.ex — reduce_while accumulator leaks internal detail

The function returns elem(result_tuple, 0), which surfaces the internal {result, llm_id} accumulator shape as an implementation detail. Extracting with |> elem(0) at the call site is fine, but documenting (or extracting) the return type would make this safer. Consider naming the final match or using a helper:

|> then(fn {result, _llm_id} -> result end)

4. escape_attr/1 is identical to escape/1

The comment acknowledges this ("today identical…kept separate for future URL-specific encoding"), which is reasonable. However, URL values in href attributes should ideally percent-encode characters like spaces, #, etc. that are valid in text but invalid in URLs. If a link URL comes from user markdown, this could silently produce invalid HTML. Consider at minimum adding a note to the TODO or a guard that validates the URL is already encoded.

5. render_node/1 for MDEx.HtmlInline / MDEx.HtmlBlock escapes raw HTML

This is intentional (prevent injection), but it means any markdown that already contains valid HTML tags (e.g. <b>) will be double-escaped and rendered as literal text. That is probably the right behaviour for user-supplied content, but it's worth a @moduledoc or inline comment to explain the intentional trade-off.

6. @parse_opts is module-level but not configurable

@parse_opts [extension: [strikethrough: true]] is fine for now, but other MDEx extensions (tables, task lists, etc.) could be useful later. A minor note: if MDEx ever requires different opts per call, the constant will need to become a function. No action needed now.

7. format/1 typespec allows nil but the callback send_message expects String.t()

The nil clause in format/1 is defensive and harmless, but it widens the public API. If nil can genuinely arrive here, the source (LLM response) should probably guard against it earlier. If it cannot, removing the nil clause and letting it crash loudly is more OTP-idiomatic (fail fast).

---

Test Coverage

8. No test for render_node fallback (_unknown)

The catch-all defp render_node(_unknown), do: "" silently swallows unknown AST nodes. A test verifying that unrecognised nodes don't crash (and produce empty string) would protect against MDEx AST changes.

9. soft break becomes space test comment vs. behaviour

The test docstring says "soft break becomes space" but the implementation emits "\n" (newline), not a space. The test passes because it only checks html =~ "line one" and html =~ "line two" without asserting the separator. Consider aligning the test description with the actual behaviour.

10. Missing test for format/1 error path (MDEx parse failure)

The {:error, _} -> escape(markdown) branch in format/1 has no test. A unit test with an input that forces a parse error (or a mock) would close this gap.

---

Minor

• .claude/rules/feature-workflow.md typo: everyting → everything, chacks → checks.
• The send_message/3 default argument (metadata \\ %{}) is kept—good.
• maybe_create_llm_response being deferred until the first successful send is a correct behaviour improvement worth noting in the commit message (already done ✓).

---

Summary

Area	Status
Core formatting logic	✅ Good
Splitting logic	⚠️ Possible chunk ordering bug in hard_split
Test coverage	✅ Good (28 tests), with a few gaps noted
Code style	✅ Follows project conventions
Security (HTML escaping)	✅ Correct
Behaviour/adapter contract	✅ Consistent

The chunk-ordering issue in hard_split is the only potentially impactful bug—worth verifying with a test that asserts the actual text content order of hard-split chunks, not just their lengths.

[claude]

Code Review

Overall this is a solid implementation. The MDEx AST-based approach is much better than regex-based markdown parsing. Good test coverage with 28 unit tests. Below are my findings, roughly ordered by severity.

---

BUGS AND CORRECTNESS ISSUES

1. Empty string sends to Telegram API

format(empty string) returns an empty HTML string, then split returns a list with one empty element, so TgWebhookHandler.send_message will call Telegram.send_message with an empty body - Telegram rejects this with a 400 error. This is reachable whenever an LLM returns an empty response.

Suggested fix: guard in TgWebhookHandler.send_message/3 - if html is empty, return :ok early. Or have split/1 return an empty list for empty input.

2. hard_split accumulator-reversal invariant is non-obvious

chunk_lines/2 prepends to acc, so hard_split/1 returns chunks in reversed order. The final Enum.reverse in split/1 restores order, but this relies on a subtle double-reversal that is easy to break.

---

API AND INTERFACE CONCERNS

3. send_message/3 returns save_message result, not the Telegram message

Any caller expecting {:ok, %Telegex.Type.Message{}} will silently break.

4. Login URL bypasses formatter - undocumented

Sending with empty opts (no parse_mode) is correct for a plain-text URL, but inconsistent with other send sites. A brief comment clarifies.

---

CODE QUALITY

5. escape_attr/1 is a premature abstraction

URL percent-encoding and HTML attribute escaping differ significantly. Until divergence happens, inline escape/1 at the call sites.

6. preferred_cli_env - dialyzer: :test is unusual

Running Dialyzer in :test env analyses test code and deps unnecessarily. Use :dev instead.

7. render_node for MDEx.List - verify list.start offset edge case

Add a test for ordered lists starting at 2 to guard against off-by-one errors.

8. @max_length measures graphemes, not UTF-16 code units

Telegram uses UTF-16 code units for its 4096-char limit. Worth a note in the module docs.

---

TESTING

9. Error-branch test is vacuous

The {:error, _} branch in format/1 is never hit by existing tests. Either inject an MDEx error or add a comment acknowledging this.

10. No test for the multi-chunk send_message path

No test verifying: (a) all chunks are dispatched, (b) only one LlmResponse record is created, (c) failures on later chunks halt correctly.

---

MINOR NITS

• @moduledoc lists tg-spoiler as supported but no renderer exists - mark as not yet implemented.
• BlockQuote renderer joins with single newline - double newline would look better.
• Consider a named type alias for the {String.t(), keyword()} return type.

---

SUMMARY: Bugs=2, API/interface=2, Code quality=4, Tests=2, Nits=3.

Items 1 (empty-string edge case) and 10 (multi-chunk test coverage) are the most important to address before merging.

[claude]

test

[claude]

test2

[claude]

Bodhi

To start your Phoenix server:

• Install dependencies with mix deps.get
• Create and migrate your database with mix ecto.setup
• Start Phoenix endpoint with mix phx.server or inside IEx with iex -S mix phx.server

Now you can visit localhost:4000 from your browser.

Ready to run in production? Please check our deployment guides.

AI Provider Configuration

Bodhi supports multiple AI providers that can be switched via configuration.

Available Providers

OpenRouter (Default)

• Module: Bodhi.OpenRouter
• Default Model: deepseek/deepseek-r1-0528:free
• Environment Variable: OPENROUTER_API_KEY
• Website: https://openrouter.ai/

Google Gemini

• Module: Bodhi.Gemini
• Model: gemini-2.0-flash
• Environment Variable: GEMINI_API_KEY

Switching Providers

To switch AI providers, update config/config.exs:

# Use OpenRouter (default)
config :bodhi, :ai_client, Bodhi.OpenRouter

# Use Google Gemini
config :bodhi, :ai_client, Bodhi.Gemini

Setting Up API Keys

1. OpenRouter:

   • Get API key from: https://openrouter.ai/keys
   • Set in .envrc: export OPENROUTER_API_KEY=sk-or-v1-your_api_key_here

2. Google Gemini:

   • Get API key from: https://aistudio.google.com/app/apikey
   • Set in .envrc: export GEMINI_API_KEY=your_api_key_here

3. Reload environment: direnv allow (if using direnv)

Changing OpenRouter Model

Edit lib/bodhi/open_router.ex and modify the @default_model attribute:

@default_model "deepseek/deepseek-r1-0528:free"  # Current default

# Other popular models:
# @default_model "anthropic/claude-3.5-sonnet"
# @default_model "openai/gpt-4-turbo"
# @default_model "meta-llama/llama-3.1-70b-instruct"
# @default_model "google/gemini-pro-1.5"

See all available models at: https://openrouter.ai/models

Features

Daily Dialog Summarization

Bodhi automatically summarizes chat conversations daily to optimize AI context and reduce API costs:

• Automatic Summarization: Worker runs daily at 2 AM UTC to summarize previous day's messages
• Smart Context Assembly: Uses summaries for older messages + full messages from last 7 days
• Cost Optimization: Reduces token usage by ~80-90% for long conversations
• Seamless Integration: Falls back gracefully when no summaries exist

Example Results:

• 265 total messages → 4 recent messages in context
• 98.5% token reduction for older conversations

Documentation

• docs/SUMMARIZATION.md - Complete guide to the summarization system
• docs/DEPLOYMENT.md - Deployment and backfill procedures

Quick Start

After deployment, backfill historical summaries:

# Preview what will be processed (no API calls)
bin/bodhi eval "Bodhi.Release.backfill_summaries(dry_run: true)"

# Run the backfill
bin/bodhi eval "Bodhi.Release.backfill_summaries()"

See docs/DEPLOYMENT.md for detailed instructions.

Learn more

• Official website: https://www.phoenixframework.org/
• Guides: https://hexdocs.pm/phoenix/overview.html
• Docs: https://hexdocs.pm/phoenix
• Forum: https://elixirforum.com/c/phoenix-forum
• Source: https://github.com/phoenixframework/phoenix

[claude]

Full review text here

[claude]

Feature Implementation Flow

• Create a new branch from main for the feature
• Implement tests first (TDD)
• Implement the feature code
• Make sure code is compilable by mix compile and has no warnings
• Run all tests with mix test and ensure they pass
• Make sure code runs in iex -S mix without errors
• Check with mix dialyzer for type issues
• Update documentation and AGENTS.md if needed
• Run mix format to ensure code style compliance
• Commit code
• Push branch to remote
• Create a pull request

[claude]

placeholder

[claude]

Supplementing the previous review with corrections and additional findings.

[claude]

Supplemental review — corrections and new findings

Corrections to previous review

Hard split / single lines over 4096 chars: already handled. chunk_lines/2 has an explicit guard calling split_long_line/1 for lines exceeding @max_length, and a passing test covers this case. No action needed.

LLM response record created before send succeeds: also incorrect. llm_id || maybe_create_llm_response(metadata) is inside the {:ok, message} branch, conditional on a successful send. No action needed.

---

New findings

Bug: empty text still calls Telegram API

An empty input produces a single empty-string chunk that is forwarded to Telegram.send_message. The Telegram Bot API rejects empty text with a 400 error. The test stub accepts anything, so the assertion passes despite the missing guard.

Suggested fix: filter blank chunks before the reduce. Use Enum.reject to drop empty-string chunks; if the result is an empty list return {:ok, nil}, otherwise proceed with Enum.reduce_while.

Security: javascript: links pass through unmodified

escape_attr/1 only HTML-escapes the standard four characters. A javascript: href from LLM output passes through unchanged. A scheme allowlist (allow only https?://) at the formatting layer is safer.

Minor: .claude/rules/feature-workflow.md should not be in this PR

The pr-workflow.md rule states never modify files in the .claude directory. The two-line addition also contains typos (everyting, chacks) and should be reverted or submitted separately.

Minor: credo: :test in preferred_cli_env

Credo is conventionally run in :dev. Running in :test pulls test-support modules into analysis scope.

Minor: escape_attr/1 comment is slightly misleading

Future URL-specific encoding implies percent-encoding, which is a different operation. Clearer wording: Kept separate so URL validation (e.g. scheme allowlist) can be added here without touching the general escape path.

---

Overall: the core implementation (MDEx AST traversal, HTML escaping, block-boundary splitting, and test coverage) is solid. The empty-chunk Telegram API call and the javascript: scheme gap are the only issues with real runtime consequences.

[claude]

TITLE: PR Review: feat/telegram-markdown

Good overall implementation with solid test coverage. Previous review feedback (LLM response creation, hard-split for long lines, periodic messages test) has been addressed. A few issues remain.

BUG: split/1 breaks HTML inside pre code blocks

String.split on double-newline is applied to the fully-rendered HTML string. A code block containing a blank line will contain a double-newline in the rendered output, causing the split to cut inside the tag.

Example: a Python code block with a blank line between two functions renders to HTML with a blank line inside the pre/code tags. After splitting on that blank line, Telegram receives two messages with mismatched HTML — unclosed pre tag in the first chunk, orphaned closing tags in the second. Telegram rejects or mangles both.

Fix: split on the AST level before rendering (preferred), or track whether the scan cursor is inside a pre block when choosing split points.

SECURITY: javascript: links pass through unmodified

render_node/1 for MDEx.Link and MDEx.Image calls escape(url) on the href value. escape/1 only handles ampersand, less-than, greater-than, and double-quote. A javascript:alert(1) URL from LLM output passes through unchanged. Add a scheme allowlist (http, https, tg) and replace unsafe URLs with a safe fallback.

ISSUE: Empty chunks may reach the Telegram API

If format/1 produces HTML with consecutive double-newline separators (e.g. a thematic break renders as empty string surrounded by blank lines), splitting on double-newline yields empty-string elements inside the chunk list. These flow into send_chunks and reach Telegram.send_message with an empty string body, which Telegram rejects.

The empty-list guard in send_message/3 only catches the case where the entire formatted message is empty. Fix: filter empty chunks before iterating in send_chunks.

ISSUE: Partial-send leaves orphaned LLM response record

If chunk 1 succeeds (LLM response record created and message saved) but chunk 2 fails, the function returns an error while leaving an LLM response record pointing to only one of the expected messages. The trade-off is acceptable, but a comment in send_chunks/4 documenting this behaviour would help future maintainers.

MINOR: .claude/rules/feature-workflow.md should not be in this PR

pr-workflow.md explicitly states never fix files in the .claude directory. The two-line addition also contains typos (everyting, chacks). Revert or submit separately.

MINOR: preferred_cli_env — credo: :test is unconventional

Credo is conventionally run in :dev. Running it in :test pulls test-support modules into static analysis scope. Change to :dev or omit the entry.

POSITIVES:

• HTML escaping is correctly applied in all render paths including attribute values.
• AST-level rendering means standard markdown elements are never double-escaped.
• Block-boundary splitting with line-level fallback and grapheme-level last resort is the right strategy.
• Fallback to escaped raw text on MDEx parse error is safe and correct.
• maybe_create_llm_response is correctly guarded inside the success branch — only created on first successful send.
• 28 unit tests with good edge case coverage: nil input, nested formatting, oversized blocks, ordering.
• Typespec on format/1 correctly reflects the two-element tuple return shape.

[claude]

Code Review

Overall this is a well-structured PR with good test coverage and clear documentation. The HTML-escaping approach to prevent XSS, URL scheme validation, and AST-based splitting at block boundaries are all solid design decisions. A few issues worth addressing before merge.

Bug: Hard-split breaks HTML tags in long code blocks

lib/bodhi/telegram/formatter.ex — hard_split/1

If a single rendered <pre><code>...</code></pre> block exceeds 4096 characters, hard_split splits it at newline/character boundaries, producing chunks with unclosed or orphaned tags that Telegram's HTML parser will reject or mangle. Consider detecting oversized code blocks in render_node/1 for %MDEx.CodeBlock and either stripping the <pre> wrapper or truncating with an ellipsis indicator. At minimum, add a TODO documenting this known limitation.

Test inconsistency: format/1 vs format_chunks/1 output mismatch

test/bodhi/tg_webhook_handler_test.exs lines 853 and 872-873

The webhook test computes expected values via Formatter.format(text), but the production code path calls format_chunks(text). These differ: format/1 calls String.trim/1 on the assembled HTML, but format_chunks/1 does not trim individual chunks. For Faker.Lorem.paragraph() input this likely passes today, but it is a latent divergence. The multi-chunk test also calls format(text) then split(html) instead of format_chunks(text) directly, testing a different code path than production. Tests should use format_chunks for expected-value computation.

Minor: empty input returns different shapes from format/1 vs format_chunks/1

format(nil) returns {"", [...]} while format_chunks(nil) returns {[""], [...]}. This forces the caller to special-case [""] as "nothing to send". Consider returning {[], ...} for truly empty input and simplifying the guard in send_message to if chunks == [], do: {:ok, nil}.

Minor: typespec style

opts :: keyword() in the behaviour callback should be opts :: Keyword.t() per Elixir convention.

Minor: safe_url?/1 catch-all guard is dead code

URI.parse("javascript:alert(1)") returns %URI{scheme: "javascript"}, so the catch-all branch is only reached for relative URLs like /path or #anchor. The String.starts_with?(url, "javascript:") guard in that branch is unreachable. Remove it and update the comment to say "relative URLs allowed".

Nit: no default for opts in Bodhi.Telegram.send_message/3

Adding opts \\ [] would be consistent with TgWebhookHandler.send_message/3's metadata \\ %{} default and remove the need for callers like the /login handler to pass [] explicitly.

Positive callouts

• HTML-escaping in escape/1 is correct and applied consistently across all text-bearing AST nodes.
• Documenting the UTF-16 vs grapheme-cluster caveat for @max_length is a useful heads-up for future maintainers.
• The lazy llm_id creation in send_chunks (only on first successful send) is a clean pattern.
• preferred_cli_env in mix.exs is a welcome quality-of-life improvement.
• Security test cases for javascript: links and raw HTML injection are thorough.

Generated with Claude Code