Simulations¶

The Chatbot API supports text, uploaded-audio and realtime-audio roleplay. A simulation uses the learner and counterpart profiles, preserves conversation metadata in the existing chat collections, and can generate structured feedback after completion.

All endpoints are mounted below:

/chatbot/api/v1/simulation

They require the same API-key/client resolution as the v2 chatbot.

Generated scenario outcomes¶

The scenario's objectives are expected conversational outcomes. Each outcome states an observable action, agreement or result, including how any shared understanding is demonstrated. This demonstration belongs in the outcome itself, even when the associated evaluation criterion already describes it.

For example, replace "establish a shared understanding of the information needed for future handoffs" with "confirm together the information to include in future handoffs". Equivalent observable wording is valid; no additional objective or fixed phrase is required.

Text chat¶

POST /chatbot/api/v1/simulation/chat accepts JSON:

curl 'http://localhost:8000/chatbot/api/v1/simulation/chat' \
  --header 'X-API-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "userGuid": "learner-123",
    "counterpart_user_id": "manager-456",
    "simulation_type": "manager_feedback",
    "message": "Hello, I would like to discuss the project.",
    "locale": "en",
    "source": "Web",
    "conversationId": null,
    "sessionId": "session-123",
    "context": {"scenario": "quarterly review"}
  }'

userGuid also accepts user_id, user_guid and user_application_id as input aliases. conversationId continues an existing simulation; omitting it starts a new conversation. parentConversationId can link a new simulation to the conversation that created it.

{
  "conversationId": "simulation-conversation-123",
  "sessionId": "session-123",
  "message": "Hello, thank you for arranging this meeting...",
  "simulation_type": "manager_feedback",
  "is_simulation": true,
  "title": "Manager feedback practice",
  "title_simulation": "Manager feedback practice"
}

The message language is detected from learner-authored text. locale (or the legacy language alias) is only a fallback when detection is uncertain. The resolved language is explicitly injected into generation, so the roleplay stays in the language requested by the learner.

Uploaded audio¶

The same /chat endpoint accepts multipart/form-data. Supply file instead of message, plus user_id, counterpart_user_id and simulation_type. Speech-to-text runs first and the generated response is converted to MP3.

The audio response uses audio/mpeg and returns the identifiers in headers:

X-Conversation-Id: <conversation id>
X-Session-Id: <session id>
X-Simulation-Title: <title, when available>

Continuous Live audio¶

Connect to WS /chatbot/api/v1/simulation/ws/chat. Required query parameters are user_application_id, counterpart_user_id and simulation_type. conversation_id, JSON-encoded context and source are optional. A valid API key is required during the handshake. context.voice defaults to brise, a natural French voice with a feminine presentation. Use sillage for its masculine alternative, or explicitly select another supported Live voice. Voice changes require a new WebSocket session.

GPT-Live 1 provides continuous audio and captions using raw 24 kHz mono PCM16. The delegated reasoning backend resolves the OpenAI mini semantic profile. The server sends session.started with the conversation and Live session IDs. Browser control is limited to microphone audio, mute/unmute, playback accounting and graceful close; provider instructions and backend tools remain server-owned.

Live captions arrive as timestamped fragments. AIHub assembles a separate message for each speaker's turn within the session, updating its text under a stable message ID and preserving its original creation time. A gap greater than two seconds on that speaker's audio timeline starts a new turn; an intervening caption from the other speaker does not. This is an application heuristic, not a provider-supplied end-of-turn signal. Spaces and repeated words are retained. History pagination and the analysis minimum of three trainee messages now count these grouped turns. data.voiceTurn contains startMs, endMs, fragmentCount and delivery. Assistant captions describe generated speech, which may have been interrupted before playback. Wait for session.closed before requesting analysis so all received captions have been saved. Already-received captions are also drained on disconnect, provider failure or cancellation, within the existing persistence timeout. A database failure terminates the session instead of confirming successful finalization. The frontend must implement the Live voice protocol, including resampling, continuous playback and connection failure handling.

OPENAI_API_KEY is required. llm_realtime_model now selects gpt-live-1; there is no separate Live transcription selector. Uploaded-file audio continues to use llm_speech_to_text_model and llm_text_to_speech_model independently.

Analysis¶

POST /chatbot/api/v1/simulation/analyze accepts:

{
  "conversationId": "simulation-conversation-123",
  "sessionId": "session-123",
  "locale": "en"
}

