cascade-protocol 1.0.0__py3-none-any.whl

cascade_protocol/__init__.py

@@ -0,0 +1,179 @@
+"""
+cascade-protocol — Python SDK for the Cascade Protocol.
+
+A privacy-first, local-first standard for serializing personal health data
+as RDF/Turtle. Zero network calls. All processing is local.
+
+Quick start:
+    >>> from cascade_protocol import Medication, serialize, validate, Pod
+    >>>
+    >>> med = Medication(
+    ...     id="urn:uuid:med0-0001-aaaa-bbbb-ccccddddeeee",
+    ...     medication_name="Metoprolol Succinate",
+    ...     is_active=True,
+    ...     dose="25mg",
+    ...     data_provenance="ClinicalGenerated",
+    ...     schema_version="1.3",
+    ... )
+    >>> turtle = serialize(med)
+    >>> result = validate(turtle)
+    >>> pod = Pod.open("./my-pod")
+    >>> meds = pod.query("medications")
+    >>> df = meds.to_dataframe()
+
+See: https://cascadeprotocol.org/docs
+"""
+
+from cascade_protocol.models import (
+    # Base
+    CascadeRecord,
+    # Record types
+    Medication,
+    Condition,
+    Allergy,
+    LabResult,
+    VitalSign,
+    Immunization,
+    Procedure,
+    FamilyHistory,
+    Coverage,
+    PatientProfile,
+    EmergencyContact,
+    Address,
+    PharmacyInfo,
+    ActivitySnapshot,
+    SleepSnapshot,
+    HealthProfile,
+    # Type aliases
+    ProvenanceType,
+    ProvenanceClass,
+    ConditionStatus,
+    AllergySeverity,
+    AllergyCategory,
+    LabInterpretation,
+    MedicationClinicalIntent,
+    CourseOfTherapyType,
+    PrescriptionCategory,
+    SourceFhirResourceType,
+    VitalType,
+    VitalInterpretation,
+    ImmunizationStatus,
+    PlanType,
+    CoverageType,
+    SubscriberRelationship,
+    BiologicalSex,
+    AgeGroup,
+    BloodType,
+    ProcedureStatus,
+)
+from cascade_protocol.serializer.turtle_serializer import (
+    serialize,
+    serialize_from_dict,
+    serialize_medication,
+    serialize_condition,
+    serialize_allergy,
+    serialize_lab_result,
+    serialize_vital_sign,
+    serialize_immunization,
+    serialize_procedure,
+    serialize_family_history,
+    serialize_coverage,
+    serialize_patient_profile,
+    serialize_activity_snapshot,
+    serialize_sleep_snapshot,
+)
+from cascade_protocol.deserializer.turtle_parser import parse, parse_one
+from cascade_protocol.validator.validator import (
+    validate,
+    validate_dict,
+    ValidationResult,
+    ValidationError,
+)
+from cascade_protocol.pod.pod import Pod, RecordSet
+from cascade_protocol.vocabularies.namespaces import (
+    NAMESPACES,
+    TYPE_MAPPING,
+    TYPE_TO_MAPPING_KEY,
+    PROPERTY_PREDICATES,
+    CURRENT_SCHEMA_VERSION,
+)
+
+__version__ = "1.0.0"
+__author__ = "Cascade Agentic Labs"
+__license__ = "Apache-2.0"
+
+__all__ = [
+    # Version
+    "__version__",
+    # Models
+    "CascadeRecord",
+    "Medication",
+    "Condition",
+    "Allergy",
+    "LabResult",
+    "VitalSign",
+    "Immunization",
+    "Procedure",
+    "FamilyHistory",
+    "Coverage",
+    "PatientProfile",
+    "EmergencyContact",
+    "Address",
+    "PharmacyInfo",
+    "ActivitySnapshot",
+    "SleepSnapshot",
+    "HealthProfile",
+    # Type aliases
+    "ProvenanceType",
+    "ProvenanceClass",
+    "ConditionStatus",
+    "AllergySeverity",
+    "AllergyCategory",
+    "LabInterpretation",
+    "MedicationClinicalIntent",
+    "CourseOfTherapyType",
+    "PrescriptionCategory",
+    "SourceFhirResourceType",
+    "VitalType",
+    "VitalInterpretation",
+    "ImmunizationStatus",
+    "PlanType",
+    "CoverageType",
+    "SubscriberRelationship",
+    "BiologicalSex",
+    "AgeGroup",
+    "BloodType",
+    "ProcedureStatus",
+    # Serialization
+    "serialize",
+    "serialize_from_dict",
+    "serialize_medication",
+    "serialize_condition",
+    "serialize_allergy",
+    "serialize_lab_result",
+    "serialize_vital_sign",
+    "serialize_immunization",
+    "serialize_procedure",
+    "serialize_family_history",
+    "serialize_coverage",
+    "serialize_patient_profile",
+    "serialize_activity_snapshot",
+    "serialize_sleep_snapshot",
+    # Deserialization
+    "parse",
+    "parse_one",
+    # Validation
+    "validate",
+    "validate_dict",
+    "ValidationResult",
+    "ValidationError",
+    # Pod
+    "Pod",
+    "RecordSet",
+    # Vocabulary
+    "NAMESPACES",
+    "TYPE_MAPPING",
+    "TYPE_TO_MAPPING_KEY",
+    "PROPERTY_PREDICATES",
+    "CURRENT_SCHEMA_VERSION",
+]

