@hasna/microservices 0.0.4 → 0.0.6

package/microservices/microservice-hiring/src/lib/scoring.ts

@@ -0,0 +1,206 @@
+/**
+ * AI resume scoring — uses OpenAI or Anthropic to evaluate applicant fit
+ */
+
+import { getApplicant, getJob, updateApplicant } from "../db/hiring.js";
+import type { Applicant, Job } from "../db/hiring.js";
+
+export interface ScoreResult {
+  match_pct: number;
+  strengths: string[];
+  gaps: string[];
+  recommendation: string;
+}
+
+export interface RankEntry {
+  applicant: Applicant;
+  score: ScoreResult;
+}
+
+// ---- Provider abstraction ----
+
+async function callAI(prompt: string): Promise<string> {
+  // Try Anthropic first, then OpenAI
+  const anthropicKey = process.env["ANTHROPIC_API_KEY"];
+  const openaiKey = process.env["OPENAI_API_KEY"];
+
+  if (anthropicKey) {
+    return callAnthropic(anthropicKey, prompt);
+  }
+  if (openaiKey) {
+    return callOpenAI(openaiKey, prompt);
+  }
+
+  throw new Error(
+    "No AI API key found. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable."
+  );
+}
+
+async function callAnthropic(apiKey: string, prompt: string): Promise<string> {
+  const response = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify({
+      model: "claude-sonnet-4-20250514",
+      max_tokens: 1024,
+      messages: [{ role: "user", content: prompt }],
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Anthropic API error ${response.status}: ${text}`);
+  }
+
+  const data = (await response.json()) as {
+    content: Array<{ type: string; text: string }>;
+  };
+  return data.content[0]?.text || "";
+}
+
+async function callOpenAI(apiKey: string, prompt: string): Promise<string> {
+  const response = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: "gpt-4o-mini",
+      messages: [{ role: "user", content: prompt }],
+      max_tokens: 1024,
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`OpenAI API error ${response.status}: ${text}`);
+  }
+
+  const data = (await response.json()) as {
+    choices: Array<{ message: { content: string } }>;
+  };
+  return data.choices[0]?.message?.content || "";
+}
+
+// ---- Scoring ----
+
+function buildScoringPrompt(job: Job, applicant: Applicant): string {
+  const requirements = job.requirements.length
+    ? job.requirements.join(", ")
+    : "No specific requirements listed";
+
+  const applicantInfo = [
+    `Name: ${applicant.name}`,
+    applicant.resume_url ? `Resume: ${applicant.resume_url}` : null,
+    applicant.notes ? `Notes/Summary: ${applicant.notes}` : null,
+    applicant.source ? `Source: ${applicant.source}` : null,
+    applicant.stage ? `Current stage: ${applicant.stage}` : null,
+    Object.keys(applicant.metadata).length > 0
+      ? `Additional info: ${JSON.stringify(applicant.metadata)}`
+      : null,
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  return `You are an expert hiring evaluator. Analyze this applicant against the job requirements and return a JSON assessment.
+
+JOB:
+Title: ${job.title}
+Department: ${job.department || "N/A"}
+Description: ${job.description || "N/A"}
+Requirements: ${requirements}
+Salary Range: ${job.salary_range || "N/A"}
+
+APPLICANT:
+${applicantInfo}
+
+Return ONLY a valid JSON object (no markdown, no code fences) with this exact structure:
+{
+  "match_pct": <number 0-100>,
+  "strengths": ["strength1", "strength2"],
+  "gaps": ["gap1", "gap2"],
+  "recommendation": "<hire/strong_hire/no_hire/maybe> — brief explanation"
+}`;
+}
+
+function parseScoreResponse(text: string): ScoreResult {
+  // Strip markdown code fences if present
+  let cleaned = text.trim();
+  if (cleaned.startsWith("```")) {
+    cleaned = cleaned.replace(/^```(?:json)?\s*\n?/, "").replace(/\n?```\s*$/, "");
+  }
+
+  try {
+    const parsed = JSON.parse(cleaned);
+    return {
+      match_pct: Math.max(0, Math.min(100, Number(parsed.match_pct) || 0)),
+      strengths: Array.isArray(parsed.strengths) ? parsed.strengths : [],
+      gaps: Array.isArray(parsed.gaps) ? parsed.gaps : [],
+      recommendation: String(parsed.recommendation || "Unable to determine"),
+    };
+  } catch {
+    return {
+      match_pct: 0,
+      strengths: [],
+      gaps: [],
+      recommendation: `AI response could not be parsed: ${text.slice(0, 200)}`,
+    };
+  }
+}
+
+export async function scoreApplicant(applicantId: string): Promise<ScoreResult> {
+  const applicant = getApplicant(applicantId);
+  if (!applicant) throw new Error(`Applicant '${applicantId}' not found`);
+
+  const job = getJob(applicant.job_id);
+  if (!job) throw new Error(`Job '${applicant.job_id}' not found`);
+
+  const prompt = buildScoringPrompt(job, applicant);
+  const response = await callAI(prompt);
+  const score = parseScoreResponse(response);
+
+  // Store in applicant metadata
+  const metadata = { ...applicant.metadata, ai_score: score, scored_at: new Date().toISOString() };
+  updateApplicant(applicantId, { metadata });
+
+  return score;
+}
+
+export async function rankApplicants(jobId: string): Promise<RankEntry[]> {
+  const job = getJob(jobId);
+  if (!job) throw new Error(`Job '${jobId}' not found`);
+
+  const applicants = (await import("../db/hiring.js")).listApplicants({ job_id: jobId });
+
+  const results: RankEntry[] = [];
+
+  for (const applicant of applicants) {
+    // Use cached score if available and recent (less than 24h old)
+    const cached = applicant.metadata?.ai_score as ScoreResult | undefined;
+    const cachedAt = applicant.metadata?.scored_at as string | undefined;
+    const isFresh =
+      cachedAt && Date.now() - new Date(cachedAt).getTime() < 24 * 60 * 60 * 1000;
+
+    if (cached && isFresh) {
+      results.push({ applicant, score: cached });
+    } else {
+      const score = await scoreApplicant(applicant.id);
+      // Re-fetch to get updated metadata
+      const updated = getApplicant(applicant.id)!;
+      results.push({ applicant: updated, score });
+    }
+  }
+
+  // Sort by match_pct descending
+  results.sort((a, b) => b.score.match_pct - a.score.match_pct);
+
+  return results;
+}
+
+// Exported for testing
+export { buildScoringPrompt, parseScoreResponse, callAI };

package/microservices/microservice-hiring/src/mcp/index.ts

@@ -26,7 +26,18 @@ import {
   updateInterview,
   addInterviewFeedback,
   deleteInterview,
+  bulkImportApplicants,
+  generateOffer,
+  getHiringForecast,
+  submitStructuredFeedback,
+  bulkReject,
+  getReferralStats,
+  saveJobAsTemplate,
+  createJobFromTemplate,
+  listJobTemplates,
+  deleteJobTemplate,
 } from "../db/hiring.js";
+import { scoreApplicant, rankApplicants } from "../lib/scoring.js";
 
 const server = new McpServer({
   name: "microservice-hiring",
@@ -451,6 +462,240 @@ server.registerTool(
   }
 );
 
+// --- Bulk Import ---
+
+server.registerTool(
+  "bulk_import_applicants",
+  {
+    title: "Bulk Import Applicants",
+    description: "Import applicants from CSV data (columns: name,email,phone,job_id,source,resume_url).",
+    inputSchema: {
+      csv_data: z.string().describe("CSV string with header row"),
+    },
+  },
+  async ({ csv_data }) => {
+    const result = bulkImportApplicants(csv_data);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// --- AI Scoring ---
+
+server.registerTool(
+  "score_applicant",
+  {
+    title: "Score Applicant",
+    description: "AI-score an applicant against job requirements. Returns match percentage, strengths, gaps, and recommendation.",
+    inputSchema: { id: z.string() },
+  },
+  async ({ id }) => {
+    try {
+      const score = await scoreApplicant(id);
+      return { content: [{ type: "text", text: JSON.stringify(score, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: String(err instanceof Error ? err.message : err) }], isError: true };
+    }
+  }
+);
+
+server.registerTool(
+  "rank_applicants",
+  {
+    title: "Rank Applicants",
+    description: "AI-rank all applicants for a job by fit score, sorted best-first.",
+    inputSchema: { job_id: z.string() },
+  },
+  async ({ job_id }) => {
+    try {
+      const ranked = await rankApplicants(job_id);
+      return { content: [{ type: "text", text: JSON.stringify(ranked, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: String(err instanceof Error ? err.message : err) }], isError: true };
+    }
+  }
+);
+
+// --- Offer Letter ---
+
+server.registerTool(
+  "generate_offer",
+  {
+    title: "Generate Offer Letter",
+    description: "Generate a Markdown offer letter for an applicant.",
+    inputSchema: {
+      id: z.string().describe("Applicant ID"),
+      salary: z.number().describe("Annual salary"),
+      start_date: z.string().describe("Start date (YYYY-MM-DD)"),
+      position_title: z.string().optional(),
+      department: z.string().optional(),
+      benefits: z.string().optional(),
+      equity: z.string().optional(),
+      signing_bonus: z.number().optional(),
+    },
+  },
+  async ({ id, salary, start_date, ...rest }) => {
+    try {
+      const letter = generateOffer(id, { salary, start_date, ...rest });
+      return { content: [{ type: "text", text: letter }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: String(err instanceof Error ? err.message : err) }], isError: true };
+    }
+  }
+);
+
+// --- Pipeline Velocity / Forecast ---
+
+server.registerTool(
+  "hiring_forecast",
+  {
+    title: "Hiring Forecast",
+    description: "Estimate days-to-fill based on average time between pipeline stages.",
+    inputSchema: { job_id: z.string() },
+  },
+  async ({ job_id }) => {
+    try {
+      const forecast = getHiringForecast(job_id);
+      return { content: [{ type: "text", text: JSON.stringify(forecast, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: String(err instanceof Error ? err.message : err) }], isError: true };
+    }
+  }
+);
+
+// --- Structured Feedback ---
+
+server.registerTool(
+  "submit_structured_feedback",
+  {
+    title: "Submit Structured Interview Feedback",
+    description: "Submit scored interview feedback with dimensions (technical, communication, culture_fit, etc.).",
+    inputSchema: {
+      id: z.string().describe("Interview ID"),
+      feedback_text: z.string().optional(),
+      technical: z.number().min(1).max(5).optional(),
+      communication: z.number().min(1).max(5).optional(),
+      culture_fit: z.number().min(1).max(5).optional(),
+      problem_solving: z.number().min(1).max(5).optional(),
+      leadership: z.number().min(1).max(5).optional(),
+      overall: z.number().min(1).max(5).optional(),
+    },
+  },
+  async ({ id, feedback_text, ...scores }) => {
+    const interview = submitStructuredFeedback(id, scores, feedback_text);
+    if (!interview) {
+      return { content: [{ type: "text", text: `Interview '${id}' not found.` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(interview, null, 2) }] };
+  }
+);
+
+// --- Bulk Rejection ---
+
+server.registerTool(
+  "bulk_reject",
+  {
+    title: "Bulk Reject Applicants",
+    description: "Bulk reject all applicants for a job matching a specific status.",
+    inputSchema: {
+      job_id: z.string(),
+      status: z.enum(["applied", "screening", "interviewing", "offered"]),
+      reason: z.string().optional(),
+    },
+  },
+  async ({ job_id, status, reason }) => {
+    const result = bulkReject(job_id, status, reason);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// --- Referral Stats ---
+
+server.registerTool(
+  "referral_stats",
+  {
+    title: "Referral Stats",
+    description: "Show conversion rates by applicant source/referral channel.",
+    inputSchema: {},
+  },
+  async () => {
+    const stats = getReferralStats();
+    return { content: [{ type: "text", text: JSON.stringify(stats, null, 2) }] };
+  }
+);
+
+// --- Job Templates ---
+
+server.registerTool(
+  "save_job_template",
+  {
+    title: "Save Job as Template",
+    description: "Save an existing job posting as a reusable template.",
+    inputSchema: {
+      job_id: z.string(),
+      name: z.string().describe("Unique template name"),
+    },
+  },
+  async ({ job_id, name }) => {
+    try {
+      const template = saveJobAsTemplate(job_id, name);
+      return { content: [{ type: "text", text: JSON.stringify(template, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: String(err instanceof Error ? err.message : err) }], isError: true };
+    }
+  }
+);
+
+server.registerTool(
+  "create_job_from_template",
+  {
+    title: "Create Job from Template",
+    description: "Create a new job posting from an existing template.",
+    inputSchema: {
+      template_name: z.string(),
+      title: z.string().optional(),
+      department: z.string().optional(),
+      location: z.string().optional(),
+      salary_range: z.string().optional(),
+    },
+  },
+  async ({ template_name, ...overrides }) => {
+    try {
+      const job = createJobFromTemplate(template_name, overrides);
+      return { content: [{ type: "text", text: JSON.stringify(job, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: String(err instanceof Error ? err.message : err) }], isError: true };
+    }
+  }
+);
+
+server.registerTool(
+  "list_job_templates",
+  {
+    title: "List Job Templates",
+    description: "List all saved job templates.",
+    inputSchema: {},
+  },
+  async () => {
+    const templates = listJobTemplates();
+    return {
+      content: [{ type: "text", text: JSON.stringify({ templates, count: templates.length }, null, 2) }],
+    };
+  }
+);
+
+server.registerTool(
+  "delete_job_template",
+  {
+    title: "Delete Job Template",
+    description: "Delete a job template by ID.",
+    inputSchema: { id: z.string() },
+  },
+  async ({ id }) => {
+    const deleted = deleteJobTemplate(id);
+    return { content: [{ type: "text", text: JSON.stringify({ id, deleted }) }] };
+  }
+);
+
 // --- Start ---
 async function main() {
   const transport = new StdioServerTransport();