Skip to content
Documentation

Response shape

SotsAI responses are behavioral reasoning artifacts.

They are not final user-facing messages.

Your LLM (or orchestration layer) is expected to interpret, filter, and transform this output into a response that makes sense for your users.

High-level structure

Section titled “High-level structure”

A typical SotsAI response looks like this:

{
  "status": "ok",
  "metadata": {
    "personalization_level": "full",
    "strength_score": 95
  },
  "content": {
    "..." <-- behavioral reasoning layers
  }
}

At a high level:

  • status confirms request success
  • metadata provides diagnostic signals
  • content contains the behavioral reasoning output

Only content is meant to inform downstream reasoning.

Important design principle

Section titled “Important design principle”

SotsAI outputs reasoning material, not prose.

You should not:

  • render this object directly to end users
  • map fields 1:1 to UI components
  • treat the response as a deterministic template
  • assume all fields are stable or mandatory

You should:

  • let your LLM interpret this object
  • decide what to surface, summarize, or ignore
  • combine it with your own generation logic

Behavioral reasoning layers

Section titled “Behavioral reasoning layers”

Inside content, SotsAI exposes several conceptual layers.

Each layer answers a different reasoning question your LLM needs.

Profile lenses

Section titled “Profile lenses”
"user_profile_lens": { ... }
"interlocutor_profile_lens": { ... }

These describe how each person tends to:

  • communicate
  • make decisions
  • react under pressure
  • interpret messages

Use these lenses to:

  • adapt tone and framing
  • choose wording intensity
  • anticipate sensitivity points

If only one profile is present, reasoning focuses on self-adjustment. If two profiles are present, reasoning includes interpersonal adaptation.

Dynamics lens

Section titled “Dynamics lens”
"dynamics_lens": {
  "friction_axes": [ ... ],
  "synergy_axes": [ ... ]
}

This layer explains why communication may be difficult or easy between two people.

It highlights:

  • where friction is likely to occur
  • where natural alignment exists
  • the direction and intensity of those dynamics

Use this to:

  • decide whether to emphasize alignment or friction in your response
  • anticipate resistance
  • explain misunderstandings
  • justify adaptation strategies internally

Behavioral levers

Section titled “Behavioral levers”
"behavioral_levers": [ ... ]

This is the most actionable layer.

Behavioral levers describe:

  • what to change in communication
  • why that change matters
  • what effect it is intended to have

Your LLM can:

  • translate these into concrete advice
  • prioritize a subset
  • rephrase them into natural language guidance

Risk patterns (if ignored)

Section titled “Risk patterns (if ignored)”
"risk_patterns_if_ignored": [ ... ]

This layer describes failure modes.

It answers:

“What is likely to go wrong if the user does not adapt?”

These are not predictions, but likely patterns observed when similar dynamics are ignored.

Use this to:

  • add warnings or guardrails
  • explain consequences
  • increase urgency or clarity in guidance

Reflection handles (optional)

Section titled “Reflection handles (optional)”
"reflection_handles": [ ... ]

These are optional introspective prompts.

They are useful if your product:

  • encourages self-reflection
  • supports coaching-like interactions
  • surfaces internal questions instead of directives

They can be ignored in more directive or automated workflows.

Metadata signals

Section titled “Metadata signals”
"metadata": {
  "personalization_level": "full",
  "strength_score": 95
}

Metadata is diagnostic, not instructional.

Typical uses:

  • confirm whether full psychometric reasoning was applied
  • measure confidence or richness of reasoning
  • drive internal logging or analytics

You generally should not surface metadata directly to users.

Stability guarantees

Section titled “Stability guarantees”

SotsAI guarantees:

  • conceptual stability of reasoning layers
  • semantic intent of each section

SotsAI does not guarantee:

  • strict field-level stability
  • identical schemas across versions
  • suitability for direct UI rendering

Design your integration to be:

  • resilient to missing fields
  • tolerant of new fields
  • driven by intent, not structure
Section titled “Recommended usage pattern”
  1. Call SotsAI
  2. Extract relevant reasoning layers
  3. Inject them into your LLM prompt or decision logic
  4. Let your LLM generate the final user-facing response

If you want concrete production patterns (retry logic, caching, fallback strategies, pipeline placement), see:

→ Integration Guides → Tool calling patterns