Instructions and uncertainties

How Spectron captures behavioural directives and tracks ambiguous or contradictory information.

Not everything in a turn is a fact about the world. Some statements tell the agent how to behave; others cannot be interpreted confidently. Spectron stores these as instructions and uncertainties — separate from ordinary attributes.

Instructions

An instruction is a persistent behavioural directive extracted from conversation:

“Always respond in bullet points.”
“Never use technical jargon.”
“From now on, label sarcasm when you detect it.”
“Keep responses under three sentences.”

Instructions are active constraints the agent should honour on subsequent turns within the relevant scope, not one-off preferences buried in an attribute.

Revoking instructions

When a user reverses a directive (“stop using bullet points”), Spectron deactivates the matching instruction rather than deleting it. History of what was asked — and when it was revoked — remains available for audit.

Using instructions in your agent

Active instructions appear in GET /profile ( instructions section) and POST /state. Fetch a profile before assembling a system prompt:

GET /api/v1/{context_id}/profile?scope[org]=acme&scope[user]=alice

{
  "instructions": [
    {
      "label": "Bullet-point responses",
      "description": "Always respond using bullet points, never flowing prose"
    }
  ]
}

See Profiles for the full profile shape.

Uncertainties

An uncertainty is recorded when extraction cannot commit to a single interpretation. The pipeline stores what was ambiguous and why, instead of guessing.

Common triggers:

A statement followed by a contradictory correction (“I'm CEO — well, co-CEO, it's complicated”)
Ambiguous references when several entities are in scope
A claim that contradicts existing memory with no clear winner
Temporal references that cannot be resolved to a date
Sarcasm or humour that may or may not contain genuine information

How uncertainties resolve

A later turn that clarifies the topic can resolve an open uncertainty automatically during extraction. Until then, the uncertainty stays visible so the agent can ask a follow-up question when appropriate.

Open uncertainties appear in POST /state under unknowns:

{
  "unknowns": [
    {
      "about": "job title",
      "reason": "User joked about being CEO, then appeared to correct themselves",
      "resolved": false
    }
  ]
}

Uncertainties and partial extractions

Spectron may still write a tentative attribute when extraction is partial, linked to the same turn as the uncertainty. Default current-state queries include it; applications that need higher confidence can treat attributes with open uncertainties on their source turn as lower trust until resolved.