Feature: AI Assistant
Relevant source files
The following files were used as context for generating this wiki page:
The AI Assistant is a core feature of the VineSight platform, designed to provide grape farmers with instant, conversational guidance on a wide range of agricultural topics. It functions as an AI-powered farming companion, capable of understanding and responding to queries in multiple languages (English, Hindi, and Marathi). The assistant leverages context from the user's farm data, recent image analyses, and conversation history to provide personalized and relevant recommendations.
This feature is a key part of the "Phase 2: AI Integration & Smart Farming" initiative. It supports text input, image attachments, and voice commands, making it an accessible tool for farmers in various scenarios. Conversation history is persisted using Supabase, allowing for long-term contextual memory and a continuous user experience.
Sources: context/PRD.md, src/components/ai/AIAssistant.tsx:41-52
Architecture Overview
The AI Assistant's architecture is a client-server model that integrates a Next.js frontend component with a backend API route, a database for persistence, and external AI services.
The diagram below illustrates the high-level architecture of the AI Assistant feature.
This diagram shows the flow of a user message from the frontend component to the backend API, which then communicates with an AI provider and streams the response back. The frontend component also interacts directly with Supabase for managing conversation history.
Sources: src/components/ai/AIAssistant.tsx:351-361, AGENTS.md, CLAUDE.md
Frontend Component: AIAssistant.tsx
This is the primary React component that renders the chat interface. It manages the UI, user interactions, state, and communication with the backend.
Sources: src/components/ai/AIAssistant.tsx
State Management
The component manages its state using React hooks (useState, useRef, useEffect).
| State Variable | Type | Description |
|---|---|---|
messages | Message[] | An array of message objects representing the current conversation. |
inputValue | string | The current text in the message input field. |
isLoading | boolean | A flag indicating if the assistant is currently processing a response. |
isListening | boolean | A flag indicating if the speech recognition is active. |
quotaStatus | object | An object containing the user's daily question quota (remaining, limit, isExceeded). |
showHistory | boolean | A flag to toggle the visibility of the conversation history panel. |
conversations | Conversation[] | An array of all past conversations loaded for the user. |
currentConversationId | string | null | The ID of the currently active conversation. |
pendingAttachments | object[] | An array of files (images) staged to be sent with the next message. |
Sources: src/components/ai/AIAssistant.tsx:55-70
Core Functionality
The main logic is orchestrated within the AIAssistant component, primarily in the handleSendMessage function.
handleSendMessage Flow
This function is triggered when a user sends a message. The process is as follows:
analyzeQuery Function
Before sending the message to the backend, the analyzeQuery function performs a basic client-side analysis of the user's text to categorize the query. It checks for keywords related to farming topics.
- Topics:
disease,irrigation,fertilizer,harvest,pruning,pest,weather,soil. - Output: Returns an object with
queryType,confidence, andrelatedTopics. This context is sent to the backend to help generate a more relevant response.
Sources: src/components/ai/AIAssistant.tsx:216-252
Key Features
| Feature | Description | Implementation Details |
|---|---|---|
| Multi-language Support | The UI and AI responses support English (en), Hindi (hi), and Marathi (mr). | Uses react-i18next for UI translation. The selected language is passed in the context to the AI for localized responses. |
| Voice Input | Users can speak their queries instead of typing. | Implemented using the browser's Web Speech API (webkitSpeechRecognition). It supports language-specific recognition (en-IN, hi-IN, mr-IN). |
| Conversation History | Past conversations are saved and can be reloaded. | Uses supabaseConversationStorage to load, save, and delete conversations from a Supabase database. |
| Quota Management | Limits non-authenticated or free-tier users to a set number of questions per day. | The quota-service is used to track the daily question count. The UI displays the remaining quota and disables the input when the limit is reached. |
| Image Attachments | Users can attach images to their messages for analysis. | An <input type="file"> allows image selection. Images are converted to a data URL and added to pendingAttachments before being sent. |
| Streaming Responses | AI responses are displayed token-by-token as they are generated. | The fetch API is used with response.body.getReader() to process the streaming response from the backend. |
Sources: src/components/ai/AIAssistant.tsx, context/PRD.md
Backend API: /api/ai/chat
This is a Next.js API route that serves as the backend for the AI Assistant. It is responsible for receiving user queries, communicating with the AI service, and streaming back the response.
(Note: The content of this file is inferred from the fetch call in AIAssistant.tsx)
Endpoint Details
- Route:
POST /api/ai/chat - Content-Type:
application/json - Authentication: The API checks for user authentication. Unauthenticated requests may be rejected or subject to stricter quotas.
- Rate Limiting: The API enforces a daily question limit.
Sources: src/components/ai/AIAssistant.tsx:351-361, 420-431
Request Payload
The API expects a JSON body with the following structure:
| Field | Type | Description |
|---|---|---|
message | string | The user's text query. |
context | object | An object containing contextual information such as farmData, language, conversationHistory, and recentTopics. |
attachments | object[] | An array of attached files (e.g., images as data URLs). |
stream | boolean | A flag to indicate whether the response should be streamed. |
Sources: src/components/ai/AIAssistant.tsx:357-361
Sequence Diagram
The following diagram shows the sequence of events when a user sends a message.
Conversation Management
Conversation state and history are managed both in the component's local state and persisted in a Supabase database for long-term storage.
Data Models
The core data structures for conversations are defined in TYPES_AND_INTERFACES.md and used within AIAssistant.tsx.
// From context/TYPES_AND_INTERFACES.md
export interface AIMessage {
id: string;
role: 'user' | 'assistant';
content: string;
language: 'en' | 'hi' | 'mr';
timestamp: Date;
metadata?: {
confidence?: number;
sources?: string[];
actionItems?: string[];
};
}
// From src/components/ai/AIAssistant.tsx
export interface Conversation {
id: string;
title: string;
messages: Message[];
createdAt: Date;
updatedAt: Date;
farmId?: number;
userId?: string;
lastMessageAt: Date;
messageCount: number;
}
Sources: context/TYPES_AND_INTERFACES.md:195-213, src/components/ai/AIAssistant.tsx:26-38
Database Schema
The CLAUDE.md document outlines the intended database schema for storing AI-related data in Supabase. The ai_conversations and ai_conversation_context tables are central to this feature.
This ER diagram shows the relationship between users, farms, and their AI conversations.
Sources: CLAUDE.md
Persistence Logic
A dedicated module, supabaseConversationStorage, handles all interactions with the database.
saveConversation(conversation): Saves or updates a conversation. It generates a title from the message content if one doesn't exist.loadConversations(userId, farmId): Loads all conversations for a given user and optional farm.deleteConversation(conversationId, userId): Deletes a specific conversation.migrateFromLocalStorage(userId): A utility to migrate conversations from local storage to Supabase for authenticated users.
This logic ensures that conversations are saved immediately and atomically to prevent data loss, even during streaming responses.
Sources: src/components/ai/AIAssistant.tsx:25, 275-298
Summary
The AI Assistant is a sophisticated, multi-faceted feature that combines a dynamic frontend, a streaming-capable backend, and robust data persistence. It is designed to be a highly interactive and context-aware tool for farmers, providing them with expert-level advice through a simple conversational interface. Key strengths include its multi-language support, voice interaction capabilities, and integration with farm-specific data to deliver personalized insights. The architecture is scalable, with clear separation of concerns between the client, server, and data layers.