Refactor examples to remove hardcoded API keys

- Updated example scripts.
- Adjusted search and resolution methods in examples to reflect the new API response structures, ensuring consistency across examples.
- Improved documentation and comments in example scripts for clarity and better user guidance.

Author: alex-omophub

examples/async_usage.py

@@ -11,24 +11,23 @@ async def basic_async_usage() -> None:
     print("=== Basic Async Usage ===")
 
     # Use async context manager
-    async with omophub.AsyncOMOPHub(api_key="oh_your_api_key") as client:
+    async with omophub.AsyncOMOPHub() as client:
         # Get a concept
         concept = await client.concepts.get(201826)
         print(f"Concept: {concept['concept_name']}")
 
-        # Search
-        results = await client.search.basic("diabetes", page_size=5)
-        concepts = results.get("concepts", [])
+        # Search - returns a flat list of concept dicts
+        concepts = await client.search.basic("diabetes", page_size=5)
         print(f"Found {len(concepts)} concepts")
 
 
 async def concurrent_requests() -> None:
     """Demonstrate concurrent API requests."""
     print("\n=== Concurrent Requests ===")
 
-    async with omophub.AsyncOMOPHub(api_key="oh_your_api_key") as client:
+    async with omophub.AsyncOMOPHub() as client:
         # Fetch multiple concepts concurrently
-        concept_ids = [201826, 4329847, 1112807, 40483312, 37311061]
+        concept_ids = [201826, 4329847, 1112807, 316866, 37311061]
 
         tasks = [client.concepts.get(cid) for cid in concept_ids]
         concepts = await asyncio.gather(*tasks)
@@ -42,26 +41,20 @@ async def parallel_searches() -> None:
     """Demonstrate parallel search operations."""
     print("\n=== Parallel Searches ===")
 
-    async with omophub.AsyncOMOPHub(api_key="oh_your_api_key") as client:
-        # Run multiple searches in parallel
+    async with omophub.AsyncOMOPHub() as client:
+        # Run multiple searches in parallel. ``search.basic`` returns a
+        # flat list of concept dicts for the current page; for the full
+        # total count we iterate across pages via ``basic_iter``.
         search_terms = ["diabetes", "hypertension", "asthma", "depression"]
 
-        async def search_and_count(term: str) -> tuple[str, int]:
-            results = await client.search.basic(term, page_size=1)
-            # Get total from pagination metadata if available
-            meta = results.get("meta", {}).get("pagination", {})
-            total_items = meta.get("total_items")
-            if total_items is not None:
-                total = total_items
-            else:
-                concepts = results.get("concepts", [])
-                total = len(concepts) if isinstance(concepts, list) else 0
-            return term, total
-
-        tasks = [search_and_count(term) for term in search_terms]
+        async def page_count(term: str) -> tuple[str, int]:
+            concepts = await client.search.basic(term, page_size=50)
+            return term, len(concepts)
+
+        tasks = [page_count(term) for term in search_terms]
         results = await asyncio.gather(*tasks)
 
-        print("Search results:")
+        print("First-page hit counts:")
         for term, count in results:
             print(f"  '{term}': {count} concepts")
 

examples/basic_usage.py

@@ -6,9 +6,9 @@
 
 def main() -> None:
     """Demonstrate basic SDK usage."""
-    # Initialize the client with your API key
-    # You can also set OMOPHUB_API_KEY environment variable
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    # Reads OMOPHUB_API_KEY from the environment. To pass it explicitly:
+    #   client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
 
     # Get a concept by ID
     concept = client.concepts.get(201826)
@@ -18,18 +18,18 @@ def main() -> None:
     print(f"  Domain: {concept['domain_id']}")
     print()
 
-    # Search for concepts
+    # Search for concepts - returns a list of concept dicts
     results = client.search.basic(
         "diabetes",
         vocabulary_ids=["SNOMED"],
         page_size=5,
     )
     print("Search results for 'diabetes':")
-    for c in results.get("concepts", []):
+    for c in results:
         print(f"  {c['concept_id']}: {c['concept_name']}")
     print()
 
-    # List vocabularies
+    # List vocabularies - returns a dict with a 'vocabularies' key
     vocabs = client.vocabularies.list(page_size=5)
     print("Available vocabularies:")
     for v in vocabs.get("vocabularies", []):

examples/error_handling.py

