How to Update Candidate Status via API in the Hiring Agent Repository

The interviewstreet/hiring-agent repository does not implement a REST API for updating candidate status; it operates entirely through local Python functions and command-line tools, requiring you to build a custom FastAPI or Flask wrapper to expose status endpoints.

The interviewstreet/hiring-agent codebase is a specialized Python tool designed for parsing résumé PDFs, extracting structured candidate data with large language models (LLM) such as Google Gemini, and generating evaluation scores. Because the architecture centers on local script execution rather than client-server communication, there are no HTTP routes, request handlers, or built-in endpoints to modify a candidate’s hiring status via API.

Why the Repository Lacks a Candidate Status API

According to the hiring-agent source code, the project is architected as a standalone evaluation engine rather than a web service. All modules are invoked directly via Python imports or CLI commands, with no HTTP server infrastructure present in any configuration or routing files.

Core Components of the Evaluation Pipeline

• PDF parsing & text extraction: The pdf.py and pymupdf_rag.py modules handle ingestion of résumé files and conversion to structured text.
• Prompt generation: The prompt.py module and Jinja2 templates in prompts/templates/*.jinja construct LLM queries based on extracted data.
• LLM provider abstraction: The models.py and llm_utils.py files manage API calls to Gemini and handle retry logic.
• Scoring & evaluation: The evaluator.py and score.py modules process LLM responses into numeric scores and formatted output.
• Configuration: The config.py and .env.example files manage environment variables for API keys and model selection.

None of these files contain Flask apps, FastAPI routers, or HTTP handlers, confirming that the repository does not support remote status updates.

The Current Local Workflow

Rather than updating a candidate record through a PATCH request, hiring-agent runs evaluations locally by chaining functions from pdf.py to evaluator.py. This workflow generates a score but does not persist or modify a "status" field in any external system.

Running a Resume Evaluation via Python

from pdf import extract_resume_data
from evaluator import evaluate_resume
from score import print_evaluation_results

# 1. Extract structured résumé data from the PDF

resume_data = extract_resume_data("candidate_resume.pdf")

# 2. Run the LLM evaluation

score = evaluate_resume(resume_data)

# 3. Display the results

print_evaluation_results(score, candidate_name="John Doe")

Executing this script creates a one-time evaluation output; it does not store candidate statuses such as "Interviewed" or "Rejected" in a database or expose them via an API.

How to Build a Candidate Status Update API

Because the repository lacks native HTTP capabilities, you must implement a service layer to expose candidate status functionality. The most efficient approach wraps the existing evaluation logic in a FastAPI application.

Choose a Web Framework

FastAPI is recommended for this integration due to its native Pydantic support and automatic OpenAPI documentation generation, though Flask is a viable alternative.

Create Pydantic Data Models

Define models to validate incoming status updates and candidate identification:

from pydantic import BaseModel

class StatusUpdate(BaseModel):
    status: str  # e.g., "Screened", "Interviewed", "Hired"

    updated_by: str

Implement the Status Update Endpoint

Add a route handler that receives status changes and persists them to your chosen storage layer:

from fastapi import FastAPI

app = FastAPI()

@app.patch("/candidates/{candidate_id}/status")
async def update_status(candidate_id: int, payload: StatusUpdate):
    # Retrieve candidate from SQLite/PostgreSQL or in-memory store

    # Update candidate.status = payload.status

    # Optionally trigger re-evaluation using evaluator.py logic

    return {"candidate_id": candidate_id, "new_status": payload.status}

Persist State and Integrate Evaluation

Connect the new API to a database (SQLite, PostgreSQL, or even a JSON file) and modify the route to invoke evaluate_resume() when a résumé is uploaded, automatically setting status = "evaluated" upon completion.

Summary

• The interviewstreet/hiring-agent repository provides no built-in API for candidate status management; it is a local CLI and library tool.
• Current functionality is limited to PDF parsing (pdf.py), LLM scoring (evaluator.py), and result printing (score.py).
• To enable status updates via API, you must implement a custom FastAPI/Flask service that wraps the existing evaluation pipeline.
• Key integration points involve the extract_resume_data() and evaluate_resume() functions for triggering evaluations upon status changes.

Frequently Asked Questions

Does hiring-agent include a REST API for candidate management?

No. The repository contains no HTTP servers, routes, or request handlers. All interactions rely on direct Python function calls or command-line scripts.

Which source files handle the resume evaluation workflow?

The primary workflow files are pdf.py for text extraction, evaluator.py for scoring logic, and score.py for formatting output. Supporting modules include models.py for LLM integration and llm_utils.py for API retry handling.

Can I update a candidate’s hiring status using the command line?

No. The CLI and library functions only support résumé parsing and score generation. There is no built-in mechanism to store or update discrete hiring statuses such as "Rejected" or "Offer Extended."

What is the fastest way to add status update functionality to this repository?

Implement a FastAPI wrapper service that imports the existing evaluation functions. Create a PATCH /candidates/{id}/status endpoint that updates a database record, and optionally wire the evaluate_resume() function to trigger when résumés are re-uploaded.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}