cledar-sdk 1.2.1__py3-none-any.whl → 1.4.0__py3-none-any.whl

{cledar_sdk-1.2.1.dist-info → cledar_sdk-1.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cledar-sdk
-Version: 1.2.1
+Version: 1.4.0
 Summary: Cledar Python SDK
 Author: Cledar
 License-File: LICENSE

{cledar_sdk-1.2.1.dist-info → cledar_sdk-1.4.0.dist-info}/RECORD

@@ -3,13 +3,13 @@ common_logging/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 common_logging/universal_plaintext_formatter.py,sha256=ExuXwfZmc_4tp3RIsoe_ByYpnTN0iQBOi101FB8hksc,3309
 common_logging/tests/test_universal_plaintext_formatter.py,sha256=bY6vvpra81_YXN2MLVjNuA8Iu7kOaZH0lmQMsohjRPI,8560
 kafka_service/README.md,sha256=3lKulsfEUs6qaKExlpPkxT_X1NYBAHraiqQRdvkQ48I,7021
-kafka_service/__init__.py,sha256=yHPDvgkwcM4vtJ2nvSsw9Sc0XqEoWUwhewRXH7x1V3A,1012
+kafka_service/__init__.py,sha256=YejBYb9sS5d0VLuYg48vqKWTWSTwlEnsGF_2Z3guXAQ,1131
 kafka_service/exceptions.py,sha256=LJ-mUYCwoQsDM-bL4ms9ZCiWIOw5kt1KStbN04Mavl0,501
 kafka_service/logger.py,sha256=jdZSJnuPpUXEwG5eLKlQMLkVxaKwuma_o9udbOAjXo0,60
 kafka_service/clients/base.py,sha256=LhiCF9vNxn-kCWld4Xfzy1lYCUj7PbhJhNURE7wIx70,3692
-kafka_service/clients/consumer.py,sha256=xgeXoS6J67YZ7w3QbhdiGkzD99RNeLteObDeXBGzDTw,3959
-kafka_service/clients/producer.py,sha256=1kLaeWoHb9y7NYkdk7cW_2Lz3UY0podj-9mVOIwWIko,2862
-kafka_service/config/schemas.py,sha256=tYw1cFBM4JPkHTxKNsTfpkA2OQ0wUkyeBu_Kfgb2cyI,3840
+kafka_service/clients/consumer.py,sha256=m0u-Q2HXLk7pD4z2ucwaQxavW3VATbvVD1fDTSAi0tA,3590
+kafka_service/clients/producer.py,sha256=oJMZ9zg7n-DFWrySu-xveQ70ZXZEQkuXE0ewMeLLKoo,2605
+kafka_service/config/schemas.py,sha256=ToAv2d3F7mMpuePBWsC12jugdMWLPQMoNCXub0VIbgE,6550
 kafka_service/handlers/dead_letter.py,sha256=Y4krNONrMayaYsvFZrXh-pRK8kfyWibEYrUyDLy-XH8,2552
 kafka_service/handlers/parser.py,sha256=BsEUFI5bDBQzf9f9s7XClk_TfEXveOG5yCTT4sOibPI,1475
 kafka_service/models/input.py,sha256=VEf9DDbXew4tJSHP7cEbXWW3k6s_1gN8QGcqs5LmxuU,254
@@ -27,7 +27,7 @@ kafka_service/tests/integration/test_producer_consumer_interaction.py,sha256=7Z6
 kafka_service/tests/integration/test_producer_integration.py,sha256=0NXNB5gN0hPSXj5j2oP9FlhAXrNVpNg5N_1DkGOHUy0,6438
 kafka_service/tests/unit/__init__.py,sha256=uiWL_3JORErRzHi12hW0-kFU36zdkl3MBg4_qtH6TM0,36
 kafka_service/tests/unit/test_base_kafka_client.py,sha256=6O31wIuoKkb-EEqD-a5PjB-zbM0h5vTFz1VGr9V3KVQ,13321
-kafka_service/tests/unit/test_config_validation.py,sha256=H_kjbmeHWbjA8a8vMZm0dZjsDhznYSom5X_lm3bY5zs,16907
+kafka_service/tests/unit/test_config_validation.py,sha256=KpMAI_5s-XWOW_bNT9rTie61eoet4kkB7YTFd9W2hOE,19971
 kafka_service/tests/unit/test_dead_letter_handler.py,sha256=qsJZKXm_fBZUnaDwBAF7Bj9aS-y7Uxc-e7u6pPQLTgc,13905
 kafka_service/tests/unit/test_error_handling.py,sha256=h91hwG02DwGEZrziSv0mLshQFK98p-P38g4gWPHuyyY,22828
 kafka_service/tests/unit/test_input_parser.py,sha256=_MIWkvhYRZR_7lg9Jo_MD3ckCTGrMrSyeR_7F5wrHSw,11556
@@ -52,14 +52,17 @@ nonce_service/__init__.py,sha256=Rh6JWML_ncfb_t_mVl7PIKOXpELRdfunMsFWAtbt5EE,68
 nonce_service/nonce_service.py,sha256=6RhA2eEztH_pNdjkBI5eqmRh14I96NjgVYy2v_z7vdM,1100
 nonce_service/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nonce_service/tests/test_nonce_service.py,sha256=sWzCBXghZNDOnSo8NQB6tyJJ95g2tZGRPlThFqD2P7g,4047
-redis_service/README.md,sha256=GFzNRpCvPRl-QoOFiDTmj1ncgUoU_HaJV74zVtdwG9M,10176
-redis_service/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+redis_service/README.md,sha256=rsIieAu4TwjoeIbHG30x3t3TyR9P9Ulcy69gdfG_jRg,14632
+redis_service/__init__.py,sha256=SgTAyteZ3pPV8R608-EQ84RmytUfSQaPGl0UJxLnGL0,250
+redis_service/async_example.py,sha256=m8dkSspJK8yti9U_Q3_Sc9XW1aq3RYL4EzBdLx5_u84,2949
 redis_service/example.py,sha256=OApl0JU59viBUZORLxlYBhVMdCc5QvOBdOjscxbm_aQ,1091
 redis_service/exceptions.py,sha256=vvD7SO0xHutSLvUf0ttMo7C6OeaVi8f3bxMservsSVI,737
 redis_service/logger.py,sha256=OBOTx6zk_6wkpB2N_FRV7gXR3xy4dpy4iX2B0oFfZ90,60
 redis_service/model.py,sha256=ykW_KHygNHhfHPvP2RyJj0g_WENXxJEP2HvGy7Yb4uo,174
-redis_service/redis.py,sha256=d8hqkVokVs6eMsteJEsEYZ56nb7WhTQ8Gc_sT4zkSRY,9974
+redis_service/redis.py,sha256=DuWaXMU5RhAW2Rf9T-Hg_1FIrQqkPin1vTXQMJJ6Sno,19817
 redis_service/redis_config_store.py,sha256=EFhyvg_Eklrh2tc5dtFpe6nnjMDkTqYT_egclhf0KaI,8919
+redis_service/tests/test_async_integration_redis.py,sha256=I-rWvOm9Cnpl8AZcrPb58tTbkq_YKh3WR2bwXB-EJRM,5005
+redis_service/tests/test_async_redis_service.py,sha256=DgzBZscXu_FiV6QIZT2AHQ0rk_Zwzu2HmsifeDhArRU,12501
 redis_service/tests/test_integration_redis.py,sha256=O3z5EgkeB6Sd9C1S3rRMW916bybDCAHb-DgTFZGLTqI,3345
 redis_service/tests/test_redis_service.py,sha256=n3FIYBk9SGzpDkRWnPj-Mi3NKYtDEpbwgjpjb_JwjF4,10252
 storage_service/README.md,sha256=Rkew1joVijHVEfyXS9C7dDw55rQ4HYRbHkRYlZiREak,15655
@@ -74,7 +77,7 @@ storage_service/tests/test_integration_filesystem.py,sha256=-H3Skc_geYIjXW1si-8u
 storage_service/tests/test_integration_s3.py,sha256=Ivg_52LXibqVGMS-53z4zda_Yh4u6FO8WplUUu5WWBc,13614
 storage_service/tests/test_local.py,sha256=3CgtxQ_lBBaPR4t9Ip0i7T98scrTOCdkmHYMVansNCc,11256
 storage_service/tests/test_s3.py,sha256=zAppsvVCeLx_NN1tQfqHo57mONEjeFDmiwyecrS3ZgQ,16355
-cledar_sdk-1.2.1.dist-info/METADATA,sha256=9087LMoW_Hd1TC5jwPFbg_w8a43r1ug9ssJJ_02gEzA,6752
-cledar_sdk-1.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-cledar_sdk-1.2.1.dist-info/licenses/LICENSE,sha256=Pz2eACSxkhsGfW9_iN60pgy-enjnbGTj8df8O3ebnQQ,16726
-cledar_sdk-1.2.1.dist-info/RECORD,,
+cledar_sdk-1.4.0.dist-info/METADATA,sha256=KY0mpTdaySyoD8xe8RDSEM0IZRFrF2rLCwNAy1SBcjg,6752
+cledar_sdk-1.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cledar_sdk-1.4.0.dist-info/licenses/LICENSE,sha256=Pz2eACSxkhsGfW9_iN60pgy-enjnbGTj8df8O3ebnQQ,16726
+cledar_sdk-1.4.0.dist-info/RECORD,,

{cledar_sdk-1.2.1.dist-info → cledar_sdk-1.4.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

kafka_service/__init__.py

@@ -1,7 +1,12 @@
 from .clients.base import BaseKafkaClient
 from .clients.consumer import KafkaConsumer
 from .clients.producer import KafkaProducer
-from .config.schemas import KafkaConsumerConfig, KafkaProducerConfig
+from .config.schemas import (
+    KafkaConsumerConfig,
+    KafkaProducerConfig,
+    KafkaSaslMechanism,
+    KafkaSecurityProtocol,
+)
 from .exceptions import (
     KafkaConnectionError,
     KafkaConsumerError,
@@ -26,6 +31,8 @@ __all__ = [
     "KafkaMessage",
     "KafkaProducerConfig",
     "KafkaConsumerConfig",
+    "KafkaSecurityProtocol",
+    "KafkaSaslMechanism",
     "KafkaConnectionError",
     "KafkaConsumerNotConnectedError",
     "KafkaProducerNotConnectedError",

kafka_service/clients/consumer.py

@@ -20,16 +20,7 @@ class KafkaConsumer(BaseKafkaClient):
     client: Consumer | None = None
 
     def connect(self) -> None:
-        self.client = Consumer(
-            {
-                "bootstrap.servers": self.config.kafka_servers,
-                "enable.auto.commit": False,
-                "enable.partition.eof": False,
-                "auto.commit.interval.ms": self.config.kafka_auto_commit_interval_ms,
-                "auto.offset.reset": self.config.kafka_offset,
-                "group.id": self.config.kafka_group_id,
-            }
-        )
+        self.client = Consumer(self.config.to_kafka_config())
         self.check_connection()
         logger.info(
             "Connected KafkaConsumer to Kafka servers.",

kafka_service/clients/producer.py

@@ -17,14 +17,7 @@ class KafkaProducer(BaseKafkaClient):
     client: Producer | None = None
 
     def connect(self) -> None:
-        self.client = Producer(
-            {
-                "bootstrap.servers": self.config.kafka_servers,
-                "client.id": self.config.kafka_group_id,
-                "compression.type": self.config.compression_type,
-                "partitioner": self.config.kafka_partitioner,
-            }
-        )
+        self.client = Producer(self.config.to_kafka_config())
         self.check_connection()
         logger.info(
             "Connected Producer to Kafka servers.",

kafka_service/config/schemas.py

@@ -1,7 +1,27 @@
+from enum import Enum
+
 from pydantic import field_validator
 from pydantic.dataclasses import dataclass
 
 
+class KafkaSecurityProtocol(str, Enum):
+    """Supported Kafka security protocols."""
+
+    PLAINTEXT = "PLAINTEXT"
+    SSL = "SSL"
+    SASL_PLAINTEXT = "SASL_PLAINTEXT"
+    SASL_SSL = "SASL_SSL"
+
+
+class KafkaSaslMechanism(str, Enum):
+    """Supported Kafka SASL mechanisms."""
+
+    PLAIN = "PLAIN"
+    SCRAM_SHA_256 = "SCRAM-SHA-256"
+    SCRAM_SHA_512 = "SCRAM-SHA-512"
+    GSSAPI = "GSSAPI"
+
+
 def _validate_kafka_servers(v: list[str] | str) -> list[str] | str:
     """Validate kafka_servers is not empty."""
     if isinstance(v, str) and v.strip() == "":
@@ -36,6 +56,10 @@ class KafkaProducerConfig:
 
     kafka_servers: list[str] | str
     kafka_group_id: str
+    kafka_security_protocol: KafkaSecurityProtocol | None = None
+    kafka_sasl_mechanism: KafkaSaslMechanism | None = None
+    kafka_sasl_username: str | None = None
+    kafka_sasl_password: str | None = None
     kafka_topic_prefix: str | None = None
     kafka_block_buffer_time_sec: int = 10
     kafka_connection_check_timeout_sec: int = 5
@@ -57,6 +81,27 @@ class KafkaProducerConfig:
     def validate_positive_timeouts(cls, v: int) -> int:
         return _validate_non_negative(v)
 
+    def to_kafka_config(self) -> dict[str, list[str] | str | None]:
+        """Build Kafka producer configuration dictionary."""
+        config = {
+            "bootstrap.servers": self.kafka_servers,
+            "client.id": self.kafka_group_id,
+            "compression.type": self.compression_type,
+            "partitioner": self.kafka_partitioner,
+        }
+
+        # Add SASL configuration if specified
+        if self.kafka_security_protocol:
+            config["security.protocol"] = self.kafka_security_protocol.value
+            if self.kafka_sasl_mechanism:
+                config["sasl.mechanism"] = self.kafka_sasl_mechanism.value
+            if self.kafka_sasl_username:
+                config["sasl.username"] = self.kafka_sasl_username
+            if self.kafka_sasl_password:
+                config["sasl.password"] = self.kafka_sasl_password
+
+        return config
+
 
 @dataclass(frozen=True)
 class KafkaConsumerConfig:
@@ -76,6 +121,10 @@ class KafkaConsumerConfig:
 
     kafka_servers: list[str] | str
     kafka_group_id: str
+    kafka_security_protocol: KafkaSecurityProtocol | None = None
+    kafka_sasl_mechanism: KafkaSaslMechanism | None = None
+    kafka_sasl_username: str | None = None
+    kafka_sasl_password: str | None = None
     kafka_offset: str = "latest"
     kafka_topic_prefix: str | None = None
     kafka_block_consumer_time_sec: int = 2
@@ -104,3 +153,26 @@ class KafkaConsumerConfig:
     @classmethod
     def validate_positive_timeouts(cls, v: int) -> int:
         return _validate_non_negative(v)
+
+    def to_kafka_config(self) -> dict[str, int | list[str] | str]:
+        """Build Kafka consumer configuration dictionary."""
+        config = {
+            "bootstrap.servers": self.kafka_servers,
+            "enable.auto.commit": False,
+            "enable.partition.eof": False,
+            "auto.commit.interval.ms": self.kafka_auto_commit_interval_ms,
+            "auto.offset.reset": self.kafka_offset,
+            "group.id": self.kafka_group_id,
+        }
+
+        # Add SASL configuration if specified
+        if self.kafka_security_protocol:
+            config["security.protocol"] = self.kafka_security_protocol.value
+            if self.kafka_sasl_mechanism:
+                config["sasl.mechanism"] = self.kafka_sasl_mechanism.value
+            if self.kafka_sasl_username:
+                config["sasl.username"] = self.kafka_sasl_username
+            if self.kafka_sasl_password:
+                config["sasl.password"] = self.kafka_sasl_password
+
+        return config

kafka_service/tests/unit/test_config_validation.py

@@ -8,7 +8,12 @@ from dataclasses import FrozenInstanceError
 import pytest
 from pydantic import ValidationError
 
-from kafka_service.config.schemas import KafkaConsumerConfig, KafkaProducerConfig
+from kafka_service.config.schemas import (
+    KafkaConsumerConfig,
+    KafkaProducerConfig,
+    KafkaSaslMechanism,
+    KafkaSecurityProtocol,
+)
 from kafka_service.models.message import KafkaMessage
 
 
@@ -523,3 +528,82 @@ def test_config_inequality() -> None:
     )
 
     assert config1 != config2
+
+
+# SASL Configuration Tests
+
+
+def test_config_with_sasl_authentication() -> None:
+    """Test creating configs with SASL authentication."""
+    producer_config = KafkaProducerConfig(
+        kafka_servers="localhost:9092",
+        kafka_group_id="test-group",
+        kafka_security_protocol=KafkaSecurityProtocol.SASL_PLAINTEXT,
+        kafka_sasl_mechanism=KafkaSaslMechanism.PLAIN,
+        kafka_sasl_username="test-user",
+        kafka_sasl_password="test-password",
+    )
+
+    consumer_config = KafkaConsumerConfig(
+        kafka_servers="localhost:9092",
+        kafka_group_id="test-group",
+        kafka_security_protocol=KafkaSecurityProtocol.SASL_SSL,
+        kafka_sasl_mechanism=KafkaSaslMechanism.SCRAM_SHA_256,
+        kafka_sasl_username="test-user",
+        kafka_sasl_password="test-password",
+    )
+
+    assert (
+        producer_config.kafka_security_protocol == KafkaSecurityProtocol.SASL_PLAINTEXT
+    )
+    assert producer_config.kafka_sasl_mechanism == KafkaSaslMechanism.PLAIN
+    assert consumer_config.kafka_security_protocol == KafkaSecurityProtocol.SASL_SSL
+    assert consumer_config.kafka_sasl_mechanism == KafkaSaslMechanism.SCRAM_SHA_256
+
+
+def test_config_invalid_sasl_values() -> None:
+    """Test that invalid SASL values raise ValidationError."""
+    with pytest.raises(ValidationError):
+        KafkaProducerConfig(
+            kafka_servers="localhost:9092",
+            kafka_group_id="test-group",
+            kafka_security_protocol="INVALID",  # type: ignore[arg-type]
+        )
+
+    with pytest.raises(ValidationError):
+        KafkaConsumerConfig(
+            kafka_servers="localhost:9092",
+            kafka_group_id="test-group",
+            kafka_sasl_mechanism="INVALID",  # type: ignore[arg-type]
+        )
+
+
+def test_to_kafka_config_with_and_without_sasl() -> None:
+    """Test that to_kafka_config() correctly includes/excludes SASL parameters."""
+    # Without SASL
+    config_no_sasl = KafkaProducerConfig(
+        kafka_servers="localhost:9092",
+        kafka_group_id="test-group",
+    )
+    kafka_config_no_sasl = config_no_sasl.to_kafka_config()
+
+    assert "security.protocol" not in kafka_config_no_sasl
+    assert "sasl.mechanism" not in kafka_config_no_sasl
+    assert "sasl.username" not in kafka_config_no_sasl
+    assert "sasl.password" not in kafka_config_no_sasl
+
+    # With SASL
+    config_with_sasl = KafkaConsumerConfig(
+        kafka_servers="localhost:9092",
+        kafka_group_id="test-group",
+        kafka_security_protocol=KafkaSecurityProtocol.SASL_SSL,
+        kafka_sasl_mechanism=KafkaSaslMechanism.SCRAM_SHA_256,
+        kafka_sasl_username="user",
+        kafka_sasl_password="pass",
+    )
+    kafka_config_with_sasl = config_with_sasl.to_kafka_config()
+
+    assert kafka_config_with_sasl["security.protocol"] == "SASL_SSL"
+    assert kafka_config_with_sasl["sasl.mechanism"] == "SCRAM-SHA-256"
+    assert kafka_config_with_sasl["sasl.username"] == "user"
+    assert kafka_config_with_sasl["sasl.password"] == "pass"

redis_service/README.md

@@ -7,6 +7,7 @@ The `redis_service` package provides a typed, high-level interface over Redis fo
 ### Key Features
 
 - **Typed API with Pydantic**: Validate JSON payloads into Pydantic models on read
+- **Async/Sync Support**: Both `AsyncRedisService` (async/await) and `RedisService` (synchronous) available
 - **Safe Serialization**: Custom JSON encoder for `Enum` (to lowercase names) and `datetime` (ISO 8601)
 - **Ergonomic Helpers**: `get`, `get_raw`, `set`, `list_keys`, `mget`, `delete`
 - **Bulk Reads**: `mget` returns a list with typed results, `None`, or `FailedValue` for per-key errors
@@ -21,6 +22,7 @@ The `redis_service` package provides a typed, high-level interface over Redis fo
 - Reading and writing typed configuration objects
 - Bulk retrieval of many keys while tolerating per-key failures
 - Observing and reacting to configuration changes in near real-time
+- Asynchronous I/O for high-performance applications (FastAPI, aiohttp, etc.)
 
 ## Installation
 
@@ -34,7 +36,9 @@ uv sync --all-groups
 pip install -e .
 ```
 
-## Usage Example
+## Usage Examples
+
+### Synchronous Usage
 
 ```python
 from pydantic import BaseModel
@@ -78,6 +82,122 @@ bulk = service.mget(keys, UserModel)
 service.delete("greeting")
 ```
 
+### Asynchronous Usage
+
+```python
+import asyncio
+from pydantic import BaseModel
+from redis_service.redis import AsyncRedisService, RedisServiceConfig
+
+
+class UserModel(BaseModel):
+    user_id: int
+    name: str
+
+
+async def main():
+    # Configure and create async service
+    config = RedisServiceConfig(
+        redis_host="localhost",
+        redis_port=6379,
+        redis_db=0,
+    )
+    service = AsyncRedisService(config)
+    await service.connect()
+
+    try:
+        # Health check
+        assert await service.is_alive() is True
+
+        # Write a typed value (automatically serialized to JSON)
+        user = UserModel(user_id=1, name="Alice")
+        await service.set("user:1", user)
+
+        # Read and validate back into the model
+        loaded = await service.get("user:1", UserModel)
+        print(loaded)  # UserModel(user_id=1, name='Alice')
+
+        # Raw access (no validation/decoding beyond Redis decode_responses)
+        await service.set("greeting", "hello")
+        print(await service.get_raw("greeting"))  # "hello"
+
+        # List keys by pattern and bulk-fetch
+        keys = await service.list_keys("user:*")
+        bulk = await service.mget(keys, UserModel)
+        # bulk is a list of UserModel | None | FailedValue
+
+        # Delete
+        await service.delete("greeting")
+
+    finally:
+        # Always close the connection
+        await service.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### FastAPI Integration Example
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Depends
+from pydantic import BaseModel
+from redis_service.redis import AsyncRedisService, RedisServiceConfig
+
+
+class UserModel(BaseModel):
+    user_id: int
+    name: str
+
+
+# Global service instance
+redis_service: AsyncRedisService | None = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: initialize Redis service
+    global redis_service
+    config = RedisServiceConfig(
+        redis_host="localhost",
+        redis_port=6379,
+        redis_db=0,
+    )
+    redis_service = AsyncRedisService(config)
+    await redis_service.connect()
+
+    yield
+
+    # Shutdown: close Redis connection
+    if redis_service:
+        await redis_service.close()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+def get_redis() -> AsyncRedisService:
+    if redis_service is None:
+        raise RuntimeError("Redis service not initialized")
+    return redis_service
+
+
+@app.get("/users/{user_id}")
+async def get_user(user_id: int, redis: AsyncRedisService = Depends(get_redis)):
+    user = await redis.get(f"user:{user_id}", UserModel)
+    if user is None:
+        return {"error": "User not found"}
+    return user
+
+
+@app.post("/users")
+async def create_user(user: UserModel, redis: AsyncRedisService = Depends(get_redis)):
+    await redis.set(f"user:{user.user_id}", user)
+    return {"status": "created", "user": user}
+```
+
 ## Development
 
 ### Project Structure
@@ -85,16 +205,18 @@ service.delete("greeting")
 ```
 redis_service/
 ├── __init__.py
-├── exceptions.py            # Custom exceptions
-├── logger.py                # Module logger
-├── model.py                 # Base config type for RedisConfigStore
-├── redis.py                 # Main RedisService implementation
-├── redis_config_store.py    # Config store with caching and watchers
-├── example.py               # Small example of using RedisConfigStore
+├── exceptions.py                      # Custom exceptions
+├── logger.py                          # Module logger
+├── model.py                           # Base config type for RedisConfigStore
+├── redis.py                           # RedisService and AsyncRedisService
+├── redis_config_store.py              # Config store with caching and watchers
+├── example.py                         # Small example of using RedisConfigStore
 ├── tests/
-│   ├── test_redis_service.py       # Unit tests (mocked Redis)
-│   └── test_integration_redis.py   # Integration tests with testcontainers
-└── README.md                # This file
+│   ├── test_redis_service.py          # Sync unit tests (mocked Redis)
+│   ├── test_async_redis_service.py    # Async unit tests (mocked Redis)
+│   ├── test_integration_redis.py      # Sync integration tests with testcontainers
+│   └── test_async_integration_redis.py # Async integration tests with testcontainers
+└── README.md                          # This file
 ```
 
 ## Running Linters
@@ -158,9 +280,9 @@ PYTHONPATH=$PWD uv run pytest redis_service/tests/test_redis_service.py::test_se
 
 ### Unit Test Details
 
-- **Test Framework**: pytest
-- **Mocking**: unittest.mock
-- **Test Count**: 30 unit tests
+- **Test Framework**: pytest, pytest-asyncio
+- **Mocking**: unittest.mock (sync), AsyncMock (async)
+- **Test Count**: 60 unit tests (30 sync + 30 async)
 
 ## Running Integration Tests
 
@@ -183,10 +305,10 @@ PYTHONPATH=$PWD uv run pytest redis_service/tests/test_integration_redis.py -v
 
 ### Integration Test Details
 
-- **Test Framework**: pytest + testcontainers
+- **Test Framework**: pytest, pytest-asyncio + testcontainers
 - **Container**: Redis
 - **Image**: `redis:7.2-alpine`
-- **Test Count**: 8 integration tests
+- **Test Count**: 17 integration tests (8 sync + 9 async)
 
 ### Run All Tests (Unit + Integration)
 
@@ -284,7 +406,7 @@ class RedisServiceConfig:
     redis_password: str | None = None
 ```
 
-### RedisService
+### RedisService (Synchronous)
 
 High-level service over `redis.Redis` with JSON handling and typed reads.
 
@@ -298,6 +420,24 @@ High-level service over `redis.Redis` with JSON handling and typed reads.
 - `mget(keys: list[str], model: type[T]) -> list[T | None | FailedValue]` — Bulk read with per-key error details
 - `delete(key: str) -> bool` — Delete a key; returns True if a key was removed
 
+### AsyncRedisService (Asynchronous)
+
+High-level async service over `redis.asyncio.Redis` with JSON handling and typed reads.
+
+#### Methods
+
+All methods are async (use `await`):
+
+- `connect() -> None` — Establish connection to Redis (must be called before using other methods)
+- `close() -> None` — Close the Redis connection
+- `is_alive() -> bool` — Ping Redis to check connectivity
+- `set(key: str, value: Any) -> bool` — Serialize and store a value; supports dict/list, Pydantic models, primitives
+- `get(key: str, model: type[T]) -> T | None` — Read and validate JSON into the given Pydantic model
+- `get_raw(key: str) -> Any | None` — Read raw value (usually string) without validation
+- `list_keys(pattern: str) -> list[str]` — List keys matching a glob-like pattern
+- `mget(keys: list[str], model: type[T]) -> list[T | None | FailedValue]` — Bulk read with per-key error details
+- `delete(key: str) -> bool` — Delete a key; returns True if a key was removed
+
 #### Exceptions
 
 - `RedisConnectionError` — Connection/transport errors

redis_service/__init__.py

@@ -0,0 +1,15 @@
+from .redis import (
+    AsyncRedisService,
+    CustomEncoder,
+    FailedValue,
+    RedisService,
+    RedisServiceConfig,
+)
+
+__all__ = [
+    "AsyncRedisService",
+    "CustomEncoder",
+    "FailedValue",
+    "RedisService",
+    "RedisServiceConfig",
+]