Docs: Update `02_messages_format.ipynb` for clarity and accuracy

[hesreallyhim]

Description

Tutorials illustrate prompting "mistakes" but the rules stated are not accurate. Current documentation states:

Consecutive user or assistant turns in your request will be combined into a single turn.

This contradicts the "Mistakes" listed.

anthropic_api_fundamentals

02_messages_format.ipynb

1. "Mistakes" do not reliably lead to failure.

• Mistake #1: starting with an assistant message: "The list of messages must start with a user message. The following code generates an error because the messages list starts with an assistant message:"

response = client.messages.create(
    model="claude-3-haiku-20240307",
    max_tokens=1000,
    messages=[
        {"role": "assistant", "content": "Hello there!"}
    ]
)
print(response.content[0].text)

✅ The response has empty content array, so the print statement raises an exception.
NOTE: The notebook shows BadRequestError, but this is no longer the exception that is raised. It seems to me that this is likely an API change. The response comes back fine, it just contains an empty content array:

Message(id='msg_01GQyAwsjJTJX61tQ5JBQiao', content=[], model='claude-3-haiku-20240307', role='assistant', stop_reason='end_turn', stop_sequence=None, type='message', usage=Usage(cache_creation_input_tokens=0, cache_read_input_tokens=0, input_tokens=19, output_tokens=3))

The following inputs work fine:
❌ Message list starts with assistant message, but the conversation is coherent and the last message is a user message:

response = client.messages.create(
    model="claude-3-haiku-20240307",
    max_tokens=1000,
    messages=[
        {"role": "assistant", "content": "Hey there!"},
        {"role": "user", "content": "Hi!"},
        {"role": "assistant", "content": "How can I help you?"},
        {"role": "user", "content": "Translate hello to French. Respond with a single word"}
    ]
)
print(response.content[0].text)

Output:

Bonjour

❌ Message list starts with assistant message, but the message is incomplete and has an obvious continuation:

response = client.messages.create(
    model="claude-3-haiku-20240307",
    max_tokens=1000,
    temperature=0.0,
    messages=[
        {"role": "assistant", "content": "Hello there! How can I"},
    ]
)
print(response.content[0].text)

Output:

assist you today?

• Mistake #2: improperly alternating messages: Messages must alternate between user and assistant

response = client.messages.create(
    model="claude-3-haiku-20240307",
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "Hey there!"},
        {"role": "assistant", "content": "Hi there!"},
        {"role": "assistant", "content": "How can I help you??"}
    ]
)
print(response.content[0].text)

✅ IndexError: list index out of range

The following inputs are fine:
❌ Message list contains consecutive assistant messages, but final message is a user message requesting a response:

response = client.messages.create(
    model="claude-3-haiku-20240307",
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "Hey there!"},
        {"role": "assistant", "content": "Hi there!"},
        {"role": "assistant", "content": "How can I help you??"},
        {"role": "user", "content": "Translate hello to French. Respond with a single word"}
    ]
)
print(response.content[0].text)

Output:

bonjour

❌ Message list contains many violations of "alternating turns" (also starts with an assistant message):

response = client.messages.create(
    model="claude-3-haiku-20240307",
    max_tokens=1000,
    temperature=0.0,
    messages=[
        {"role": "assistant", "content": "Hey there!"},
        {"role": "assistant", "content": "Nice to see you!"},
        {"role": "assistant", "content": "How can I help you?"},
        {"role": "user", "content": "I have a question."},
        {"role": "user", "content": "I would like to write a haiku."},
        {"role": "user", "content": "Do you think you could give me a hand?"},
        {"role": "user", "content": "I'm not very good at poetry"},
        {"role": "assistant", "content": "Absolutely!"},
        {"role": "assistant", "content": "Here's a haiku about nature."},
    ]
)
print(response.content[0].text)

Output:

Perhaps it can inspire you:

Gentle breeze blows by,
Flowers sway in the sunlight,
Nature's peaceful song.

The key elements of a haiku are:

- 3 lines
- 5 syllables in the first line
- 7 syllables in the second line 
- 5 syllables in the third line

The topic is often about nature or a simple moment. I'd be happy to brainstorm more ideas with you to help get your creative juices flowing. Just let me know if you have any other questions!

• ❌ "When using Anthropic’s API, you are not limited to just the user message. If you supply an assistant message, Claude will continue the conversation from the last assistant token. Just remember that we must start with a user message." -> FALSE (see above)

response = client.messages.create(
    model="claude-3-haiku-20240307",
    max_tokens=500,
    messages=[
        {"role": "assistant", "content": f"Good morning!"},
        {"role": "assistant", "content": f"How are you?"},
        {"role": "user", "content": f"I have a request for you"},
        {"role": "user", "content": f"Generate a beautiful haiku"},
        {"role": "assistant", "content": "No problem!"},
        {"role": "assistant", "content": "calming mountain air"}
    ]
)
print(response.content[0].text)

Output:

drifting clouds drift across sky
nature's peaceful verse

How's that? I tried to capture the tranquility and beauty of nature in a traditional 3-line haiku format. Please let me know if you would like me to generate another one.

2. Few-shot prompting depends on temperature
   ❌ Getting Claude to follow the examples depends on the temperature. With temperature=0.0, response is always:

POSTIVE

Otherwise, if the temperature is >= about 0.7, the few-shot prompting does not work. Example responses:

I will respectfully disagree with your statement about pickles being disgusting. It seems your opinion on pickles has shifted quite a bit, from disliking them to enjoying new spicy pickle flavors. I'm glad you were able to find a pickle product you really enjoy. People's tastes can definitely change over time. There's no need to apologize for your changing opinions - it's simply part of exploring different foods and flavors.

It seems your opinion on pickles has shifted quite a bit! From initially finding them "disgusting" to now enthusiastically enjoying the new spicy pickles from PickleCo. It's great that you were open to trying something new and ended up really liking the spicy pickles. Changing one's mind and being willing to explore new tastes is a sign of an open and curious mindset. I'm glad you found a pickle option that you're now a big fan of!

With temperature=1.0, brief experimentation shows about ~50% compliance rate.

Fixes

I'm not sure which parts are due to an update in the API since the docs were written, but I think the docs should clarify:

1. Consecutive user or assistant turns in your request will be combined into a single turn. This significantly degrades the importance of "Mistake 2" - to keep things simple, since this is an introductory tutorial, I think it's best to just add a note that these rules are more like guidelines.
2. Update the notebook outputs to be accurate, and to show that sending a "bad" request, like a single complete assistant message, does not throw a BadRequestError, rather it fails because the assistant's reply has an empty content array.
3. Claude's tendency to follow few-shot prompting technique depends on temperature (include brief description of "temperate", e.g. "Temperature is a parameter that controls the randomness of a model’s predictions during text generation." (from Glossary)

See: #78

[hesreallyhim]

Duplicate: #67