FedMCP - Federal Parliamentary Information

# AI Chat Implementation Status **Last Updated:** 2025-01-04 **Status:** Foundation Complete ✅ | Ready for API Routes & UI --- ## 🎯 Project Overview Implementing AI chat interface for CanadaGPT with: - **Hybrid pricing model**: Profitable quotas + BYOK + usage-based billing - **Multi-provider support**: Anthropic Claude (primary) + OpenAI GPT - **Context-aware prompts**: MP pages, Bill pages, Dashboard, etc. - **Smart quota management**: Free trial → Paid tiers → BYOK for unlimited --- ## ✅ Phase 1: Database & Setup (COMPLETE) ### Database Migration Created **File:** `/supabase/migrations/20250104000000_ai_chat_system.sql` **Tables Created (6):** 1. `user_subscriptions` - Subscription tiers and billing settings 2. `user_api_keys` - Encrypted BYOK keys (AES-256-GCM) 3. `conversations` - Chat threads with context awareness 4. `messages` - Individual messages with token tracking 5. `usage_logs` - Detailed usage for billing 6. `credit_packs` - Pre-purchased credits for pay-as-you-go **PostgreSQL Functions (4):** - `can_user_query(user_id)` - Quota validation - `track_query_usage(...)` - Usage logging & overage billing - `reset_monthly_overages()` - Monthly billing reset (cron) - `cleanup_expired_conversations()` - Daily cleanup (cron) **Features:** - Row-Level Security (RLS) on all tables - Automated triggers for `updated_at` timestamps - Daily quota usage view - Tiered conversation expiration (0/30/90 days) **Documentation:** `/supabase/README.md` --- ## ✅ Phase 2: Dependencies (COMPLETE) ### Installed Packages ```json { "ai": "^5.0.87", // Vercel AI SDK "@anthropic-ai/sdk": "^0.68.0", // Anthropic Claude "openai": "^6.8.0", // OpenAI GPT "react-markdown": "^10.1.0", // Markdown rendering "remark-gfm": "^4.0.1", // GitHub Flavored Markdown "framer-motion": "^12.23.24", // Animations "zustand": "^5.0.8" // State management } ``` --- ## ✅ Phase 3: Type System (COMPLETE) ### TypeScript Types **File:** `/src/lib/types/chat.ts` **Key Types:** - Database types matching SQL schema - `ChatState` & `ChatActions` for state management - `QuotaCheckResult` & `UsageStats` for API responses - `ContextType` for page-aware prompts - `SuggestedPrompt` & `ContextPrompts` for UI **Enums:** - `SubscriptionTier`: free | basic | pro | usage_only - `AIProvider`: anthropic | openai - `MessageRole`: user | assistant | system | function - `ContextType`: general | mp | bill | dashboard | lobbying | spending --- ## ✅ Phase 4: State Management (COMPLETE) ### Zustand Store **File:** `/src/lib/stores/chatStore.ts` **State Management:** - Conversation CRUD operations - Message management with streaming - Quota checking & validation - Usage stats tracking - Context awareness (MP, Bill, Dashboard, etc.) - BYOK key tracking **Optimized Hooks:** - `useChatOpen()` - Toggle chat widget - `useChatMessages()` - Messages & loading state - `useChatInput()` - Input handling & send - `useChatQuota()` - Quota status & usage stats - `useChatContext()` - Page context management **Key Features:** - Automatic quota checking before queries - Streaming message handling - Tiered conversation expiration - Error handling & retry logic --- ## 📋 Phase 5: API Routes (IN PROGRESS) ### Routes to Create #### 1. `/api/chat/route.ts` (Main Chat Endpoint) **Method:** POST **Features:** - Streaming responses with Server-Sent Events - Quota validation before processing - Context injection from page data - Support for both Anthropic & OpenAI - BYOK key detection & usage - Token tracking & cost calculation - Automatic usage logging **Request Body:** ```typescript { conversation_id: string; message: string; context?: { type: ContextType; id?: string; data?: Record<string, any>; }; } ``` **Response:** Server-Sent Events stream ``` data: {"content": "partial response..."} data: {"content": "more content..."} data: {"done": true, "message": {...}} data: [DONE] ``` #### 2. `/api/chat/quota/route.ts` (Quota Check) **Method:** GET **Returns:** ```typescript { can_query: boolean; reason: string; requires_payment: boolean; queries_remaining?: number; resets_at?: string; } ``` #### 3. `/api/chat/usage/route.ts` (Usage Stats) **Method:** GET **Returns:** ```typescript { queries_today: number; queries_this_month: number; tokens_today: number; cost_today: number; overage_amount: number; } ``` --- ## 📋 Phase 6: Chat UI Components (PENDING) ### Components to Build #### 1. Core Components - `ChatMessage.tsx` - Individual message with markdown - `ChatInput.tsx` - Input field with submit - `ChatHistory.tsx` - Scrollable message list - `ChatSuggestions.tsx` - Context-aware prompt buttons - `QuotaDisplay.tsx` - Quota status badge #### 2. Floating Widget - `ChatWidget.tsx` - Main widget container - Keyboard shortcut: `Cmd/Ctrl + K` - States: Collapsed, Expanded, Loading, Error - Fixed position bottom-right - Persists across navigation #### 3. Modals & Overlays - `QuotaWarningModal.tsx` - Daily limit reached - `OverageModal.tsx` - Continue with overage? - `BYOKPromptModal.tsx` - Upgrade to unlimited --- ## 📋 Phase 7: Context Integration (PENDING) ### Pages to Enhance #### MP Detail Page (`/mps/[id]`) **Context:** ```typescript { type: 'mp', id: mp.id, data: { name: mp.name, party: mp.party, riding: mp.riding, recent_bills: mp.sponsored_bills, expenses: mp.total_expenses } } ``` **Suggested Prompts:** - "What bills has this MP sponsored?" - "How does their spending compare to party average?" - "Show me their voting record on climate bills" #### Bill Detail Page (`/bills/[session]/[number]`) **Context:** ```typescript { type: 'bill', id: `${bill.session}/${bill.number}`, data: { number: bill.number, title: bill.title, status: bill.status, sponsor: bill.sponsor.name } } ``` **Suggested Prompts:** - "Summarize this bill in simple terms" - "Who is lobbying on this bill?" - "What's the voting record?" #### Dashboard (`/dashboard`) **Context:** ```typescript { type: 'dashboard', data: { top_spenders: [...], active_bills: count, conflicts: [...] } } ``` **Suggested Prompts:** - "Show me the top spending MPs this quarter" - "What are the most controversial bills?" - "Find conflicts of interest" --- ## 📋 Phase 8: BYOK Management (PENDING) ### API Key Management UI #### Settings Page Enhancement **Route:** `/settings/api-keys` **Features:** - Connect Anthropic Claude key - Connect OpenAI GPT key - Test key validation - Key encryption (AES-256-GCM) - Active/inactive toggle - Last validated timestamp - Validation errors display **Encryption:** ```typescript // Uses Node.js crypto module const cipher = crypto.createCipheriv('aes-256-gcm', ENCRYPTION_KEY, iv); const encrypted = cipher.update(apiKey, 'utf8', 'hex'); const tag = cipher.getAuthTag(); ``` --- ## 💰 Economics Summary ### Pricing Tiers (Final) | Tier | Price | Daily Quota | BYOK | Overages | |------|-------|-------------|------|----------| | **Free** | $0 | 10 lifetime | ❌ | ❌ | | **Basic** | $9.99/mo | 15/day (450/mo) | ✅ Unlimited | $0.025/query | | **Pro** | $29.99/mo | 40/day (1200/mo) | ✅ Unlimited | $0.025/query | | **Usage-Only** | Pay-per-use | 0 included | ✅ Optional | $0.025/query | ### Cost Analysis - **Cost per query:** $0.016 (Claude Sonnet 3.5) - **Revenue per query:** $0.025 (56% profit margin) - **BYOK adoption target:** 40-60% of paid users - **Effective margins:** 44-69% depending on BYOK adoption **Always Profitable:** - Basic full utilization: $9.99 - $7.20 = $2.79 profit/mo - Pro full utilization: $29.99 - $19.20 = $10.79 profit/mo - BYOK users: 90%+ margin (subscription only) --- ## 🔐 Security Features ### API Key Encryption - **Algorithm:** AES-256-GCM - **Storage:** Encrypted key + IV + Auth Tag in database - **Access:** Server-side only, never exposed to client - **Validation:** Test query before storage ### Row-Level Security (RLS) - Users can only access their own data - Enforced at database level - Bypassed only by service role (admin) ### Rate Limiting - Per-user quota checks - IP-based rate limiting (100 requests/hour anonymous) - Exponential backoff for retries --- ## 📊 Success Metrics ### Adoption Targets - [ ] 30% of authenticated users try chat - [ ] 15% become regular users (5+ queries/week) - [ ] 10% convert to paid tiers ### Revenue Targets - [ ] BYOK adoption: 40-60% of paid users - [ ] Average overage: $2-5/mo per Basic user - [ ] Pro tier upgrade rate: 5% of Basic users ### Quality Targets - [ ] 85%+ query accuracy - [ ] <2s average response time - [ ] <5% error rate --- ## 🚀 Next Steps (Priority Order) 1. **Create API Routes** (2-3 hours) - `/api/chat/route.ts` with streaming - `/api/chat/quota/route.ts` - `/api/chat/usage/route.ts` 2. **Build Chat UI Components** (4-6 hours) - Core message components - Floating widget with animations - Quota displays and warnings 3. **Implement Context Integration** (2-3 hours) - Add chat to MP pages - Add chat to Bill pages - Dashboard integration 4. **Build BYOK Management** (2-3 hours) - API key settings page - Key validation & testing - Encryption implementation 5. **Testing & Polish** (2-3 hours) - End-to-end testing - Error handling - Loading states - Responsive design **Total Estimated Time:** 12-18 hours to MVP --- ## 📝 Environment Variables Needed Add to `.env.local`: ```env # Supabase NEXT_PUBLIC_SUPABASE_URL=https://yourproject.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key SUPABASE_SERVICE_ROLE_KEY=your-service-role-key # AI Providers (server-side) ANTHROPIC_API_KEY=your-anthropic-key OPENAI_API_KEY=your-openai-key # Encryption (generate with: openssl rand -hex 32) ENCRYPTION_KEY=your-32-byte-hex-key # Stripe (for billing) STRIPE_SECRET_KEY=your-stripe-secret-key NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your-stripe-publishable-key STRIPE_WEBHOOK_SECRET=your-webhook-secret ``` --- ## 📦 Files Created ### Database - `/supabase/migrations/20250104000000_ai_chat_system.sql` - `/supabase/README.md` ### Types - `/src/lib/types/chat.ts` ### State Management - `/src/lib/stores/chatStore.ts` ### Documentation - `/AI_CHAT_IMPLEMENTATION_PLAN.md` (comprehensive plan) - `/AI_CHAT_IMPLEMENTATION_STATUS.md` (this file) --- ## 🔧 Commands to Run ### 1. Apply Database Migration ```bash # Via Supabase CLI supabase db push --file supabase/migrations/20250104000000_ai_chat_system.sql # Or via Dashboard SQL Editor # Copy contents and execute ``` ### 2. Set Up Cron Jobs (in Supabase) ```sql -- Reset monthly overages (1st of month, midnight UTC) SELECT cron.schedule( 'reset-monthly-overages', '0 0 1 * *', 'SELECT reset_monthly_overages();' ); -- Cleanup expired conversations (daily, 2 AM UTC) SELECT cron.schedule( 'cleanup-expired-conversations', '0 2 * * *', 'SELECT cleanup_expired_conversations();' ); ``` ### 3. Generate Encryption Key ```bash openssl rand -hex 32 ``` --- ## 🎨 Design System Integration Uses existing CanadaGPT design system: - `@canadagpt/design-system` package - TailwindCSS theme variables - Lucide React icons - Framer Motion animations **Colors:** - `accent-red` - Primary actions - `text-primary` - Main text - `text-secondary` - Secondary text - `bg-secondary` - Card backgrounds - `border-subtle` - Borders --- ## ✨ Key Features Implemented 1. **Profitable at all tiers** - Never lose money on queries 2. **Unlimited with BYOK** - Users bring their own API keys 3. **Usage-based billing** - Overage charges when quota exceeded 4. **Context awareness** - Prompts adapt to current page 5. **Streaming responses** - Real-time AI responses 6. **Secure encryption** - AES-256-GCM for API keys 7. **Tiered history** - Conversation retention by tier 8. **Quota enforcement** - Real-time validation --- ## 📞 Support & Resources - **Anthropic Docs:** https://docs.anthropic.com/ - **OpenAI Docs:** https://platform.openai.com/docs - **Vercel AI SDK:** https://sdk.vercel.ai/ - **Supabase Docs:** https://supabase.com/docs - **Implementation Plan:** `/AI_CHAT_IMPLEMENTATION_PLAN.md` --- **Status:** Ready to continue with API routes and UI components! 🚀