Google Gemini AI Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/modeling/gemini_sentiment.py
• src/modeling/comment_filter.py
• dashboard-next/app/api/live-comments/route.ts
• DUAL_MODEL_ARCHITECTURE.md
• GEMINI_AI_INTEGRATION.md
• src/modeling/gemini_svm_mimic.py
• CHANGELOG.md
• README.md

The Google Gemini AI integration is a core component of the project's real-time analysis capabilities. It is part of a Dual Model Architecture where it handles live, raw data from YouTube, providing context-aware sentiment analysis, while a traditional SVM model handles static, pre-labeled data. This integration enables advanced features such as smart comment filtering and nuanced understanding of Indonesian slang and colloquialisms, significantly improving analysis accuracy for live content.

The integration primarily uses the gemini-2.5-flash model for its efficiency and is accessed via a dedicated FastAPI backend. It includes robust features like rate limiting and a fallback system to ensure service availability.

Sources: DUAL_MODEL_ARCHITECTURE.md, GEMINI_AI_INTEGRATION.md, README.md

Architecture Overview

The system employs a dual-model strategy to leverage the strengths of both traditional machine learning and modern large language models. Gemini AI is exclusively used for the "Live Dashboard" components.

• Static Dashboard: Uses a custom-trained SVM model for analyzing historical, cleaned, and pre-labeled datasets. This is fast, cost-effective, and consistent for static analysis.
• Live Dashboard: Uses Gemini AI for real-time analysis of raw, unprocessed YouTube comments. This provides high accuracy, contextual understanding, and reasoning for its predictions.

Sources: DUAL_MODEL_ARCHITECTURE.md, CHANGELOG.md:14-25, README.md:12-29

The following diagram illustrates the dual-model architecture.

Model Comparison

Aspect	SVM Model	Gemini AI
Data Type	Pre-labeled, cleaned	Raw, real-time
Training	Custom dataset	Pre-trained LLM
Speed	<1ms per comment (local)	1-2s per comment (API call)
Accuracy	87.5% (domain-specific)	95%+ (estimated)
Context	Limited	Excellent
Reasoning	No	Yes
Cost	Free	API quota
Offline	Yes	No

Sources: DUAL_MODEL_ARCHITECTURE.md:80-91, README.md:32-41

Core Components

The Gemini integration is composed of several key Python classes, each responsible for a specific task.

GeminiSentimentAnalyzer

This class is the primary component for performing sentiment analysis on text. It is located in src/modeling/gemini_sentiment.py.

Sources: src/modeling/gemini_sentiment.py:9-100

Key Logic:

1. Initialization: Configures the google.generativeai library with an API key and initializes the gemini-2.5-flash model.
2. Rate Limiting: Before making an API call, _check_rate_limit() ensures the number of requests does not exceed max_requests_per_hour (set to 15). The counter resets every hour.
3. Prompting: The analyze_sentiment method constructs a specific prompt asking the AI to classify the sentiment and provide a confidence score and reasoning in JSON format.
4. API Call: It sends the prompt to the Gemini API.
5. Response Parsing: It parses the JSON from the AI's response. If parsing fails, it attempts a simpler text-based extraction.
6. Fallback: If the rate limit is exceeded, the API call fails, or parsing fails, it reverts to _fallback_analysis(), a rule-based method using positive/negative word lists.

Sources: src/modeling/gemini_sentiment.py:12-99

The prompt is structured to ensure a consistent JSON output:

# src/modeling/gemini_sentiment.py:65-68
prompt = f"""Analisis sentimen: "{text}"
        
Jawab format JSON:
{{"sentiment": "positive/negative/neutral", "confidence": 0.85, "reasoning": "alasan singkat"}}"""

Sources: src/modeling/gemini_sentiment.py:65-68

GeminiCommentFilter

This class uses Gemini AI to determine if a comment is relevant to the topic of Indonesian football (timnas). This pre-processing step significantly reduces the number of irrelevant comments sent for full sentiment analysis, saving API calls and processing time.

