How to provide titles and descriptions in the data structure?

API
1

On this page, OpenAI recommends the following:

Tips for your data structure

To maximize the quality of model generations, we recommend the following:

Name keys clearly and intuitively
Create clear titles and descriptions for important keys in your structure
Create and use evals to determine the structure that works best for your use case

The example given is as follows:

from pydantic import BaseModel

class Step(BaseModel):
    explanation: str
    output: str

class MathResponse(BaseModel):
    steps: list[Step]
    final_answer: str

How do I provide titles and descriptions for this data structure?

1 Like
2

To provide titles and descriptions for your data structure using Pydantic, you can use the Field function from Pydantic. This allows you to add metadata to your fields, such as titles and descriptions. Here’s how you can modify the given example to include titles and descriptions:

from pydantic import BaseModel, Field

class Step(BaseModel):
    explanation: str = Field(..., title="Explanation", description="A detailed explanation of the step.")
    output: str = Field(..., title="Output", description="The output result of the step.")

class MathResponse(BaseModel):
    steps: list[Step] = Field(..., title="Steps", description="A list of steps involved in solving the problem.")
    final_answer: str = Field(..., title="Final Answer", description="The final answer to the problem.")

In this example:

  • Field is used to add a title and description to each field in the Step and MathResponse classes.
  • The ... indicates that the field is required.

Do let me know if this helped or further describe your issue! :hugs:

1 Like
3

Fantastic! And damn quick response. Thank you very much for that. I will try this now and update.

1 Like
4

For my previous answer, Copilot might have given me a hand.
I can only recommend it for simpler issues like this. :smile:

Feel free to mark my answer as a solution so future users will have an easier time in finding a solution. :hugs:

1 Like
5

Also - titles are are auto-generated from the class names. You do not need to override them unless you’ve got a much better schema for the AI to see as response_format.

The quality of the schema actually sent and understood is reflected in the quality of the contents produced (AI can’t choose not to follow the container, though, but can misuse arrays).

For functions, titles are just part of the description the AI receives.

You might be curious if one logs OpenAI’s Python pydantic construction of the code above, showing each schema object created to develop the final response format schema, in this case, nested.

{'description': 'A detailed explanation of the step.', 'title': 'Explanation Title', 'type': 'string'}
{'description': 'The output result of the step.', 'title': 'title_step-output', 'type': 'string'}
{'properties': {'explanation': {'description': 'A detailed explanation of the step.', 'title': 'Explanation Title', 'type': 'string'}, 'output': {'description': 'The output result of the step.', 'title': 'title_step-output', 'type': 'string'}}, 'required': ['explanation', 'output'], 'title': 'Step', 'type': 'object', 'additionalProperties': False}
{'$ref': '#/$defs/Step'}
{'description': 'A list of steps involved in solving the problem.', 'items': {'$ref': '#/$defs/Step'}, 'title': 'title of steps', 'type': 'array'}
{'description': 'The final answer to the problem.', 'title': 'title of answer', 'type': 'string'}
{'$defs': {'Step': {'properties': {'explanation': {'description': 'A detailed explanation of the step.', 'title': 'Explanation Title', 'type': 'string'}, 'output': {'description': 'The output result of the step.', 'title': 'title_step-output', 'type': 'string'}}, 'required': ['explanation', 'output'], 'title': 'Step', 'type': 'object', 'additionalProperties': False}}, 'properties': {'steps': {'description': 'A list of steps involved in solving the problem.', 'items': {'$ref': '#/$defs/Step'}, 'title': 'title of steps', 'type': 'array'}, 'final_answer': {'description': 'The final answer to the problem.', 'title': 'title of answer', 'type': 'string'}}, 'required': ['steps', 'final_answer'], 'title': 'MathResponse', 'type': 'object', 'additionalProperties': False}

What’s being sent as response_format when I modify the titles to make them obvious, before conversion to JSON:

{'$defs': {'Step': {'properties': {'explanation': {'description': 'A detailed explanation of the step.', 'title': 'Explanation Title', 'type': 'string'}, 'output': {'description': 'The output result of the step.', 'title': 'title_step-output', 'type': 'string'}}, 'required': ['explanation', 'output'], 'title': 'Step', 'type': 'object', 'additionalProperties': False}}, 'properties': {'steps': {'description': 'A list of steps involved in solving the problem.', 'items': {'$ref': '#/$defs/Step'}, 'title': 'title of steps', 'type': 'array'}, 'final_answer': {'description': 'The final answer to the problem.', 'title': 'title of answer', 'type': 'string'}}, 'required': ['steps', 'final_answer'], 'title': 'MathResponse', 'type': 'object', 'additionalProperties': False}