feat(genapi): parallel function call

Author: tgenaitay

ai-data/generative-apis/how-to/use-function-calling.mdx

@@ -184,6 +184,106 @@ if response.choices[0].message.tool_calls:
         print(final_response.choices[0].message.content)
 ```
 
+### Parallel function calling
+
+In addition to one function call described above, you can also call multiple functions in a single turn.
+This section shows an example for how you can use parallel function calling.
+
+Define the tools:
+
+```
+def open_floor_space(floor_number: int) -> bool:
+    """Opens up the specified floor for party space by unlocking doors and moving furniture."""
+    print(f"Floor {floor_number} is now open party space!")
+    return True
+
+def set_lobby_vibe(party_mode: bool) -> str:
+    """Switches lobby screens and lighting to party mode."""
+    status = "party mode activated!" if party_mode else "back to business mode"
+    print(f"Lobby is now in {status}")
+    return "The lobby is ready to party!"
+
+def prep_snack_station(activate: bool) -> bool:
+    """Converts the cafeteria into a snack and drink station."""
+    print(f"Snack station is {'open and stocked!' if activate else 'closed.'}")
+    return True
+```
+
+Define the specifications:
+
+```
+tools = [
+    {
+        "type": "function",
+        "function": {
+            "name": "open_floor_space",
+            "description": "Opens up an entire floor for the party",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "floor_number": {
+                        "type": "integer",
+                        "description": "Which floor to open up"
+                    }
+                },
+                "required": ["floor_number"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_lobby_vibe",
+            "description": "Transform lobby atmosphere into party mode",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "party_mode": {
+                        "type": "boolean",
+                        "description": "True for party, False for business"
+                    }
+                },
+                "required": ["party_mode"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "prep_snack_station",
+            "description": "Set up the snack and drink station",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "activate": {
+                        "type": "boolean",
+                        "description": "True to open, False to close"
+                    }
+                },
+                "required": ["activate"]
+            }
+        }
+    }
+]
+```
+
+Next, call the model with proper instructions
+
+```
+system_prompt = """
+You are an office party control assistant. When asked to transform the office into a party space, you should:
+1. Open up a floor for the party
+2. Transform the lobby into party mode
+3. Set up the snack station
+Make all these changes at once for an instant office party!
+"""
+
+messages = [
+    {"role": "system", "content": system_prompt},
+    {"role": "user", "content": "Turn this office building into a party!"}
+]
+```
+
 ## Best practices
 
 When implementing function calling, follow these guidelines for optimal results:
@@ -220,14 +320,8 @@ For more information about function calling and advanced implementations, refer
 - [JSON Schema Specification](https://json-schema.org/specification)
 - [Chat Completions API Reference](/ai-data/generative-apis/api-cli/using-chat-api/)
 
-## Conclusion
-
-Function calling significantly extends the capabilities of language models by allowing them to interact with external tools and APIs. By following the patterns and best practices outlined in this guide, you can create robust applications that combine the power of language models with practical functionality.
+Function calling significantly extends the capabilities of language models by allowing them to interact with external tools and APIs. 
 
-When implementing function calling, remember to:
-- Design clear and focused function definitions
-- Handle multi-turn conversations appropriately
-- Follow best practices for optimal performance
-- Implement proper error handling and validation
-
-Experiment with both simple and complex implementations to determine which approach best suits your application's needs.
+<Message type="note">
+  We can't wait to see what you will build with function calls. Tell us what you are up to, share your experiments on Scaleway's Slack community #ai 
+</Message>