structured output & rag

11 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

generateQuery Server Action signature and implementation

The generateQuery Server Action is asynchronous and takes one parameter: input (string). It uses the generateText function with Output.object to constrain the model's output to a pre-defined schema. The function returns a single string field called 'query' using Zod schema validation. The Server Action is marked with 'use server' directive and calls the model with system prompt and user input, returning result.output.query.

generateText function with structured output for SQL generation

The generateText function is called with: model: 'openai/gpt-4o', system: system prompt string, prompt: formatted user query string, and output: Output.object({ schema: z.object({ query: z.string() }) }). This constrains the model to return only the SQL query without additional prefixes or explanations.

explainQuery Server Action signature and implementation

The explainQuery Server Action is asynchronous and takes two parameters: input (string, the original natural language query) and sqlQuery (string, the generated SQL query). It uses generateText function with Output.array to return an array of explanations. The function includes both the user query and generated SQL query in the prompt to provide context for explanations.

QueryExplanation schema definition

The explanationSchema in lib/types.ts is defined as: z.object({ section: z.string(), explanation: z.string() }). Each explanation has a 'section' field (the part of the query being explained) and an 'explanation' field (the plain English explanation of that section). This schema is used with Output.array to generate an array of explanation objects.

Output.array for multiple structured objects

The Output.array() function can be used to indicate to the model that an array of objects matching a schema should be returned. Usage: output: Output.array({ element: explanationSchema }) where explanationSchema is a Zod schema.

Chart configuration schema with visual and data mapping

The configSchema in lib/types.ts includes the following fields: description (string describing the chart), takeaway (string with main takeaway), type (enum of 'bar', 'line', 'area', 'pie'), title (string), xKey (string for x-axis or category), yKeys (array of strings for y-axis values), multipleLines (optional boolean for line charts), measurementColumn (optional string for line chart quantitative column), lineCategories (optional array of strings for comparing different lines), colors (optional record mapping yKeys to CSS color values), and legend (boolean). Each field has .describe() annotations to give the model context.

generateChartConfig Server Action implementation

The generateChartConfig Server Action is asynchronous and takes two parameters: results (Result[] array of query results) and userQuery (string of user's natural language query). It calls generateText with model 'openai/gpt-4o', system prompt 'You are a data visualization expert.', a prompt that includes the user query and JSON-stringified results, and output: Output.object({ schema: configSchema }). The function then overrides colors with shadcn theme colors (hsl(var(--chart-N)) format) and returns the updated config.

Chart visualization with Zod describe annotations

The configSchema makes extensive use of Zod's .describe() function to give the model context about each field's purpose. This helps the model understand what each key should contain and generate more accurate results. The schema includes description and takeaway fields to force the model to conceptually understand the data before generating technical configuration attributes.

Chart configuration override with theme colors

After the model generates chart configuration with custom colors, the implementation overrides the colors object to use shadcn theme colors. The pattern is: config.yKeys.forEach((key, index) => { colors[key] = `hsl(var(--chart-${index + 1}))`; }). This replaces generated colors with theme-consistent CSS variables like hsl(var(--chart-1)), hsl(var(--chart-2)), etc.

SQL query generation with Output.object structured output

When using Output.object with generateText, the result is accessed via result.output which contains the parsed schema. For SQL generation, the structure is: const result = await generateText({ output: Output.object({ schema: z.object({ query: z.string() }) }) }); return result.output.query;

Limiting model output tokens in chart generation

The guide demonstrates that asking the model to generate only chart configuration (fixed-size, not many tokens) rather than asking it to return the full dataset is more efficient. This approach reduces latency and costs while still enabling dynamic visualization based on query results. The model generates structural metadata (chart type, axis mappings, colors) rather than data itself.

Give your agent this brain