Overview
Tuturuuu leverages the Vercel AI SDK to generate structured data from large language models (LLMs). This approach enables type-safe AI responses, improved reliability, and consistent data structures for features like flashcards, quizzes, and learning plans.
This guide covers how to use AI structured data generation in the Tuturuuu development workflow.
Key Concepts
What is Structured Data Generation?
While text generation can be useful, many applications require generating structured data. For example, you might want to:
- Extract specific information from text
- Generate quizzes or flashcards from learning material
- Create complex objects like learning plans or task lists
- Ensure AI responses follow a consistent format
The AI SDK standardizes structured object generation across model providers with the generateObject
and streamObject
functions. You can use Zod schemas to specify the shape of the data that you want, and the AI model will generate data that conforms to that structure.
Architecture in Tuturuuu
Tuturuuu’s AI features follow this high-level architecture:
- Frontend UI - React components that display and interact with AI-generated content
- API Routes - Next.js routes that handle AI requests and responses
- AI SDK - Vercel AI SDK that manages model providers and generates structured data
- Supabase - Backend database for authentication, authorization, and storing AI-generated content
Schema Definitions
Schemas define the structure of the data that will be generated by the AI models. In Tuturuuu, these are defined in packages/ai/src/object/types.ts
using Zod.
Here are some examples of schemas used in Tuturuuu:
Flashcard Schema
export const flashcardSchema = z.object({
flashcards: z.array(
z.object({
front: z.string().describe('Question. Do not use emojis or links.'),
back: z.string().describe('Answer. Do not use emojis or links.'),
})
),
});
Quiz Schema
export const quizSchema = z.object({
quizzes: z.array(
z.object({
question: z.string().describe('Question. Do not use emojis or links.'),
quiz_options: z.array(
z.object({
value: z.string().describe('Option. Do not use emojis or links.'),
explanation: z
.string()
.describe(
'Explain why this option is correct or incorrect, if it is incorrect, explain possible misconceptions and what made the option wrong with respect to the question, if it is correct, explain why it is correct. Be as detailed as possible.'
),
is_correct: z.boolean().describe('This option is a correct answer.'),
})
),
})
),
});
Year Plan Schema
export const yearPlanSchema = z.object({
yearPlan: z.object({
overview: z
.string()
.describe(
'A high-level overview of the year plan and how the goals will be achieved'
),
quarters: z
.array(quarterSchema)
.describe('List of quarters in the year plan'),
recommendations: z
.array(z.string())
.describe('Additional recommendations, tips, or considerations'),
start_date: z
.string()
.describe('Start date of the year plan (ISO date string)'),
end_date: z
.string()
.describe('End date of the year plan (ISO date string)'),
}),
});
Creating an API Endpoint
To create an API endpoint that generates structured data, follow these steps:
1. Create a new route file
Create a new route file in the appropriate Next.js app, for example:
// app/api/ai/flashcards/route.ts
import { google } from '@ai-sdk/google';
import { flashcardSchema } from '@tuturuuu/ai/object/types';
import {
createAdminClient,
createClient,
} from '@tuturuuu/supabase/next/server';
import { streamObject } from 'ai';
export const runtime = 'edge';
export const maxDuration = 60;
export async function POST(req: Request) {
// Implementation...
}
2. Implement authentication and validation
Use Supabase to authenticate the user and validate their permissions:
const sbAdmin = await createAdminClient();
const { wsId, context } = await req.json();
// Validate input
if (!wsId) return new Response('Missing workspace ID', { status: 400 });
if (!context) return new Response('Missing context', { status: 400 });
// Authenticate user
const supabase = await createClient();
const { data: { user } } = await supabase.auth.getUser();
if (!user) return new Response('Unauthorized', { status: 401 });
// Check feature flag
const { count, error } = await sbAdmin
.from('workspace_secrets')
.select('*', { count: 'exact', head: true })
.eq('ws_id', wsId)
.eq('name', 'ENABLE_CHAT')
.eq('value', 'true');
if (error) return new Response(error.message, { status: 500 });
if (count === 0)
return new Response('You are not allowed to use this feature.', { status: 401 });
3. Generate structured data
Use the AI SDK to generate structured data based on the schema:
const result = streamObject({
model: google('gemini-2.0-flash-001', {
safetySettings: [
{
category: 'HARM_CATEGORY_DANGEROUS_CONTENT',
threshold: 'BLOCK_NONE',
},
// Other safety settings...
],
}),
prompt: `Generate 10 flashcards with the following context: ${context}`,
schema: flashcardSchema,
});
// Stream the response to the client
return result.toTextStreamResponse();
Supported Models
Tuturuuu supports multiple AI models through the Vercel AI SDK. The available models are defined in packages/ai/src/models.ts
:
export const models = [
{
value: 'gemini-2.0-flash-001',
label: 'gemini-2.0-flash',
provider: 'Google',
description: 'Gemini 2.0 Flash delivers next-gen features...',
context: 1000000,
},
{
value: 'gemini-2.0-pro-exp-02-05',
label: 'gemini-2.0-pro-exp-02-05',
provider: 'Google',
description: 'Gemini 2.0 Pro supports up to 1 million tokens...',
context: 2000000,
},
// Other models...
];
To use a different model in your endpoint, simply change the model reference:
const result = streamObject({
model: google('gemini-2.0-pro-exp-02-05', {
// Configuration...
}),
// Other parameters...
});
Calling from the Frontend
To call your AI endpoint from the frontend, you can use the appropriate hooks or fetch API:
// Example using fetch
async function generateFlashcards(workspaceId: string, context: string) {
const response = await fetch('/api/ai/flashcards', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
wsId: workspaceId,
context,
}),
});
if (!response.ok) {
const error = await response.text();
throw new Error(error);
}
// For streaming responses
const reader = response.body?.getReader();
const decoder = new TextDecoder();
while (reader) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value);
// Process the chunk (partial object)
console.log(JSON.parse(chunk));
}
}
Integration with Supabase
Tuturuuu’s AI features are tightly integrated with Supabase for several purposes:
TypeScript Types
Supabase-generated TypeScript types are available at packages/types/src/supabase.ts
. These types are automatically generated when you run pnpm sb:typegen
or pnpm sb:reset
and are accessible to all apps that have the @tuturuuu/types
package installed.
You can use these types to ensure type safety when working with Supabase data in your AI features:
import type { Database } from '@tuturuuu/types/supabase';
// Type-safe access to workspace_secrets table
const { data, error } = await supabase
.from<
Database['public']['Tables']['workspace_secrets']['Row']
>('workspace_secrets')
.select('*')
.eq('ws_id', wsId)
.eq('name', 'ENABLE_AI');
// Type-safe access to specific columns
const { data: workspace } = await supabase
.from('workspaces')
.select('id, name, handle')
.eq('id', wsId)
.single();
// TypeScript knows the structure of 'workspace' with proper types
const workspaceName: string = workspace?.name;
Short-hand Type Access
For more convenient access to common table types in your AI features, Tuturuuu also provides short-hand type definitions in packages/types/src/db.ts
. These are easier to use and remember than the full database type paths:
import type { AIChat, AIPrompt, WorkspaceDocument } from '@tuturuuu/types/db';
// Use short-hand types directly for AI-related tables
const { data: chats } = await supabase
.from('ai_chats')
.select('*')
.eq('creator_id', user.id);
// Types are properly inferred
chats?.forEach((chat: AIChat) => {
console.log(chat.id, chat.title);
});
// Store AI-generated content with proper types
const document: WorkspaceDocument = {
id: uuidv4(),
ws_id: wsId,
name: 'AI Generated Document',
content: generatedContent,
created_at: new Date().toISOString(),
creator_id: user.id,
};
await supabase.from('workspace_documents').insert(document);
The short-hand types can also include extended client-side properties that aren’t in the database schema, making them perfect for your AI feature implementations.
This ensures that your AI features correctly interact with the database schema, reducing runtime errors and improving development experience.
Authentication and Authorization
Before making AI requests, ensure the user is authenticated and authorized to use the feature:
// Get the current user
const { data: { user } } = await supabase.auth.getUser();
if (!user) return new Response('Unauthorized', { status: 401 });
// Check workspace membership
const { data: member, error: memberError } = await sbAdmin
.from('workspace_members')
.select('*')
.eq('ws_id', wsId)
.eq('user_id', user.id)
.single();
if (memberError || !member)
return new Response('You are not a member of this workspace', { status: 403 });
Feature Flags
Use the workspace_secrets
table to enable or disable AI features for specific workspaces:
// Check if the AI feature is enabled for this workspace
const { count, error } = await sbAdmin
.from('workspace_secrets')
.select('*', { count: 'exact', head: true })
.eq('ws_id', wsId)
.eq('name', 'ENABLE_AI')
.eq('value', 'true');
if (error) return new Response(error.message, { status: 500 });
if (count === 0)
return new Response('AI features are not enabled for this workspace', { status: 403 });
Storing Results
You can store AI-generated content in Supabase for future use:
// Store the generated flashcards
const { error } = await sbAdmin
.from('flashcard_sets')
.insert({
ws_id: wsId,
creator_id: user.id,
name: 'Generated Flashcards',
description: context.substring(0, 100) + '...',
cards: result.object.flashcards,
});
if (error) return new Response(error.message, { status: 500 });
Best Practices
Schema Design
When designing schemas for AI-generated content:
- Be specific - Use the
.describe()
method to provide clear instructions to the AI model
- Keep it simple - Break complex schemas into smaller, nested objects
- Add validations - Use Zod’s validation methods (
.min()
, .max()
, .regex()
, etc.)
- Use enums - For fields with a fixed set of values, use
.enum()
Example of a well-designed schema:
const taskSchema = z.object({
title: z.string().min(3).max(100).describe('A concise title for the task'),
description: z
.string()
.min(10)
.describe('Detailed description of what needs to be done'),
priority: z
.enum(['high', 'medium', 'low'])
.describe('Priority level of the task'),
due_date: z.string().describe('Due date in ISO format (YYYY-MM-DD)'),
estimated_hours: z
.number()
.min(0)
.max(100)
.describe('Estimated hours to complete'),
});
Error Handling
Implement robust error handling for AI-generated content:
try {
const result = streamObject({
// Configuration...
});
return result.toTextStreamResponse();
} catch (error: any) {
console.error('AI generation error:', error);
// Return a friendly error message
return NextResponse.json(
{
message: 'Failed to generate content. Please try again later.',
error: error.message,
},
{ status: 500 }
);
}
Response Processing
For complex AI-generated content, you may need to post-process the response:
// Example: Filtering out inappropriate content
const filteredFlashcards = result.object.flashcards.filter((card) => {
// Remove cards containing inappropriate words
const inappropriateWords = ['inappropriate1', 'inappropriate2'];
return !inappropriateWords.some(
(word) => card.front.includes(word) || card.back.includes(word)
);
});
Local Development and Testing
Setting Up API Keys
To test AI features locally, you need to set up the appropriate API keys in your environment:
- Create a
.env.local
file in the root of your Next.js app
- Add the necessary API keys:
GOOGLE_GENERATIVE_AI_API_KEY=your-google-ai-key
OPENAI_API_KEY=your-openai-key
- Restart your development server
Testing AI Endpoints
You can test your AI endpoints using tools like Postman or simple cURL commands:
curl -X POST http://localhost:3000/api/ai/flashcards \
-H "Content-Type: application/json" \
-d '{"wsId":"00000000-0000-0000-0000-000000000000","context":"The process of photosynthesis converts light energy into chemical energy that can be used by plants and other organisms."}'
Troubleshooting
Common Issues
- API Key Issues: Ensure your API keys are correctly set in your environment
- Model Unavailability: Some models may be unavailable in certain regions
- Token Limits: Large prompts may exceed token limits
- Schema Validation Errors: The AI might generate content that doesn’t match your schema
Debugging Tips
- Log the prompt: Print the full prompt being sent to the AI model
- Start with simple schemas: Begin with simple schemas and gradually increase complexity
- Check response format: Verify the raw response from the AI model before schema validation
Further Resources