AI Structured Data

Prerequisite: You should have followed the Development and Local Supabase Development setup guides.

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

Mira Chat Attachments

Dashboard chat attachments are uploaded to Supabase Storage before the user message is sent. New chats may first place files under {wsId}/chats/ai/resources/temp/{userId} and then move them into {wsId}/chats/ai/resources/{chatId} once the chat exists. Tools that read those attachments, such as convert_file_to_markdown, should resolve bare filenames and stale same-workspace attachment paths against the current chat folder. They must still reject full paths from another workspace.

Mira Dashboard Chat Agent Loop

The dashboard Mira chat keeps the main assistant in fast mode by default. New sessions should ignore stale stored thinking preferences unless the user manually opts into the toolbar’s deep-check mode for that active session. Assistant text should stream as soon as it is useful, then tool calls may run inline, followed by more assistant text in the same response. Keep every assistant text surface on the shared Streamdown wrapper, including text rendered inside compact tool UIs, so code blocks, tables, Mermaid, math, and CJK spacing stay consistent. Mira enables Streamdown math with singleDollarTextMath because model output commonly uses $...$ inline LaTeX. Keep @streamdown/math in the Tailwind source scan alongside the base Streamdown dist files, and keep katex/dist/katex.min.css imported from the chat renderer path. While the request is submitted but no assistant text has arrived yet, the chat should render a lightweight assistant activity bubble with rotating status copy. Hide that placeholder as soon as real assistant text streams, and keep it separate from markdown/tool rendering so status cycling does not re-render heavy message content. Keep the first optional-tool model step lean. Unless a workflow must force a specific tool before answering, expose only select_tools and no_action_needed on the first step so the model can stream direct answers without carrying every tool schema. Stream smoothing should not add artificial per-chunk delay on the dashboard chat path; perceived smoothness belongs in the client activity state, not in delayed server chunks. Do not force select_tools as the universal first step. Force tool selection only when the workflow cannot answer safely before a tool runs, such as current web lookups, workspace context switching, workspace member lookups, file conversion, or writes. Complex verification, risk review, planning checks, or conflicting evidence should use run_parallel_checks, which delegates to bounded ToolLoopAgent subagents in parallel and returns a compact summary to the main assistant. Any Mira tool that spawns additional model calls must use MiraToolContext.creditWsId ?? wsId, resolve the plan model for that billed workspace, preflight AI credits, apply the workspace output-token cap, and deduct the subcall usage before exposing the generated result.

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 async function POST(req: Request) {
  // Implementation...
}

2. Implement authentication and validation

Use Supabase to authenticate the user and validate their permissions:

// createAdminClient() is synchronous; do not await it.
const sbAdmin = 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 });

Fast session auth for Mira and assistant routes

Session-authenticated AI routes may accept the x-tuturuuu-ai-temp-auth header as an optimization before falling back to Supabase getUser(). The browser mints this token through POST /api/ai/temp-auth/token after the normal session, workspace normalization, membership, and selected billing workspace checks succeed. Tokens live only in memory on the client, expire after 60 seconds, and are stored in Redis only as SHA-256 digests. Revocation is version-based: ai:temp-auth:user-version:{userId} is bumped before logout or account removal, so any token minted under the old version is rejected. Redis is not authoritative for security; when Redis is unavailable or a token is missing/invalid, routes fall back to the existing Supabase session path. A revoked token returns 401 and does not fall back. Credit availability snapshots are also Redis-backed under ai:credits:snapshot:{billingWsId}:{userId}. They are UI/status hints only and must not authorize model execution. AI preflight must call the authoritative Postgres allowance RPC so daily credit limits, daily request limits, and feature-specific request limits are enforced before every model run. Actual reservations, deductions, and ledger writes remain in Postgres, and successful commits invalidate the snapshot.

3. Generate structured data

Use the AI SDK to generate structured data based on the schema:

