{"repo": "auxilus08/hvac-customer-complaint-intelligence-system", "files": {"CLAUDE.md": {"f4f5bc377539049a3f4db9da4ad82abf9823715d": {"t": 1785746478.511911, "n": 6506, "h": "950c3ff484c3cc2d", "c": "# HVAC Customer Complaint Intelligence System\n\nEnd-to-end platform that ingests HVAC service complaints (English + Hinglish), clusters\nthem by semantic similarity, detects emerging fault patterns, and generates LLM-authored\nadvisories. Goal: compress 6–8 week manual pattern-detection cycles to under 24 hours.\n\n## Repository layout\n\n| Path | Purpose | Stack |\n|------|---------|-------|\n| [hvac-backend/](hvac-backend/) | API + workers + DB | Python 3.11, FastAPI, SQLAlchemy 2.0 async, Alembic, Celery, Redis, Postgres 16 + pgvector |\n| [hvac-ml/](hvac-ml/) | ML pipeline (imported by backend) | sentence-transformers (`paraphrase-multilingual-MiniLM-L12-v2`), UMAP, HDBSCAN, VADER |\n| [hvac-frontend/](hvac-frontend/) | Dashboard | React 18, Vite, Tailwind, react-query, Plotly, Recharts |\n\n**LLM provider is pluggable.** Set `LLM_PROVIDER` in `.env` to one of `deepseek`, `qwen`, or `gemini`. All three are accessed through the OpenAI Python SDK against each provider's compatible-mode endpoint, so the call sites are uniform. The factory lives at [hvac-backend/app/services/llm_client.py](hvac-backend/app/services/llm_client.py) — `get_llm_client() -> (OpenAI, model_name)`. Anthropic is no longer used; ignore any stale `ANTHROPIC_API_KEY` references.\n\n| Provider | Default model | Base URL |\n|----------|--------------|----------|\n| `deepseek` | `deepseek-chat` | `https://api.deepseek.com` |\n| `qwen` | `qwen3-vl-plus` | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` |\n| `gemini` | `gemini-2.5-flash-lite` | `https://generativelanguage.googleapis.com/v1beta/openai/` |\n\nThe legacy `google.generativeai` SDK path is preserved in [hvac-ml/pipeline/labeler.py](hvac-ml/pipeline/labeler.py) for backward compatibility — when the labeler is constructed without an injected `client`/`base_url` it falls back to that path. New call sites should always inject the client from `get_llm_client()`.\n\n## Backend internals\n\n- Entry: [hvac-backend/app/main.py](hvac-backend/app/main.py)\n- HTTP routes: [hvac-backend/app/api/](hvac-backend/app/api/)\n- ORM models: [hvac-backend/app/models/](hvac-backend/app/models/)\n- Pydantic schemas: [hvac-backend/app/schemas/](hvac-backend/app/schemas/)\n- Business logic: [hvac-backend/app/services/](hvac-backend/app/services/)\n- Celery workers: [hvac-backend/app/workers/](hvac-backend/app/workers/) — queues: `embeddings`, `sentiment`, `batch`\n- Migrations: [hvac-backend/alembic/](hvac-backend/alembic/)\n\n## ML pipeline\n\nStage modules in [hvac-ml/pipeline/](hvac-ml/pipeline/): `embedder.py` → `clusterer.py` → `labeler.py` → `sentiment.py` → `trend_detector.py`.\n\n`umap-learn` requires `scikit-learn<1.7` (the `force_all_finite` rename); pyproject pins `scikit-learn==1.6.1` — don't bump it.\n\n## Frontend internals\n\n- Entry: [hvac-frontend/src/main.jsx](hvac-frontend/src/main.jsx), [hvac-frontend/src/App.jsx](hvac-frontend/src/App.jsx)\n- API client: [hvac-frontend/src/api/](hvac-frontend/src/api/)\n- Components: [hvac-frontend/src/components/](hvac-frontend/src/components/)\n- Dev server proxies `/api/*` → `http://localhost:8000`. Override via `VITE_API_BASE_URL` in `hvac-frontend/.env.local`.\n\n## Common commands\n\nRun from each subproject root.\n\n### Backend ([hvac-backend/Makefile](hvac-backend/Makefile))\n\n```bash\nmake dev              # docker compose up --build (full stack: api + workers + pg + redis)\nmake down             # stop stack and drop volumes\nmake migrate          # alembic upgrade head\nmake migration m='...' # autogenerate migration\nmake seed             # synthetic complaints\nmake cluster          # trigger nightly batch cluster job\nmake test             # fast tests (excludes slow + performance)\nmake test-unit        # unit only\nmake test-integ       # integration only\nmake test-compliance  # PII compliance suite (22 tests)\nmake test-slow        # ML quality gates (silhouette, Jaccard)\nmake lint             # ruff check + mypy\nmake format           # ruff format + --fix\nmake check-pii        # PII strip audit\nmake demo-check       # verify_demo_data.py\nmake flower           # Celery monitor at :5555\n```\n\n### ML\n\n```bash\ncd hvac-ml\npytest -m \"not slow\"  # fast\npytest -m slow        # quality gates\n```\n\n### Frontend\n\n```bash\ncd hvac-frontend\nnpm install\nnpm run dev           # :5173\nnpm run build && npm run preview\nnpm run lint\n```\n\n## Required environment\n\nEdit `hvac-backend/.env` (copy from `.env.example`):\n\n| Variable | Purpose |\n|----------|---------|\n| `LLM_PROVIDER` | `deepseek`, `qwen`, or `gemini` — picks which key/model/base-URL trio gets used |\n| `DEEPSEEK_API_KEY` / `QWEN_API_KEY` / `GOOGLE_API_KEY` | At least the active provider's key must be set |\n| `SECRET_KEY` | App signing key (32+ chars) — `python -c \"import secrets; print(secrets.token_hex(32))\"` |\n| `RAW_TEXT_ENCRYPTION_KEY`, `PII_ENCRYPTION_KEY` | AES-256-GCM keys (base64 32-byte) — `python -c \"import secrets,base64; print(base64.b64encode(secrets.token_bytes(32)).decode())\"` |\n| `POSTGRES_*` | DB credentials |\n\n## Default ports\n\n| Service | URL |\n|---------|-----|\n| API | http://localhost:8000 (docs at `/docs`, health at `/health`) |\n| Frontend | http://localhost:5173 |\n| Postgres | localhost:5432 |\n| Redis | localhost:6379 |\n| Flower | http://localhost:5555 (when `make flower`) |\n\n## Conventions and gotchas\n\n- Repo root on this machine is owned by `root`; writing files at the top level needs sudo. The `.claude/` directory is owned by `anas` so Claude Code can write to it freely.\n- Async SQLAlchemy 2.0 throughout the backend — use `AsyncSession`, not the sync API.\n- Celery on Windows native needs `--pool=solo`; prefer Docker or WSL.\n- pgvector requires the `pgvector/pgvector:pg16` image (already wired into compose). Bare Postgres needs `CREATE EXTENSION vector;`.\n- PII handling is non-optional — there's a dedicated compliance test suite (`make test-compliance`) and a `check-pii` audit. Don't log raw complaint text outside the encrypted vault.\n- Pre-commit hooks are installed via `make install`; don't bypass with `--no-verify`.\n\n## More docs\n\n- [hvac-backend/README.md](hvac-backend/README.md) — backend architecture & API reference\n- [hvac-backend/DEMO_SCRIPT.md](hvac-backend/DEMO_SCRIPT.md) — 5-minute spoken demo\n- [hvac-backend/BRANCHING_STRATEGY.md](hvac-backend/BRANCHING_STRATEGY.md) — git workflow\n- [hvac-ml/README.md](hvac-ml/README.md) — ML pipeline internals\n- [hvac-frontend/README.md](hvac-frontend/README.md) — frontend structure\n- [README.md](README.md) — full setup walkthrough (Linux + Windows)\n"}, "9a7a19881271b6002194736d72337b8fe9eb9967": {"t": 1785764769.4540067, "n": 6506, "h": "950c3ff484c3cc2d", "c": "# HVAC Customer Complaint Intelligence System\n\nEnd-to-end platform that ingests HVAC service complaints (English + Hinglish), clusters\nthem by semantic similarity, detects emerging fault patterns, and generates LLM-authored\nadvisories. Goal: compress 6–8 week manual pattern-detection cycles to under 24 hours.\n\n## Repository layout\n\n| Path | Purpose | Stack |\n|------|---------|-------|\n| [hvac-backend/](hvac-backend/) | API + workers + DB | Python 3.11, FastAPI, SQLAlchemy 2.0 async, Alembic, Celery, Redis, Postgres 16 + pgvector |\n| [hvac-ml/](hvac-ml/) | ML pipeline (imported by backend) | sentence-transformers (`paraphrase-multilingual-MiniLM-L12-v2`), UMAP, HDBSCAN, VADER |\n| [hvac-frontend/](hvac-frontend/) | Dashboard | React 18, Vite, Tailwind, react-query, Plotly, Recharts |\n\n**LLM provider is pluggable.** Set `LLM_PROVIDER` in `.env` to one of `deepseek`, `qwen`, or `gemini`. All three are accessed through the OpenAI Python SDK against each provider's compatible-mode endpoint, so the call sites are uniform. The factory lives at [hvac-backend/app/services/llm_client.py](hvac-backend/app/services/llm_client.py) — `get_llm_client() -> (OpenAI, model_name)`. Anthropic is no longer used; ignore any stale `ANTHROPIC_API_KEY` references.\n\n| Provider | Default model | Base URL |\n|----------|--------------|----------|\n| `deepseek` | `deepseek-chat` | `https://api.deepseek.com` |\n| `qwen` | `qwen3-vl-plus` | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` |\n| `gemini` | `gemini-2.5-flash-lite` | `https://generativelanguage.googleapis.com/v1beta/openai/` |\n\nThe legacy `google.generativeai` SDK path is preserved in [hvac-ml/pipeline/labeler.py](hvac-ml/pipeline/labeler.py) for backward compatibility — when the labeler is constructed without an injected `client`/`base_url` it falls back to that path. New call sites should always inject the client from `get_llm_client()`.\n\n## Backend internals\n\n- Entry: [hvac-backend/app/main.py](hvac-backend/app/main.py)\n- HTTP routes: [hvac-backend/app/api/](hvac-backend/app/api/)\n- ORM models: [hvac-backend/app/models/](hvac-backend/app/models/)\n- Pydantic schemas: [hvac-backend/app/schemas/](hvac-backend/app/schemas/)\n- Business logic: [hvac-backend/app/services/](hvac-backend/app/services/)\n- Celery workers: [hvac-backend/app/workers/](hvac-backend/app/workers/) — queues: `embeddings`, `sentiment`, `batch`\n- Migrations: [hvac-backend/alembic/](hvac-backend/alembic/)\n\n## ML pipeline\n\nStage modules in [hvac-ml/pipeline/](hvac-ml/pipeline/): `embedder.py` → `clusterer.py` → `labeler.py` → `sentiment.py` → `trend_detector.py`.\n\n`umap-learn` requires `scikit-learn<1.7` (the `force_all_finite` rename); pyproject pins `scikit-learn==1.6.1` — don't bump it.\n\n## Frontend internals\n\n- Entry: [hvac-frontend/src/main.jsx](hvac-frontend/src/main.jsx), [hvac-frontend/src/App.jsx](hvac-frontend/src/App.jsx)\n- API client: [hvac-frontend/src/api/](hvac-frontend/src/api/)\n- Components: [hvac-frontend/src/components/](hvac-frontend/src/components/)\n- Dev server proxies `/api/*` → `http://localhost:8000`. Override via `VITE_API_BASE_URL` in `hvac-frontend/.env.local`.\n\n## Common commands\n\nRun from each subproject root.\n\n### Backend ([hvac-backend/Makefile](hvac-backend/Makefile))\n\n```bash\nmake dev              # docker compose up --build (full stack: api + workers + pg + redis)\nmake down             # stop stack and drop volumes\nmake migrate          # alembic upgrade head\nmake migration m='...' # autogenerate migration\nmake seed             # synthetic complaints\nmake cluster          # trigger nightly batch cluster job\nmake test             # fast tests (excludes slow + performance)\nmake test-unit        # unit only\nmake test-integ       # integration only\nmake test-compliance  # PII compliance suite (22 tests)\nmake test-slow        # ML quality gates (silhouette, Jaccard)\nmake lint             # ruff check + mypy\nmake format           # ruff format + --fix\nmake check-pii        # PII strip audit\nmake demo-check       # verify_demo_data.py\nmake flower           # Celery monitor at :5555\n```\n\n### ML\n\n```bash\ncd hvac-ml\npytest -m \"not slow\"  # fast\npytest -m slow        # quality gates\n```\n\n### Frontend\n\n```bash\ncd hvac-frontend\nnpm install\nnpm run dev           # :5173\nnpm run build && npm run preview\nnpm run lint\n```\n\n## Required environment\n\nEdit `hvac-backend/.env` (copy from `.env.example`):\n\n| Variable | Purpose |\n|----------|---------|\n| `LLM_PROVIDER` | `deepseek`, `qwen`, or `gemini` — picks which key/model/base-URL trio gets used |\n| `DEEPSEEK_API_KEY` / `QWEN_API_KEY` / `GOOGLE_API_KEY` | At least the active provider's key must be set |\n| `SECRET_KEY` | App signing key (32+ chars) — `python -c \"import secrets; print(secrets.token_hex(32))\"` |\n| `RAW_TEXT_ENCRYPTION_KEY`, `PII_ENCRYPTION_KEY` | AES-256-GCM keys (base64 32-byte) — `python -c \"import secrets,base64; print(base64.b64encode(secrets.token_bytes(32)).decode())\"` |\n| `POSTGRES_*` | DB credentials |\n\n## Default ports\n\n| Service | URL |\n|---------|-----|\n| API | http://localhost:8000 (docs at `/docs`, health at `/health`) |\n| Frontend | http://localhost:5173 |\n| Postgres | localhost:5432 |\n| Redis | localhost:6379 |\n| Flower | http://localhost:5555 (when `make flower`) |\n\n## Conventions and gotchas\n\n- Repo root on this machine is owned by `root`; writing files at the top level needs sudo. The `.claude/` directory is owned by `anas` so Claude Code can write to it freely.\n- Async SQLAlchemy 2.0 throughout the backend — use `AsyncSession`, not the sync API.\n- Celery on Windows native needs `--pool=solo`; prefer Docker or WSL.\n- pgvector requires the `pgvector/pgvector:pg16` image (already wired into compose). Bare Postgres needs `CREATE EXTENSION vector;`.\n- PII handling is non-optional — there's a dedicated compliance test suite (`make test-compliance`) and a `check-pii` audit. Don't log raw complaint text outside the encrypted vault.\n- Pre-commit hooks are installed via `make install`; don't bypass with `--no-verify`.\n\n## More docs\n\n- [hvac-backend/README.md](hvac-backend/README.md) — backend architecture & API reference\n- [hvac-backend/DEMO_SCRIPT.md](hvac-backend/DEMO_SCRIPT.md) — 5-minute spoken demo\n- [hvac-backend/BRANCHING_STRATEGY.md](hvac-backend/BRANCHING_STRATEGY.md) — git workflow\n- [hvac-ml/README.md](hvac-ml/README.md) — ML pipeline internals\n- [hvac-frontend/README.md](hvac-frontend/README.md) — frontend structure\n- [README.md](README.md) — full setup walkthrough (Linux + Windows)\n"}}}}