CompanionHK 港伴AI

Welcome Page
Home Page
Signup Page
Login Page
Weather Summary
Local Guide
Local Guide Recommendations
Study Buddy
Companionship

Inspiration

Hong Kong is one of the most fast-paced cities in the world — and one of the loneliest. Students face immense academic pressure from the DSE exam system, young professionals deal with isolation in a city of 7.5 million, and everyone navigates a dense urban landscape where finding the right place, the right help, or simply someone to talk to can feel surprisingly hard.

We noticed that existing tools are fragmented: a mental health chatbot here, a maps app there, a tutoring service somewhere else. None of them understand you as a whole person — your mood, your preferences, your language — and none of them speak the way Hong Kongers actually talk. We asked ourselves: what if one companion could support you emotionally, help you explore your city, and coach you through your studies — all in natural Cantonese?

That question became 港伴AI (CompanionHK).

What it does

CompanionHK is a multi-role AI companion with three distinct spaces, each with its own personality, memory, and conversation history:

Companion — A warm, emotionally intelligent friend who listens, validates, and supports. It follows an emotional scaffolding framework (reflect, validate, explore, support) and never rushes to fix things. When it detects crisis signals, it surfaces verified Hong Kong helpline numbers (Samaritans, SPS, Emergency 999) through a safety banner.
Local Guide — A born-and-raised Hong Konger who knows every corner of the city. It combines real-time weather, your current mood, your preferences, and Google Maps data to recommend places that actually fit right now — with MTR directions, cost hints, and rainy-day alternatives.
Study Guide — A patient tutor who uses the Socratic method and understands the DSE exam system. It teaches with active recall, spaced repetition, and the Feynman technique — and pauses academic content to address exam stress when it senses a student is overwhelmed.

The entire app is bilingual and Cantonese-native: write in Cantonese and it replies in colloquial 口語, mix languages and it code-switches naturally.

How we built it

Architecture: We chose a provider-adapter pattern from day one — every external service (LLM, voice, maps, weather, retrieval) sits behind a swappable adapter with a feature flag. This let us wire all five sponsor APIs without coupling our core logic to any single provider.
Frontend: Next.js 16 (App Router) with TypeScript, Tailwind CSS 4, Framer Motion for animations, and Radix UI primitives. The home screen adapts its background to live weather conditions. Each role has its own visual identity (rose for Companion, emerald for Local Guide, indigo for Study Guide). The recommendation flow renders interactive map cards with travel time estimates.
Backend: Python FastAPI with Pydantic models, serving role-aware chat through a single model route with role-specific prompt/policy selection. The orchestration layer supports both a simple runtime and a LangGraph stateful runtime (feature-flagged) with thread checkpoints keyed by (user_id, role, thread_id).
Memory: A hybrid system — Redis holds short-term conversation context with TTL (role-scoped), while PostgreSQL with pgvector stores long-term preferences and semantic retrieval memory. The AI remembers who you are across sessions without silently storing raw sensitive content.
Safety: Not a stretch goal — it's the foundation. A continuous safety monitor scores emotion and crisis risk on every message. High-risk signals adapt the UI tone, inject safety context into prompts, and trigger a banner with verified Hong Kong crisis hotlines. Dangerous requests are refused with calm, supportive language. Safety rules override every other instruction in every role.

Sponsor integrations:

MiniMax powers the primary chat model (MiniMax-M2.5) and safety scoring (MiniMax-M2), plus embedding generation for semantic memory.
ElevenLabs provides high-quality English text-to-speech.
Cantonese.ai provides native Cantonese ASR and TTS.
Exa enriches recommendations with fresh local context (events, trending places, neighbourhood info).
AWS is the full deployment target: Amplify (frontend), ECS Fargate (backend), RDS PostgreSQL (database), ElastiCache Redis (cache), and CloudWatch (observability).
Local data: Google Maps API for place search, routing, and photos. Open-Meteo for real-time weather (no API key required). Recommendations combine all of these with the user's emotion state and preferences.

Challenges we faced

Prompt engineering for three distinct personas was harder than expected. The Companion needed to avoid therapist clichés ("everything happens for a reason") while still being genuinely supportive. The Local Guide had to balance enthusiasm with practical accuracy — recommending a hiking trail during a typhoon would destroy trust instantly. The Study Guide needed to know when to stop teaching and start caring about the student's mental state. Getting these boundaries right required many iterations.

Cantonese is not just "Chinese" — written Cantonese (口語) has its own grammar, vocabulary, and tone that differ significantly from standard written Chinese (書面語). Most LLMs default to Mandarin-flavoured formal Chinese. Tuning the prompts to produce natural, colloquial Cantonese that feels like texting a friend — not reading a government notice — took deliberate prompt design and testing.

Safety without paternalism was a constant design tension. We wanted the app to catch genuine crisis signals and surface help, but not to over-trigger on every expression of frustration or sadness. Balancing sensitivity with respect for the user's autonomy required careful threshold tuning in the safety monitor.

Provider orchestration under time pressure. Wiring five sponsor APIs through adapter interfaces in 24 hours meant every integration had to degrade gracefully. If MiniMax is down, the mock provider keeps chat alive. If ElevenLabs fails, Cantonese.ai takes over (and vice versa). If Google Maps has no results, recommendations still return with district-level guidance. Building this resilience was essential but time-consuming.

Memory scoping across roles introduced subtle bugs. A preference shared in Companion mode ("I love hiking") should inform Local Guide recommendations, but the emotional context of that conversation should not leak. Designing the memory boundary — what crosses roles, what stays private — required careful data modelling.

What we learned

Safety-first design changes everything. When crisis detection is built into the foundation rather than bolted on, it shapes the entire product for the better — from prompt design to UI flow to error handling. Adapter patterns pay for themselves immediately in a hackathon. Being able to swap, disable, or mock any provider without touching core logic saved us hours of debugging.

Cantonese NLP is an underserved space. There is enormous demand for AI that speaks to Hong Kong users in their actual language, and the tooling is catching up fast thanks to providers like Cantonese.ai. Context-aware recommendations are dramatically more useful than generic ones. Combining weather + mood + preferences + real map data transforms "here are some restaurants" into "here's where you should go right now, and here's why."

Emotional AI needs boundaries. The most important thing a companion can do is know what it is not — it is not a therapist, not a doctor, not a replacement for human connection. Being honest about that, while still being genuinely supportive, is the hardest and most important design challenge.