Redis Backend for State Persistence

Redis-based state persistence with advanced features including compression, versioning, and performance optimization.

Features

• High Performance: Redis for fast state operations
• Compression Support: LZ4 and zlib compression
• Version Management: Automatic versioning with rollback
• TTL Support: Automatic expiration of states
• Connection Pooling: Efficient connection management
• Data Integrity: Checksum verification

Quick Start

from recoagent.state import RedisStatePersistence, CompressionType

# Basic Redis configuration
persistence = RedisStatePersistence(
    redis_url="redis://localhost:6379/0",
    compression_type=CompressionType.LZ4,
    enable_versioning=True,
    max_versions=10,
    default_ttl=3600
)

# Save state
persistence.save_with_metadata(
    state={"user_id": "123", "data": "important_data"},
    state_id="user_session_123",
    version=1,
    tags=["user", "session"]
)

# Load state
result = persistence.load_with_metadata("user_session_123")
if result:
    state, metadata = result
    print(f"State: {state}")
    print(f"Version: {metadata.version}")

Configuration Options

Basic Configuration

persistence = RedisStatePersistence(
    redis_url="redis://localhost:6379/0",
    compression_type=CompressionType.LZ4,
    enable_versioning=True,
    max_versions=10,
    default_ttl=3600
)

Advanced Configuration

persistence = RedisStatePersistence(
    redis_url="redis://localhost:6379/0",
    compression_type=CompressionType.LZ4,
    enable_versioning=True,
    max_versions=20,
    default_ttl=7200,
    # Redis connection options
    redis_options={
        "socket_timeout": 5,
        "socket_connect_timeout": 5,
        "retry_on_timeout": True,
        "decode_responses": False,
        "max_connections": 20
    }
)

Compression Types

LZ4 Compression (Recommended)

persistence = RedisStatePersistence(
    redis_url="redis://localhost:6379/0",
    compression_type=CompressionType.LZ4  # Fast compression
)

Zlib Compression

persistence = RedisStatePersistence(
    redis_url="redis://localhost:6379/0",
    compression_type=CompressionType.ZLIB  # High compression
)

No Compression

persistence = RedisStatePersistence(
    redis_url="redis://localhost:6379/0",
    compression_type=CompressionType.NONE  # No compression
)

Performance Optimization

Connection Pooling

persistence = RedisStatePersistence(
    redis_url="redis://localhost:6379/0",
    redis_options={
        "max_connections": 20,
        "retry_on_timeout": True,
        "socket_keepalive": True,
        "socket_keepalive_options": {}
    }
)

Memory Management

# Monitor Redis memory usage
stats = persistence.get_stats()
if 'redis_info' in stats:
    used_memory = stats['redis_info']['used_memory']
    print(f"Redis memory usage: {used_memory}")
    
    # Clean up old versions if memory is high
    if used_memory > "100MB":
        for state_id in persistence.list_states():
            versions = persistence.list_versions(state_id)
            if len(versions) > 5:
                for version in versions[:-5]:
                    persistence.delete_version(state_id, version.version)

Best Practices

1. Use LZ4 Compression: Best balance of speed and compression
2. Set Appropriate TTL: Based on state lifetime
3. Monitor Memory: Track Redis memory usage
4. Connection Pooling: Configure appropriate pool size
5. Version Management: Keep reasonable number of versions
6. Error Handling: Implement proper error handling

Troubleshooting

Common Issues

1. Connection Errors: Check Redis server and connection string
2. Memory Issues: Monitor Redis memory usage
3. Compression Errors: Check LZ4/zlib installation
4. Performance Issues: Optimize connection pool and compression

Debug Mode

import logging
logging.getLogger('recoagent.state.persistence').setLevel(logging.DEBUG)

API Reference

RedisStatePersistence

Parameter	Type	Description
redis_url	str	Redis connection URL
compression_type	CompressionType	Compression type
enable_versioning	bool	Enable versioning
max_versions	int	Maximum versions to keep
default_ttl	int	Default TTL in seconds
redis_options	Dict	Redis connection options