The result contains a summary, overall score from 1 to 3, criterion scores, strengths, improvement areas, actionable tips and key moments. If the learner did not participate enough, simulation_incomplete is true, overall_score is 0, and the feedback collections are empty.

Summaries, strengths, improvement areas, tips and key-moment feedback address the learner directly. topics_not_covered may also use neutral factual statements, such as "No sensitive topic was discussed, so diplomacy could not be assessed." An unreached topic is not presented as a learner fault.

Analysis uses the full exchange to resolve clear references before identifying missing information. If a colleague asks for earlier notice of blockers and the learner replies "I will share them weekly", the subject and frequency are known. Feedback may suggest how to handle urgent blockers between updates or refine the format, but must not claim that no subject or timing was specified. A weekly frequency and an exact day are different levels of detail. Already supplied details remain consistent across feedback fields, and future commitments are not credited as completed actions. These rules apply to all five simulation types.

Missing evidence of execution or results after a future commitment is not an observed weakness and must not justify an improvement area or a lower score. The analysis evaluates the quality of the commitment and behavior visible during the exchange. Advice solely about putting a commitment into practice belongs in actionable_tips as implementation or consolidation. Improvement areas have no minimum count and remain empty when no gap is supported.

Improvement tips address supported gaps, while a brief consolidation or implementation tip may reinforce an observed strength or put an explicit commitment into practice. This is also allowed for a criterion scored Applying when the tip does not imply a deficiency. Scores are not lowered to justify such advice, and generic encouragement is not added to fill the list. A tip that depends on an unconfirmed agreement remains conditional.

Paraphrases preserve the meaning of commitments: communicating better does not imply communicating more, more often or sooner. Concrete refinements remain suggestions unless the learner actually committed to them.

A counterpart stating a need and the learner responding to it already form a dialogue about that need. Feedback may suggest confirming whether the proposed response meets the need, but must not describe that initial exchange as absent. For example, acknowledge the response to a request for earlier blocker reporting before suggesting a check that the proposed rhythm suits the colleague. A proposal or unilateral commitment does not establish mutual agreement. Advice that depends on an unconfirmed agreement remains explicitly conditional, for example: "If you agree on an update rhythm with your colleague, follow it and later ask whether it is working well." An earlier suggestion to seek confirmation does not make the rhythm already agreed. No particular tip or confirmation question is mandatory.

Future tense alone does not express this condition. Prefer "If you agree on a measure with your colleague, put it into practice" over "apply the measure you will have agreed on". This distinction concerns an unconfirmed future agreement; it does not mean that the latter wording claims an action has already occurred.

The same applies to a vague commitment: "What can I improve?" followed by a coordination request and "I will communicate better" establishes an initial exchange. Feedback recognizes it before suggesting a specific action or deeper discussion. It neither describes the conversation as one-way nor credits in-depth collaboration that the transcript does not show.

Each criterion is assessable only when the exchange shows the behavior in its definition. For example, cordiality during routine coordination feedback can support openness or relationship building, but does not establish diplomacy when that criterion concerns sensitive topics. Without a sensitive topic, Diplomacy receives N/A, not a default numeric score. Short exchanges can still support other scores; duration alone does not determine assessability.

Key moments quote the learner's actual words and reflect only supported strengths or gaps. Both positive and negative moments are not required: one meaningful quote may receive feedback that acknowledges a strength and suggests a refinement. Short exchanges may still contain a useful moment. Return an empty list when no meaningful moment can be grounded in a direct quote; never invent one for balance.

{
  "conversationId": "simulation-conversation-123",
  "sessionId": "session-123",
  "simulation_type": "manager_feedback",
  "simulation_incomplete": false,
  "summary": "The discussion remained clear and constructive.",
  "overall_score": 2,
  "scores": {"communication_clarity": 2},
  "strengths": ["Concrete examples were used."],
  "areas_for_improvement": ["Clarify the next step."],
  "actionable_tips": ["Conclude with an action and a deadline."],
  "key_moments": [
    {"moment": "I will share them weekly.", "feedback": "You propose a clear cadence. Clarify how you will flag urgent blockers between updates."}
  ]
}

Implementation map¶

• HTTP/WebSocket contracts: src/chatbot/simulation/router.py and schemas.py;
• Live relay: src/chatbot/simulation/live_session.py;
• conversation persistence and orchestration: src/chatbot/agentic/core/simulation_core.py;
• reusable generation/analysis logic: src/chatbot/agentic/tools/simulation_common.py.