some docs

lib/llm_composer.ex

@@ -1,5 +1,9 @@
 defmodule LlmComposer do
-  @moduledoc false
+  @moduledoc """
+  `LlmComposer` is responsible for interacting with a language model to perform chat-related operations,
+  such as running completions and executing functions based on the responses. The module provides 
+  functionality to handle user messages, generate responses, and automatically execute functions as needed.
+  """
 
   alias LlmComposer.Helpers
   alias LlmComposer.LlmResponse
@@ -10,13 +14,34 @@ defmodule LlmComposer do
 
   @type messages :: [Message.t()]
 
+  @doc """
+  Initiates a simple chat interaction with the language model.
+
+  ## Parameters
+    - `settings`: The settings for the language model, including prompts and options.
+    - `msg`: The user message to be sent to the language model.
+
+  ## Returns
+    - The result of the language model's response, which may include function executions if specified.
+  """
   @spec simple_chat(Settings.t(), String.t()) :: Helpers.action_result()
   def simple_chat(%Settings{} = settings, msg) do
     messages = get_messages(settings, msg, [], %{})
 
     run_completion(settings, messages)
   end
 
+  @doc """
+  Runs the completion process by sending messages to the language model and handling the response.
+
+  ## Parameters
+    - `settings`: The settings for the language model, including prompts, model options, and functions.
+    - `messages`: The list of messages to be sent to the language model.
+    - `previous_response` (optional): The previous response object, if any, used for context.
+
+  ## Returns
+    - A tuple containing `:ok` with the response or `:error` if the model call fails.
+  """
   @spec run_completion(Settings.t(), messages(), LlmResponse.t() | nil) :: Helpers.action_result()
   def run_completion(settings, messages, previous_response \\ nil) do
     system_msg = Message.new(:system, settings.system_prompt)
@@ -43,6 +68,7 @@ defmodule LlmComposer do
     end)
   end
 
+  @doc false
   @spec get_messages(Settings.t(), String.t(), messages(), map()) :: messages()
   defp get_messages(settings, current_message, old_messages, opts) do
     old_messages ++ [Message.new(:user, user_prompt(settings, current_message, opts))]
@@ -55,6 +81,7 @@ defmodule LlmComposer do
     prompt <> message
   end
 
+  @doc false
   @spec maybe_run_functions(LlmResponse.t(), messages(), Settings.t()) :: Helpers.action_result()
   defp maybe_run_functions(res, messages, settings) do
     res

lib/llm_composer/helpers.ex

@@ -1,8 +1,10 @@
 defmodule LlmComposer.Helpers do
   @moduledoc """
-  Function helpers for Caller macro module.
+  Provides helper functions for the `LlmComposer` module, particularly for managing
+  function calls and handling language model responses.
 
-  Functions that can be seen in a error stack trace if something fails.
+  These helpers are designed to execute functions as part of the response processing pipeline,
+  manage completions, and log relevant information for debugging.
   """
 
   alias LlmComposer.Function
@@ -19,6 +21,17 @@ defmodule LlmComposer.Helpers do
           | {:completion, LlmResponse.t(), llmfunctions()}
           | {:error, term()}
 
+  @doc """
+  Executes the functions specified in the language model response, if any.
+
+  ## Parameters
+    - `res`: The language model response containing actions to be executed.
+    - `llm_functions`: A list of functions available for execution.
+
+  ## Returns
+    - `{:ok, res}` if no actions are found in the response.
+    - `{:completion, res, results}` if actions are executed, returning the completion status and results.
+  """
   @spec maybe_exec_functions(LlmResponse.t(), llmfunctions()) :: action_result()
   def maybe_exec_functions(%{actions: []} = res, _functions), do: {:ok, res}
 
@@ -28,6 +41,17 @@ defmodule LlmComposer.Helpers do
     {:completion, res, results}
   end
 
+  @doc """
+  Completes the chat flow by appending function results to the messages and re-running the completion process.
+
+  ## Parameters
+    - `action_result`: The result of a previous action or completion.
+    - `messages`: The list of messages exchanged so far.
+    - `run_completion_fn`: A function to re-run the completion with updated messages.
+
+  ## Returns
+    - The result of re-running the completion with the new set of messages and function results.
+  """
   @spec maybe_complete_chat(action_result(), messages(), function()) :: action_result()
   def maybe_complete_chat({:ok, _} = res, _messages, _fcalls), do: res
 
@@ -43,6 +67,7 @@ defmodule LlmComposer.Helpers do
     run_completion_fn.(new_messages)
   end
 
+  @doc false
   @spec exec_function(fcall :: FunctionCall.t(), functions :: llmfunctions()) :: FunctionCall.t()
   defp exec_function(%FunctionCall{} = fcall, functions) do
     [