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

sf_queue_sdk-0.2.0b21/README.md → sf_queue_sdk-0.2.0b23/PKG-INFO

@@ -1,3 +1,11 @@
+Metadata-Version: 2.4
+Name: sf-queue-sdk
+Version: 0.2.0b23
+Summary: Python SDK for sf-queue - Redis-based queue system
+Requires-Python: >=3.11
+Requires-Dist: redis>=5.0.0
+Description-Content-Type: text/markdown
+
 # sf-queue-sdk
 
 Python SDK for sf-queue. Enqueues emails via Redis Streams with optional blocking confirmation from the Go consumer service.
@@ -350,6 +358,40 @@ result = client.tool_assignment.send_batch_and_wait(
 | `current_assignment` | `Optional[str]` | Yes | Current cluster_id (None for new embeddings) |
 | `new_assignment` | `str` | Yes | The cluster_id to assign to |
 
+## Recommendations
+
+### Fire and forget
+
+```python
+result = client.recommendations.create(
+    user_id="user_xyz",
+    topic_id="topic_abc123",
+    limit=10,  # optional
+)
+print("Enqueued:", result.message_id)
+```
+
+### Create and wait for result
+
+```python
+result = client.recommendations.create_and_wait(
+    user_id="user_xyz",
+    topic_id="topic_abc123",
+    limit=10,  # optional
+    timeout=30,
+)
+print(result.success)
+print(result.message_id)
+```
+
+### Recommendation Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `user_id` | `str` | Yes | User requesting recommendations |
+| `topic_id` | `str` | Yes | Topic context for recommendations |
+| `limit` | `Optional[int]` | No | Max recommendations to return |
+
 ## Cleanup
 
 ```python

sf_queue_sdk-0.2.0b21/PKG-INFO → sf_queue_sdk-0.2.0b23/README.md

@@ -1,11 +1,3 @@
-Metadata-Version: 2.4
-Name: sf-queue-sdk
-Version: 0.2.0b21
-Summary: Python SDK for sf-queue - Redis-based queue system
-Requires-Python: >=3.11
-Requires-Dist: redis>=5.0.0
-Description-Content-Type: text/markdown
-
 # sf-queue-sdk
 
 Python SDK for sf-queue. Enqueues emails via Redis Streams with optional blocking confirmation from the Go consumer service.
@@ -358,6 +350,40 @@ result = client.tool_assignment.send_batch_and_wait(
 | `current_assignment` | `Optional[str]` | Yes | Current cluster_id (None for new embeddings) |
 | `new_assignment` | `str` | Yes | The cluster_id to assign to |
 
+## Recommendations
+
+### Fire and forget
+
+```python
+result = client.recommendations.create(
+    user_id="user_xyz",
+    topic_id="topic_abc123",
+    limit=10,  # optional
+)
+print("Enqueued:", result.message_id)
+```
+
+### Create and wait for result
+
+```python
+result = client.recommendations.create_and_wait(
+    user_id="user_xyz",
+    topic_id="topic_abc123",
+    limit=10,  # optional
+    timeout=30,
+)
+print(result.success)
+print(result.message_id)
+```
+
+### Recommendation Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `user_id` | `str` | Yes | User requesting recommendations |
+| `topic_id` | `str` | Yes | Topic context for recommendations |
+| `limit` | `Optional[int]` | No | Max recommendations to return |
+
 ## Cleanup
 
 ```python

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

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

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

@@ -1,6 +1,6 @@
 """sf-queue Python SDK - Redis-based queue system."""
 
-__version__ = "0.2.0b21"
+__version__ = "0.2.0b23"
 
 from queue_sdk.client import QueueClient
 from queue_sdk.types import (
@@ -16,6 +16,8 @@ from queue_sdk.types import (
     EmailResponse,
     QueueClientConfig,
     QueueResponse,
+    RecommendationRequestData,
+    RecommendationResponse,
     SendResult,
     ToolAssignmentData,
     TopicAssignmentData,
@@ -31,6 +33,8 @@ __all__ = [
     "BatchEmailResponse",
     "QueueResponse",
     "BatchQueueResponse",
+    "RecommendationRequestData",
+    "RecommendationResponse",
     "TopicAssignmentData",
     "BatchTopicAssignmentData",
     "ToolAssignmentData",

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

@@ -2,6 +2,7 @@
 
 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
 from queue_sdk.queues.tool_assignment_queue import ToolAssignmentQueue
 from queue_sdk.queues.topic_assignment_queue import TopicAssignmentQueue
 from queue_sdk.redis_client import create_redis_client
@@ -65,6 +66,7 @@ class QueueClient:
         self.topic_assignment = TopicAssignmentQueue(self._redis, self._environment)
         self.tool_assignment = ToolAssignmentQueue(self._redis, self._environment)
         self.pdf_to_image = PdfToImageQueue(self._redis, self._environment)
+        self.recommendations = RecommendationQueue(self._redis, self._environment)
 
     def disconnect(self) -> None:
         """Close the Redis connection."""

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

@@ -0,0 +1,72 @@
+"""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")

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

@@ -128,6 +128,25 @@ class BatchToolAssignmentData:
     assignments: list[ToolAssignmentData]
 
 
+@dataclass
+class RecommendationRequestData:
+    """Data for a recommendation request (mirrors Kafka recommendationRequests)."""
+
+    user_id: str
+    topic_id: str
+    limit: Optional[int] = None
+
+
+@dataclass
+class RecommendationResponse:
+    """Response from a processed recommendation request."""
+
+    success: bool
+    message_id: str
+    error: Optional[str] = None
+    processed_at: Optional[str] = None
+
+
 @dataclass
 class ConvertData:
     """Data for a PDF/video to image conversion request."""