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: rahul01110100@gmail.com

🏥 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