cascade-protocol

Python SDK for the Cascade Protocol — a privacy-first, local-first standard for serializing personal health data as RDF/Turtle.

Installation

pip install cascade-protocol

With optional extras:

pip install "cascade-protocol[pandas]"       # pandas DataFrame integration
pip install "cascade-protocol[validation]"   # SHACL validation via pyshacl
pip install "cascade-protocol[notebooks]"    # Jupyter notebook support
pip install "cascade-protocol[all]"          # Everything

Quick Start

from cascade_protocol import Medication, serialize, validate, Pod

# Create a medication record
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",
)

# Serialize to Turtle
turtle = serialize(med)
print(turtle)

# Validate structural integrity
result = validate(turtle)
print(result.is_valid, result.errors)

# Open a Cascade Pod and query records
pod = Pod.open("./my-pod")
meds = pod.query("medications")

# Convert to pandas DataFrame (requires pandas extra)
df = meds.to_dataframe()
print(df.head())

# Reconstruct models from DataFrame
restored = Medication.from_dataframe(df)

Serialization Output

@prefix cascade: <https://ns.cascadeprotocol.org/core/v1#> .
@prefix health: <https://ns.cascadeprotocol.org/health/v1#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<urn:uuid:med0-0001-aaaa-bbbb-ccccddddeeee> a health:MedicationRecord ;
    health:medicationName "Metoprolol Succinate" ;
    health:isActive true ;
    cascade:dataProvenance cascade:ClinicalGenerated ;
    cascade:schemaVersion "1.3" ;
    health:dose "25mg" .

Supported Data Types

Pod API

from cascade_protocol import Pod

pod = Pod.open("./my-pod")

# Query by data type
meds = pod.query("medications")
vitals = pod.query("vital-signs")
profile = pod.query("patient-profile")

# Iterate records
for med in meds:
    print(med.medication_name, med.dose)

# DataFrame conversion
df = meds.to_dataframe()

Parsing Turtle

from cascade_protocol.deserializer import parse, parse_one

# Parse multiple records
meds = parse(turtle_string, "MedicationRecord")

# Parse a single record
med = parse_one(turtle_string, "MedicationRecord")

Namespaces

from cascade_protocol.vocabularies import NAMESPACES, CURRENT_SCHEMA_VERSION

print(NAMESPACES["cascade"])   # https://ns.cascadeprotocol.org/core/v1#
print(NAMESPACES["health"])    # https://ns.cascadeprotocol.org/health/v1#
print(CURRENT_SCHEMA_VERSION)  # 1.3

Privacy & Security

• Zero network calls during normal operation
• All processing is local
• No telemetry or analytics
• Data never leaves your machine

License

Apache 2.0 — see LICENSE.

Links

• Getting Started Guide
• Protocol Schema Reference
• Conformance Test Suite