Перейти до основного вмісту

🤖 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) 💬 for quick follow-up questions.
  2. Open the dedicated workspace route at /app/assistant when you want conversation history, guided starter briefs, and direct handoffs into other product surfaces.
  3. Type your question in any supported language and continue the workflow from chat into reports, company pages, watchlists, or forensics when handoffs are available.

Capabilities​

What the Assistant Knows​

TopicDetails
Platform NavigationAll menu items, tabs, their purpose
Topics TabAspect analysis, data from aspect_sentiments
Sentiment TabPie charts, AI labels
Battle ModeCompany comparison
Trust ScoreComplete formula breakdown
Data SourcesKununu, Glassdoor, Reddit, etc.
Real-time InfoNews, stock prices, market trends
DocumentationDeployment guides, API docs, troubleshooting

Workspace And Handoff Behavior​

  • The assistant can now run inside a dedicated workspace route with saved conversation history.
  • Guided starter briefs help users begin with common company, crypto, and contract-forensics tasks.
  • Assistant responses may include workflow-aware next steps such as:
    • opening a company overview
    • viewing a report
    • adding an entity to a watchlist
    • opening the forensics route for a contract or wallet follow-up
  • These handoffs depend on the available evidence and the current tool path.

Security Readiness And Report Handoff​

The assistant workspace can prepare a crypto security readiness brief and hand that brief into the dedicated readiness report route:

/app/crypto/:slug/readiness

This workflow is designed for pre-audit and partner-review preparation. The assistant keeps the current project, evidence gaps, security provenance, and recommended next actions visible, then opens a report-ready surface when the user needs a structured handoff.

The readiness workflow can help answer questions such as:

  • What evidence is available for this crypto project right now?
  • Which security, contract, tokenomics, or source gaps should be closed before a public review?
  • What should a reviewer, founder, investor, or partner look at next?

The readiness route is not a formal smart contract audit, investment recommendation, legal conclusion, or guarantee that vulnerabilities do not exist. It is a structured handoff based on available Vartovii data and visible source evidence.

Workflow Memory For Follow-Ups​

Assistant responses can include additive workflow metadata. When a previous response includes a company, crypto, contract, or readiness workflow, short follow-up questions such as What should I do next? can stay attached to the same context instead of starting a new generic chat path.

This behavior is used by the assistant workspace to keep the latest brief, tools, route suggestions, and next-step cards aligned with the conversation.

Languages Supported​

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

Prompt Alignment Contract (Updated 2026-03-03)​

The chat system prompt is synchronized with runtime scoring logic and risk boundaries.

Corporate Trust Score (6-factor)​

  • Rating Quality: 25%
  • Sentiment: 25%
  • Volume: 15%
  • Source Diversity: 15%
  • Consistency: 10%
  • Recency: 10%

Crypto Trust Score (6-factor)​

  • Treasury: 20%
  • Dev Activity: 20%
  • Security: 20%
  • Financials: 15%
  • Tokenomics: 15%
  • Community: 10%

Risk Level Boundaries​

  • LOW: 80-100
  • MEDIUM: 60-79
  • HIGH: 40-59
  • CRITICAL: 0-39

Response Policy​

  • Avoid conditional/speculative wording for available data (for example if, might, could, probably).
  • State concrete numbers when data exists.
  • If required data is missing, explicitly say "data not available".

🔍 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​

ParameterTypeDescription
messagestringUser's question (required)
historyarrayPrevious messages for context
companystringOptional company context
languagestringen, ua, or auto
enable_groundingboolForce web search on/off
enable_ragboolForce internal docs search on/off

History messages can include additive assistant execution metadata. When a previous assistant message includes execution.workflow, the backend uses that workflow context to keep short follow-up turns, such as "what next?", tied to the prior company, crypto, or contract analysis.

Response Fields​

FieldTypeDescription
responsestringAI answer (markdown formatted)
statusstringok or error
groundedboolWhether web search was used
rag_usedboolWhether internal docs were searched
sourcesarrayCitations (type: web or rag)
executionobjectRuntime metadata including tool execution and workflow context

Execution Metadata​

The /api/ai/chat response can now include additive execution context for workspace-aware UI rendering.

Example fields inside execution:

  • status
  • tools_used
  • workflow.action_type
  • workflow.entity_ref
  • workflow.suggested_next

The workflow.suggested_next list is used by the assistant workspace to render direct handoff actions without changing the core response schema for existing clients.

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)​

TaskModel (default stable)Notes
Chatgemini-2.5-flashFast and region-safe
Reportsgemini-2.5-proHigh quality in EU regions
Fallbackgemini-2.5-* + 2.0Automatic safety chain
Preview modegemini-3*Enable with GEMINI_MODEL_PROFILE=preview
RAG Embeddingstext-embedding-004Vertex 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