Turn (Appraisal)

Bypass the automatic text-based cognitive appraisal and supply your own 6-dimensional appraisal vector directly. This is ideal for game events, sensor data, and any non-text interaction where you compute the appraisal yourself.

Process Appraisal Turn

POST /v1/turn/appraisal

Send a pre-computed appraisal vector to the emotion engine. Instead of the API interpreting a natural language event description, you provide the exact cognitive appraisal values. The engine then computes the emotional state change, updates body budget, soul stage, and returns the full result including prompt data for your LLM.

Headers

Header	Type	Required	Description
`Authorization`	`string`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	`string`	Yes	`application/json`

Request Body

Field	Type	Required	Description
`sessionId`	`string`	Yes	Session ID
`appraisal`	`object`	Yes	6-dimensional appraisal vector
`appraisal.goal_relevance`	`number`	Yes	How relevant is this event to the character's goals `[0, 1]`
`appraisal.goal_congruence`	`number`	Yes	Does the event help (+) or hinder (-) goals `[-1, 1]`
`appraisal.expectedness`	`number`	Yes	How expected was this event `[0, 1]`
`appraisal.controllability`	`number`	Yes	How much control the character has `[0, 1]`
`appraisal.agency`	`number`	Yes	Who caused the event: negative = external, positive = self `[-1, 1]`
`appraisal.norm_compatibility`	`number`	Yes	Alignment with character's values `[-1, 1]`
`context`	`string`	No	Description of what happened (for prompt_data enrichment)
`elapsedSeconds`	`number`	No	Time in seconds since last interaction

Appraisal Vector Ranges

Dimension	Range	Description
`goal_relevance`	`[0, 1]`	0 = irrelevant, 1 = highly relevant to the character's goals
`goal_congruence`	`[-1, 1]`	-1 = completely blocks goals, +1 = perfectly advances goals
`expectedness`	`[0, 1]`	0 = total surprise, 1 = fully anticipated
`controllability`	`[0, 1]`	0 = no control, 1 = full control over the situation
`agency`	`[-1, 1]`	-1 = purely external cause, +1 = purely self-caused
`norm_compatibility`	`[-1, 1]`	-1 = violates values, +1 = perfectly aligns with values

Response

The response is identical to the Process Turn endpoint:

Field	Type	Description
`appraisal`	`object`	The appraisal vector (echoed back)
`prediction_error`	`number`	Difference between expected and actual appraisal
`emotion_delta`	`object`	Change in emotional state `{ V, A, D }`
`new_emotion`	`object`	Updated emotional state `{ V, A, D }`
`emotion_intensity`	`number`	Overall intensity of the emotional state `[0, 1]`
`discrete_emotion`	`string`	Closest discrete emotion label (e.g., `"fear"`, `"anger"`)
`soul_stage`	`object`	Current developmental/narrative phase
`body_budget`	`object`	Energy and stress levels `{ energy, stress }`
`stage_transition`	`object\|null`	Soul stage transition info, if one occurred
`prompt_data`	`object`	Pre-built context for your LLM prompt

Use Cases

Game events — An enemy attack, a level-up, a treasure discovery
Sensor data — Physiological signals translated into appraisal dimensions
Non-text interactions — Button presses, gesture inputs, timer events
Custom appraisal logic — When your application has its own event interpretation

Examples

curl

An NPC getting hit by critical damage: high goal relevance, very negative goal congruence, low expectedness.

curl -X POST https://api.molroo.io/v1/turn/appraisal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session_xyz",
    "appraisal": {
      "goal_relevance": 0.95,
      "goal_congruence": -0.9,
      "expectedness": 0.15,
      "controllability": 0.1,
      "agency": -0.8,
      "norm_compatibility": -0.5
    },
    "context": "Player character took a critical hit from a dragon (850 damage, 20% HP remaining)",
    "elapsedSeconds": 3
  }'

JavaScript

const response = await fetch("https://api.molroo.io/v1/turn/appraisal", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sessionId: "session_xyz",
    appraisal: {
      goal_relevance: 0.95,
      goal_congruence: -0.9,
      expectedness: 0.15,
      controllability: 0.1,
      agency: -0.8,
      norm_compatibility: -0.5,
    },
    context:
      "Player character took a critical hit from a dragon (850 damage, 20% HP remaining)",
    elapsedSeconds: 3,
  }),
});
 
const result = await response.json();
// result.new_emotion = { V: -0.65, A: 0.82, D: -0.41 }
// result.discrete_emotion = "fear"
// result.emotion_intensity = 0.85
// result.body_budget = { energy: 0.55, stress: 0.78 }

Python

import requests
 
response = requests.post(
    "https://api.molroo.io/v1/turn/appraisal",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "sessionId": "session_xyz",
        "appraisal": {
            "goal_relevance": 0.95,
            "goal_congruence": -0.9,
            "expectedness": 0.15,
            "controllability": 0.1,
            "agency": -0.8,
            "norm_compatibility": -0.5,
        },
        "context": "Player character took a critical hit from a dragon (850 damage, 20% HP remaining)",
        "elapsedSeconds": 3,
    },
)
 
result = response.json()
print(result["discrete_emotion"])  # "fear"
print(result["new_emotion"])       # {"V": -0.65, "A": 0.82, "D": -0.41}
print(result["prompt_data"])       # Pre-built LLM context with emotional state

Example: Level Up (Positive Event)

A positive game event where the NPC levels up after a hard-fought battle:

{
  "sessionId": "session_xyz",
  "appraisal": {
    "goal_relevance": 0.8,
    "goal_congruence": 0.9,
    "expectedness": 0.6,
    "controllability": 0.7,
    "agency": 0.8,
    "norm_compatibility": 0.7
  },
  "context": "Character leveled up to level 15 after defeating the forest guardian"
}

This would produce a positive emotional shift (joy/pride) because the event is goal-congruent, self-caused (high agency), and controllable.

Errors

Code	Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`VALIDATION_ERROR`	400	Invalid appraisal values (out of range)
`NOT_FOUND`	404	Session not found
`RATE_LIMIT`	429	Too many requests

Turn (Appraisal)

On this page