Debugging Unexpected Git Repository Content in the Hiring Agent Project

Unexpected files in the hiring-agent repository are typically development artifacts—JSON caches in cache/ and CSV logs created when DEVELOPMENT_MODE=True—not source code leaks or security breaches.

The hiring-agent repository by InterviewStreet transforms resume PDFs into structured evaluations using a multi-stage LLM pipeline. When debugging unexpected Git repository content, you are most likely encountering intermediate artifacts generated during local development rather than malicious code or submodule issues. Understanding the pipeline's architecture and its development-mode caching behavior is essential for distinguishing between legitimate source files and disposable runtime data.

Understanding the Pipeline Architecture

The repository implements a five-stage Python pipeline where each stage has specific responsibilities and dedicated modules:

• PDF Extraction – pymupdf_rag.py and pdf.py convert PDF pages to Markdown-like text using the to_markdown method and invoke LLM calls per section.
• Section Parsing – Jinja templates in prompts/templates/*.jinja (such as basics.jinja and work.jinja) define strict extraction prompts.
• GitHub Enrichment – github.py detects usernames in resumes, fetches profile data, classifies repositories, and prompts the LLM to select the top 7 projects.
• Evaluation – evaluator.py builds system and user prompts, calls the LLM through initialize_llm_provider from llm_utils.py, and parses responses into the EvaluationData Pydantic model defined in models.py.
• Output – score.py orchestrates the entire flow, prints summaries, and conditionally writes cache files when DEVELOPMENT_MODE is enabled.

All structured data conforms to the JSON Resume schema implemented in models.py, including the JSONResume top-level class and provider-specific implementations like OllamaProvider and GeminiProvider.

Sources of Unexpected Repository Content

When you encounter surprising files or directories, they typically originate from these three sources:

Development Cache Artifacts

During execution with DEVELOPMENT_MODE=True (set in config.py), the pipeline writes JSON blobs to the cache/ directory. Files like resumecache_<basename>.json store intermediate PDF extraction results from pdf.py, while githubcache_<basename>.json holds fetched GitHub profile data generated by github.py. These files are not part of the source tree but appear after any local run.

Generated CSV Logs

The score.py module appends evaluation results to resume_evaluations.csv in the project root when development mode is active. This CSV accumulates rows for every processed resume and is not tracked in version control.

External Assets

The repository contains no Git submodules. Any additional content beyond the five-stage modules and the files listed above is likely a manual copy or leftover from earlier execution runs.

How to Clean Up and Prevent Unexpected Files

If git status shows untracked or modified files that match the patterns above, use these commands to restore the repository state:

# Remove generated cache files

rm -rf cache/*.json

# Remove accumulated CSV export

rm resume_evaluations.csv

# If accidentally tracked, stop tracking but keep file

git rm --cached resume_evaluations.csv
git rm --cached cache/

# Restore accidentally modified source files

git checkout -- score.py config.py

To prevent future instances of debugging unexpected Git repository content, add these entries to your .gitignore:

# Development artifacts

cache/
*.json
resume_evaluations.csv

# Environment variables

.env

Common Pitfalls and Fixes

Symptom	Likely Cause	Solution
Large binary files in repository	Cached JSON or CSV from previous runs	Delete cache/ directory and resume_evaluations.csv
ImportError: cannot import name 'OllamaProvider'	Unsupported LLM_PROVIDER environment variable	Verify LLM_PROVIDER is set to ollama or gemini in llm_utils.py
Blank JSON responses from LLM	Missing Jinja templates	Ensure TemplateManager in prompts/template_manager.py can locate templates under prompts/templates/
Rate-limit errors from Gemini	Excessive API calls	The provider implements exponential back-off in models.py; increase delays or switch to Ollama for offline testing

Inspecting Pipeline Execution

When verifying what content the pipeline generates, run these commands to inspect specific stages:

# Activate environment and run full evaluation

source .venv/bin/activate
python score.py path/to/resume.pdf

# Inspect cached PDF extraction output

cat cache/resumecache_myresume.json

# Inspect GitHub enrichment data

cat cache/githubcache_myresume.json

# Check if CSV was updated

tail -n 5 resume_evaluations.csv

Summary

• Unexpected files in the hiring-agent repository are almost always development artifacts created when DEVELOPMENT_MODE=True.
• The cache/ directory stores intermediate JSON from pdf.py and github.py processing, while score.py generates resume_evaluations.csv.
• No Git submodules exist in the repository; extra content indicates manual copies or execution leftovers.
• Remove artifacts with rm -rf cache/ and rm resume_evaluations.csv, then add these patterns to .gitignore to prevent future tracking.
• When debugging import errors or malformed responses, verify LLM_PROVIDER settings and template paths in prompts/template_manager.py.

Frequently Asked Questions

Why do JSON files appear in my repository after running the hiring agent?

These are intermediate cache files generated by score.py when DEVELOPMENT_MODE=True (defined in config.py). The files resumecache_<basename>.json and githubcache_<basename>.json store PDF extraction results and GitHub API responses to speed up debugging. They are not part of the source code and should be added to .gitignore.

Is it safe to delete the cache directory and resume_evaluations.csv?

Yes. The cache/ directory and resume_evaluations.csv are runtime outputs used only for development convenience. score.py recreates them automatically when processing new resumes with development mode enabled. Deleting them will not affect the pipeline's ability to process PDFs or evaluate candidates.

How do I switch between Ollama and Gemini providers without leaving artifacts?

Set the LLM_PROVIDER environment variable before running score.py. For Gemini, also export GEMINI_API_KEY. The provider initializes through initialize_llm_provider in llm_utils.py, which instantiates either OllamaProvider or GeminiProvider from models.py. Neither provider writes persistent files, but ensure you clean up any cache/ files between runs to avoid cross-contamination of resume data.

What should I check if the pipeline fails with template errors?

Verify that prompts/template_manager.py can locate Jinja templates in prompts/templates/ (such as basics.jinja and work.jinja). The TemplateManager raises a ValueError if templates are missing. Ensure you run commands from the repository root so relative paths resolve correctly, preventing the "blank or malformed JSON" symptom that occurs when prompts fail to render.

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