"temperature" as the real-world examples in *-chat-functions.adoc is problematic

[joemoore]

The use of "temperature" as a real-world example in the *chat-functions.adoc files (spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/functions) is problematic for several reasons:

• Conflates the temperature aspect of generative AI with these terminology-colliding "temperature" examples.
• Obscures documentation searches for temperature which confusingly adds search results from the above files.
• Results in confusing example scenarios and discussions:
  • "For a more accurate 'temperature' set the temperature of the 'temperature' so that the 'temperature' is less impacted by the temperature."
  • "What is the temperature in the example?" "It's 0.5" "Wow, that's cold." "Huh?"

There are many other example scenarios that can be used to get the point across, even in the "weather" or "location" domains, that can avoid this terminology collision. I'm willing to work on a PR with an alternative, perhaps "humidity", unless changes to these examples are a non-starter for some reason.

[tzolov]

Hi @joemoore , I see how this could cause some confusion, but I doubt it is that profound. The weather use case comes from the OpenAI's own function-calling guide and I have not heard confusions complains. Also, I've run couple of "temperature" related searches and expectedly the runtime options top the results. What I don't like is that the Function Calling introduction page is too anaemic. We need to improve this.

So far we have few other function calling use-cases implementations in our ITs and demos and we plan to setup a dedicated spring-ai samples repository soon. So if you would be interested to contribute, perhaps you can implement an new interesting demo/use-case.

[markpollack]

I agree that the weather use case isn't going to confuse people in terms of the concept of temperature. Closing. Overall review of docs generally speaking is a generic task for 1.0 GA.