smartinno 1.0.0__tar.gz

smartinno-1.0.0/MANIFEST.in

@@ -0,0 +1 @@
+include redis_sdk/*.md

smartinno-1.0.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: smartinno
+Version: 1.0.0
+Summary: Unified Redis Python SDK for the Safari Pro architecture.
+Author: Safari Pro Engineering
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: redis>=5.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Unified Redis Python SDK
+
+A unified, robust Python wrapper for interacting with multiple Redis architectures seamlessly. This SDK uses the Factory Design Pattern to abstract away the complexity of connecting to different Redis setups. It natively enforces data standardization (JSON enveloping) and integrates enterprise-grade features out of the box.
+
+## Core Features
+
+- **Automatic Data Standardization**: All payloads sent to Redis are automatically wrapped in a standard JSON envelope containing `request_id` (a UUID), `event`, `type`, `service`, `payload`, and `timestamp`. The SDK transparently unwraps this when reading data so your application only ever sees the raw data it passed.
+- **Key Namespacing**: All keys are prefixed with `{service_name}:{action}:{key}` to prevent collisions across microservices.
+- **Intelligent Routing**: Use `UseCase.AUTO` to automatically route cache commands to a Native Cluster, Pub/Sub to Sentinel, and Streams to a Hybrid proxy.
+- **Enterprise-Grade Configurations**: Built-in support for Connection Pooling, SSL/TLS, Exponential Backoff Retries, and Socket Keepalives.
+
+---
+
+## Supported Architectures & Use Cases
+
+| Architecture | `UseCase` Enum | Underlying Driver | Best For |
+|---|---|---|---|
+| **Intelligent Router** | `AUTO` | `IntelligentRouterAdapter` | Hands-off optimal routing based on command type. |
+| **Native Redis Cluster** | `HIGH_CONCURRENCY` | `redis.cluster.RedisCluster` | Horizontal scaling, massive reads/writes. |
+| **Sentinel + HAProxy** | `HEAVY_TRANSACTIONS` | `redis.Redis` (HAProxy) | Pub/Sub, robust transactions. |
+| **Hybrid (Predixy Proxy)** | `MICROSERVICES` | `redis.Redis` (Standard) | Easy multi-tenant connections, stateless clients. |
+
+---
+
+## Usage Guide
+
+### 1. Basic Import
+```python
+from redis_sdk.config import RedisConfig, UseCase
+from redis_sdk.factory import RedisClientFactory
+```
+
+### 2. Configuration & Enterprise Settings
+Initialize your configuration and pass `service_name` to define your application's namespace. You can also pass enterprise features like retries and connection limits.
+
+```python
+cluster_config = RedisConfig(
+    host="redis-node-1", 
+    port=6379, 
+    password="your_password",
+    startup_nodes=[{"host": "redis-node-1", "port": 6379}],
+    
+    # Core SDK configs
+    service_name="my_billing_app",
+    
+    # Enterprise configs
+    ssl=False,
+    max_connections=100,
+    socket_timeout=5.0,
+    retry_on_timeout=True,
+    retry_backoff=True, # Enables Exponential Backoff
+    retry_backoff_retries=3
+)
+```
+
+### 3. Native Cluster (`HIGH_CONCURRENCY`)
+```python
+client = RedisClientFactory.get_client(cluster_config, UseCase.HIGH_CONCURRENCY)
+
+# Automatically formats key to 'my_billing_app:cache:foo'
+# Automatically wraps data in a JSON envelope.
+client.set("foo", {"some": "data"})
+
+# Transparently unwraps the envelope and returns {"some": "data"}
+print(client.get("foo"))
+```
+
+### 4. Hybrid Proxy (`MICROSERVICES`)
+Connects to the Native Cluster through a Predixy proxy. The client patches pipeline transactions automatically because Predixy handles clustering efficiently.
+
+```python
+hybrid_config = RedisConfig(
+    host="localhost", 
+    port=6381, 
+    password="your_password",
+    service_name="my_billing_app"
+)
+
+client = RedisClientFactory.get_client(hybrid_config, UseCase.MICROSERVICES)
+
+# Pipelines are patched automatically!
+pipe = client.pipeline(transaction=True)
+pipe.set("a", 1)
+pipe.set("b", 2)
+pipe.execute()
+```
+> **Note on Predixy Pipelines:** Predixy Proxy does not support cross-node `MULTI/EXEC` efficiently via python pipelines. If you pass `transaction=True`, the Hybrid adapter catches it, prints a notice, and gracefully overrides it to `transaction=False`.
+
+### 5. Intelligent Router (`AUTO`)
+The absolute easiest way to consume Redis. Provide the configurations for all environments to the factory, request `UseCase.AUTO`, and the router will send your queries to the optimal architecture.
+
+```python
+router_client = RedisClientFactory.get_client(
+    config=global_config, 
+    use_case=UseCase.AUTO
+)
+
+# Routes to Native Cluster
+router_client.set("cache_key", "fast_data")
+
+# Routes to Sentinel
+router_client.publish("global_events", "system_ready")
+
+# Routes to Hybrid Proxy
+router_client.xadd("audit_trail", {"action": "login"})
+```
+
+---
+
+## Running the Tests
+
+To verify that the SDK routes correctly to all three architectures:
+
+1. **Inside Docker (Recommended)**: Use `run_tests_in_docker.ps1` to run the tests securely inside the same docker network as the Redis instances.
+2. **Local Windows**: Run `python test_sdk.py`. (Note: Native Cluster tests may fail gracefully if it requires docker DNS resolution).
+# Redis SDK Developer Guide
+
+This developer guide provides step-by-step instructions on how to use the Safari Pro Redis SDK, including how to connect to Redis, read data (both pending and new) from streams, and utilize the built-in Communication Service for sending SMS, emails, and in-app notifications.
+
+## 1. Connecting to Redis
+
+The SDK abstracts the underlying Redis architecture (Cluster, Sentinel, or Hybrid/Predixy) using the `RedisClientFactory` and the `UseCase` enum.
+
+```python
+from redis_sdk.config import RedisConfig, UseCase
+from redis_sdk.factory import RedisClientFactory
+
+# Initialize the configuration with your service namespace
+config = RedisConfig(
+    host="redis-node-1",
+    port=6379,
+    password="your_password",
+    startup_nodes=[{"host": "redis-node-1", "port": 6379}],
+    service_name="my_service"
+)
+
+# Request a client tailored for high concurrency (e.g., Native Cluster)
+client = RedisClientFactory.get_client(config, UseCase.HIGH_CONCURRENCY)
+```
+
+## 2. Reading Data from Redis Streams
+
+Redis Streams is the backbone of the SDK's messaging architecture. You can use the unified `xread` method to consume data from streams. The SDK handles JSON envelop unwrapping automatically.
+
+### Reading Pending Messages
+To read all existing/pending messages in a stream from the beginning, pass `0` (or `"0-0"`) as the stream ID.
+
+```python
+# Read pending messages from the beginning (ID 0)
+messages = client.xread({"communication:events": 0}, count=10)
+
+if messages:
+    for stream_name, events in messages:
+        print(f"Found {len(events)} pending messages in {stream_name}")
+        for msg_id, msg_data in events:
+            print(f"Message ID: {msg_id}, Data: {msg_data}")
+```
+
+### Reading New Messages
+To listen for new messages, pass `$` as the stream ID and use the `block` parameter (in milliseconds). The client will block and wait until a new message arrives.
+
+```python
+# Block and wait for up to 5000ms for new messages
+new_messages = client.xread({"communication:events": "$"}, count=1, block=5000)
+
+if new_messages:
+    for stream_name, events in new_messages:
+        for msg_id, msg_data in events:
+            print(f"New event received: {msg_id}")
+```
+
+> [!TIP]
+> The Intelligent Router (`UseCase.AUTO`) will automatically route stream commands like `XADD` and `XREAD` to the Hybrid architecture!
+
+---
+
+## 3. Using the Communication Service
+
+The `CommunicationService` is a robust module integrated into the SDK that queues messages onto Redis Streams for external communication workers to process.
+
+```python
+from redis_sdk.communication_service import communication_service
+```
+
+### Sending SMS
+
+You can send SMS messages to one or multiple recipients.
+
+```python
+success = communication_service.send_sms(
+    recipients=["+254700123456", "+254711654321"],
+    message="Your Safari Pro booking is confirmed!",
+    template="booking_confirmation",
+    metadata={"booking_id": "BK-001"}
+)
+```
+
+### Sending Emails
+
+The email functionality supports plain text, HTML, and templates.
+
+```python
+email_result = communication_service.send_email(
+    recipients=["guest@example.com"],
+    subject="Booking Confirmation",
+    body="Your safari booking BK-001 has been confirmed.",
+    html_content="<h1>Booking Confirmed</h1>",
+    template_name="booking_email",
+    context_data={"guest_name": "Alice"},
+    metadata={"booking_id": "BK-001"}
+)
+
+print(email_result["message_id"]) # Message ID tracking
+```
+
+### Sending In-App Notifications
+
+Queue an in-app notification that will be pushed to the user's notification center in real-time.
+
+```python
+inapp_result = communication_service.send_inapp_notification(
+    user_id="user_123",
+    title="Booking Confirmed",
+    message="Your booking #BK-001 has been confirmed",
+    notification_type="booking_confirmed",
+    action_url="/bookings/BK-001",
+    priority="high"
+)
+```
+
+### Multi-Channel Notifications (All-in-One)
+
+Send to multiple channels simultaneously using `send_notification()`.
+
+```python
+results = communication_service.send_notification(
+    notification_type="payment_received",
+    recipients={
+        "email": ["finance@safari.co"],
+        "sms": ["+254700999888"],
+        "user_id": "user_456",
+    },
+    content={
+        "email_subject": "Payment Received",
+        "email_body": "Payment of $500 received for booking BK-002.",
+        "sms_message": "Payment of $500 received. Ref: BK-002",
+        "inapp_title": "Payment Received",
+        "inapp_message": "We received your $500 payment for booking BK-002",
+    },
+    metadata={"booking_id": "BK-002", "amount": "500.00", "priority": "high"}
+)
+
+print(results) # {"email": {...}, "sms": True, "inapp": True}
+```

smartinno-1.0.0/redis_sdk/DEVELOPER_GUIDE.md

@@ -0,0 +1,253 @@
+# Safari Pro: Redis & Communication Developer Guide
+
+This developer guide details how to read data from Redis Streams (including handling **New** and **Pending** messages) and how to leverage the **Communication Service** for sending Emails, SMS, and In-App notifications.
+
+---
+
+## 📚 1. Redis Streams: Reading Data (New vs. Pending)
+
+Redis Streams (`XADD`, `XREAD`, `XREADGROUP`) act as a high-performance, append-only log suited for event-driven architectures. When consuming from a stream via **Consumer Groups**, messages fall into two categories:
+1. **New Messages**: Messages added to the stream that have never been delivered to any consumer in the consumer group.
+2. **Pending Messages**: Messages that were delivered to a consumer but have **not yet been acknowledged** (`XACK`). These live in the group's **Pending Entries List (PEL)**.
+
+### How the SDK Wraps Stream Data
+The unified SDK automatically prefixes stream keys with `{service_name}:stream:{key}` and encodes fields into a JSON envelope:
+- **Writing**: `xadd("audit_trail", {"user": "alice"})` writes to `safari_pro:stream:audit_trail`.
+- **Reading**: `xread` automatically extracts the `payload` block and decodes it back to a Python dictionary.
+
+---
+
+### 📥 Reading New Messages
+To read new messages using a consumer group, pass the special ID `>` to `XREADGROUP`. This indicates that you only want messages that have never been delivered to any other consumer in the group.
+
+```python
+from redis_sdk.config import RedisConfig, UseCase
+from redis_sdk.factory import RedisClientFactory
+
+# 1. Initialize Client
+config = RedisConfig(
+    host="redis-node-1", 
+    port=6379, 
+    password="my_super_secret_cluster_pass_2026",
+    service_name="safari_pro"
+)
+client = RedisClientFactory.get_client(config, UseCase.AUTO)
+
+# Note: Since 'xgroup_create' is not explicitly wrapped, 
+# it transparently proxies to the native redis-py driver with Circuit Breaker protection.
+stream_key = "safari_pro:stream:booking_events"
+group_name = "booking_processors"
+
+# 2. Create the consumer group if it doesn't exist
+try:
+    client.xgroup_create(name=stream_key, groupname=group_name, id="0", mkstream=True)
+except Exception:
+    # Group already exists
+    pass
+
+# 3. Read NEW messages (using '>')
+# This block blocks for up to 2 seconds (2000ms) waiting for new messages
+response = client.xreadgroup(
+    groupname=group_name,
+    consumername="worker-1",
+    streams={stream_key: ">"},
+    count=10,
+    block=2000
+)
+
+if response:
+    for stream, messages in response:
+        for msg_id, fields in messages:
+            print(f"New Message Received [{msg_id}]: {fields}")
+            
+            # 4. Acknowledge the message once processed successfully
+            client.xack(stream_key, group_name, msg_id)
+```
+
+---
+
+### 🔄 Reading & Resolving Pending Messages
+If a consumer crashes after reading a message but before acknowledging it with `XACK`, that message remains in the **Pending Entries List (PEL)**. If the worker restarts, it should first read and process its pending messages before requesting new ones.
+
+To retrieve pending messages, read from the stream using the **start ID (e.g. `0-0` or `0`)** instead of `>`. This tells Redis to return messages assigned to this consumer that have not been acknowledged.
+
+```python
+# 1. Read PENDING messages assigned to "worker-1"
+pending_response = client.xreadgroup(
+    groupname=group_name,
+    consumername="worker-1",
+    streams={stream_key: "0"},  # "0" fetches pending messages for this consumer
+    count=10
+)
+
+if pending_response:
+    for stream, messages in pending_response:
+        for msg_id, fields in messages:
+            print(f"Reprocessing Pending Message [{msg_id}]: {fields}")
+            
+            # Process and ACK
+            client.xack(stream_key, group_name, msg_id)
+```
+
+### 🚨 Dead-Letter & Orphaned Message Recovery (`XPENDING` and `XCLAIM`)
+If a worker dies permanently, its pending messages will be stuck forever unless claimed by another worker. You can inspect stuck messages and transfer ownership using `xpending` and `xclaim`:
+
+```python
+import time
+
+# Find messages pending for more than 30 seconds
+# xpending_range(name, group, idle_min_time_ms, start, end, count)
+pending_info = client.xpending_range(
+    name=stream_key,
+    group=group_name,
+    min_idle_time=30000,  # 30 seconds idle
+    start="-",
+    end="+",
+    count=10
+)
+
+for item in pending_info:
+    msg_id = item["message_id"]
+    consumer = item["consumer"]
+    idle_time = item["elapsed_time"]
+    
+    print(f"Message {msg_id} is dead/idle for {idle_time}ms on consumer {consumer}.")
+    
+    # Claim ownership of the message for "worker-2"
+    client.xclaim(
+        name=stream_key,
+        group=group_name,
+        consumername="worker-2",
+        min_idle_time=30000,
+        message_ids=[msg_id]
+    )
+    print(f"Successfully claimed {msg_id} to worker-2")
+```
+
+---
+
+## ✉️ 2. Using the Communication Service
+
+The `CommunicationService` provides a unified API for dispatching SMS, Email, and In-App notifications. Under the hood, it pushes these events to a unified Redis stream (`communication:events`), decoupling the frontend/API from delivery workers.
+
+### Import and Access
+Always use the pre-configured singleton instance:
+```python
+from redis_sdk.communication_service import communication_service
+```
+
+---
+
+### 📱 A. Sending SMS
+Sends short text messages. The phone number is validated automatically before being queued.
+
+```python
+success = communication_service.send_sms(
+    recipients=["+254700123456", "+254711654321"],
+    message="Your Safari Pro booking is confirmed! Details: safari.pro/b/BK-902",
+    template="booking_confirmation",
+    metadata={"booking_id": "BK-902"}
+)
+
+if success:
+    print("SMS queued successfully!")
+```
+
+**Parameters:**
+- `recipients`: A phone number string or list of phone numbers.
+- `message`: Plain text content.
+- `template`: Optional template identifier (useful for transactional SMS providers).
+- `metadata`: Optional dict containing analytics fields or tracking tags.
+
+---
+
+### 📧 B. Sending Emails
+Supports plain text, custom HTML structures, template context injection, and document attachments.
+
+```python
+result = communication_service.send_email(
+    recipients=["guest@example.com"],
+    subject="Welcome to Safari Pro!",
+    body="Thank you for signing up for Safari Pro.",
+    html_content="<h1>Welcome!</h1><p>We are thrilled to have you join us.</p>",
+    template_name="welcome_user",
+    context_data={"username": "Alice"},
+    attachments=[
+        {
+            "filename": "itinerary.pdf",
+            "content": "BASE64_ENCODED_STRING...",
+            "content_type": "application/pdf"
+        }
+    ],
+    metadata={"user_id": "usr_9021"}
+)
+
+# Returns a dictionary: {"success": bool, "message_id": str, "queued": bool}
+if result.get("success"):
+    print(f"Email queued. Msg ID: {result['message_id']}")
+```
+
+---
+
+### 🔔 C. Sending In-App Notifications
+Queues real-time alerts that appear directly inside the user's notification center within the Safari Pro app.
+
+```python
+result = communication_service.send_inapp_notification(
+    user_id="user_123",
+    title="New Booking Request",
+    message="A client requested a booking on 'Maasai Mara Express'.",
+    notification_type="booking_request",
+    action_url="/partner/bookings/BK-902",
+    metadata={"booking_id": "BK-902"},
+    priority="high",          # 'low', 'normal', 'high', 'critical'
+    requires_action=True       # Forces the user to explicitly dismiss or act on it
+)
+```
+
+---
+
+### 📣 D. Multi-Channel Notifications
+When you need to alert a user across multiple channels simultaneously (e.g. notify a host of a payment via Email + SMS + In-App notification), use the combined `send_notification` method.
+
+```python
+channels_status = communication_service.send_notification(
+    notification_type="payment_received",
+    recipients={
+        "email": ["host@example.com"],
+        "sms": ["+254700999888"],
+        "user_id": "host_456"
+    },
+    content={
+        "email_subject": "Payment Received for Booking BK-002",
+        "email_body": "Payment of $1,500 has been successfully captured.",
+        "email_html": "<h2>Payment Captured</h2><p>Payment of $1,500 has been captured.</p>",
+        "sms_message": "Safari Pro: $1,500 payment received. Ref: BK-002",
+        "inapp_title": "Payment Captured",
+        "inapp_message": "$1,500 payment received from guest."
+    },
+    metadata={"booking_id": "BK-002", "amount": "1500.00"}
+)
+
+# Returns a dictionary showing success per channel:
+# Example: {"email": {"success": True, ...}, "sms": True, "inapp": True}
+print("Notification results:", channels_status)
+```
+
+---
+
+### ⚙️ E. Checking Communication Service Health
+To monitor the communication pipeline:
+
+```python
+status = communication_service.get_service_status()
+print(status)
+# Output:
+# {
+#     "redis_connected": True,
+#     "redis_healthy": True,
+#     "sms_stream": "communication:events",
+#     "email_stream": "communication:events",
+#     "inapp_stream": "communication:events"
+# }
+```