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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sf-queue-sdk
-Version: 0.2.0b21
+Version: 0.2.0b24
 Summary: Python SDK for sf-queue - Redis-based queue system
 Requires-Python: >=3.11
 Requires-Dist: redis>=5.0.0
@@ -358,6 +358,91 @@ 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)
+```
+
+### 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 |
+|-------|------|----------|-------------|
+| `user_id` | `str` | Yes | User requesting recommendations |
+| `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.0b21 → sf_queue_sdk-0.2.0b24}/README.md

@@ -350,6 +350,91 @@ 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)
+```
+
+### 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 |
+|-------|------|----------|-------------|
+| `user_id` | `str` | Yes | User requesting recommendations |
+| `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.0b21 → sf_queue_sdk-0.2.0b24}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sf-queue-sdk"
-version = "0.2.0b21"
+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.0b21 → 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.0b21"
+__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,
@@ -16,6 +19,8 @@ from queue_sdk.types import (
     EmailResponse,
     QueueClientConfig,
     QueueResponse,
+    RecommendationRequestData,
+    RecommendationResponse,
     SendResult,
     ToolAssignmentData,
     TopicAssignmentData,
@@ -23,6 +28,7 @@ from queue_sdk.types import (
 
 __all__ = [
     "QueueClient",
+    "QueryClient",
     "QueueClientConfig",
     "EmailData",
     "EmailButton",
@@ -31,6 +37,10 @@ __all__ = [
     "BatchEmailResponse",
     "QueueResponse",
     "BatchQueueResponse",
+    "RecommendationRequestData",
+    "RecommendationResponse",
+    "BatchRecommendationRequestData",
+    "BatchRecommendationResponse",
     "TopicAssignmentData",
     "BatchTopicAssignmentData",
     "ToolAssignmentData",

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

@@ -1,7 +1,9 @@
 """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
 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 +67,8 @@ 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)
+        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.0b21 → sf_queue_sdk-0.2.0b24}/queue_sdk/types.py

@@ -128,6 +128,45 @@ 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 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."""