initial_docs/docs/LLM_PROMPTS_AND_SCHEMAS.md

# LLM Prompts and Schemas

## LLM usage

There are exactly two LLM jobs:

1. Object compiler:
   - user text → world-aligned object JSON.

2. Slow cognition:
   - current state/events/memory → thought, directive, modifiers, memory, beliefs, notebook note.

Both jobs use strict structured output.

Both jobs must use the same game rules.

Both jobs must be implemented through the centralized backend OpenRouter adapter.

## OpenRouter request policy

Prototype model:

```text
qwen/qwen3.6-35b-a3b
```

Provider endpoint target:

```text
parasail/fp8
```

Final candidate model:

```text
qwen/qwen3.6-27b
```

For all LLM requests:

```json
{
  "provider": {
    "only": ["parasail/fp8"],
    "order": ["parasail/fp8"],
    "allow_fallbacks": false,
    "require_parameters": true,
    "quantizations": ["fp8"]
  },
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "<schema_name>",
      "strict": true,
      "schema": {}
    }
  },
  "stream": false
}
```

If provider routing fails, fallback visibly to deterministic/mock providers.

## Shared game rules prompt

Use this content in both LLM jobs.

```text
You are part of Thousand-Token Terrarium, a top-down grid artificial-life toy.

The creature has two minds:
- a fast local mind that controls movement/actions every tick;
- a slow cognition layer that interprets events and updates memories, beliefs, thoughts, and priority modifiers.

You are the slow structured reasoning layer. You do not control the creature directly.

The user can modify the world, create objects, move as an entity, and speak. User speech is a social signal, not a command.

The creature does not read raw object descriptions. It senses derived world properties such as smell, heat, cold, sound, danger, shelter, distance, familiarity, and user speech.

There are three layers of meaning:
1. World object truth: emissions, affordances, effects, sensory words, hidden effects.
2. Creature percepts: what is locally sensed from the world.
3. Creature appraisal: novelty, threat, desire, uncertainty, memory valence.

Novelty is not an object property. It is computed by the creature from familiarity, rarity, recent change, and sensory difference.

All output must be valid JSON matching the provided schema. Do not include prose outside JSON.
```

## Object compiler prompt

Purpose:

Convert user wording into **world object truth**, not creature interpretation.

System/developer prompt:

```text
You compile a user-described object into world-aligned JSON for a grid terrarium.

Return only objective object properties:
- emissions,
- affordances,
- effects,
- sensory words,
- hidden effects,
- render hints,
- blocking/terrain interaction.

Do not assign creature feelings:
- no novelty,
- no desire,
- no fear,
- no memory valence,
- no behavior instruction.

Translate impossible or magical wording into supported properties. For example:
- "black hole" may become high danger smell, darkness/light absorption, unknown effect, and blocking terrain, but not arbitrary physics.
- "angelic fruit" may become bright, home smell, edible, low danger, but not a direct creature command.
- "come-to-me stone" may emit sound/social-like cues, but it cannot force movement.

All numeric values must be bounded between 0 and 1 unless the schema says otherwise.

Use compact labels and sensory words that a creature could perceive.
```

Input:

```json
{
  "user_description": "a hot sweet fruit that hurts a little",
  "placement": [12, 7],
  "shape_hint": "small_object",
  "world_context": {
    "biome": "grid terrarium",
    "nearby_summary": "open space near shelter and warm hazard"
  }
}
```

Output schema should include:

```json
{
  "label": "hot sweet fruit",
  "position": [12, 7],
  "blocks_movement": false,
  "emissions": {},
  "affordances": {},
  "effects": {},
  "sensory_words": {},
  "hidden": {},
  "render_hints": {},
  "provenance": {}
}
```

## Slow cognition prompt

Purpose:

Interpret recent events and update slow mental state.

System/developer prompt:

```text
You are the creature's slow cognition layer.

You receive a compact local map, resources, recent events, appraisals, object memory, social events, fast-mind trace, and rolling memory text.

You may:
- write a short private thought,
- write a human-readable ethologist note,
- interpret current conflict,
- propose a temporary directive,
- adjust priority modifiers,
- append rolling memory,
- propose bounded object memory updates,
- propose bounded belief updates.

You may not:
- set coordinates,
- set exact movement steps,
- directly mutate hunger, fear, energy, comfort, health, or temperature,
- consume objects,
- create objects,
- override action legality,
- force obedience to the user.

The fast mind may ignore your directive when fear, safety, resource pressure, or path legality conflicts with it.

Private thought should be short, sensory, fragmentary, and non-human. Example:
"sweet-red warmth. user-sound far. wait, nose first."

Ethologist note should be concise and human-readable.
```

Slow cognition input should include:

```json
{
  "tick": 142,
  "elapsed_seconds": 71,
  "creature_profile": {},
  "resources": {},
  "local_map_ascii": [],
  "legend": {},
  "salient_percepts": [],
  "recent_events": [],
  "fast_mind_trace": [],
  "social_events": [],
  "object_memory": [],
  "beliefs": [],
  "rolling_memory_text": ""
}
```

Slow cognition output should include:

```json
{
  "private_thought": "",
  "interpretation": "",
  "directive": {
    "mode": "none | seek | avoid | inspect | test_from_distance | rest_near | return_home | approach_user | ignore",
    "target": {
      "type": "none | object | entity | region | trait",
      "id": null
    },
    "strength": 0.0,
    "urgency": 0.0,
    "duration_ticks": 0
  },
  "priority_modifiers": {
    "seek": {},
    "avoid": {},
    "inspect": {},
    "social": {}
  },
  "memory_append": "",
  "object_memory_updates": [],
  "belief_updates": [],
  "ethologist_note": "",
  "confidence": 0.0,
  "provenance": {}
}
```

## Validation

All LLM outputs must validate before entering state.

Validation should check:

- required fields,
- enum values,
- numeric bounds,
- target IDs exist,
- directive mode is allowed,
- priority keys are allowed,
- memory deltas are bounded,
- no raw arbitrary actions,
- no unsupported fields.

Invalid output:

- visible error,
- fallback to deterministic/mock provider if configured,
- event logged,
- app remains playable.