[batool-fariha]

Pull Request

Description

Adds an offline, runnable example of validate_code() and validate_codeable_concept() from openmed/clinical/exporters/valueset.py, so new users can see how to check codes against a ValueSet without a terminology server. It uses a small invented ValueSet under urn:openmed:example:, so no real vocabulary content is involved.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement
• Test addition/improvement

Changes Made

• examples/valueset_validate_code.py (new, 100 lines): builds a synthetic ValueSet that includes routine, soon and immediate and then excludes immediate, and prints one JSON line per case:
  • a member (routine), a non-member (unlisted) and an excluded code (immediate) through validate_code();
  • the annotate, drop and downgrade policies of validate_codeable_concept() on a CodeableConcept with one member and one non-member coding.
• tests/unit/examples/test_valueset_validate_code_example.py (new): checks one JSON line per case, that the excluded code is reported as a non-member, what each policy does to the non-member coding, that only the invented urn:openmed:example: system is used, and that no network connection is opened.
• docs/cookbook.md: one row for the new script. tests/unit/test_docs_cookbook_links.py::test_cookbook_indexes_current_scripts_and_notebooks requires every top-level example to be listed, and it fails without this row.
• CHANGELOG.md: one entry under Unreleased.

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes (see the note below: the new tests and the cookbook link tests pass, but I did not run the whole suite)
• I have tested this change with different models/inputs (not applicable: no models are involved)

What I ran, and what I could not. I could not install the project's full development environment, so I did not run .venv/bin/python -m pytest tests/unit/examples/test_valueset_validate_code_example.py -q as written in the issue. Instead I loaded the real openmed/clinical/exporters/valueset.py (it only uses the standard library) in an isolated environment containing just pytest and ruff, and ran:

pytest tests/unit/examples/test_valueset_validate_code_example.py tests/unit/test_docs_cookbook_links.py -q
ruff check examples/valueset_validate_code.py tests/unit/examples/test_valueset_validate_code_example.py
ruff format --check examples/valueset_validate_code.py tests/unit/examples/test_valueset_validate_code_example.py

All 12 tests pass and both ruff commands are clean with the repository's configuration. Two negative controls fail as expected: removing the exclude clause from the ValueSet fails the excluded-code test, and changing the system to a real-looking URI fails the invented-system test. CI will run the full suite.

Documentation

• I have updated the documentation accordingly
• I have added docstrings to new functions/classes
• I have updated the CHANGELOG.md

Code Quality

• I ran make format, make lint, and make format-check (I ran ruff check and ruff format --check directly with the repository's configuration instead; see Testing)
• For Swift/OpenMedKit changes, I ran make format-swift and make lint-swift (not applicable)
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings

Dependencies

• I have not added any new dependencies
• OR I have added new dependencies and they are justified because: ____

Checklist

• I have read the contributing guide, Code of Conduct, and relevant policies
• My commits have clear, descriptive messages
• I have squashed/organized my commits appropriately

Related Issues

Closes #4657

Screenshots/Examples

Output of main() (one JSON line per case):

{"case": "member", "code": "routine", "message": "Code is a member of the supplied ValueSet.", "valid": true}
{"case": "non_member", "code": "unlisted", "message": "Code is not a member of the supplied ValueSet.", "valid": false}
{"case": "excluded", "code": "immediate", "message": "The code is explicitly excluded from the supplied ValueSet.", "valid": false}
{"annotated_codes": ["unlisted"], "case": "codeable_concept_annotate", "codes": ["soon", "unlisted"], "severities": ["error"], "valid": false}
{"annotated_codes": [], "case": "codeable_concept_drop", "codes": ["soon"], "severities": ["error"], "valid": false}
{"annotated_codes": ["unlisted"], "case": "codeable_concept_downgrade", "codes": ["soon", "unlisted"], "severities": ["warning"], "valid": false}

AI assistance

This change was written with Claude Code (Claude Sonnet 5.5). It is disclosed here rather than in a commit trailer, because the repository's commit-attribution check rejects co-author and generated-by footers. It was checked only as described under Testing, which includes the limits noted there.