From 73b1b4f3934b7021fd87ce0d26cea84c8486f5b6 Mon Sep 17 00:00:00 2001
From: Ian McLerran <imclerran@protonmail.com>
Date: Tue, 31 Dec 2024 08:27:03 -0600
Subject: [PATCH 1/2] Refactor module header docs slightly

---
 package/Toolkit/FileSystem.roc     | 3 +--
 package/Toolkit/OpenWeatherMap.roc | 3 +--
 package/Toolkit/Roc.roc            | 3 +--
 package/Toolkit/Serper.roc         | 3 +--
 package/Toolkit/UtcTime.roc        | 3 +--
 package/Toolkit/Wikipedia.roc      | 3 +--
 package/Toolkit/WolframAlpha.roc   | 3 +--
 package/Toolkit/WorldTimeApi.roc   | 3 +--
 8 files changed, 8 insertions(+), 16 deletions(-)

diff --git a/package/Toolkit/FileSystem.roc b/package/Toolkit/FileSystem.roc
index 11edea0..6728d4e 100644
--- a/package/Toolkit/FileSystem.roc
+++ b/package/Toolkit/FileSystem.roc
@@ -1,7 +1,6 @@
 ## A collection of prebuilt tools for interacting with the file system. For safety reasons, the tools in this module are limited to working in the current working directory and its subdirectories.
-##
-## Usage:
 ## ```
+## # USAGE:
 ## # Tool list to initialize the client
 ## tools = [listDirectory, listFileTree, readFileContents, writeFileContents ]
 ## # Tool handler map is passed to Tools.handleToolCalls!
diff --git a/package/Toolkit/OpenWeatherMap.roc b/package/Toolkit/OpenWeatherMap.roc
index 5a3f218..d8889dc 100644
--- a/package/Toolkit/OpenWeatherMap.roc
+++ b/package/Toolkit/OpenWeatherMap.roc
@@ -1,7 +1,6 @@
 ## A collection of prebuilt tools for interacting with the OpenWeatherMap API.
-##
-## Usage:
 ## ```
+## # USAGE:
 ## # Tool list to initialize the client
 ## tools = [geocoding, currentWeather]
 ## # Tool handler map is passed to Tools.handleToolCalls!
diff --git a/package/Toolkit/Roc.roc b/package/Toolkit/Roc.roc
index 3317748..b6dca91 100644
--- a/package/Toolkit/Roc.roc
+++ b/package/Toolkit/Roc.roc
@@ -1,7 +1,6 @@
 ## A collection of prebuilt tools for interacting with the Roc programming language CLI.
-##
-## Usage:
 ## ```
+## # USAGE:
 ## # Tool list to initialize the client
 ## tools = [roc, rocCheck, rocTest, rocStart]
 ## # Tool handler map is passed to Tools.handleToolCalls!
diff --git a/package/Toolkit/Serper.roc b/package/Toolkit/Serper.roc
index 1b8b21a..7849962 100644
--- a/package/Toolkit/Serper.roc
+++ b/package/Toolkit/Serper.roc
@@ -1,7 +1,6 @@
 ## A prebuilt tool for interacting with the serper.dev google search API.
-##
-## Usage:
 ## ```
+## # USAGE:
 ## # Tool list to initialize the client
 ## tools = [serper]
 ## # Tool handler map is passed to Tools.handleToolCalls!
diff --git a/package/Toolkit/UtcTime.roc b/package/Toolkit/UtcTime.roc
index 01e1d7f..567dff9 100644
--- a/package/Toolkit/UtcTime.roc
+++ b/package/Toolkit/UtcTime.roc
@@ -1,7 +1,6 @@
 ## A prebuilt tool for getting the current UTC time.
-##
-## Usage:
 ## ```
+## # USAGE:
 ## # Tool list to initialize the client
 ## tools = [utcNow]
 ## # Tool handler map is passed to Tools.handleToolCalls!
