Skip to content

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.

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

  • Understand the architecture

    See service ownership, request routing, and persistence boundaries.

    Demo architecture

  • Explore the graphs

    Compare schema adapters, RAG, citations, client events, 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

    Model discovery, Chat Settings, persistence, login, streaming, and HITL.

    Use Chainlit

  • Use Open WebUI

    A general manifold Pipe plus a dedicated simple-graph UserValve demo.

    Use Open WebUI

  • Route through Bifrost

    Route two independently addressable LGOS APIs through one raw OpenAI pass-through endpoint.

    Bifrost gateway

  • Observe the stack

    Add the optional Collector overlay without changing the LGOS package.

    OpenTelemetry overlay

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
Chainlit Persistent OpenAI client, login, settings UI, events, and HITL UI Independent uv project and lgos-chainlit image
Open WebUI Dynamic generated models plus a static UserValves example Independent uv project; Open WebUI uses its official image
Bifrost Shared model catalog plus provider-selected raw pass-through Compose configuration with the official image
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 Chainlit element bodies External endpoint required by Chainlit

Only the APIs import langgraph-openai-serve. Chainlit and Open WebUI exercise the OpenAI wire contract without importing the package. Their dynamic clients use Bifrost's catalog for provider-qualified discovery and raw pass-through for model details and chat. The fixed-model Open WebUI example uses Bifrost pass-through without catalog discovery. Pass-through preserves the required LGOS model-detail extension.

Client Capabilities

Demo client Missing LGOS metadata Runtime settings Interrupts Client events Citations
Chainlit Limited-functionality profile and warning toast Renders supported discovered fields Native choices and free-text input with a durable ledger Native status, Plotly, and live activity elements Markdown content
Open WebUI generated models Limited-functionality model description and warning notification Renders supported discovered fields as Chat Variables Persisted native ask_user card with LGOS replay Native status and persisted chart embeds Native source events and Markdown
Open WebUI static example Warning notification Fixed simple-graph UserValves None Not requested Assistant text only

Ordinary graph conversations work through an OpenAI SDK without a demo adapter. An interrupt still uses standard OpenAI tool_calls, but a client application must recognize langgraph_interrupt, collect human answers, and replay the canonical assistant/tool exchange. 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 replay and retention contract.

Chainlit persists its pending tool-call ledger 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.