Resolving Git Repository Discrepancies in the Hiring Agent Codebase

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 and pdf.py, preserving document structure including headings and tables.
• Section Parsing: Invokes the LLM (via OllamaProvider or GeminiProvider defined in models.py) using Jinja templates from prompt.py to extract strict JSON-Resume objects.
• GitHub Enrichment: Detects usernames and pulls profile data through github.py, classifying repositories and selecting the top seven most relevant projects.
• Evaluation: Applies fairness-constrained scoring rules in evaluator.py, aggregating category scores and generating human-readable explanations stored in EvaluationData schemas.
• Output & Export: Orchestrated by 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 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.

GitHub API Rate Limiting

While not strictly a repository discrepancy, the GeminiProvider class in 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, github.py, or evaluator.py if they were added or modified since your last fetch.

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

   rm -rf cache/*

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

   python score.py path/to/resume.pdf

   When DEVELOPMENT_MODE=True (set in 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 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	CLI entry point that orchestrates the full pipeline and catches module-level errors
pdf.py	Handles PDF-to-Markdown conversion; check for updates to PDFHandler class methods
models.py	Contains Pydantic schemas for JSON-Resume and LLM provider abstractions including retry logic
github.py	Fetches profile data; verify against API changes that might affect repository classification
evaluator.py	Implements scoring rules; ensure EvaluationData schema matches current expectations
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 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 and 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), the system automatically regenerates all intermediate JSON artifacts using the current code version and Pydantic schemas from 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, github.py, or prompt.py. Because 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, 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.

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