v1.4.0 release

Author: alex-omophub

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2026-02-23
+
+### Added
+
+- **Semantic search** (`search.semantic()`, `search.semantic_iter()`): Natural language concept search using neural embeddings. Search for clinical intent like "high blood sugar levels" to find diabetes-related concepts. Supports filtering by vocabulary, domain, standard concept, concept class, and minimum similarity threshold. `semantic_iter()` provides automatic pagination.
+- **Similarity search** (`search.similar()`): Find concepts similar to a reference concept ID, concept name, or natural language query. Three algorithm options: `'semantic'` (neural embeddings), `'lexical'` (string matching), and `'hybrid'` (combined). Configurable similarity threshold with optional detailed scores and explanations.
+
 ## [1.3.1] - 2026-01-24
 
 ### Fixed
@@ -83,7 +90,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Full type hints and PEP 561 compliance
 - HTTP/2 support via httpx
 
-[Unreleased]: https://github.com/omopHub/omophub-python/compare/v1.3.1...HEAD
+[Unreleased]: https://github.com/omopHub/omophub-python/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/omopHub/omophub-python/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/omopHub/omophub-python/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/omopHub/omophub-python/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/omopHub/omophub-python/compare/v0.1.0...v1.2.0

README.md

@@ -81,6 +81,26 @@ for result in client.search.semantic_iter("chronic kidney disease", page_size=50
     print(f"{result['concept_id']}: {result['concept_name']}")
 ```
 
+### Similarity Search
+
+Find concepts similar to a known concept or natural language query:
+
+```python
+# Find concepts similar to a known concept
+results = client.search.similar(concept_id=201826, algorithm="hybrid")
+for r in results["results"]:
+    print(f"{r['concept_name']} (score: {r['similarity_score']:.2f})")
+
+# Find similar concepts using a natural language query
+results = client.search.similar(
+    query="medications for high blood pressure",
+    algorithm="semantic",
+    similarity_threshold=0.6,
+    vocabulary_ids=["RxNorm"],
+    include_scores=True,
+)
+```
+
 ## Async Support
 
 ```python
@@ -153,7 +173,7 @@ suggestions = client.concepts.suggest("diab", vocabulary_ids=["SNOMED"], page_si
 | Resource | Description | Key Methods |
 |----------|-------------|-------------|
 | `concepts` | Concept lookup and batch operations | `get()`, `get_by_code()`, `batch()`, `suggest()` |
-| `search` | Full-text and semantic search | `basic()`, `advanced()`, `semantic()`, `semantic_iter()`, `fuzzy()` |
+| `search` | Full-text and semantic search | `basic()`, `advanced()`, `semantic()`, `semantic_iter()`, `similar()`, `fuzzy()` |
 | `hierarchy` | Navigate concept relationships | `ancestors()`, `descendants()` |
 | `mappings` | Cross-vocabulary mappings | `get()`, `map()` |
 | `vocabularies` | Vocabulary metadata | `list()`, `get()`, `stats()` |

examples/search_concepts.py

@@ -80,9 +80,68 @@ def pagination_example() -> None:
         print(f"  ... and {count - 3} more concepts shown (demo limited to {count})")
 
 
+def semantic_search() -> None:
+    """Demonstrate semantic search using neural embeddings."""
+    print("\n=== Semantic Search ===")
+
+    # Natural language search - understands clinical intent
+    results = client.search.semantic("high blood sugar levels")
+    for r in results["results"][:3]:
+        print(f"  {r['concept_name']} (similarity: {r['similarity_score']:.2f})")
+
+    # Filtered semantic search with minimum threshold
+    results = client.search.semantic(
+        "heart attack",
+        vocabulary_ids=["SNOMED"],
+        domain_ids=["Condition"],
+        threshold=0.5,
+    )
+    print(f"  Found {len(results['results'])} SNOMED conditions for 'heart attack'")
+
+
+def semantic_pagination() -> None:
+    """Demonstrate auto-pagination with semantic_iter."""
+    print("\n=== Semantic Pagination ===")
+
+    count = 0
+    for result in client.search.semantic_iter("chronic kidney disease", page_size=20):
+        count += 1
+        if count <= 3:
+            print(f"  {result['concept_id']}: {result['concept_name']}")
+        if count >= 50:  # Limit for demo
+            break
+
+    if count > 3:
+        print(f"  ... and {count - 3} more results (demo limited to {count})")
+
+
+def similarity_search() -> None:
+    """Demonstrate similarity search."""
+    print("\n=== Similarity Search ===")
+
+    # Find concepts similar to Type 2 diabetes mellitus (concept_id=201826)
+    results = client.search.similar(concept_id=201826, algorithm="hybrid")
+    print("Concepts similar to 'Type 2 diabetes mellitus':")
+    for r in results["results"][:5]:
+        print(f"  {r['concept_name']} (score: {r['similarity_score']:.2f})")
+
+    # Find similar using a natural language query with semantic algorithm
+    results = client.search.similar(
+        query="medications for high blood pressure",
+        algorithm="semantic",
+        similarity_threshold=0.6,
+        vocabulary_ids=["RxNorm"],
+        include_scores=True,
+    )
+    print(f"\n  Found {len(results['results'])} similar RxNorm concepts")
+
+
 if __name__ == "__main__":
     basic_search()
     filtered_search()
     fuzzy_search()
     autocomplete_example()
     pagination_example()
+    semantic_search()
+    semantic_pagination()
+    similarity_search()

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "omophub"
 dynamic = ["version"]
-description = "Python SDK for OMOPHub - Medical Vocabulary API"
+description = "Python SDK for OMOPHub - Medical Vocabulary API with semantic search"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -27,6 +27,9 @@ keywords = [
     "terminology",
     "api",
     "sdk",
+    "semantic-search",
+    "embeddings",
+    "nlp",
 ]
 classifiers = [
     "Development Status :: 4 - Beta",