feat: Add comprehensive Caching System for performance optimization

- Create cache/ module with LRU memory cache and optional Redis support
- Implement CacheManager with configurable TTL per data type
- Add cache invalidation by pattern and prefix clearing
- Support for dataclass serialization and decorator-based caching
- Implement cache statistics tracking (hit/miss rates)
- Add 40 comprehensive tests (29 unit, 11 integration)
- Configure sensible TTLs: 1 day for market hours, 1 hour for assets, etc.

Features:
- LRU in-memory cache with size limits
- Optional Redis backend with automatic fallback
- Per-data-type TTL configuration
- Cache key generation with hash for long keys
- Thread-safe concurrent access
- Decorator for easy function result caching
- Pattern-based cache invalidation
- Detailed statistics tracking

This completes Phase 3 of the v3.0.0 development plan.
All Performance & Quality features are now implemented.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: TexasCoding

DEVELOPMENT_PLAN.md

@@ -230,20 +230,22 @@ main
 - Clear error messages for feed issues
 - Configuration for preferred feeds
 
-#### 3.3 Caching System ⬜
+#### 3.3 Caching System ✅
 **Branch**: `feature/caching-system`
 **Priority**: 🟢 Medium
 **Estimated Time**: 3 days
+**Actual Time**: < 1 day
+**Completed**: 2025-01-16
 
 **Tasks**:
-- [ ] Create `cache/` module structure
-- [ ] Implement `CacheManager` class
-- [ ] Add LRU in-memory cache
-- [ ] Add optional Redis support
-- [ ] Implement cache invalidation logic
-- [ ] Configure TTL per data type
-- [ ] Add comprehensive tests (10+ test cases)
-- [ ] Update documentation
+- [x] Create `cache/` module structure
+- [x] Implement `CacheManager` class
+- [x] Add LRU in-memory cache
+- [x] Add optional Redis support
+- [x] Implement cache invalidation logic
+- [x] Configure TTL per data type
+- [x] Add comprehensive tests (40 test cases: 29 unit, 11 integration)
+- [x] Update documentation
 
 **Acceptance Criteria**:
 - Configurable caching per data type
@@ -298,13 +300,13 @@ main
 
 ## 📈 Progress Tracking
 
-### Overall Progress: 🟦 67% Complete
+### Overall Progress: 🟦 75% Complete
 
 | Phase | Status | Progress | Estimated Completion |
 |-------|--------|----------|---------------------|
 | Phase 1: Critical Features | ✅ Complete | 100% | Week 1 |
 | Phase 2: Important Enhancements | ✅ Complete | 100% | Week 2 |
-| Phase 3: Performance & Quality | 🟦 In Progress | 67% | Week 7 |
+| Phase 3: Performance & Quality | ✅ Complete | 100% | Week 2 |
 | Phase 4: Advanced Features | ⬜ Not Started | 0% | Week 10 |
 
 ### Feature Status Legend

src/py_alpaca_api/cache/__init__.py

@@ -0,0 +1,9 @@
+"""Cache module for py-alpaca-api.
+
+This module provides caching functionality to improve performance and reduce API calls.
+"""
+
+from .cache_config import CacheConfig, CacheType
+from .cache_manager import CacheManager
+
+__all__ = ["CacheManager", "CacheConfig", "CacheType"]

src/py_alpaca_api/cache/cache_config.py

@@ -0,0 +1,68 @@
+"""Cache configuration for py-alpaca-api."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class CacheType(Enum):
+    """Types of cache backends supported."""
+
+    MEMORY = "memory"
+    REDIS = "redis"
+    DISABLED = "disabled"
+
+
+@dataclass
+class CacheConfig:
+    """Configuration for cache system.
+
+    Attributes:
+        cache_type: Type of cache backend to use
+        max_size: Maximum number of items in memory cache
+        default_ttl: Default time-to-live in seconds
+        data_ttls: TTL overrides per data type
+        redis_host: Redis host (if using Redis)
+        redis_port: Redis port (if using Redis)
+        redis_db: Redis database number (if using Redis)
+        redis_password: Redis password (if using Redis)
+        enabled: Whether caching is enabled
+    """
+
+    cache_type: CacheType = CacheType.MEMORY
+    max_size: int = 1000
+    default_ttl: int = 300  # 5 minutes default
+    data_ttls: dict[str, int] = field(
+        default_factory=lambda: {
+            "market_hours": 86400,  # 1 day
+            "calendar": 86400,  # 1 day
+            "assets": 3600,  # 1 hour
+            "account": 60,  # 1 minute
+            "positions": 10,  # 10 seconds
+            "orders": 5,  # 5 seconds
+            "quotes": 1,  # 1 second
+            "bars": 60,  # 1 minute
+            "trades": 60,  # 1 minute
+            "news": 300,  # 5 minutes
+            "watchlists": 300,  # 5 minutes
+            "snapshots": 1,  # 1 second
+            "metadata": 86400,  # 1 day (condition codes, exchanges)
+        }
+    )
+    redis_host: str = "localhost"
+    redis_port: int = 6379
+    redis_db: int = 0
+    redis_password: str | None = None
+    enabled: bool = True
+
+    def get_ttl(self, data_type: str) -> int:
+        """Get TTL for a specific data type.
+
+        Args:
+            data_type: Type of data to get TTL for
+
+        Returns:
+            TTL in seconds
+        """
+        return self.data_ttls.get(data_type, self.default_ttl)