const result = streamObject({
  // Use a current default model ID. Active callers in `packages/ai/src`
  // (calendar, chat title generation, search wrapper) use
  // `gemini-3.1-flash-lite`. See "Supported Models" below for how the
  // catalog is resolved dynamically at runtime.
  model: google('gemini-3.1-flash-lite', {
    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. There is no static model array anymore — the catalog is sourced dynamically from the AI gateway and stored in the ai_gateway_models table (synced by packages/ai/src/credits/sync-gateway-models.ts). The browsable catalog is served from apps/infrastructure:

API: GET /api/v1/infrastructure/ai/models (apps/infrastructure/src/app/api/v1/infrastructure/ai/models/route.ts)
Docs: see Model Catalog for how metadata is published, browsed, and synced.

The set of provider integrations the SDK can wire up lives in packages/ai/src/supported-providers.ts:

export const supportedProviders = [
  'google',
  'google-vertex',
  'openai',
  'anthropic',
] as const;

For per-workspace plan resolution (which model a billed workspace is allowed to run), use the helpers under packages/ai/src/credits/ such as resolve-plan-model.ts and cap-output-tokens.ts, rather than hard-coding a model ID. To use a different model in your endpoint, change the model reference. Active callers default to gemini-3.1-flash-lite:

const result = streamObject({
  model: google('gemini-3.1-flash-lite', {
    // 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 bun sb:typegen or bun 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';

// 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';

// 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) {
  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

Overview

Platform

Build

Learn

Reference

Overview

Key Concepts

What is Structured Data Generation?

Architecture in Tuturuuu

Mira Chat Attachments

Mira Dashboard Chat Agent Loop

Schema Definitions

Flashcard Schema

Quiz Schema

Year Plan Schema

Creating an API Endpoint

1. Create a new route file

2. Implement authentication and validation

Fast session auth for Mira and assistant routes

3. Generate structured data

Supported Models

Calling from the Frontend

Integration with Supabase

TypeScript Types

Short-hand Type Access

Authentication and Authorization

Feature Flags

Storing Results

Best Practices

Schema Design

Error Handling

Response Processing

Local Development and Testing

Setting Up API Keys

Testing AI Endpoints

Troubleshooting

Common Issues

Debugging Tips

Further Resources

​Overview

​Key Concepts

​What is Structured Data Generation?

​Architecture in Tuturuuu

​Mira Chat Attachments

​Mira Dashboard Chat Agent Loop

​Schema Definitions

​Flashcard Schema

​Quiz Schema

​Year Plan Schema

​Creating an API Endpoint

​1. Create a new route file

​2. Implement authentication and validation

​Fast session auth for Mira and assistant routes

​3. Generate structured data

​Supported Models

​Calling from the Frontend

​Integration with Supabase

​TypeScript Types

​Short-hand Type Access

​Authentication and Authorization

​Feature Flags

​Storing Results

​Best Practices

​Schema Design

​Error Handling

​Response Processing

​Local Development and Testing

​Setting Up API Keys

​Testing AI Endpoints

​Troubleshooting

​Common Issues

​Debugging Tips

​Further Resources

Overview

Key Concepts

What is Structured Data Generation?

Architecture in Tuturuuu

Mira Chat Attachments

Mira Dashboard Chat Agent Loop

Schema Definitions

Flashcard Schema

Quiz Schema

Year Plan Schema

Creating an API Endpoint

1. Create a new route file

2. Implement authentication and validation

Fast session auth for Mira and assistant routes

3. Generate structured data

Supported Models

Calling from the Frontend

Integration with Supabase

TypeScript Types

Short-hand Type Access

Authentication and Authorization

Feature Flags

Storing Results

Best Practices

Schema Design

Error Handling

Response Processing

Local Development and Testing

Setting Up API Keys

Testing AI Endpoints

Troubleshooting

Common Issues

Debugging Tips

Further Resources