# Resolving Git Repository Discrepancies in the Hiring Agent Codebase

> Quickly resolve Git repository discrepancies in the hiring agent codebase. Learn how to clear caches, update modules, and verify environment variables to fix issues.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: how-to-guide
- Published: 2026-07-13

---

**The Hiring Agent repository employs a five-stage modular architecture that isolates failures to specific components, making it straightforward to identify and fix discrepancies between your local clone and the remote repository by clearing caches, updating modules, and verifying environment variables.**

Resolving Git repository discrepancies in the `interviewstreet/hiring-agent` codebase requires understanding how its modular pipeline processes résumés from PDF extraction through final evaluation. Because the system deliberately separates concerns into distinct stages—with clear boundaries between PDF handling, LLM parsing, GitHub enrichment, and scoring—any mismatch between your local state and the remote HEAD typically surfaces as isolated import errors or stale cache files rather than systemic failures.

## Understanding the Modular Pipeline Architecture

The repository implements a deliberate separation of concerns across five distinct stages. Each stage is encapsulated in its own module, ensuring that changes or missing files can be pinpointed without affecting the entire evaluation flow.

- **PDF Extraction**: Converts PDF pages to Markdown-like representations using [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) and [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), preserving document structure including headings and tables.
- **Section Parsing**: Invokes the LLM (via `OllamaProvider` or `GeminiProvider` defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)) using Jinja templates from [`prompt.py`](https://github.com/interviewstreet/hiring-agent/blob/main/prompt.py) to extract strict JSON-Resume objects.
- **GitHub Enrichment**: Detects usernames and pulls profile data through [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), classifying repositories and selecting the top seven most relevant projects.
- **Evaluation**: Applies fairness-constrained scoring rules in [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py), aggregating category scores and generating human-readable explanations stored in `EvaluationData` schemas.
- **Output & Export**: Orchestrated by [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), which prints evaluations and writes to `resume_evaluations.csv` when `DEVELOPMENT_MODE=True`.

## How Repository Discrepancies Manifest

When your local clone falls behind the remote or contains corrupted intermediate files, the modular design surfaces specific error types that point directly to the root cause.

### Import Errors and Missing Modules

Because stage boundaries are explicit—for example, [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) imports `pdf.PDFHandler`—a missing or outdated module raises an `ImportError` during the Python interpreter's initial load. This immediately identifies which file needs updating from the remote repository.

### Cache Inconsistencies and Stale Data

The pipeline reads and writes JSON files under the `cache/` directory between stages. If these intermediate artifacts were generated by an older version of the code, they may contain schemas incompatible with current Pydantic models in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py).

### GitHub API Rate Limiting

While not strictly a repository discrepancy, the `GeminiProvider` class in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) (lines 71-93) implements exponential back-off with jitter to handle API limits. Silent failures here can mask underlying repository synchronization issues if the code attempting to retry is itself outdated.

## Step-by-Step Resolution Process

Follow these specific steps to reconcile your local state with the remote repository and regenerate clean intermediate artifacts.

1. **Verify the repository state** – Run `git status` and `git fetch --prune` to ensure your local HEAD reflects the remote.

2. **Update modules and dependencies** – Execute `git pull` or `git checkout <branch>` to obtain the latest versions of [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), or [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) if they were added or modified since your last fetch.

3. **Clear stale caches** – Delete all cached intermediates to prevent schema mismatches:

   ```bash
   rm -rf cache/*
   ```

4. **Run the pipeline in development mode** – Execute the entry point to surface any remaining import or runtime errors:

   ```bash
   python score.py path/to/resume.pdf
   ```

   When `DEVELOPMENT_MODE=True` (set in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)), the system automatically recreates missing cache files and provides full stack traces.

5. **Inspect the generated CSV** – Verify that `resume_evaluations.csv` contains a row with the résumé hash and current timestamp, confirming that the updated repository version processed the input.

## Environment Configuration and Provider Setup

Repository discrepancies often involve missing environment variables defined in `.env.example`. Ensure your local configuration includes:

- `LLM_PROVIDER` (set to `ollama` or `gemini`)
- `DEFAULT_MODEL` (e.g., `gemma3:4b`)
- `GEMINI_API_KEY` or `GITHUB_TOKEN` as required

Provider-specific logic in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) handles rate limiting differently: `OllamaProvider` wraps the local chat API, while `GeminiProvider` implements retry logic (lines 73-86) that respects API back-off recommendations, preventing silent failures that could complicate debugging.

## Key Files to Inspect When Troubleshooting

When resolving discrepancies, examine these specific files to ensure version alignment:

| File | Role |
|------|------|
| [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) | CLI entry point that orchestrates the full pipeline and catches module-level errors |
| [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) | Handles PDF-to-Markdown conversion; check for updates to `PDFHandler` class methods |
| [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) | Contains Pydantic schemas for JSON-Resume and LLM provider abstractions including retry logic |
| [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) | Fetches profile data; verify against API changes that might affect repository classification |
| [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) | Implements scoring rules; ensure `EvaluationData` schema matches current expectations |
| [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) | Stores `DEVELOPMENT_MODE` flag and global settings that control cache behavior |

## Summary

- **Resolving Git repository discrepancies** in the Hiring Agent codebase relies on its five-stage modular architecture that isolates failures to specific components.
- **Import errors** immediately identify missing modules, while **cache inconsistencies** in the `cache/` directory indicate stale intermediate JSON files.
- Clear cached artifacts with `rm -rf cache/*` and run `python score.py` in development mode to regenerate clean state.
- Verify environment variables in `.env` match the current `.env.example` specifications, particularly for `LLM_PROVIDER` and API tokens.
- The `GeminiProvider` class in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) handles rate limiting with exponential back-off, ensuring API-related discrepancies don't mask underlying code issues.

## Frequently Asked Questions

### Why does the Hiring Agent use a modular pipeline architecture?

The architecture splits processing into five distinct stages—PDF extraction, section parsing, GitHub enrichment, evaluation, and output—each contained in separate modules like [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py). This design ensures that a discrepancy in one component (such as a missing import or outdated cache) fails fast and provides clear error messages without corrupting the entire evaluation pipeline.

### How do I clear stale cache files in the Hiring Agent repository?

Delete all files in the `cache/` directory using `rm -rf cache/*` from your terminal. When you subsequently run `python score.py <resume.pdf>` with `DEVELOPMENT_MODE=True` (as defined in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)), the system automatically regenerates all intermediate JSON artifacts using the current code version and Pydantic schemas from [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py).

### What causes ImportError when running score.py?

An `ImportError` typically indicates that your local clone is missing a module that exists in the remote repository, such as [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), or [`prompt.py`](https://github.com/interviewstreet/hiring-agent/blob/main/prompt.py). Because [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) explicitly imports these stage-specific modules, running `git pull` to update your local files will resolve the missing dependency and allow the pipeline to load correctly.

### How does DEVELOPMENT_MODE help resolve repository discrepancies?

When `DEVELOPMENT_MODE` is set to `True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the system enables verbose error reporting, automatic cache regeneration, and CSV logging to `resume_evaluations.csv`. This mode surfaces stack traces for import errors and schema mismatches while ensuring that missing cache files are rebuilt according to the current repository version rather than failing silently on stale data.