Structured Output
This Cookbook takes about 10 minutes. You'll learn how to output structured data using AI.
While AI is often associated with conversational tools like ChatGPT, AIs are capable of producing structured data, which unlocks significantly more power and flexibility.
LLM providers initially called this feature "Functions". It was renamed to "Tools" to make it more relatable to non-technical users. Since then, it is clear that the most popular use of this feature is to structure the output of the AI. This is why we refer to it as Structure in the app.
What is Structured Data?
Structured data is information organized in a clear, consistent format, making it easy to use and analyze. Think of a spreadsheet: it's a simple example of structured data. Imagine you have a list of contacts. You could organize this list in a spreadsheet with columns for "First Name," "Last Name," and "Phone Number." Each row represents a single contact, and the columns provide a consistent structure for storing the information.
This structure makes the data easy to understand, search, and use in various ways. You can easily sort your contacts alphabetically, filter them by last name, or import them into another program.
Advantages of Using Structured Data with Telosnex
Just like a spreadsheet brings order to a list of contacts, structured data can organize the information generated by AI, making it far more powerful.
Instead of receiving a jumbled text response from the AI, you can use structured data to get precise and organized information. For example, if you have a PDF of a scanned exam, you can ask the AI to extract all the questions and answers in a structured format like this:
{
"questions": [
{
"question": "What is the capital of France?",
"answer": "Paris"
},
{
"question": "Who wrote the novel 'Pride and Prejudice'?",
"answer": "Jane Austen"
}
]
}
This is JSON (JavaScript Object Notation), a common and human-readable format for representing structured data. JSON employs a simple structure with keys and values, similar to a dictionary, where words (keys) correspond to their definitions (values).
In our example, the "questions" key has a value that is a list of question-and-answer pairs. Each pair has a "question" key and an "answer" key.
Structured data offers several key advantages:
- Precision: Extract only the specific data you need, eliminating manual searching and sorting through lengthy text responses.
- Automation: Link different actions within a Script, creating efficient, automated workflows. For instance, extract company names from a news article, then automatically format them into web search queries.
- Interoperability: Easily share and use your data with other tools. Copy structured data as a CSV or TSV file for use in programs like Excel or Google Sheets.
AI Beyond Conversation: The Power of Structured Templates
While Large Language Models (LLMs), like ChatGPT, are renowned for their conversational abilities, their capabilities extend far beyond chat. By using structured templates, we can guide these models to provide information in a format ready for various purposes.
Think of a structured template as a blueprint instructing the AI on how to organize the information it generates.
Plan
Goal
Our goal is to utilize JSON schemas to guide the AI in generating various types of structured data, moving beyond simple text responses. These schemas act as detailed instructions for the LLM, ensuring it delivers information in a structured and predictable way, guaranteeing data that's ready for use in other applications or steps in our workflow.
Creating a Script with Structured Output
We'll create a script with two main steps:
- Dialogue: Provide clear instructions to the AI, outlining the desired data and format.
- AI Chat: Leverage structured templates, guiding the AI to respond with data organized according to our chosen JSON schema.
Creating the Script
-
Navigate to the Scripts Screen: From the Home screen, press the Go button, then press Scripts. (See Manual > Companion > Go Button).
-
Create a New Script: Press the Add button (plus icon) at the top of the screen to start a new script.
Adding Steps
1. Dialogue
- Press Code at the top of the screen to switch to the Code view of your script.
- Press Dialogue to add a Dialogue step. This is where we provide instructions to the AI.
- Copy and paste the following instructions into the Dialogue step, tailoring them to the specific structured data you want to generate. We'll use the 'Problems' schema as an example:
Given the following text, extract any questions and their associated answer choices, formatted according to the 'Problems' template:
Input: {{prompt}}
This tells the AI that we want structured data based on the user's input. The {{prompt}} template dynamically inserts the user's input.
2. AI Chat
- Press AI Chat at the bottom of the Code tab to add an AI Chat step. This is where the AI generates the structured data.
- Change "Variable Name" to
data. This allows us to reference the structured data later if needed. - Press Structure, then press Add. We will now define the structure of our data using JSON schemas.
Defining Structure with JSON Schemas
JSON schemas are like precise recipes for structured data, telling the AI how to organize the information it generates, ensuring consistency and accuracy.
To add structured data to your script, follow these steps:
- Select the AI Chat Step: In the Code tab, click on the AI Chat step.
- Open the Structure Settings: Click on the "Structure" button within the AI Chat step.
- Add a New Structure: Click on the "Add" button to create a new structured data template.
- Define the Structure:
- Name: Give your structured data a descriptive name (e.g., "problems", "flashcards", "sentiment_analysis").
- Description: Briefly explain what this structure represents (e.g., "Extracts problems from text," "Generates flashcards from text," "Analyzes the sentiment of a text").
- JSON Schema: Paste the relevant JSON schema code into this field. We'll explore some examples below.
- Save the Structure: Click "Done" to save your structured data template.
Example Schemas
Let's explore some example JSON schemas:
Problems Schema
{
"type": "object",
"description": "Represents a list of multiple-choice or short-answer questions extracted from a text",
"properties": {
"problems": {
"type": "array",
"description": "An array of problems (questions and answer choices)",
"items": {
"type": "object",
"description": "A single question with its corresponding answer choices",
"properties": {
"question": {
"type": "string",
"description": "The text of the question, phrased clearly and concisely"
},
"choices": {
"type": "string",
"description": "The answer choices, formatted as lowercase letters followed by a closing parenthesis (e.g., a) choice1 b) choice2 c) choice3)"
}
},
"required": ["question", "choices"]
}
}
},
"required": ["problems"]
}
This schema instructs the AI to extract multiple-choice or short-answer questions from text and structure them in a specific way:
"type": "object": This indicates that the data will be structured as a JSON object, which is like a container for key-value pairs."properties": {}": This section defines the properties (or fields) within our object."problems": {}: This is a property called "problems," which is an array (a list) of problem objects."items": {}: This defines the structure of each item within the "problems" array. Each item represents a single question."question": {}: This is a property within each problem object, representing the question itself."type": "string": This specifies that the "question" property must contain a string (text)."description": "The text of the question, phrased clearly and concisely": This gives the AI guidance on how to format the question.
"choices": {}: This is another property within each problem object, representing the answer choices."type": "string": This specifies that the "choices" property must contain a string (text)."description": "The answer choices, formatted as lowercase letters followed by a closing parenthesis (e.g., a) choice1 b) choice2 c) choice3)": This tells the AI how to format the answer choices.
"required": ["question", "choices"]: This indicates that both "question" and "choices" are mandatory fields for each problem object."required": ["problems"]: This indicates that the "problems" property itself is mandatory within the overall object.
Real-World Use Case: Imagine you are a teacher creating a quiz from a textbook chapter. You could use this schema to quickly extract all the questions and answer choices, saving you hours of manual work!
Flashcards Schema
{
"type": "object",
"description": "Represents a set of flashcards for learning and memorization",
"properties": {
"flashcards": {
"type": "array",
"description": "An array of flashcards, each containing a prompt and its associated information",
"items": {
"type": "object",
"description": "A single flashcard with a query (prompt) and recall (answer/information)",
"properties": {
"query": {
"type": "string",
"description": "The prompt or question on the front of the flashcard (e.g., a vocabulary word, a historical event, a scientific concept)"
},
"recall": {
"type": "string",
"description": "The answer, definition, or information to be remembered, corresponding to the query on the back of the flashcard"
}
},
"required": ["recall", "query"]
}
}
},
"required": ["flashcards"]
}
This schema guides the AI to generate flashcards from text:
"type": "object": This indicates that the data will be in the form of a JSON object."properties": {}: This section contains the different properties within the object."flashcards": {}: This is a property named "flashcards," which is an array (a list) of flashcard objects."items": {}: This defines what each item within the "flashcards" array should look like. Each item represents a single flashcard."query": {}: This property represents the prompt or question on the front of the flashcard."type": "string": It must be a string (text)."description": "The prompt or question on the front of the flashcard (e.g., a vocabulary word, a historical event, a scientific concept)": This provides context to the AI about the type of content expected in the "query" field.
"recall": {}: This property represents the answer or information on the back of the flashcard."type": "string": It must also be a string (text)."description": "The answer, definition, or information to be remembered, corresponding to the query on the back of the flashcard": This explains what should go in the "recall" field.
"required": ["recall", "query"]: This means both "recall" and "query" are required fields for each flashcard object."required": ["flashcards"]: This indicates that the "flashcards" property is required within the main object.
Real-World Use Case: Imagine you're studying for a history exam. You could paste your notes into Telosnex and use this schema to automatically generate flashcards with key terms and their definitions, making studying more efficient and engaging.
Sentiment Analysis Schema
{
"type": "object",
"description": "Represents the sentiment analysis of a text, providing both the sentiment score and the reasoning behind it",
"properties": {
"objects": {
"type": "array",
"description": "An array of sentiment analysis objects, each analyzing a specific chunk of text",
"items": {
"type": "object",
"description": "Sentiment analysis for a portion of text, including the text itself, the sentiment score, and the AI's reasoning",
"properties": {
"text": {
"type": "string",
"description": "The specific portion of text being analyzed for sentiment"
},
"reasoning": {
"type": "string",
"description": "A clear and concise explanation of why the AI assigned the given sentiment score, highlighting keywords or phrases that influenced the analysis"
},
"sentiment": {
"type": "integer",
"description": "The sentiment score, ranging from 0 (very negative) to 10 (very positive), reflecting the overall emotional tone of the text"
}
},
"required": ["sentiment", "reasoning", "text"]
}
}
},
"required": ["objects"]
}
This schema instructs the AI to analyze the sentiment of a text and provide reasoning for its analysis:
"type": "object": This specifies the data structure as a JSON object."properties": {}: This section defines the properties (or fields) that make up the object."objects": {}: This property is an array (a list) that contains multiple sentiment analysis objects."items": {}: This defines the structure for each object within the "objects" array. Each object represents the sentiment analysis of a particular segment of text."text": {}: This property within each "object" holds the actual text being analyzed."type": "string": The text must be in string format."description": "The specific portion of text being analyzed for sentiment": This description tells the AI what to put in the "text" field.
"reasoning": {}: This property provides the AI's explanation or justification for its sentiment rating."type": "string": The reasoning is also provided as a string (text)."description": "A clear and concise explanation of why the AI assigned the given sentiment score, highlighting keywords or phrases that influenced the analysis": This description guides the AI to provide insightful reasoning.
"sentiment": {}: This property represents the sentiment score, often on a numerical scale."type": "integer": This indicates that the sentiment score should be a whole number (an integer)."description": "The sentiment score, ranging from 0 (very negative) to 10 (very positive), reflecting the overall emotional tone of the text": This clarifies the meaning and potential range of the sentiment score.
"required": ["sentiment", "reasoning", "text"]: This ensures that all three of these properties are present within each "object."
"required": ["objects"]: This indicates that the "objects" property is mandatory for the overall structure.
Real-World Use Case: Imagine you own a small business and want to understand customer feedback from online reviews. You could use this schema to analyze the sentiment of the reviews, quickly identifying positive and negative comments, and gain insights into what customers love and what they want you to improve.
Search Queries Schema
{
"type": "object",
"description": "Represents a set of distinct search queries related to a specific topic",
"properties": {
"search_query_0": {
"type": "string",
"description": "The first search query, focused on a specific aspect of the topic"
},
"search_query_1": {
"type": "string",
"description": "The second search query, exploring a different facet of the topic"
},
"search_query_2": {
"type": "string",
"description": "The third search query, providing an alternative perspective or angle on the topic"
}
},
"required": ["search_query_0", "search_query_1", "search_query_2"]
}
This schema instructs the AI to generate three distinct search queries related to a given topic:
"type": "object": This indicates that the data will be structured as a JSON object."properties": {}": This section defines the properties (or fields) within our object."search_query_0": {}: This property represents the first search query."type": "string": This specifies that the "search_query_0" property must contain a string (text), which will be the search query itself."description": "The first search query, focused on a specific aspect of the topic": This gives the AI guidance on how to formulate the search query, emphasizing a specific focus.
"search_query_1": {}: This property represents the second search query."type": "string": This specifies that the "search_query_1" property must contain a string (text) for the second search query."description": "The second search query, exploring a different facet of the topic": This guides the AI to create a search query that explores a different aspect of the topic compared to the first query.
"search_query_2": {}: This property represents the third search query."type": "string": This specifies that the "search_query_2" property must contain a string (text) for the third search query."description": "The third search query, providing an alternative perspective or angle on the topic": This instructs the AI to generate a search query that offers a different perspective or angle on the topic, further expanding the search scope.
"required": ["search_query_0", "search_query_1", "search_query_2"]: This indicates that all three search query properties ("search_query_0", "search_query_1", and "search_query_2") are mandatory fields within the overall object.
Real-World Use Case: Imagine you are researching a complex topic like "electric vehicles." You could use this schema to have the AI generate three distinct search queries, focusing on different aspects like "battery technology," "charging infrastructure," or "government incentives." This helps you gather a broader range of relevant information for your research.
Test Your Script
-
Open the Test Tab: Click on the "Test" tab in your script.
-
Enter a Relevant Prompt: Type or paste input that aligns with the chosen schema. Here are examples designed to mimic real-world situations:
-
Problems Schema:
The Renaissance was a period of great cultural and artistic flourishing in Europe. What were two key characteristics of Renaissance art?
a) Realism and humanism
b) Abstract expressionism and cubism
c) Surrealism and dadaism
Leonardo da Vinci, a prominent Renaissance artist, painted the Mona Lisa.
The Protestant Reformation began in the 16th century. Who initiated the Protestant Reformation?
a) Martin Luther
b) John Calvin
c) Henry VIII
The Reformation led to significant religious and political changes in Europe.
What is the capital of France?
a) Paris
b) London
c) Berlin
The Eiffel Tower is a famous landmark in Paris. -
Flashcards Schema:
Photosynthesis is the process by which green plants and some other organisms use sunlight to synthesize foods with chlorophyll as the catalyst. The process converts light energy into chemical energy that can be later released to fuel the organisms' activities (energy transformation). This process takes place in chloroplasts, organelles found in plant cells.
Cellular respiration is the process by which organisms combine oxygen with foodstuff molecules, diverting the chemical energy in these substances into life-sustaining activities and discarding, as waste products, carbon dioxide and water. -
Sentiment Analysis Schema:
Comment 1: "I love this product! It's exactly what I was looking for, and it works perfectly. Highly recommended!"
Comment 2: "This is the worst purchase I've ever made. The product arrived damaged, and the customer service was terrible."
Comment 3: "It's okay, I guess. Not as good as I hoped, but it's not the worst thing ever."
-
-
Run the Test: Press "Test" and observe how the AI handles these more complex and realistic inputs. The AI should still accurately extract the structured data you need, demonstrating its ability to work with diverse, real-world information.
Recap
Congratulations! You've learned how to work with structured data in Telosnex!
Key Takeaways
- Structured Data: Information organized in a clear, consistent format, enabling efficient analysis and utilization.
- JSON: A widely used, human-readable format for representing structured data.
- JSON Schema: A blueprint defining the structure and rules of your JSON data, ensuring accuracy and consistency in AI output.
By harnessing structured data, you can:
- Extract Precise Information: Pinpoint the exact data you need from text, eliminating manual sifting and sorting.
- Automate Workflows: Create dynamic, time-saving processes by connecting different AI actions within your scripts.
- Build Powerful Applications: Develop interactive applications that leverage structured data to deliver more dynamic and powerful user experiences.