kipu-python 0.0.2

A comprehensive Python library for the Kipu Healthcare API with HMAC SHA1 authentication and recursive JSON flattening

Kipu API Python library

The Kipu Python library provides convenient access to the Kipu API from any Python 3.8+ application. The library includes HMAC SHA1/SHA256 authentication, recursive JSON flattening capabilities and type definitions for most of the request params and response fields, and offers asynchronous clients powered by [asyncio].

It is generated from our KipuAPI V3 specification

🚀 Features

• ✅ Complete API Coverage: All 80+ Kipu API V3 endpoints implemented
• 🔐 Secure Authentication: HMAC SHA1/SHA256 signature generation
• 📊 Automatic Flattening: Converts nested JSON responses to pandas DataFrames
• ⚡ Async Support: Built with asyncio for high performance
• 🛡️ Error Handling: Comprehensive exception hierarchy
• 📝 Type Hints: Full typing support for better development experience
• 🔄 Flexible Response Format: Choose between raw JSON or flattened DataFrames

📦 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

The library handles HMAC SHA1 signature generation automatically. You need three credentials from Kipu:

• access_id: Your API access identifier
• secret_key: Your secret key for signature generation
• app_id: Your application ID (also called recipient_id)
• version: API version (3 for SHA1, 4 for SHA256)

API Version Support

The library supports both Kipu API v3 and v4:

• V3: Uses HMAC-SHA1 authentication (default, most stable)
• V4: Uses HMAC-SHA256 authentication (newer, more secure)

# 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

• Patients: Census, individual records, admissions, latest updates
• Medical Records: Vital signs, allergies, assessments, glucose logs
• Evaluations: Patient evaluations, evaluation templates
• Appointments: Scheduling, types, statuses, resources
• Users & Providers: User management, provider records, roles
• Administrative: Locations, care levels, flags, settings
• Insurance: Insurance records, verification
• Groups: Group sessions, patient groups

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

• Python: 3.8+
• Dependencies:
  • aiohttp>=3.8.0 - Async HTTP client
  • pandas>=1.3.0 - Data manipulation
  • numpy>=1.20.0 - Numerical computing
  • tqdm>=4.60.0 - Progress bars

🤝 Contributing

Welcome contributions! Here's the quick process:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Run quality checks: make lint and make test
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

For detailed guidelines, see CONTRIBUTING.md

For faster development, use UV: See UV_GUIDE.md

📃 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: Read the Docs
• Issues: GitHub Issues
• Email: [e-mail]

🏥 Healthcare Compliance

This library is designed for healthcare applications. Ensure your implementation complies with:

• HIPAA (Health Insurance Portability and Accountability Act)
• Local healthcare data protection regulations
• Kipu's terms of service and security requirements

---

Built with ❤️ for the opensource community