oehrpy 0.1.1__tar.gz → 0.2.0__tar.gz

{oehrpy-0.1.1 → oehrpy-0.2.0}/CHANGELOG.md

@@ -1,6 +1,21 @@
 # CHANGELOG
 
 
+## v0.2.0 (2026-02-04)
+
+### Documentation
+
+- Add PRDs for composition lifecycle, audit, builders, and EHR management (#19)
+  ([#19](https://github.com/platzhersh/oehrpy/pull/19),
+  [`1542994`](https://github.com/platzhersh/oehrpy/commit/1542994dd9c5319b268041ab6f114d45377a3791))
+
+### Features
+
+- Add composition versioning and update operations (PRD-0002) (#20)
+  ([#20](https://github.com/platzhersh/oehrpy/pull/20),
+  [`eadb0c9`](https://github.com/platzhersh/oehrpy/commit/eadb0c9f7714aa4bbfb0e7fce3cbd8e6481a7ce9))
+
+
 ## v0.1.1 (2026-01-31)
 
 ### Bug Fixes

{oehrpy-0.1.1 → oehrpy-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: oehrpy
-Version: 0.1.1
+Version: 0.2.0
 Summary: A Python SDK for openEHR with type-safe Reference Model classes, template builders, and EHRBase client
 Project-URL: Homepage, https://github.com/platzhersh/oehrpy
 Project-URL: Documentation, https://github.com/platzhersh/oehrpy#readme

oehrpy-0.2.0/docs/prd/PRD-0002-composition-lifecycle.md

@@ -0,0 +1,135 @@
+# PRD-0002: Composition Lifecycle (Update & Versioning)
+
+**Version:** 1.0
+**Date:** 2026-01-31
+**Status:** Draft
+**Owner:** Open CIS Project
+**Priority:** P0 (Critical)
+
+---
+
+## Executive Summary
+
+Extend the oehrpy SDK to support the full composition lifecycle: updating/amending existing compositions and retrieving prior versions. These capabilities are fundamental to clinical data management — without them, records are write-once and audit history is inaccessible.
+
+This PRD covers two tightly coupled gaps identified in the oehrpy gap analysis:
+1. **Composition Update/Amendment** — `PUT /ehr/{ehr_id}/composition/{versioned_object_uid}`
+2. **Composition Versioning** — retrieving compositions at a point in time, listing version history, and accessing the versioned composition container
+
+---
+
+## Problem Statement
+
+oehrpy currently supports creating and deleting compositions but provides no way to:
+
+1. **Amend a composition** — Clinicians routinely correct errors, add addenda, or update status fields on existing records. The openEHR model supports this through versioning: each update creates a new version while preserving the original.
+
+2. **Retrieve previous versions** — Regulatory requirements (e.g., HIPAA, GDPR health data provisions) mandate access to the full history of changes to a clinical record. Without version retrieval, there is no way to answer "what did this record say last Tuesday?"
+
+3. **List version history** — Governance workflows need to enumerate all versions of a composition to display audit trails, compare changes, or roll back.
+
+---
+
+## Requirements
+
+### Functional Requirements
+
+#### FR-1: Update Composition
+
+| Field | Detail |
+|---|---|
+| Endpoint | `PUT /ehr/{ehr_id}/composition/{versioned_object_uid}` |
+| SDK method | `EHRBaseClient.update_composition(ehr_id, versioned_object_uid, preceding_version_uid, template_id, composition, format)` |
+| Input | EHR ID, `versioned_object_uid` (the composition's UUID, used in the request path), `preceding_version_uid` (the full version string, e.g. `uuid::domain::1`, sent in the `If-Match` header per RFC 7232), template ID, updated composition body, format (CANONICAL / FLAT / STRUCTURED) |
+| Output | Updated composition with new version UID |
+| Headers | `If-Match: {preceding_version_uid}` for optimistic concurrency |
+
+- Must support all three composition formats (CANONICAL, FLAT, STRUCTURED)
+- Must return the new version UID on success
+- Must raise a clear error on version conflict (HTTP 412 Precondition Failed, per RFC 7232 `If-Match` semantics)
+- Must raise a clear error if the composition has been deleted (HTTP 404)
+
+#### FR-2: Get Composition at Version
+
+| Field | Detail |
+|---|---|
+| Endpoint | `GET /ehr/{ehr_id}/composition/{versioned_object_uid}` with `version_at_time` parameter |
+| SDK method | `EHRBaseClient.get_composition_at_time(ehr_id, versioned_object_uid, version_at_time, format)` |
+| Input | EHR ID, `versioned_object_uid` (the composition's UUID), ISO 8601 timestamp, optional format |
+| Output | Composition as it existed at the given point in time |
+
+#### FR-3: Get Versioned Composition
+
+| Field | Detail |
+|---|---|
+| Endpoint | `GET /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}` |
+| SDK method | `EHRBaseClient.get_versioned_composition(ehr_id, versioned_object_uid)` |
+| Output | Versioned composition metadata (UID, owner ID, time created) |
+
+#### FR-4: Get Version by Version UID
+
+| Field | Detail |
+|---|---|
+| Endpoint | `GET /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version/{version_uid}` |
+| SDK method | `EHRBaseClient.get_composition_version(ehr_id, versioned_object_uid, version_uid)` |
+| Output | Specific version of the composition with full audit metadata |
+
+#### FR-5: List Composition Versions
+
+| Field | Detail |
+|---|---|
+| Endpoint | `GET /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version` |
+| SDK method | `EHRBaseClient.list_composition_versions(ehr_id, versioned_object_uid)` |
+| Output | List of version descriptors (version UID, commit audit, lifecycle state) |
+
+### Non-Functional Requirements
+
+- **NFR-1**: All new methods must be async (consistent with existing client)
+- **NFR-2**: Optimistic concurrency via `If-Match` must be handled transparently — the caller passes the preceding version UID and the SDK sets the header
+- **NFR-3**: Version conflict errors (HTTP 412 Precondition Failed) must raise a typed `PreconditionFailedError` exception
+- **NFR-4**: Full test coverage with both unit tests (mocked HTTP) and integration tests against EHRBase
+
+---
+
+## API Design
+
+```python
+# Update a composition
+new_version_uid = await client.update_composition(
+    ehr_id=ehr_id,
+    versioned_object_uid=versioned_object_uid,
+    preceding_version_uid=preceding_version_uid,
+    template_id="vital_signs",
+    composition=updated_flat_data,
+    format=CompositionFormat.FLAT,
+)
+
+# Get composition as it was at a specific time
+old_composition = await client.get_composition_at_time(
+    ehr_id=ehr_id,
+    versioned_object_uid=versioned_object_uid,
+    version_at_time="2026-01-15T10:00:00Z",
+)
+
+# List all versions
+versions = await client.list_composition_versions(
+    ehr_id=ehr_id,
+    versioned_object_uid=versioned_object_uid,
+)
+```
+
+---
+
+## Testing Strategy
+
+- **Unit tests**: Mock HTTP responses for each endpoint, verify request construction (headers, URL, body)
+- **Integration tests**: Create → Update → Retrieve version history against EHRBase 2.0
+- **Edge cases**: Version conflict (concurrent update), deleted composition, invalid timestamp format
+
+---
+
+## Success Criteria
+
+1. All five SDK methods implemented and passing integration tests against EHRBase 2.0
+2. Version conflict handling works correctly with `If-Match` / HTTP 412
+3. Round-trip test: create → update → retrieve both versions → verify content differs

oehrpy-0.2.0/docs/prd/PRD-0003-audit-and-contributions.md

@@ -0,0 +1,102 @@
+# PRD-0003: Audit & Contributions
+
+**Version:** 1.0
+**Date:** 2026-01-31
+**Status:** Draft
+**Owner:** Open CIS Project
+**Priority:** P1 (High)
+**Depends on:** PRD-0002 (Composition Lifecycle)
+
+---
+
+## Executive Summary
+
+Add support for openEHR Contributions — atomic changesets that group one or more composition changes with audit metadata. Contributions provide the answer to "who changed what, when, and why" and are required for regulatory compliance in any production clinical system.
+
+---
+
+## Problem Statement
+
+Every composition change in openEHR is wrapped in a Contribution, but oehrpy currently ignores this layer entirely. This means:
+
+1. **No audit trail** — There is no way to retrieve the provenance of a change (committer identity, timestamp, change description)
+2. **No atomic multi-composition commits** — Clinical workflows sometimes require multiple compositions to be committed as a single logical unit (e.g., a medication order and a corresponding encounter note). Without Contributions, each composition is an independent request with no transactional grouping.
+3. **Regulatory gaps** — Healthcare regulations require demonstrable audit trails. Without Contribution access, an oehrpy-based system cannot satisfy audit requirements.
+
+---
+
+## Requirements
+
+### Functional Requirements
+
+#### FR-1: Create Contribution
+
+| Field | Detail |
+|---|---|
+| Endpoint | `POST /ehr/{ehr_id}/contribution` |
+| SDK method | `EHRBaseClient.create_contribution(ehr_id, contribution)` |
+| Input | EHR ID, Contribution object containing: list of version changes (each with composition + change type), audit details (committer, description, time) |
+| Output | Contribution UID |
+
+Change types per the openEHR spec:
+- `creation` — new composition
+- `amendment` — update to existing composition
+- `modification` — structural change
+- `deleted` — logical deletion
+
+#### FR-2: Get Contribution
+
+| Field | Detail |
+|---|---|
+| Endpoint | `GET /ehr/{ehr_id}/contribution/{contribution_uid}` |
+| SDK method | `EHRBaseClient.get_contribution(ehr_id, contribution_uid)` |
+| Output | Contribution object with audit metadata and list of version references |
+
+### Model Requirements
+
+#### MR-1: Contribution Model
+
+A `Contribution` Pydantic model (or use the existing RM `CONTRIBUTION` class) with:
+- `uid`: Contribution identifier
+- `versions`: List of object references to the versioned objects included
+- `audit`: `AUDIT_DETAILS` with committer, time_committed, change_type, description
+
+#### MR-2: Contribution Builder
+
+A helper to construct Contribution request bodies:
+
+```python
+contribution = (
+    ContributionBuilder(ehr_id=ehr_id)
+    .add_creation(template_id="vital_signs", composition=vitals_data)
+    .add_amendment(uid=existing_uid, template_id="vital_signs", composition=updated_data)
+    .set_audit(committer="Dr. Smith", description="Routine vitals and correction")
+    .build()
+)
+
+uid = await client.create_contribution(ehr_id, contribution)
+```
+
+### Non-Functional Requirements
+
+- **NFR-1**: Async methods consistent with existing client
+- **NFR-2**: Audit details must support both minimal (auto-filled by server) and explicit (caller-provided) modes
+- **NFR-3**: Full test coverage including multi-composition atomic commits
+
+---
+
+## Testing Strategy
+
+- **Unit tests**: Mock HTTP, verify Contribution request body structure matches openEHR spec
+- **Integration tests**:
+  - Create a contribution with a single composition creation, retrieve it, verify audit fields
+  - Create a contribution with multiple operations (create + amend), verify atomicity
+  - Verify contribution UID appears in composition version metadata
+
+---
+
+## Success Criteria
+
+1. `create_contribution()` and `get_contribution()` implemented and passing integration tests
+2. `ContributionBuilder` provides a fluent API for multi-operation contributions
+3. Audit metadata (committer, timestamp, description) round-trips correctly

oehrpy-0.2.0/docs/prd/PRD-0004-dynamic-composition-builders.md

@@ -0,0 +1,107 @@
+# PRD-0004: Dynamic Composition Builders
+
+**Version:** 1.0
+**Date:** 2026-01-31
+**Status:** Draft
+**Owner:** Open CIS Project
+**Priority:** P1 (High)
+
+---
+
+## Executive Summary
+
+Unlock oehrpy's existing OPT parser and template generator so that developers can generate type-safe composition builders from any OPT file — at build time or at runtime. Ship a small set of pre-built builders for common clinical document types alongside the generic capability.
+
+---
+
+## Problem Statement
+
+oehrpy ships a single hand-crafted `VitalSignsBuilder`. The OPT parser (`opt_parser.py`) and builder generator (`builder_generator.py`) exist in the codebase and can already produce builder classes from OPT files, but:
+
+1. **The capability is undiscoverable** — There is no public API or CLI command to generate a builder from an OPT file. The only example is a script in `examples/`.
+2. **No runtime generation** — Developers must run a script, capture the output, and paste it into their project. There is no way to load a template and get a builder object at runtime.
+3. **Only one pre-built builder** — `VitalSignsBuilder` covers one template. Common clinical document types (medications, problem lists, lab results) have no builder support.
+4. **No validation against template constraints** — Generated builders set FLAT paths but do not enforce cardinality, mandatory fields, or terminology bindings from the OPT.
+
+---
+
+## Requirements
+
+### Functional Requirements
+
+#### FR-1: Runtime Builder Factory
+
+```python
+from openehr_sdk.templates import CompositionBuilder
+
+# Load from a local OPT file
+builder = CompositionBuilder.from_opt("path/to/medication_order.opt")
+
+# Use the builder with FLAT format
+composition = (
+    builder
+    .set("medication/order:0/medication_item|value", "Amoxicillin")
+    .set("medication/order:0/dose|magnitude", 500)
+    .set("medication/order:0/dose|unit", "mg")
+    .build()
+)
+```
+
+- Parse the OPT at runtime and return a builder instance with template-aware path helpers
+- Builder must produce valid FLAT format output
+
+#### FR-2: CLI / Script Generation (improve existing)
+
+```bash
+# Generate a builder module from an OPT file
+python -m openehr_sdk.templates.generate path/to/template.opt --output my_builder.py
+```
+
+- Wrap the existing `builder_generator.py` in a proper CLI entry point
+- Generated code should be a self-contained Python module that can be imported
+
+#### FR-3: Pre-built Builders
+
+Ship builders for commonly used openEHR templates:
+
+| Builder | Template |
+|---|---|
+| `VitalSignsBuilder` | (already exists) |
+| `MedicationOrderBuilder` | Medication order / prescription |
+| `ProblemListBuilder` | Problem / diagnosis list |
+| `LabResultBuilder` | Laboratory result report |
+
+Pre-built builders should be generated from OPT files included in the repository under `templates/`.
+
+#### FR-4: Template Constraint Validation (optional / stretch)
+
+Builders optionally validate values against OPT constraints:
+- Required fields raise an error on `build()` if missing
+- Cardinality constraints (max occurrences) enforced on indexed paths
+- Terminology bindings validated for coded fields
+
+### Non-Functional Requirements
+
+- **NFR-1**: Runtime builder creation from an OPT file must complete in under 500ms for typical templates
+- **NFR-2**: Generated builder code must pass ruff and mypy checks
+- **NFR-3**: Pre-built builders must be importable from `openehr_sdk.templates.builders`
+
+---
+
+## Testing Strategy
+
+- **Unit tests**:
+  - `from_opt()` produces a builder with correct paths for the Vital Signs OPT (already in repo)
+  - CLI generation produces importable, lint-clean Python code
+  - Pre-built builders produce valid FLAT output
+- **Integration tests**: Compositions built with generated builders are accepted by EHRBase 2.0
+- **Round-trip**: Generate builder → build composition → upload → retrieve → verify content
+
+---
+
+## Success Criteria
+
+1. `CompositionBuilder.from_opt()` works for any valid OPT 1.4 file
+2. CLI entry point generates importable builder modules
+3. At least 3 pre-built builders ship alongside `VitalSignsBuilder`
+4. All generated compositions pass EHRBase validation in integration tests

oehrpy-0.2.0/docs/prd/PRD-0005-ehr-management-and-query-extensions.md

@@ -0,0 +1,180 @@
+# PRD-0005: EHR Management & Query Extensions
+
+**Version:** 1.0
+**Date:** 2026-01-31
+**Status:** Draft
+**Owner:** Open CIS Project
+**Priority:** P2 (Medium)
+
+---
+
+## Executive Summary
+
+Round out the oehrpy SDK's REST API coverage by adding three independent feature groups:
+
+1. **EHR Directory** — Folder-based organization of compositions within an EHR
+2. **EHR Status Updates** — Modify EHR metadata (subject link, modifiable flag, active/inactive)
+3. **Stored Queries** — Register, retrieve, and execute named AQL queries on the server
+
+These are medium-value, low-to-medium effort additions that complete the SDK's coverage of the openEHR REST API.
+
+---
+
+## Problem Statement
+
+After PRDs 0002–0004, three areas of the openEHR REST API remain uncovered:
+
+1. **No folder organization** — All compositions in an EHR exist as a flat list. Clinical systems typically organize records by episode, department, or encounter type using the EHR Directory (FOLDER structure). Without this, applications must implement their own organization layer outside of openEHR.
+
+2. **No EHR status management** — Once an EHR is created, its metadata cannot be modified. There is no way to link a subject after creation, mark an EHR as non-modifiable (locked), or deactivate it.
+
+3. **No stored query support** — Every AQL query must be sent in full on each request. Production systems benefit from registering commonly used queries once and executing them by name with parameters, reducing payload size and enabling server-side query optimization.
+
+---
+
+## Requirements
+
+### Feature Group 1: EHR Directory
+
+#### FR-1.1: Create / Update Directory
+
+| Field | Detail |
+|---|---|
+| Endpoint | `PUT /ehr/{ehr_id}/directory` |
+| SDK method | `EHRBaseClient.update_directory(ehr_id, directory, preceding_version_uid=None)` |
+| Input | EHR ID, FOLDER structure (name, folders, items), optional `preceding_version_uid` (the version string sent in the `If-Match` header per RFC 7232; required for updates, omitted on first creation) |
+| Output | Updated directory with new version UID |
+
+#### FR-1.2: Get Directory
+
+| Field | Detail |
+|---|---|
+| Endpoint | `GET /ehr/{ehr_id}/directory` |
+| SDK method | `EHRBaseClient.get_directory(ehr_id, version_at_time=None, path=None)` |
+| Input | EHR ID, optional timestamp, optional sub-path |
+| Output | FOLDER structure |
+
+#### FR-1.3: Delete Directory
+
+| Field | Detail |
+|---|---|
+| Endpoint | `DELETE /ehr/{ehr_id}/directory` |
+| SDK method | `EHRBaseClient.delete_directory(ehr_id, preceding_version_uid)` |
+| Input | EHR ID, preceding version UID |
+| Output | None (HTTP 204) |
+
+#### FR-1.4: Directory Builder
+
+Helper for constructing FOLDER hierarchies:
+
+```python
+directory = (
+    DirectoryBuilder()
+    .add_folder("episodes", items=[composition_ref_1])
+    .add_folder("encounters/2026-01", items=[composition_ref_2, composition_ref_3])
+    .build()
+)
+
+await client.update_directory(ehr_id, directory, preceding_version_uid=dir_version_uid)
+```
+
+### Feature Group 2: EHR Status Updates
+
+#### FR-2.1: Get EHR Status
+
+| Field | Detail |
+|---|---|
+| Endpoint | `GET /ehr/{ehr_id}/ehr_status` |
+| SDK method | `EHRBaseClient.get_ehr_status(ehr_id)` |
+| Output | EHR_STATUS object (subject, is_modifiable, is_queryable) |
+
+#### FR-2.2: Update EHR Status
+
+| Field | Detail |
+|---|---|
+| Endpoint | `PUT /ehr/{ehr_id}/ehr_status` |
+| SDK method | `EHRBaseClient.update_ehr_status(ehr_id, status, preceding_version_uid)` |
+| Input | EHR ID, updated EHR_STATUS, preceding version UID (If-Match) |
+| Output | Updated EHR_STATUS with new version UID |
+
+Common use cases:
+- Link a subject (patient) to an EHR after anonymous creation
+- Mark an EHR as non-modifiable (locked for legal hold)
+- Set `is_queryable` to false to exclude from AQL queries
+
+### Feature Group 3: Stored Queries
+
+#### FR-3.1: Register Query
+
+| Field | Detail |
+|---|---|
+| Endpoint | `PUT /definition/query/{qualified_query_name}/{version}` |
+| SDK method | `EHRBaseClient.register_query(name, version, aql, query_type="AQL")` |
+| Input | Qualified name (e.g., `org.example::vitals_latest`), version, AQL string |
+| Output | Query definition metadata |
+
+#### FR-3.2: Get Query Definition
+
+| Field | Detail |
+|---|---|
+| Endpoint | `GET /definition/query/{qualified_query_name}/{version}` |
+| SDK method | `EHRBaseClient.get_query(name, version=None)` |
+| Output | Stored query definition (name, version, AQL text, saved timestamp) |
+
+#### FR-3.3: List Stored Queries
+
+| Field | Detail |
+|---|---|
+| Endpoint | `GET /definition/query` |
+| SDK method | `EHRBaseClient.list_queries()` |
+| Output | List of registered query definitions |
+
+#### FR-3.4: Execute Stored Query
+
+| Field | Detail |
+|---|---|
+| Endpoint | `GET /query/{qualified_query_name}/{version}` |
+| SDK method | `EHRBaseClient.execute_stored_query(name, version=None, params=None, fetch=None, offset=None)` |
+| Input | Query name, optional version, optional parameters dict, optional pagination |
+| Output | AQL result set (same format as ad-hoc query execution) |
+
+```python
+# Register a reusable query
+await client.register_query(
+    name="org.example::latest_bp",
+    version="1.0.0",
+    aql="SELECT c FROM COMPOSITION c WHERE c/archetype_details/template_id/value = 'vital_signs' ORDER BY c/context/start_time DESC LIMIT 1",
+)
+
+# Execute by name with parameters
+result = await client.execute_stored_query(
+    name="org.example::latest_bp",
+    version="1.0.0",
+)
+```
+
+### Non-Functional Requirements
+
+- **NFR-1**: All methods async, consistent with existing client
+- **NFR-2**: Directory operations must use `If-Match` for optimistic concurrency (same pattern as PRD-0002)
+- **NFR-3**: Stored query names must follow the openEHR qualified name format (`{namespace}::{query-name}`)
+
+---
+
+## Testing Strategy
+
+- **Unit tests**: Mock HTTP for all endpoints, verify request/response mapping
+- **Integration tests**:
+  - Directory: Create directory → add compositions → retrieve by path → delete
+  - EHR Status: Create EHR → update status → verify changes persist
+  - Stored Queries: Register → list → execute → verify results match ad-hoc query
+- **Edge cases**: Directory version conflicts, updating locked EHR, executing non-existent stored query
+
+---
+
+## Success Criteria
+
+1. All three feature groups implemented with full unit test coverage
+2. Integration tests passing against EHRBase 2.0
+3. Directory builder provides a usable API for constructing folder hierarchies
+4. Stored queries round-trip correctly (register → execute → same results as ad-hoc)

{oehrpy-0.1.1 → oehrpy-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oehrpy"
-version = "0.1.1"
+version = "0.2.0"
 description = "A Python SDK for openEHR with type-safe Reference Model classes, template builders, and EHRBase client"
 readme = "README.md"
 requires-python = ">=3.10"

{oehrpy-0.1.1 → oehrpy-0.2.0}/src/openehr_sdk/client/__init__.py

@@ -9,13 +9,16 @@ from .ehrbase import (
     AuthenticationError,
     CompositionFormat,
     CompositionResponse,
+    CompositionVersionResponse,
     EHRBaseClient,
     EHRBaseConfig,
     EHRBaseError,
     EHRResponse,
     NotFoundError,
+    PreconditionFailedError,
     QueryResponse,
     ValidationError,
+    VersionedCompositionResponse,
 )
 
 __all__ = [
@@ -24,9 +27,12 @@ __all__ = [
     "EHRResponse",
     "CompositionResponse",
     "CompositionFormat",
+    "CompositionVersionResponse",
     "QueryResponse",
+    "VersionedCompositionResponse",
     "EHRBaseError",
     "AuthenticationError",
     "NotFoundError",
+    "PreconditionFailedError",
     "ValidationError",
 ]