{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/README.md"
} 1→# ReviewLens AI
2→
3→A review intelligence portal that ingests customer reviews and lets analysts explore them through a guardrailed conversational interface.
4→
5→## Architecture
6→
7→```
8→CSV Upload / URL Scrape
9→ │
10→ ▼
11→ Parse & Index ──→ ChromaDB (in-process vector store)
12→ │
13→ ▼
14→ Ingestion Summary ──→ Chat Interface
15→ │
16→ User Message
17→ │
18→ ▼
19→ Claude Agent SDK
20→ (per-message loop)
21→ │
22→ ┌───────┼───────┐
23→ │ │ │
24→ search_reviews │ generate_chart
25→ analyze_sentiment
26→ calculate_stats
27→ suggest_follow_ups
28→ │
29→ ▼
30→ SSE Stream → Chat UI
31→ (text + charts + follow-ups)
32→```
33→
34→**Stack:** FastAPI, Jinja2/HTMX, SSE streaming, Claude Agent SDK with custom MCP tools, ChromaDB, Chart.js.
35→
36→## Key Design Decisions
37→
38→### Scope Guard (Three-Layer Defense)
39→The AI only answers questions about the ingested reviews:
40→1. **System prompt** — explicit instructions to refuse out-of-scope questions
41→2. **Retrieval confidence** — if ChromaDB returns nothing relevant, auto-reject
42→3. **Architectural boundary** — the agent has no tools that access external data
43→
44→### CSV-First Ingestion
45→CSV upload is the polished primary path. URL scraping via Firecrawl is best-effort secondary — review platforms are heavily anti-bot and the results are unpredictable.
46→
47→### Conversational Agent Loop
48→Unlike a fire-and-forget agent, ReviewLens invokes the agent per-message. Each user message triggers a fresh agent loop with conversation history as context.
49→
50→### Chart.js Inline Charts
51→The `generate_chart` tool returns Chart.js config JSON. The frontend renders charts inline in chat messages. The agent decides when a chart adds value.
52→
53→## Setup
54→
55→```bash
56→cd reviewlens
57→python -m venv .venv && source .venv/bin/activate
58→pip install -r requirements.txt
59→
60→cp .env.example .env
61→# Edit .env with your ANTHROPIC_API_KEY
62→
63→uvicorn app.main:app --reload
64→```
65→
66→Open http://localhost:8000
67→
68→## Deploy (Render)
69→
70→1. Push to GitHub
71→2. Connect repo in Render dashboard
72→3. Set `ANTHROPIC_API_KEY` environment variable
73→4. Deploy — uses `render.yaml` for config
74→
75→## CSV Format
76→
77→The parser auto-detects common column names. Minimum required: a text/review column.
78→
79→| Column | Aliases |
80→|--------|---------|
81→| text | text, review, review_text, content, body, comment |
82→| rating | rating, score, stars, star_rating |
83→| date | date, review_date, created_at, timestamp |
84→| author | author, reviewer, user, username |
85→| platform | platform, source, site |
86→
87→## Environment Variables
88→
89→| Variable | Required | Description |
90→|----------|----------|-------------|
91→| `ANTHROPIC_API_KEY` | Yes | Claude API key |
92→| `CLAUDE_MODEL` | No | Model override (default: claude-sonnet-4-6-20250514) |
93→| `FIRECRAWL_API_KEY` | No | Enables URL scraping |
94→| `DATA_DIR` | No | Data directory (default: data) |
95→| `CHROMA_DIR` | No | ChromaDB directory (default: data/chroma) |
96→## Setup ```bash cd reviewlens python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt cp .env.example .env # Edit .env with your ANTHROPIC_API_KEY uvicorn app.main:app --reload ``` Open http://localhost:8000
## Running Locally ### Prerequisites - Python 3.12+ - An [Anthropic API key](https://console.anthropic.com/) ### Setup ```bash # Clone and enter the project git clone <repo-url> cd reviewlens # Create virtual environment python -m venv .venv source .venv/bin/activate # macOS/Linux # .venv\Scripts\activate # Windows # Install dependencies pip install -r requirements.txt # Configure environment cp .env.example .env ``` Open `.env` and set your API key: ``` ANTHROPIC_API_KEY=sk-ant-your-key-here ``` ### Run ```bash uvicorn app.main:app --reload --reload-exclude '.venv' ``` Open [http://localhost:8000](http://localhost:8000) ### Test It 1. Go to `http://localhost:8000` 2. Enter a product name and upload a CSV (see CSV Format below) 3. You'll be redirected to the chat interface with an ingestion summary 4. Ask questions about the reviews — try the suggested follow-up buttons A sample test CSV: ```csv review_text,rating,date,author "Great product, battery life is amazing.",5,2024-06-15,Alice "Shipping took forever. Product itself is fine.",3,2024-06-20,Bob "Terrible customer service. Broke after 2 weeks.",1,2024-07-01,Charlie "Best purchase this year. Highly recommend.",5,2024-07-10,Diana ```
The file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/README.md has been updated successfully.
Done. The setup section now has clear prerequisites, step-by-step instructions, the --reload-exclude '.venv' fix, and a sample CSV to test with.