Update documentation and enhance functionality

- Added semantic search examples to the README for better user guidance.
- Modified user agent in request.R to dynamically reflect package version.
- Enhanced SearchResource class to include `concept_class_id` parameter for filtering.
- Updated documentation for `SearchResource` to reflect new parameter.

Author: alex-omophub

.github/FUNDING.yml

@@ -6,6 +6,7 @@
 .Ruserdata
 *.Rcheck/
 *.tar.gz
+dump.rdb
 
 # Build artifacts
 docs/

.gitignore

@@ -20,7 +20,7 @@ build_request <- function(base_url, api_key, timeout = 30, max_retries = 3,
       "Content-Type" = "application/json",
       "Accept" = "application/json"
     ) |>
-    httr2::req_user_agent("OMOPHub-SDK-R/1.0.0") |>
+    httr2::req_user_agent(paste0("OMOPHub-SDK-R/", utils::packageVersion("omophub"))) |>
     httr2::req_timeout(timeout) |>
     httr2::req_throttle(
       rate = .omophub_env$rate_limit_capacity / .omophub_env$rate_limit_fill_time

R/request.R

@@ -280,6 +280,7 @@ SearchResource <- R6::R6Class(
     #' @param vocabulary_ids Filter by vocabulary IDs.
     #' @param domain_ids Filter by domain IDs.
     #' @param standard_concept Filter by standard concept ('S' or 'C').
+    #' @param concept_class_id Filter by concept class ID.
     #' @param threshold Minimum similarity threshold (0.0-1.0).
     #' @param page_size Results per page. Default 100.
     #' @param max_pages Maximum pages to fetch. Default Inf.
@@ -290,6 +291,7 @@ SearchResource <- R6::R6Class(
                             vocabulary_ids = NULL,
                             domain_ids = NULL,
                             standard_concept = NULL,
+                            concept_class_id = NULL,
                             threshold = NULL,
                             page_size = 100,
                             max_pages = Inf,
@@ -300,6 +302,7 @@ SearchResource <- R6::R6Class(
           vocabulary_ids = vocabulary_ids,
           domain_ids = domain_ids,
           standard_concept = standard_concept,
+          concept_class_id = concept_class_id,
           threshold = threshold,
           page = page,
           page_size = size

R/search.R

@@ -82,6 +82,29 @@ mappings <- client$mappings$get(201826, target_vocabulary = "ICD10CM")
 ancestors <- client$hierarchy$ancestors(201826, max_levels = 3)
 ```
 
+## Semantic Search
+
+Use natural language queries to find concepts using neural embeddings:
+
+```r
+# Natural language search - understands clinical intent
+results <- client$search$semantic("high blood sugar levels")
+for (r in results$data$results) {
+  cat(sprintf("%s (similarity: %.2f)\n", r$concept_name, r$similarity_score))
+}
+
+# Filter by vocabulary and set minimum similarity threshold
+results <- client$search$semantic(
+  "heart attack",
+  vocabulary_ids = "SNOMED",
+  domain_ids = "Condition",
+  threshold = 0.5
+)
+
+# Fetch all results with auto-pagination
+all_results <- client$search$semantic_all("chronic kidney disease", page_size = 50)
+```
+
 ## Use Cases
 
 ### ETL & Data Pipelines
@@ -169,7 +192,7 @@ concepts_df %>%
 | Resource | Description | Key Methods |
 |----------|-------------|-------------|
 | `concepts` | Concept lookup and batch operations | `get()`, `get_by_code()`, `batch()`, `suggest()` |
-| `search` | Full-text and semantic search | `basic()`, `advanced()`, `basic_all()` |
+| `search` | Full-text and semantic search | `basic()`, `advanced()`, `semantic()`, `semantic_all()`, `basic_all()` |
 | `hierarchy` | Navigate concept relationships | `ancestors()`, `descendants()` |
 | `mappings` | Cross-vocabulary mappings | `get()`, `map()` |
 | `vocabularies` | Vocabulary metadata | `list()`, `get()`, `stats()` |