Implement FHIR-to-OMOP concept resolution in v1.6.0, adding methods for single and batch resolution of FHIR codings, and CodeableConcept handling. Refactor shared response parsing in API requests to improve maintainability. Update README with usage examples and correct Python version requirement in CONTRIBUTING.md.

Author: alex-omophub

CHANGELOG.md

@@ -5,6 +5,28 @@ 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.6.0] - 2026-04-10
+
+### Added
+
+- **FHIR-to-OMOP Concept Resolver** (`client.fhir`): Translate FHIR coded values into OMOP standard concepts, CDM target tables, and optional Phoebe recommendations in a single API call.
+  - `resolve()`: Resolve a single FHIR `Coding` (system URI + code) or text-only input via semantic search fallback. Returns the standard concept, target CDM table, domain alignment check, and optional mapping quality signal.
+  - `resolve_batch()`: Batch-resolve up to 100 FHIR codings per request with inline per-item error reporting. Failed items do not fail the batch.
+  - `resolve_codeable_concept()`: Resolve a FHIR `CodeableConcept` with multiple codings. Automatically picks the best match per OHDSI vocabulary preference (SNOMED > RxNorm > LOINC > CVX > ICD-10). Falls back to the `text` field via semantic search when no coding resolves.
+- New TypedDict types for FHIR resolver: `FhirResolveResult`, `FhirResolution`, `FhirBatchResult`, `FhirBatchSummary`, `FhirCodeableConceptResult`, `ResolvedConcept`, `RecommendedConceptOutput`.
+- Both sync (`OMOPHub`) and async (`AsyncOMOPHub`) clients support FHIR resolver methods via `client.fhir.*`.
+
+### Changed
+
+- **Extracted shared response parsing** (`_request.py`): The duplicated JSON decode / error-handling / rate-limit-retry logic across `Request._parse_response`, `Request._parse_response_raw`, `AsyncRequest._parse_response`, and `AsyncRequest._parse_response_raw` (4 copies of ~50 lines each) is now a single `_parse_and_raise()` module-level function. All four methods delegate to it, eliminating the risk of divergence bugs.
+- **Fixed `paginate_async` signature** (`_pagination.py`): The type hint now correctly declares `Callable[[int, int], Awaitable[tuple[...]]]` instead of `Callable[[int, int], tuple[...]]`, and the runtime `hasattr(__await__)` duck-typing hack has been replaced with a clean `await`.
+- **`AsyncSearch.semantic_iter`** now delegates to `paginate_async` instead of manually reimplementing the pagination loop, matching the sync `semantic_iter` which already uses `paginate_sync`.
+
+### Fixed
+
+- Python prerequisite in CONTRIBUTING.md corrected from `3.9+` to `3.10+` (matching `pyproject.toml`).
+- `__all__` in `types/__init__.py` sorted per RUF022.
+
 ## [1.5.1] - 2026-04-08
 
 ### Fixed
@@ -117,7 +139,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.5.1...HEAD
+[Unreleased]: https://github.com/omopHub/omophub-python/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/omopHub/omophub-python/compare/v1.5.1...v1.6.0
 [1.5.1]: https://github.com/omopHub/omophub-python/compare/v1.5.0...v1.5.1
 [1.5.0]: https://github.com/omopHub/omophub-python/compare/v1.4.1...v1.5.0
 [1.4.1]: https://github.com/omopHub/omophub-python/compare/v1.4.0...v1.4.1

README.md

@@ -58,6 +58,46 @@ mappings = client.mappings.get_by_code("ICD10CM", "E11.9", target_vocabulary="SN
 ancestors = client.hierarchy.ancestors(201826, max_levels=3)
 ```
 
+## FHIR-to-OMOP Resolution
+
+Resolve FHIR coded values to OMOP standard concepts in one call:
+
+```python
+# Single FHIR Coding → OMOP concept + CDM target table
+result = client.fhir.resolve(
+    system="http://snomed.info/sct",
+    code="44054006",
+    resource_type="Condition",
+)
+print(result["resolution"]["target_table"])  # "condition_occurrence"
+print(result["resolution"]["mapping_type"])  # "direct"
+
+# ICD-10-CM → traverses "Maps to" automatically
+result = client.fhir.resolve(
+    system="http://hl7.org/fhir/sid/icd-10-cm",
+    code="E11.9",
+)
+print(result["resolution"]["standard_concept"]["vocabulary_id"])  # "SNOMED"
+
+# Batch resolve up to 100 codings
+batch = client.fhir.resolve_batch([
+    {"system": "http://snomed.info/sct", "code": "44054006"},
+    {"system": "http://loinc.org", "code": "2339-0"},
+    {"system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "197696"},
+])
+print(f"Resolved {batch['summary']['resolved']}/{batch['summary']['total']}")
+
+# CodeableConcept with vocabulary preference (SNOMED wins over ICD-10)
+result = client.fhir.resolve_codeable_concept(
+    coding=[
+        {"system": "http://snomed.info/sct", "code": "44054006"},
+        {"system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "E11.9"},
+    ],
+    resource_type="Condition",
+)
+print(result["best_match"]["resolution"]["source_concept"]["vocabulary_id"])  # "SNOMED"
+```
+
 ## Semantic Search
 
 Use natural language queries to find concepts using neural embeddings:
@@ -200,6 +240,7 @@ suggestions = client.concepts.suggest("diab", vocabulary_ids=["SNOMED"], page_si
 | `mappings` | Cross-vocabulary mappings | `get()`, `map()` |
 | `vocabularies` | Vocabulary metadata | `list()`, `get()`, `stats()` |
 | `domains` | Domain information | `list()`, `get()`, `concepts()` |
+| `fhir` | FHIR-to-OMOP resolution | `resolve()`, `resolve_batch()`, `resolve_codeable_concept()` |
 
 ## Configuration