🤖 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	Model	Why
Chat	gemini-3-flash-preview	Fast responses (primary)
Reports	gemini-3.1-pro-preview	High quality (primary)
Sentiment	gemini-3-flash-preview	Cost-effective (primary)
Fallbacks	gemini-2.5-*	Automatic safety chain

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=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