Middleware and Enterprise Service Bus for AI#

<!-- MuleSoft Flow: Clinical AI Enrichment Process API -->
<!-- Educational example — not for clinical use -->
<flow name="clinical-ai-enrichment-process-api">

    <!-- 1. Receive canonical clinical context from System API -->
    <http:listener config-ref="ai-enrichment-listener-config"
                   path="/api/v1/clinical-enrichment"
                   allowedMethods="POST"/>

    <!-- 2. Log request metadata (never log PHI in ESB logs) -->
    <logger level="INFO"
            message="Clinical AI enrichment request: #[correlationId]"
            doc:name="Log Request Metadata"/>

    <!-- 3. Transform canonical format to AI service request format -->
    <ee:transform doc:name="Transform to AI Request Format">
        <ee:message>
            <ee:set-payload><![CDATA[
                %dw 2.0
                output application/json
                ---
                {
                    query: payload.clinicalQuestion,
                    capability: "clinical_rag",
                    context: {
                        encounterClass: payload.encounter.class,
                        primaryDiagnosisCodes: payload.conditions map (c) -> c.code,
                        activeMedications: payload.medications map (m) -> m.display
                    },
                    requestId: correlationId
                }
            ]]></ee:set-payload>
        </ee:message>
    </ee:transform>

    <!-- 4. Invoke AI Gateway with circuit breaker -->
    <http:request config-ref="ai-gateway-request-config"
                  method="POST"
                  path="/v1/clinical-rag"
                  doc:name="Invoke AI Gateway">
        <http:response-validator>
            <http:success-status-code-validator values="200,202"/>
        </http:response-validator>
        <http:request-builder>
            <http:header headerName="Authorization" value="#['Bearer ' ++ vars.aiGatewayToken]"/>
            <http:header headerName="X-Request-ID" value="#[correlationId]"/>
        </http:request-builder>
    </http:request>

    <!-- 5. Transform AI response to canonical Process API response -->
    <ee:transform doc:name="Transform AI Response to Canonical">
        <ee:message>
            <ee:set-payload><![CDATA[
                %dw 2.0
                output application/json
                ---
                {
                    requestId: payload.requestId,
                    aiEnrichment: {
                        response: payload.response,
                        citations: payload.citations map (c) -> {
                            title: c.document_title,
                            source: c.source_organization,
                            effectiveDate: c.effective_date
                        },
                        cached: payload.cached,
                        modelTier: payload.model_tier
                    },
                    processingMetadata: {
                        latencyMs: payload.latency_ms,
                        processedAt: now() as String
                    }
                }
            ]]></ee:set-payload>
        </ee:message>
    </ee:transform>

    <!-- 6. Error handler: return safe fallback on AI service failure -->
    <error-handler>
        <on-error-continue type="HTTP:TIMEOUT, HTTP:CONNECTIVITY">
            <ee:transform>
                <ee:message>
                    <ee:set-payload><![CDATA[
                        %dw 2.0
                        output application/json
                        ---
                        {
                            requestId: correlationId,
                            aiEnrichment: null,
                            fallbackReason: "ai_service_unavailable",
                            processingMetadata: {processedAt: now() as String}
                        }
                    ]]></ee:set-payload>
                </ee:message>
            </ee:transform>
        </on-error-continue>
    </error-handler>

</flow>

# Azure Logic Apps + API Management pattern for AI integration
# Educational example — not for clinical use

AZURE_INTEGRATION_PATTERN = {
    "description": (
        "Azure API Management (APIM) acts as the AI gateway within Azure Integration Services. "
        "Logic Apps orchestrate the workflow: receive event, retrieve FHIR context, "
        "invoke APIM → Azure OpenAI, write result back to FHIR."
    ),
    
    "apim_policy": """
<!-- Azure API Management policy for Azure OpenAI proxy with rate limiting -->
<!-- Educational example -->
<policies>
    <inbound>
        <!-- Validate subscription key -->
        <validate-jwt header-name="Authorization" require-scheme="Bearer">
            <openid-config url="https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration"/>
            <required-claims>
                <claim name="scp" match="any">
                    <value>ai-platform.write</value>
                </claim>
            </required-claims>
        </validate-jwt>
        
        <!-- Rate limiting: 10,000 tokens per minute per subscription -->
        <rate-limit-by-key calls="100" renewal-period="60"
                           counter-key="@(context.Subscription.Id)"
                           remaining-calls-header-name="X-RateLimit-Remaining"/>
        
        <!-- Route to Azure OpenAI endpoint -->
        <set-backend-service base-url="https://reference-oai.openai.azure.com"/>
        
        <!-- Strip internal headers before forwarding -->
        <set-header name="api-key" exists-action="override">
            <value>{{azure-openai-api-key}}</value>
        </set-header>
    </inbound>
    
    <outbound>
        <!-- Remove Azure-specific headers from response -->
        <set-header name="apim-request-id" exists-action="delete"/>
        
        <!-- Log token usage for cost attribution -->
        <log-to-eventhub logger-id="ai-usage-logger">
            @{
                var body = context.Response.Body?.As<JObject>();
                return new JObject(
                    new JProperty("subscriptionId", context.Subscription.Id),
                    new JProperty("promptTokens", body?["usage"]?["prompt_tokens"]),
                    new JProperty("completionTokens", body?["usage"]?["completion_tokens"]),
                    new JProperty("timestamp", DateTime.UtcNow)
                ).ToString();
            }
        </log-to-eventhub>
    </outbound>
</policies>
""",
}

# Python equivalent of ESB HL7 → JSON transformation
# Typical ESB implementation uses DataWeave (MuleSoft) or XSLT
# Educational example — not for clinical use

def transform_hl7_adt_to_ai_event(raw_hl7: str) -> dict:
    """
    Transform HL7 v2 ADT message to structured AI event payload.
    
    In MuleSoft, this is implemented as a DataWeave transformation.
    This Python equivalent illustrates the transformation logic.
    
    Educational example — not for clinical use.
    """
    import hl7
    
    message = hl7.parse(raw_hl7)
    
    msh = message["MSH"][0]
    pid = message["PID"][0] if "PID" in message else None
    pv1 = message["PV1"][0] if "PV1" in message else None
    
    def safe_get(segment, field, component=0):
        try:
            return str(segment[field][component]) if segment[field] else ""
        except (IndexError, KeyError):
            return ""
    
    return {
        "messageType": "adt",
        "triggerEvent": safe_get(msh, 9, 1),
        "messageControlId": safe_get(msh, 10),
        "sendingFacility": safe_get(msh, 4),
        "messageTimestamp": safe_get(msh, 7),
        "patient": {
            "medicalRecordNumber": safe_get(pid, 3, 0) if pid else None,
            "dateOfBirth": safe_get(pid, 7) if pid else None,
            "gender": safe_get(pid, 8) if pid else None,
        } if pid else None,
        "visit": {
            "visitNumber": safe_get(pv1, 19) if pv1 else None,
            "patientClass": safe_get(pv1, 2) if pv1 else None,
            "admitDateTime": safe_get(pv1, 44) if pv1 else None,
            "attendingPhysicianNpi": safe_get(pv1, 7, 0) if pv1 else None,
        } if pv1 else None,
    }