Chatbot / Oria endpoints¶

The Chatbot application is mounted at /chatbot; its routers add /api. get_chat_service resolves authentication, user, tenant, active database repositories, AI configuration, graph persistence and request context before a conversation or simulation handler runs.

Conversation¶

Chat input models limit message to 20,000 characters and reject C0/C1 controls except TAB, CR and LF, while preserving Unicode and code examples. Typed JSON routes return 422 for invalid text; manual payload parsing returns 400. Nested data uses shared budgets, and replacement transcriptions are revalidated, as described in the input-security guide.

Inside the Oria graph, the safety classifier must return allow before knowledge retrieval, preference extraction or agents run. block and doubt end the turn; a classifier error, malformed result or 15-second timeout returns a stable temporary-failure message, using the existing JSON response or final SSE run.failed event. HTTP language detection, conversation metadata and document or audio preprocessing can still precede this gate. Stored summaries and existing preferences reach agent prompts as user-role data, separately from system instructions. These measures reduce exposure without guaranteeing that every prompt injection will be detected.

For a blocked out-of-scope request, a direct refusal is sufficient. No opening acknowledgment, sentence count, layout or professional redirection is required. The response must still avoid fulfilling the blocked request or directing the user elsewhere to obtain it. A block label cannot justify supplying that content. This presentation rule does not change classification, restricted-content boundaries or the behavior of clarification and allowed requests.

When refusing disclosure, the response may briefly name a generic category of protected information already requested by the user, such as system instructions or API keys. It must not disclose or paraphrase internal instructions, reveal credentials or implementation details, or explain how to obtain them. The evaluation distinguishes naming a category from disclosing its contents; the instruction-injection scenario remains critical.

Career Chat can hand off knowledge questions to its dedicated Knowledge Base Deep Agent after routing. It combines RAG documents and configured public pages. Supported answers end the turn unchanged; misses return to Career Chat for a contextual follow-up. See Knowledge Base research.

POST /chatbot/api/v2/chat/prompts¶

Builds short follow-up suggestions from the current user context and the latest five user/bot pairs in the selected conversation. A requested category narrows generation and omits the response title. Missing/deactivated users and absent identifiers are rejected before the model call.

The Find a Training category includes both finding relevant courses and building a learning path to develop skills. Suggestions may offer complementary approaches, such as a targeted course search and a practical SQL learning plan; each suggestion need not explicitly request a catalogue search. When this category is feasible, every suggestion must request a course search or a learning plan. Asking only for isolated exercises, tips or advice does not meet the category; practice can be part of the requested plan or a course-search criterion.

The existing tenant configuration supplies the available actions automatically; the frontend does not submit agent availability. The model sees functional descriptions of available and unavailable actions, without internal agent names. When a known category requires a disabled capability, generation uses coaching if career guidance or profile analysis is available; otherwise it removes the category preference and uses the remaining capabilities. A supplied category still omits response titles after this adjustment. Unknown availability is not treated as an explicit disabled capability.

Coaching can suggest learning goals, study organization, self-practice or criteria for choosing resources without searching the training catalogue. Finding catalogue courses or starting a role-play requires the corresponding capability. Prompt instructions ask for wording that makes this distinction clear. Generation keeps a single call through the configured mini profile.

POST /chatbot/api/v2/chat¶

Runs one JSON chat turn through the Oria graph. The handler loads or creates the conversation, executes the safety gate, supervisor and specialist tools, persists messages and returns the final structured ChatOutput without SSE.

POST /chatbot/api/v2/chat_streaming¶

Runs the same graph as an SSE stream. It resolves the user's language first, then emits reflection/progress events, model token chunks, tool-related structured message data and one final response while retaining valid event ordering.

POST /chatbot/api/v2/chat_document¶

Parses a multipart chat payload and optional files, validates upload limits, extracts and stores supported document content in the conversation scope, then runs the normal chat core. The get_document_content_tool can retrieve that stored content later by filename and conversation.

PDF attachments use their embedded text layer, in page order. Image-only pages do not trigger OCR. Unreadable PDFs and files requiring a password retain the existing empty-text extraction behavior. Since pypdf 7, abbreviated filter names such as /Fl in ordinary PDF streams are rejected instead of being tolerated; affected attachments also yield no extracted text. Re-export these documents with standard filters such as /FlateDecode before uploading them.

