AI Interview & Assessment System (crew-provexa)

An intelligent interview and skill assessment system powered by CrewAI that evaluates candidates based on their resume, GitHub profile, and interview responses. The system produces detailed skill assessments with percentage scores, identifies strengths and weaknesses, generates personalized course recommendations, and suggests suitable job opportunities.

Available as both a FastAPI HTTP service and an interactive CLI.

Features

• Profile Analysis — analyzes resumes and GitHub profiles to extract skills, experience, and technical domain
• AI-Powered Interviews — generates contextual interview questions based on candidate profile and target role
• Skill Assessment — evaluates responses and produces percentage-based skill scores with supporting evidence
• Strengths & Weaknesses — identifies specific strong/weak areas with improvement suggestions
• Course Recommendations — generates prioritized learning resources to close skill gaps
• Job Recommendations — suggests relevant job/internship listings matched to the assessment
• Career Path Suggestions — proposes next-step roles based on overall score
• CLI Mode — run the full pipeline interactively from the terminal, no HTTP client needed

Architecture

The system uses CrewAI with two specialized crews that run sequentially, orchestrated by InterviewSystem:

ProfileAnalysisCrew

Analyzes candidate profiles and extracts comprehensive context:

1. Resume Extractor — extracts technical info, skills, experience, and achievements from resume text
2. GitHub Profile Analyst — analyzes GitHub profiles for technical skills, project experience, and code quality signals
3. Technical Domain Classifier — classifies primary technical domain and identifies secondary domains
4. Profile Synthesizer — synthesizes everything into a single candidate profile context

Output: domain classification, extracted skills, skill clusters, technical strengths, potential weaknesses, and interview readiness assessment.

InterviewCrew

Conducts the interview and identifies strong/weak areas:

1. Domain-Specific Technical Interviewer — generates targeted questions from the profile context
2. Technical Response Evaluator — evaluates responses to determine skill proficiency
3. Strength and Weakness Analyzer — identifies specific strong/weak areas with evidence
4. Skill Proficiency Assessor — produces percentage-based skill assessments

Output: domain-specific questions, strengths/weaknesses with evidence, percentage-based skill assessments, course recommendations.

Tech Stack

• Python 3.10+
• FastAPI + Uvicorn
• CrewAI (multi-agent orchestration)
• LLMs: Gemini (primary), Groq (optional fallback)
• aiofiles for async resume upload handling
• Optional: PostgreSQL / Redis (configured via config.py, not required to run the core pipeline)
• Optional: Adzuna API for live job listings (falls back to mock data otherwise)

Installation

1. Clone the repository:

   git clone https://github.com/naumankhalid-dev/crew-provexa.git
   cd crew-provexa
   

2. Create a virtual environment:

   python -m venv venv
   venv\Scripts\activate     # On Windows
   source venv/bin/activate  # On Unix
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Set up environment variables:

   cp .env.example .env
   

   Edit .env and add your keys (see Configuration below).

Usage

Start the API server

python main.py

or

uvicorn main:app --reload

The API is available at http://localhost:8000.

Run the CLI

python cli_interview.py

The CLI walks you through the same pipeline interactively — prompts for name, email, target role, experience, skills, resume text, and/or GitHub URL, then prints:

• Assessed level
• Key skills / gaps
• Skill assessments with percentages
• Course recommendations
• Top job matches

API Endpoints

All candidate-input endpoints accept multipart/form-data (so a resume file can be attached).

1. Analyze Profile

POST /api/v1/profile/analyze
Content-Type: multipart/form-data
name: string (required)
email: string (required)
target_role: string (required)
experience_years: float (default 0.0)
github_url: string (optional)
additional_info: string (optional)
resume: file (optional)
skills: string (optional — JSON array or comma-separated, e.g. '["Python","FastAPI"]' or "Python,FastAPI")

Runs ProfileAnalysisCrew and returns domain classification, extracted skills, skill clusters, technical strengths/weaknesses, and interview readiness. Use this before generating interview questions.

2. Generate Interview Questions

POST /api/v1/interview/questions
Content-Type: multipart/form-data
(same candidate fields as above)
num_questions: integer (default 10)

Returns a list of { id, question, category, difficulty } objects tailored to the candidate's profile.

3. Evaluate Interview Responses

POST /api/v1/interview/evaluate
Content-Type: multipart/form-data
(same candidate fields as above)
responses: string (required — JSON array of response objects)

Each item in responses:

{
  "question": "string",
  "category": "string (optional, default 'general')",
  "difficulty": "string (optional, default 'medium')",
  "answer": "string",
  "confidence": 1-10
}

