Chainlit Client¶

The included Chainlit UI is an optional OpenAI client of LGOS. It does not add routes or change the server contract.

The Chainlit project intentionally does not install or import the langgraph-openai-serve Python package. It demonstrates that a UI integration needs only the OpenAI wire contract. Its local declarations cover only LGOS model metadata and link to their authoritative source files.

Each server tool a profile advertises in lgos.server_tools becomes an opt-in Chat Settings switch labelled from its name: server-tool gets Package version and Web search, while deep-research gets only Web search and receives gateway MCP tools separately through its advertised capability. Chainlit includes only selected tools in the native Responses tools array, and offers display_file only to profiles that list it in lgos.client_tools. A custom tool uses a name-only declaration, while search uses {"type":"web_search"}. LGOS completes selected server tools inside the same Response, so Chainlit executes only returned function_call items. deep-research pauses for plan review when a question needs research, not through a UI setting. Native URL-citation annotations become clickable Chainlit source elements containing Markdown links, without changing the replayed answer text.

Run The UI¶

Create the local environment file and a Chainlit signing secret:

cp demo/.env.example demo/.env
uv run --directory demo/ui/chainlit_ui --locked chainlit create-secret

Put the generated value in CHAINLIT_AUTH_SECRET. Configure Chainlit's native element storage with BUCKET_NAME, APP_AWS_*, and DEV_AWS_ENDPOINT. Separately configure the central Files API with DEMO_API_FILES_BUCKET, DEMO_API_FILES_S3_ENDPOINT, and DEMO_API_FILES_AWS_*. Replace every example value before starting the UI; neither service reads the other's S3 settings.

just demo/compose

just demo/up lgos-litellm

just demo/up lgos-bifrost

just demo/up lgos-postgres-mcp

just demo/chainlit --port 5000

Both modes apply pending Chainlit schema migrations when the UI starts. See Docker Compose for container endpoints.

When starting components independently, sync model metadata before using the UI: model sync for LiteLLM or just demo/sync-bifrost for Bifrost. The full-stack Compose targets do this automatically. Profile discovery and settings read GET /model/info with the current gateway credential. Entries with model_info.lgos become profiles; model_name is sent unchanged to managed /v1/responses. There are no provider allowlists, implicit prefixes, or per-provider catalog URLs. With Bifrost selected, native /v1/models supplies provider-qualified IDs and the full extension as a JSON string in additional_attributes.lgos. Catalog sync publishes that metadata automatically during startup. Inference sends the catalog ID unchanged to native /openai/v1/responses. The demo API owns the descriptions and capabilities. Chainlit keeps the Responses model usable for plain text but marks it as Limited functionality when an endpoint omits or strips them.

LiteLLM's managed /v1/models response contains only the standard model fields, so it is not the UI catalog. The full model_info.lgos extension supplies descriptions, features, and client-settings schemas in one response. Selecting a profile rereads the selected gateway's native catalog so settings use current metadata and model permissions. Errors do not trigger a fallback to LGOS.

The gateway selector owns routing; users explicitly configure its type and root URL. Browser login and gateway authorization are separate settings: mock and OAuth login can use a static key, while OAuth can optionally delegate the signed-in user's access token.

Gateway MCP¶

The backend derives one trusted /mcp connection from the selected gateway root. The browser receives no URL or bearer token, and user-provided servers remain disabled. After you click Connect, Chainlit owns the session and discovers the tools authorized by the gateway. It sends them only when the selected model advertises the mcp_tools capability. Every MCP request carries the same credential as Responses and Files, resolved at that moment: OPENAI_GATEWAY_API_KEY, or the signed-in user's refreshed access token in delegated mode. mcp-postgres applies a fixed report allowlist at the API boundary, while general-purpose graphs can use the gateway-authorized tool catalog without knowing which MCP servers provide it.

The current database example is PostgreSQL Through Native MCP; see it for the complete request flow, read-only controls, and connection steps. Chainlit's official MCP guide documents the underlying lifecycle.

File Attachments¶

The UI uploads every file attached to the current user message through client.files.create(..., purpose="user_data"). It then replaces the attachment with a native Responses input_file part containing the returned file_id. Files requests use the selected gateway's normal /v1 route. Bifrost assigns them to its fixed lgos-files provider, while LiteLLM assigns them to its configured litellm_proxy Files provider. Responses continue to use the selected model provider. The demo therefore has one file namespace shared by both inference providers.

