Configuring AI Services

Relevant source files

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

• backend/services/ai_service.py
• backend/api/questions.py
• backend/schemas.py
• web/src/components/QuestionCard.js
• web/src/components/QuestionForm.js
• README.md

The AI services module provides intelligent features for the Q&A dashboard, including AI-powered answer suggestions and real-time duplicate question detection. It is built using Langchain with Google's Gemini models. The system is designed to be robust, with a fallback "mock mode" that provides simulated responses if the AI service is not configured or encounters an error.

This integration enhances the user experience by providing instant, helpful suggestions and preventing redundant questions on the platform. The core logic is encapsulated within the AIService class in the backend, which is exposed via specific API endpoints consumed by the Next.js frontend.

Sources: README.md:14-15, backend/services/ai_service.py:1-83, backend/api/questions.py:270-296

Architecture Overview

The AI services are integrated into the application's backend and are consumed by the frontend. The two primary features, Answer Suggestion and Duplicate Question Detection, follow distinct but similar flows. The AIService acts as a central singleton service that handles all interactions with the underlying Gemini LLM.

The following diagram illustrates the high-level interaction between the user, the frontend, the backend API, and the AI service.

This diagram shows the two main AI-driven user flows: duplicate checking while typing a question and requesting an answer suggestion for an existing question.
Sources: backend/services/ai_service.py, backend/api/questions.py, web/src/components/QuestionForm.js, web/src/components/QuestionCard.js

Configuration

To enable the AI services, a specific environment variable must be set in the backend's environment (e.g., in the .env file). If this variable is not present, the service will operate in a "mock mode".

Variable	Description	File
GOOGLE_API_KEY	The API key for Google's Generative AI services (Gemini).	backend/services/ai_service.py:20

The README.md also mentions OPENAI_API_KEY and LANGCHAIN_API_KEY, but the current implementation in ai_service.py exclusively uses GOOGLE_API_KEY for the ChatGoogleGenerativeAI model.

Sources: backend/services/ai_service.py:20-23, README.md:143-145

AI Service Implementation

The core of the AI functionality resides in the AIService class, which is implemented as a singleton to ensure a single, shared instance throughout the application's lifecycle.

Sources: backend/services/ai_service.py:12-17

AIService Class

The AIService class manages the connection to the LLM, handles mock mode switching, and contains the logic for generating suggestions and checking for duplicates.

This diagram shows the structure of the AIService singleton, its private attributes, and its public methods for interacting with the AI model.
Sources: backend/services/ai_service.py:12-83

Initialization

Upon first instantiation, the _initialize method is called. It checks for the GOOGLE_API_KEY environment variable.

• If the key is found, it initializes the ChatGoogleGenerativeAI model (gemini-2.5-flash-lite) and sets mock_mode to False.
• If the key is not found or if initialization fails, it logs a warning and sets mock_mode to True.

Sources: backend/services/ai_service.py:19-35

Mock Mode

When mock_mode is True, any call to generate_suggested_answer will bypass the LLM and return a static, predefined response via the _get_mock_response method. This ensures the application remains functional for development and testing without requiring a valid API key.

# backend/services/ai_service.py:65-71
def _get_mock_response(self, question_text: str) -> SuggestedAnswer:
    logger.info(f"Returning mock answer for: {question_text}")
    return SuggestedAnswer(
        answer="""[MOCK] This is a simulated answer generated because the AI service
        is in mock mode or encountered an error.
        Please check your API key configuration.""",
    )

Sources: backend/services/ai_service.py:22-23, 37-39, 65-71

Features

1. AI-Powered Answer Suggestion

This feature allows users to request an AI-generated answer for any question on the dashboard.

Flow

The process is initiated from the frontend QuestionCard component, which calls a dedicated backend endpoint. The AIService then processes the request.

This sequence diagram details the steps from a user's click to the display of an AI-generated answer, including the backend service and LLM interaction.
Sources: web/src/components/QuestionCard.js:63-77, backend/api/questions.py:270-289, backend/services/ai_service.py:37-63

Implementation Details

The generate_suggested_answer method uses a PromptTemplate to structure the query sent to the LLM, ensuring the model provides a helpful and concise response. Before calling the LLM, it checks a semantic cache (semantic_cache) for a similar, previously answered question. If a new answer is generated, it is cached for future use.

# backend/services/ai_service.py:42-49
template = """
You are a helpful assistant for a Q&A platform. Please
provide a helpful, concise, and polite answer to the following question.

Question: {question}

Answer:
"""
prompt = PromptTemplate(template=template, input_variables=["question"])

Sources: backend/services/ai_service.py:42-59

2. Duplicate Question Detection

To prevent clutter, the system checks if a question being typed is a duplicate of an existing one. This check is performed in real-time as the user types.

Flow

The QuestionForm component uses a debounced effect to send the current text to the backend after the user stops typing for 500ms. The AIService then performs a similarity search.

This diagram shows the real-time duplicate check, from user input to the frontend displaying a warning based on the backend's similarity analysis.
Sources: web/src/components/QuestionForm.js:13-52, backend/api/questions.py:292-296, backend/services/ai_service.py:73-118

Implementation Details

The check_duplicate method leverages the semantic_cache.vector_store to perform a similarity search. It returns is_duplicate: True if the similarity score is below a certain threshold (a lower score indicates higher similarity). If a duplicate is found, the response includes the text of the similar question and its existing answer, if available.

Sources: backend/services/ai_service.py:73-118

API Endpoints and Schemas

The AI features are exposed through specific endpoints in the questions API router.

API Endpoints

Method	Endpoint	Description	Controller Function
GET	/questions/{question_id}/suggest-answer	Generates a suggested answer for a question.	suggest_answers
POST	/questions/check-duplicate	Checks if a given text is a duplicate of an existing question.	check_duplicate

Sources: backend/api/questions.py:270-296

Data Schemas

These Pydantic models define the structure of the data for AI-related API requests and responses.

Schema	Fields	Description
SuggestedAnswer	answer: str	Contains the AI-generated answer text.
DuplicateCheckRequest	text: str	The text to be checked for duplication.
DuplicateCheckResponse	is_duplicate: bool similar_question: Optional[str] answer: Optional[str] similarity_score: float	The result of the duplicate check, including details of the similar question if found.

Sources: backend/schemas.py:84-96