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
# Contact support for CloudFormation templates
aws cloudformation create-stack \
  --stack-name cachee-ai-production \
  --template-url <provided-by-support> \
  --parameters \
      ParameterKey=VPC,ParameterValue=vpc-12345 \
      ParameterKey=Subnets,ParameterValue=subnet-abc\\,subnet-def \
      ParameterKey=CacheSize,ParameterValue=100 \
      ParameterKey=InstanceType,ParameterValue=<recommended-instance-type> \
  --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

export CACHEE_API_KEY="ck_live_xxxxxxxxxxxxxxxxxxxx"

# Node.js
npm install @cachee/sdk

# Python
pip install cachee

import { CacheeClient } from '@cachee/sdk'

const cache = new CacheeClient({
  apiKey: process.env.CACHEE_API_KEY,
  region: 'auto',        // routes to nearest edge
  fallback: 'local',     // in-memory LRU if server unreachable
  timeout: 2000          // ms
})

// Your first cache operation
await cache.set('user:1234', { name: 'Alice', plan: 'scale' }, { ttl: 300 })
const user = await cache.get('user:1234')
console.log(user) // { name: 'Alice', plan: 'scale' }

// GET — retrieve a cached value
const val = await cache.get('key')

// SET — store with optional TTL (seconds)
await cache.set('key', value, { ttl: 300 })

// DEL — remove a key
await cache.del('key')

// EXISTS — check if a key exists
const exists = await cache.exists('key')  // boolean

// MSET — batch set multiple keys
await cache.mset([
  { key: 'a', value: 1, ttl: 60 },
  { key: 'b', value: 2, ttl: 60 },
  { key: 'c', value: 3, ttl: 60 }
])

const cache = new CacheeClient({
  apiKey: process.env.CACHEE_API_KEY,

  // Region: 'auto' (nearest), or explicit: 'us-east-1', 'eu-west-1', 'ap-southeast-1'
  region: 'auto',

  // Fallback: 'local' (in-memory LRU), 'none' (throw on disconnect), or 'stale' (serve expired)
  fallback: 'local',

  // Timeout in ms for each operation
  timeout: 2000,

  // Max keys in local fallback LRU (default: 10000)
  fallbackMaxKeys: 10000,

  // Retry: exponential backoff on transient failures
  retries: 3,
  retryDelay: 200  // ms, doubles each retry
})

services:
  your-app:
    image: your-app:latest
    environment:
      # Point your existing Redis client here:
      REDIS_HOST: cachee-sidecar
      REDIS_PORT: "6379"
    depends_on:
      - cachee-sidecar

  cachee-sidecar:
    image: cacheeai/sidecar:latest
    environment:
      CACHEE_API_KEY: ${CACHEE_API_KEY}
      CACHEE_MODE: sidecar
      RESP_PORT: "6379"
      L1_MAX_KEYS: "1000000"
      L1_DEFAULT_TTL: "600"
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: '0.5'
    healthcheck:
      test: ["CMD", "redis-cli", "-p", "6379", "PING"]
      interval: 10s
      timeout: 3s
      retries: 3

apiVersion: v1
kind: Pod
metadata:
  name: app-with-cachee
spec:
  containers:
    - name: your-app
      image: your-app:latest
      env:
        - name: REDIS_URL
          value: "redis://localhost:6379"

    - name: cachee-sidecar
      image: cacheeai/sidecar:latest
      env:
        - name: CACHEE_API_KEY
          valueFrom:
            secretKeyRef:
              name: cachee-secrets
              key: api-key
        - name: CACHEE_MODE
          value: "sidecar"
        - name: RESP_PORT
          value: "6379"
      ports:
        - containerPort: 6379
          name: redis
      resources:
        requests:
          memory: "64Mi"
          cpu: "100m"
        limits:
          memory: "256Mi"
          cpu: "500m"
      livenessProbe:
        tcpSocket:
          port: 6379
        initialDelaySeconds: 5
        periodSeconds: 10
      readinessProbe:
        tcpSocket:
          port: 6379
        initialDelaySeconds: 3
        periodSeconds: 5

# Pull and run the Cachee agent
docker run -d \
  --name cachee-agent \
  -e CACHEE_CONNECT_TOKEN="ct_live_xxxxxxxxxxxx" \
  -e CACHEE_REGION="us-east-1" \
  -p 6379:6379 \
  -p 3000:3000 \
  cacheeai/agent:latest

# The agent will:
# 1. Authenticate with the control plane using your token
# 2. Download your configuration and AI models
# 3. Start serving Redis protocol on port 6379
# 4. Begin sending operational metrics to the control plane

# Test Redis protocol
redis-cli -h localhost -p 6379 PING
# → PONG

# Test a SET/GET cycle
redis-cli -h localhost -p 6379 SET hello world
# → OK
redis-cli -h localhost -p 6379 GET hello
# → "world"

# Check agent health
curl http://localhost:3000/health
# → {"status":"ok","mode":"self-hosted","connected":true}

docker run -d \
  --name cachee-agent \
  -e CACHEE_CONNECT_TOKEN="ct_live_xxxxxxxxxxxx" \
  -e HTTPS_PROXY="http://your-proxy:8080" \
  -e CONTROL_PLANE_URL="https://api.cachee.ai" \
  -p 6379:6379 \
  cacheeai/agent:latest