Kipu API Python library

🚀 Features

📦 Installation

pip install kipu-python

🔧 Quick Start

import asyncio
from kipu import KipuClient
async def main():
 async with KipuClient(
 access_id="your_access_id",
 secret_key="your_secret_key", 
 app_id="your_app_id",
 version=3
 ) as client:
 
 # Get patient census as flattened DataFrame
 census_df = await client.get_patients_census()
 print(f"Found {len(census_df)} patients")
 
 # Get specific patient as raw JSON
 patient_data = await client.get_patient("patient_id", flatten=False)
 print(f"Patient: {patient_data['first_name']} {patient_data['last_name']}")
asyncio.run(main())

🔑 Authentication

API Version Support

# Use V3 (SHA1)
client_v3 = KipuClient(access_id, secret_key, app_id, version=3)
# Use V4 (SHA256 - recommended for new integrations)
client_v4 = KipuClient(access_id, secret_key, app_id, version=4)

📚 API Coverage

Patient Management

# Get patient census
census_df = await client.get_patients_census(params={
 "phi_level": "high",
 "page": 1,
 "per": 50
})
# Get specific patient
patient = await client.get_patient("patient_id")
# Create new patient
patient_data = {
 "document": {
 "recipient_id": app_id,
 "data": {
 "first_name": "John",
 "last_name": "Doe",
 "dob": "1990-01-01"
 }
 }
}
new_patient = await client.create_patient(patient_data)

Medical Records

# Get vital signs
vital_signs_df = await client.get_vital_signs()
patient_vitals = await client.get_patient_vital_signs("patient_id")
# Get allergies
allergies_df = await client.get_allergies()
patient_allergies = await client.get_patient_allergies("patient_id")
# Create vital signs
vital_data = {
 "document": {
 "recipient_id": app_id,
 "data": {
 "systolic_blood_pressure": 120,
 "diastolic_blood_pressure": 80,
 "heart_rate": 72
 }
 }
}
await client.create_patient_vital_signs("patient_id", vital_data)

Appointments

# Get appointments
appointments_df = await client.get_scheduler_appointments(params={
 "start_date": "2024-01-01",
 "end_date": "2024-12-31"
})
# Get patient appointments
patient_appointments = await client.get_patient_appointments("patient_id")

Administrative

# Get locations, users, providers
locations_df = await client.get_locations()
users_df = await client.get_users()
providers_df = await client.get_providers()

🔄 Response Processing

Automatic Flattening (Default)

# Returns a flattened pandas DataFrame
census_df = await client.get_patients_census()
print(type(census_df)) # <class 'pandas.core.frame.DataFrame'>

Raw JSON Response

# Returns raw JSON
census_data = await client.get_patients_census(flatten=False)
print(type(census_data)) # <class 'dict'> or <class 'list'>

Global Flattening Control

# Disable auto-flattening globally
async with KipuClient(
 access_id, secret_key, app_id, version,
 auto_flatten=False
) as client:
 raw_data = await client.get_patients_census() # Raw JSON
 flat_data = await client.get_patients_census(flatten=True) # DataFrame

🛡️ Error Handling

from kipu.exceptions import (
 KipuAPIError,
 KipuAuthenticationError,
 KipuValidationError,
 KipuNotFoundError,
 KipuServerError
)
try:
 patient = await client.get_patient("invalid_id")
except KipuNotFoundError as e:
 print(f"Patient not found: {e.message}")
except KipuAuthenticationError as e:
 print(f"Authentication failed: {e.message}")
except KipuAPIError as e:
 print(f"API error: {e.message} (Status: {e.status_code})")

📎 File Uploads

# Patient with attachment
patient_data = {
 "document[recipient_id]": app_id,
 "document[data][first_name]": "John",
 "document[data][last_name]": "Doe"
}
files = {
 "document[attachments_attributes][0][attachment]": {
 "content": file_bytes,
 "filename": "patient_id.jpg",
 "content_type": "image/jpeg"
 }
}
await client.create_patient(patient_data, files=files)

📋 Available Endpoints

Core Categories

Complete Method List

# Patient endpoints
client.get_patients_census()
client.get_patient(patient_id)
client.create_patient(data)
client.update_patient(patient_id, data)
client.get_patients_admissions()
client.get_patients_latest()
# Medical records
client.get_vital_signs()
client.get_patient_vital_signs(patient_id)
client.create_patient_vital_signs(patient_id, data)
client.get_allergies()
client.get_patient_allergies(patient_id)
client.get_cows()
client.get_ciwa_ars()
client.get_glucose_logs()
# And 70+ more endpoints...

🧪 Development & Testing

Quick Setup

# Clone and install
git clone [https://github.com/Rahulkumar010/kipu-python.git](https://github.com/Rahulkumar010/kipu-python.git)
cd kipu-python
# Traditional
pip install -e ".[dev]"
# Fast with UV (10x faster!)
pip install uv && uv pip install -e ".[dev]"
make test # Run tests
make format # Format code
make lint # Check quality
make version # Show version
make bump-patch # Bump version

📄 Requirements

🤝 Contributing

📃 License

🆘 Support

🏥 Healthcare Compliance