Back merge

[alex-omophub]

Summary by cubic

Back-merge from develop introducing semantic and bulk search, plus improved rate-limit handling with Retry-After and jitter for more reliable requests. This also standardizes params across resources and updates docs, examples, and tests.

• New Features

  • Added search.semantic() and search.similar() for embedding-based and concept-similarity search.
  • Added search.bulk_basic() and search.bulk_semantic() to run many queries in one call.
  • Added hierarchy.get() to fetch ancestors and descendants together, with new filters.
  • Expanded types for semantic, similar, and bulk search responses.
  • CI and PyPI publish workflows added.

• Migration

  • Suggest/autocomplete: use vocabulary_ids and domain_ids; replace limit/max_suggestions with page_size; supports page and vocab_release.
  • Relationships: relationship_type -> relationship_ids; target_vocabulary -> vocabulary_ids; default page_size is 100; new include_reverse.
  • Hierarchy: filters now vocabulary_ids/domain_ids; standard_only replaced by include_invalid; new hierarchy.get(...) for combined view.
  • Mappings: target_vocabularies collapsed to target_vocabulary; paging/quality/context flags removed; use include_invalid and optional vocab_release.
  • Vocabularies/Domains: vocabularies.get() no longer accepts include options—use vocabularies.stats() and vocabularies.domains(); vocabularies.list() default page_size=20; domains.list() now only include_stats.

^{Written for commit 1915148. Summary will update on new commits.}

[codecov]

Codecov Report

❌ Patch coverage is 84.21053% with 105 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/omophub/resources/search.py	71.79%	28 Missing and 27 partials ⚠️
src/omophub/resources/relationships.py	40.00%	6 Missing and 6 partials ⚠️
src/omophub/resources/vocabularies.py	64.70%	4 Missing and 8 partials ⚠️
src/omophub/_http.py	74.19%	5 Missing and 3 partials ⚠️
src/omophub/resources/mappings.py	81.39%	4 Missing and 4 partials ⚠️
src/omophub/_request.py	88.46%	2 Missing and 4 partials ⚠️
src/omophub/_version.py	60.00%	2 Missing ⚠️
src/omophub/resources/domains.py	80.00%	0 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

5 issues found across 43 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="CHANGELOG.md">

<violation number="1" location="CHANGELOG.md:8">
P3: Add link definitions for the new `[1.5.1]` and `[1.5.0]` changelog sections so those headings resolve correctly.</violation>

<violation number="2" location="CHANGELOG.md:120">
P2: Update the `[Unreleased]` compare link to start from `v1.5.1` (latest release), not `v1.4.1`.</violation>
</file>

<file name="CONTRIBUTING.md">

<violation number="1" location="CONTRIBUTING.md:56">
P2: The documented Python prerequisite is too low for this project. Update it to match the actual supported version (`>=3.10`) to avoid setup failures for contributors using 3.9.</violation>
</file>

<file name="src/omophub/_request.py">

<violation number="1" location="src/omophub/_request.py:100">
P2: Substantial duplicate response/error-handling logic was added; extract shared parsing/error handling to a single helper to avoid divergence bugs.</violation>
</file>

<file name="src/omophub/resources/search.py">

<violation number="1" location="src/omophub/resources/search.py:673">
P2: `paginate_async` already exists in `_pagination.py` and is purpose-built for this. The sync counterpart `Search.semantic_iter` correctly delegates to `paginate_sync`, but this async version manually reimplements the same pagination loop. Use `paginate_async` for consistency and to avoid duplicating pagination logic.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Update the [Unreleased] compare link to start from v1.5.1 (latest release), not v1.4.1.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At CHANGELOG.md, line 120:

<comment>Update the `[Unreleased]` compare link to start from `v1.5.1` (latest release), not `v1.4.1`.</comment>

<file context>
@@ -27,5 +117,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - HTTP/2 support via httpx
 
-[Unreleased]: https://github.com/omopHub/omophub-python/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/omopHub/omophub-python/compare/v1.4.1...HEAD
+[1.4.1]: https://github.com/omopHub/omophub-python/compare/v1.4.0...v1.4.1
+[1.4.0]: https://github.com/omopHub/omophub-python/compare/v1.3.1...v1.4.0
</file context>

Suggested change

	[Unreleased]: https://github.com/omopHub/omophub-python/compare/v1.4.1...HEAD
	[Unreleased]: https://github.com/omopHub/omophub-python/compare/v1.5.1...HEAD

[cubic-dev-ai]

P2: The documented Python prerequisite is too low for this project. Update it to match the actual supported version (>=3.10) to avoid setup failures for contributors using 3.9.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At CONTRIBUTING.md, line 56:

<comment>The documented Python prerequisite is too low for this project. Update it to match the actual supported version (`>=3.10`) to avoid setup failures for contributors using 3.9.</comment>

<file context>
@@ -0,0 +1,160 @@
+
+### Prerequisites
+
+- Python 3.9+
+- pip
+
</file context>

[cubic-dev-ai]

P2: Substantial duplicate response/error-handling logic was added; extract shared parsing/error handling to a single helper to avoid divergence bugs.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/omophub/_request.py, line 100:

<comment>Substantial duplicate response/error-handling logic was added; extract shared parsing/error handling to a single helper to avoid divergence bugs.</comment>

<file context>
@@ -97,6 +97,62 @@ def _parse_response(
         response: APIResponse = data  # type: ignore[assignment]
         return response.get("data", data)
 
+    def _parse_response_raw(
+        self,
+        content: bytes,
</file context>

[cubic-dev-ai]

P2: paginate_async already exists in _pagination.py and is purpose-built for this. The sync counterpart Search.semantic_iter correctly delegates to paginate_sync, but this async version manually reimplements the same pagination loop. Use paginate_async for consistency and to avoid duplicating pagination logic.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/omophub/resources/search.py, line 673:

<comment>`paginate_async` already exists in `_pagination.py` and is purpose-built for this. The sync counterpart `Search.semantic_iter` correctly delegates to `paginate_sync`, but this async version manually reimplements the same pagination loop. Use `paginate_async` for consistency and to avoid duplicating pagination logic.</comment>

<file context>
@@ -297,49 +584,223 @@ async def advanced(
+        page_size: int = DEFAULT_PAGE_SIZE,
+    ) -> AsyncIterator[SemanticSearchResult]:
+        """Iterate through all semantic search results with auto-pagination."""
+        page = 1
+
+        while True:
</file context>

[cubic-dev-ai]

P3: Add link definitions for the new [1.5.1] and [1.5.0] changelog sections so those headings resolve correctly.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At CHANGELOG.md, line 8:

<comment>Add link definitions for the new `[1.5.1]` and `[1.5.0]` changelog sections so those headings resolve correctly.</comment>

<file context>
@@ -5,6 +5,96 @@ 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.5.1] - 2026-04-08
+
+### Fixed
</file context>