pylantir 0.2.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

{pylantir-0.2.3.dist-info → pylantir-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pylantir
-Version: 0.2.3
+Version: 0.3.0
 Summary: Python - DICOM Modality WorkList with Optional API
 Author-email: Milton Camacho <miltoncamachoicc@gmail.com>
 Requires-Python: >=3.11.1
@@ -21,6 +21,8 @@ Requires-Dist: uuid
 Requires-Dist: coloredlogs
 Requires-Dist: python-dotenv
 Requires-Dist: pandas
+Requires-Dist: requests
+Requires-Dist: pytz
 Requires-Dist: fastapi>=0.104.1 ; extra == "api"
 Requires-Dist: uvicorn[standard]>=0.24.0 ; extra == "api"
 Requires-Dist: passlib[bcrypt]==1.7.4 ; extra == "api"
@@ -46,6 +48,7 @@ Requires-Dist: pytest-runner ; extra == "test"
 Requires-Dist: pytest==7.3.1 ; extra == "test"
 Requires-Dist: pytest-github-actions-annotate-failures ; extra == "test"
 Requires-Dist: shellcheck-py==0.9.0.2 ; extra == "test"
+Requires-Dist: responses>=0.23.0 ; extra == "test"
 Project-URL: Documentation, https://github.com/miltoncamacho/pylantir/tree/main#readme
 Project-URL: Source, https://github.com/miltoncamacho/pylantir
 Project-URL: Tracker, https://github.com/miltoncamacho/pylantir/issues
@@ -197,14 +200,16 @@ usage: pylantir [-h] [--AEtitle AETITLE] [--ip IP] [--port PORT] [--pylantir_con
 - **--ip IP**: IP/host address for the server
 - **--port PORT**: Port for the server
 - **--pylantir_config PYLANTIR_CONFIG**: Path to the configuration JSON file containing pylantir configs:
+  - **data_sources**: Array of data source configurations (recommended new format)
+    - Each source has: `name`, `type`, `enabled`, `sync_interval`, `operation_interval`, `config`, `field_mapping`
+  - **redcap2wl**: Legacy field mapping (deprecated, auto-converts to data_sources)
   - **allowed_aet**: List of allowed AE titles e.g. `["MRI_SCANNER", "MRI_SCANNER_2"]`
-  - **site**: Site ID:string
+  - **site**: Site ID (legacy format, deprecated)
   - **protocol**: `{"site": "protocol_name", "mapping": "HIS/RIS mapping"}`
-  - **redcap2wl**: Dictionary of REDCap fields to worklist fields mapping e.g., `{"redcap_field": "worklist_field"}`
   - **db_path**: Path to main worklist database e.g., `"/path/to/worklist.db"`
   - **users_db_path**: Optional path to users authentication database e.g., `"/path/to/users.db"`
-  - **db_update_interval**: How often to reload the database e
-  - **operation_interval**: What is the time range in a day in which the database will be updated e.g., `{"start_time":[hours,minutes],"end_time":[hours,minutes]}`
+  - **db_update_interval**: Legacy sync interval (deprecated, use sync_interval in data_sources)
+  - **operation_interval**: Legacy operation window (deprecated, use operation_interval in data_sources)
 - **--mpps_action {create,set}**: Action to perform for MPPS either create or set
 - **--mpps_status {COMPLETED,DISCONTINUED}**: Status to set for MPPS either COMPLETED or DISCONTINUED
 - **--callingAEtitle CALLINGAETITLE**: Calling AE Title for MPPS, it helps when the MWL is limited to only accept certain AE titles
@@ -213,40 +218,317 @@ usage: pylantir [-h] [--AEtitle AETITLE] [--ip IP] [--port PORT] [--pylantir_con
 
 ## Configuration JSON file
 
-As a default pylantir will try to read a JSON structured file with the following structure:
+Pylantir supports a modular data sources configuration that allows you to connect to multiple data sources simultaneously.
+
+### New Data Sources Format (Recommended)
+
+The new configuration format uses a `data_sources` array to define one or more data sources:
 
 ```json
 {
   "db_path": "/path/to/worklist.db",
   "users_db_path": "/path/to/users.db",
   "db_echo": "False",
-  "db_update_interval": 60,
-  "operation_interval": {"start_time": [0,0],"end_time": [23,59]},
   "allowed_aet": [],
+  "data_sources": [
+    {
+      "name": "main_redcap",
+      "type": "redcap",
+      "enabled": true,
+      "sync_interval": 60,
+      "operation_interval": {
+        "start_time": [0, 0],
+        "end_time": [23, 59]
+      },
+      "config": {
+        "site_id": "792",
+        "protocol": "BRAIN_MRI_3T"
+      },
+      "field_mapping": {
+        "study_id": "study_id",
+        "instrument": "redcap_repeat_instrument",
+        "session_id": "mri_instance",
+        "family_id": "family_id",
+        "youth_dob_y": "youth_dob_y",
+        "t1_date": "t1_date",
+        "demo_sex": "demo_sex",
+        "scheduled_date": "mri_date",
+        "scheduled_time": "mri_time",
+        "mri_wt_lbs": "patient_weight_lb",
+        "referring_physician": "referring_physician_name",
+        "performing_physician": "performing_physician",
+        "station_name": "station_name",
+        "status": "performed_procedure_step_status"
+      }
+    }
+  ],
+  "protocol": {
+    "792": "BRAIN_MRI_3T",
+    "mapping": "GEHC"
+  }
+}
+```
+
+**Data Source Configuration Fields:**
+
+- **`name`**: Unique identifier for this data source (used in logs and database tracking)
+- **`type`**: Data source type (currently supports `"redcap"`; extensible for future sources)
+- **`enabled`**: Boolean to enable/disable this source without removing its configuration
+- **`sync_interval`**: How often to sync data (in seconds)
+- **`operation_interval`**: Time window when sync should occur (24-hour format)
+  - `start_time`: `[hours, minutes]` - Start of operation window
+  - `end_time`: `[hours, minutes]` - End of operation window
+- **`config`**: Source-specific configuration
+  - For REDCap: `site_id`, `protocol`, and optional API credentials
+- **`field_mapping`**: Maps source fields to DICOM worklist fields
+- **`window_mode`** (Calpendo optional): `rolling` (default) or `daily`
+- **`daily_window`** (Calpendo optional): `{"start_time": [h, m], "end_time": [h, m]}`
+
+### Multiple Data Sources Example
+
+You can configure multiple data sources to sync simultaneously:
+
+```json
+{
+  "db_path": "/path/to/worklist.db",
+  "data_sources": [
+    {
+      "name": "site_792_redcap",
+      "type": "redcap",
+      "enabled": true,
+      "sync_interval": 60,
+      "config": {
+        "site_id": "792",
+        "protocol": "BRAIN_MRI_3T"
+      },
+      "field_mapping": { "study_id": "study_id" }
+    },
+    {
+      "name": "site_793_redcap",
+      "type": "redcap",
+      "enabled": true,
+      "sync_interval": 120,
+      "config": {
+        "site_id": "793",
+        "protocol": "CARDIAC_MRI"
+      },
+      "field_mapping": { "patient_id": "patient_id" }
+    }
+  ]
+}
+```
+
+## Calpendo Data Source Integration
+
+Pylantir supports integration with Calpendo booking systems to automatically sync MRI/EEG scanner bookings into the DICOM worklist. This allows scanner operators to see scheduled bookings directly on their imaging equipment.
+
+### Prerequisites
+
+Set up environment variables for Calpendo authentication:
+
+```bash
+export CALPENDO_USERNAME=<your_calpendo_username>
+export CALPENDO_PASSWORD=<your_calpendo_password>
+```
+
+### Minimal Configuration
+
+```json
+{
+  "db_path": "/path/to/worklist.db",
+  "data_sources": [
+    {
+      "name": "calpendo_mri",
+      "type": "calpendo",
+      "enabled": true,
+      "sync_interval": 60,
+      "config": {
+        "base_url": "https://your-institution.calpendo.com",
+        "resources": ["3T Diagnostic", "EEG Lab"]
+      },
+      "field_mapping": {
+        "patient_id": {
+          "source_field": "title",
+          "_extract": {
+            "pattern": "^([A-Z0-9]+)_.*",
+            "group": 1
+          }
+        },
+        "patient_name": {
+          "source_field": "title",
+          "_extract": {
+            "pattern": "^[A-Z0-9]+_(.+)$",
+            "group": 1
+          }
+        },
+        "study_description": {
+          "source_field": "properties.project.formattedName",
+          "_extract": {
+            "pattern": "^([^(]+)",
+            "group": 1
+          }
+        },
+        "accession_number": "id"
+      }
+    }
+  ]
+}
+```
+
+### Full Configuration with All Options
+
+```json
+{
+  "name": "calpendo_scanners",
+  "type": "calpendo",
+  "enabled": true,
+  "sync_interval": 60,
+  "config": {
+    "base_url": "https://your-institution.calpendo.com",
+    "resources": ["3T Diagnostic", "EEG Lab", "Mock Scanner"],
+    "status_filter": "Approved",
+    "lookback_multiplier": 2,
+    "timezone": "America/Edmonton",
+    "resource_modality_mapping": {
+      "3T": "MR",
+      "EEG": "EEG",
+      "Mock": "OT"
+    }
+  },
+  "field_mapping": {
+    "patient_id": {
+      "source_field": "title",
+      "_extract": {
+        "pattern": "^([A-Z0-9]+)_.*",
+        "group": 1
+      }
+    },
+    "patient_name": {
+      "source_field": "title",
+      "_extract": {
+        "pattern": "^[A-Z0-9]+_(.+)$",
+        "group": 1
+      }
+    },
+    "study_description": {
+      "source_field": "properties.project.formattedName",
+      "_extract": {
+        "pattern": "^([^(]+)",
+        "group": 1
+      }
+    },
+    "accession_number": "id",
+    "study_instance_uid": "id"
+  }
+}
+```
+
+**Calpendo Configuration Fields:**
+
+- **`base_url`**: Calpendo server URL (e.g., `https://your-institution.calpendo.com`)
+- **`resources`**: Array of resource names to sync (e.g., scanner names)
+- **`status_filter`** (optional): Only sync bookings with this status (e.g., `"Approved"`)
+- **`lookback_multiplier`** (optional, default: 2): Rolling window multiplier for incremental sync
+- **`timezone`** (optional, default: `"America/Edmonton"`): Timezone for booking timestamps
+- **`resource_modality_mapping`** (optional): Map resource names to DICOM modality codes
+- **`field_mapping`** (at data source root): Maps Calpendo fields to worklist fields
+- **`window_mode`** (optional): `rolling` (default) or `daily`
+- **`daily_window`** (optional): `{"start_time": [h, m], "end_time": [h, m]}`
+  - Use **`_extract`** for regex-based field extraction:
+    - **`pattern`**: Regular expression pattern (use `\\` for escaping in JSON)
+    - **`group`**: Capture group number (0 = full match, 1+ = capture groups)
+
+### Regex Pattern Examples
+
+Common patterns for extracting information from Calpendo booking titles:
+
+```json
+{
+  "patient_id": {
+    "source_field": "title",
+    "_extract": {
+      "pattern": "^([A-Z0-9]+)_.*",
+      "group": 1
+    }
+  },
+  "patient_name": {
+    "source_field": "title",
+    "_extract": {
+      "pattern": "^[A-Z0-9]+_(.+)$",
+      "group": 1
+    }
+  },
+  "study_description": {
+    "source_field": "properties.project.formattedName",
+    "_extract": {
+      "pattern": "^([^(]+)",
+      "group": 1
+    }
+  }
+}
+```
+
+### Troubleshooting
+
+**Authentication Errors:**
+- Verify environment variables are set correctly
+- Check Calpendo username/password are valid
+- Ensure API access is enabled for your account
+
+**No Bookings Synced:**
+- Check `resources` list matches actual Calpendo resource names
+- Verify `status_filter` isn't too restrictive
+- Check booking dates are within the rolling window (current time ± lookback window)
+
+**Regex Extraction Failures:**
+- Test regex patterns with sample data before deployment
+- Check JSON escaping (use `\\` for backslashes)
+- Set logging to DEBUG to see extraction warnings
+
+### Workflow Notes
+
+- MPPS status updates are owned by N-CREATE/N-SET; sync operations do not overwrite existing `performed_procedure_step_status` values.
+
+For more details, see the [Calpendo plugin quickstart](specs/002-calpendo-plugin/quickstart.md).
+
+### Legacy Configuration Format (Deprecated)
+
+⚠️ **The legacy configuration format is deprecated but still supported for backward compatibility.**
+
+If you're using the old format, Pylantir will automatically convert it to the new format at runtime:
+
+```json
+{
+  "db_path": "/path/to/worklist.db",
+  "db_echo": "False",
+  "db_update_interval": 60,
+  "operation_interval": {"start_time": [0,0], "end_time": [23,59]},
   "site": "792",
   "redcap2wl": {
     "study_id": "study_id",
-    "instrument": "redcap_repeat_instrument",
-    "session_id" : "mri_instance",
-    "family_id": "family_id",
-    "youth_dob_y": "youth_dob_y",
-    "t1_date": "t1_date",
-    "demo_sex": "demo_sex",
-    "scheduled_date": "mri_date",
-    "scheduled_time": "mri_time",
-    "mri_wt_lbs": "patient_weight_lb",
-    "referring_physician": "referring_physician_name",
-    "performing_physician": "performing_physician",
-    "station_name": "station_name",
-    "status": "performed_procedure_step_status"
+    "demo_sex": "demo_sex"
   },
   "protocol": {
-    "792": "BRAIN_MRI_3T",
-    "mapping": "GEHC"
+    "792": "BRAIN_MRI_3T"
   }
 }
 ```
 
+When using the legacy format, you'll see a deprecation warning:
+```
+WARNING: Legacy configuration format detected.
+Consider migrating to 'data_sources' format for better flexibility.
+```
+
+**Migration Note**: To migrate from legacy to new format:
+1. Rename `redcap2wl` → `field_mapping`
+2. Move `site` → `config.site_id`
+3. Move `protocol[site]` → `config.protocol`
+4. Move `db_update_interval` → `sync_interval`
+5. Wrap everything in a `data_sources` array with `name`, `type`, and `enabled` fields
+
+See `config/mwl_config_multi_source_example.json` for a complete example.
+
 ### Memory Management (Optional)
 
 When you install the `monitoring` optional dependency (`pip install pylantir[monitoring]`), Pylantir gains enhanced memory monitoring capabilities during REDCap synchronization:

pylantir-0.3.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+pylantir/__init__.py,sha256=kl2Et644PvUIvziU4BTxiTD1W4_g7E0xBYCHgPE6RZc,363
+pylantir/api_server.py,sha256=NFrme9T6DSe9EAbW7LMZgqYD1wDJIm9NLfH79sdXTjo,23369
+pylantir/auth_db_setup.py,sha256=yfhF8Eo6AVSbqZcC6-W0SPPXC1mkL7Dp9b8UxkI4GVc,5911
+pylantir/auth_models.py,sha256=v_xg5-YD4S7oafl2SDTC_ExmcasROWdVHG1tqn_qE0A,2707
+pylantir/auth_utils.py,sha256=Gr6tBR_IZXY61xiadhsc7BpnCRYeFYkAtN5QJW_wE8Q,5761
+pylantir/db_concurrency.py,sha256=4tCiHW8cxcrPxDEzXEBzyUviiQiO-7B2skxSaC40t9M,6387
+pylantir/db_setup.py,sha256=C0AwZ3Pa-lE821SQ3DtLlAPb83def3y5AY8EBmmAHXM,3664
+pylantir/models.py,sha256=qv1pQa0sWWG-wMECof3GsTgpnzltkWqYjK5UiKAoT0Y,1907
+pylantir/mwl_server.py,sha256=GMJDcK0u_KM3oa6UqQ87NxMVye2pvG2cdkcI9k_iExg,10338
+pylantir/populate_db.py,sha256=PL70ZmdHA401_wTO7tBrlqMsviGcoR9fensJsXel6Ew,2306
+pylantir/redcap_to_db.py,sha256=buUl27-ACoCeuJkm8WadIb8Mta3CDCqrHGhNkRxLJBY,21437
+pylantir/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pylantir/cli/run.py,sha256=D_c6iKE273LpfRCvHfmfN-b3K0XjX-KpwWY5eV_PPdE,37435
+pylantir/config/calpendo_config_example.json,sha256=F8DXfq2CR6Dmfj35nVH-q0duIpvHsv7Tw1cfhW5q56k,1942
+pylantir/config/config_example_with_cors.json,sha256=4F6YCOYMIPOZVnEdrWw3txIPWUyA3hRBIRs-zS5h2Vk,2885
+pylantir/config/mwl_config.json,sha256=hz7n3Ii9R9sFvrgPERlbQMu0rLP-bpN5sTvRYuRD74k,1636
+pylantir/data_sources/__init__.py,sha256=g9ishvpYxbE8rQjJwHHoAaCRNDcwJ1w0SIYmn8WVvXs,2310
+pylantir/data_sources/base.py,sha256=eOc2jo7RxYnkEdAttPHJ2o4LI3t9NdT22NXsFN9OEOg,3600
+pylantir/data_sources/calpendo_plugin.py,sha256=tVPwFwK_38_tdgWjvh9LNmnjTaiygQqECD5jdjo0VVQ,27709
+pylantir/data_sources/redcap_plugin.py,sha256=BEw85cz8DhF8VqZIENQ8ZDF5IB1lg1UYB6BqEIzwqbk,12816
+pylantir-0.3.0.dist-info/entry_points.txt,sha256=vxaxvfGppLqRt9_4sqNDdP6b2jlgpcHIwP7UQfrM1T0,50
+pylantir-0.3.0.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
+pylantir-0.3.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pylantir-0.3.0.dist-info/METADATA,sha256=TdWd9E24hLgcCGNOuTLAy5htOfTAPwJzWd2LvXX3YoI,28213
+pylantir-0.3.0.dist-info/RECORD,,

pylantir-0.2.3.dist-info/RECORD

@@ -1,20 +0,0 @@
-pylantir/__init__.py,sha256=kl2Et644PvUIvziU4BTxiTD1W4_g7E0xBYCHgPE6RZc,363
-pylantir/api_server.py,sha256=PLhHv1fzDptg5ujP7MgvBC43bKyDmCIT-hxmM4yB5PI,23177
-pylantir/auth_db_setup.py,sha256=yfhF8Eo6AVSbqZcC6-W0SPPXC1mkL7Dp9b8UxkI4GVc,5911
-pylantir/auth_models.py,sha256=v_xg5-YD4S7oafl2SDTC_ExmcasROWdVHG1tqn_qE0A,2707
-pylantir/auth_utils.py,sha256=Gr6tBR_IZXY61xiadhsc7BpnCRYeFYkAtN5QJW_wE8Q,5761
-pylantir/db_concurrency.py,sha256=4tCiHW8cxcrPxDEzXEBzyUviiQiO-7B2skxSaC40t9M,6387
-pylantir/db_setup.py,sha256=ljL3u6RTj1W7JqAsi_iYvV0rRUtwRut66X4IDAMQmCQ,3572
-pylantir/models.py,sha256=bKgI0EN1VSYanPTOvEhEY2Zzqa0gDYLpVnE_KNQ6PEc,1780
-pylantir/mwl_server.py,sha256=GMJDcK0u_KM3oa6UqQ87NxMVye2pvG2cdkcI9k_iExg,10338
-pylantir/populate_db.py,sha256=KIbkVA-EAuTlDArXMFOHkjMmVfjlsTApj7S1wpUu1bM,2207
-pylantir/redcap_to_db.py,sha256=rzA9VZl2qG67Ff82lxKgpXFVVkrmxBlr7Fd5OZORrVU,19476
-pylantir/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pylantir/cli/run.py,sha256=4JI9cRwoKYGG53DDP32ZBfXlZp_5hl0C3A7FiM3JyJw,21885
-pylantir/config/config_example_with_cors.json,sha256=4F6YCOYMIPOZVnEdrWw3txIPWUyA3hRBIRs-zS5h2Vk,2885
-pylantir/config/mwl_config.json,sha256=I1nPzXofmw2JviS7hEOw01ExdL6pGdgH46rcKYu6ofo,1437
-pylantir-0.2.3.dist-info/entry_points.txt,sha256=vxaxvfGppLqRt9_4sqNDdP6b2jlgpcHIwP7UQfrM1T0,50
-pylantir-0.2.3.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
-pylantir-0.2.3.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pylantir-0.2.3.dist-info/METADATA,sha256=_QLhbm0N61fQGwKtlZHPONSlchoJGCm1Dgh4yIi0nVU,19888
-pylantir-0.2.3.dist-info/RECORD,,