cascade_protocol/deserializer/__init__.py

@@ -0,0 +1,10 @@
+"""
+Cascade Protocol Turtle deserializer.
+"""
+
+from cascade_protocol.deserializer.turtle_parser import (
+    parse,
+    parse_one,
+)
+
+__all__ = ["parse", "parse_one"]

cascade_protocol/deserializer/turtle_parser.py

@@ -0,0 +1,353 @@
+"""
+Turtle parser for deserializing Cascade Protocol records.
+
+Uses rdflib for robust Turtle parsing, then maps RDF triples back
+to Python model objects using the PROPERTY_PREDICATES reverse map.
+
+Supports:
+- @prefix declarations
+- Subject-predicate-object triples
+- Typed literals (xsd:dateTime, xsd:date, xsd:integer, xsd:double)
+- URI references
+- Boolean literals
+- RDF lists
+- Blank nodes (PatientProfile nested objects)
+- Multi-value predicates (repeated predicate with different objects)
+
+Example:
+    >>> from cascade_protocol.deserializer import parse, parse_one
+    >>> meds = parse(turtle_string, "MedicationRecord")
+    >>> med = parse_one(turtle_string, "MedicationRecord")
+"""
+
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+from cascade_protocol.models.common import CascadeRecord
+from cascade_protocol.models.medication import Medication
+from cascade_protocol.models.condition import Condition
+from cascade_protocol.models.allergy import Allergy
+from cascade_protocol.models.lab_result import LabResult
+from cascade_protocol.models.vital_sign import VitalSign
+from cascade_protocol.models.immunization import Immunization
+from cascade_protocol.models.procedure import Procedure
+from cascade_protocol.models.family_history import FamilyHistory
+from cascade_protocol.models.coverage import Coverage
+from cascade_protocol.models.patient_profile import PatientProfile, EmergencyContact, Address, PharmacyInfo
+from cascade_protocol.models.wellness import ActivitySnapshot, SleepSnapshot
+from cascade_protocol.vocabularies.namespaces import (
+    NAMESPACES,
+    TYPE_MAPPING,
+    TYPE_TO_MAPPING_KEY,
+    build_reverse_predicate_map,
+)
+
+# ---------------------------------------------------------------------------
+# Reverse mappings
+# ---------------------------------------------------------------------------
+
+# VitalSign uses clinical: namespace for snomedCode and interpretation
+_ADDITIONAL_REVERSE = {
+    f"{NAMESPACES['clinical']}snomedCode": "snomed_code",
+    f"{NAMESPACES['clinical']}interpretation": "interpretation",
+}
+
+_REVERSE_PREDICATE_MAP = build_reverse_predicate_map(_ADDITIONAL_REVERSE)
+
+# Reverse type map: full RDF type URI -> (record_type_string, mapping_key)
+def _build_reverse_type_map() -> dict[str, tuple[str, str]]:
+    result: dict[str, tuple[str, str]] = {}
+    for mapping_key, mapping in TYPE_MAPPING.items():
+        rdf_type = mapping["rdf_type"]
+        colon_idx = rdf_type.find(":")
+        if colon_idx >= 0:
+            ns_prefix = rdf_type[:colon_idx]
+            local_name = rdf_type[colon_idx + 1:]
+            ns_uri = NAMESPACES.get(ns_prefix)
+            if ns_uri:
+                result[f"{ns_uri}{local_name}"] = (local_name, mapping_key)
+    return result
+
+_REVERSE_TYPE_MAP = _build_reverse_type_map()
+
+# ---------------------------------------------------------------------------
+# Field type classification
+# ---------------------------------------------------------------------------
+
+_BOOLEAN_FIELDS = {"is_active", "as_needed"}
+
+_INTEGER_FIELDS = {
+    "computed_age", "refills_allowed", "supply_duration_days", "onset_age",
+    "steps", "active_minutes", "calories", "awakenings",
+    "total_sleep_minutes", "deep_sleep_minutes", "rem_sleep_minutes", "light_sleep_minutes",
+}
+
+_FLOAT_FIELDS = {
+    "value", "reference_range_low", "reference_range_high", "distance",
+}
+
+_ARRAY_FIELDS = {
+    "drug_codes", "affects_vital_signs", "monitored_vital_signs",
+}
+
+# ---------------------------------------------------------------------------
+# Record type -> model class mapping
+# ---------------------------------------------------------------------------
+
+_TYPE_CLASS_MAP: dict[str, type] = {
+    "MedicationRecord": Medication,
+    "ConditionRecord": Condition,
+    "AllergyRecord": Allergy,
+    "LabResultRecord": LabResult,
+    "VitalSign": VitalSign,
+    "ImmunizationRecord": Immunization,
+    "ProcedureRecord": Procedure,
+    "FamilyHistoryRecord": FamilyHistory,
+    "CoverageRecord": Coverage,
+    "InsurancePlan": Coverage,
+    "PatientProfile": PatientProfile,
+    "ActivitySnapshot": ActivitySnapshot,
+    "SleepSnapshot": SleepSnapshot,
+}
+
+# ---------------------------------------------------------------------------
+# Resolve type URI
+# ---------------------------------------------------------------------------
+
+def _resolve_type_uri(type_str: str) -> str | None:
+    """Resolve a record type string (e.g. 'MedicationRecord') to a full RDF type URI."""
+    for mapping in TYPE_MAPPING.values():
+        rdf_type = mapping["rdf_type"]
+        colon_idx = rdf_type.find(":")
+        if colon_idx >= 0:
+            ns_prefix = rdf_type[:colon_idx]
+            local_name = rdf_type[colon_idx + 1:]
+            if local_name == type_str:
+                ns_uri = NAMESPACES.get(ns_prefix)
+                if ns_uri:
+                    return f"{ns_uri}{local_name}"
+    return None
+
+# ---------------------------------------------------------------------------
+# rdflib-based parsing
+# ---------------------------------------------------------------------------
+
+def _parse_with_rdflib(turtle: str) -> list[dict[str, Any]]:
+    """
+    Parse Turtle content using rdflib and extract all typed subjects.
+
+    Returns a list of dicts, one per unique subject, with an internal
+    ``_rdf_type`` key set to the full RDF type URI.
+    """
+    try:
+        import rdflib
+        from rdflib import Graph, URIRef, Literal, BNode
+        from rdflib.namespace import RDF, XSD
+    except ImportError:
+        raise ImportError(
+            "rdflib is required for Turtle parsing. "
+            "Install it with: pip install rdflib"
+        )
+
+    g = Graph()
+    g.parse(data=turtle, format="turtle")
+
+    RDF_TYPE = RDF.type
+    CASCADE_NS = NAMESPACES["cascade"]
+
+    # Group triples by subject
+    subject_triples: dict[str, list[tuple[str, Any, str]]] = {}
+    for s, p, o in g:
+        subj_str = str(s)
+        if isinstance(s, BNode):
+            subj_str = f"_:{s}"
+        subject_triples.setdefault(subj_str, [])
+        subject_triples[subj_str].append((str(p), o, subj_str))
+
+    results: list[dict[str, Any]] = []
+
+    for subj_str, triples in subject_triples.items():
+        # Find rdf:type
+        rdf_type_uri: str | None = None
+        for pred_uri, obj, _ in triples:
+            if pred_uri == str(RDF_TYPE):
+                rdf_type_uri = str(obj)
+                break
+
+        if rdf_type_uri is None:
+            continue  # Skip subjects without a type
+
+        # Check if it's a known Cascade type
+        type_info = _REVERSE_TYPE_MAP.get(rdf_type_uri)
+        if type_info is None:
+            continue
+
+        record_type, _ = type_info
+
+        record: dict[str, Any] = {
+            "id": subj_str,
+            "type": record_type,
+        }
+
+        # Group by predicate (for repeated predicates -> arrays)
+        pred_values: dict[str, list[Any]] = {}
+        for pred_uri, obj, _ in triples:
+            if pred_uri == str(RDF_TYPE):
+                continue
+            pred_values.setdefault(pred_uri, [])
+            pred_values[pred_uri].append(obj)
+
+        for pred_uri, objects in pred_values.items():
+            py_key = _REVERSE_PREDICATE_MAP.get(pred_uri)
+            if not py_key:
+                continue
+
+            # Array fields
+            if py_key in _ARRAY_FIELDS:
+                values: list[Any] = []
+                for obj in objects:
+                    if isinstance(obj, (rdflib.URIRef,)):
+                        values.append(str(obj))
+                    elif isinstance(obj, Literal):
+                        values.append(str(obj))
+                    elif hasattr(obj, "__iter__"):
+                        # RDF collection
+                        try:
+                            for item in obj:
+                                values.append(str(item))
+                        except Exception:
+                            values.append(str(obj))
+                    else:
+                        values.append(str(obj))
+                record[py_key] = values
+                continue
+
+            # Single-value fields: use first object
+            obj = objects[0]
+
+            # dataProvenance: extract local name from cascade namespace
+            if py_key == "data_provenance":
+                obj_str = str(obj)
+                if obj_str.startswith(CASCADE_NS):
+                    record[py_key] = obj_str[len(CASCADE_NS):]
+                else:
+                    record[py_key] = obj_str
+                continue
+
+            # Boolean fields
+            if py_key in _BOOLEAN_FIELDS:
+                if isinstance(obj, Literal):
+                    record[py_key] = str(obj).lower() == "true"
+                else:
+                    record[py_key] = str(obj).lower() == "true"
+                continue
+
+            # Integer fields
+            if py_key in _INTEGER_FIELDS:
+                try:
+                    record[py_key] = int(str(obj))
+                except (ValueError, TypeError):
+                    record[py_key] = str(obj)
+                continue
+
+            # Float fields
+            if py_key in _FLOAT_FIELDS:
+                try:
+                    record[py_key] = float(str(obj))
+                except (ValueError, TypeError):
+                    record[py_key] = str(obj)
+                continue
+
+            # Typed literals
+            if isinstance(obj, Literal):
+                if obj.datatype == XSD.integer:
+                    try:
+                        record[py_key] = int(str(obj))
+                    except ValueError:
+                        record[py_key] = str(obj)
+                elif obj.datatype in (XSD.double, XSD.decimal, XSD.float):
+                    try:
+                        record[py_key] = float(str(obj))
+                    except ValueError:
+                        record[py_key] = str(obj)
+                elif obj.datatype == XSD.boolean:
+                    record[py_key] = str(obj).lower() == "true"
+                else:
+                    record[py_key] = str(obj)
+                continue
+
+            # URI reference
+            if isinstance(obj, rdflib.URIRef):
+                record[py_key] = str(obj)
+                continue
+
+            # Default
+            record[py_key] = str(obj)
+
+        results.append(record)
+
+    return results
+
+
+def _dict_to_record(data: dict[str, Any]) -> CascadeRecord | None:
+    """Convert a parsed dict to the appropriate CascadeRecord subclass."""
+    record_type = data.get("type", "")
+    cls = _TYPE_CLASS_MAP.get(record_type)
+    if cls is None:
+        return None
+
+    from dataclasses import fields as dc_fields
+    valid_keys = {f.name for f in dc_fields(cls)}
+    kwargs = {k: v for k, v in data.items() if k in valid_keys}
+    return cls(**kwargs)  # type: ignore[call-arg]
+
+
+def parse(turtle: str, record_type: str) -> list[CascadeRecord]:
+    """
+    Parse Turtle content and return typed records matching the specified type.
+
+    Args:
+        turtle: Turtle document content.
+        record_type: Record type string (e.g., ``"MedicationRecord"``, ``"VitalSign"``).
+
+    Returns:
+        List of parsed records of the specified type.
+
+    Raises:
+        ValueError: If the record type is unknown.
+        ImportError: If rdflib is not installed.
+
+    Example:
+        >>> meds = parse(turtle_string, "MedicationRecord")
+    """
+    type_uri = _resolve_type_uri(record_type)
+    if type_uri is None:
+        raise ValueError(f"Unknown record type: {record_type!r}")
+
+    all_records = _parse_with_rdflib(turtle)
+    matching = [r for r in all_records if r.get("type") == record_type]
+
+    result: list[CascadeRecord] = []
+    for data in matching:
+        rec = _dict_to_record(data)
+        if rec is not None:
+            result.append(rec)
+    return result
+
+
+def parse_one(turtle: str, record_type: str) -> CascadeRecord | None:
+    """
+    Parse a single record from Turtle content.
+
+    Returns the first record matching the specified type, or ``None`` if none found.
+
+    Args:
+        turtle: Turtle document content.
+        record_type: Record type string.
+
+    Returns:
+        The parsed record, or None.
+    """
+    results = parse(turtle, record_type)
+    return results[0] if results else None

