# How the Caching Mechanism Works in Development Mode in Hiring-Agent

> Learn how Hiring-Agent's development mode caching speeds up workflows by skipping PDF parsing and GitHub API calls using deterministic JSON files.

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

---

**The development-mode caching mechanism in Hiring-Agent uses deterministic JSON files stored in a `cache/` directory to skip expensive PDF parsing and GitHub API calls when `DEVELOPMENT_MODE` is set to `True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py).**

When iterating on candidate evaluation logic, repeatedly parsing resumes or hitting API rate limits slows down development. The **Hiring-Agent** project solves this with a lightweight, file-based caching layer that activates automatically during local development. This system intercepts expensive operations and persists their results to disk, ensuring deterministic, instant reloads on subsequent runs.

## Resume Processing Cache in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)

The resume evaluation pipeline caches parsed PDF data to avoid re-running OCR and extraction on every test run.

### Cache Path Construction and Lookup

Before processing a PDF, the code constructs a deterministic filename based on the input document's basename. According to [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) lines 216–219, the pattern `cache/resumecache_<pdf-basename>.json` is generated uniquely per file.

If **`DEVELOPMENT_MODE`** is enabled and the file exists, lines 227–231 load the JSON and instantiate a `JSONResume` object immediately, bypassing the entire parsing pipeline. Console output explicitly logs "Loading cached data…" to indicate when this shortcut activates.

### Cache Validation and Error Handling

Corrupted cache files are handled gracefully. Lines 237–244 catch JSON decode errors, emit a warning message, delete the invalid file, and fall back to live PDF processing. This ensures that disk corruption never blocks development workflow.

### Writing Cache Files

After successful parsing, the system writes results back to disk for future runs. Lines 259–261 create the `cache/` directory if missing, then serialize the resume object to the previously determined path. Subsequent evaluations of the same PDF load instantly from this JSON snapshot.

## GitHub API Response Caching in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)

External API calls follow an identical pattern to prevent rate-limit exhaustion during iterative testing.

### Generating Deterministic Cache Keys

The helper function `_create_cache_filename` (lines 18–25) generates filenames using the pattern `cache/gh_githubcache_<url-parts>[_<param-hash>].json`. This deterministic hashing ensures identical requests map to identical cache files regardless of execution order.

### Cache Retrieval and Invalidation

When `DEVELOPMENT_MODE` is active, lines 35–42 check for the cached file's existence and return the stored JSON response as if it came from the live API. If parsing fails, lines 44–50 log a warning, remove the corrupt file, and proceed with a real network request.

### Persisting Successful Responses

For HTTP 200 responses, lines 104–107 write the response body to the cache path, creating the directory structure on demand. Line 111 logs any filesystem exceptions during the write operation, but failures to cache never propagate or interrupt the main execution flow.

## Configuration and Environment Setup

The global toggle resides in **[`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)** at line 6, where `DEVELOPMENT_MODE = True` by default. Production deployments should override this via environment variables or direct modification to disable caching and force fresh data ingestion.

## Code Examples

Run the resume evaluator with automatic caching:

```python
from score import main

# First run parses the PDF and writes cache/resumecache_<name>.json

result = main("samples/jane_doe_resume.pdf")
print(result)  # Subsequent runs load JSON from cache instantly

```

Fetch GitHub data with transparent caching:

```python
from github import request_github_api

# First call contacts the real GitHub API

status, data = request_github_api(
    api_url="https://api.github.com/users/interviewstreet",
    params=None,
)

# Second call reads from cache/gh_githubcache_api_github_com_users_interviewstreet.json

print(status, data)

```

Disable caching for production runs:

```bash
export DEVELOPMENT_MODE=False  # or edit config.py

python -m score samples/resume.pdf  # Forces fresh PDF parsing

```

## Summary

- **File-based storage**: All cache entries are JSON files under the `cache/` directory.
- **Deterministic naming**: Filames derive from input PDF basenames or API URL hashes to ensure consistent lookup.
- **Graceful degradation**: Corrupted cache files trigger deletion and automatic fallback to live processing.
- **Development-only**: Controlled exclusively by the `DEVELOPMENT_MODE` flag in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), allowing clean production runs when disabled.

## Frequently Asked Questions

### Where are the cache files stored?

Cache files reside in a `cache/` directory created at runtime in the project root. Resume caches follow the pattern `resumecache_<basename>.json`, while GitHub caches use `gh_githubcache_<hash>.json`.

### How do I clear the cache manually?

Delete the `cache/` directory or specific JSON files within it. The next run will regenerate them automatically by re-processing the source PDFs or re-fetching API data.

### Can I use this caching mechanism in production?

The repository recommends disabling `DEVELOPMENT_MODE` in production to ensure fresh data and avoid stale results. However, the code does not enforce this; you must explicitly set `DEVELOPMENT_MODE = False` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) or via environment variables before deployment.

### What happens if the cache file is corrupted?

Both [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) (lines 237–244) and [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) (lines 44–50) catch JSON decode errors, log a warning, delete the invalid file, and execute the full processing or HTTP request. This ensures corrupted caches never crash the application.