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

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.

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

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

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

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

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

# 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 and github.py.

Summary

• The caching mechanism is controlled by the DEVELOPMENT_MODE flag in 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 at line 6. This central configuration variable controls whether the caching logic in score.py and github.py checks for and writes to cache files.

How does the resume cache handle corrupted JSON files?

When 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 (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 (lines 259-261) and 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.

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