Release version 1.5.0 with new bulk search features

Author: alex-omophub

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: omophub
 Title: R Client for the 'OMOPHub' Medical Vocabulary API
-Version: 1.4.0
+Version: 1.5.0
 Authors@R: c(
     person("Alex", "Chen", email = "alex@omophub.com", role = c("aut", "cre", "cph")),
     person("Observational Health Data Science and Informatics", role = c("cph"))

NEWS.md

@@ -1,3 +1,17 @@
+# omophub 1.5.0
+
+## New Features
+
+* **Bulk lexical search** (`bulk_basic()`): Execute up to 50 keyword searches
+  in a single API call. Supports shared default filters for vocabulary, domain,
+  and other parameters. Each search is identified by a unique `search_id` for
+  result matching. Maps to `POST /v1/search/bulk`.
+
+* **Bulk semantic search** (`bulk_semantic()`): Execute up to 25 natural-language
+  searches using neural embeddings in a single call. Supports per-search
+  similarity thresholds and shared defaults. Query length validated at 1-500
+  characters. Maps to `POST /v1/search/semantic-bulk`.
+
 # omophub 1.4.0
 
 ## New Features

inst/examples/search_concepts.R

@@ -276,6 +276,79 @@ for (s in similar$similar_concepts) {
 }
 cat("\n")
 
+# ============================================================================
+# Bulk Lexical Search
+# ============================================================================
+
+cat("11. Bulk lexical search (multiple queries in one call)\n")
+cat("------------------------------------------------------\n")
+
+# Search for multiple terms at once (up to 50)
+results <- client$search$bulk_basic(list(
+  list(search_id = "q1", query = "diabetes mellitus"),
+  list(search_id = "q2", query = "hypertension"),
+  list(search_id = "q3", query = "aspirin")
+), defaults = list(vocabulary_ids = list("SNOMED"), page_size = 3))
+
+cat("Bulk search results:\n")
+for (item in results$results) {
+  cat(sprintf("  %s: %d results (%s)\n",
+              item$search_id, length(item$results), item$status))
+}
+cat("\n")
+
+# ============================================================================
+# Bulk Semantic Search
+# ============================================================================
+
+cat("12. Bulk semantic search (multiple NLP queries)\n")
+cat("------------------------------------------------\n")
+
+# Search for multiple natural-language queries at once (up to 25)
+results <- client$search$bulk_semantic(list(
+  list(search_id = "s1", query = "heart failure treatment options"),
+  list(search_id = "s2", query = "type 2 diabetes medication"),
+  list(search_id = "s3", query = "elevated blood pressure")
+), defaults = list(threshold = 0.5, page_size = 5))
+
+cat("Bulk semantic results:\n")
+for (item in results$results) {
+  n_results <- item$result_count %||% length(item$results)
+  cat(sprintf("  %s: %d results (%s)\n",
+              item$search_id, n_results, item$status))
+
+  # Show top result for each query
+  if (length(item$results) > 0) {
+    top <- item$results[[1]]
+    cat(sprintf("    Top: %s (score: %.2f)\n",
+                top$concept_name, top$similarity_score))
+  }
+}
+cat("\n")
+
+# ============================================================================
+# Bulk Search with Per-Query Overrides
+# ============================================================================
+
+cat("13. Bulk search with per-query filters\n")
+cat("--------------------------------------\n")
+
+# Defaults apply to all, but individual searches can override
+results <- client$search$bulk_basic(list(
+  list(search_id = "conditions", query = "diabetes", domain_ids = list("Condition")),
+  list(search_id = "drugs", query = "metformin", domain_ids = list("Drug"))
+), defaults = list(vocabulary_ids = list("SNOMED", "RxNorm"), page_size = 3))
+
+for (item in results$results) {
+  cat(sprintf("  %s:\n", item$search_id))
+  for (c in item$results) {
+    cat(sprintf("    [%d] %s (%s/%s)\n",
+                c$concept_id, c$concept_name,
+                c$vocabulary_id, c$domain_id))
+  }
+}
+cat("\n")
+
 # ============================================================================
 # Done
 # ============================================================================

vignettes/getting-started.Rmd

@@ -188,6 +188,53 @@ similar <- client$search$similar(
 )
 ```
 
+## Bulk Search
+
+Search for multiple queries in a single API call — much faster than individual requests when you have many terms to look up.
+
+### Bulk Lexical Search
+
+Execute up to 50 keyword searches at once:
+
+```{r bulk-basic}
+results <- client$search$bulk_basic(list(
+  list(search_id = "q1", query = "diabetes mellitus"),
+  list(search_id = "q2", query = "hypertension"),
+  list(search_id = "q3", query = "aspirin")
+), defaults = list(vocabulary_ids = list("SNOMED"), page_size = 5))
+
+# Each result is matched by search_id
+for (item in results$results) {
+  cat(sprintf("%s: %d results\n", item$search_id, length(item$results)))
+}
+```
+
+### Bulk Semantic Search
+
+Execute up to 25 natural-language searches using neural embeddings:
+
+```{r bulk-semantic}
+results <- client$search$bulk_semantic(list(
+  list(search_id = "s1", query = "heart failure treatment options"),
+  list(search_id = "s2", query = "type 2 diabetes medication")
+), defaults = list(threshold = 0.5, page_size = 10))
+
+for (item in results$results) {
+  cat(sprintf("%s: %d results\n", item$search_id,
+              item$result_count %||% length(item$results)))
+}
+```
+
+Defaults apply to all searches; per-search values override them:
+
+```{r bulk-overrides}
+# Different domains per query, shared vocabulary filter
+results <- client$search$bulk_basic(list(
+  list(search_id = "cond", query = "diabetes", domain_ids = list("Condition")),
+  list(search_id = "drug", query = "metformin", domain_ids = list("Drug"))
+), defaults = list(vocabulary_ids = list("SNOMED", "RxNorm"), page_size = 5))
+```
+
 ## Autocomplete
 
 Get suggestions for autocomplete: