Feature: AI-Powered Insights
Relevant source files
The following files were used as context for generating this wiki page:
The AI-Powered Insights feature is a core component of VineSight's Phase 3 "Advanced AI Intelligence" initiative. Its primary purpose is to transform the application from a reactive tool into a proactive AI advisor. It aggregates, prioritizes, and presents actionable insights from various specialized AI subsystems, such as pest prediction, smart task generation, and financial analysis. This centralized system aims to reduce farmer decision fatigue by providing a sorted list of the most critical and relevant actions and observations for their farm at any given time.
The feature is designed to be context-aware, learning from farmer decisions and outcomes to deliver increasingly personalized recommendations. It serves as the main interface for the AI Agronomist, Smart Task Generator, and other advanced AI capabilities.
Sources: context/PRD.md:126-140, 163-170, CLAUDE.md:20-25, src/lib/ai-insights-service.ts
Architecture and Data Flow
The AI Insights system is orchestrated by the AIInsightsService, which acts as a central hub. It gathers data from multiple sources, processes it, and formats it into a unified AIInsight data structure for consumption by the frontend.
Sources: src/lib/ai-insights-service.ts:7-12
High-Level Architecture
The following diagram illustrates the major components and their interactions in generating AI insights.
Insight Generation Sequence
The sequence diagram below details the step-by-step process when a user requests AI insights for their farm.
Core Service: AIInsightsService
This service is the brain of the feature, responsible for orchestrating the collection, processing, and delivery of AI insights.
Sources: src/lib/ai-insights-service.ts
Key Responsibilities
- Aggregation: Gathers data from various sources including other services (
PestPredictionService,SmartTaskGenerator), direct database queries, and dedicated AI analysis API endpoints. - Formatting: Standardizes all incoming data into a unified
AIInsightobject structure. - Prioritization: Sorts the collected insights based on a defined order:
priority(critical > high > medium > low), thentimeRelevant, and finallyconfidence. - Caching: Implements a simple in-memory cache with a 5-minute Time-to-Live (TTL) to reduce redundant computations and database load for frequent requests.
- Categorization: Provides a method (
getInsightsByCategory) to group insights for detailed view pages.
Sources: src/lib/ai-insights-service.ts:13-33, 186-202, 492-516
Insight Categories
The service generates several types of insights, each corresponding to a different area of farm management.
| Insight Type | Source | Description |
|---|---|---|
pest_prediction | PestPredictionService | High or critical risk alerts for pests and diseases, with a prevention window. |
task_recommendation | SmartTaskGenerator | High-priority tasks generated by the AI, such as irrigation or spraying. |
weather_alert | /api/ai/weather-insights | Advisory based on current and forecasted weather conditions. |
profitability_insight | /api/ai/financial-analysis | Analysis of recent spending patterns, identifying trends and risks. |
general_advice | /api/ai/growth-analysis | Recommendations related to the current growth stage of the crop. |
Sources: src/lib/ai-insights-service.ts:70-183, src/app/help/page.tsx:110-115
Data Models
The AI Insights feature relies on a set of new database tables introduced in Phase 3 and a corresponding set of TypeScript interfaces.
Sources: supabase/migrations/20250903_phase3_ai_schema.sql, context/TYPES_AND_INTERFACES.md
Database Schema (ER Diagram)
The following diagram shows the key tables in the Supabase database that store the data used to generate AI insights.
AIInsight Interface
All generated insights are normalized into the AIInsight object structure before being sent to the frontend.
| Property | Type | Description |
|---|---|---|
id | string | A unique identifier for the insight. |
type | string | The category of the insight (e.g., pest_prediction, task_recommendation). |
priority | 'critical' | 'high' | 'medium' | 'low' | The urgency level of the insight. |
title | string | The main headline for the insight. |
subtitle | string | A short description or summary. |
icon | string | The name of the Lucide icon to display. |
actionLabel | string | The text for the primary action button. |
actionType | 'navigate' | 'execute' | The type of action to perform. |
actionData | object | Data required for the action (e.g., a route or task ID). |
confidence | number | The AI's confidence score (0-1) for the insight. |
timeRelevant | boolean | Indicates if the insight is time-sensitive. |
tags | string[] | A list of tags for filtering and categorization. |
Sources: src/lib/ai-insights-service.ts:8-9, context/TYPES_AND_INTERFACES.md:299-322 (Implicitly defined in ai-insights-service.ts and aligns with AITaskRecommendation and other types)
Example AIInsight Object
{
"id": "pest_123",
"type": "pest_prediction",
"priority": "critical",
"title": "Downy Mildew Risk",
"subtitle": "Prevention window: 2 days",
"icon": "AlertTriangle",
"actionLabel": "Apply Treatment",
"actionType": "navigate",
"actionData": {
"route": "/farms/1/pest-alerts",
"pestId": 123,
"expiresAt": "2025-09-05T00:00:00.000Z"
},
"confidence": 0.92,
"timeRelevant": true,
"tags": ["pest", "disease", "prevention"]
}
Sources: src/lib/ai-insights-service.ts:70-89
Fallback Mechanisms
The AIInsightsService includes fallback logic for insights that depend on external API calls (weather-insights, financial-analysis, growth-analysis). If an API call fails, the service attempts to generate a more basic, rule-based insight using available data. This ensures that the user still receives some level of guidance even if advanced AI processing is temporarily unavailable.
- Weather Insights Fallback: If the
/api/ai/weather-insightscall fails,generateWeatherInsightsis called to produce basic alerts, such as a fungal risk warning based on high humidity and temperature. - Financial Insights Fallback: If the
/api/ai/financial-analysiscall fails, a basic analysis compares the last 30 days of spending against a static average to detect overspending.