sf-queue-sdk 0.2.0b23__tar.gz → 0.2.0b24__tar.gz

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sf-queue-sdk
-Version: 0.2.0b23
+Version: 0.2.0b24
 Summary: Python SDK for sf-queue - Redis-based queue system
 Requires-Python: >=3.11
 Requires-Dist: redis>=5.0.0
@@ -384,6 +384,32 @@ print(result.success)
 print(result.message_id)
 ```
 
+### Batch (fire and forget)
+
+```python
+result = client.recommendations.create_batch([
+    {"user_id": "user_1", "topic_id": "topic_1", "limit": 10},
+    {"user_id": "user_2", "topic_id": "topic_2"},
+])
+print("Enqueued:", result.message_id)
+```
+
+### Batch (wait for confirmation)
+
+```python
+result = client.recommendations.create_batch_and_wait(
+    [
+        {"user_id": "user_1", "topic_id": "topic_1"},
+        {"user_id": "user_2", "topic_id": "topic_2"},
+    ],
+    timeout=60,
+)
+print(result.success)
+print(result.total)
+print(result.successful)
+print(result.failed)
+```
+
 ### Recommendation Fields
 
 | Field | Type | Required | Description |
@@ -392,6 +418,31 @@ print(result.message_id)
 | `topic_id` | `str` | Yes | Topic context for recommendations |
 | `limit` | `Optional[int]` | No | Max recommendations to return |
 
+## Query (Direct Key Lookups)
+
+Read values directly from Redis by key. These are plain `GET` / `MGET` calls, not queue operations.
+
+### Get a single key
+
+```python
+value = client.query.get("mykey")
+print(value)  # str or None
+```
+
+### Get multiple keys
+
+```python
+values = client.query.get_many(["key1", "key2", "key3"])
+print(values)  # list[str | None]
+```
+
+### Query Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `get(key)` | `Optional[str]` | Fetch a single key via Redis GET |
+| `get_many(keys)` | `list[Optional[str]]` | Fetch multiple keys via Redis MGET |
+
 ## Cleanup
 
 ```python

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b24}/README.md

@@ -376,6 +376,32 @@ print(result.success)
 print(result.message_id)
 ```
 
+### Batch (fire and forget)
+
+```python
+result = client.recommendations.create_batch([
+    {"user_id": "user_1", "topic_id": "topic_1", "limit": 10},
+    {"user_id": "user_2", "topic_id": "topic_2"},
+])
+print("Enqueued:", result.message_id)
+```
+
+### Batch (wait for confirmation)
+
+```python
+result = client.recommendations.create_batch_and_wait(
+    [
+        {"user_id": "user_1", "topic_id": "topic_1"},
+        {"user_id": "user_2", "topic_id": "topic_2"},
+    ],
+    timeout=60,
+)
+print(result.success)
+print(result.total)
+print(result.successful)
+print(result.failed)
+```
+
 ### Recommendation Fields
 
 | Field | Type | Required | Description |
@@ -384,6 +410,31 @@ print(result.message_id)
 | `topic_id` | `str` | Yes | Topic context for recommendations |
 | `limit` | `Optional[int]` | No | Max recommendations to return |
 
+## Query (Direct Key Lookups)
+
+Read values directly from Redis by key. These are plain `GET` / `MGET` calls, not queue operations.
+
+### Get a single key
+
+```python
+value = client.query.get("mykey")
+print(value)  # str or None
+```
+
+### Get multiple keys
+
+```python
+values = client.query.get_many(["key1", "key2", "key3"])
+print(values)  # list[str | None]
+```
+
+### Query Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `get(key)` | `Optional[str]` | Fetch a single key via Redis GET |
+| `get_many(keys)` | `list[Optional[str]]` | Fetch multiple keys via Redis MGET |
+
 ## Cleanup
 
 ```python

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b24}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sf-queue-sdk"
-version = "0.2.0b23"
+version = "0.2.0b24"
 description = "Python SDK for sf-queue - Redis-based queue system"
 readme = "README.md"
 requires-python = ">=3.11"

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b24}/queue_sdk/__init__.py

@@ -1,11 +1,14 @@
 """sf-queue Python SDK - Redis-based queue system."""
 
-__version__ = "0.2.0b23"
+__version__ = "0.2.0b24"
 
 from queue_sdk.client import QueueClient
