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

> Troubleshoot interviewstreet/hiring-agent repository issues. Validate remote origin core files .env config and run smoke tests to restore expected state fast.

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

---

**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`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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.

```bash
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`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) – Orchestrates the end-to-end evaluation flow
- [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) – Applies fairness-aware scoring rules
- [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) – Handles LLM calls per resume section
- [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) – Extracts PDF content to Markdown
- [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) – Enriches candidate profiles with GitHub data
- [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) – Defines Pydantic schemas and provider abstractions (`OllamaProvider`, `GeminiProvider`)
- [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) – Initializes providers and cleans responses
- `prompts/` – Contains Jinja2 templates for structured extraction

Run this command to check for missing files:

```bash
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`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) and [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt).

```bash
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:

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

```

Successful runs display a summary and, if `DEVELOPMENT_MODE=True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py):

```bash
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:

```python
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:

```python
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:

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py), [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), or the orchestration logic in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py), [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py), [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) and [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py).

### How do I fix import errors when running [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) in a fresh virtual environment. Also verify that all core module files ([`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py). Verify that `DEVELOPMENT_MODE` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).