What to Do When a Git Repository Is Not What You Expect: Troubleshooting the Hiring Agent Pipeline

When the interviewstreet/hiring-agent repository doesn't match your expectations, follow a systematic validation workflow—confirm the remote origin, verify core files like score.py and evaluator.py, check your .env configuration, and run a smoke test—to quickly restore the expected state.

If you clone the interviewstreet/hiring-agent repository and encounter missing files, unexpected versions, or custom code that breaks the resume evaluation pipeline, you need a deterministic recovery strategy. This guide explains exactly what to do when a Git repository is not what you expect, providing concrete steps to validate and restore the system using the actual modular architecture implemented in the source code.

Confirm the Repository Origin

First, verify you cloned the official repository and not a fork or outdated mirror. Check your remote origin and compare your commit SHA with the main branch on GitHub.

git remote -v

# Should show: https://github.com/interviewstreet/hiring-agent.git

git log --oneline -1

# Compare this hash with the latest commit on github.com/interviewstreet/hiring-agent main

Validate Core Files and Directory Structure

The Hiring Agent pipeline relies on a fixed set of Python modules and Jinja templates. Verify the presence of these critical files in your working directory:

• score.py – Orchestrates the end-to-end evaluation flow
• evaluator.py – Applies fairness-aware scoring rules
• pdf.py – Handles LLM calls per resume section
• pymupdf_rag.py – Extracts PDF content to Markdown
• github.py – Enriches candidate profiles with GitHub data
• models.py – Defines Pydantic schemas and provider abstractions (OllamaProvider, GeminiProvider)
• llm_utils.py – Initializes providers and cleans responses
• prompts/ – Contains Jinja2 templates for structured extraction

Run this command to check for missing files:

ls -la score.py pdf.py pymupdf_rag.py github.py evaluator.py models.py llm_utils.py prompts/

Check Configuration and Environment Variables

The system expects a .env file modeled after .env.example. Open your configuration and verify these required variables are set:

• LLM_PROVIDER
• DEFAULT_MODEL
• GEMINI_API_KEY (if using Gemini)

Corrupted or missing environment variables cause silent failures in models.py and llm_utils.py when initializing providers.

Verify Dependency Versions

Incompatible Python versions or third-party libraries cause import errors or subtle behavioral differences. The project pins Python 3.11+ and declares dependencies in requirements.txt.

python --version  # Should be 3.11+

pip install -r requirements.txt

Run a Smoke Test

Execute the simplest entry point to exercise every stage of the pipeline and surface missing components early:

python score.py path/to/sample.pdf

Successful runs display a summary and, if DEVELOPMENT_MODE=True in config.py, output a CSV line to the console.

Recover Missing or Corrupted Files

If any core file is absent or altered, fetch it directly from the main branch using the raw GitHub URL. For example, to restore models.py:

curl -L https://raw.githubusercontent.com/interviewstreet/hiring-agent/main/models.py -o models.py

Re-run the smoke test after restoring files to confirm the pipeline executes correctly.

Debug Individual Components Programmatically

When the CLI behaves unexpectedly, isolate specific stages using Python to identify where the repository state diverges from expectations.

Test the full pipeline programmatically:

from score import run_score

pdf_path = "samples/example_resume.pdf"
run_score(pdf_path)  # Equivalent to `python score.py <pdf_path>`

Test PDF extraction independently:

from pymupdf_rag import PDFExtractor

extractor = PDFExtractor()
markdown = extractor.to_markdown("samples/example_resume.pdf")
print(markdown[:500])  # Preview the first 500 characters

Test GitHub enrichment in isolation:

from github import GitHubEnricher

enricher = GitHubEnricher()
profile = enricher.get_profile("octocat")  # Replace with actual username

print(profile)  # Shows JSON of the public profile

These snippets help you pinpoint whether the issue lies in pymupdf_rag.py, github.py, or the orchestration logic in score.py.

Summary

• Verify the remote origin points to https://github.com/interviewstreet/hiring-agent and matches the latest main branch commit
• Confirm core files exist: score.py, evaluator.py, models.py, github.py, pdf.py, pymupdf_rag.py, llm_utils.py, and the prompts/ directory
• Validate environment variables in .env against the template in .env.example
• Run python score.py sample.pdf as a smoke test after any restoration
• Use curl to fetch specific missing files directly from the main branch without re-cloning
• Test individual components using the provided Python snippets to isolate stage-specific failures

Frequently Asked Questions

Why does my cloned repository have different files than the documentation?

You may have cloned a fork, an outdated branch, or encountered a partial clone. Check the remote origin with git remote -v and ensure it matches https://github.com/interviewstreet/hiring-agent.git. Compare your current commit SHA with the main branch on GitHub to verify you have the latest version that includes all files like evaluator.py and llm_utils.py.

How do I fix import errors when running score.py?

Import errors typically indicate missing dependencies or incompatible Python versions. Ensure you are using Python 3.11 or higher, then reinstall requirements from requirements.txt in a fresh virtual environment. Also verify that all core module files (models.py, llm_utils.py, etc.) exist in the root directory and are not corrupted.

Can I restore just one corrupted file without re-cloning the entire repository?

Yes. Use curl to fetch the raw file directly from GitHub. For example, to restore evaluator.py, run: curl -L https://raw.githubusercontent.com/interviewstreet/hiring-agent/main/evaluator.py -o evaluator.py. This preserves your local configuration and environment variables while fixing the specific corrupted component.

What should I do if the smoke test succeeds but the output seems wrong?

Check your .env configuration first, specifically LLM_PROVIDER and DEFAULT_MODEL as defined in models.py. Verify that DEVELOPMENT_MODE in config.py matches your intended usage. You can also test individual components—such as PDFExtractor.to_markdown() or GitHubEnricher.get_profile()—to isolate which stage produces unexpected results before the final scoring in evaluator.py.

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