README_API.md

LinkedIn Sourcing Agent API 🎯

An AI-powered candidate sourcing and scoring system that automatically finds, analyzes, and ranks LinkedIn candidates for job openings.

🚀 Features

• Intelligent Search: Generates optimized search queries for LinkedIn candidate discovery
• Profile Analysis: Extracts and structures candidate data using advanced parsing
• AI Scoring: Multi-dimensional scoring algorithm evaluating education, experience, skills, and cultural fit
• Personalized Outreach: Generates tailored outreach messages highlighting candidate strengths
• RESTful API: Easy integration with existing HR systems and workflows

📡 API Usage

POST /source-candidates

Submit a job description and get ranked candidates with personalized outreach messages.

Request:

{
  "title": "Software Engineer, ML Research",
  "company": "Windsurf",
  "location": "Mountain View, CA",
  "requirements": [
    "Experience with large language models (LLMs)",
    "Strong background in machine learning and AI",
    "PhD or Master's in Computer Science or related field"
  ],
  "description": "We are looking for a talented ML Research Engineer...",
  "max_candidates": 10,
  "confidence_threshold": 0.3
}

Response:

{
  "job_id": "abc123",
  "job_title": "Software Engineer, ML Research",
  "company": "Windsurf",
  "candidates_found": 5,
  "candidates_scored": 5,
  "top_candidates": [
    {
      "name": "John Doe",
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "fit_score": 8.5,
      "confidence": 0.9,
      "adjusted_score": 7.65,
      "key_highlights": [
        "PhD in Computer Science from Stanford",
        "Current: Senior ML Engineer at Google",
        "Skills: LLM, PyTorch, TensorFlow"
      ],
      "outreach_message": "Hi John, I noticed your impressive work with LLMs at Google and think you'd be perfect for our ML Research role at Windsurf...",
      "profile_summary": {
        "name": "John Doe",
        "headline": "Senior ML Engineer | LLM Specialist",
        "current_company": "Google",
        "score_breakdown": {
          "education": 9.5,
          "career_trajectory": 8.0,
          "company_relevance": 9.0,
          "experience_match": 8.5
        }
      }
    }
  ],
  "processing_time": 12.5,
  "status": "completed",
  "timestamp": "2025-07-01T02:30:00Z"
}

🔧 Endpoints

• GET / - API information
• GET /health - Health check
• POST /source-candidates - Main sourcing endpoint
• GET /example - Example request format
• GET /docs - Interactive API documentation

🎯 Scoring Algorithm

The system evaluates candidates across multiple dimensions:

• Education (25%): University prestige, degree relevance, field of study
• Experience Match (30%): Role similarity, industry relevance, skill alignment
• Career Trajectory (20%): Progression, tenure, company quality
• Company Relevance (15%): Similar company experience, industry fit
• Location Match (10%): Geographic compatibility

🚀 Quick Start

1. Visit the API documentation at /docs
2. Try the /example endpoint to see request format
3. Submit a job via /source-candidates
4. Get ranked candidates with personalized messages

🔐 Note

This demo uses mock data for educational purposes. In production, you would need:

• Valid LinkedIn API access
• SerpAPI key for search
• Groq API key for LLM processing

Built with FastAPI, Pydantic, and modern async Python.