chore: import upstream snapshot with attribution

examples/openai-tools-call/README.md

@@ -0,0 +1,57 @@
+# openai-tools-call (OpenAI Tools Call Example)
+
+This example demonstrates how to use promptfoo to evaluate OpenAI's tools calling capabilities. It shows how to define and test tool usage with the Chat Completions API.
+
+## Features Demonstrated
+
+- Defining tools for AI models to use
+- Testing tool call outputs
+- Validating AI-generated function arguments
+- Transforming outputs for assertions
+
+## Environment Variables
+
+This example requires the following environment variables:
+
+- `OPENAI_API_KEY` - Your OpenAI API key
+
+You can set this in a `.env` file or directly in your environment.
+
+## Running the Example
+
+You can run this example with:
+
+```bash
+npx promptfoo@latest init --example openai-tools-call
+# and then
+cd openai-tools-call
+
+# Run the evaluation
+npx promptfoo eval
+
+# View the results
+npx promptfoo view
+```
+
+## What This Example Does
+
+The configuration defines a custom tool for getting weather information. It then tests the model's ability to:
+
+1. Correctly call the weather function when asked about weather
+2. Pass the correct location parameter based on the city mentioned
+3. Handle various cities, including international ones
+4. Format responses consistently
+
+## Key Features
+
+- Uses `is-valid-openai-tools-call` assertion to validate the function call structure
+- Demonstrates output transformation to isolate and test specific parts of the response
+- Shows how to use JavaScript assertions for detailed validation
+- Tests with a variety of locations to ensure robust behavior
+
+## Documentation
+
+For more details, see:
+
+- [OpenAI Tools documentation](https://platform.openai.com/docs/guides/function-calling)
+- [promptfoo OpenAI Provider documentation](https://promptfoo.dev/docs/providers/openai#using-tools-and-functions)

examples/openai-tools-call/promptfooconfig.yaml

@@ -0,0 +1,73 @@
+# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
+description: OpenAI tools calling with weather API integration
+
+prompts:
+  - 'What is the weather like in {{city}}?'
+
+providers:
+  - id: openai:chat:gpt-5.4-mini
+    config:
+      verbosity: high
+      tools:
+        [
+          {
+            'type': 'function',
+            'function':
+              {
+                'name': 'get_current_weather',
+                'description': 'Get the current weather in a given location',
+                'parameters':
+                  {
+                    'type': 'object',
+                    'properties':
+                      {
+                        'location':
+                          {
+                            'type': 'string',
+                            'description': 'The city and state, e.g. San Francisco, CA',
+                          },
+                        'unit': { 'type': 'string', 'enum': ['celsius', 'fahrenheit'] },
+                      },
+                    'required': ['location'],
+                  },
+              },
+          },
+        ]
+
+tests:
+  - vars:
+      city: Boston
+    assert:
+      - type: is-json
+      - type: is-valid-openai-tools-call
+      - type: javascript
+        value: output[0].function.name === 'get_current_weather'
+      - type: javascript
+        value: JSON.parse(output[0].function.arguments).location === 'Boston, MA'
+
+  - vars:
+      city: New York
+    options:
+      # Transform is a cleaner way to pick out specific properties.
+      # This transform returns only the 'name' property
+      transform: output[0].function.name
+    assert:
+      - type: equals
+        value: get_current_weather
+
+  - vars:
+      city: Paris
+    assert:
+      - type: equals
+        value: get_current_weather
+        # Transform is a cleaner way to pick out specific properties.
+        # This transform returns only the 'name' property
+        transform: output[0].function.name
+      - type: similar
+        value: Paris, France
+        threshold: 0.5
+        # This transform returns only the parsed location argument.
+        transform: JSON.parse(output[0].function.arguments).location
+
+  - vars:
+      city: Mars