Runs InterviewCrew and returns overall score, skill assessments (with skill_name, percentage, strength_level, evidence), strengths/weaknesses/improvement areas, course recommendations, and an interview summary.

4. Get Job Recommendations

POST /api/v1/jobs/recommend
Content-Type: application/json
{
"interview_result": { ... },   // an InterviewResult-shaped object, e.g. output of endpoint 3
"location": "string (optional, query param)",
"limit": 5                      // optional, query param, default 5
}

Returns matched jobs with job_title, company, description, required_skills, match_percentage, salary_range, location, url. Uses Adzuna if configured, otherwise mock/sample listings.

5. Complete Assessment (End-to-End)

POST /api/v1/assessment/complete
Content-Type: multipart/form-data
(same candidate fields as endpoint 3, plus:)
location: string (optional, query param)
job_limit: integer (default 5, query param)

Runs the full pipeline in one call — profile analysis → interview evaluation → job recommendations → career path suggestions — and returns a combined result under assessment.

Health Check

GET /

Returns { "status": "healthy", "service": "AI Interview & Assessment System", "version": "1.0.0" }.

Example Workflow

1. Submit Candidate Profile — upload a resume and/or provide a GitHub URL, specify a target role (e.g. "Backend Engineer"); the system extracts skills and classifies the technical domain.
2. Generate Interview Questions — the system generates contextual questions of varying difficulty across relevant technical areas.
3. Conduct Interview — the candidate answers each question with a self-reported confidence level (1–10).
4. Get Assessment Results — overall score, per-skill percentage assessments, strengths/weaknesses, and course recommendations.
5. Career Guidance — job matches and career path suggestions based on the overall score.

Skill Assessment Levels

Data Models (models.py)

• CandidateProfile — name, email, resume_text, github_url, experience_years, skills, target_role, additional_info
• InterviewQuestion — question, category, difficulty
• InterviewResponse — question_id, answer, confidence (1–10)
• SkillAssessment — skill_name, percentage (0–100), strength_level, evidence
• StrengthWeaknessAnalysis — strengths, weaknesses, improvement_areas
• CourseRecommendation — title, description, duration_weeks, topics, resources, priority
• InterviewResult — candidate_name, target_role, overall_score, assessed_level, skill_assessments, analysis, course_recommendations, interview_summary, role_match_percentage, timestamp
• JobRecommendation — job_title, company, description, required_skills, match_percentage, salary_range, location, url, listing_type
• FinalAssessment — interview_result, job_recommendations, career_path_suggestions
• SkillGap (reserved for Phase 2, see below) — skill_name, current_level, required_level, importance_for_role, evidence

Project Structure

crew-provexa/
├── main.py                    # FastAPI application with API endpoints
├── cli_interview.py           # Interactive CLI entrypoint
├── interview_system.py        # Orchestrates the two crews and manages workflow
├── profile_analysis_crew.py   # CrewAI crew for profile analysis (resume, GitHub, domain classification)
├── interview_crew.py          # CrewAI crew for interview generation and evaluation
├── profile_analyzer.py        # Resume text extraction and GitHub API integration
├── job_service.py             # Job recommendation service (Adzuna + mock fallback)
├── agents.py                  # CrewAI agent definitions
├── models.py                  # Pydantic data models
├── config.py                  # Configuration management (env-backed settings)
├── utils.py                   # Parsing helpers (parse_crew_result, safe_parse_list, etc.)
├── requirements.txt           # Python dependencies
├── .env.example                # Environment variables template
├── example_usage.py           # Example usage script
├── test_setup.py               # Setup verification script
├── test_utils.py                # Sanity checks for JSON/list parsing helpers
├── README.md                  # This file
└── uploads/                   # Directory for uploaded resumes (created at runtime)

API Documentation

Once the server is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Configuration

Environment variables are managed via config.py (Pydantic BaseSettings, loaded from .env):

Development

Running tests

python test_setup.py
python test_utils.py

Adding new agents

Edit agents.py to add new CrewAI agents with specific roles and goals.

Customizing job sources

Modify job_service.py to integrate with different job board APIs (Adzuna, Indeed, Reed, etc.).

Roadmap

Phase 2 — Course Gap Generation (sketched in models.py, not yet implemented) A dedicated CourseGeneratorCrew will consume the weak skills identified during evaluation (as SkillGap objects — skill, current vs. required level, importance to the target role, and supporting evidence) and produce a personalized, week-by-week learning roadmap per skill, sourcing curated resources (video, courses, hands-on projects). This is intentionally decoupled from job matching so both can evolve independently.

License

MIT License

Contributors

• Nauman Khalid — GitHub
• Muhammad Mohib Ali — Profile
• Khalid Hussain — Profile

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.