diff --git a/package/Toolkit/Wikipedia.roc b/package/Toolkit/Wikipedia.roc
index ce4a662..eab0e9a 100644
--- a/package/Toolkit/Wikipedia.roc
+++ b/package/Toolkit/Wikipedia.roc
@@ -1,7 +1,6 @@
 ## A collection of prebuilt tools for interacting with Wikipedia.
-##
-## Usage:
 ## ```
+## # USAGE:
 ## # Tool list to initialize the client
 ## tools = [wikipediaSearch, wikipediaParse]
 ## # Tool handler map is passed to Tools.handleToolCalls!
diff --git a/package/Toolkit/WolframAlpha.roc b/package/Toolkit/WolframAlpha.roc
index 5620475..c755b1b 100644
--- a/package/Toolkit/WolframAlpha.roc
+++ b/package/Toolkit/WolframAlpha.roc
@@ -1,7 +1,6 @@
 ## A prebuilt tool for interacting with Wolfram Alpha.
-##
-## Usage:
 ## ```
+## # USAGE:
 ## # Tool list to initialize the client
 ## tools = [wolframShortAnswer]
 ## # Tool handler map is passed to Tools.handleToolCalls!
diff --git a/package/Toolkit/WorldTimeApi.roc b/package/Toolkit/WorldTimeApi.roc
index b3ae4be..e165c95 100644
--- a/package/Toolkit/WorldTimeApi.roc
+++ b/package/Toolkit/WorldTimeApi.roc
@@ -1,7 +1,6 @@
 ## A prebuilt tool for interacting with the WorldTimeApi.
-##
-## Usage:
 ## ```
+## # USAGE:
 ## # Tool list to initialize the client
 ## tools = [currentTime]
 ## # Tool handler map is passed to Tools.handleToolCalls!

From 71f08798c68b675665b3eb8550ac0ee834d3129d Mon Sep 17 00:00:00 2001
From: Ian McLerran <imclerran@protonmail.com>
Date: Tue, 31 Dec 2024 08:58:02 -0600
Subject: [PATCH 2/2] Add type signatures for all toolkits

---
 package/Toolkit/FileSystem.roc     | 8 ++++----
 package/Toolkit/OpenWeatherMap.roc | 2 ++
 package/Toolkit/Roc.roc            | 4 ++++
 package/Toolkit/Serper.roc         | 1 +
 package/Toolkit/UtcTime.roc        | 7 ++++---
 package/Toolkit/Wikipedia.roc      | 2 ++
 package/Toolkit/WolframAlpha.roc   | 1 +
 package/Toolkit/WorldTimeApi.roc   | 1 +
 8 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/package/Toolkit/FileSystem.roc b/package/Toolkit/FileSystem.roc
index 6728d4e..009d992 100644
--- a/package/Toolkit/FileSystem.roc
+++ b/package/Toolkit/FileSystem.roc
@@ -29,7 +29,7 @@ import json.Json
 import InternalTools exposing [Tool, buildTool]
 
 ## Expose name, handler and tool for listDirectory.
