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

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.

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

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 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

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

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:

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:

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, 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 or via environment variables before deployment.

What happens if the cache file is corrupted?

Both score.py (lines 237–244) and 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.

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