Metadata-Version: 2.4
Name: langgraph_openai_serve
Version: 0.30.0rc2
Summary: Openai Compatible Langgraph Server
Keywords: langgraph_openai_serve
Author: İlker SIĞIRCI
Author-email: İlker SIĞIRCI <sigirci.ilker@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: anyio>=4.14,<5
Requires-Dist: click>=8.1
Requires-Dist: fastapi>=0.121.0
Requires-Dist: langgraph>=1.2.6,<2.0.0
Requires-Dist: openai>=3.20.0,<4.0.0
Requires-Dist: opentelemetry-api>=1.35.0,<2
Requires-Dist: pydantic>=2.11,<3
Requires-Dist: pydantic-settings>=2.9.0
Requires-Dist: uvicorn>=0.51.0
Requires-Dist: hatchet-sdk>=1.40.3,<2 ; extra == 'hatchet'
Requires-Dist: langgraph-checkpoint-postgres>=3.1.0,<4 ; extra == 'postgres'
Requires-Dist: psycopg>=3.3.4,<4 ; extra == 'postgres'
Requires-Dist: psycopg-pool>=3.3.0,<4 ; extra == 'postgres'
Requires-Dist: langgraph-openai-serve[hatchet,postgres,tracing] ; extra == 'server'
Requires-Dist: fastapi>=0.142.2 ; extra == 'server'
Requires-Dist: hatchet-sdk[otel]>=1.40.3,<2 ; extra == 'server'
Requires-Dist: opentelemetry-distro>=0.66b0,<0.67 ; extra == 'server'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.45.0,<2 ; extra == 'server'
Requires-Dist: opentelemetry-instrumentation-httpx>=0.66b0,<0.67 ; extra == 'server'
Requires-Dist: opentelemetry-instrumentation-logging>=0.66b0,<0.67 ; extra == 'server'
Requires-Dist: opentelemetry-instrumentation-psycopg>=0.66b0,<0.67 ; extra == 'server'
Requires-Dist: psycopg[binary]>=3.3.4,<4 ; extra == 'server'
Requires-Dist: structlog>=26.1.0,<27 ; extra == 'server'
Requires-Dist: langchain>=1.2.11 ; extra == 'tracing'
Requires-Dist: langfuse>=4.0.0,<5.0.0 ; extra == 'tracing'
Maintainer: İlker SIĞIRCI
Maintainer-email: İlker SIĞIRCI <sigirci.ilker@gmail.com>
Requires-Python: >=3.11, <3.15
Provides-Extra: hatchet
Provides-Extra: postgres
Provides-Extra: server
Provides-Extra: tracing
Description-Content-Type: text/markdown

# LangGraph OpenAI Serve

Serve LangGraph graphs through an OpenAI-compatible `/v1` API so existing
OpenAI SDKs, Chainlit, Open WebUI, and similar clients can call them without a
project-specific protocol.

## Install

Use `uv` for project dependency management:

```bash
uv add langgraph-openai-serve
```

The equivalent `pip` command is:

```bash
pip install langgraph-openai-serve
```

For deployments that use PostgreSQL for LangGraph checkpoints, Store data, or
cross-worker interrupt coordination, install the optional integration:

```bash
uv add "langgraph-openai-serve[postgres]"
```

For polling-only background Responses executed by Hatchet, install its
integration. `InMemoryBackgroundBackend` needs no extra for local trials; see
[Run Responses In The Background](docs/how-to-guides/background-responses.md).

```bash
uv add "langgraph-openai-serve[hatchet]"
```

For built-in Langfuse tracing, install the tracing integration:

```bash
uv add "langgraph-openai-serve[tracing]"
```

Set `LGOS_ENABLE_LANGFUSE=True` together with `LANGFUSE_PUBLIC_KEY` and
`LANGFUSE_SECRET_KEY`. LGOS creates the callback lazily on the first graph run;
importing the package never initializes Langfuse.

The package contains the OpenAI-compatible server integration, not a built-in
LLM graph. Applications register their own graphs. The `demo/` checkout keeps
each deployable application in an independent uv project with its own lockfile.
Its `lgos-rag` example indexes a small corpus packaged with the demo API, so the
entire directory can be copied and run without files from this repository.