The attachment button appears only for profiles that advertise file_inputs and accepts up to five files of 10 MiB each per message. Select lgos/file-input to process an attachment with the dedicated demo graph. If an OpenAI API caller sends a native file part to a general graph such as simple-graph, LGOS preserves it, but that graph does not resolve its central ID.

Chainlit's native S3 persistence remains responsible for restoring UI elements. The OpenAI Files upload is the separate inference contract; the adapter does not wait for a Chainlit persistence URL or put one in file_data. See Accept And Display Files.

Voice¶

Chainlit's native microphone button streams raw audio to the app; Chainlit has no speech-to-text or text-to-speech of its own. The app shows the microphone only when DEMO_AUDIO_STT_MODEL is set and adds a Read aloud button under each completed answer only when DEMO_AUDIO_TTS_MODEL is set. Both features come from chainlit-utils; the app supplies the gateway client, models, and voice.

The microphone dictates like Open WebUI's:

1. Click the microphone or press P, speak, then stop the recording. Chainlit does not stop on silence.
2. The app wraps the recording in a WAV file and sends it to the selected gateway's /v1/audio/transcriptions route.
3. The transcript appears in the chat input. Edit it and press Enter to send it like a typed message.

Chainlit has no API for its chat input. The app therefore sends the transcript with cl.send_window_message, and chainlit-utils' dictation.js, loaded through the native custom_js setting, writes it into the #chat-input textarea. Recheck that script after Chainlit upgrades.

Read aloud also works like Open WebUI's:

• The button is the chainlit-utils SpeechButton custom element, built from Chainlit's own button and tooltip components. It sends only the answer's message ID and a sentence number through callAction, so the browser cannot request arbitrary speech.
• The backend removes emojis and Markdown formatting, splits the answer into sentences with Open WebUI's rules, and sends one sentence to /v1/audio/speech. The browser plays the sentences in order, so playback starts after the first one and long answers stay under the speech input limit. Neither gateway streams speech as a normal audio response: LiteLLM returns the finished clip, and Bifrost streams only stream_format: "sse" events.
• Speech is synthesized only when the button is clicked. Replays reuse the sentences already fetched on that page.

Speech uses the same gateway credential as Responses, including a delegated OAuth token, and LGOS receives and returns only text. See Stack Settings for the speech settings. Chainlit names a thread that starts with a recording audio, even when the dictated text is discarded.

Runtime Settings¶

After a profile is selected, Chainlit:

1. Reads the selected model's gateway metadata through the OpenAI client and uses lgos.client_settings.
2. Renders supported JSON Schema properties as Chainlit Chat Settings.
3. Restores saved values that still match the supported widget type or choice.
4. Compares the selected values with the advertised defaults.
5. Sends changed values as JSON text in metadata.lgos_settings on every Responses request.

Booleans become switches, inline string enums become selects, strings become text inputs, and integers become sliders when they declare both minimum and maximum, or number inputs otherwise. Other schema shapes are not rendered. Chainlit stores number widget values as floats, so whole numbers are sent as integers. The adapter checks only these types, integer bounds, and select membership when restoring the UI; it does not interpret general JSON Schema constraints. LGOS remains the validation authority. If the required LGOS model extension is unavailable, Chainlit hides the controls, uses server defaults, keeps the thread's saved selections for when the metadata returns, and shows a transient Limited functionality warning after selection. Profile discovery itself stays list-only because descriptions and features arrive with the list response.

Runtime settings discovered from lgos/simple-graph and rendered as native Chainlit controls.

The same panel includes a Chainlit-owned Stream response switch for every profile. It defaults to enabled and selects responses.stream or responses.create; it is not included in lgos_settings. With streaming disabled, Chainlit waits for the complete response and sends the answer once. The switch also applies to the answer that follows a human review.

Models advertising background also receive an opt-in Run in background switch. Chainlit uses non-streaming create/retrieve polling, renders lifecycle states in its task list, and requests cancellation when the turn stops. Interrupt answers follow the same switch. This client-owned switch is not included in lgos_settings.

