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

> Learn how the caching mechanism works in Hiring-Agent's development mode. Discover how intermediate results are stored as JSON to speed up operations and avoid redundant computations.

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

---

**In development mode, the Hiring-Agent project stores intermediate results as JSON files in a `cache/` directory, checking for existing caches before performing expensive operations like PDF parsing or GitHub API calls, and writing results back only when `DEVELOPMENT_MODE` is `True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py).**

The hiring-agent repository by InterviewStreet implements a lightweight, file-based caching layer to accelerate iterative development workflows. When the `DEVELOPMENT_MODE` flag is enabled in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the system persists parsed resume data and GitHub API responses to disk, eliminating redundant computation and network requests across repeated script executions. This mechanism ensures deterministic, fast feedback loops while maintaining the flexibility to force fresh processing when needed.

## 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 expensive text extraction and structuring operations on every development iteration.

### Cache Path Construction and Lookup

Before processing a PDF, the system constructs a deterministic cache filename based on the input file's basename. In [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) lines 216-219, the code builds a path following the pattern `cache/resumecache_<pdf-basename>.json`. When `DEVELOPMENT_MODE` is active and this file exists on disk, the system short-circuits the parsing logic and loads the cached `JSONResume` object directly from the JSON file (lines 227-231).

### Cache Invalidation and Error Handling

If a cache file becomes corrupted or contains invalid JSON, the system implements graceful degradation. Lines 237-244 in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) catch `JSONDecodeError` exceptions, log a warning message, delete the corrupt file from disk, and proceed with full PDF parsing. This ensures that transient write failures or manual file edits do not permanently break the development workflow.

### Cache Persistence After Processing

After successfully parsing a PDF, the system writes the structured result back to the cache directory. Lines 259-261 in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) create the `cache/` directory if it does not exist and serialize the `JSONResume` object to the predetermined cache path. All cache operations emit explicit log messages, such as "Loading cached data…" or "⚠️ Warning…", making the data flow visible during script execution.

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

External API calls to GitHub are cached to prevent rate limiting and avoid redundant network traffic during development.

### Deterministic Filename Generation

The `_create_cache_filename` function (lines 18-25 in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)) generates a unique, deterministic filename by sanitizing the API URL and appending a hash of request parameters. This produces cache keys like `cache/gh_githubcache_<url-parts>[_<param-hash>].json`, ensuring that identical API requests map to the same cache file across different execution contexts.

### Cache Retrieval and Fallback Logic

When `DEVELOPMENT_MODE` is enabled, the `request_github_api` function first checks for the existence of a cached response (lines 35-42). If found, the function reads the JSON file and returns the stored data as if it were a fresh API response. If the cache file is missing or contains invalid JSON (lines 44-50), the system logs a warning, removes the defective file, and executes a live HTTP request to the GitHub API.

### Writing New Cache Entries

Following a successful API call that returns HTTP 200, the response body is persisted to the cache directory (lines 104-107). The system creates the `cache/` folder on demand and writes the JSON payload to the filename generated earlier in the request lifecycle. Any exceptions encountered during the cache write operation are logged at line 111 but do not halt execution, ensuring that transient disk issues do not crash the application.

## Configuration and Mode Flag

The `DEVELOPMENT_MODE` boolean flag is defined in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) at line 6 and defaults to `True` for local development environments. This centralized configuration controls caching behavior across both the resume scoring and GitHub integration modules. Production deployments can override this setting via environment variables or direct modification to disable caching and force fresh data processing.

## Practical Code Examples

The following examples demonstrate how to interact with the caching mechanism during development and production scenarios.

### Running the Resume Evaluator with Cache

```python
from score import main

# First execution parses the PDF and writes to cache/resumecache_jane_doe_resume.json

result = main("samples/jane_doe_resume.pdf")

# Subsequent executions load instantly from the JSON cache while DEVELOPMENT_MODE=True

print(result)

```

### Fetching GitHub Data with Cache

```python
from github import request_github_api

# Initial call contacts the live GitHub API and caches the response

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

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

```

### Disabling Cache for Production Runs

```bash

# Set the environment variable to override config.py

export DEVELOPMENT_MODE=False

python -m score samples/jane_doe_resume.pdf

```

This forces fresh PDF parsing and API calls on every execution, bypassing all cache lookups in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) and [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py).

## Summary

- The **caching mechanism** is controlled by the `DEVELOPMENT_MODE` flag in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) and applies to both resume processing and GitHub API calls.
- Cache files are stored as **JSON** in a `cache/` directory using deterministic filenames based on input PDF names or API request parameters.
- **Cache hits** bypass expensive operations entirely, returning deserialized objects immediately from disk.
- **Corrupted caches** are automatically detected, deleted, and regenerated without manual intervention.
- The system differentiates between development and production through a single configuration boolean, ensuring clean, uncached execution when deployed.

## Frequently Asked Questions

### Where is the development mode flag defined in Hiring-Agent?

The `DEVELOPMENT_MODE` flag is hard-coded to `True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) at line 6. This central configuration variable controls whether the caching logic in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) and [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) checks for and writes to cache files.

### How does the resume cache handle corrupted JSON files?

When [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) encounters a `JSONDecodeError` while reading a cache file (lines 237-244), it logs a warning, deletes the corrupt file from disk, and falls back to full PDF parsing. After successful parsing, it writes a new, valid cache file to replace the deleted one.

### Can I use the GitHub cache for different API endpoints simultaneously?

Yes. The `_create_cache_filename` function in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) (lines 18-25) generates unique filenames for each API URL and parameter combination. This allows concurrent caching of multiple endpoints (e.g., user profiles, repositories, issues) without collisions, as each distinct request maps to a distinct JSON file in the `cache/` directory.

### What happens if the cache directory does not exist?

Both [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) (lines 259-261) and [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) (lines 104-107) create the `cache/` directory automatically using `os.makedirs()` with `exist_ok=True` before writing cache files. The system does not require manual directory creation.