evaldoc 1.0.0

package/functions/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "evaldoc-functions",
+  "private": true,
+  "main": "src/index.js",
+  "engines": {
+    "node": "20"
+  },
+  "scripts": {
+    "lint": "echo 'no lint configured'",
+    "serve": "firebase emulators:start --only functions,firestore,hosting",
+    "deploy": "firebase deploy --only functions"
+  },
+  "dependencies": {
+    "firebase-admin": "^12.2.0",
+    "firebase-functions": "^5.1.0",
+    "openai": "^4.20.0",
+    "@google/generative-ai": "^0.1.3",
+    "dotenv": "^16.3.1"
+  }
+}

package/functions/src/analytics.js

@@ -0,0 +1,101 @@
+const admin = require("firebase-admin");
+
+function getDateKey(date = new Date()) {
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(date.getUTCDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function getMonthKey(date = new Date()) {
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  return `${year}-${month}`;
+}
+
+function extractKeywords(message) {
+  const text = String(message || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ");
+  const stop = new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "that",
+    "this",
+    "from",
+    "have",
+    "what",
+    "when",
+    "where",
+    "your",
+    "you",
+    "are",
+    "can",
+    "how",
+    "does",
+    "about"
+  ]);
+  const words = text
+    .split(/\s+/)
+    .filter((word) => word.length > 3 && !stop.has(word));
+  return words.slice(0, 2);
+}
+
+async function incrementAnalytics({ providerId, sessionId, escalated, satisfaction, topicKey, message }) {
+  const db = admin.firestore();
+  const dateKey = getDateKey();
+  const monthKey = getMonthKey();
+  const dailyRef = db
+    .collection("providers")
+    .doc(providerId)
+    .collection("analyticsDaily")
+    .doc(dateKey);
+
+  const updates = {
+    chatCount: admin.firestore.FieldValue.increment(1),
+    updatedAt: admin.firestore.FieldValue.serverTimestamp()
+  };
+
+  // Track unique sessions per day using a sub-field set
+  if (sessionId) {
+    updates[`sessions.${sessionId}`] = true;
+  }
+
+  if (escalated) {
+    updates.escalationCount = admin.firestore.FieldValue.increment(1);
+  }
+  if (typeof satisfaction === "number") {
+    updates.satisfactionSum = admin.firestore.FieldValue.increment(satisfaction);
+    updates.satisfactionCount = admin.firestore.FieldValue.increment(1);
+  }
+  if (topicKey) {
+    updates[`topicCounts.${topicKey}`] = admin.firestore.FieldValue.increment(1);
+  }
+  const keywords = extractKeywords(message);
+  keywords.forEach((word) => {
+    updates[`questionBuckets.${word}`] = admin.firestore.FieldValue.increment(1);
+  });
+
+  const providerRef = db.collection("providers").doc(providerId);
+  const providerUpdates = {
+    monthlyChatCount: admin.firestore.FieldValue.increment(1),
+    monthlyChatCountMonth: monthKey,
+    totalChatCount: admin.firestore.FieldValue.increment(1),
+    updatedAt: admin.firestore.FieldValue.serverTimestamp()
+  };
+  if (escalated) {
+    providerUpdates.totalEscalationCount = admin.firestore.FieldValue.increment(1);
+  }
+
+  const batch = db.batch();
+  batch.set(dailyRef, updates, { merge: true });
+  batch.set(providerRef, providerUpdates, { merge: true });
+  await batch.commit();
+}
+
+module.exports = {
+  incrementAnalytics,
+  getMonthKey
+};

package/functions/src/audit.js

@@ -0,0 +1,28 @@
+const admin = require('firebase-admin');
+
+/**
+ * HIPAA-compliant audit logging.
+ * Logs access and modification events to Firestore auditLog collection.
+ *
+ * Every entry records: who, what, when, and the outcome.
+ */
+async function logAuditEvent({ action, actorId, actorType, resourceType, resourceId, outcome, meta }) {
+  try {
+    const db = admin.firestore();
+    await db.collection('auditLog').add({
+      action,
+      actorId: actorId || 'system',
+      actorType: actorType || 'system',
+      resourceType,
+      resourceId: resourceId || null,
+      outcome: outcome || 'success',
+      meta: meta || {},
+      timestamp: admin.firestore.FieldValue.serverTimestamp()
+    });
+  } catch (err) {
+    // Audit logging must never crash the application
+    console.error('[Audit] Failed to write audit log:', err.message);
+  }
+}
+
+module.exports = { logAuditEvent };

package/functions/src/auth.js

@@ -0,0 +1,19 @@
+const admin = require("firebase-admin");
+
+async function verifyAuthHeader(authHeader) {
+  if (!authHeader || !authHeader.startsWith("Bearer ")) {
+    return null;
+  }
+
+  const token = authHeader.slice("Bearer ".length);
+
+  try {
+    return await admin.auth().verifyIdToken(token);
+  } catch (err) {
+    return null;
+  }
+}
+
+module.exports = {
+  verifyAuthHeader
+};

package/functions/src/drafts.js

@@ -0,0 +1,128 @@
+const OpenAI = require('openai');
+const { GoogleGenerativeAI } = require('@google/generative-ai');
+
+/**
+ * AI-Drafted Doctor Responses Module
+ *
+ * When a conversation is classified as needs_review or urgent,
+ * generates a suggested response for the doctor to review, edit, and send.
+ */
+
+/**
+ * Generate a draft doctor response for a conversation
+ */
+async function generateDoctorDraft({ messages, provider, topic, triageCategory, doctorExamples }) {
+  const providerName = provider.displayName || 'Doctor';
+  const specialty = provider.specialty || 'healthcare';
+
+  // Build conversation summary from recent messages
+  const recentMessages = (messages || []).slice(-8);
+  const conversationSummary = recentMessages.map(msg => {
+    const role = msg.role === 'user' || msg.role === 'patient' ? 'Patient' : 'AI Assistant';
+    return `${role}: ${(msg.content || msg.message || '').substring(0, 300)}`;
+  }).join('\n');
+
+  // Find the last patient message
+  const lastPatientMsg = [...recentMessages].reverse().find(
+    m => m.role === 'user' || m.role === 'patient'
+  );
+  const patientQuestion = lastPatientMsg
+    ? (lastPatientMsg.content || lastPatientMsg.message || '')
+    : '';
+
+  // Build doctor examples section
+  let examplesSection = '';
+  if (doctorExamples && doctorExamples.length > 0) {
+    examplesSection = `\n\nHere are examples of how ${providerName} has responded to similar questions previously. Match their tone and style:\n`;
+    doctorExamples.slice(0, 3).forEach((ex, i) => {
+      examplesSection += `\nExample ${i + 1}:\nPatient asked: ${ex.patientMessage}\nDoctor replied: ${ex.doctorResponse}\n`;
+    });
+  }
+
+  const systemPrompt = `You are drafting a response for ${providerName}, a ${specialty} provider, to send to their patient. The doctor will review and edit your draft before sending it.
+
+GUIDELINES:
+- Write as if you ARE the doctor (first person: "I recommend...", "In my experience...")
+- Be specific and clinically accurate for a ${specialty} context
+- Address the patient's actual question directly
+- Keep it professional but warm - match a real doctor's communication style
+- Include any relevant follow-up steps or recommendations
+- If the patient's concern is urgent (triage: ${triageCategory}), acknowledge the urgency
+- Length: 2-4 sentences for simple questions, 4-6 for complex ones
+- Do NOT include disclaimers about being an AI - this will be sent as the doctor's own words
+${examplesSection}
+
+Topic context: ${topic || 'general health'}`;
+
+  const userPrompt = `Draft a doctor response for this conversation:\n\n${conversationSummary}\n\nThe patient's key question/concern: "${patientQuestion.substring(0, 500)}"`;
+
+  try {
+    const draft = await callDraftLLM(systemPrompt, userPrompt);
+    return {
+      draft: draft,
+      generatedAt: new Date().toISOString(),
+      status: 'pending'
+    };
+  } catch (err) {
+    console.error('[Drafts] LLM draft generation failed:', err.message);
+    return null;
+  }
+}
+
+/**
+ * Call LLM for draft generation - DeepSeek primary (better quality), Gemini fallback
+ */
+async function callDraftLLM(systemPrompt, userPrompt) {
+  // Try DeepSeek first (better quality for medical drafts)
+  if (process.env.DEEPSEEK_API_KEY) {
+    try {
+      const client = new OpenAI({
+        apiKey: process.env.DEEPSEEK_API_KEY,
+        baseURL: 'https://api.deepseek.com'
+      });
+
+      const response = await client.chat.completions.create({
+        model: 'deepseek-chat',
+        messages: [
+          { role: 'system', content: systemPrompt },
+          { role: 'user', content: userPrompt }
+        ],
+        max_tokens: 500,
+        temperature: 0.3
+      });
+
+      return response.choices[0].message.content.trim();
+    } catch (err) {
+      console.error('[Drafts] DeepSeek failed:', err.message);
+    }
+  }
+
+  // Fallback to Gemini
+  if (process.env.GEMINI_API_KEY) {
+    try {
+      const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
+      const model = genAI.getGenerativeModel({
+        model: 'gemini-2.5-flash',
+        systemInstruction: systemPrompt
+      });
+
+      const result = await model.generateContent({
+        contents: [{ role: 'user', parts: [{ text: userPrompt }] }],
+        generationConfig: {
+          maxOutputTokens: 500,
+          temperature: 0.3
+        }
+      });
+
+      return result.response.text().trim();
+    } catch (err) {
+      console.error('[Drafts] Gemini failed:', err.message);
+    }
+  }
+
+  throw new Error('No LLM available for draft generation');
+}
+
+module.exports = {
+  generateDoctorDraft
+};

package/functions/src/feedback.js

@@ -0,0 +1,164 @@
+const admin = require('firebase-admin');
+
+/**
+ * Doctor Response Feedback Loop Module
+ *
+ * When a doctor responds (or accepts/edits an AI draft), this module:
+ * 1. Captures the doctor's response as an "example" linked to the patient question
+ * 2. Retrieves relevant examples for future AI prompt injection
+ *
+ * This gives the AI the doctor's "voice" without model fine-tuning.
+ */
+
+/**
+ * Capture a doctor's response as a training example
+ */
+async function captureDoctorExample({
+  doctorId,
+  threadId,
+  topic,
+  patientMessage,
+  doctorResponse,
+  wasAiDraft,
+  aiDraftOriginal
+}) {
+  const db = admin.firestore();
+
+  // Calculate edit distance ratio if draft was edited
+  let editDistance = null;
+  if (wasAiDraft && aiDraftOriginal) {
+    editDistance = calculateEditRatio(aiDraftOriginal, doctorResponse);
+  }
+
+  const example = {
+    threadId,
+    topic: topic || 'general_health_info',
+    patientMessage: (patientMessage || '').substring(0, 500),
+    doctorResponse: (doctorResponse || '').substring(0, 1000),
+    wasAiDraft: wasAiDraft || false,
+    aiDraftOriginal: wasAiDraft ? (aiDraftOriginal || '').substring(0, 1000) : null,
+    editDistance,
+    createdAt: admin.firestore.FieldValue.serverTimestamp()
+  };
+
+  const ref = await db
+    .collection('providers')
+    .doc(doctorId)
+    .collection('doctorExamples')
+    .add(example);
+
+  console.log(`[Feedback] Captured doctor example ${ref.id} for doctor ${doctorId}`);
+
+  // Update the thread to mark feedback was processed
+  await db.collection('threads').doc(threadId).update({
+    doctorResponseFedBack: true,
+    feedbackProcessedAt: admin.firestore.FieldValue.serverTimestamp()
+  }).catch(err => console.error('[Feedback] Failed to update thread:', err.message));
+
+  return { id: ref.id, ...example };
+}
+
+/**
+ * Retrieve relevant doctor examples for prompt injection
+ *
+ * Fetches the most recent examples from this doctor that match the topic,
+ * to be injected into the AI system prompt as few-shot examples.
+ */
+async function retrieveRelevantExamples({ doctorId, topic, limit = 3 }) {
+  const db = admin.firestore();
+
+  // First try topic-specific examples
+  let snapshot = await db
+    .collection('providers')
+    .doc(doctorId)
+    .collection('doctorExamples')
+    .where('topic', '==', topic || 'general_health_info')
+    .orderBy('createdAt', 'desc')
+    .limit(limit)
+    .get();
+
+  let examples = snapshot.docs.map(doc => ({ id: doc.id, ...doc.data() }));
+
+  // If not enough topic-specific examples, fill with recent general examples
+  if (examples.length < limit) {
+    const remaining = limit - examples.length;
+    const existingIds = new Set(examples.map(e => e.id));
+
+    const generalSnapshot = await db
+      .collection('providers')
+      .doc(doctorId)
+      .collection('doctorExamples')
+      .orderBy('createdAt', 'desc')
+      .limit(remaining + examples.length) // fetch extra to account for dupes
+      .get();
+
+    generalSnapshot.docs.forEach(doc => {
+      if (!existingIds.has(doc.id) && examples.length < limit) {
+        examples.push({ id: doc.id, ...doc.data() });
+      }
+    });
+  }
+
+  return examples;
+}
+
+/**
+ * Calculate a simple edit distance ratio between two strings
+ * Returns 0.0 (identical) to 1.0 (completely different)
+ */
+function calculateEditRatio(original, edited) {
+  if (!original || !edited) return 1.0;
+  if (original === edited) return 0.0;
+
+  const maxLen = Math.max(original.length, edited.length);
+  if (maxLen === 0) return 0.0;
+
+  // Simple character-level difference approximation
+  let changes = 0;
+  const minLen = Math.min(original.length, edited.length);
+
+  for (let i = 0; i < minLen; i++) {
+    if (original[i] !== edited[i]) changes++;
+  }
+  changes += Math.abs(original.length - edited.length);
+
+  return Math.min(1.0, changes / maxLen);
+}
+
+/**
+ * Get feedback statistics for a doctor
+ */
+async function getFeedbackStats({ doctorId }) {
+  const db = admin.firestore();
+
+  const snapshot = await db
+    .collection('providers')
+    .doc(doctorId)
+    .collection('doctorExamples')
+    .orderBy('createdAt', 'desc')
+    .limit(100)
+    .get();
+
+  const examples = snapshot.docs.map(doc => doc.data());
+
+  const totalExamples = examples.length;
+  const aiDraftBased = examples.filter(e => e.wasAiDraft).length;
+  const manualResponses = totalExamples - aiDraftBased;
+  const avgEditDistance = aiDraftBased > 0
+    ? examples.filter(e => e.wasAiDraft && e.editDistance !== null)
+        .reduce((sum, e) => sum + e.editDistance, 0) / aiDraftBased
+    : null;
+
+  return {
+    totalExamples,
+    aiDraftBased,
+    manualResponses,
+    avgEditDistance: avgEditDistance !== null ? Math.round(avgEditDistance * 100) / 100 : null
+  };
+}
+
+module.exports = {
+  captureDoctorExample,
+  retrieveRelevantExamples,
+  getFeedbackStats
+};

package/functions/src/firebase-init.js

@@ -0,0 +1,29 @@
+const admin = require('firebase-admin');
+
+/**
+ * Shared Firebase Admin initialization.
+ * Ensures a single admin instance across server.js and Cloud Functions.
+ *
+ * Usage:
+ *   const { admin, db } = require('./firebase-init');
+ */
+function initializeFirebase(options = {}) {
+  if (admin.apps.length) {
+    return { admin, db: admin.firestore() };
+  }
+
+  if (options.credential) {
+    admin.initializeApp({
+      credential: options.credential,
+      projectId: options.projectId || process.env.PROJECT_ID || 'evaldocplatform'
+    });
+  } else {
+    admin.initializeApp({
+      projectId: options.projectId || process.env.PROJECT_ID || 'evaldocplatform'
+    });
+  }
+
+  return { admin, db: admin.firestore() };
+}
+
+module.exports = { admin, initializeFirebase };

package/functions/src/i18n.js

@@ -0,0 +1,134 @@
+/**
+ * i18n.js — Localization module for safety-critical patient-facing text.
+ *
+ * Self-contained: no dependencies on safety.js or topics.js. English is the
+ * source of truth; missing locales or keys gracefully fall back to English.
+ *
+ * Intended to be wired into safety.js (refusalMessage/escalationMessage) and
+ * topics.js (per-topic disclaimers) later without breaking existing behavior.
+ */
+
+// Supported base locales. The provider `locale` field should normalize to one
+// of these via normalizeLocale().
+const SUPPORTED_LOCALES = ['en', 'es', 'fr', 'de', 'pt', 'ar'];
+
+const DEFAULT_LOCALE = 'en';
+
+/**
+ * Translation table. Every key MUST exist in every supported locale.
+ * English is authoritative; other locales are natural translations of the
+ * same meaning, preserving the safety/medical-disclaimer intent.
+ */
+const MESSAGES = {
+  en: {
+    disclaimer_footer:
+      'This is general information, not medical advice. Consult a licensed clinician.',
+    refusal:
+      "I can't help with that. Please consult a licensed clinician for personalized medical advice.",
+    escalation:
+      'This may be urgent. Please seek emergency care or contact your local emergency number immediately.',
+    emergency_banner:
+      'If this is an emergency, call your local emergency number now.'
+  },
+  es: {
+    disclaimer_footer:
+      'Esta es información general, no asesoramiento médico. Consulte a un profesional sanitario autorizado.',
+    refusal:
+      'No puedo ayudar con eso. Consulte a un profesional sanitario autorizado para obtener asesoramiento médico personalizado.',
+    escalation:
+      'Esto podría ser urgente. Busque atención de emergencia o llame de inmediato al número de emergencias local.',
+    emergency_banner:
+      'Si se trata de una emergencia, llame ahora al número de emergencias local.'
+  },
+  fr: {
+    disclaimer_footer:
+      "Ceci est une information générale, et non un avis médical. Consultez un professionnel de santé agréé.",
+    refusal:
+      "Je ne peux pas vous aider avec cela. Veuillez consulter un professionnel de santé agréé pour obtenir un avis médical personnalisé.",
+    escalation:
+      "Cela peut être urgent. Veuillez consulter des soins d'urgence ou appeler immédiatement votre numéro d'urgence local.",
+    emergency_banner:
+      "En cas d'urgence, appelez immédiatement votre numéro d'urgence local."
+  },
+  de: {
+    disclaimer_footer:
+      'Dies sind allgemeine Informationen und keine medizinische Beratung. Wenden Sie sich an eine zugelassene medizinische Fachkraft.',
+    refusal:
+      'Dabei kann ich nicht helfen. Bitte wenden Sie sich für eine persönliche medizinische Beratung an eine zugelassene medizinische Fachkraft.',
+    escalation:
+      'Dies könnte dringend sein. Bitte suchen Sie sofort eine Notaufnahme auf oder rufen Sie umgehend Ihre örtliche Notrufnummer an.',
+    emergency_banner:
+      'Wenn dies ein Notfall ist, rufen Sie jetzt Ihre örtliche Notrufnummer an.'
+  },
+  pt: {
+    disclaimer_footer:
+      'Estas são informações gerais, não aconselhamento médico. Consulte um profissional de saúde licenciado.',
+    refusal:
+      'Não posso ajudar com isso. Por favor, consulte um profissional de saúde licenciado para obter aconselhamento médico personalizado.',
+    escalation:
+      'Isto pode ser urgente. Procure atendimento de emergência ou ligue imediatamente para o número de emergência local.',
+    emergency_banner:
+      'Se isto for uma emergência, ligue agora para o número de emergência local.'
+  },
+  ar: {
+    disclaimer_footer:
+      'هذه معلومات عامة وليست استشارة طبية. يُرجى استشارة طبيب مرخّص.',
+    refusal:
+      'لا أستطيع المساعدة في ذلك. يُرجى استشارة طبيب مرخّص للحصول على استشارة طبية مخصّصة.',
+    escalation:
+      'قد يكون هذا أمرًا عاجلاً. يُرجى طلب الرعاية الطارئة أو الاتصال برقم الطوارئ المحلي فورًا.',
+    emergency_banner:
+      'إذا كانت هذه حالة طارئة، فاتصل الآن برقم الطوارئ المحلي.'
+  }
+};
+
+/**
+ * Normalize an arbitrary locale tag to a supported base locale.
+ * Examples: 'en-US' -> 'en', 'EN' -> 'en', 'pt_BR' -> 'pt', 'xx' -> 'en',
+ * null/undefined/'' -> 'en'.
+ *
+ * @param {string} locale
+ * @returns {string} a supported locale code
+ */
+function normalizeLocale(locale) {
+  if (typeof locale !== 'string' || locale.trim() === '') {
+    return DEFAULT_LOCALE;
+  }
+  // Take the primary subtag before any region separator ('-' or '_').
+  const base = locale.trim().toLowerCase().split(/[-_]/)[0];
+  return SUPPORTED_LOCALES.includes(base) ? base : DEFAULT_LOCALE;
+}
+
+/**
+ * Translate a key into the given locale, falling back to English when the
+ * locale is unsupported or the key is missing in that locale.
+ *
+ * @param {string} key    a key present in MESSAGES.en
+ * @param {string} locale a locale tag (will be normalized)
+ * @returns {string} the localized string, or '' if the key does not exist at all
+ */
+function t(key, locale) {
+  const normalized = normalizeLocale(locale);
+  const localeTable = MESSAGES[normalized] || MESSAGES[DEFAULT_LOCALE];
+
+  if (localeTable && Object.prototype.hasOwnProperty.call(localeTable, key)) {
+    return localeTable[key];
+  }
+  // Fall back to English for a missing key in a non-English locale.
+  if (
+    MESSAGES[DEFAULT_LOCALE] &&
+    Object.prototype.hasOwnProperty.call(MESSAGES[DEFAULT_LOCALE], key)
+  ) {
+    return MESSAGES[DEFAULT_LOCALE][key];
+  }
+  // Unknown key entirely.
+  return '';
+}
+
+module.exports = {
+  SUPPORTED_LOCALES,
+  DEFAULT_LOCALE,
+  MESSAGES,
+  normalizeLocale,
+  t
+};

package/functions/src/limits.js

@@ -0,0 +1,27 @@
+const { getMonthKey } = require("./analytics");
+
+async function checkMonthlyLimit({ providerDoc }) {
+  const data = providerDoc.data();
+  const limit = data.monthlyChatLimit;
+  if (!limit || limit <= 0) {
+    return { allowed: true };
+  }
+
+  const currentMonth = getMonthKey();
+  const storedMonth = data.monthlyChatCountMonth;
+  const currentCount = storedMonth === currentMonth ? data.monthlyChatCount || 0 : 0;
+  const resetNeeded = storedMonth && storedMonth !== currentMonth;
+
+  if (currentCount >= limit) {
+    return {
+      allowed: false,
+      message: "This provider has reached their monthly chat limit. Please try again next month."
+    };
+  }
+
+  return { allowed: true, resetNeeded, currentMonth };
+}
+
+module.exports = {
+  checkMonthlyLimit
+};