cascade_protocol/models/__init__.py

@@ -0,0 +1,84 @@
+"""
+Cascade Protocol data models.
+
+All record types available as top-level imports from this package.
+"""
+
+from cascade_protocol.models.common import (
+    CascadeRecord,
+    ProvenanceType,
+    ProvenanceClass,
+    ConditionStatus,
+    AllergySeverity,
+    AllergyCategory,
+    LabInterpretation,
+    MedicationClinicalIntent,
+    CourseOfTherapyType,
+    PrescriptionCategory,
+    SourceFhirResourceType,
+    VitalType,
+    VitalInterpretation,
+    ImmunizationStatus,
+    PlanType,
+    CoverageType,
+    SubscriberRelationship,
+    BiologicalSex,
+    AgeGroup,
+    BloodType,
+    ProcedureStatus,
+)
+from cascade_protocol.models.medication import Medication
+from cascade_protocol.models.condition import Condition
+from cascade_protocol.models.allergy import Allergy
+from cascade_protocol.models.lab_result import LabResult
+from cascade_protocol.models.vital_sign import VitalSign
+from cascade_protocol.models.immunization import Immunization
+from cascade_protocol.models.procedure import Procedure
+from cascade_protocol.models.family_history import FamilyHistory
+from cascade_protocol.models.coverage import Coverage
+from cascade_protocol.models.patient_profile import PatientProfile, EmergencyContact, Address, PharmacyInfo
+from cascade_protocol.models.wellness import ActivitySnapshot, SleepSnapshot
+from cascade_protocol.models.health_profile import HealthProfile
+
+__all__ = [
+    # Base
+    "CascadeRecord",
+    # Type aliases
+    "ProvenanceType",
+    "ProvenanceClass",
+    "ConditionStatus",
+    "AllergySeverity",
+    "AllergyCategory",
+    "LabInterpretation",
+    "MedicationClinicalIntent",
+    "CourseOfTherapyType",
+    "PrescriptionCategory",
+    "SourceFhirResourceType",
+    "VitalType",
+    "VitalInterpretation",
+    "ImmunizationStatus",
+    "PlanType",
+    "CoverageType",
+    "SubscriberRelationship",
+    "BiologicalSex",
+    "AgeGroup",
+    "BloodType",
+    "ProcedureStatus",
+    # Record types
+    "Medication",
+    "Condition",
+    "Allergy",
+    "LabResult",
+    "VitalSign",
+    "Immunization",
+    "Procedure",
+    "FamilyHistory",
+    "Coverage",
+    "PatientProfile",
+    "EmergencyContact",
+    "Address",
+    "PharmacyInfo",
+    "ActivitySnapshot",
+    "SleepSnapshot",
+    "HealthProfile",
+]