Key Logic:

1. Relevance Check: The is_relevant_comment method sends a comment to the Gemini AI.
2. Prompting: The prompt asks the AI to act as a filter, providing criteria for "RELEVAN" and "TIDAK RELEVAN" content, and to respond with a JSON object containing a boolean relevant flag and a reason.
3. Rate Limiting: It implements a similar hourly rate limit (max_requests = 10) as the sentiment analyzer.
4. Fallback: If the rate limit is exceeded or the API call fails, it uses _fallback_filter(), which relies on keyword matching for football context and spam indicators.

Sources: src/modeling/comment_filter.py:10-100

GeminiSVMMimic

This experimental component demonstrates using Gemini's few-shot learning capabilities to mimic the behavior of the project's statically trained SVM model. It generates a prompt containing examples of the SVM model's predictions and asks Gemini to predict new text in the same style. This showcases the versatility of the Gemini integration beyond simple sentiment analysis.

Sources: src/modeling/gemini_svm_mimic.py

API Integration and Data Flow

The Gemini models are exposed via a FastAPI backend, which the Next.js frontend consumes. The primary flow is for analyzing live YouTube comments.

Live Comment Analysis Flow

The following sequence diagram illustrates the process when a user requests live comment analysis from the dashboard.

Sources: dashboard-next/app/api/live-comments/route.ts, GEMINI_AI_INTEGRATION.md:30-46

API Endpoints

The Gemini integration is primarily served by a FastAPI backend running on http://localhost:8000.

Method	Endpoint	Description	Source File
POST	/predict	Analyzes sentiment for a single text.	GEMINI_AI_INTEGRATION.md:33-37
POST	/predict-batch	Analyzes sentiment for a list of texts.	GEMINI_AI_INTEGRATION.md:39-43
GET	/model-info	Returns information about the loaded model.	GEMINI_AI_INTEGRATION.md:45-46
GET	/health	Health check endpoint.	GEMINI_AI_INTEGRATION.md:73-74

Configuration and Rate Limiting

The system includes mechanisms for configuration and to prevent exceeding API quotas.

API Key

The Gemini API key is hardcoded in the source files for demonstration purposes, but documentation suggests it should be managed via environment variables.

• Hardcoded Key: AIzaSyC79pEPb22JKUyXlmOjVt99vnLounyYvrY
• Location: src/modeling/gemini_sentiment.py:104, src/modeling/comment_filter.py:11, src/modeling/gemini_svm_mimic.py:12
• Recommended Practice: export GEMINI_API_KEY="your_api_key"

Sources: src/modeling/gemini_sentiment.py:104, README.md:123-124, DUAL_MODEL_ARCHITECTURE.md:144-145

Rate Limiting and Fallback

To manage API costs and usage limits, both the sentiment analyzer and comment filter implement rate limiting with a fallback mechanism.

The logic flow is as follows:

Sources: src/modeling/gemini_sentiment.py:21-30, 58-63, 91-99, src/modeling/comment_filter.py:17-23, 56-58

Component	Rate Limit	Fallback Method
GeminiSentimentAnalyzer	15 requests/hour	Keyword-based word counting (_fallback_analysis)
GeminiCommentFilter	10 requests/hour	Keyword matching for football/spam (_fallback_filter)

Sources: src/modeling/gemini_sentiment.py:15, 32-53, src/modeling/comment_filter.py:14, 60-94, CHANGELOG.md:68

Conclusion

The Google Gemini AI integration is a pivotal feature that elevates the project from a standard sentiment analysis tool to an advanced, real-time social listening platform. By handling the complexities of live, unstructured data, it provides nuanced, context-aware insights that are not possible with the static SVM model alone. The architecture's inclusion of smart filtering, rate limiting, and robust fallback systems demonstrates a well-considered approach to integrating a powerful but quota-limited external service, ensuring both high-quality analysis and system resilience.