From 081baf203cac528f02492244fa78ac708723ca1f Mon Sep 17 00:00:00 2001
From: Luciano Scarpulla <scarpulla53@gmail.com>
Date: Tue, 12 Nov 2024 12:18:33 +0800
Subject: [PATCH] add README section

---
 README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/README.md b/README.md
index acac77d..644859b 100644
--- a/README.md
+++ b/README.md
@@ -261,6 +261,50 @@ The universe is never done.
 
 Simple, yet effective.
 
+### Tools (Function calling)
+Tools (also known as functions) let you call any Python function from your AI conversations. Here's an example:
+
+```python
+def get_weather(
+    location: Annotated[
+        str, Field(description="The city and state, e.g. San Francisco, CA")
+    ],
+    unit: Annotated[
+        Literal["celcius", "fahrenheit"],
+        Field(
+            description="The unit of temperature, either 'celsius' or 'fahrenheit'"
+        ),
+    ] = "celcius",
+):
+    """
+    Get the current weather in a given location
+    """
+    return f"42 {unit}"
+
+# Add your function as a tool
+conversation = sm.create_conversation()
+conversation.add_message("user", "What's the weather in San Francisco?")
+response = conversation.send(tools=[get_weather])
+```
+
+Note how we're using Python's `Annotated` feature combined with `Field` to provide additional context to our function parameters. This helps the AI understand the intention and constraints of each parameter, making tool calls more accurate and reliable.
+You can alos ommit `Annotated` and just pass the `Field` parameter.
+```python
+def get_weather(
+    location: str = Field(description="The city and state, e.g. San Francisco, CA"),
+    unit:Literal["celcius", "fahrenheit"]= Field(
+        default="celcius",
+        description="The unit of temperature, either 'celsius' or 'fahrenheit'"
+        ),
+):
+    """
+    Get the current weather in a given location
+    """
+    return f"42 {unit}"
+```
+
+Functions can be defined with type hints and Pydantic models for validation. The AI will intelligently choose when to call the functions and incorporate the results into its responses.
+
 ### Logging
 
 Simplemind uses [Logfire](https://pydantic.dev/logfire) for logging. To enable logging, call `sm.enable_logfire()`.