LangGraph GaussDB FastAPI

A FastAPI server that implements key LangGraph Platform-compatible endpoints with async GaussDB persistence.

Install

The bundled y_agent graph requires the internal, workspace-confinement build of y-agent and the system bwrap executable. The y-agent SDK is carried in-tree as plain source at agent/y_agent/ — nothing to install, and edits to it take effect on the next server restart.

python -m pip install -e .    # server + y-agent's runtime deps
bwrap --version               # required; startup fails closed without it

import y_agent resolves because agent/ is placed on sys.path — PYTHONPATH in run-server.sh for the server, pythonpath = ["agent"] for pytest. y-agent's own runtime requirements are declared in this project's pyproject.toml (the y-agent's runtime closure block), since no package metadata does it any more. See AGENTS.md for how to run y-agent's test suite against this source, and run ~/claude/y-agent/scripts/preflight_bubblewrap.py on the target host before deploying — bwrap --version alone does not prove confinement will work.

run-server.sh refuses to boot unless the imported y_agent is the in-tree source at the expected version, so a stale y-agent package in site-packages cannot silently shadow it. If it ever does: pip uninstall -y y-agent.

The y-agent graph uses /usr/bin/bwrap (or /usr/local/bin/bwrap) by default. Set Y_AGENT_BWRAP only when Bubblewrap is installed at another trusted absolute system path. If Bubblewrap is unavailable, startup fails closed.

To run the packaged Chainlit prototype too:

python -m pip install "langgraph-gaussdb-fastapi[chainlit]"

Run

Set the database connection in a mode settings file or with environment variables, then start the server:

LG_MODE=dev \
LG_SETTINGS_FILE=settings/secrets.env \
langgraph-gaussdb-fastapi

Configuration is loaded from settings/base.env, then settings/{LG_MODE}.env; LG_MODE defaults to dev. If LG_SETTINGS_FILE is set, that file is loaded after the mode file. Real process environment variables always win, so existing deployment env vars continue to work. When no working-directory settings/ directory exists, packaged defaults are used.

The default graph config now comes from the packaged server_config.json. You can still override it with LG_GRAPH_CONFIG.

{
  "dependencies": [],
  "graphs": {
    "echo": "graph.example_graph:graph",
    "qwen_tools": "graph.qwen_tools_graph:graph",
    "orchestrator_worker": "graph.workflow_graphs:orchestrator_worker_graph",
    "router_specialist": "graph.workflow_graphs:router_specialist_graph",
    "evaluator_optimizer": "graph.workflow_graphs:evaluator_optimizer_graph"
  }
}

Additional packaged workflow graphs:

• orchestrator_worker: planner -> worker fan-out -> synthesis
• router_specialist: request classification into research, implementation, review, or general specialist
• evaluator_optimizer: draft -> critique -> revise loop with a bounded retry budget

Health checks are available at / and /ok.

Chainlit

The distribution includes a packaged Chainlit UI that can be mounted onto the same FastAPI app as a sub-application. This is the recommended way to run the UI: a single process, no extra ports, no cross-origin hops.

Install the optional extra:

python -m pip install "langgraph-gaussdb-fastapi[chainlit]"

Start the server with LG_ENABLE_CHAINLIT=1 in the selected settings file or in the process environment:

LG_ENABLE_CHAINLIT=1 \
CHAINLIT_AUTH_SECRET=change-me \
langgraph-gaussdb-fastapi

The Chainlit UI is served at /chainlit (override with LG_CHAINLIT_PATH). In mounted mode the Chainlit backend talks to the LangGraph API in-process via httpx.ASGITransport, so LANGGRAPH_SERVER_URL does not need to be set. Chainlit's FastAPI integration docs recommend header auth for this setup: https://docs.chainlit.io/integrations/fastapi

If LG_ENABLE_CHAINLIT is unset or the chainlit extra is not installed, the helper is a silent no-op and the API server continues normally. If LG_ENABLE_CHAINLIT=1 but CHAINLIT_AUTH_SECRET is missing, the API server still starts but the UI is not mounted.

Settings files and environment variables

The repository includes these mode files:

Use LG_SETTINGS_DIR=/path/to/settings to read mode files from another directory. Use LG_SETTINGS_FILE=/path/to/secrets.env for a local override file; settings/*.local.env and settings/secrets.env are ignored by git.

Supported settings-file syntax is KEY=value, optional export KEY=value, shell-style quoting, blank lines, and comments.

Legacy standalone launcher (deprecated)

The previous langgraph-gaussdb-chainlit launcher is still shipped for backwards compatibility but is deprecated in favor of the mounted flow:

LANGGRAPH_SERVER_URL=http://127.0.0.1:2026 \
langgraph-gaussdb-chainlit --headless --host 0.0.0.0 --port 8010

Integration tests

Run the opt-in integration suite against a live GaussDB-backed environment. The fixtures now boot a single FastAPI process with Chainlit mounted:

RUN_LANGGRAPH_CHAINLIT_INTEGRATION=1 pytest -m integration