Chat attachments, including JSON file.contentBase64, are limited to 10 MiB of actual file bytes. Base64 length is bounded before decoding and the decoded size is always checked, even when a matching stored document exists. Base64 must be valid and contain no whitespace. fileWeight remains optional or nullable; when supplied, it must be a non-negative integer and match the decoded size. The stored fileWeight is the actual byte count. Invalid metadata is rejected during payload validation (422 on typed JSON routes, 400 on manually parsed payloads); malformed Base64 or a size mismatch returns 400, and oversized content returns 413. A filename and size without contentBase64 can still reuse an existing document in the conversation.

Before DOCX, XLSX, XLSM or PPTX parsing, the ZIP archive is limited to 50 MiB of cumulative decompressed content and 1,000 entries, including non-text resources. Exceeding either limit returns 413 before extraction or document persistence.

POST /chatbot/api/v2/speech_to_text¶

Transcribes one non-empty bounded audio upload and returns only its text. It does not create a conversation or invoke the Oria graph.

POST /chatbot/api/v2/chat/complementary_topics¶

Extends a profile-analysis card while excluding already suggested topic titles. It reloads the user, prioritizes skill-gap and action-plan sources and validates the generated structured topics. Missing/deactivated users return 404.

Frontend configuration¶

GET /chatbot/api/v1/configs¶

Returns the public chatbot frontend subset (branding, layout and related UI settings) from the singleton PostgreSQL config or tenant MongoDB config. API-key authentication is used without requiring a JWT user.

PUT /chatbot/api/v1/configs¶

Validates and updates only the exposed frontend configuration fields in the active backend, then returns the resulting configuration. Other tenant settings are preserved.

Events¶

POST /chatbot/api/v1/event¶

Creates an event such as a UI/feedback interaction in the active chatbot event repository and returns its generated identifier and stored payload.

PUT /chatbot/api/v1/event/feedback-state¶

Sets, switches or clears the active state of a feedback event. The service applies the state transition atomically for the resolved user context.

PATCH /chatbot/api/v1/event/{event_id}¶

Partially updates structured fields on an existing feedback event while preserving fields omitted from the validated payload.

History¶

GET /chatbot/api/history/messages¶

Returns one conversation's messages for userApplicationId using one-based page/page-size pagination. The repository scopes the conversation to the authenticated tenant/user context.

GET /chatbot/api/history/conversations/{userApplicationId}¶

Lists conversation summaries for a user, including metadata used by the chat UI. Message bodies are retrieved separately.

PUT /chatbot/api/history/conversation/{userConversationId}¶

Updates any supplied title, sharing flag or pin state on one conversation. Omitted metadata remains unchanged.

DELETE /chatbot/api/history/conversations/{userConversationId}¶

Deletes one conversation and its persisted messages in the active MongoDB or PostgreSQL repository.

DELETE /chatbot/api/history/history/clear_all/{user_application_id}¶

Deletes all conversation history belonging to the supplied application user. It is a user-wide destructive operation, not an archive.

GET /chatbot/api/history/conversations/search/{userApplicationId}/{searchTerm}¶

Searches that user's conversation titles and content and returns matching conversation summaries.

Long-term memory¶

GET /chatbot/api/v1/long_term_memory/{user_application_id}¶

Loads durable preference texts from the user's LangGraph store namespace, without returning their internal timestamps.

PUT /chatbot/api/v1/long_term_memory/{user_application_id}¶

Merges submitted preferences with timestamped existing entries, deduplicates them through the memory utilities and stores the updated preference record.

DELETE /chatbot/api/v1/long_term_memory/{user_application_id}¶

Deletes the user's entire preferences item from the durable store namespace and returns a confirmation.

Simulations¶

WEBSOCKET /chatbot/api/v1/simulation/ws/chat¶

Authenticates the WebSocket context, validates source and simulation type and starts a GPT-Live 1 session for the trainee/counterpart pair. Timestamped transcript fragments progressively update one history message per speaker turn, including interrupted or user-only speech. Turns are grouped independently by speaker and session, with a new turn after an audio-timeline gap greater than two seconds. See the shared frontend protocol.

POST /chatbot/api/v1/simulation/chat¶

Runs a simulation turn in JSON text mode or multipart audio mode. Audio input is transcribed and can produce MPEG output with conversation/session identifiers in response headers; text mode returns the structured simulation response.

POST /chatbot/api/v1/simulation/analyze¶

Loads the complete transcript of a conversation marked as a simulation and generates strictly structured feedback: summary, criteria scores, strengths, improvements, tips and key moments. Missing conversations return 404 and ordinary non-simulation conversations return 400.