[dev-mubassir]

Summary

• Routes primary text generation (generateReply, summarizeConversation, Auto-reply, Draft AI reply) to Groq Cloud (openai/gpt-oss-20b) with automatic, zero-customer-error fallback to Gemini.
• Reasoning model support with reasoning tag stripping (), concurrency limiter (GROQ_MAX_CONCURRENCY), circuit breaker (5 consecutive failures -> 60s cooldown), and rate-limit headers capture.
• Additive database migration 20261029100000_add_ai_usage_logs tracking token usage, latency, provider, feature, user, and estimated cost (USD & INR). Privacy guaranteed: metadata only, zero DM text or prompt content stored.
• Super Admin Panel controls at /admin/ai: provider order runtime switcher, Groq operational health card, test probe button, date-filtered usage metrics, SVG timeline chart, breakdown tables, top customers table, trace log table, and CSV export.

Files Changed

• backend/prisma/schema.prisma & backend/prisma/migrations/20261029100000_add_ai_usage_logs/migration.sql
• backend/src/lib/ai/groqTextGen.js
• backend/src/lib/ai/aiUsageLogger.js & backend/src/lib/ai/aiPricing.js
• backend/src/lib/settings.js
• backend/src/services/aiService.js (flagged: 1 usage log in classification)
• backend/src/lib/ai/clefClassifier.js (flagged: 1 usage log in classification)
• backend/src/routes/adminAiUsage.js & backend/src/routes/admin.js
• frontend/src/app/admin/ai/page.js & frontend/src/lib/api.js
• backend/tests/groq-textgen.test.js
• .env.example & README.md

Migration Name

• 20261029100000_add_ai_usage_logs

Environment Variables

• GROQ_API_KEY
• GROQ_TEXT_MODEL (default: openai/gpt-oss-20b)
• GROQ_TIMEOUT_MS (default: 15000)
• GROQ_REASONING_EFFORT (default: low)
• GROQ_MAX_CONCURRENCY (default: 10)
• TEXT_PROVIDER_FORCE (kill switch: gemini)
• USD_INR (default: 84)

Test Results

• All 10 validation tests in tests/groq-textgen.test.js passed.
• Full backend regression suite: 87 files passed (1016 passed, 0 failed, 12 skipped).
• Live cloud test against Groq Cloud: openai/gpt-oss-20b responded 200 OK.
• Frontend production build & lint: 0 errors.

Rollback

• Admin UI: Switch text generation provider to Google Gemini in /admin/ai.
• Env kill switch: Set TEXT_PROVIDER_FORCE=gemini.