Add Python example for calling the OpenAI Chat API

Signed-off-by: Han Verstraete (OpenFaaS Ltd) <han@openfaas.com>

Author: welteki

docs/languages/python.md

@@ -709,6 +709,113 @@ curl http://127.0.0.1:8080/function/kafka-producer \
   --data "Hello from OpenFaaS"
 ```
 
+## Example: Call the OpenAI Chat API
+
+This example shows how to call the OpenAI Chat Completions API from a Python function using the official `openai` SDK.
+
+**1. Create the function**
+
+Pull the `python3-http` template and scaffold a new function. The `openai` package is pure Python, so the Alpine-based template is fine here.
+
+```bash
+faas-cli template store pull python3-http
+faas-cli new --lang python3-http openai-chat \
+  --prefix ttl.sh/openfaas-examples
+```
+
+The example uses the public [ttl.sh](https://ttl.sh) registry — replace the prefix with your own registry for production use.
+
+**2. Add the openai dependency**
+
+Add `openai` to the function's `requirements.txt` so it gets installed during the build:
+
+```
+openai
+```
+
+**3. Create a secret for the API key**
+
+Store the OpenAI API key as an OpenFaaS secret. This keeps the key out of environment variables and the function's container image.
+
+Save your API key to `openai-api-key.txt`, then run:
+
+```bash
+faas-cli secret create openai-api-key --from-file openai-api-key.txt
+```
+
+At runtime, the secret is mounted as a file under `/var/openfaas/secrets/` inside the function container.
+
+**4. Configure the function**
+
+Update `stack.yaml` to attach the secret created in the previous step:
+
+```yaml
+functions:
+  openai-chat:
+    lang: python3-http
+    handler: ./openai-chat
+    image: ttl.sh/openfaas-examples/openai-chat:latest
+    secrets:
+    - openai-api-key
+```
+
+**5. Write the handler**
+
+The handler reads the OpenAI API key from the mounted secret and uses it to create a chat completion. The request body is sent as the user message.
+
+The OpenAI client is initialised once on the first request and stored in a global variable. This means subsequent invocations reuse the same client, avoiding the overhead of creating a new connection on every request.
+
+```python
+from openai import OpenAI
+
+client = None
+
+def initClient():
+    apiKey = read_secret('openai-api-key')
+    return OpenAI(api_key=apiKey)
+
+def handle(event, context):
+    global client
+
+    # Initialise the client once and reuse it across invocations
+    if client is None:
+        client = initClient()
+
+    completion = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[
+            {"role": "user", "content": event.body.decode("utf-8")}
+        ]
+    )
+
+    return {
+        "statusCode": 200,
+        "body": completion.choices[0].message.content
+    }
+
+def read_secret(name):
+    with open("/var/openfaas/secrets/" + name, "r") as f:
+        return f.read().strip()
+```
+
+**6. Deploy and invoke**
+
+Build, push and deploy the function with `faas-cli up`. The `--filter` flag selects a single function from the stack file and `--tag digest` uses the image content hash as the tag instead of `latest`, so that Kubernetes always pulls an updated image:
+
+```bash
+faas-cli up \
+ --filter openai-chat \
+ --tag digest
+
+# Send a prompt to the function
+curl http://127.0.0.1:8080/function/openai-chat \
+  --data "What is the capital of France?"
+```
+
+!!! tip "Streaming responses with Server-Sent Events (SSE)"
+
+    This example waits for the full completion before responding. To stream tokens back to the client as they are generated, you can use Server-Sent Events (SSE) with the `python3-flask` template, which gives direct access to Flask's `stream_with_context` helper. See [Stream OpenAI responses from functions using Server Sent Events](https://www.openfaas.com/blog/openai-streaming-responses/) on the OpenFaaS blog for a working example.
+
 ## OpenTelemetry zero-code instrumentation
 
 Using [OpenTelemetry zero-code instrumentation](https://opentelemetry.io/docs/zero-code/python/) for python functions requires some minor modifications to the existing Python templates.