Chainlit may restore UI selections with a saved thread, but LGOS does not persist runtime settings. The adapter resends non-default values for every request that needs them. The underlying contract is documented in LangGraph Runtime Settings.

Persistence And Login¶

Reusable OIDC routes, request credential isolation, and encrypted token storage come from chainlit-utils. Demo-specific settings and login policy are grouped in demo/ui/chainlit_ui/src/lgos_chainlit/auth.py, with wiring tests in demo/ui/chainlit_ui/tests/test_auth.py. Reusable browser-flow and token-storage tests live in chainlit-utils. See the Chainlit project README for the module layout, editable utility development, and targeted test commands, and the chainlit-utils repository for its reusable integration suite.

Chainlit's PostgreSQL data layer stores users, threads, steps, and feedback. Opening a stored thread restores its transcript, with answered reviews as their function calls and outputs, and continues with the same login identity. The adapter also sends Chainlit's stable thread ID as metadata.conversation_id on every Responses request, allowing Langfuse to group the thread's per-request traces into one session. The persistent-plot-agent demo also combines that value with the authenticated safety_identifier to scope its LangGraph chart document. The transcript remains owned and resent by Chainlit; no chat history is added to LGOS. See the persistent plot agent ownership flow for the API Store, Chainlit PostgreSQL, and S3 boundaries.

The demo's chainlit.yml sets the first row. just demo/compose --sso adds the SSO overlay, which sets the last row. Outside Compose, such as with just demo/chainlit, Chainlit reads DEMO_CHAINLIT_LOGIN_TYPE and DEMO_CHAINLIT_ENABLE_OAUTH_TOKEN_FORWARDING from its environment, which also allows the middle row.

DEMO_SSO_ISSUER=https://id.example.com
CHAINLIT_URL=https://chat.example.com
DEMO_CHAINLIT_OAUTH_CLIENT_AUTH_METHOD=client_secret_basic
DEMO_CHAINLIT_OAUTH_ENCRYPTION_KEYS='["YOUR_GENERATED_FERNET_KEY"]'
OAUTH_GENERIC_CLIENT_ID=YOUR_CLIENT_ID
OAUTH_GENERIC_CLIENT_SECRET=YOUR_CLIENT_SECRET
OAUTH_GENERIC_NAME=generic
OAUTH_GENERIC_SCOPES="openid profile email groups offline_access llm:invoke"

uv run python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'

Browser login is separate from bearer-token protection for the LGOS /v1 API. See Authentication.

Interrupt Demo¶

Select lgos/interruptible-approval in the normal Chainlit profile menu, then send Refund order ORDER-123 for the customer. The same UI also handles interrupts returned by other profiles, including deep-research.

Initial requests need no interrupt metadata. The client implements the Responses interrupt continuation: it stores the paused Response ID, asks for every call in the batch, submits only matching function_call_output items, and repeats when the graph pauses again. The chainlit-utils HitlWorkflow owns the review ledger, Chainlit persistence, pending-request protection, and batch continuation, and its HumanReview element renders the form. The demo keeps only the LGOS lgos_interrupt name, the Responses request callback, and the conversion of each interrupt payload into a review prompt with its choices. The prompt is the payload's question; graphs write their details into it, and other payload fields are data for API clients that the form does not display.

Each pause posts a normal Chainlit message, below any answer text the graph produced first, with one persisted custom element, and returns. The element collects one answer for every call in the batch and invokes a native Chainlit action callback through callAction. The browser sends only opaque step, element, and revision references plus the answers; the callback reads the model ID, Response ID, and exact calls from the message's ledger. It records the answers and replies at once, and the resumed graph then runs like a chat message, with Chainlit's running state and Stop. Like Open WebUI's answered card, an answered review stays in the conversation without its form and records the decision, such as Answered: approve. A later pause asks in a new message.

Cancel closes the review without resuming the graph, as Open WebUI's does: the message records Cancelled., later requests replay nothing of it, and the paused run waits for the demo API's expiry. Until a review is answered or cancelled, a new message asks the user to do one or the other.

