Programmable SecondMind Directives#

SecondMind can return inspectable structured guidance instead of one opaque whisper. Developers control the output contract while Supafone continues to observe the call, infer the current belief state, and apply the confidence gate.

json

{
  "empathy_directive": "Slow down and acknowledge that the caller is worried.",
  "tactical_directive": "Confirm the preferred callback time before closing.",
  "surface_facts": ["The caller requested a callback after 5 PM."],
  "guardrails": ["Do not claim the callback is scheduled until a tool confirms it."],
  "language": "en",
  "confidence": 0.86,
  "kind": "mixed"
}

What Developers Control#

Control	Effect
`enabled`	Include or deterministically clear a field
`instructions`	Give field-specific generation requirements
`max_chars` / `maxChars`	Bound a directive string after generation
`max_items` / `maxItems`	Bound a fact or guardrail list
`item_max_chars` / `itemMaxChars`	Bound each list item
`language_mode` / `languageMode`	Follow the caller, trust the model, or force one language
`allowed_kinds` / `allowedKinds`	Suppress kinds the application does not accept
`confidence_threshold` / `confidenceThreshold`	Emit nothing below the configured evidence gate
`operator_guardrails` / `operatorGuardrails`	Add application-specific standing rules
transform callback	Revise or suppress the final directive in local SDK code

The contract is applied in the model prompt and enforced again in code. A model cannot ignore a disabled field, exceed a configured bound, or bypass the confidence and kind gates.

Python#

python

from supafone_labs import DirectiveContract, supercharge

brain = supercharge(
    my_agent,
    scenario="legal_intake",
    directive_contract=DirectiveContract(
        empathy_directive={
            "instructions": "Acknowledge emotion in one calm sentence.",
            "max_chars": 120,
        },
        tactical_directive={
            "instructions": "Name exactly one next operational action.",
            "max_chars": 140,
        },
        surface_facts={"max_items": 3},
        guardrails={"max_items": 4},
        language_mode="caller",
        confidence_threshold=0.8,
        operator_guardrails=[
            "Never claim a callback is booked until the scheduling tool confirms it."
        ],
    ),
)

For local code that needs final control, use a sync or async transform. Returning None suppresses the directive:

python

async def approve(directive, belief, state):
    if belief.intent == "unknown":
        return None
    return directive.model_copy(
        update={"tactical_directive": "Escalate this turn to the application router."}
    )

brain = supercharge(my_agent, directive_transform=approve)

TypeScript#

const directive = await supafone.whisperStructured(transcript, {
  directiveContract: {
    empathyDirective: {
      instructions: "Acknowledge emotion in one calm sentence.",
      maxChars: 120,
    },
    tacticalDirective: {
      instructions: "Name exactly one next operational action.",
      maxChars: 140,
    },
    surfaceFacts: { maxItems: 3 },
    guardrails: { maxItems: 4 },
    languageMode: "caller",
    confidenceThreshold: 0.8,
    operatorGuardrails: [
      "Never claim a callback is booked until the scheduling tool confirms it."
    ],
  },
  transform: (candidate) =>
    candidate.surface_facts.length ? candidate : null,
});

whisper() remains the backward-compatible one-string convenience method. whisperStructured() and its directive() alias return the structured object or null when guidance is not justified.

Safety Boundary#

Developer controls govern generated coaching. They do not erase platform or scenario safety requirements. Standing safety rules remain in the reasoning prompt even when generated guardrails are hidden, and a callback failure degrades to no guidance rather than affecting the live call.

View raw Markdown