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:**
```json
{
  "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:**
```json
{
  "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.