Any other response finishes the turn like any other: the demo runs client function calls such as MCP tools or display_file and requests the answer with their results. The resumed run has already finished, so those requests start from the conversation, and files attached to the reviewed turn are not sent again. Like any stateless Responses transcript, later requests replay each answered review in place as its exact lgos_interrupt calls and answers; the review message's own text stays out, because the calls carry it. The client therefore depends only on the standard tool-call batch, not the graph topology. See the shared interrupt walkthrough and the concise design rationale.

The deep-research graph uses the same review UI for its research plan. The review message shows the plan, the form offers Start research and Answer now, and a custom response edits the plan.

Chainlit renders the LangGraph interrupt as native choices with an optional custom response field.

Streaming, Events, And Citations¶

The bundled Chainlit client uses OpenAI Responses. In streaming mode, the SDK stream manager owns event accumulation and supplies the terminal Response; the adapter streams answer text into the assistant message. Messages without the optional phase field are also treated as answers. It maps completed phase="commentary" items to the display selected by DEMO_CHAINLIT_STATUS_DISPLAY:

The step stays collapsed by default and keeps its history in the expanded content. The task list completes the previous task when the next status arrives. Both displays finish when the turn succeeds or pauses for human review. Clicking Stop, a failed request, or an incomplete response marks the active status as failed. Statuses stay out of the assistant answer and later model context. Background response polling uses the same display setting. Restart Chainlit after changing it. The bundled [UI] cot = "tool_call" configuration makes steps visible; custom configurations must use "tool_call" or "full".

Clicking Stop also closes the Responses stream. The answer text shown so far stays visible and in later model context; Chainlit's "Task manually stopped." notice does not. Both streaming and non-streaming requests require a completed Response before displaying files or accepting a successful turn. Failed interrupt resumes leave the saved continuation intact.

Native refusal text is displayed as the assistant's explanation. Incomplete responses report their native reason, retain any already streamed text for the user, and do not execute client functions. Failure and incomplete events are handled directly because the SDK's final-response helper requires completion.

Transcript replay labels assistant answers as final_answer and preserves explicit phase values, following OpenAI's assistant phase guidance.

The persistent plot graph returns a standard display_file function call. Chainlit downloads the Plotly JSON through the OpenAI Files API, reconstructs the figure with plotly.io.from_json, and persists a native Plotly element with interactive hover, zoom, and legend controls. It returns the matching function_call_output before requesting the final answer. Image files still use the native Image element. Each continuation of a new turn retains the original input, including instructions and file references, then appends the complete Response output and matching tool results. Streaming and non-streaming modes retain final-answer text from every call in that exchange and exclude commentary from the answer. The official data layer stores the element in the configured S3-compatible bucket, so it returns with the thread.

The UI renders Markdown links, images, and inline citation markers from assistant content. Shared prompts and graph behavior are documented under Events And Citations and Persistent Plot Agent. A schema-normalizing proxy must preserve standard Responses items and events.

Settings Reference¶

Use .env.example for demo environment values. The tables below explain their roles, not their defaults.

Shared gateway settings are documented in Stack Settings. Chainlit-specific settings:

See the bundled Bifrost gateway for the Compose endpoint and adapter behavior.

Unprefixed Chainlit and OIDC integration settings:

The element bucket must allow browser CORS GET and HEAD requests from the Chainlit origin. CORS only permits the cross-origin response; the object still requires Chainlit's time-limited presigned URL. See Amazon S3's CORS guide.

Review Chainlit's current MCP and PostgreSQL guidance when updating Chainlit because those native contracts are release-specific.

Production Notes¶

• Use OAuth login in production, as just demo/compose --sso does; mock login provides no access control or user isolation.
• Choose static-key or delegated gateway authorization explicitly with DEMO_CHAINLIT_ENABLE_OAUTH_TOKEN_FORWARDING when Chainlit runs outside the demo Compose stack.
• The gateway MCP connection uses the same credential as Responses and Files: the static key, or each user's delegated token.
• Keep OAuth, signing, and object-storage secrets outside source control.
• Restrict allow_origins to the deployed HTTPS origin.
• Configure session affinity for multiple UI workers and object storage for native file and chart persistence. File-capable profiles enable attachments.
• Route traffic to a new worker only after its health check passes; the endpoint answers once startup migrations finish.

See Chainlit's documentation for password callbacks, OAuth, PostgreSQL persistence, and deployment.