Merge pull request #23 from macrocosm-os/gen_2014_add_on_demand_data_keyword_mode

GEN-2014: Add keyword_mode parameter to OnDemandData requests

Author: lew-sword

README.md

@@ -85,8 +85,10 @@ print(polled_response)
 
 SN13 is focused on large-scale data collection. With the OnDemandAPI, you can run precise, real-time queries against platforms like X (Twitter) and Reddit (YouTube forthcoming).
 
-As of data-universe release [v1.9.8](https://github.com/macrocosm-os/data-universe/releases/tag/v1.9.8):
-- All keywords in the OnDemandData request will be present in the returned post/comment data.
+As of the latest data-universe [release](https://github.com/macrocosm-os/data-universe/releases/):
+- Users may select two post-filtering modes via the `keyword_mode` parameter: 
+    - `"any"`: Returns posts that contain any combination of the listed keywords.
+    - `"all"`: Returns posts that contain all of the keywords (default).
 - For Reddit requests, the first keyword in the list corresponds to the requested subreddit, and subsequent keywords are treated as normal.
 - For YouTube requests, only one username should be supplied - corresponding to the channel name - while keywords are ignored (empty list).
 
@@ -105,7 +107,8 @@ response = client.sn13.OnDemandData(
     keywords=["galaxy"],        # Optional, up to 5 keywords
     start_date='2025-04-15',    # Defaults to 24h range if not specified
     end_date='2025-05-15',      # Defaults to current time if not specified
-    limit=1000                  # Optional, up to 1000 results
+    limit=1000,                 # Optional, up to 1000 results
+    keyword_mode='any'          # Optional, "any" or "all"
 )
 
 print(response)

examples/sn13_on_demand_data.py

@@ -1,8 +1,10 @@
 """
 Example of using the SN13 On Demand Data Streaming service with Macrocosmos SDK.
 
-As of data-universe release v1.9.8:
-    - All keywords in the OnDemandData request will be present in the returned post/comment data.
+As of the latest data-universe release:
+    - Users may select two post-filtering modes via the keyword_mode parameter:
+        - "any": Returns posts that contain any combination of the listed keywords.
+        - "all": Returns posts that contain all of the keywords (default, if field omitted).
     - For Reddit requests, the first keyword in the list corresponds to the requested subreddit, and subsequent keywords are treated as normal.
     - For YouTube requests, only one username should be supplied - corresponding to the channel name - while keywords are ignored (empty list).
 """
@@ -21,7 +23,8 @@
     keywords=["photo", "space", "mars"],
     start_date="2024-04-01",
     end_date="2025-04-25",
-    limit=3,
+    limit=5,
+    keyword_mode="any",
 )
 
 print(response)

examples/sn13_on_demand_data_async.py

@@ -2,15 +2,18 @@
 Example demonstrating concurrent async operations with the SN13 On Demand Data service.
 Shows how multiple requests can be processed simultaneously in an async context.
 
-As of data-universe release v1.9.8:
-    - All keywords in the OnDemandData request will be present in the returned post/comment data.
+As of the latest data-universe release:
+    - Users may select two post-filtering modes via the keyword_mode parameter:
+        - "any": Returns posts that contain any combination of the listed keywords.
+        - "all": Returns posts that contain all of the keywords (default, if field omitted).
     - For Reddit requests, the first keyword in the list corresponds to the requested subreddit, and subsequent keywords are treated as normal.
     - For YouTube requests, only one username should be supplied - corresponding to the channel name - while keywords are ignored (empty list).
 """
 
 import os
 import asyncio
 import time
+from typing import Optional
 
 import macrocosmos as mc
 
@@ -24,6 +27,7 @@ async def fetch_data(
     end_date: str,
     limit: int,
     request_id: int,
+    keyword_mode: Optional[str] = None,
 ):
     """Fetch data for a single request and track its timing."""
     start_time = time.time()
@@ -36,6 +40,7 @@ async def fetch_data(
         start_date=start_date,
         end_date=end_date,
         limit=limit,
+        keyword_mode=keyword_mode,
     )
 
     end_time = time.time()
@@ -60,27 +65,34 @@ async def main():
             "keywords": [
                 "photo",
                 "space",
-            ],  # Posts including both keywords will be returned
+            ],  # Posts including either keyword will be returned
             "start_date": "2024-04-01",
             "end_date": "2024-04-30",
             "limit": 5,
             "request_id": 1,
+            "keyword_mode": "any",
         },
         {
             "source": "reddit",
-            "usernames": ["TheMuseumOfScience"],
-            "keywords": ["r/nasa", "vision"],  # First keyword is the subreddit
-            "start_date": "2025-04-01",
-            "end_date": "2025-08-25",
-            "limit": 1,
+            "usernames": [],
+            "keywords": [
+                "r/CasualUK",
+                "moon",
+                "tonight",
+                "nice",
+            ],  # First keyword is the subreddit, next keywords should all appear in returned posts
+            "start_date": "2025-09-01",
+            "end_date": "2025-09-08",
+            "limit": 5,
             "request_id": 2,
+            "keyword_mode": "all",
         },
         {
             "source": "youtube",
             "usernames": ["veritasium"],
             "keywords": [],  # YouTube does not currently support keywords, list left empty
-            "start_date": "2025-08-01",
-            "end_date": "2025-08-06",
+            "start_date": "2025-07-01",
+            "end_date": "2025-09-06",
             "limit": 1,
             "request_id": 3,
         },

protos/apex/v1/apex.proto

@@ -25,11 +25,14 @@ service ApexService {
   rpc GetDeepResearcherJob(GetDeepResearcherJobRequest) returns (GetDeepResearcherJobResponse);
 
   // GetChatSessions retrieves a user's chats
-  rpc GetChatSessions(google.protobuf.Empty) returns (GetChatSessionsResponse);
+  rpc GetChatSessions(GetChatSessionsRequest) returns (GetChatSessionsResponse);
 
   // GetStoredChatCompletions retrieves a chat's completions
   rpc GetStoredChatCompletions(GetStoredChatCompletionsRequest) returns (GetStoredChatCompletionsResponse);
 
+  // GetChatCompletion retrieves a completion by its ID
+  rpc GetChatCompletion(GetChatCompletionRequest) returns (StoredChatCompletion);
+
   // UpdateChatAttributes updates specified attributes of a chat
   rpc UpdateChatAttributes(UpdateChatAttributesRequest) returns (UpdateChatAttributesResponse);
 
@@ -461,12 +464,24 @@ message GetChatSessionsResponse {
   repeated ChatSession chat_sessions = 1;
 }
 
+// A GetChatSessionsRequest message
+message GetChatSessionsRequest {
+  // chat_type: type of chat (e.g. "apex" or "gravity")
+  string chat_type = 1;
+}
+
 // A GetStoredChatCompletionRequest request message
 message GetStoredChatCompletionsRequest {
   // chat_id: a unique identifier for a chat
   string chat_id = 1;
 }
 
+// A GetChatCompletionRequest request message
+message GetChatCompletionRequest {
+  // completion_id: a unique identifier for a completion
+  string completion_id = 1;
+}
+
 
 // A StoredChatCompletion message repeated in GetStoredChatCompletionsResponse
 message StoredChatCompletion {
@@ -620,6 +635,8 @@ message UpdateCompletionAttributesRequest {
   optional string completion_text = 2;
   // metadata: metadata json blob (optional)
   google.protobuf.Struct metadata = 3;
+  // user_prompt_text: the user's prompt text (optional)
+  optional string user_prompt_text = 4;
 }
 
 // An UpdateCompletionAttributes response