Apppublic

Kagamicho/cs_chatbot

sourceHugging Faceupdated 3mo agoView on Hugging Face

0likes

App README

Remix Denki Chatbot

Japanese AI chatbot for Remix Denki (リミックスでんき) — Phase 1 MVP.

Bootstraps from public website + PDFs + manual FAQ, designed so real CS Q&A pairs can be added later without code changes or model retraining.

See docs/superpowers/specs/2026-04-28-remix-chatbot-design.md for the full design.

Setup

bash

cp .env.example .env
# Edit .env — required vars listed below
uv sync
uv run uvicorn app.main:app --reload

Required environment variables

Variable	Purpose	How to get
`FIREBASE_ADMIN_CREDENTIALS`	Path to Firebase service-account JSON	Firebase Console → Project settings → Service accounts → Generate new private key → save to `secrets/firebase-admin.json`
`FIREBASE_PROJECT_ID`	Firebase project ID (must match service account)	Same JSON file, `project_id` field. Defaults to `remix-chatbox-dashboard`.
`GEMINI_API_KEY`	Gemini AI Studio API key (LLM calls)	https://aistudio.google.com/apikey
`CSAT_JWT_SECRET`	Signs CSAT survey links embedded in emails	`python -c "import secrets; print(secrets.token_urlsafe(48))"`
`PUBLIC_DASHBOARD_BASE_URL`	Base URL of the CS dashboard (for CSAT links)	Set to `http://localhost:3001` for dev, public URL in prod
`SMTP_PASSWORD`	Gmail App Password for outbound email	https://myaccount.google.com/apppasswords — leave empty for stub mode (emails saved but not sent)
`SMTP_USER`	SMTP login / From address	Your support Gmail address
`SMTP_HOST`	SMTP server host	`smtp.gmail.com` (default)
`SMTP_PORT`	SMTP server port	`587` (default, STARTTLS)
`SMTP_FROM_NAME`	Display name on outgoing emails	e.g. `Customer Support`
`SMTP_FROM_ADDRESS`	From address (defaults to `SMTP_USER` if empty)	Optional override
`SMTP_USE_TLS`	Enable STARTTLS	`true` (default)
`CHAT_LOG_DIR`	Directory for per-day JSONL chat logs	`data/logs` (default)

Optional / rarely changed:

Variable	Purpose	Default
`LLM_PROVIDER`	`gemini_api` or `vertex_ai`	`gemini_api`
`GCP_PROJECT_ID`	GCP project for Vertex AI	(required if `LLM_PROVIDER=vertex_ai`)
`GCP_LOCATION`	Vertex AI region	`asia-northeast1`
`ENABLE_HALLUCINATION_CHECK`	Post-answer hallucination check (~1-2s/turn)	`false`
`APP_HOST` / `APP_PORT`	Server bind address	`0.0.0.0:8000`
`LOG_LEVEL`	Python log level	`INFO`

Stack

—LLM: Gemini 2.5 (Flash + Pro) via Google AI Studio API → Vertex AI for production
—Retrieval: Hybrid (BM25 + vector embeddings + reranker)
—Backend: FastAPI
—Vector DB: Chroma (local) → Vertex Vector Search (production)
—Crawler: Playwright
—Frontend: Static HTML/JS chat widget

Quickstart

bash

# 1. Install deps
uv sync

# 2. Set API key
cp .env.example .env
# edit .env, add your GEMINI_API_KEY

# 3. Build the knowledge base from public sources
uv run python ingestion/run_ingest.py

# 4. Start the chat server
uv run uvicorn app.main:app --reload

# 5. Open the widget
# visit http://localhost:8000/

Project layout

chatbot/
├── config/         # settings, prompts, LLM profiles
├── app/            # FastAPI service (the core)
├── ingestion/      # KB build pipeline (crawl → chunk → embed → index)
├── data/           # sources, processed chunks, indexes, logs
├── frontend/       # HTML/JS chat widget
├── eval/           # golden Q&A regression set
├── scripts/        # CSV → Q&A converters, review UI, exporters
├── tests/
└── docs/           # design spec

Adding real Q&A later

When CS hands you a CSV of real Q&A:

bash

# convert (auto-detects encoding/columns first time, saves mapping)
uv run python scripts/csv_to_qa_jsonl.py --input data/sources/cs_inbox/<file>.csv --interactive

# (optional) review in browser
uv run python scripts/qa_review.py --file data/sources/qa_pairs/<batch>.jsonl

# re-index just the new Q&A (~30s, no downtime)
uv run python ingestion/run_ingest.py --source qa_pairs

No retraining. No code changes. The bot answers from the new data on the next request.

CS Dashboard Phase 1 (added 2026-05-08)

—/escalate now dual-writes to JSONL + Firestore conversations/{id}
—POST /admin/conversations/{id}/{reply,status,assignee} — agent endpoints
—GET /admin/smtp-status — banner check
—Stub-mode email: when SMTP_PASSWORD empty, replies are saved with sentVia="stub" and not delivered

See docs/superpowers/specs/2026-05-08-cs-dashboard-design.md for full design.