ai-suggestions

name: ai-suggestions description: Guide for Genkit AI integration, smart destination suggestions, and AI-powered features in TrainTrack

This skill provides guidance for working with Genkit AI, implementing smart destination suggestions, and managing AI-powered features in TrainTrack.

Genkit AI Setup

Configuration: src/ai/genkit.ts

• Uses Google AI plugin
• Model: googleai/gemini-2.0-flash
• Exports ai instance for flows

Environment Variable Required:

GEMINI_API_KEY=<your_gemini_api_key>

AI Flows

Smart Destination Suggestion Flow

File: src/ai/flows/smart-destination-suggestion.ts

Purpose: Suggests potential destinations and routes based on past booking data and popular travel trends.

Input Schema:

{
  pastBookingData: string,      // JSON string with past bookings
  popularTravelTrends: string    // JSON string with trends
}

Output Schema:

[
  {
    destination: string,  // Suggested destination
    route: string,       // Suggested route
    reason: string       // Reason for suggestion
  }
]

Flow Definition:

• Uses Zod schemas for type safety
• Defines prompt template with ai.definePrompt
• Implements flow with ai.defineFlow
• Returns structured JSON output

UI Integration

Component: src/components/SmartSuggestionTool.tsx

Features:

• Auto-fills past booking data from Firestore
• Editable popular travel trends
• AI-powered suggestion generation
• Display of suggested destinations with reasons

Current Status: AI suggestions temporarily disabled for static export deployment. The component shows an error message instead of calling the AI flow.

Using Genkit Flows

Importing and Calling Flows

import { suggestDestinations, type SuggestDestinationsInput } from '@/ai/flows/smart-destination-suggestion';

const input: SuggestDestinationsInput = {
  pastBookingData: JSON.stringify(bookings),
  popularTravelTrends: JSON.stringify(trends)
};

const suggestions = await suggestDestinations(input);

Creating New Flows

Pattern:

1. Define input schema with Zod
2. Define output schema with Zod
3. Create prompt template
4. Define flow with input/output schemas
5. Implement flow logic

Example Structure:

import { ai } from '@/ai/genkit';
import { z } from 'genkit';

const InputSchema = z.object({
  // Input fields
});

const OutputSchema = z.object({
  // Output fields
});

const prompt = ai.definePrompt({
  name: 'myPrompt',
  input: { schema: InputSchema },
  output: { schema: OutputSchema },
  prompt: `Your prompt template here: {{{inputField}}}`,
});

const myFlow = ai.defineFlow(
  {
    name: 'myFlow',
    inputSchema: InputSchema,
    outputSchema: OutputSchema,
  },
  async input => {
    const { output } = await prompt(input);
    return output!;
  }
);

Genkit Development Server

Start Dev Server:

npm run genkit:dev

Start with Auto-Reload:

npm run genkit:watch

Dev Server Entry: src/ai/dev.ts

Access: Open Genkit Dev UI at http://localhost:4000

Features:

• Test flows interactively with sample inputs
• View flow outputs
• Debug AI responses
• Monitor performance

Data Preparation

Booking Data Format

[
  {
    "id": "booking-id",
    "source": "Station A",
    "destination": "Station B",
    "journeyDate": "2024-01-15T00:00:00.000Z",
    "passengers": [
      { "name": "John Doe", "age": 30, "gender": "male" }
    ],
    "status": "completed"
  }
]

Travel Trends Format

[
  {
    "trend": "Weekend getaways to nearby cities",
    "popularity": "High"
  },
  {
    "trend": "Coastal destinations for summer",
    "popularity": "Medium"
  }
]

Static Export Considerations

Current Limitation: AI features are temporarily disabled in static export deployment because:

• Server-side AI calls cannot be made from static builds
• API key exposure concerns
• Client-side Genkit integration complexity

Workaround: The SmartSuggestionTool component shows a placeholder message instead of calling the AI flow.

Future Implementation Options:

1. Deploy as a serverless function (Firebase Functions)
2. Use a separate API endpoint for AI requests
3. Implement client-side Genkit with proper API key management

Best Practices

Prompt Engineering

Clear Instructions: Be explicit about what the AI should do

prompt: `You are a travel expert. Based on the past booking data and popular travel trends,
you will suggest potential destinations and routes to the user.

Past Booking Data: {{{pastBookingData}}}
Popular Travel Trends: {{{popularTravelTrends}}}

Suggest destinations and routes in JSON format:`,

Structured Output: Use Zod schemas for type-safe responses

const OutputSchema = z.array(
  z.object({
    destination: z.string(),
    route: z.string(),
    reason: z.string()
  })
);

Error Handling

Try-Catch Pattern:

try {
  const result = await suggestDestinations(input);
  setSuggestions(result);
} catch (err) {
  console.error(err);
  setError(err instanceof Error ? err.message : 'An error occurred');
}

Loading States: Show loading indicators during AI calls

const [isLoading, setIsLoading] = useState(false);

const handleSubmit = async () => {
  setIsLoading(true);
  try {
    const result = await suggestDestinations(input);
    setSuggestions(result);
  } finally {
    setIsLoading(false);
  }
};

Data Validation

Validate JSON Inputs:

try {
  JSON.parse(pastBookingData);
} catch (err) {
  setError('Invalid JSON format for past booking data');
  return;
}

Sanitize AI Output:

• Validate AI responses against Zod schema
• Handle missing or malformed data
• Provide fallback suggestions if AI fails

Testing AI Flows

Using Genkit Dev UI

1. Start dev server: npm run genkit:dev
2. Open http://localhost:4000
3. Select the flow to test
4. Enter sample input data
5. Run and examine output

Sample Test Input

{
  "pastBookingData": "[{\"source\":\"Mumbai\",\"destination\":\"Delhi\",\"journeyDate\":\"2024-01-15T00:00:00.000Z\",\"status\":\"completed\"}]",
  "popularTravelTrends": "[{\"trend\":\"Weekend getaways\",\"popularity\":\"High\"}]"
}

Expected Output Format

[
  {
    "destination": "Jaipur",
    "route": "Mumbai → Delhi → Jaipur",
    "reason": "Based on your Mumbai-Delhi travel history, Jaipur offers cultural attractions and is a popular weekend destination."
  }
]

Troubleshooting

API Key Errors:

• Verify GEMINI_API_KEY in environment variables
• Check API key is valid and has proper permissions
• Ensure key is not exposed in client code

Flow Not Found:

• Verify flow is properly defined in src/ai/flows/
• Check Genkit dev server is running
• Ensure flow name matches in import

Type Errors:

• Verify Zod schemas match expected data
• Check TypeScript types are correctly inferred
• Use z.infer<> for type extraction

Slow Response Times:

• Consider caching AI responses
• Implement debouncing for user inputs
• Use loading indicators for better UX

Static Export Issues:

• AI features currently disabled in static build
• Consider deploying AI endpoints separately
• Use serverless functions for AI calls

Key Files Reference

• src/ai/genkit.ts - Genkit configuration
• src/ai/flows/smart-destination-suggestion.ts - Main AI flow
• src/ai/dev.ts - Dev server entry
• src/components/SmartSuggestionTool.tsx - UI component
• src/lib/firestoreClient.ts - Data fetching for AI

Future Enhancements

Additional AI Flows:

• Route optimization based on historical data
• Price prediction for train bookings
• Personalized travel recommendations
• Crowd density predictions

Integration Improvements:

• Server-side Genkit deployment
• Real-time AI suggestions
• Multi-language support
• Voice input for travel queries