docs: add example of f.signature (#955)

Signed-off-by: Louis Mandel <[email protected]>

Author: mandel

examples/tools/search.pdl

@@ -0,0 +1,40 @@
+description: tool use
+defs:
+  search:
+    description: Wikipedia search
+    function:
+      topic:
+        type: string
+        description: Topic to search
+    return:
+      lang: python
+      code: |
+        import warnings, wikipedia
+        warnings.simplefilter("ignore")
+        try:
+          result = wikipedia.summary("${ topic }")
+        except wikipedia.WikipediaException as e:
+          result = str(e)
+text:
+- role: system
+  content: |
+    You are a helpful AI assistant with access to the 
+    following tools. If a tool does not exist in the 
+    provided list of tools, notify the user that you 
+    do not have the ability to fulfill the request.
+  contribute: [context]
+- role: tools
+  content:
+    text: ${ [ search.signature ] }
+  contribute: [context]
+- "What is the circumference of planet Earth?\n"
+- def: actions
+  model: ollama_chat/granite3.3:8b
+  parser: json
+  spec: [{ name: str, arguments: { topic: str }}]
+- "\n"
+- if: ${ actions[0].name == "search" }
+  then:
+    call: ${ search }
+    args:
+      topic: ${ actions[0].arguments.topic }

tests/results/examples/tools/search.0.result

@@ -0,0 +1,6 @@
+What is the circumference of planet Earth?
+[{'name': 'search', 'arguments': {'topic': 'circumference of Earth'}}]
+Earth's circumference is the distance around Earth. Measured around the equator, it is 40,075.017 km (24,901.461 mi). Measured passing through the poles, the circumference is 40,007.863 km (24,859.734 mi).
+Treating the Earth as a sphere, its circumference would be its single most important measurement. The first known scientific measurement and calculation was done by Eratosthenes, by comparing altitudes of the mid-day sun at two places a known north–south distance apart. He achieved a great degree of precision in his computation. The Earth's shape deviates from spherical by flattening, but by only about 0.3%.
+
+Measurement of Earth's circumference has been important to navigation since ancient times. In modern times, Earth's circumference has been used to define fundamental units of measurement of length: the nautical mile in the seventeenth century and the metre in the eighteenth. Earth's polar circumference is very near to 21,600 nautical miles because the nautical mile was intended to express one  minute of latitude (see meridian arc), which is 21,600 partitions of the polar circumference (that is 60 minutes × 360 degrees). The polar circumference is also close to 40,000 kilometres because the metre was originally defined to be one ten millionth (i.e., a kilometre is one ten thousandth) of the arc from pole to equator (quarter meridian). The accuracy of measuring the circumference has improved since then, but the physical length of each unit of measure had remained close to what it was determined to be at the time, so the Earth's circumference is no longer a round number in metres or nautical miles.