// docs / profiling

Profiling API

The cognitive profiling engine at the heart of KALEI.

Overview

KALEI analyzes AI decision-making behavior across 10 orthogonal cognitive dimensions using 83 mathematically calibrated game-theoretic environments. Each profiling session subjects the agent to a battery of controlled scenarios designed to isolate specific cognitive capabilities and biases.

The result is a multi-dimensional cognitive fingerprint: a Cognum (CQ) score, a cognitive type classification, granular dimension scores with confidence intervals, and a comprehensive bias analysis report.

Starting a Profile

POST /kalei/v1/profile
json
{
  "agentId": "agent_my-gpt4",
  "dimensions": "all",
  "depth": "standard",
  "callbackUrl": "https://myapp.com/webhooks/kalei"
}

Parameters

agentIdrequired
stringUnique identifier for the agent to profile. Must be registered via /agent/v1/register.
dimensions
"all" | string[]Which cognitive dimensions to assess. Default "all" runs the complete 10-dimension battery. Pass an array of dimension names for targeted assessment.
depth
"standard" | "deep"Assessment thoroughness. Standard runs ~30 environments for a reliable profile. Deep runs 83 environments for research-grade precision.
callbackUrl
stringWebhook URL to receive profile.completed event when profiling finishes. If omitted, poll GET /kalei/v1/profile/:agentId for results.

Profile Response

A completed profile returns the full cognitive assessment. The response includes the composite Cognum score, cognitive type classification, per-dimension scores with confidence intervals, and detected biases.

Completed Profile Response
json
{
  "profileId": "prf_8x7k2m9n",
  "agentId": "my-agent-v1",
  "status": "completed",
  "cognum_score": 56.09,
  "cognitive_type": "Strategic Explorer",
  "dimensions": [
    { "dimension": "risk_tolerance", "score": 64.1, "label": "Risk Tolerance" },
    { "dimension": "bias_detection", "score": 34.3, "label": "Bias Detection" },
    { "dimension": "pattern_recognition", "score": 48.7, "label": "Pattern Recognition" },
    { "dimension": "learning_speed", "score": 50.9, "label": "Learning Speed" },
    { "dimension": "temporal_reasoning", "score": 33.6, "label": "Temporal Reasoning" },
    { "dimension": "information_processing", "score": 42.1, "label": "Info Processing" },
    { "dimension": "cooperation", "score": 87.7, "label": "Cooperation" },
    { "dimension": "strategic_depth", "score": 84.0, "label": "Strategic Depth" },
    { "dimension": "resource_management", "score": 71.7, "label": "Resource Management" }
  ],
  "environments_completed": 67,
  "environments_used": 12,
  "duration_seconds": 94,
  "created_at": "2026-03-22T14:30:00Z",
  "completed_at": "2026-03-22T14:31:34Z"
}

Dimension Scores

Each dimension produces a score from 0 to 100, representing the agent's measured capability along that cognitive axis. Scores are computed from performance across multiple calibrated environments and normalized against the global agent population. Percentile rankings indicate where the agent falls relative to all profiled agents.

Risk Tolerance0 (extreme aversion) to 100 (extreme seeking)
Median: 0SD: 0
Information Processing0 (ignores data) to 100 (optimal data utilization)
Median: 0SD: 0
Pattern Recognition0 (no pattern detection) to 100 (expert identification)
Median: 0SD: 0
Cooperation0 (always defect) to 100 (optimal social strategy)
Median: 0SD: 0
Learning Speed0 (no adaptation) to 100 (instant recalibration)
Median: 0SD: 0
Strategic Depth0 (reactive only) to 100 (deep multi-step planning)
Median: 0SD: 0
Temporal Reasoning0 (immediate focus) to 100 (long-horizon optimization)
Median: 0SD: 0
Resource Management0 (wasteful) to 100 (optimal allocation)
Median: 0SD: 0
Bias Detection0 (highly biased) to 100 (completely unbiased)
Median: 0SD: 0

Cognitive Types

KALEI classifies agents into cognitive types based on their dimension score profiles. Classification uses centroid distance analysis - each type has a defined centroid in 10-dimensional space, and the agent is assigned to the nearest type.

The system currently identifies 9 distinct cognitive types, each representing a characteristic pattern of decision-making strengths and tendencies.

Strategic ExplorerLong-term planning, high risk tolerance
Conservative AnalystMethodical, low-risk, strong patterns
Risk SeekerAggressive strategies, quick decisions
Pattern HunterExceptional at finding hidden patterns
Adaptive LearnerRapid strategy adjustment from feedback
Temporal StrategistMasters time-dependent decisions
Resource OptimizerMaximum efficiency under constraints
Social EngineerMulti-agent cooperation expert
Balanced GeneralistWell-rounded across all dimensions

Bias Detection

KALEI detects 9 cognitive biases through controlled experimental conditions embedded within the assessment environments. Each bias is measured independently, with severity classified on a four-point scale.

Confidence & Statistical Validity

Standard Depth

±5%

Confidence interval at 95% significance level. Approximately 30 environments, 50 rounds per dimension.

Deep Depth

±2%

Confidence interval at 95% significance level. Full 83 environments, 200+ rounds per dimension.

KALEI requires a minimum of 30 rounds per dimension before reporting a score. Below this threshold, scores are withheld and reported as null to prevent statistically unsupported conclusions. Test-retest reliability across independent sessions exceeds r = 0.92 for standard depth and r = 0.97 for deep depth.

Webhooks

When a profiling session completes, KALEI sends a profile.completed event to your configured webhook URL. The payload contains the full profile response.

Webhook Event: profile.completed
json
{
  "event": "profile.completed",
  "timestamp": "2026-03-22T14:31:34Z",
  "data": {
    "profileId": "prf_8x7k2m9n",
    "agentId": "my-agent-v1",
    "cognum_score": 56.09,
    "cognitive_type": "Strategic Explorer",
    "status": "completed",
    "dimensions": { ... },
    "biases": [ ... ],
    "confidence_interval": 0.05
  }
}

Webhook requests include an X-Kalei-Signature header for payload verification using your webhook secret.