mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 18:41:07 +08:00
## Description
`GoogleCacheOptimizer` tracks Google `CachedContent` lifecycles via
`CachedContentInfo`, whose `is_expired` / `ttl_remaining_seconds` /
`age_seconds` compared a stored `expires_at` / `created_at` against a
**naive** `datetime.now()`:
```python
@property
def is_expired(self) -> bool:
return datetime.now() >= self.expires_at
```
The documented integration registers the timestamp straight off Google's
SDK:
```python
cached_content = genai.caching.CachedContent.create(model=..., contents=..., ttl=timedelta(hours=1))
optimizer.register_cache(cache_id=cached_content.name, ..., expires_at=cached_content.expire_time)
```
`CachedContent.expire_time` is a timezone-**aware** RFC3339 value.
Comparing or subtracting it against a naive `datetime.now()` raises
`TypeError: can't compare offset-naive and offset-aware datetimes`. This
crashes `register_cache` itself (it logs `ttl_remaining_seconds`), and
every consumer of `is_expired`: `get_reusable_cache`,
`cleanup_expired_caches`, and the `list_*` helpers. A single aware entry
also poisons `cleanup_expired_caches`, which iterates `is_expired` over
the whole registry. `CachedContentInfo.from_dict` reconstructs the same
aware value from a persisted `expires_at`, so the crash survives a
save/restore round-trip.
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- `headroom/cache/google.py`: added a `_now_matching(reference)` helper
that returns `datetime.now(reference.tzinfo)`, and use it in
`CachedContentInfo.is_expired`, `ttl_remaining_seconds`, and
`age_seconds`. "Now" is anchored to the same awareness as the value it
is measured against, so an aware `expires_at` compares against an aware
now, and a naive one keeps the exact prior behavior
(`datetime.now(None)` is naive local time).
- `tests/test_cache/test_google.py`: added
`test_cache_registration_accepts_aware_expiry`,
`test_cache_lookup_expired_aware`, and
`test_from_dict_roundtrip_preserves_aware_expiry`.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
### Test Output
```text
tests/test_cache/test_google.py -> 21 passed in 0.72s
uvx ruff@0.16.2 check headroom/cache/google.py tests/test_cache/test_google.py -> All checks passed!
uvx mypy@1.20.2 headroom/cache/google.py -> Success: no issues found in 1 source file
```
## Real Behavior Proof
- Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1,
ruff 0.16.2 and mypy 1.20.2 via uvx.
- Exact command / steps: before the fix, `optimizer.register_cache(...,
expires_at=datetime.now(timezone.utc) + timedelta(hours=1))` raised
`TypeError: can't subtract offset-naive and offset-aware datetimes` at
`google.py:108` (`ttl_remaining_seconds`, called from `register_cache`'s
log line). After the fix, the same call registers cleanly,
`get_reusable_cache` returns the entry, `cleanup_expired_caches` returns
`[]`, an aware past-expiry entry reports `is_expired == True`, and naive
registrations behave exactly as before (`is_expired == False`,
`ttl_remaining_seconds > 0`).
- Observed result: aware and naive expiry timestamps both work; no
`TypeError`; naive-path values unchanged.
- Not tested: no live `genai.caching.CachedContent.create` call (the
optimizer intentionally makes no API calls); the aware timestamp Google
returns is reproduced with `datetime.now(timezone.utc)`, which has the
same awareness.
## Runtime Rollout Safety
- Rollout-managed feature(s): none. `GoogleCacheOptimizer` is an
SDK-side cache lifecycle utility (`headroom.cache`), not a
rollout-channel-gated runtime feature.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: no. Naive timestamps take
`datetime.now(None)`, identical to the previous `datetime.now()`; only
the previously-crashing aware case changes, from `TypeError` to a
correct comparison.
- Kill switch / disable path: N/A.
- Unsafe override required: no.
- Qualification impact: none; behavior for existing naive callers is
byte-for-byte unchanged.
- Rollback path: revert this PR; the properties return to a naive
`datetime.now()`.
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation (N/A:
internal behavior, unchanged semantics)
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`
## Additional Notes
`_now_matching` is deliberately minimal: it does not rewrite stored
timestamps or change the serialization format, so a mixed registry of
naive and aware entries each compare correctly on their own terms. This
matches the module's existing convention of leaving caller-supplied
timestamps as-is.
323 lines
11 KiB
Python
323 lines
11 KiB
Python
"""Tests for GoogleCacheOptimizer."""
|
|
|
|
from datetime import datetime, timedelta, timezone
|
|
|
|
import pytest
|
|
|
|
from headroom.cache import CacheConfig, GoogleCacheOptimizer, OptimizationContext
|
|
from headroom.cache.base import CacheStrategy
|
|
from headroom.cache.google import (
|
|
GOOGLE_CACHE_DISCOUNT,
|
|
GOOGLE_MIN_CACHE_TOKENS,
|
|
CacheabilityAnalysis,
|
|
CachedContentInfo,
|
|
)
|
|
|
|
|
|
class TestGoogleCacheOptimizer:
|
|
"""Test GoogleCacheOptimizer functionality."""
|
|
|
|
@pytest.fixture
|
|
def optimizer(self):
|
|
"""Create optimizer instance."""
|
|
return GoogleCacheOptimizer()
|
|
|
|
@pytest.fixture
|
|
def context(self):
|
|
"""Create optimization context."""
|
|
return OptimizationContext(
|
|
provider="google",
|
|
model="gemini-1.5-pro",
|
|
)
|
|
|
|
def test_optimizer_properties(self, optimizer):
|
|
"""Test optimizer properties."""
|
|
assert optimizer.name == "google-cached-content"
|
|
assert optimizer.provider == "google"
|
|
assert optimizer.strategy == CacheStrategy.CACHED_CONTENT
|
|
|
|
def test_enforces_minimum_tokens(self):
|
|
"""Test that Google's minimum is enforced."""
|
|
config = CacheConfig(min_cacheable_tokens=100)
|
|
optimizer = GoogleCacheOptimizer(config)
|
|
assert optimizer.config.min_cacheable_tokens >= GOOGLE_MIN_CACHE_TOKENS
|
|
|
|
def test_optimize_below_threshold(self, optimizer, context):
|
|
"""Test optimization with content below threshold."""
|
|
messages = [
|
|
{"role": "system", "content": "Short system prompt."},
|
|
{"role": "user", "content": "Hello!"},
|
|
]
|
|
|
|
result = optimizer.optimize(messages, context)
|
|
|
|
assert result.metrics.cacheable_tokens < GOOGLE_MIN_CACHE_TOKENS
|
|
assert any("32K" in w for w in result.warnings)
|
|
|
|
def test_optimize_above_threshold(self, optimizer, context):
|
|
"""Test optimization with content above threshold."""
|
|
# Create content above 32K tokens
|
|
messages = [
|
|
{"role": "system", "content": "You are helpful. " * 15000},
|
|
{"role": "user", "content": "Hello!"},
|
|
]
|
|
|
|
result = optimizer.optimize(messages, context)
|
|
|
|
assert result.metrics.cacheable_tokens > 0
|
|
if result.metrics.cacheable_tokens >= GOOGLE_MIN_CACHE_TOKENS:
|
|
assert result.metrics.estimated_savings_percent == GOOGLE_CACHE_DISCOUNT * 100
|
|
|
|
def test_analyze_cacheability(self, optimizer, context):
|
|
"""Test cacheability analysis."""
|
|
messages = [
|
|
{"role": "system", "content": "Short"},
|
|
{"role": "user", "content": "Hello!"},
|
|
]
|
|
|
|
analysis = optimizer.analyze_cacheability(messages, context)
|
|
|
|
assert isinstance(analysis, CacheabilityAnalysis)
|
|
assert analysis.total_tokens > 0
|
|
assert analysis.tokens_below_minimum > 0
|
|
assert analysis.is_cacheable is False
|
|
assert len(analysis.recommendations) > 0
|
|
|
|
def test_cache_registration(self, optimizer):
|
|
"""Test registering a cache."""
|
|
cache_info = optimizer.register_cache(
|
|
cache_id="test-cache-123",
|
|
content_hash="abc123",
|
|
token_count=50000,
|
|
expires_at=datetime.now() + timedelta(hours=1),
|
|
)
|
|
|
|
assert cache_info.cache_id == "test-cache-123"
|
|
assert cache_info.content_hash == "abc123"
|
|
assert cache_info.token_count == 50000
|
|
assert not cache_info.is_expired
|
|
assert cache_info.ttl_remaining_seconds > 0
|
|
|
|
def test_cache_lookup(self, optimizer):
|
|
"""Test looking up a registered cache."""
|
|
optimizer.register_cache(
|
|
cache_id="test-cache-456",
|
|
content_hash="def456",
|
|
token_count=50000,
|
|
expires_at=datetime.now() + timedelta(hours=1),
|
|
)
|
|
|
|
found = optimizer.get_reusable_cache("def456")
|
|
assert found is not None
|
|
assert found.cache_id == "test-cache-456"
|
|
|
|
def test_cache_lookup_expired(self, optimizer):
|
|
"""Test that expired caches are not returned."""
|
|
optimizer.register_cache(
|
|
cache_id="expired-cache",
|
|
content_hash="expired123",
|
|
token_count=50000,
|
|
expires_at=datetime.now() - timedelta(hours=1),
|
|
)
|
|
|
|
found = optimizer.get_reusable_cache("expired123")
|
|
assert found is None
|
|
|
|
def test_cache_registration_accepts_aware_expiry(self, optimizer):
|
|
"""A timezone-aware ``expires_at`` must not crash lifecycle checks.
|
|
|
|
Google's ``genai.caching.CachedContent.expire_time`` is an aware
|
|
RFC3339 value, and the documented integration registers it directly.
|
|
Comparing it against a naive ``datetime.now()`` raised
|
|
``TypeError: can't compare offset-naive and offset-aware datetimes``,
|
|
which crashed ``register_cache`` itself (it logs ``ttl_remaining_seconds``)
|
|
and every ``is_expired`` consumer.
|
|
"""
|
|
aware_future = datetime.now(timezone.utc) + timedelta(hours=1)
|
|
cache_info = optimizer.register_cache(
|
|
cache_id="aware-cache",
|
|
content_hash="aware123",
|
|
token_count=50000,
|
|
expires_at=aware_future,
|
|
)
|
|
assert not cache_info.is_expired
|
|
assert cache_info.ttl_remaining_seconds > 0
|
|
assert cache_info.age_seconds >= 0
|
|
|
|
# Lookup and cleanup iterate is_expired over the registry.
|
|
assert optimizer.get_reusable_cache("aware123") is not None
|
|
assert optimizer.cleanup_expired_caches() == []
|
|
|
|
def test_cache_lookup_expired_aware(self, optimizer):
|
|
"""An already-expired aware cache is recognized as expired, not crashed."""
|
|
aware_past = datetime.now(timezone.utc) - timedelta(hours=1)
|
|
cache_info = optimizer.register_cache(
|
|
cache_id="aware-expired",
|
|
content_hash="awareexp123",
|
|
token_count=50000,
|
|
expires_at=aware_past,
|
|
)
|
|
assert cache_info.is_expired
|
|
assert optimizer.get_reusable_cache("awareexp123") is None
|
|
|
|
def test_from_dict_roundtrip_preserves_aware_expiry(self):
|
|
"""``to_dict``/``from_dict`` of an aware timestamp stays comparable."""
|
|
info = CachedContentInfo(
|
|
cache_id="rt",
|
|
content_hash="rt123",
|
|
created_at=datetime.now(timezone.utc),
|
|
expires_at=datetime.now(timezone.utc) + timedelta(hours=1),
|
|
token_count=50000,
|
|
)
|
|
restored = CachedContentInfo.from_dict(info.to_dict())
|
|
assert restored.is_expired is False
|
|
assert restored.ttl_remaining_seconds > 0
|
|
|
|
def test_cache_lookup_insufficient_ttl(self, optimizer):
|
|
"""Test that caches with insufficient TTL are not returned."""
|
|
optimizer.register_cache(
|
|
cache_id="short-ttl-cache",
|
|
content_hash="shortttl123",
|
|
token_count=50000,
|
|
expires_at=datetime.now() + timedelta(seconds=30),
|
|
)
|
|
|
|
# Default min_ttl is 60 seconds
|
|
found = optimizer.get_reusable_cache("shortttl123")
|
|
assert found is None
|
|
|
|
def test_extend_cache_ttl(self, optimizer):
|
|
"""Test extending cache TTL."""
|
|
optimizer.register_cache(
|
|
cache_id="extend-cache",
|
|
content_hash="extend123",
|
|
token_count=50000,
|
|
expires_at=datetime.now() + timedelta(hours=1),
|
|
)
|
|
|
|
new_expires = datetime.now() + timedelta(hours=2)
|
|
updated = optimizer.extend_cache_ttl("extend-cache", new_expires)
|
|
|
|
assert updated is not None
|
|
assert updated.expires_at == new_expires
|
|
|
|
def test_remove_cache(self, optimizer):
|
|
"""Test removing a cache."""
|
|
optimizer.register_cache(
|
|
cache_id="remove-cache",
|
|
content_hash="remove123",
|
|
token_count=50000,
|
|
expires_at=datetime.now() + timedelta(hours=1),
|
|
)
|
|
|
|
removed = optimizer.remove_cache("remove-cache")
|
|
assert removed is True
|
|
|
|
found = optimizer.get_reusable_cache("remove123")
|
|
assert found is None
|
|
|
|
def test_cleanup_expired_caches(self, optimizer):
|
|
"""Test cleaning up expired caches."""
|
|
# Register expired cache
|
|
optimizer.register_cache(
|
|
cache_id="cleanup-expired",
|
|
content_hash="cleanup123",
|
|
token_count=50000,
|
|
expires_at=datetime.now() - timedelta(hours=1),
|
|
)
|
|
|
|
expired_ids = optimizer.cleanup_expired_caches()
|
|
assert "cleanup-expired" in expired_ids
|
|
|
|
def test_list_caches(self, optimizer):
|
|
"""Test listing caches."""
|
|
optimizer.register_cache(
|
|
cache_id="list-cache-1",
|
|
content_hash="list1",
|
|
token_count=50000,
|
|
expires_at=datetime.now() + timedelta(hours=1),
|
|
)
|
|
optimizer.register_cache(
|
|
cache_id="list-cache-2",
|
|
content_hash="list2",
|
|
token_count=50000,
|
|
expires_at=datetime.now() + timedelta(hours=2),
|
|
)
|
|
|
|
caches = optimizer.list_caches()
|
|
assert len(caches) >= 2
|
|
|
|
def test_get_statistics(self, optimizer):
|
|
"""Test getting statistics."""
|
|
optimizer.register_cache(
|
|
cache_id="stats-cache",
|
|
content_hash="stats123",
|
|
token_count=50000,
|
|
expires_at=datetime.now() + timedelta(hours=1),
|
|
)
|
|
|
|
stats = optimizer.get_statistics()
|
|
assert "active_caches" in stats
|
|
assert "caches_created" in stats
|
|
assert stats["caches_created"] >= 1
|
|
|
|
def test_prepare_cache_creation(self, optimizer, context):
|
|
"""Test preparing cache creation parameters."""
|
|
messages = [
|
|
{"role": "system", "content": "You are helpful. " * 15000},
|
|
{"role": "user", "content": "Hello!"},
|
|
]
|
|
|
|
params = optimizer.prepare_cache_creation(messages, context)
|
|
|
|
if params is not None:
|
|
assert "contents" in params
|
|
assert "ttl" in params
|
|
assert "display_name" in params
|
|
|
|
def test_build_request_with_cache(self, optimizer):
|
|
"""Test building request with cache."""
|
|
messages = [
|
|
{"role": "system", "content": "System prompt"},
|
|
{"role": "user", "content": "User message"},
|
|
]
|
|
|
|
request = optimizer.build_request_with_cache(messages, "cache-123")
|
|
|
|
assert "cached_content" in request
|
|
assert request["cached_content"] == "cache-123"
|
|
assert "contents" in request
|
|
|
|
def test_export_import_registry(self, optimizer):
|
|
"""Test exporting and importing cache registry."""
|
|
optimizer.register_cache(
|
|
cache_id="export-cache",
|
|
content_hash="export123",
|
|
token_count=50000,
|
|
expires_at=datetime.now() + timedelta(hours=1),
|
|
)
|
|
|
|
exported = optimizer.export_cache_registry()
|
|
assert len(exported) >= 1
|
|
|
|
new_optimizer = GoogleCacheOptimizer()
|
|
imported = new_optimizer.import_cache_registry(exported)
|
|
assert imported >= 1
|
|
|
|
def test_cached_content_info_serialization(self):
|
|
"""Test CachedContentInfo serialization."""
|
|
info = CachedContentInfo(
|
|
cache_id="test",
|
|
content_hash="hash",
|
|
created_at=datetime.now(),
|
|
expires_at=datetime.now() + timedelta(hours=1),
|
|
token_count=50000,
|
|
)
|
|
|
|
data = info.to_dict()
|
|
restored = CachedContentInfo.from_dict(data)
|
|
|
|
assert restored.cache_id == info.cache_id
|
|
assert restored.content_hash == info.content_hash
|
|
assert restored.token_count == info.token_count
|