runtime_contract.md

rolo-brain — runtime prompt contract

This document specifies the exact first-user-turn layout the model was trained on. If you are wiring rolo-brain into your own runtime, the assembled prompt should match this grammar; deviations move inference off the training distribution and reduce output quality.

You don't need this file if you're using ollama run interactively — the REPL sends each line as a plain user message, and Gemma's instruction-following keeps the conversation coherent. But the state-conditioned voice the fine-tune adds (mood, energy, animation state) only activates when the prompt includes the bracketed state header described below. This contract is for developers calling /api/chat from code who want the full conditioned behavior.

---

1. The contract in one sentence

There is no system role. Each inference call sends exactly one user message containing a bracketed state header, a blank line, and either the user's message (chat) or the literal sentinel <idle> (proactive speech).

---

2. First-user-turn grammar

After Ollama applies the chat template, the prompt fed to the model is:

<start_of_turn>user
<state_block>
<pet_state_block_if_present>

<user_message_or_idle_sentinel><end_of_turn>
<start_of_turn>model

The portion you assemble and put in messages[0].content is:

<state_block>
<pet_state_block_if_present>

<user_message_or_idle_sentinel>

Rules:

• <state_block> is required and follows the grammar in §3.
• <pet_state_block_if_present> is omitted on the chat channel and required on the speech channel. On chat, the state block is followed immediately by the blank-line separator.
• Exactly one blank line (two \n in a row) separates the header(s) from the message body, on both channels.
• <user_message_or_idle_sentinel> is the user's typed message verbatim on chat, or the literal string <idle> on speech (see §5).

An optional [Observation: …] line may appear between the pet-state block and the blank-line separator on the speech channel.

---

3. State header vocabulary

The state block has the form:

[Mood: <mood> | Energy: <energy> | Social: <social> | Time: <time>]

with an optional trailing | Hunger: <hunger> field. Field order is fixed. The separator is space-pipe-space.

Field	Accepted values
Mood	happy, content, neutral, low, sad. May carry a parenthetical sass modifier: sad (snarky), low (very snarky).
Energy	high, medium, low
Social	engaged, ok, lonely
Time	12-hour clock, e.g. 8:30 AM, 2:00 PM, 1:30 AM
Hunger	just ate or peckish. Omit the field entirely at neutral hunger.

Example state blocks:

[Mood: content | Energy: high | Social: ok | Time: 9:00 AM]
[Mood: sad (snarky) | Energy: low | Social: lonely | Time: 2:00 PM | Hunger: peckish]

Values outside this vocabulary won't raise an error, but the model hasn't seen them and output quality will drop.

---

4. Pet-state block (speech channel only)

Proactive-speech calls include a second bracketed line documenting Rolo's current animation state:

[State: <stem>]

The five accepted stems are:

Animation state	Stem
Idle	Rolo is sitting idle
Walking	Rolo is walking around
Sniffing food	Rolo is sniffing a file
Just ate	Rolo just finished eating and is satisfied
Food declined	Rolo was offered food but it was declined

The training corpus contains only these five stems on the speech channel. Other animation states (sleeping, dragging, mid-eating) are suppressed upstream and don't reach inference.

---

5. The idle sentinel

On the speech channel, the body of the user turn is the literal string:

<idle>

No quotes, no whitespace padding, no alternative spellings. This is the token sequence the model was trained to interpret as "no user message — say something appropriate to the current state."

---

6. Output expectations

• Length. Replies are 1–3 sentences. Training data was capped at 30 words per response; sampling uses num_predict=64, which leaves headroom for stop-token cleanup.
• No emoji. The training corpus was emoji-free.
• No lists. The bundled Modelfile stops on bullet/list markers (\n* , \n- , \n1. , \n2. ) as a safeguard. The model rarely emits them.
• No follow-up question loop. Rolo is a desktop pet, not an assistant — he reacts, comments, and stops.

Long, list-shaped, or assistant-like output usually indicates a prompt that violates §2 or §3 — most often, a system message that shouldn't be there.

---

7. Worked examples

Chat channel — typed user message

{
  "model": "hf.co/larawashington/rolo-brain",
  "messages": [
    {
      "role": "user",
      "content": "[Mood: content | Energy: medium | Social: ok | Time: 8:30 AM]\n\nmorning rolo"
    }
  ]
}

Note the \n\n between the state header and morning rolo — one blank line, two newlines.

Expected output: a short greeting in Rolo's voice, 1–2 sentences.

Speech channel — proactive <idle>

{
  "model": "hf.co/larawashington/rolo-brain",
  "messages": [
    {
      "role": "user",
      "content": "[Mood: content | Energy: medium | Social: ok | Time: 2:30 PM | Hunger: just ate]\n[State: Rolo is sitting idle]\n\n<idle>"
    }
  ]
}

Note: two bracketed lines separated by a single \n, then \n\n, then the literal <idle>.

Expected output: a short, in-character remark appropriate to the mood and state.

Speech channel — with perception observation

[Mood: low | Energy: low | Social: lonely | Time: 11:42 PM]
[State: Rolo is sitting idle]
[Observation: cursor has not moved in 12 minutes]

<idle>

Observations are short free-form clauses. They appeared in a minority of training rows, and the model handles their absence without issue.

---

8. Common mistakes

Mistake	Symptom
Adding a system role	Generic, list-prone, assistant-shaped replies
Hardcoding <IDLE>, [idle], idle, etc.	Model treats it as user content; replies go off-tone
Two blank lines between header and body	Output quality drop from a tokenization shift at the boundary
Missing the [State: …] line on speech	Replies lose grounding in Rolo's current animation
Using a mood word outside §3	Output looks fluent but is off-distribution
Sending emoji in the user message	Model may echo them and degrade voice

If output looks wrong, log the exact contents of messages[0].content and compare against the examples in §7.