Repository tasks require Bash and [Just 1.58.0 or newer](https://just.systems/).
Run `just` for package recipes and `just demo/` for independent demo workflows.
Use `just --usage <recipe>` to see a recipe's options and defaults.

## Generate An Application

Create an independent project that `lgos serve` runs, with example graphs,
tests, developer guidance, and Docker:

```bash
uvx cookiecutter https://github.com/ilkersigirci/langgraph-openai-serve.git \
  --directory lgos-starter-template
```

See the [starter guide](docs/starter-template.md) for setup, and
[Run The LGOS Server](docs/how-to-guides/server.md) to serve your own registry.

## Quick Demo

From this repository, prepare the demo environment and PostgreSQL:

```bash
cp demo/.env.example demo/.env
just demo/up lgos-db --wait
just demo/api --editable
```

Then call the demo with the OpenAI Python client:

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:3004/v1", api_key="DUMMY")

response = client.responses.create(
    model="custom-input-output-context",
    input="Show me custom schemas.",
    store=False,
    safety_identifier="demo-user",
)

print(response.output_text)
```

Existing Chat Completions clients can call the same simple graph through the
same base URL:

```python
completion = client.chat.completions.create(
    model="custom-input-output-context",
    messages=[{"role": "user", "content": "Show me custom schemas."}],
    safety_identifier="demo-user",
)

print(completion.choices[0].message.content)
```

Use Responses for new clients and advanced workflow features. The Chat example
is the compatibility path for existing Chat-only clients.

Use `curl http://localhost:3004/v1/models` only as a diagnostic to inspect the
registered demo graph names.

`just demo/api --editable` overlays this checkout without changing
the self-contained demo project or its lockfile. The demo publishes independent
API and Chainlit images and runs a pinned, lightly patched Open WebUI image
with the demo's Open WebUI integration mounted into it. See the
[demo Docker Compose guide](docs/demo/docker.md).

The complete Compose demo lets one `OPENAI_GATEWAY_TYPE=litellm|bifrost`
setting place either gateway in front of both maintained UI clients. Chainlit
and Open WebUI use normal managed/native Responses and Files routes. Metadata
comes from LiteLLM's native `/model/info` after [model sync](docs/demo/litellm-sync.md),
or Bifrost's native `/v1/models` after [catalog sync](docs/demo/bifrost.md#declarative-model-metadata).
Neither UI connects directly to LGOS. The
PostgreSQL-persistent Chainlit client uses a shared mock login by default, with
OIDC login available as an opt-in mode. See the
[Chainlit demo](docs/demo/chainlit.md).

## Use In FastAPI

```python
from fastapi import FastAPI
from langgraph_openai_serve import GraphConfig, GraphRegistry, LanggraphOpenaiServe
from your_graphs import my_graph

app = FastAPI()
registry = GraphRegistry(
    graphs={
        "my-graph": GraphConfig(
            graph=my_graph,
            description="Answer questions with my LangGraph workflow.",
        )
    }
)

LanggraphOpenaiServe(registry=registry, app=app).bind_openai_api()
```

The default base URL is `{host}/v1`. Registered graph names become OpenAI `model`
values.

LGOS accepts native Responses `input_file` parts with opaque `file_id` values,
but does not own file upload or storage. Deploy one Files API for the graph
services that share a file namespace, or use a gateway-native Files provider.
The standalone S3-backed [demo Files API](demo/files_api/README.md) is a small
reference deployment. Chat Completions remains available for direct
compatibility clients; the maintained demo UIs use Responses exclusively. See
[Choose Responses or Chat Completions](docs/getting-started.md#choose-responses-or-chat-completions)
for a feature-by-feature comparison.

## Docs

- Documentation home: [docs/index.md](docs/index.md)
- Package getting started: [docs/getting-started.md](docs/getting-started.md)
- Architecture and state ownership: [docs/explanation/architecture.md](docs/explanation/architecture.md)
- Self-contained demo stack: [docs/demo/index.md](docs/demo/index.md)
- Self-hosted service references: [docs/demo/self-hosted.md](docs/demo/self-hosted.md)
- Runnable demo API: [docs/demo/api.md](docs/demo/api.md)
- Demo graph catalog: [docs/demo/graphs/](docs/demo/graphs/index.md)
- OpenAI clients: [docs/tutorials/openai-clients.md](docs/tutorials/openai-clients.md)
- Custom graphs: [docs/tutorials/custom-graphs.md](docs/tutorials/custom-graphs.md)
- LangGraph runtime settings: [docs/how-to-guides/langgraph-runtime-settings.md](docs/how-to-guides/langgraph-runtime-settings.md)
- Background Responses: [docs/how-to-guides/background-responses.md](docs/how-to-guides/background-responses.md)
- OpenAI-compatible proxies: [docs/how-to-guides/openai-proxies.md](docs/how-to-guides/openai-proxies.md)
- API and configuration: [docs/reference.md](docs/reference.md)
- Compatibility contract: [docs/explanation/openai-compatibility.md](docs/explanation/openai-compatibility.md)
