Merge pull request #1 from lazy-hq/tool-docs

Tool docs

Author: ishaksebsib

apps/docs/content/docs/concepts/tools.mdx

@@ -2,4 +2,152 @@
 title: Tools
 ---
 
-//TODO:
+A 'Tool' is a general term for a function or logic that can be executed by an AI
+model. They can be user defined or pre-defined by the provider. Tools are provided
+to the AI model's context as per the developer's needs.The AI model can then use the
+provided tools to perform specific queries to aid in text generation or actions to
+be taken externally. Most common tools include the following searching the web,
+querying a public API, executing a shell command, and more.
+
+Here is the recommended and less verbose way to define a tool. It allows you to annotate native
+Rust functions with the `#[tool]` macro, which will generate a `Tool` struct for you.
+
+```rust
+use crate::core::{tool, Tool};
+
+#[tool]
+/// Get the weather information given a location
+pub fn get_weather(location: String) {
+    let weather = match location.as_str() {
+        // Some logic to query a weather API
+        "New York" => 75,
+        "Tokyo" => 80,
+        _ => 70,
+    };
+    Ok(weather.to_string())
+}
+```
+
+A tool has 4 components:
+
+- **name**: It is used to identify the tool in the AI model. Make sure it is unique and describes
+what the tool does well. The name of the tool in this case is `get_weather`.
+
+- **description**: This is a brief description of what the tool does. It is used to
+help the AI model understand what the tool does and how to use it. The function's doc comment 
+as the description. you can use rust style documentation with examples for few-shot prompting
+
+- **arguments**: This is the schema of the input that the AI model will use to generate
+inputs for the tool. It uses the [schemars](https://docs.rs/schemars/latest/schemars/) crate
+to define the [json schema](https://json-schema.org/) of the input. The function's arguments
+are serialized into json schema in which the AI model will use to generate inputs. 
+just make sure
+the arguments implement the `schemars::JsonSchema` trait or are natively supported
+by the `schemars` crate.
+
+- **body**: This is the logic that will be called when the AI model calls the tool. it 
+takes a single argument of type `serde_json::Value` which is the json input provided by the AI model. the function should return a `Result<String, String>`
+which is the output of the tool. If the tool fails, you can return an error message as `Err(String)` which can
+also be helpful for the AI model to understand what went wrong.
+
+You can optionally override the `name` and `description` of the tool by passing them as arguments to the `#[tool]` macro.
+
+```rust
+use crate::core::{tool, Tool};
+
+#[tool(name = "get-weather", description = "Get the weather information given a location")]
+/// A tool that returns the weather information given a location
+pub fn get_weather(location: String) {
+    let weather = match location.as_str() {
+        // Some logic to query a weather API
+        "New York" => 75,
+        "Tokyo" => 80,
+        _ => 70,
+    };
+    Ok(weather.to_string())
+}
+```
+
+This will make the tool name and description configurable. name will be `get-weather` and description will be `Get the weather information given a location`.
+
+
+## Using the structs
+
+You can define your own tools in aisdk by instantiating the `Tool` and related structs and passing
+it to one of the AI model text generation builders.
+
+```rust
+use super::{Tool, ToolExecute};
+use serde_json::Value;
+    
+// define tool function body, should return Result<String, String>
+#[allow(unused_variables)]
+let func = ToolExecute::new(Box::new(|inp: Value| {
+    // Ai SDK will pass in a json object with the following structure
+    // ```json
+    // {
+    //     "location": "New York"
+    // }
+    // ```
+    let location = inp.get("location").unwrap();
+    Ok(format!("Cloudy"))
+}));
+
+// define tool input structure
+#[derive(schemars::JsonSchema, Debug)]
+#[allow(dead_code)]
+struct ToolInput {
+    location: String,
+}
+
+// change tool arguments to json schema
+// Which will be similar to the following
+// ```json
+// "properties": {
+//     "location": {
+//         "type": "string"
+//     }
+// }
+let schema = schemars::schema_for!(ToolInput);
+
+// bring it all together
+let get_weather_tool = Tool::builder()
+    .name("get-weather")
+    .description("Get the weather information given a location")
+    .input_schema(schema.clone())
+    .execute(func)
+    .build()
+    .unwrap();
+
+```
+
+## Registering the tool
+
+To register the tool with the AI model, you need to add it to text generation builders using the `with_tool` method. This
+appends the tool to the list of tools that the AI model will use to generate text.
+
+```rust
+// call the model with the `#[tool]` macro
+let result = LanguageModelRequest::builder()
+    .model(OpenAI::new("gpt-4o"))
+    .system("You are a helpful assistant with access to tools.")
+    .prompt("What is the weather in New York?")
+    .with_tool(get_weather())
+    .build()
+    .generate_text()
+    .await;
+```
+
+or if you are using the structs
+
+```rust
+// call the model with `Tool` struct
+let result = LanguageModelRequest::builder()
+    .model(OpenAI::new("gpt-4o"))
+    .system("You are a helpful assistant with access to tools.")
+    .prompt("What is the weather in New York?")
+    .with_tool(get_weather_tool) // you don't need to call it if using structs.
+    .build()
+    .generate_text()
+    .await;
+```

package.json

@@ -4,8 +4,8 @@
 	"scripts": {
 		"build": "turbo run build",
 		"dev": "turbo run dev",
-		"format-and-lint": "biome check .",
-		"format-and-lint:fix": "biome check . --write",
+		"format-and-lint": "npx biome check .",
+		"format-and-lint:fix": "npx biome check . --write",
 		"check-types": "turbo run check-types"
 	},
 	"devDependencies": {