+from queue_sdk.query import QueryClient
 from queue_sdk.types import (
     BatchEmailResponse,
     BatchQueueResponse,
+    BatchRecommendationRequestData,
+    BatchRecommendationResponse,
     BatchToolAssignmentData,
     BatchTopicAssignmentData,
     ConvertData,
@@ -25,6 +28,7 @@ from queue_sdk.types import (
 
 __all__ = [
     "QueueClient",
+    "QueryClient",
     "QueueClientConfig",
     "EmailData",
     "EmailButton",
@@ -35,6 +39,8 @@ __all__ = [
     "BatchQueueResponse",
     "RecommendationRequestData",
     "RecommendationResponse",
+    "BatchRecommendationRequestData",
+    "BatchRecommendationResponse",
     "TopicAssignmentData",
     "BatchTopicAssignmentData",
     "ToolAssignmentData",

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b24}/queue_sdk/client.py

@@ -1,5 +1,6 @@
 """QueueClient - main entry point for the Python SDK."""
 
+from queue_sdk.query import QueryClient
 from queue_sdk.queues.email_queue import EmailQueue
 from queue_sdk.queues.pdf_to_image_queue import PdfToImageQueue
 from queue_sdk.queues.recommendation_queue import RecommendationQueue
@@ -67,6 +68,7 @@ class QueueClient:
         self.tool_assignment = ToolAssignmentQueue(self._redis, self._environment)
         self.pdf_to_image = PdfToImageQueue(self._redis, self._environment)
         self.recommendations = RecommendationQueue(self._redis, self._environment)
+        self.query = QueryClient(self._redis)
 
     def disconnect(self) -> None:
         """Close the Redis connection."""

sf_queue_sdk-0.2.0b24/queue_sdk/query.py

@@ -0,0 +1,22 @@
+"""QueryClient - direct Redis key lookups."""
+
+from typing import Optional
+
+import redis as redis_lib
+
+
+class QueryClient:
+    """Direct Redis key lookups (GET, MGET)."""
+
+    def __init__(self, redis_client: redis_lib.Redis):
+        self._redis = redis_client
+
+    def get(self, key: str) -> Optional[str]:
+        """Fetch a single key from Redis."""
+        return self._redis.get(key)
+
+    def get_many(self, keys: list[str]) -> list[Optional[str]]:
+        """Fetch multiple keys from Redis in a single MGET call."""
+        if not keys:
+            return []
+        return self._redis.mget(*keys)

sf_queue_sdk-0.2.0b24/queue_sdk/queues/recommendation_queue.py

@@ -0,0 +1,136 @@
+"""Recommendation queue with typed methods."""
+
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+import redis as redis_lib
+
+from queue_sdk.queues.base_queue import BaseQueue
+from queue_sdk.types import (
+    BatchRecommendationResponse,
+    RecommendationResponse,
+    SendResult,
+)
+
+
+class RecommendationQueue(BaseQueue):
+    """Typed methods for creating recommendation requests via the queue."""
+
+    def __init__(self, redis_client: redis_lib.Redis, environment: str):
+        super().__init__(redis_client, environment, "recommendation-requests")
+
+    def create(
+        self,
+        user_id: str,
+        topic_id: str,
+        limit: Optional[int] = None,
+    ) -> SendResult:
+        """Enqueue a recommendation request (fire and forget)."""
+        self._validate(user_id, topic_id)
+        payload = self._build_payload(user_id, topic_id, limit)
+        message_id = self._enqueue(payload)
+        return SendResult(message_id=message_id)
+
+    def create_and_wait(
+        self,
+        user_id: str,
+        topic_id: str,
+        limit: Optional[int] = None,
+        timeout: Optional[int] = None,
+    ) -> RecommendationResponse:
+        """Enqueue a recommendation request and wait for the result."""
+        self._validate(user_id, topic_id)
+        payload = self._build_payload(user_id, topic_id, limit)
+        response = self._enqueue_and_wait(payload, timeout)
+
+        return RecommendationResponse(
+            success=response.success,
+            message_id=response.message_id,
+            error=response.error,
+            processed_at=response.processed_at,
+        )
+
+    def create_batch(
+        self,
+        requests: list[dict[str, Any]],
+    ) -> SendResult:
+        """Enqueue multiple recommendation requests (fire and forget)."""
+        self._validate_batch(requests)
+        payload = self._build_batch_payload(requests)
+        message_id = self._enqueue(payload)
+        return SendResult(message_id=message_id)
+
+    def create_batch_and_wait(
+        self,
+        requests: list[dict[str, Any]],
+        timeout: Optional[int] = None,
+    ) -> BatchRecommendationResponse:
+        """Enqueue multiple recommendation requests and wait for confirmation."""
+        self._validate_batch(requests)
+        payload = self._build_batch_payload(requests)
+        response = self._enqueue_and_wait(payload, timeout)
+
+        return BatchRecommendationResponse(
+            success=response.success,
+            message_id=response.message_id,
+            error=response.error,
+            processed_at=response.processed_at,
+            total=getattr(response, "total", len(requests)),
+            successful=getattr(
+                response, "successful", len(requests) if response.success else 0
+            ),
+            failed=getattr(response, "failed", 0 if response.success else len(requests)),
+        )
+
+    def _build_payload(
+        self,
+        user_id: str,
+        topic_id: str,
+        limit: Optional[int],
+    ) -> dict[str, Any]:
+        """Build the recommendation request payload."""
+        payload: dict[str, Any] = {
+            "userId": user_id,
+            "topicId": topic_id,
+            "requestedAt": datetime.now(timezone.utc).isoformat(),
+            "key": f"{user_id}-{topic_id}",
+        }
+        if limit is not None:
+            payload["limit"] = limit
+        return payload
+
+    def _build_batch_payload(
+        self, requests: list[dict[str, Any]]
+    ) -> dict[str, Any]:
+        """Build the batch recommendation request payload."""
+        return {
+            "batch": True,
+            "requests": [
+                self._build_payload(
+                    r.get("user_id", ""),
+                    r.get("topic_id", ""),
+                    r.get("limit"),
+                )
+                for r in requests
+            ],
+        }
+
+    @staticmethod
+    def _validate(user_id: str, topic_id: str) -> None:
+        """Validate the recommendation request."""
+        if not user_id:
+            raise ValueError("user_id is required")
+        if not topic_id:
+            raise ValueError("topic_id is required")
+
+    def _validate_batch(self, requests: list[dict[str, Any]]) -> None:
+        """Validate the batch of recommendation requests."""
+        if len(requests) == 0:
+            raise ValueError("At least one request is required")
+        if len(requests) > 100:
+            raise ValueError("Maximum 100 requests allowed per batch")
+        for r in requests:
+            self._validate(
+                r.get("user_id", ""),
+                r.get("topic_id", ""),
+            )

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b24}/queue_sdk/types.py

@@ -147,6 +147,26 @@ class RecommendationResponse:
     processed_at: Optional[str] = None
 
 
+@dataclass
+class BatchRecommendationRequestData:
+    """Data for multiple recommendation requests."""
+
+    requests: list[dict]
+
+
+@dataclass
+class BatchRecommendationResponse:
+    """Response from a processed batch of recommendation requests."""
+
+    success: bool
+    message_id: str
+    total: int
+    successful: int
+    failed: int
+    error: Optional[str] = None
+    processed_at: Optional[str] = None
+
+
 @dataclass
 class ConvertData:
     """Data for a PDF/video to image conversion request."""

sf_queue_sdk-0.2.0b23/queue_sdk/queues/recommendation_queue.py

@@ -1,72 +0,0 @@
-"""Recommendation queue with typed methods."""
-
-from datetime import datetime, timezone
-from typing import Any, Optional
-
-import redis as redis_lib
-
-from queue_sdk.queues.base_queue import BaseQueue
-from queue_sdk.types import RecommendationResponse, SendResult
-
-
-class RecommendationQueue(BaseQueue):
-    """Typed methods for creating recommendation requests via the queue."""
-
-    def __init__(self, redis_client: redis_lib.Redis, environment: str):
-        super().__init__(redis_client, environment, "recommendation-requests")
-
-    def create(
-        self,
-        user_id: str,
-        topic_id: str,
-        limit: Optional[int] = None,
-    ) -> SendResult:
-        """Enqueue a recommendation request (fire and forget)."""
-        self._validate(user_id, topic_id)
-        payload = self._build_payload(user_id, topic_id, limit)
-        message_id = self._enqueue(payload)
-        return SendResult(message_id=message_id)
-
-    def create_and_wait(
-        self,
-        user_id: str,
-        topic_id: str,
-        limit: Optional[int] = None,
-        timeout: Optional[int] = None,
-    ) -> RecommendationResponse:
-        """Enqueue a recommendation request and wait for the result."""
-        self._validate(user_id, topic_id)
-        payload = self._build_payload(user_id, topic_id, limit)
-        response = self._enqueue_and_wait(payload, timeout)
-
-        return RecommendationResponse(
-            success=response.success,
-            message_id=response.message_id,
-            error=response.error,
-            processed_at=response.processed_at,
-        )
-
-    def _build_payload(
-        self,
-        user_id: str,
-        topic_id: str,
-        limit: Optional[int],
-    ) -> dict[str, Any]:
-        """Build the recommendation request payload."""
-        payload: dict[str, Any] = {
-            "userId": user_id,
-            "topicId": topic_id,
-            "requestedAt": datetime.now(timezone.utc).isoformat(),
-            "key": f"{user_id}-{topic_id}",
-        }
-        if limit is not None:
-            payload["limit"] = limit
-        return payload
-
-    @staticmethod
-    def _validate(user_id: str, topic_id: str) -> None:
-        """Validate the recommendation request."""
-        if not user_id:
-            raise ValueError("user_id is required")
-        if not topic_id:
-            raise ValueError("topic_id is required")