@@ -10,7 +10,7 @@ def handle_not_found() -> None:
     """Handle concept not found errors."""
     print("=== Handling Not Found ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
 
     try:
         # Try to get a non-existent concept
@@ -40,7 +40,7 @@ def handle_rate_limit() -> None:
     """Handle rate limit errors with retry."""
     print("\n=== Handling Rate Limits ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
 
     for i in range(5):
         try:
@@ -58,7 +58,7 @@ def handle_validation() -> None:
     """Handle validation errors."""
     print("\n=== Handling Validation Errors ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
 
     try:
         # Try an invalid request
@@ -73,7 +73,7 @@ def comprehensive_error_handling() -> None:
     """Demonstrate comprehensive error handling."""
     print("\n=== Comprehensive Error Handling ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
 
     try:
         concept = client.concepts.get(201826)

examples/fhir_interop.py

@@ -31,6 +31,7 @@
 
 from __future__ import annotations
 
+import os
 from types import SimpleNamespace
 from typing import TYPE_CHECKING
 
@@ -39,7 +40,12 @@
 if TYPE_CHECKING:
     from omophub.types.fhir import Coding
 
-API_KEY = "oh_your_api_key"
+# Read from the environment so the example runs out-of-the-box:
+#   export OMOPHUB_API_KEY=oh_...
+# Scenario 8 (get_fhirpy_client) needs an explicit key string, so we
+# materialize it once here. All other scenarios use omophub.OMOPHub()
+# directly, which also picks up OMOPHUB_API_KEY.
+API_KEY = os.environ.get("OMOPHUB_API_KEY", "oh_your_api_key")
 
 
 # ---------------------------------------------------------------------------
@@ -51,7 +57,7 @@ def coding_kwarg_with_dict() -> None:
     """Pass a plain dict via the new ``coding=`` kwarg."""
     print("=== 1. coding= kwarg with a plain dict ===")
 
-    client = omophub.OMOPHub(api_key=API_KEY)
+    client = omophub.OMOPHub()
     try:
         result = client.fhir.resolve(
             coding={
@@ -76,7 +82,7 @@ def coding_kwarg_with_typed_dict() -> None:
     """Use omophub's lightweight `Coding` TypedDict for IDE autocomplete."""
     print("\n=== 2. coding= kwarg with omophub.types.fhir.Coding ===")
 
-    client = omophub.OMOPHub(api_key=API_KEY)
+    client = omophub.OMOPHub()
     try:
         coding: Coding = {
             "system": "http://loinc.org",
@@ -105,7 +111,7 @@ def coding_kwarg_with_duck_object() -> None:
     """
     print("\n=== 3. coding= kwarg with a duck-typed object ===")
 
-    client = omophub.OMOPHub(api_key=API_KEY)
+    client = omophub.OMOPHub()
     try:
         # SimpleNamespace stands in for any Coding-like class - fhir.resources,
         # fhirpy, or your own domain model.
@@ -143,7 +149,7 @@ def coding_kwarg_with_fhir_resources() -> None:
         print("  Skipped: pip install omophub[fhir-resources]")
         return
 
-    client = omophub.OMOPHub(api_key=API_KEY)
+    client = omophub.OMOPHub()
     try:
         # Single Coding from fhir.resources
         snomed = FhirCoding(
@@ -191,7 +197,7 @@ def mixed_batch_inputs() -> None:
     """A single `resolve_batch` accepts heterogeneous coding shapes."""
     print("\n=== 5. resolve_batch with mixed input shapes ===")
 
-    client = omophub.OMOPHub(api_key=API_KEY)
+    client = omophub.OMOPHub()
     try:
         typed: Coding = {"system": "http://loinc.org", "code": "2339-0"}
         duck = SimpleNamespace(
@@ -232,7 +238,7 @@ def explicit_kwargs_override_coding() -> None:
     """
     print("\n=== 6. Explicit kwargs override coding= fields ===")
 
-    client = omophub.OMOPHub(api_key=API_KEY)
+    client = omophub.OMOPHub()
     try:
         base = SimpleNamespace(
             system="http://snomed.info/sct",
@@ -262,7 +268,7 @@ def connection_helper_urls() -> None:
 
     from omophub import get_fhir_server_url
 
-    client = omophub.OMOPHub(api_key=API_KEY)
+    client = omophub.OMOPHub()
     try:
         # Property on the client returns the R4 base URL
         print(f"  client.fhir_server_url = {client.fhir_server_url}")

examples/fhir_resolver.py

@@ -29,7 +29,7 @@ def resolve_snomed() -> None:
     """Resolve a SNOMED CT code directly to its OMOP concept."""
     print("=== 1. SNOMED Direct Resolution ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
     try:
         result = client.fhir.resolve(
             system="http://snomed.info/sct",
@@ -57,7 +57,7 @@ def resolve_icd10_mapped() -> None:
     """Resolve a non-standard ICD-10-CM code — automatically traverses Maps to."""
     print("\n=== 2. ICD-10-CM → SNOMED Mapping ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
     try:
         result = client.fhir.resolve(
             system="http://hl7.org/fhir/sid/icd-10-cm",
@@ -89,7 +89,7 @@ def resolve_loinc() -> None:
     """Resolve a LOINC lab code to the OMOP measurement table."""
     print("\n=== 3. LOINC → Measurement ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
     try:
         result = client.fhir.resolve(
             system="http://loinc.org",
@@ -116,7 +116,7 @@ def resolve_rxnorm() -> None:
     """Resolve an RxNorm drug code to the OMOP drug_exposure table."""
     print("\n=== 4. RxNorm → Drug Exposure ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
     try:
         result = client.fhir.resolve(
             system="http://www.nlm.nih.gov/research/umls/rxnorm",
@@ -141,7 +141,7 @@ def resolve_text_only() -> None:
     """Resolve using only display text — triggers BioLORD semantic search."""
     print("\n=== 5. Text-Only Semantic Fallback ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
     try:
         # No system or code — just natural language text
         result = client.fhir.resolve(
@@ -168,7 +168,7 @@ def resolve_vocabulary_id_bypass() -> None:
     """Use vocabulary_id directly when you already know the OMOP vocabulary."""
     print("\n=== 6. Vocabulary ID Bypass ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
     try:
         # Skip URI resolution — go straight to the vocabulary
         result = client.fhir.resolve(
@@ -193,7 +193,7 @@ def resolve_with_recommendations() -> None:
     """Get Phoebe-recommended related concepts alongside the resolution."""
     print("\n=== 7. With Phoebe Recommendations ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
     try:
         result = client.fhir.resolve(
             system="http://snomed.info/sct",
@@ -225,7 +225,7 @@ def resolve_with_quality() -> None:
     """Get a mapping quality signal to triage which resolutions need review."""
     print("\n=== 8. With Mapping Quality ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
     try:
         # Direct SNOMED match → "high" quality
         result = client.fhir.resolve(
@@ -273,7 +273,7 @@ def resolve_batch() -> None:
     """Resolve multiple codings in a single call with per-item error reporting."""
     print("\n=== 9. Batch Resolution ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
     try:
         result = client.fhir.resolve_batch(
             [
@@ -324,7 +324,7 @@ def resolve_codeable_concept() -> None:
     """Resolve a CodeableConcept with multiple codings — SNOMED wins by preference."""
     print("\n=== 10. CodeableConcept Resolution ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
     try:
         result = client.fhir.resolve_codeable_concept(
             coding=[
@@ -382,7 +382,7 @@ def resolve_codeable_concept_text_fallback() -> None:
     """When no structured coding resolves, fall back to the text field."""
     print("\n=== 11. CodeableConcept Text Fallback ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
     try:
         result = client.fhir.resolve_codeable_concept(
             coding=[
@@ -420,7 +420,7 @@ async def async_resolve() -> None:
     """Demonstrate async FHIR resolution with concurrent requests."""
     print("\n=== 12. Async FHIR Resolution ===")
 
-    async with omophub.AsyncOMOPHub(api_key="oh_your_api_key") as client:
+    async with omophub.AsyncOMOPHub() as client:
         # Single resolve
         result = await client.fhir.resolve(
             system="http://snomed.info/sct",
@@ -463,7 +463,7 @@ def error_handling_examples() -> None:
     """Demonstrate error responses from the FHIR resolver."""
     print("\n=== Error Handling Examples ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
     try:
         # Unknown code system URI → 400 with suggestion
         print("  Typo in URI:")

examples/map_between_vocabularies.py

@@ -8,7 +8,7 @@ def get_mappings() -> None:
     """Get mappings for a concept to other vocabularies."""
     print("=== Concept Mappings ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
 
     try:
         # Type 2 diabetes mellitus (SNOMED)
@@ -43,7 +43,7 @@ def map_concepts() -> None:
     """Map multiple concepts to a target vocabulary."""
     print("\n=== Batch Concept Mapping ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
 
     try:
         # Map SNOMED concepts to ICD-10-CM
@@ -74,7 +74,7 @@ def lookup_by_code() -> None:
     """Look up a concept by vocabulary code and find its standard mapping."""
     print("\n=== Code Lookup and Mapping ===")
 
-    client = omophub.OMOPHub(api_key="oh_your_api_key")
+    client = omophub.OMOPHub()
 
     try:
         # Look up ICD-10-CM code E11 (Type 2 diabetes)

examples/navigate_hierarchy.py

@@ -3,7 +3,9 @@
 
 import omophub
 
-client = omophub.OMOPHub(api_key="oh_your_api_key")
+# Reads OMOPHUB_API_KEY from the environment. To pass it explicitly:
+#   client = omophub.OMOPHub(api_key="oh_your_api_key")
+client = omophub.OMOPHub()
 
 
 def get_ancestors() -> None: