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, catalog-detail pass-through, 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, login, settings UI, file display, and HITL UI	Independent uv project and `lgos-chainlit` image
Open WebUI	Responses manifold plus dynamic generated Workspace Models	Independent uv project; Open WebUI uses its official image
Bifrost	Shared model catalog plus provider-selected native OpenAI routing	Compose configuration with the official image
LiteLLM	Selectable managed UI inference edge plus catalog-detail pass-through	Pinned public `homeserver-litellm` image and Compose 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; only catalog detail uses pass-through to preserve LGOS extensions.

Pinned managed-routing limitations

The bundled Bifrost native Responses route preserves phase, commentary, file-input, and continuation contracts; only normalized model-detail and error metadata remain strict expected failures. Its raw pass-through route passes the direct contract suite. The bundled homeserver-litellm image preserves native streaming through dynamic wildcard routes. Standard error metadata remains rewritten. Pass-through routes remain the lossless 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	Missing LGOS metadata	Runtime settings	Interrupts	UI feedback	Citations
Chainlit	Uploads attachments to the central Files API	Limited-functionality profile and warning toast	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	Limited-functionality model description and warning notification	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

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.