Add caching for parsed syllabus data

[schmerl]

Cache Requirements for SyllabusMCP

Overview

Add caching capabilities to store parsed syllabus information to improve performance and reduce redundant processing.

Background

Currently, the system:

• Parses PDF syllabi on-demand using extract_pdf_text() and LLM parsing
• Generates academic plans from parsed syllabi using LLM orchestration
• Has no persistence layer, requiring re-parsing and re-generation on every request

This leads to:

• Unnecessary PDF re-parsing for the same syllabus files
• Wasted LLM API calls for identical syllabus content
• Slow response times for repeated queries
• No ability to retrieve previously generated plans

Scope

In Scope

1. Syllabus Cache: Store parsed ParsedSyllabus objects
2. Cache key generation based on syllabus content (SHA-256 hash of raw PDF bytes)
3. Cache invalidation mechanisms
4. Cache persistence (survive application restarts) in system cache directory
5. Basic cache statistics and management

Out of Scope

• Academic Plan caching (plans are ephemeral and not cached)
• Distributed caching across multiple instances
• Cache warming strategies
• Advanced eviction policies (LRU, LFU, etc.)
• Cache size limits or quotas
• Versioning of cached data structures
• Cache encryption
• Time-based cache expiry
• MCP tool integration for cache operations

Functional Requirements

FR1: Syllabus Cache Storage

• FR1.1: Store ParsedSyllabus objects indexed by a unique key
• FR1.2: Support both local file paths and URLs as syllabus sources
• FR1.3: Generate cache keys based on syllabus content hash (not filename)
• FR1.4: Retrieve cached ParsedSyllabus by key
• FR1.5: Check if a syllabus is cached without loading full content

FR2: Cache Invalidation

• FR2.1: Ability to invalidate specific cached syllabi by key
• FR2.2: Ability to clear all cached syllabi

FR3: Cache Persistence

• FR3.1: Cache data persists across application restarts
• FR3.2: Cache stored in system cache directory (~/.cache/syllabusmcp/ on macOS/Linux)
• FR3.3: Graceful handling of corrupted cache files

FR4: Cache Management

• FR4.1: List all cached syllabus keys
• FR4.2: Get cache statistics (count, size, last access time)
• FR4.3: Export cached data for inspection

Non-Functional Requirements

NFR1: Performance

• Cache lookup should be fast (<10ms for key existence check)
• Cache retrieval should be significantly faster than re-parsing (>80% time savings)

NFR2: Reliability

• Cache failures should not break the application (graceful degradation)
• Corrupted cache entries should be detected and skipped
• Application should work correctly even with empty cache

NFR3: Maintainability

• Cache implementation should be modular and testable
• Clear separation between cache logic and business logic
• Type-safe interfaces using dataclasses

NFR4: Storage Efficiency

• Use pickle for serialization (preserves Python types)
• Avoid duplicate storage of identical content
• Content-addressable storage (SHA-256 hash of raw PDF bytes)

NFR5: Developer Experience

• Simple API for cache operations (get, set, invalidate)
• Clear logging of cache hits/misses
• Easy to disable caching for testing

User Stories

US1: Avoid Re-parsing Unchanged Syllabi

As a user
I want the system to remember previously parsed syllabi
So that I don't wait for re-parsing when querying the same syllabus multiple times

US2: Invalidate Outdated Cache

As a developer
I want to invalidate cached entries when source files change
So that the system doesn't serve stale data

US3: Inspect Cache Contents

As a developer
I want to view what's in the cache
So that I can debug issues and understand cache behavior

US4: Clear Cache for Testing

As a developer
I want to easily clear the cache
So that I can test cache-miss behavior and start fresh

Design Decisions

1. Serialization Format: Use pickle for efficient Python object serialization
2. Cache Location: System cache directory (~/.cache/syllabusmcp/ on macOS/Linux)
3. Content Hashing: Hash raw PDF bytes (before text extraction) for cache keys
4. Plan Caching: Not implemented - plans are ephemeral and generated on-demand
5. Cache Expiry: Not implemented - manual invalidation only
6. MCP Integration: Cache operations are internal only, not exposed as MCP tools

Success Criteria

1. ✅ 80%+ reduction in parsing time for repeated syllabus queries
2. ✅ 100% reduction in LLM calls for cached syllabi
3. ✅ Zero cache-related crashes or data loss
4. ✅ Cache survives application restarts
5. ✅ Comprehensive test coverage (>80%)
6. ✅ Clear documentation for cache usage