Clinical Event Logging

Clinical Event Logging

The Klira SDK provides structured event logging functions for healthcare AI workflows. Each function creates a child span with appropriate attributes, enabling auditability and compliance monitoring for clinical AI systems.

All functions are imported from klira.sdk.healthcare:

from klira.sdk.healthcare import (
    log_clinical_decision,
    log_human_escalation,
    log_agent_handoff,
    log_safety_check,
    log_rag_retrieval,
)

log_clinical_decision()

Record when the AI system makes or recommends a clinical decision.

log_clinical_decision(
    decision="Recommend follow-up imaging",
    reasoning="Patient symptoms consistent with suspected fracture",
    confidence=0.87,
    guideline_reference="ACR Appropriateness Criteria"
)

Parameters

Parameter	Type	Required	Description
decision	str	Yes	The clinical decision or recommendation
reasoning	str	No	Explanation of the decision logic
confidence	float	No	Confidence score (0.0–1.0)
**extra	Any	No	Additional key-value attributes added to the span

Span Attributes

• klira.healthcare.event_type = "clinical_decision"
• klira.healthcare.decision
• klira.healthcare.reasoning
• klira.healthcare.confidence

log_human_escalation()

Record when the AI system escalates to a human clinician.

log_human_escalation(
    reason="Patient reported chest pain — requires immediate clinical assessment",
    urgency="critical"
)

Parameters

Parameter	Type	Required	Description
reason	str	Yes	Why escalation is needed
urgency	str	No	Urgency level: "normal", "high", "critical". Default: "normal"
**extra	Any	No	Additional attributes

Span Attributes

• klira.healthcare.event_type = "human_escalation"
• klira.healthcare.escalation_reason
• klira.healthcare.urgency

log_agent_handoff()

Record when one AI agent hands off to another.

log_agent_handoff(
    from_agent="triage_agent",
    to_agent="specialist_agent",
    reason="Patient symptoms require cardiology-specific assessment"
)

Parameters

Parameter	Type	Required	Description
from_agent	str	Yes	Name of the originating agent
to_agent	str	Yes	Name of the receiving agent
reason	str	No	Reason for the handoff
**extra	Any	No	Additional attributes

Span Attributes

• klira.healthcare.event_type = "agent_handoff"
• klira.healthcare.from_agent
• klira.healthcare.to_agent
• klira.healthcare.handoff_reason

log_safety_check()

Record the result of a clinical safety check.

log_safety_check(
    check_type="drug_interaction",
    passed=False,
    details="Potential interaction between prescribed medications detected"
)

Parameters

Parameter	Type	Required	Description
check_type	str	Yes	Type of safety check performed
passed	bool	Yes	Whether the check passed
details	str	No	Additional details about the result
**extra	Any	No	Additional attributes

Span Attributes

• klira.healthcare.event_type = "safety_check"
• klira.healthcare.check_type
• klira.healthcare.check_passed
• klira.healthcare.check_details

log_rag_retrieval()

Record a retrieval-augmented generation lookup against clinical knowledge bases.

log_rag_retrieval(
    source="clinical_guidelines_db",
    query="treatment protocol for type 2 diabetes",
    result_count=5
)

Parameters

Parameter	Type	Required	Description
source	str	Yes	Name of the knowledge source
query	str	Yes	The retrieval query
result_count	int	No	Number of results returned. Default: 0
**extra	Any	No	Additional attributes

Span Attributes

• klira.healthcare.event_type = "rag_retrieval"
• klira.healthcare.rag_source
• klira.healthcare.rag_query
• klira.healthcare.rag_result_count

Complete Working Example

from klira.sdk import Klira
from klira.sdk.decorators import workflow, agent, tool
from klira.sdk.healthcare import (
    set_patient_context,
    set_clinical_context,
    log_clinical_decision,
    log_human_escalation,
    log_safety_check,
    log_rag_retrieval,
)

Klira.init(
    app_name="ClinicalDecisionSupport",
    api_key="klira_live_your_key",
    clinical_domain="emergency_medicine",
)

@workflow(name="er_triage", user_id="dr_jones", conversation_id="triage_session_001")
async def triage_patient(patient_id: str, symptoms: str) -> dict:
    set_patient_context(patient_id=patient_id)
    set_clinical_context(department="Emergency", specialty="General")

    # Look up relevant clinical guidelines
    log_rag_retrieval(
        source="emergency_protocols",
        query=symptoms,
        result_count=3
    )

    # Run safety checks
    log_safety_check(
        check_type="allergy_screening",
        passed=True,
        details="No known drug allergies on file"
    )

    # Make clinical recommendation
    severity = await assess_severity(symptoms)

    if severity == "critical":
        log_human_escalation(
            reason=f"Critical symptoms detected: {symptoms}",
            urgency="critical"
        )
        return {"action": "escalate", "urgency": "critical"}

    log_clinical_decision(
        decision=f"Triage category: {severity}",
        reasoning=f"Based on symptom assessment: {symptoms}",
        confidence=0.82
    )

    return {"action": "triage", "severity": severity}

@agent(name="severity_assessor")
async def assess_severity(symptoms: str) -> str:
    # Clinical severity assessment logic
    return "moderate"

Related Pages

• Healthcare AI Context — Set patient and clinical context
• PHI Anonymization — Configure PHI redaction and masking
• Tracing — View clinical events in distributed traces