Skip to content

feat: added caching and offline support for categories and languages

Mohana Sri Bhavitha requested to merge offline-cache-support into develop

🚀 Merge Request Title

feat: add caching and offline support for categories and languages

🧾 Summary

This merge request introduces a local caching layer for categories and languages data in the Corpus CLI.
The goal is to enable offline access, improve resilience, and reduce repeated API calls for stable reference data.

✨ Features Implemented

  • Automatic Caching
    Categories and languages are cached locally at ~/.corpus/cache.json after successful API calls.
  • API Fallback
    When the API is unavailable or fails, the CLI automatically falls back to cached data.
  • Offline Mode (--offline)
    Uses only cached data without making any API calls.
  • Refresh Mode (--refresh)
    Forces a fresh API request and updates the cache.

💻 CLI Usage

Default Behavior

Fetches data from API and falls back to cache if needed:

corpus-client categories corpus-client languages

Offline Mode

Uses only cached data:

corpus-client categories --offline

Refresh Mode

Forces API fetch and updates cache:

corpus-client categories --refresh

⚙️ Behavior Summary

Mode Behavior
Default API → fallback to cache
--offline Cache only (error if no cache)
--refresh Force API → update cache

🏗️ Implementation Details

  • Cache Location: ~/.corpus/cache.json

  • Cache Structure:

    { "base_url": "...", "categories": [], "languages": [], "fetched_at": "" }

  • Base URL Validation:
    Cache is only used if base_url matches the current environment (prevents cross-environment conflicts).

  • Reusable Helper:
    Introduced _get_with_cache() to eliminate duplication and centralize caching logic.

📁 Files Changed

  • src/corpus_client_cli/cli.py
    → Added categories/languages commands with --offline and --refresh flags
  • src/corpus_client_cli/utils/cache_manager.py
    → New cache utility functions (load_cache, save_cache, update_cache)
  • src/corpus_client_cli/utils/__init__.py
    → Package initialization
  • tests/test_cache_manager.py
    → Added 10 unit tests for cache functionality
  • README.md
    → Updated with caching and CLI usage documentation

🧪 Testing

  • ✅ All 44 tests passing
  • ✅ Ruff linting passed
  • ✅ Mypy type checking passed

📸 Screenshots

CLI Help

`$ corpus-client categories --help

Usage: categories [OPTIONS]

Options: --offline Use cached data only --refresh Force refresh from API`

Offline Mode

`$ corpus-client categories --offline

Using cached categories data (offline mode)

  1. Category 1 (abc-123)`

✅ Final Checklist

  • Feature works end-to-end
    • Handles API failure gracefully
    • Supports offline and refresh modes
    • Tests added and passing
    • Documentation updated
    • Ready for review 🚀

Merge request reports