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.

Run The UI¶

Create the local environment file and a Chainlit signing secret:

cd demo
cp .env.example .env
uv run --directory 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.

make run-chainlit

make run-litellm

make run-bifrost

make run-chainlit-local

Both modes apply pending Chainlit schema migrations before the UI starts. Open http://localhost:3002. See Docker Compose for container endpoints.

With LiteLLM selected, profile discovery reads each graph's description and features from the lgos-a and lgos-b catalog pass-throughs, keeps the corresponding prefix, and sends the qualified model to managed /v1/responses. With Bifrost selected, aggregate discovery finds each provider, catalog detail uses /openai_passthrough/v1 with x-model-provider, and inference uses native /openai/v1/responses with the same provider header. 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 pass-through base URL forwards GET /models and GET /models/{model} to LGOS unchanged; Chainlit therefore receives GraphConfig.description, features, and detailed client-settings schemas while all network traffic still terminates at LiteLLM.

The gateway selector owns routing; users configure only the gateway type and optional root URL.

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 file-input to process an attachment with the dedicated demo graph. Selecting Bifrost instead exposes lgos-a/file-input and its lgos-b equivalent. 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.

Runtime Settings¶

After a profile is selected, Chainlit:

1. Retrieves the detailed model through the configured OpenAI client and reads 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, and strings become text inputs. Other schema shapes are not rendered. The adapter checks only boolean/string types 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, 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-a/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.

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¶

Chainlit's PostgreSQL data layer stores users, threads, steps, and feedback. Opening a stored thread restores its role/content transcript 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 OpenAI user 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.

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

Interrupt Demo¶

Run the dedicated HITL UI:

DEMO_CHAINLIT_UI_FILE=hitl make run-chainlit-local

Initial requests need no interrupt metadata. The HITL 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. Each response is shown with Chainlit's native AskElementMessage and a small custom element. Choice buttons and the allowed free-text field submit one {resume: ...} value, so the client depends only on the standard tool-call batch, not the graph topology. See the shared interrupt walkthrough.

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

Streaming, Events, And Citations¶

Both bundled Chainlit clients use OpenAI Responses. In the general client's 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 a native TaskList, completing each prior task when the next status arrives and completing the list when the full response succeeds. Clicking Stop marks the active task as failed and closes the Responses stream; incomplete assistant text remains visible but is excluded from later model context. 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.

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 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.

Gateway settings:

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

Native Chainlit 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.

The demo requires Chainlit 2.11.1 or newer. Review Chainlit's migration guidance when updating it because the PostgreSQL schema is release-specific.

Production Notes¶

• Use OAuth or another real callback; mock mode provides no access control or user isolation.
• 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.
• Run lgos-chainlit-setup before starting or replacing workers.

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