Examples update

[alex-omophub]

Summary by cubic

Clarifies Mappings API usage across README, examples, and types, including correct ICD-10 → SNOMED direction, get() vs get_iter pagination, and which fields each endpoint returns.

• New Features
  • README and types: switched ICD-10 example to concepts.get_by_code() + mappings.get(), added mappings.get_iter to the API table, explained mapping direction, and documented mappings.get vs mappings.map field differences in the Mapping type (resolve target codes via concepts.get).
  • Examples: clarified get() (single page, no pagination info) vs get_iter (walks all pages), showed mapping to ICD10CM via relationship_ids=["Mapped from"], resolving target codes with concepts.get, handling Maps to value, filtering deprecated rows with include_invalid=False, and improved error handling/output formatting.

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

1 issue found across 2 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="examples/map_between_vocabularies.py">

<violation number="1" location="examples/map_between_vocabularies.py:25">
P3: The mapping row does expose vocabulary/code fields, so this comment tells users to make an unnecessary concept lookup and contradicts the SDK schema. Updating the comment to describe those optional fields would keep the example accurate.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The mapping row does expose vocabulary/code fields, so this comment tells users to make an unnecessary concept lookup and contradicts the SDK schema. Updating the comment to describe those optional fields would keep the example accurate.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At examples/map_between_vocabularies.py, line 25:

<comment>The mapping row does expose vocabulary/code fields, so this comment tells users to make an unnecessary concept lookup and contradicts the SDK schema. Updating the comment to describe those optional fields would keep the example accurate.</comment>

<file context>
@@ -5,34 +5,147 @@
+
+        print(f"Mappings for concept {concept_id} (this page: {len(mappings)}):")
+        for m in mappings[:10]:
+            # A mapping row carries only these fields. Vocabulary id and
+            # concept code are NOT part of it -- fetch the target concept if
+            # you need them.
</file context>

Suggested change

	# A mapping row carries only these fields. Vocabulary id and
	# concept code are NOT part of it -- fetch the target concept if
	# you need them.
	# Mapping rows include the target concept ID/name and may also include
	# target vocabulary/code fields when returned by the API.

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

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="src/omophub/types/mapping.py">

<violation number="1" location="src/omophub/types/mapping.py:40">
P3: The new docstring lists a top-level ``confidence`` field among the fields that ``mappings.get`` returns, but the ``Mapping`` type defines no such field — confidence only exists as ``quality.confidence_score`` and, per the note two lines below, is populated only when ``include_mapping_quality=True`` is requested. Listing bare ``confidence`` as a guaranteed return field is internally inconsistent with both the type and the note, and will lead readers to write ``m["confidence"]`` (a KeyError / missing type member). Either drop ``confidence`` from the list, name it ``quality.confidence_score`` and qualify it with the ``include_mapping_quality=True`` condition, or add the missing top-level field to the ``Mapping`` type. The same claim appears in the comment added to examples/map_between_vocabularies.py in this PR, so both should be aligned if corrected.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The new docstring lists a top-level confidence field among the fields that mappings.get returns, but the Mapping type defines no such field — confidence only exists as quality.confidence_score and, per the note two lines below, is populated only when include_mapping_quality=True is requested. Listing bare confidence as a guaranteed return field is internally inconsistent with both the type and the note, and will lead readers to write m["confidence"] (a KeyError / missing type member). Either drop confidence from the list, name it quality.confidence_score and qualify it with the include_mapping_quality=True condition, or add the missing top-level field to the Mapping type. The same claim appears in the comment added to examples/map_between_vocabularies.py in this PR, so both should be aligned if corrected.

Prompt for AI agents

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

<comment>The new docstring lists a top-level ``confidence`` field among the fields that ``mappings.get`` returns, but the ``Mapping`` type defines no such field — confidence only exists as ``quality.confidence_score`` and, per the note two lines below, is populated only when ``include_mapping_quality=True`` is requested. Listing bare ``confidence`` as a guaranteed return field is internally inconsistent with both the type and the note, and will lead readers to write ``m["confidence"]`` (a KeyError / missing type member). Either drop ``confidence`` from the list, name it ``quality.confidence_score`` and qualify it with the ``include_mapping_quality=True`` condition, or add the missing top-level field to the ``Mapping`` type. The same claim appears in the comment added to examples/map_between_vocabularies.py in this PR, so both should be aligned if corrected.</comment>

<file context>
@@ -31,6 +31,19 @@ class MappingContext(TypedDict, total=False):
+
+    - ``mappings.get`` (``GET /concepts/{id}/mappings``) returns exactly
+      ``source_concept_id``, ``source_concept_name``, ``target_concept_id``,
+      ``target_concept_name``, ``relationship_id`` and ``confidence``.
+      Supplying ``target_vocabulary`` does NOT add the vocabulary/code fields
+      -- measured against production 2026-08-12. Resolve a target's vocabulary
</file context>

Suggested change

	``target_concept_name``, ``relationship_id`` and ``confidence``.
	``target_concept_name``, ``relationship_id``, and ``quality.confidence_score``
	(the last only when ``include_mapping_quality=True`` is requested).