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.

The server-tool profile has fixed opt-in switches for lgos_package_version and web_search; advanced-graph has only the Web search Chat Settings switch and receives gateway MCP tools separately through its advertised capability. Chainlit knows the server-tool names and includes only selected tools in the native Responses tools array; it does not discover those names from model metadata. Package lookup uses a name-only custom declaration, while search uses {"type":"web_search"}. LGOS completes selected server tools inside the same Response, so Chainlit executes only returned function_call items. The advanced graph enters note review when the user asks to remember or save something, 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/chainlit

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

When starting components independently with LiteLLM, sync model metadata before using the UI. 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, 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 full model_info.lgos extension supplies descriptions, features, and client-settings schemas in one response. Selecting a profile rereads this endpoint 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 and uses the same credential as Responses and Files. 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. 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-a/file-input or lgos-b/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.

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, 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¶

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

DEMO_CHAINLIT_LOGIN_TYPE=oauth
CHAINLIT_URL=https://chat.example.com
DEMO_CHAINLIT_OAUTH_ISSUER=https://id.example.com
DEMO_CHAINLIT_OAUTH_CLIENT_AUTH_METHOD=client_secret_basic
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"
OPENAI_GATEWAY_TYPE=litellm
OPENAI_GATEWAY_BASE_URL=https://litellm.example.com
DEMO_GATEWAY_HOST_URL=https://litellm.example.com
OPENAI_GATEWAY_API_KEY=TO_BE_FILLED
DEMO_CHAINLIT_ENABLE_OAUTH_TOKEN_FORWARDING=false

DEMO_CHAINLIT_ENABLE_OAUTH_TOKEN_FORWARDING=true
DEMO_CHAINLIT_OAUTH_ENCRYPTION_KEYS='["YOUR_GENERATED_FERNET_KEY"]'
OAUTH_GENERIC_SCOPES="openid profile email groups offline_access llm:invoke"
OPENAI_GATEWAY_BASE_URL=https://litellm-sso.example.com
DEMO_GATEWAY_HOST_URL=https://litellm-sso.example.com

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-a/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 advanced-graph.

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 ledger validation, Chainlit persistence, pending-request protection, and batch continuation. The demo keeps only the LGOS lgos_interrupt name, the Responses request callback, the payload presentation, and the InterruptReview element. The workflow publishes a normal Chainlit message with one persisted custom element and immediately returns. The element collects one answer for every interrupt call in the current batch, then invokes a native Chainlit action callback through callAction. The callback reads the trusted model ID, Response ID, exact function calls, and expected element ID from message metadata; the browser sends only opaque step, element, and revision references plus the answers. One accepted action advances one Responses transition. A later interrupt updates the same form, while a terminal response marks the ledger complete and removes 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 advanced graph uses the same review UI for real note uploads after an explicit natural-language save request. The payload displays the exact note content and destination before approval. Knowledge citations stay in the answer as filenames and provider file IDs; the default S3 Files connection is not a bridge to the graph's configured vector service.

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

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

The demo requires Chainlit 2.12.0 or newer. Review Chainlit's current MCP and PostgreSQL guidance when updating because those native contracts are release-specific.

Production Notes¶

• Set DEMO_CHAINLIT_LOGIN_TYPE=oauth in production; mock login provides no access control or user isolation.
• Choose static-key or delegated gateway authorization explicitly with DEMO_CHAINLIT_ENABLE_OAUTH_TOKEN_FORWARDING.
• The trusted MCP gateway connection uses the same OPENAI_GATEWAY_API_KEY as Responses and Files. It is not registered when delegated token forwarding is enabled.
• 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.