SDK Documentation

# Simple key
@cachee.cache(key="users_list")
def get_all_users():
    return db.query("SELECT * FROM users")

# Dynamic key with parameter
@cachee.cache(key="user:{user_id}")
def get_user(user_id):
    return db.query("SELECT * FROM users WHERE id = ?", user_id)

# Composite key with multiple parameters
@cachee.cache(key="products:{category}:{page}")
def get_products(category, page):
    return db.query("SELECT * FROM products WHERE category = ? LIMIT ? OFFSET ?",
                    category, 20, page * 20)

# Complex key with custom serialization
@cachee.cache(key="search:{query}:{filters_hash}")
def search_products(query, filters):
    filters_hash = hashlib.md5(json.dumps(filters).encode()).hexdigest()
    return db.search(query, filters)

@cachee.cache(
    key: str,                          # Cache key with parameter interpolation
    ttl_strategy: str = "adaptive",    # TTL strategy: adaptive, fixed, stale-while-revalidate, time-based, no-ttl
    ttl: int = None,                   # TTL in seconds (required if ttl_strategy="fixed")
    namespace: str = None,             # Logical grouping for related cache entries
    version: str = "1",                # Cache version for schema changes
    warm_cache: bool = False,          # Pre-compute during off-peak hours
    fallback_on_error: bool = False,   # Serve stale data if function raises error
    compress: bool = True,             # Compress large payloads (>10KB)
    serialize: str = "json",           # Serialization: json, pickle, msgpack
    tags: List[str] = None,            # Tags for bulk invalidation
    conditions: Dict = None,           # Conditional caching rules
    ai_enabled: bool = True,           # Enable AI features
    metrics: bool = True,              # Track performance metrics
    local_cache: bool = True,          # Enable in-memory L1 cache
    distributed: bool = True,          # Use distributed cache (Redis/Memcached)
)

# Example 1: API calls with fallback
@cachee.cache(
    key="github:user:{username}",
    ttl_strategy="fixed",
    ttl=300,  # 5 minutes
    fallback_on_error=True,  # Serve stale if GitHub is down
    tags=["external_api", "github"]
)
def get_github_user(username):
    response = httpx.get(f"https://api.github.com/users/{username}")
    return response.json()

# Example 2: Expensive aggregation with cache warming
@cachee.cache(
    key="analytics:dashboard:{org_id}",
    ttl_strategy="adaptive",
    warm_cache=True,  # Pre-compute at 2 AM daily
    compress=True,
    namespace="analytics"
)
def get_dashboard_analytics(org_id):
    # Expensive multi-table aggregation
    return db.run_analytics_query(org_id)

# Example 3: User-specific data with namespace
@cachee.cache(
    key="user:{user_id}:preferences",
    namespace="users",
    version="2",  # Increment when schema changes
    tags=["users", "preferences"],
    serialize="json"
)
def get_user_preferences(user_id):
    return db.query("SELECT * FROM user_preferences WHERE user_id = ?", user_id)

# Example 4: Conditional caching based on request size
@cachee.cache(
    key="search:{query}",
    conditions={
        "cache_if": lambda result: len(result) > 0,  # Only cache non-empty results
        "skip_if": lambda query: len(query) < 3      # Don't cache short queries
    }
)
def search(query):
    return db.full_text_search(query)

# Enable automatic cache warming
@cachee.cache(
    key="analytics:{org_id}",
    warm_cache=True  # AI will determine best time to warm
)
def get_analytics(org_id):
    return expensive_aggregation(org_id)

# Manual cache warming (useful for migrations)
cachee.warm_cache(
    function=get_analytics,
    params=[{"org_id": id} for id in active_org_ids],
    schedule="0 2 * * *"  # Every day at 2 AM
)

# Warm cache for specific keys
cachee.warm_keys([
    "analytics:org_123",
    "analytics:org_456",
    "analytics:org_789"
])

# Warm entire namespace
cachee.warm_namespace("analytics", concurrency=10)

# Get real-time metrics
metrics = cachee.get_metrics(
    namespace="users",
    time_range="last_24h"
)

print(f"Cache Hit Rate: {metrics['hit_rate']}%")
print(f"Avg Latency: {metrics['latency_p50']}ms")
print(f"Cost Savings: ${metrics['cost_savings']}")

# Get AI predictions
predictions = cachee.get_ai_predictions(
    key="user:{user_id}"
)

print(f"Predicted next access: {predictions['next_access_time']}")
print(f"Recommended TTL: {predictions['recommended_ttl']}s")
print(f"Confidence: {predictions['confidence']}%")

# Export metrics to Prometheus
from prometheus_client import start_http_server
cachee.enable_prometheus_exporter(port=9090)

# Send metrics to CloudWatch
cachee.enable_cloudwatch_metrics(
    namespace="Cachee",
    region="us-west-2"
)

# 1. Use local L1 cache for hot data
@cachee.cache(
    key="config:app_settings",
    local_cache=True,          # In-memory cache
    local_ttl=60,              # 60 seconds in memory
    distributed_ttl=300        # 5 minutes in Redis
)
def get_app_config():
    return db.query("SELECT * FROM config")

# 2. Batch operations when possible
@cachee.cache_batch(
    key="user:{user_id}",
    batch_size=100
)
def get_users_batch(user_ids):
    return db.query("SELECT * FROM users WHERE id IN (?)", user_ids)

# 3. Use stale-while-revalidate for high-traffic endpoints
@cachee.cache(
    key="homepage:feed",
    ttl_strategy="stale-while-revalidate",
    ttl=300,                   # Serve stale after 5 minutes
    grace_period=3600          # But keep serving stale for up to 1 hour
)
def get_homepage_feed():
    return expensive_feed_query()

# 4. Conditional caching for variable-cost operations
@cachee.cache(
    key="search:{query}",
    conditions={
        "cache_if": lambda result: len(result) > 10,  # Only cache if many results
        "ttl_if": lambda result: 3600 if len(result) > 100 else 300  # Dynamic TTL
    }
)
def search(query):
    return search_engine.query(query)

# Deploy via AWS Marketplace CloudFormation
aws cloudformation create-stack \
  --stack-name cachee-ai-production \
  --template-url https://s3.amazonaws.com/cachee-cf-templates/latest.yaml \
  --parameters \
      ParameterKey=VPC,ParameterValue=vpc-12345 \
      ParameterKey=Subnets,ParameterValue=subnet-abc\\,subnet-def \
      ParameterKey=CacheSize,ParameterValue=100 \
      ParameterKey=InstanceType,ParameterValue=cache.r6g.xlarge \
  --capabilities CAPABILITY_IAM

# Or use our CLI
cachee-cli deploy aws \
  --region us-west-2 \
  --vpc vpc-12345 \
  --subnets subnet-abc,subnet-def \
  --cache-size 100GB