feat: add in-product survey system (#2008)

* feat: add in-product survey system

- SurveyManager: event-based trigger, Space API communication
- Trigger on first successful non-WebSocket response
- Backend API: /api/v1/survey/{pending,respond,dismiss}
- Frontend: floating survey widget with progressive questions
- Flat radio/checkbox style (not dropdown Select)

* fix: persist triggered survey events to disk across restarts

Store triggered events in data/survey_triggered_events.json so that
restarting the process doesn't re-query Space for already-triggered events.

* fix: use metadata table for survey event persistence instead of file

Store triggered events in the existing metadata KV table
(key='survey_triggered_events') instead of a standalone JSON file.

* fix: ruff format and prettier fixes

Author: RockChinQ

src/langbot/pkg/api/http/controller/groups/survey.py

@@ -0,0 +1,47 @@
+import quart
+
+from .. import group
+
+
+@group.group_class('survey', '/api/v1/survey')
+class SurveyRouterGroup(group.RouterGroup):
+    async def initialize(self) -> None:
+        @self.route('/pending', methods=['GET'], auth_type=group.AuthType.USER_TOKEN)
+        async def _get_pending() -> str:
+            """Get pending survey for the frontend to display."""
+            survey = self.ap.survey.get_pending_survey() if self.ap.survey else None
+            return self.success(data={'survey': survey})
+
+        @self.route('/respond', methods=['POST'], auth_type=group.AuthType.USER_TOKEN)
+        async def _respond() -> str:
+            """Submit survey response."""
+            json_data = await quart.request.json
+            survey_id = json_data.get('survey_id')
+            answers = json_data.get('answers', {})
+            completed = json_data.get('completed', True)
+
+            if not survey_id:
+                return self.fail(1, 'survey_id required')
+
+            if self.ap.survey:
+                ok = await self.ap.survey.submit_response(survey_id, answers, completed)
+                if ok:
+                    return self.success()
+                return self.fail(2, 'Failed to submit response')
+            return self.fail(3, 'Survey not available')
+
+        @self.route('/dismiss', methods=['POST'], auth_type=group.AuthType.USER_TOKEN)
+        async def _dismiss() -> str:
+            """Dismiss survey."""
+            json_data = await quart.request.json
+            survey_id = json_data.get('survey_id')
+
+            if not survey_id:
+                return self.fail(1, 'survey_id required')
+
+            if self.ap.survey:
+                ok = await self.ap.survey.dismiss_survey(survey_id)
+                if ok:
+                    return self.success()
+                return self.fail(2, 'Failed to dismiss')
+            return self.fail(3, 'Survey not available')

src/langbot/pkg/core/app.py

@@ -39,6 +39,7 @@
 from ..rag.knowledge import kbmgr as rag_mgr
 from ..vector import mgr as vectordb_mgr
 from ..telemetry import telemetry as telemetry_module
+from ..survey import manager as survey_module
 
 
 class Application:
@@ -147,6 +148,8 @@ class Application:
 
     telemetry: telemetry_module.TelemetryManager = None
 
+    survey: survey_module.SurveyManager = None
+
     monitoring_service: monitoring_service.MonitoringService = None
 
     def __init__(self):

src/langbot/pkg/core/stages/build_app.py

@@ -34,6 +34,7 @@
 from ...vector import mgr as vectordb_mgr
 from .. import taskmgr
 from ...telemetry import telemetry as telemetry_module
+from ...survey import manager as survey_module
 
 
 @stage.stage_class('BuildAppStage')
@@ -110,6 +111,11 @@ async def run(self, ap: app.Application):
         await telemetry_inst.initialize()
         ap.telemetry = telemetry_inst
 
+        # Survey manager
+        survey_inst = survey_module.SurveyManager(ap)
+        await survey_inst.initialize()
+        ap.survey = survey_inst
+
         cmd_mgr_inst = cmdmgr.CommandManager(ap)
         await cmd_mgr_inst.initialize()
         ap.cmd_mgr = cmd_mgr_inst

src/langbot/pkg/pipeline/process/handlers/chat.py

@@ -200,6 +200,11 @@ async def handle(
 
                     # Send telemetry asynchronously and do not block pipeline via app's telemetry manager
                     await self.ap.telemetry.start_send_task(payload)
+
+                    # Trigger survey event on first successful non-WebSocket response
+                    if not locals().get('error_info') and adapter_name and 'WebSocket' not in adapter_name:
+                        if self.ap.survey:
+                            await self.ap.survey.trigger_event('first_bot_response_success')
                 except Exception as ex:
                     # Ensure telemetry issues do not affect normal flow
                     self.ap.logger.warning(f'Failed to send telemetry: {ex}')

src/langbot/pkg/survey/__init__.py

@@ -0,0 +1 @@
+"""Survey module for in-product surveys triggered by events."""

src/langbot/pkg/survey/manager.py

@@ -0,0 +1,148 @@
+"""Survey manager: tracks events, communicates with Space to fetch/submit surveys."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import typing
+import httpx
+import sqlalchemy
+
+from ..core import app as core_app
+from ..entity.persistence.metadata import Metadata
+from ..utils import constants
+
+SURVEY_TRIGGERED_KEY = 'survey_triggered_events'
+
+
+class SurveyManager:
+    """Manages survey lifecycle: event tracking, pending survey fetch, submission."""
+
+    def __init__(self, ap: core_app.Application):
+        self.ap = ap
+        self._triggered_events: set[str] = set()
+        self._pending_survey: typing.Optional[dict] = None
+        self._space_url: str = ''
+
+    async def initialize(self):
+        space_config = self.ap.instance_config.data.get('space', {})
+        self._space_url = space_config.get('url', '').rstrip('/')
+        await self._load_triggered_events()
+
+    async def _load_triggered_events(self):
+        """Load previously triggered events from metadata table."""
+        try:
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.select(Metadata).where(Metadata.key == SURVEY_TRIGGERED_KEY)
+            )
+            row = result.first()
+            if row:
+                self._triggered_events = set(json.loads(row[0].value))
+        except Exception:
+            self._triggered_events = set()
+
+    async def _save_triggered_events(self):
+        """Persist triggered events to metadata table."""
+        try:
+            value = json.dumps(list(self._triggered_events))
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.select(Metadata).where(Metadata.key == SURVEY_TRIGGERED_KEY)
+            )
+            if result.first():
+                await self.ap.persistence_mgr.execute_async(
+                    sqlalchemy.update(Metadata).where(Metadata.key == SURVEY_TRIGGERED_KEY).values(value=value)
+                )
+            else:
+                await self.ap.persistence_mgr.execute_async(
+                    sqlalchemy.insert(Metadata).values(key=SURVEY_TRIGGERED_KEY, value=value)
+                )
+        except Exception as e:
+            self.ap.logger.debug(f'Failed to save survey triggered events: {e}')
+
+    def _is_space_configured(self) -> bool:
+        space_config = self.ap.instance_config.data.get('space', {})
+        if space_config.get('disable_telemetry', False):
+            return False
+        return bool(self._space_url)
+
+    async def trigger_event(self, event: str):
+        """Called when an event occurs. Checks Space for a pending survey."""
+        if event in self._triggered_events:
+            return
+        if not self._is_space_configured():
+            return
+
+        self._triggered_events.add(event)
+        await self._save_triggered_events()
+
+        # Check for pending survey asynchronously
+        asyncio.create_task(self._fetch_pending_survey(event))
+
+    async def _fetch_pending_survey(self, event: str):
+        """Fetch pending survey from Space for this event."""
+        try:
+            url = f'{self._space_url}/api/v1/survey/pending'
+            payload = {
+                'instance_id': constants.instance_id,
+                'event': event,
+            }
+            async with httpx.AsyncClient(timeout=httpx.Timeout(10)) as client:
+                resp = await client.post(url, json=payload)
+                if resp.status_code == 200:
+                    data = resp.json()
+                    if data.get('code') == 0 and data.get('data', {}).get('survey'):
+                        self._pending_survey = data['data']['survey']
+                        self.ap.logger.info(f'Survey pending: {self._pending_survey.get("survey_id")}')
+        except Exception as e:
+            self.ap.logger.debug(f'Failed to fetch pending survey: {e}')
+
+    def get_pending_survey(self) -> typing.Optional[dict]:
+        """Return the current pending survey (if any) for the frontend to display."""
+        return self._pending_survey
+
+    def clear_pending_survey(self):
+        """Clear the pending survey (after user responds or dismisses)."""
+        self._pending_survey = None
+
+    async def submit_response(self, survey_id: str, answers: dict, completed: bool = True) -> bool:
+        """Submit a survey response to Space."""
+        if not self._is_space_configured():
+            return False
+        try:
+            url = f'{self._space_url}/api/v1/survey/respond'
+            payload = {
+                'survey_id': survey_id,
+                'instance_id': constants.instance_id,
+                'answers': answers,
+                'metadata': {
+                    'version': constants.semantic_version,
+                },
+                'completed': completed,
+            }
+            async with httpx.AsyncClient(timeout=httpx.Timeout(10)) as client:
+                resp = await client.post(url, json=payload)
+                if resp.status_code == 200:
+                    self.clear_pending_survey()
+                    return True
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to submit survey response: {e}')
+        return False
+
+    async def dismiss_survey(self, survey_id: str) -> bool:
+        """Dismiss a survey."""
+        if not self._is_space_configured():
+            return False
+        try:
+            url = f'{self._space_url}/api/v1/survey/dismiss'
+            payload = {
+                'survey_id': survey_id,
+                'instance_id': constants.instance_id,
+            }
+            async with httpx.AsyncClient(timeout=httpx.Timeout(10)) as client:
+                resp = await client.post(url, json=payload)
+                if resp.status_code == 200:
+                    self.clear_pending_survey()
+                    return True
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to dismiss survey: {e}')
+        return False