cascade_protocol/models/allergy.py

@@ -0,0 +1,67 @@
+"""
+Allergy data model for the Cascade Protocol.
+
+Represents an allergy or intolerance record, sourced from EHR imports
+or self-reported by the patient.
+
+RDF type: ``health:AllergyRecord``
+Vocabulary: https://ns.cascadeprotocol.org/health/v1#
+
+See: https://cascadeprotocol.org/docs/cascade-protocol-schemas
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from cascade_protocol.models.common import CascadeRecord
+
+
+@dataclass
+class Allergy(CascadeRecord):
+    """
+    An allergy record in the Cascade Protocol.
+
+    Required fields: ``allergen``, ``data_provenance``, ``schema_version``.
+    All date fields use ISO 8601 string format.
+
+    Serializes as ``health:AllergyRecord`` in Turtle.
+    """
+
+    type: str = field(default="AllergyRecord", init=True)
+
+    allergen: str = ""
+    """
+    Name of the allergen substance.
+    Maps to ``health:allergen`` in Turtle serialization.
+    """
+
+    allergy_category: str | None = None
+    """
+    Category of the allergen (e.g., ``"medication"``, ``"food"``, ``"environmental"``).
+    Maps to ``health:allergyCategory`` in Turtle serialization.
+    """
+
+    reaction: str | None = None
+    """
+    Description of the allergic reaction (e.g., ``"Hives (urticaria)"``).
+    Maps to ``health:reaction`` in Turtle serialization.
+    """
+
+    allergy_severity: str | None = None
+    """
+    Severity of the allergic reaction (mild, moderate, severe, life-threatening).
+    Maps to ``health:allergySeverity`` in Turtle serialization.
+    """
+
+    onset_date: str | None = None
+    """
+    Date of allergy onset (ISO 8601).
+    Maps to ``health:onsetDate`` in Turtle serialization.
+    """
+
+    @classmethod
+    def from_dataframe(cls, df: "pd.DataFrame") -> list["Allergy"]:  # type: ignore[name-defined]
+        """Reconstruct a list of Allergy records from a pandas DataFrame."""
+        from cascade_protocol.pandas_integration.dataframe import dataframe_to_records
+        return dataframe_to_records(df, cls)  # type: ignore[return-value]