-listDirectory : { name : Str, handler : Str -> Task Str _, tool : Tool }
+listDirectory : { name : Str, handler : Str -> Task Str *, tool : Tool }
 listDirectory = {
     name: listDirectoryTool.function.name,
     handler: listDirectoryHandler,
@@ -72,7 +72,7 @@ listDirectoryHandler = \args ->
 ## Expose name, handler and tool for listFileTree.
 ##
 ## This tool will allow the model to list the contents of a directory, and all subdirectories.
-listFileTree : { name : Str, handler : Str -> Task Str _, tool : Tool }
+listFileTree : { name : Str, handler : Str -> Task Str *, tool : Tool }
 listFileTree = {
     name: listFileTreeTool.function.name,
     handler: listFileTreeHandler,
@@ -133,7 +133,7 @@ fileTreeHelper = \paths, accumulation, depth ->
 ## Expose name, handler and tool for readFileContents.
 ##
 ## This tool will allow the model to read the contents of a file.
-readFileContents : { name : Str, handler : Str -> Task Str _, tool : Tool }
+readFileContents : { name : Str, handler : Str -> Task Str *, tool : Tool }
 readFileContents = {
     name: readFileContentsTool.function.name,
     handler: readFileContentsHandler,
@@ -176,7 +176,7 @@ readFileContentsHandler = \args ->
 ## Expose name, handler and tool for writeFileContents.
 ##
 ## This tool will allow the model to write content to a file.
-writeFileContents : { name : Str, handler : Str -> Task Str _, tool : Tool }
+writeFileContents : { name : Str, handler : Str -> Task Str *, tool : Tool }
 writeFileContents = {
     name: writeFileContentsTool.function.name,
     handler: writeFileContentsHandler,
diff --git a/package/Toolkit/OpenWeatherMap.roc b/package/Toolkit/OpenWeatherMap.roc
index d8889dc..ac053ca 100644
--- a/package/Toolkit/OpenWeatherMap.roc
+++ b/package/Toolkit/OpenWeatherMap.roc
@@ -24,6 +24,7 @@ import InternalTools exposing [Tool]
 ## Expose name, handler and tool for geocoding.
 ##
 ## This tool will allow the model to get the correct latitude and longitude for a location, for use with the currentWeather tool.
+geocoding: { name : Str, handler : Str -> Task Str *, tool : Tool }
 geocoding = {
     name: geocodingTool.function.name,
     handler: geocodingHandler,
@@ -84,6 +85,7 @@ geocodingHandler = \args ->
 ## Expose name, handler and tool for currentWeather
 ##
 ## This tool will allow the model to get the current weather for a location.
+currentWeather: { name : Str, handler : Str -> Task Str *, tool : Tool }
 currentWeather = {
     name: currentWeatherTool.function.name,
     handler: currentWeatherHandler,
diff --git a/package/Toolkit/Roc.roc b/package/Toolkit/Roc.roc
index b6dca91..85ecbe5 100644
--- a/package/Toolkit/Roc.roc
+++ b/package/Toolkit/Roc.roc
@@ -37,6 +37,7 @@ CommandErr : [
 ## Expose name, handler and tool for roc.
 ##
 ## This tool will allow the model to run `roc` for a roc file.
+roc : { name : Str, handler : Str -> Task Str *, tool : Tool }
 roc = {
     name: rocTool.function.name,
     handler: rocHandler,
@@ -77,6 +78,7 @@ rocHandler = \args ->
 ## Expose name, handler and tool for rocCheck.
 ##
 ## This tool will allow the model to run `roc check` for a Roc file.
+rocCheck : { name : Str, handler : Str -> Task Str *, tool : Tool }
 rocCheck = {
     name: rocCheckTool.function.name,
     handler: rocCheckHandler,
@@ -118,6 +120,7 @@ rocCheckHandler = \args ->
 ## Expose name, handler and tool for rocTest.
 ##
 ## This tool will allow the model to run `roc test` for a Roc file.
+rocTest : { name : Str, handler : Str -> Task Str *, tool : Tool }
 rocTest = {
     name: rocTestTool.function.name,
     handler: rocTestHandler,
@@ -159,6 +162,7 @@ rocTestHandler = \args ->
 ## Expose name, handler and tool for rocStart.
 ##
 ## This tool will allow the model to use `roc-start` to initialize a new Roc application.
+rocStart : { name : Str, handler : Str -> Task Str *, tool : Tool }
 rocStart = {
     name: rocStartTool.function.name,
     handler: rocStartHandler,
diff --git a/package/Toolkit/Serper.roc b/package/Toolkit/Serper.roc
index 7849962..e12f012 100644
--- a/package/Toolkit/Serper.roc
+++ b/package/Toolkit/Serper.roc
@@ -21,6 +21,7 @@ import InternalTools exposing [Tool, buildTool]
 ## Expose name, handler and tool for serper.
 ##
 ## This tool allows the model to search google using the serper.dev API.
+serper : { name : Str, handler : Str -> Task Str *, tool : Tool }
 serper = {
     name: tool.function.name,
     handler,
diff --git a/package/Toolkit/UtcTime.roc b/package/Toolkit/UtcTime.roc
index 567dff9..c0dbdca 100644
--- a/package/Toolkit/UtcTime.roc
+++ b/package/Toolkit/UtcTime.roc
@@ -18,7 +18,10 @@ module { getUtcNow, utcToNanos } -> [utcNow]
 import InternalTools exposing [Tool, buildTool]
 import iso.DateTime
 
-## Expose name, handler and tool for utcNow
+## Expose name, handler and tool for utcNow.
+##
+## This tool allows the model to get the current UTC time as an ISO 8601 string.
+utcNow : { name : Str, handler : Str -> Task Str *, tool : Tool }
 utcNow = {
     name: tool.function.name,
     handler,
@@ -26,8 +29,6 @@ utcNow = {
 }
 
 ## Tool definition for the utcNow function
-##
-## This tool allows the model to get the current UTC time as an ISO 8601 string.
 tool : Tool
 tool = buildTool "utcNow" "Get the current UTC time as an ISO 8601 string" []
 
diff --git a/package/Toolkit/Wikipedia.roc b/package/Toolkit/Wikipedia.roc
index eab0e9a..5d1aa5c 100644
--- a/package/Toolkit/Wikipedia.roc
+++ b/package/Toolkit/Wikipedia.roc
@@ -27,6 +27,7 @@ baseUrl = "https://en.wikipedia.org/w/api.php"
 ## Expose name, handler and tool for the wikipediaSarch.
 ##
 ## This tool allows the model to search Wikipedia for a given query.
+wikipediaSearch : { name : Str, handler : Str -> Task Str *, tool : Tool }
 wikipediaSearch = {
     name: wikipediaSearchTool.function.name,
     handler: wikipediaSearchHandler,
@@ -93,6 +94,7 @@ wikipediaSearchHandler = \args ->
 ## Expose name, handler and tool for the wikipediaParse tool.
 ##
 ## This tool allows the model to parse a Wikipedia article.
+wikipediaParse : { name : Str, handler : Str -> Task Str *, tool : Tool }
 wikipediaParse = {
     name: wikipediaParseTool.function.name,
     handler: wikipediaParseHandler,
diff --git a/package/Toolkit/WolframAlpha.roc b/package/Toolkit/WolframAlpha.roc
index c755b1b..29acfe4 100644
--- a/package/Toolkit/WolframAlpha.roc
+++ b/package/Toolkit/WolframAlpha.roc
@@ -24,6 +24,7 @@ import Shared exposing [urlEncode]
 ## Expose name, handler and tool for shortAnswer.
 ##
 ## This tool allows the model to ask Wolfram Alpha a question and get a short answer.
+wolframShortAnswer : { name : Str, handler : Str -> Task Str *, tool : Tool }
 wolframShortAnswer = {
     name: shortAnswerTool.function.name,
     handler: shortAnswerHandler,
diff --git a/package/Toolkit/WorldTimeApi.roc b/package/Toolkit/WorldTimeApi.roc
index e165c95..81347e1 100644
--- a/package/Toolkit/WorldTimeApi.roc
+++ b/package/Toolkit/WorldTimeApi.roc
@@ -21,6 +21,7 @@ import json.Json
 ## Expose name, handler and tool for the currentTime.
 ##
 ## This tool allows the model to get the current time data for a given timezone.
+currentTime : { name : Str, handler : Str -> Task Str *, tool : Tool }
 currentTime = {
     name: tool.function.name,
     handler,