Merge pull request #35 from imclerran/update-docs

Update documentation for Toolkits

package/Toolkit/FileSystem.roc

@@ -1,3 +1,24 @@
+## 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:
+## ```
+## # Tool list to initialize the client
+## tools = [listDirectory, listFileTree, readFileContents, writeFileContents ]
+## # Tool handler map is passed to Tools.handleToolCalls!
+## toolHandlerMap = Dict.fromList [
+##     (listDirectory.name, listDirectory.handler),
+##     (listFileTree.name, listFileTree.handler),
+##     (readFileContents.name, readFileContents.handler),
+##     (writeFileContents.name, writeFileContents.handler),
+## ]
+## client = Client.init { apiKey, model: "tool-capable/model", tools }
+##
+## #...
+## 
+## messages = Chat.appendUserMessage previousMessages newMessage
+## response = Http.send (Chat.buildHttpRequest client messages {}) |> Task.result!
+## updatedMessages = updateMessagesFromResponse response messages |> Tools.handleToolCalls! client toolHandlerMap
+## ```
 module { pathFromStr, pathToStr, listDir, isDir, readFile, writeUtf8 } -> [
     listDirectory,
     listFileTree,
@@ -8,7 +29,8 @@ module { pathFromStr, pathToStr, listDir, isDir, readFile, writeUtf8 } -> [
 import json.Json
 import InternalTools exposing [Tool, buildTool]
 
-## Expose name, handler and tool for listDirectory
+## Expose name, handler and tool for listDirectory.
+listDirectory : { name : Str, handler : Str -> Task Str _, tool : Tool }
 listDirectory = {
     name: listDirectoryTool.function.name,
     handler: listDirectoryHandler,
@@ -48,7 +70,10 @@ listDirectoryHandler = \args ->
                     |> Str.joinWith "\n"
                     |> Task.ok
 
-## Expose name, handler and tool for listFileTree
+## 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: listFileTreeTool.function.name,
     handler: listFileTreeHandler,
@@ -106,7 +131,10 @@ fileTreeHelper = \paths, accumulation, depth ->
                 newString = buildStr accumulation (pathToStr path) ""
                 fileTreeHelper pathsTail newString depth
 
-## Expose name, handler and tool for readFileContents
+## 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: readFileContentsTool.function.name,
     handler: readFileContentsHandler,
@@ -146,7 +174,10 @@ readFileContentsHandler = \args ->
                     |> Result.withDefault "Failed to read file"
                     |> Task.ok
 
-## Expose name, handler and tool for writeFileContents
+## 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: writeFileContentsTool.function.name,
     handler: writeFileContentsHandler,

package/Toolkit/OpenWeatherMap.roc

@@ -1,9 +1,30 @@
+## A collection of prebuilt tools for interacting with the OpenWeatherMap API.
+##
+## Usage:
+## ```
+## # Tool list to initialize the client
+## tools = [geocoding, currentWeather]
+## # Tool handler map is passed to Tools.handleToolCalls!
+## toolHandlerMap = Dict.fromList [
+##     (geocoding.name, geocoding.handler),
+##     (currentWeather.name, currentWeather.handler),
+## ]
+## client = Client.init { apiKey, model: "tool-capable/model", tools }
+##
+## #...
+##
+## messages = Chat.appendUserMessage previousMessages newMessage
+## response = Http.send (Chat.buildHttpRequest client messages {}) |> Task.result!
+## updatedMessages = updateMessagesFromResponse response messages |> Tools.handleToolCalls! client toolHandlerMap
+## ```
 module { sendHttpReq, getEnvVar } -> [geocoding, currentWeather]
 
 import json.Json
 import InternalTools exposing [Tool]
 
-## Expose name, handler and tool for geocoding
+## 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: geocodingTool.function.name,
     handler: geocodingHandler,
@@ -62,6 +83,8 @@ geocodingHandler = \args ->
                     |> Task.ok
 
 ## Expose name, handler and tool for currentWeather
+##
+## This tool will allow the model to get the current weather for a location.
 currentWeather = {
     name: currentWeatherTool.function.name,
     handler: currentWeatherHandler,

package/Toolkit/Roc.roc

@@ -1,3 +1,24 @@
+## A collection of prebuilt tools for interacting with the Roc programming language CLI.
+##
+## Usage:
+## ```
+## # Tool list to initialize the client
+## tools = [roc, rocCheck, rocTest, rocStart]
+## # Tool handler map is passed to Tools.handleToolCalls!
+## toolHandlerMap = Dict.fromList [
+##     (roc.name, roc.handler),
+##     (rocCheck.name, rocCheck.handler),
+##     (rocTest.name, rocTest.handler),
+##     (rocStart.name, rocStart.handler),
+## ]
+## client = Client.init { apiKey, model: "tool-capable/model", tools }
+##
+## #...
+##
+## messages = Chat.appendUserMessage previousMessages newMessage
+## response = Http.send (Chat.buildHttpRequest client messages {}) |> Task.result!
+## updatedMessages = updateMessagesFromResponse response messages |> Tools.handleToolCalls! client toolHandlerMap
+## ```
 module { cmdNew, cmdArg, cmdOutput } -> [roc, rocCheck, rocTest, rocStart]
 
 import json.Json
@@ -14,6 +35,9 @@ CommandErr : [
     IOError Str,
 ]
 
+## Expose name, handler and tool for roc.
+##
+## This tool will allow the model to run `roc` for a roc file.
 roc = {
     name: rocTool.function.name,
     handler: rocHandler,
@@ -51,6 +75,9 @@ rocHandler = \args ->
                     |> cmdOutputResultToStr
                     |> Task.ok
 
+## Expose name, handler and tool for rocCheck.
+##
+## This tool will allow the model to run `roc check` for a Roc file.
 rocCheck = {
     name: rocCheckTool.function.name,
     handler: rocCheckHandler,
@@ -89,6 +116,9 @@ rocCheckHandler = \args ->
                     |> cmdOutputResultToStr
                     |> Task.ok
 
+## Expose name, handler and tool for rocTest.
+##
+## This tool will allow the model to run `roc test` for a Roc file.
 rocTest = {
     name: rocTestTool.function.name,
     handler: rocTestHandler,
@@ -127,6 +157,9 @@ rocTestHandler = \args ->
                     |> cmdOutputResultToStr
                     |> Task.ok
 
+## 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: rocStartTool.function.name,
     handler: rocStartHandler,

package/Toolkit/Serper.roc

@@ -1,8 +1,27 @@
+## A prebuilt tool for interacting with the serper.dev google search API.
+##
+## Usage:
+## ```
+## # Tool list to initialize the client
+## tools = [serper]
+## # Tool handler map is passed to Tools.handleToolCalls!
+## toolHandlerMap = Dict.fromList [(serper.name, serper.handler)]
+## client = Client.init { apiKey, model: "tool-capable/model", tools }
+##
+## #...
+##
+## messages = Chat.appendUserMessage previousMessages newMessage
+## response = Http.send (Chat.buildHttpRequest client messages {}) |> Task.result!
+## updatedMessages = updateMessagesFromResponse response messages |> Tools.handleToolCalls! client toolHandlerMap
+## ```
+
 module { sendHttpReq, getEnvVar } -> [serper]
 
 import InternalTools exposing [Tool, buildTool]
 
-## Expose name, handler and tool for serper
+## Expose name, handler and tool for serper.
+##
+## This tool allows the model to search google using the serper.dev API.
 serper = {
     name: tool.function.name,
     handler,

package/Toolkit/UtcTime.roc

@@ -1,3 +1,19 @@
+## A prebuilt tool for getting the current UTC time.
+##
+## Usage:
+## ```
+## # Tool list to initialize the client
+## tools = [utcNow]
+## # Tool handler map is passed to Tools.handleToolCalls!
+## toolHandlerMap = Dict.fromList [(utcNow.name, utcNow.handler)]
+## client = Client.init { apiKey, model: "tool-capable/model", tools }
+##
+## #...
+##
+## messages = Chat.appendUserMessage previousMessages newMessage
+## response = Http.send (Chat.buildHttpRequest client messages {}) |> Task.result!
+## updatedMessages = updateMessagesFromResponse response messages |> Tools.handleToolCalls! client toolHandlerMap
+## ```
 module { getUtcNow, utcToNanos } -> [utcNow]
 
 import InternalTools exposing [Tool, buildTool]
@@ -11,6 +27,8 @@ 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" []
 

package/Toolkit/Wikipedia.roc

@@ -1,3 +1,22 @@
+## A collection of prebuilt tools for interacting with Wikipedia.
+##
+## Usage:
+## ```
+## # Tool list to initialize the client
+## tools = [wikipediaSearch, wikipediaParse]
+## # Tool handler map is passed to Tools.handleToolCalls!
+## toolHandlerMap = Dict.fromList [
+##     (wikipediaSearch.name, wikipediaSearch.handler),
+##     (wikipediaParse.name, wikipediaParse.handler),
+## ]
+## client = Client.init { apiKey, model: "tool-capable/model", tools }
+##
+## #...
+##
+## messages = Chat.appendUserMessage previousMessages newMessage
+## response = Http.send (Chat.buildHttpRequest client messages {}) |> Task.result!
+## updatedMessages = updateMessagesFromResponse response messages |> Tools.handleToolCalls! client toolHandlerMap
+## ```
 module { sendHttpReq } -> [wikipediaSearch, wikipediaParse]
 
 import json.Json
@@ -6,14 +25,16 @@ import Shared exposing [urlEncode]
 
 baseUrl = "https://en.wikipedia.org/w/api.php"
 
-## Expose name, handler and tool for the wikipediaSarch
+## Expose name, handler and tool for the wikipediaSarch.
+##
+## This tool allows the model to search Wikipedia for a given query.
 wikipediaSearch = {
     name: wikipediaSearchTool.function.name,
     handler: wikipediaSearchHandler,
     tool: wikipediaSearchTool,
 }
 
-## Tool definition for the wikepedia search function
+## Tool definition for the wikepedia search function.
 wikipediaSearchTool : Tool
 wikipediaSearchTool =
     queryParam = {
@@ -70,7 +91,9 @@ wikipediaSearchHandler = \args ->
                     "Failed to get response from Wikipedia"
                     |> Task.ok
 
-## Expose name, handler and tool for the wikipediaParse
+## Expose name, handler and tool for the wikipediaParse tool.
+##
+## This tool allows the model to parse a Wikipedia article.
 wikipediaParse = {
     name: wikipediaParseTool.function.name,
     handler: wikipediaParseHandler,

package/Toolkit/WolframAlpha.roc

@@ -1,10 +1,30 @@
+## A prebuilt tool for interacting with Wolfram Alpha.
+##
+## Usage:
+## ```
+## # Tool list to initialize the client
+## tools = [wolframShortAnswer]
+## # Tool handler map is passed to Tools.handleToolCalls!
+## toolHandlerMap = Dict.fromList [
+##     (wolframShortAnswer.name, wolframShortAnswer.handler),
+## ]
+## client = Client.init { apiKey, model: "tool-capable/model", tools }
+##
+## #...
+##
+## messages = Chat.appendUserMessage previousMessages newMessage
+## response = Http.send (Chat.buildHttpRequest client messages {}) |> Task.result!
+## updatedMessages = updateMessagesFromResponse response messages |> Tools.handleToolCalls! client toolHandlerMap
+## ```
 module { sendHttpReq, getEnvVar } -> [wolframShortAnswer]
 
 import json.Json
 import InternalTools exposing [Tool]
 import Shared exposing [urlEncode]
 
-## Expose name, handler and tool for shortAnswer
+## 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: shortAnswerTool.function.name,
     handler: shortAnswerHandler,

package/Toolkit/WorldTimeApi.roc

@@ -1,9 +1,27 @@
+## A prebuilt tool for interacting with the WorldTimeApi.
+##
+## Usage:
+## ```
+## # Tool list to initialize the client
+## tools = [currentTime]
+## # Tool handler map is passed to Tools.handleToolCalls!
+## toolHandlerMap = Dict.fromList [(currentTime.name, currentTime.handler)]
+## client = Client.init { apiKey, model: "tool-capable/model", tools }
+##
+## #...
+##
+## messages = Chat.appendUserMessage previousMessages newMessage
+## response = Http.send (Chat.buildHttpRequest client messages {}) |> Task.result!
+## updatedMessages = updateMessagesFromResponse response messages |> Tools.handleToolCalls! client toolHandlerMap
+## ```
 module { sendHttpReq } -> [currentTime]
 
 import InternalTools exposing [Tool]
 import json.Json
 
-## Expose name, handler and tool for the currentTime
+## 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: tool.function.name,
     handler,