11.6 Agena API Integration - ravkorsurv/kor-ai-core GitHub Wiki

11.6 Agena API Integration โ€“ Kor.ai Bayesian Inference Engine

Kor.ai uses the Agena.ai Cloud API to perform probabilistic inference on Bayesian Network models for market abuse detection. This document describes how we authenticate, structure payloads, interpret responses, and integrate inference into the alerting pipeline.

๐Ÿ”Œ API Endpoint

Inference Endpoint

POST https://api.agena.ai/public/v1/calculate

๐Ÿ” Authentication Flow

  1. Token Request

POST https://auth.agena.ai/realms/cloud/protocol/openid-connect/token

  1. HTTP Headers

Authorization: Bearer <access_token>
Content-Type: application/json

  1. Management

  • Tokens are securely stored in environment variables

  • Backend rotates tokens on expiry

  • Only scoped secrets are permitted in execution environments

๐Ÿ“† Payload Format

{
  "model": "InsiderDealingModel",
  "dataSet": {
    "Q1": true,
    "Q3": "High",
    "Q5": "Positive"
  },
  "sync-wait": true
}
Field Description
model Name of the Bayesian model hosted in Agena
dataSet Map of node IDs to observed evidence
sync-wait When true, returns the full result in the same call

๐Ÿ”„ Retry and Fallback Logic

  • Max retries: 3

  • Retry delay: exponential backoff

  • Fallback trigger:

    • API timeout

    • 5xx or 401 response

  • Fallback outcome:

    • Alert marked as "scoreStatus": "API_Failure"

    • Notification logged for reprocessing

๐Ÿ”ฎ Future Enhancements

  • Support for Agenaโ€™s asynchronous batch mode (async)

  • Token auto-refresh handling via background job

  • Integration with local pgmpy engine as fallback or override

  • Per-alert cost tracking for API budget control

  • Unified format for all responses to support case management export

โš ๏ธ **GitHub.com Fallback** โš ๏ธ