Self-Contained Demo Stack¶

The demo/ directory is a portable example distribution built around langgraph-openai-serve. It contains independently locked applications, client integrations, gateway configuration, and a complete Compose stack.

Watch the demo showcase

Watch the complete demo showcase to see the demo stack in action.

Package and demo have different owners

The PyPI package provides the OpenAI-compatible server integration. It contains no built-in graph, UI, gateway, database, or runnable application. Everything described in this section belongs to demo/ and can be copied or operated independently of the package source checkout with published images. The development Compose override intentionally uses the parent checkout as an editable API dependency.

Run the API

Start PostgreSQL and call the example graphs through an OpenAI client.

Run the API
Run the Files API

Start the independent OpenAI Files service backed by S3-compatible storage.

Run the Files API
Understand the architecture

See service ownership, request routing, and persistence boundaries.

Demo architecture
Explore the graphs

Compare schema adapters, RAG, citations, stream-event filtering, file output, subgraphs, and HITL.

Example graphs
Run the complete stack

Use published images or build the demo applications with an editable LGOS checkout.

Docker Compose
Use Chainlit

Responses, model discovery, Chat Settings, persistence, login, and HITL.

Use Chainlit
Use Open WebUI

A Responses manifold Pipe with generated graph-specific Workspace Models.

Use Open WebUI
Route through Bifrost

Select the native UI inference path and inspect its pinned compatibility boundary.

Bifrost gateway
:material-gateway:{ .lg .middle } Use the LiteLLM edge

Select the managed UI inference route, native model metadata, and compatibility tests.

LiteLLM in Compose
Observe the stack

Add the optional Collector overlay without changing the LGOS package. For the surrounding self-hosted infrastructure, use the separate reference page.

OpenTelemetry overlay

Self-hosted service references

Components¶

Component	Demo-owned responsibility	Distribution
Demo APIs	Two FastAPI graph services that may expose different graph sets	One independent uv project; Compose runs the `lgos-demo-api` image twice
Files API	Shared OpenAI file namespace and S3 persistence	Independent uv project and `lgos-files-api` image
Chainlit	Persistent Responses client, native MCP sessions, login, settings UI, file display, and HITL UI	Independent uv project and `lgos-chainlit` image
Open WebUI	Responses manifold, native MCP tools, and dynamic generated Workspace Models	Host-run locked sync project plus the unchanged pinned official image
Bifrost	Shared model catalog plus provider-selected native OpenAI routing	Compose configuration with the official image
LiteLLM	Managed UI inference and native `/model/info` metadata	Pinned public `homeserver-litellm` image and Compose configuration
DBHub	Six fixed read-only reports over curated live-data PostgreSQL views	Pinned official image and demo-owned TOML configuration
PostgreSQL	Thread-scoped graph data, pending interrupts, cross-worker interrupt coordination, and Chainlit persistence	Official image with a demo-owned bind directory
S3-compatible storage	Files API objects and separate Chainlit element bodies	External endpoint with independently configured buckets

Only the graph API project imports langgraph-openai-serve. The Files API implements its independent OpenAI Files contract without importing LGOS. Chainlit and Open WebUI exercise the graph API's OpenAI wire contract without importing the package. OPENAI_GATEWAY_TYPE=litellm|bifrost selects their shared edge. Responses and Files use its normal managed/native routes. LiteLLM metadata comes from /model/info after model sync; Bifrost uses catalog-detail pass-through.

Pinned managed-routing limitations

The bundled Bifrost native Responses route preserves phase, commentary, file-input, continuation, and store: false contracts; normalized model-detail and error metadata remain strict expected failures. Its raw pass-through route preserves successful-request contracts, while virtual-key governance rejects the unknown-model error case before pass-through. The bundled homeserver-litellm image preserves native streaming and commentary. Standard error metadata remains rewritten. Direct LGOS and Bifrost's raw route remain protocol references. The UIs use the selected gateway's normal inference route and accept that route's documented limitations; see Docker Compose and Bifrost Gateway for the precise boundaries.

Client Capabilities¶

Demo client	File input	MCP	Runtime settings	Interrupts	UI feedback	Citations
Chainlit	Uploads attachments to the central Files API	Per-session trusted native Streamable HTTP connection	Renders supported discovered fields	Native choices and free-text input with a durable continuation record	Native status and persisted image elements	Markdown content
Open WebUI generated models	Uploads attachments to the central Files API	One synchronized gateway connection attached from discovered `mcp_tools` metadata	Renders supported discovered fields as Chat Variables	Persisted native `ask_user` card with LGOS continuation	Native status and persisted file events	Native source events and Markdown

Both clients still expose limited-functionality models when LGOS metadata is missing; see their client-specific guides for that behavior.

Ordinary graph conversations work through an OpenAI SDK without a demo adapter. An interrupt uses standard Responses function calls, but a client application must recognize lgos_interrupt, collect human answers, and return each call ID in a function_call_output item with previous_response_id. The Chainlit and Open WebUI adapters show that client behavior without importing LGOS. See OpenAI Clients.

Persistence Boundary¶

The UI owns chat history. LGOS stores resumable interrupt state and explicit thread-scoped application data, not the transcript. PostgreSQL provides the checkpointer, LangGraph store, and cross-worker interrupt coordination, with no Redis service. See Persistent Plot Agent for Store and UI ownership, Interruptible Human Review for the server lifecycle, and OpenAI Compatibility for the normative continuation and retention contract.

Chainlit persists the paused Response ID and exact interrupt calls in a pending interrupt record with a documented crash window. Open WebUI persists its native ask_user card and opaque graph cursor on the assistant message. Their exact recovery boundaries are documented on the Chainlit and Open WebUI pages.

For exact commands and environment ownership, use Demo Settings and Commands. To build your own application, get started with the package.