# Sherpa

> Sherpa is an AI-powered Applicant Tracking System (ATS) built on Laravel. It uses a conversational AI agent to automate the full recruitment lifecycle — from job posting and candidate sourcing to interview scheduling and pipeline management.

## What Sherpa Does

Sherpa replaces form-driven recruiting workflows with a natural language AI agent. Recruiters and hiring managers interact with Sherpa through a chat interface to post jobs, find candidates, launch sourcing campaigns, and schedule interviews — without navigating menus or filling out forms.

**Tagline:** "Your AI Recruiter, Available 24/7"

## Core Capabilities

### AI Agent (Conversational Interface)
Sherpa's AI agent understands recruiter intent and executes multi-step recruiting tasks in response to plain-language instructions. It uses OpenAI's API with a stateless architecture — conversation history is stored locally, not on OpenAI servers, ensuring data privacy.

- Session limit: 45 exchanges per session, 60-minute auto-archive
- Context window: 20 messages of rolling history
- Real-time responses via WebSocket (Pusher)
- Voice input via OpenAI Whisper transcription

### Job Management
- Generate full job posts (title, description, qualifications) from a role name
- Edit or republish jobs by asking in natural language
- Search jobs by title or criteria
- Distribute job postings to LinkedIn via Unipile API and XML job feeds

### Candidate Search & Import
- Semantic search across the entire candidate talent pool, ranked by relevance
- Import candidates directly from LinkedIn profile URLs
- Resume parsing supporting PDF, Word (.docx/.doc), JPEG (OCR), TXT, and Markdown
- PII detection and redaction via Microsoft Presidio
- Email enrichment from LinkedIn profiles via Prospeo.io

### AI Sourcing Campaigns
- Launch automated LinkedIn sourcing campaigns by specifying role and location
- AI finds matching profiles, builds shortlists, and adds candidates to the pipeline automatically
- Campaigns run as background jobs; status is trackable via the agent

### Interview Scheduling
- AI checks connected calendars and suggests available slots
- Books interviews, sends notifications, and avoids scheduling conflicts
- Supports rescheduling and cancellations via conversation
- Integrates with Google Calendar, Microsoft Outlook, and Apple Calendar

### Pipeline Management
- Move candidates between pipeline stages via natural language
- Query pipeline state: "Who applied this week?", "Who's pending a response?"
- Full pipeline summaries in plain language
- Candidate status history and notes

### Company Knowledge Base
- Upload documents (PDF, Word, Excel, PowerPoint, CSV, HTML, code files) to a per-company vector store
- AI crawls your company website to extract brand, culture, and role context
- RAG (Retrieval-Augmented Generation) injects relevant company knowledge into every AI response
- Each company has an isolated vector store — no cross-company data leakage

### Career Site Builder
- Custom branded career pages for companies
- Job listings and candidate application flows

### Video Interviews
- Built-in virtual interview rooms
- Real-time video conferencing for remote hiring

### Screening
- Customizable screening questionnaire templates
- Self-service screening links (token-gated, public access)

## AI Agent Tools

Sherpa's AI agent has access to 27 tools registered in its tool registry:

**Job tools:** validate_job_title, resolve_job_title, create_job_post, edit_job_post, get_job_post, search_jobs

**Candidate tools:** list_applicants, search_candidates, get_candidate_profile, update_candidate_status, add_candidate_to_job, handle_linkedin_url

**Interview tools:** get_upcoming_interviews, suggest_interview_slots, schedule_interview, update_interview, cancel_interview, get_interview_details

**Sourcing tools:** handle_sourcing_campaign, check_active_campaigns

**Company tools:** crawl_company_website, update_company_profile, get_onboarding_status, fetch_company_docs

**Data tools:** run_sql_query, handle_uploaded_document

## Integrations

### Calendar
- Google Calendar (Gmail OAuth)
- Microsoft Outlook / Office 365
- Apple Calendar / iCloud

### LinkedIn
- Profile scraping via Apify (harvestapi/linkedin-profile-scraper)
- Job posting via Unipile API
- LinkedIn OAuth authentication

### AI & LLM
- OpenAI GPT-4o (primary reasoning model)
- OpenAI Whisper (voice-to-text)
- OpenAI Vector Store (per-company RAG)

### Communication
- Email: Mailgun, Amazon SES, SparkPost
- SMS: Twilio
- Real-time: Pusher WebSockets
- Push notifications: Firebase Cloud Messaging

### Data & Enrichment
- Prospeo.io — LinkedIn-to-email enrichment
- Microsoft Presidio — PII detection and redaction
- Apify — Web scraping platform

### Payments
- Stripe, PayPal

## Model Context Protocol (MCP)

Sherpa implements MCP servers for calendar and LinkedIn integration:
- `GmailCalendarServer` — Google Calendar event management, availability checking
- `OutlookCalendarServer` — Microsoft Outlook calendar integration
- `AppleCalendarServer` — Apple Calendar integration
- `LinkedInScraperServer` — LinkedIn profile extraction via Apify
- `ApifyServer` — General web scraping via Apify cloud

MCP transport layers: REST, HTTP, STDIO

## Technical Stack

- **Backend:** Laravel 12, PHP 8.3+
- **AI:** OpenAI Responses API (stateless), OpenAI Assistants API
- **Frontend:** Vue.js 2, Bootstrap 4, jQuery
- **Database:** MySQL
- **Queue:** Redis + Laravel Queue (background sourcing campaigns, resume parsing)
- **Auth:** Laravel Passport (API), Laravel Socialite (OAuth)
- **Vector Search:** OpenAI Vector Store with per-company isolation

## Target Users

- **Recruiters** — Automate sourcing, screening, and scheduling
- **Hiring Managers** — Manage pipelines and interviews via conversation
- **HR Departments** — Oversee the full recruitment process
- **Companies** — From startups to enterprises needing faster time-to-hire

## Compliance & Privacy

- GDPR-ready data scoping (data isolated per company)
- PII redaction from resumes before storage
- Cookie consent management
- Stateless AI architecture — no conversation data stored on OpenAI servers
- Multi-language support: English, French, Spanish

## Frequently Asked Questions

**What is Sherpa?**
Sherpa is an AI-powered ATS that lets recruiters manage the entire hiring process through a conversational AI agent. Instead of navigating forms and menus, users tell Sherpa what they need in plain language and it executes the task.

**How does Sherpa find candidates?**
Sherpa searches your existing talent pool using semantic similarity, ranks candidates by relevance, and can also launch AI-driven sourcing campaigns that find new candidates on LinkedIn automatically.

**Does Sherpa integrate with my calendar?**
Yes. Sherpa connects to Google Calendar, Microsoft Outlook, and Apple Calendar. It checks availability, suggests slots, and books interviews automatically.

**Is candidate data kept private?**
Yes. Each company has its own isolated vector store and data scope. Sherpa uses a stateless AI architecture so conversation data is stored in your own database, not on OpenAI's servers.

**What file formats does Sherpa support for resumes?**
PDF, Word (.docx, .doc), JPEG/JPG (via OCR), TXT, and Markdown.

**Can Sherpa post jobs to LinkedIn?**
Yes, via the Unipile API integration. Jobs can also be distributed via XML feeds to multiple job boards.

**Does Sherpa support voice input?**
Yes. Users can send voice messages to the AI agent; Sherpa transcribes them using OpenAI Whisper.