talentmatcher

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 🏗️ Talent Matcher Agent

AI-powered system for automatically matching rejected candidates to alternative open positions.

## 🎯 Overview

When a candidate is rejected for a position, this system automatically:
1. Parses their CV using Gemini AI
2. Generates embeddings for skills, experience, and overall profile
3. Searches for similar open positions using pgvector
4. Consolidates and ranks matches
5. Generates a detailed analysis memo for recruiters

## 🚀 Tech Stack

- **Frontend**: Next.js 14 (App Router), TypeScript, Tailwind CSS
- **Backend**: Next.js API Routes, BullMQ workers
- **Database**: Supabase (PostgreSQL + pgvector)
- **AI**: Google Gemini 2.0 (CV parsing, embeddings, analysis)
- **Workflow**: LangGraph (parallel execution orchestration)
- **Queue**: BullMQ + Redis (background job processing)

## 📋 Prerequisites

- Node.js 18+ and npm
- Docker (for Redis)
- Supabase account
- Google Gemini API key

## 🛠️ Setup

### 1. Install Dependencies

```bash
npm install
```

### 2. Setup Supabase

1. Create a new project at [supabase.com](https://supabase.com)
2. Run the migration from `supabase-migration.sql` in the SQL Editor
3. Note your Project URL, anon key, and service_role key

### 3. Configure Environment Variables

Copy `.env.example` to `.env.local`:

```bash
cp .env.example .env.local
```

Fill in your credentials:

```env
# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Gemini
GEMINI_API_KEY=your-gemini-api-key

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
NODE_ENV=development
```

### 4. Start Redis

```bash
docker-compose up -d
```

### 5. Start Development Services

**Quick Start (Recommended):**
```bash
npm run dev:concurrent  # Starts all services at once with color-coded output
```

**Individual Services:**
```bash
# Terminal 1: Next.js server
npm run dev

# Terminal 2: Workflow worker
npm run worker:workflow

# Terminal 3: Job indexing worker
npm run worker:indexing
```

Visit [http://localhost:3000](http://localhost:3000)

### 6. Setup Claude Code Infrastructure (Optional but Recommended)

The project includes comprehensive Claude Code development tools:

```bash
# Initialize project management
/pm:init

# List available commands
/pm:help

# Show current development status
/pm:status
```

For detailed setup, see the [Developer Guide](https://github.com/majesteitbart/talentmatcher/blob/HEAD/docs/DEVELOPER_GUIDE.md).

## 📡 API Endpoints

### Reject Candidate & Trigger Matching

```bash
POST /api/candidates/reject
Content-Type: application/json

{
  "candidate_id": "uuid",
  "application_id": "uuid",
  "rejection_reason": "Not enough experience" 
}
```

### Check Workflow Status

```bash
GET /api/workflow/status/[workflow_execution_id]
```

### Index Jobs for Vector Search

```bash
POST /api/jobs/index
Content-Type: application/json

{
  "company_id": "uuid",
  "job_ids": ["uuid1", "uuid2"] // optional, indexes all active jobs if omitted
}
```

## 🔄 Workflow Architecture

The matching workflow uses LangGraph for orchestration:

```
START
  ↓
Parse CV (Gemini)
  ↓
  ├── Retrieve by Skills (parallel)
  ├── Retrieve by Experience (parallel)
  └── Retrieve by Profile (parallel)
  ↓
Consolidate Matches (weighted scoring)
  ↓
Generate Analysis (Gemini)
  ↓
END
```

### Key Features:

- **Parallel Execution**: Skills, experience, and profile searches run simultaneously
- **Weighted Scoring**: Skills (40%), Experience (35%), Profile (25%)
- **Multi-source Boost**: Jobs matching multiple criteria get a 5% boost per source
- **Graceful Degradation**: Workflow continues even if some retrievers fail

## 📊 Database Schema

Key tables:
- `companies` - Company information
- `jobs` - Job postings
- `job_embeddings` - Vector embeddings for semantic search
- `candidates` - Candidate profiles
- `parsed_cvs` - Structured CV data
- `applications` - Job applications
- `workflow_executions` - LangGraph workflow runs
- `match_results` - Matched jobs with scores

## 🤖 Claude Code Development Infrastructure

This project includes a comprehensive Claude Code development ecosystem with specialized agents and tools.

### Key Features

- **9 Specialized Agents**: Code analysis, testing, documentation, design review, and more
- **50+ Project Management Commands**: Epic/issue tracking, PRD management, workflow automation
- **Automated Testing**: Comprehensive test execution with real services (no mocking)
- **Smart Documentation**: Auto-generated and updated documentation
- **Epic-Based Development**: Organize work around large features rather than individual issues

### Quick Commands

```bash
# Project Management
/pm:init                    # Initialize new epic
/pm:status                 # Show current work status
/pm:next                   # Get next task
/pm:standup                # Generate standup report

# Development Workflow
/review                    # Code review mode
/testing:run               # Run tests with analysis
/commit                    # Smart commit with validation
/prompt <task>             # Get AI assistance

# Get Help
/pm:help                   # List all available commands
```

### Agent Coordination

For complex tasks, agents work together automatically:

```bash
# Example: Add new feature
Task agent_type="workflow-orchestrator" description="Add user authentication"
```

This will coordinate multiple agents to:
1. Analyze requirements
2. Create implementation plan
3. Build the feature
4. Write tests
5. Update documentation
6. Perform code review

For complete documentation, see the [Developer Guide](https://github.com/majesteitbart/talentmatcher/blob/HEAD/docs/DEVELOPER_GUIDE.md).

## 🧪 Testing

### Automated Testing with Claude Code

Use the specialized test-runner agent for comprehensive testing:

```bash
# Run all tests with analysis
Task agent_type="test-runner" description="Run full test suite"

# Test specific functionality
Task agent_type="test-runner" description="Test authentication endpoints"
```

### Manual Testing

To test the workflow manually:

1. First, index some jobs:
```bash
curl -X POST http://localhost:3000/api/jobs/index
  -H "Content-Type: application/json"
  -d '{"company_id": "00000000-0000-0000-0000-000000000001"}'
```

2. Create a candidate and application (via Supabase dashboard or API)

3. Reject the candidate to trigger matching:
```bash
curl -X POST http://localhost:3000/api/candidates/reject
  -H "Content-Type: application/json"
  -d '{
    "candidate_id": "your-candidate-uuid",
    "application_id": "your-application-uuid",
    "rejection_reason": "Overqualified"
  }'
```

4. Check the workflow status:
```bash
curl http://localhost:3000/api/workflow/status/[workflow_id]
```

## 📈 Performance

- **CV Parsing**: ~2-4 seconds
- **Embedding Generation**: ~1 second per type (3 parallel)
- **Vector Search**: <100ms per query (with HNSW index)
- **Match Consolidation**: <50ms
- **Analysis Generation**: ~3-5 seconds
- **Total Workflow**: ~10-15 seconds

## 💰 Cost Estimates

Per candidate workflow:
- Gemini Parsing: ~$0.02
- Embeddings (3 types): ~$0.06
- Vector Search: ~$0.01
- Analysis: ~$0.03
- **Total**: ~$0.12 per candidate

## 🛡️ Production Checklist

- [ ] Set up proper authentication
- [ ] Configure Row Level Security (RLS) in Supabase
- [ ] Set up monitoring and alerting
- [ ] Configure rate limiting
- [ ] Set up error tracking (e.g., Sentry)
- [ ] Deploy workers to production (e.g., Railway, Render)
- [ ] Set up CI/CD pipeline
- [ ] Configure backup strategy
- [ ] Set up log aggregation
- [ ] Performance testing

## 📚 Documentation

- **[API Documentation](https://github.com/majesteitbart/talentmatcher/blob/HEAD/docs/API_DOCUMENTATION.md)** - Complete API reference with validation rules
- **[Developer Guide](https://github.com/majesteitbart/talentmatcher/blob/HEAD/docs/DEVELOPER_GUIDE.md)** - Development workflow and Claude Code infrastructure
- **[Error Handling Guide](https://github.com/majesteitbart/talentmatcher/blob/HEAD/docs/ERROR_HANDLING.md)** - Common errors and troubleshooting
- **[Error Notes](https://github.com/majesteitbart/talentmatcher/blob/HEAD/docs/error_notes.md)** - Recent fixes and resolved issues

## 📝 License

MIT

## 🤝 Contributing

We use epic-based development with Claude Code infrastructure:

1. **Initialize Epic**: Use `/pm:init` to start new features
2. **Follow Patterns**: See [Developer Guide](https://github.com/majesteitbart/talentmatcher/blob/HEAD/docs/DEVELOPER_GUIDE.md) for workflow
3. **Use Agents**: Leverage specialized agents for code quality and testing
4. **Smart Commits**: Use `/commit` for validated commits

Contributions welcome! Please open an issue or PR.

## 📧 Support

For questions or issues:

1. **Debug with Claude Code**: Use `Task agent_type="code-analyzer" description="Investigate issue"`
2. **Check Documentation**: Review [Error Handling Guide](https://github.com/majesteitbart/talentmatcher/blob/HEAD/docs/ERROR_HANDLING.md)
3. **GitHub Issues**: Open an issue for bugs or feature requests
4. **Developer Help**: Use `/pm:help` for command assistance

🏗️ Talent Matcher Agent

AI-powered system for automatically matching rejected candidates to alternative open positions.

🎯 Overview

When a candidate is rejected for a position, this system automatically:

Parses their CV using Gemini AI
Generates embeddings for skills, experience, and overall profile
Searches for similar open positions using pgvector
Consolidates and ranks matches
Generates a detailed analysis memo for recruiters

🚀 Tech Stack

Frontend: Next.js 14 (App Router), TypeScript, Tailwind CSS
Backend: Next.js API Routes, BullMQ workers
Database: Supabase (PostgreSQL + pgvector)
AI: Google Gemini 2.0 (CV parsing, embeddings, analysis)
Workflow: LangGraph (parallel execution orchestration)
Queue: BullMQ + Redis (background job processing)

📋 Prerequisites

Node.js 18+ and npm
Docker (for Redis)
Supabase account
Google Gemini API key

🛠️ Setup

1. Install Dependencies

npm install

2. Setup Supabase

Create a new project at supabase.com
Run the migration from supabase-migration.sql in the SQL Editor
Note your Project URL, anon key, and service_role key

3. Configure Environment Variables

Copy .env.example to .env.local:

cp .env.example .env.local

Fill in your credentials:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Gemini
GEMINI_API_KEY=your-gemini-api-key

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
NODE_ENV=development

4. Start Redis

docker-compose up -d

5. Start Development Services

Quick Start (Recommended):

npm run dev:concurrent  # Starts all services at once with color-coded output

Individual Services:

# Terminal 1: Next.js server
npm run dev

# Terminal 2: Workflow worker
npm run worker:workflow

# Terminal 3: Job indexing worker
npm run worker:indexing

Visit http://localhost:3000

6. Setup Claude Code Infrastructure (Optional but Recommended)

The project includes comprehensive Claude Code development tools:

# Initialize project management
/pm:init

# List available commands
/pm:help

# Show current development status
/pm:status

For detailed setup, see the Developer Guide.

📡 API Endpoints

Reject Candidate & Trigger Matching

POST /api/candidates/reject
Content-Type: application/json

{
  "candidate_id": "uuid",
  "application_id": "uuid",
  "rejection_reason": "Not enough experience" 
}

Check Workflow Status

GET /api/workflow/status/[workflow_execution_id]

Index Jobs for Vector Search

POST /api/jobs/index
Content-Type: application/json

{
  "company_id": "uuid",
  "job_ids": ["uuid1", "uuid2"] // optional, indexes all active jobs if omitted
}

🔄 Workflow Architecture

The matching workflow uses LangGraph for orchestration:

START
  ↓
Parse CV (Gemini)
  ↓
  ├── Retrieve by Skills (parallel)
  ├── Retrieve by Experience (parallel)
  └── Retrieve by Profile (parallel)
  ↓
Consolidate Matches (weighted scoring)
  ↓
Generate Analysis (Gemini)
  ↓
END

Key Features:

Parallel Execution: Skills, experience, and profile searches run simultaneously
Weighted Scoring: Skills (40%), Experience (35%), Profile (25%)
Multi-source Boost: Jobs matching multiple criteria get a 5% boost per source
Graceful Degradation: Workflow continues even if some retrievers fail

📊 Database Schema

Key tables:

companies - Company information
jobs - Job postings
job_embeddings - Vector embeddings for semantic search
candidates - Candidate profiles
parsed_cvs - Structured CV data
applications - Job applications
workflow_executions - LangGraph workflow runs
match_results - Matched jobs with scores

🤖 Claude Code Development Infrastructure

This project includes a comprehensive Claude Code development ecosystem with specialized agents and tools.

Key Features

9 Specialized Agents: Code analysis, testing, documentation, design review, and more
50+ Project Management Commands: Epic/issue tracking, PRD management, workflow automation
Automated Testing: Comprehensive test execution with real services (no mocking)
Smart Documentation: Auto-generated and updated documentation
Epic-Based Development: Organize work around large features rather than individual issues

Quick Commands

# Project Management
/pm:init                    # Initialize new epic
/pm:status                 # Show current work status
/pm:next                   # Get next task
/pm:standup                # Generate standup report

# Development Workflow
/review                    # Code review mode
/testing:run               # Run tests with analysis
/commit                    # Smart commit with validation
/prompt <task>             # Get AI assistance

# Get Help
/pm:help                   # List all available commands

Agent Coordination

For complex tasks, agents work together automatically:

# Example: Add new feature
Task agent_type="workflow-orchestrator" description="Add user authentication"

This will coordinate multiple agents to:

Analyze requirements
Create implementation plan
Build the feature
Write tests
Update documentation
Perform code review

For complete documentation, see the Developer Guide.

🧪 Testing

Automated Testing with Claude Code

Use the specialized test-runner agent for comprehensive testing:

# Run all tests with analysis
Task agent_type="test-runner" description="Run full test suite"

# Test specific functionality
Task agent_type="test-runner" description="Test authentication endpoints"

Manual Testing

To test the workflow manually:

First, index some jobs:

curl -X POST http://localhost:3000/api/jobs/index
  -H "Content-Type: application/json"
  -d '{"company_id": "00000000-0000-0000-0000-000000000001"}'

Create a candidate and application (via Supabase dashboard or API)
Reject the candidate to trigger matching:

curl -X POST http://localhost:3000/api/candidates/reject
  -H "Content-Type: application/json"
  -d '{
    "candidate_id": "your-candidate-uuid",
    "application_id": "your-application-uuid",
    "rejection_reason": "Overqualified"
  }'

Check the workflow status:

curl http://localhost:3000/api/workflow/status/[workflow_id]

📈 Performance

CV Parsing: ~2-4 seconds
Embedding Generation: ~1 second per type (3 parallel)
Vector Search: <100ms per query (with HNSW index)
Match Consolidation: <50ms
Analysis Generation: ~3-5 seconds
Total Workflow: ~10-15 seconds

💰 Cost Estimates

Per candidate workflow:

Gemini Parsing: ~$0.02
Embeddings (3 types): ~$0.06
Vector Search: ~$0.01
Analysis: ~$0.03
Total: ~$0.12 per candidate

🛡️ Production Checklist

Set up proper authentication
Configure Row Level Security (RLS) in Supabase
Set up monitoring and alerting
Configure rate limiting
Set up error tracking (e.g., Sentry)
Deploy workers to production (e.g., Railway, Render)
Set up CI/CD pipeline
Configure backup strategy
Set up log aggregation
Performance testing

📚 Documentation

API Documentation - Complete API reference with validation rules
Developer Guide - Development workflow and Claude Code infrastructure
Error Handling Guide - Common errors and troubleshooting
Error Notes - Recent fixes and resolved issues

📝 License

MIT

🤝 Contributing

We use epic-based development with Claude Code infrastructure:

Initialize Epic: Use /pm:init to start new features
Follow Patterns: See Developer Guide for workflow
Use Agents: Leverage specialized agents for code quality and testing
Smart Commits: Use /commit for validated commits

Contributions welcome! Please open an issue or PR.

📧 Support

For questions or issues:

Debug with Claude Code: Use Task agent_type="code-analyzer" description="Investigate issue"
Check Documentation: Review Error Handling Guide
GitHub Issues: Open an issue for bugs or feature requests
Developer Help: Use /pm:help for command assistance