amber Copilot

LLM-based, endpoint-grounded student-housing booking assistant - a replacement for amber's manual site copilot. The assistant answers only through confirmed amber API endpoints + a small policy KB, with human-in-the-loop escalation.

Demo/portfolio project. It calls base.amberstudent.com, an undocumented internal-looking host, politely (cached, rate-limited). Not affiliated with amber.

Quick start (Docker)

cp .env.example .env      # add your GROQ_API_KEY
docker compose up --build
# backend :8000  frontend :5173  redis host:6380
curl http://localhost:8000/health   # {"status":"ok"}

Quick start (manual)

cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env       # keep .env inside backend/ for pytest
uvicorn app.main:app --reload --port 8000
# separate terminal:
cd frontend && npm install && npm run dev

Tests

cd backend
pytest -m "not live"     # offline: always pass
pytest -m live           # hits amber API (needs internet); groq test needs GROQ_API_KEY

See CHECKS.md for a full, step-by-step verification guide.

Build status

• Phase 0 - Scaffold, config, endpoint registry
• Phase 1 - amber API client (5 endpoints) + SQLite TTL cache
• Phase 2 - Normalization, canonical schema, policy KB
• Phase 3 - Groq LLM gateway + grounded prompts
• Phase 4 - Agent tools
• Phase 5 - Memory + smart-form
• Phase 6 - Agent loop + SSE /chat
• Phase 7 - Widget UI (MVP finish line)
• Phase 8 - Simulated HITL
• Phase 9 - Voice / i18n / eval / deploy

Layout

backend/app/
  config.py            typed settings (.env)
  main.py              FastAPI + /health
  amber/               registry, client, models, endpoints (Phase 1)
  amber/normalize.py   canonical schema + property_brief (Phase 2)
  store/cache.py       SQLite TTL cache
  store/kb.py          policy FAQ knowledge base (Phase 2)
  agent/llm.py         ChatModel + GroqChatModel (Phase 3)
  agent/prompts.py     grounding system prompt + router prompt (Phase 3)
  data/kb/*.md         FAQ source
frontend/src/          Vite + React + TS widget (Shadow DOM)