ux-research-agent-slackbot / docs /walkthrough.md
debug-log
Claude Opus 4.6
feat: Insight Repository โ€” GitLab ์ดˆ๊ธฐํ™” + HF ์ž๋™ ๋ฐฐํฌ
501bc8c
|
Raw History Blame Contribute Delete
5.12 kB
# UX/Research Chatbot PoC Walkthrough
This document outlines how to set up and run the Proof of Concept (PoC) for the UX/Research Chatbot. This agent searches internal research reports and Baymard guidelines using metadata filtering and LLM generation.
## Features
- **Multimodal (Image/Video) Analysis**: Analyze UI designs for usability issues or search for similar references using uploaded files.
- **Unified Search**: Searches both `research_report.json` and `baymard_unified_database_v2.json`.
- **Agentic Retriever (RAG)**: LLM์ด ์ง์ ‘ Fuzzy ๊ฒ€์ƒ‰โ†’๋ฌธ์„œ ์ฝ๊ธฐโ†’ํŒ๋‹จ ๋ฃจํ”„๋ฅผ ์‹คํ–‰ํ•˜๋Š” ์—์ด์ „ํŠธ ๊ธฐ๋ฐ˜ ๊ฒ€์ƒ‰.
- **Source Routing**: detect intent (e.g., "์‚ฌ๋‚ด ๋ฆฌ์„œ์น˜๋งŒ", "๋ฒ ์ด๋งˆ๋“œ๋งŒ") to filter data sources.
- **Context Awareness**: Remembers previous conversation turns to handle follow-up questions (e.g., "๊ทธ ์ค‘์—์„œ ์‚ฌ๋‚ด ๋ฆฌ์„œ์น˜๋งŒ ๋ณด์—ฌ์ค˜").
- **Smart Filtering**: Extracts keywords from natural language queries to filter documents before generation.
- **LLM**: Powered by Google Gemini 3 Flash (`gemini-3-flash-preview`).
## Setup
### 1. Prerequisites
- Python 3.8+
- Google API Key
### 2. Installation
1. Navigate to the project directory:
```bash
cd /Users/johan/.gemini/antigravity/brain/e4e4053f-3b95-42ed-b913-7720b36a4303
```
2. Install dependencies (if not already done):
```bash
pip install -r requirements.txt
```
3. Set up API Key:
- Ensure `.env` file exists and contains `GOOGLE_API_KEY=your_key_here`.
## Deployment
The project is deployed on Hugging Face Spaces as two separate services:
### 1. Web Application (Streamlit)
* **URL**: [https://huggingface.co/spaces/YGCXLab/ux-research-agent-poc](https://huggingface.co/spaces/YGCXLab/ux-research-agent-poc)
* **Purpose**: User-friendly web interface for research and file analysis.
* **Deployment**: `python deploy_web.py`
### 2. Slackbot
* **Space**: [https://huggingface.co/spaces/YGCXLab/ux-research-agent-slackbot](https://huggingface.co/spaces/YGCXLab/ux-research-agent-slackbot) (No UI)
* **Purpose**: Dedicated bot for Slack integration (Socket Mode).
* **Deployment**: `python deploy_slack.py`
### Slackbot Integration & Deployment (2026-01-14)
- **Separate Deployment**: Deployed Slackbot to a dedicated Hugging Face Space (`ux-research-agent-slackbot`) to ensure stability and independent scaling.
- **Full RAG Support**:
- Implemented `indexer.py` improvements to extract text from **original PDF files** (Baymard) and **Markdown files** (Internal Research).
- Configured server-side indexing: The bot automatically builds a fresh Vector DB from the uploaded `data` folder on startup, ensuring compatibility and data freshness.
- **Multimodal & Interactive**:
- Supports image/video inputs for UX analysis.
- Added emoji reactions (๐Ÿค”, โœ…, โš ๏ธ) for better user feedback during processing.
- Enabled "Socket Mode" for reliable communication without public URL exposure.
## Web Interface (Streamlit) Local Run
To run the web app locally:
```bash
venv/bin/streamlit run app.py
```
This will open a browser window at `http://localhost:8501`.
- Enter your question in the chat input.
- Clear chat history using the button in the sidebar.
## Usage Examples
### Scenario 1: General Research
Ask for materials across all sources.
> **User**: "๋ฆฌ๋ทฐ ๊ด€๋ จ ์ž๋ฃŒ ์ฐพ์•„์ค˜"
>
> **Bot**:
> - [Internal Research] [IDI] ๋ฆฌ๋ทฐ ํƒ์ƒ‰ ๊ฒฝํ—˜ ๊ฐœ์„  ์„ ํ–‰...
> - [Baymard Guideline] Allow Users to Sort Reviews #837...
>
> (Summary and links are provided for both sources)
### Scenario 2: Source-Specific Search
Ask specifically for internal or external data.
> **User**: "๋ฆฌ๋ทฐ ๊ด€๋ จ **์‚ฌ๋‚ด๋ฆฌ์„œ์น˜** ๋‚ด์šฉ ์ฐพ์•„์ค˜"
>
> **Bot**:
> - [Internal Research] [IDI] ๋ฆฌ๋ทฐ ํƒ์ƒ‰ ๊ฒฝํ—˜ ๊ฐœ์„  ์„ ํ–‰...
> - [Internal Research] ์ถ”์ฒœ ์ด๋‹ˆ์…”ํ‹ฐ๋ธŒ...
>
> (Only internal research items are returned)
### Scenario 3: Context-Aware Follow-up
Refine your search using previous context.
> **User**: "๋ฆฌ๋ทฐ ๊ด€๋ จ ์ž๋ฃŒ ์ฐพ์•„์ค˜"
> **Bot**: (Returns mixed results)
> **User**: "**๊ทธ ์ค‘์—์„œ** ์‚ฌ๋‚ด ๋ฆฌ์„œ์น˜๋งŒ ๋ณด์—ฌ์ค˜"
> **Bot**: (Filters previous topic for internal research only)
### Scenario 4: Design Critique (Multimodal)
Get feedback on a UI design.
> **Input**: (Uploads screenshot of a checkout page)
> **User**: "์ด ํ™”๋ฉด์˜ ๋ฌธ์ œ์ ์ด ๋ญ์•ผ?"
> **Bot**:
> "ํ•ด๋‹น ํ™”๋ฉด์—์„œ ๋‹ค์Œ๊ณผ ๊ฐ™์€ UX ๋ฌธ์ œ์ ์ด ๋ฐœ๊ฒฌ๋ฉ๋‹ˆ๋‹ค:
> 1. '๊ฒฐ์ œํ•˜๊ธฐ' ๋ฒ„ํŠผ์ด ์Šคํฌ๋กค ์•„๋ž˜์— ์žˆ์–ด ๋ฐœ๊ฒฌํ•˜๊ธฐ ์–ด๋ ต์Šต๋‹ˆ๋‹ค (Baymard Guideline #124 ์ฐธ์กฐ).
> 2. ..."
### Scenario 5: Visual Reference Search (Multimodal)
Find guidelines relevant to a specific UI pattern.
> **Input**: (Uploads screenshot of a date picker)
> **User**: "์ด๋Ÿฐ UI์™€ ๊ด€๋ จ๋œ ๊ฐ€์ด๋“œ๋ผ์ธ ์ฐพ์•„์ค˜"
> **Bot**:
> "์ด๋ฏธ์ง€์—์„œ 'Date Picker', 'Calendar' ์š”์†Œ๊ฐ€ ์‹๋ณ„๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ๊ด€๋ จ ๊ฐ€์ด๋“œ๋ผ์ธ์€ ๋‹ค์Œ๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค:
> - [Baymard] Date Picker Design Best Practices..."
- `search_engine.py`: Main entry point and logic (CLI, LLM Chain).
- `requirements.txt`: Python package dependencies.