🤖 AI Chat Assistant Feature

Overview

Vartovii includes an integrated AI Chat Assistant powered by Google Vertex AI (Gemini 3 Flash preview with Gemini 2.5 fallback).

The assistant is named Вартовий (Guardian in Ukrainian) and can answer questions about:

• All platform features and tabs
• Trust Score formulas (Company & Crypto)
• Data sources
• How to use the platform
• Real-time market news (via Google Search Grounding)
• Internal documentation (via RAG - 86+ docs indexed)

How to Access

1. Click the floating chat button (bottom-right corner) 💬
2. Type your question in any language
3. Get instant AI-powered answers with beautiful markdown formatting

Capabilities

What the Assistant Knows

Topic	Details
Platform Navigation	All menu items, tabs, their purpose
Topics Tab	Aspect analysis, data from aspect_sentiments
Sentiment Tab	Pie charts, AI labels
Battle Mode	Company comparison
Trust Score	Complete formula breakdown
Data Sources	Kununu, Glassdoor, Reddit, etc.
Real-time Info	News, stock prices, market trends
Documentation	Deployment guides, API docs, troubleshooting

Languages Supported

• 🇺🇦 Ukrainian
• 🇬🇧 English
• 🇩🇪 German

---

🔍 Google Search Grounding

The assistant can search the web to provide real-time information.

Auto-Detection

Grounding is automatically triggered when your question contains:

• latest, news, today, current, right now
• stock, price, market, trend
• what is, who is, tell me about
• compare to, competitor

Example

User: What are the latest news about Tesla?
Assistant: [searches Google, returns current info with sources]

---

📚 RAG (Internal Documentation Search)

The assistant can search 86+ internal markdown documents to provide accurate, context-aware answers.

Auto-Detection

RAG is automatically triggered for questions containing:

• how to, how do I, where is
• documentation, docs, guide
• deploy, setup, configure
• API, endpoint, error
• як, де знайти (Ukrainian)

Example

User: How do I deploy to Cloud Run?
Assistant: [searches docs, cites GCP_MIGRATION_GUIDE.md]

Auto-Indexing (GitHub Action)

Documents are automatically synced and re-indexed on every push to docs/:

1. GitHub Action triggers on push to docs/**
2. Syncs docs to GCS bucket gs://sentry-analytics-docs-rag/docs/
3. Re-indexes Vertex AI RAG corpus
4. Shows summary in GitHub Actions

Manual indexing:

cd backend
python scripts/index_docs.py         # Index from GCS
python scripts/index_docs.py --list  # View indexed files
python scripts/index_docs.py --info  # Corpus information

---

API Reference

Endpoints

• POST /api/ai/chat — Main chat (with optional grounding/RAG)
• POST /api/ai/search — Web search with AI summary
• GET /api/ai/chat/health — Health check

Request Parameters

Parameter	Type	Description
message	string	User's question (required)
history	array	Previous messages for context
company	string	Optional company context
language	string	en, ua, or auto
enable_grounding	bool	Force web search on/off
enable_rag	bool	Force internal docs search on/off

Response Fields

Field	Type	Description
response	string	AI answer (markdown formatted)
status	string	ok or error
grounded	bool	Whether web search was used
rag_used	bool	Whether internal docs were searched
sources	array	Citations (type: web or rag)

Example Request

{
  "message": "How do I configure the database?",
  "enable_rag": true
}

Example Response

{
  "response": "To configure the database...",
  "status": "ok",
  "grounded": false,
  "rag_used": true,
  "sources": [{ "type": "rag", "file": "QUICKSTART.md", "score": 0.85 }]
}

---

Architecture

backend/ai/
├── config.py                 # Model config (Gemini 3 preview + fallback)
├── client.py                 # GeminiClient singleton
├── prompts/chat.py           # System prompt + knowledge base
├── services/
│   └── chat_service.py       # Chat + Grounding + RAG logic
└── rag/
    ├── corpus_manager.py     # Vertex AI RAG corpus
    └── retrieval_service.py  # Semantic search

backend/api/
└── chat.py                   # API endpoints

backend/scripts/
└── index_docs.py             # Document indexing CLI

.github/workflows/
└── rag-auto-index.yml        # Auto-sync & reindex on push

dashboard_app/src/components/
└── ChatWidget.jsx            # Floating UI widget + markdown

---

UI Features

Markdown Rendering

The chat widget renders AI responses with beautiful formatting:

• Headers — Styled h1, h2, h3
• Tables — Proper borders and highlighting
• Lists — Bullet and numbered lists
• Code — Syntax-highlighted blocks
• Links — Clickable with proper styling
• Bold/Italic — Emphasized text

Floating Widget

• Bottom-right corner button
• Expandable chat panel (glassmorphism design)
• Multi-turn conversation with history
• Loading animation

---

Configuration

Environment Variables

GOOGLE_CLOUD_PROJECT=sentry-analytics-prod
GEMINI_LOCATION=europe-west4
SEARCH_LOCATION=global
GOOGLE_APPLICATION_CREDENTIALS=./sentry-analytics-key.json

Models (current)

Task	Model	Notes
Chat	gemini-3-flash-preview	Fast, primary
Reports	gemini-3.1-pro-preview	High quality, primary
Fallback	gemini-2.5-*	Automatic safety chain
RAG Embeddings	text-embedding-004	Vertex AI

---

Status

• Grounding — Google Search for real-time info ✅
• RAG Search — 86+ docs indexed ✅
• Auto-Indexing — GitHub Action on push ✅
• Markdown UI — Beautiful rendering ✅
• Source Citations UI — Display in chat widget
• Feedback Collection — Improve responses