🤖 AI Integration Documentation

Overview

Vartovii includes a built-in AI assistant powered by Google Vertex AI (Gemini).

Architecture

backend/ai/
├── config.py           # Model & region configuration
├── client.py           # GeminiClient singleton
├── services/
│   ├── chat_service.py      # Chat assistant
│   ├── report_service.py    # Company reports
│   └── sentiment_service.py  # Sentiment analysis
└── prompts/
    ├── chat.py         # Knowledge base
    ├── report.py       # Report templates
    └── sentiment.py    # Sentiment prompts

backend/api/
└── chat.py             # FastAPI endpoint /api/ai/chat

Models Used

Task	Current production profile	Fallback path
Chat	gemini-3.5-flash	gemini-2.5-flash + 2.0
Reports	gemini-3.1-pro-preview	Gemini 2.5 / 2.0 chain
Sentiment	gemini-3.5-flash	gemini-2.5-flash + 2.0
ADK paths	gemini-3.5-flash	gemini-2.5-flash + 2.0

Production currently uses GEMINI_MODEL_PROFILE=preview with Gemini 3.x models. The stable Gemini 2.5 profile remains available as a rollback path when availability, location policy, or rollout risk requires it.

API Endpoint

POST /api/ai/chat

Request:

{
  "message": "Що таке Trust Score?",
  "language": "ua",
  "history": [],
  "company": "BMW"
}

Response:

{
  "response": "Trust Score — це...",
  "status": "ok"
}

Frontend Widget

Located at: dashboard_app/src/components/ChatWidget.jsx

• Floating button (bottom-right)
• Glass-card chat panel
• Multi-turn conversation history
• Auto language detection

Configuration

Required environment variables in backend/.env:

GOOGLE_CLOUD_PROJECT=sentry-analytics-prod
GEMINI_LOCATION=global
RAG_EMBEDDING_LOCATION=europe-west4
SEARCH_LOCATION=global
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

Usage

Start all services:

./scripts/startup.sh

Test chat API:

curl -X POST http://localhost:8000/api/ai/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"Привіт!","language":"ua"}'

Knowledge Base

The AI knows about:

• Trust Score formula (Company & Crypto)
• Data sources (Kununu, Glassdoor, Reddit, etc.)
• Platform features and pricing
• How to use the platform
• FAQs