Slim initial python API docs for tools and chains, closes #1022

Author: simonw

docs/python-api.md

@@ -45,6 +45,50 @@ If you have set a `OPENAI_API_KEY` environment variable you can omit the `model.
 
 Calling `llm.get_model()` with an invalid model ID will raise a `llm.UnknownModelError` exception.
 
+(python-api-tools)=
+
+### Tools
+
+{ref}`Tools <tools>` are functions that can be executed by the model as part of a chain of responses.
+
+You can define tools in Python code - with a docstring to describe what they do - and then pass them to the `model.prompt()` method using the `tools=` keyword argument. If the model decides to request a tool call the `response.tool_calls()` method show what the model wants to execute:
+
+```python
+import llm
+
+def upper(text: str) -> str:
+    """Convert text to uppercase."""
+    return text.upper()
+
+model = llm.get_model("gpt-4.1-mini")
+response = model.prompt("Convert panda to upper", tools=[upper])
+tool_calls = response.tool_calls()
+# [ToolCall(name='upper', arguments={'text': 'panda'}, tool_call_id='...')]
+```
+You can call `response.execute_tool_calls()` to execute those calls and get back the results:
+```python
+tool_results = response.execute_tool_calls()
+# [ToolResult(name='upper', output='PANDA', tool_call_id='...')]
+```
+To pass the results of the tool calls back to the model you need to use a utility method called `model.chain()`:
+```python
+chain_response = model.chain(
+    "Convert panda to upper",
+    tools=[upper],
+)
+print(chain_response.text())
+# The word "panda" converted to uppercase is "PANDA".
+```
+You can also loop through the `model.chain()` response to get a stream of tokens, like this:
+```python
+for chunk in model.chain(
+    "Convert panda to upper",
+    tools=[upper],
+):
+    print(chunk, end="", flush=True)
+```
+This will stream each of the chain of responses in turn as they are generated.
+
 (python-api-system-prompts)=
 
 ### System prompts

docs/tools.md

@@ -20,4 +20,6 @@ In LLM every tool is a defined as a Python function. The function can take any n
 
 Tool functions should include a docstring that describes what the function does. This docstring will become the description that is passed to the model.
 
-The Python API can accept functions directly. The command-line interface has two ways for tools to be defined: via plugins that implement the {ref}`register_tools() plugin hook <plugin-hooks-register-tools>`, or directly on the command-line using the `--functions` argument to specify a block of Python code defining one or more functions - or a path to a Python file containing the same.
+The Python API can accept functions directly. The command-line interface has two ways for tools to be defined: via plugins that implement the {ref}`register_tools() plugin hook <plugin-hooks-register-tools>`, or directly on the command-line using the `--functions` argument to specify a block of Python code defining one or more functions - or a path to a Python file containing the same.
+
+You can use tools {ref}`with the LLM command-line tool <usage-tools>` or {ref}`with the Python API <python-api-tools>`.