🤖 AI Chat Assistant Feature

Overview

Vartovii includes an integrated AI Chat Assistant powered by Google Vertex AI Gemini, using the configured stable or preview model profile with fallback safety.

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

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

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 checked on every push to docs/:

1. GitHub Action triggers on push to docs/**
2. Syncs documentation snapshots for retrieval checks
3. Keeps the Neon-backed retrieval index aligned through the active indexing workflow
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

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

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)
execution	object	Runtime 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 profiles and fallback chain
├── client.py                 # GeminiClient singleton
├── prompts/chat.py           # System prompt + knowledge base
├── services/
│   └── chat_service.py       # Chat + Grounding + RAG logic
└── rag/
    ├── retrieval_service.py  # Neon-backed retrieval service
    └── embedding_service.py  # Vertex embedding adapter

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=global
RAG_EMBEDDING_LOCATION=europe-west4
SEARCH_LOCATION=global
GOOGLE_APPLICATION_CREDENTIALS=./sentry-analytics-key.json

Models (current)

Task	Current production profile	Notes
Chat	gemini-3.5-flash	Fast interactive path
Reports	gemini-3.1-pro-preview	Deep report generation path
Fallback	gemini-2.5-* + 2.0	Automatic safety chain
Stable mode	gemini-2.5-flash / gemini-2.5-pro	Rollback profile
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