Examples overview¶

Runnable examples

The runnable examples live in the top-level gateway-examples/ project. They are intentionally small, opinionated, and close to real application patterns, so you can copy one integration style without digging through the whole gateway codebase first.

Source repository: github.com/lunargate-ai/gateway-examples

All runnable examples¶

python-basic-poetry
python-responses-tools-poetry
python-auto-tiers-poetry
python-ollama-embeddings-poetry
node-express-moderate
docker-compose-minimal
streamlit-chat-docker-compose
streamlit-rag-redissearch-docker-compose

Example families¶

SDK-first examples: python-basic-poetry, python-responses-tools-poetry, python-auto-tiers-poetry, python-ollama-embeddings-poetry
App/backend example: node-express-moderate
Compose demos: docker-compose-minimal, streamlit-chat-docker-compose, streamlit-rag-redissearch-docker-compose

Start smallest
Use a one-file Python example with the normal OpenAI SDK.

Test embeddings first
Use the Poetry embeddings example to verify /v1/embeddings against local Ollama.

Try Responses + tools
Use a minimal Python loop for /v1/responses with one local tool and function_call_output.

Start fastest
Run gateway plus demo app together with one compose command.

Learn lunargate/auto
See how the gateway picks model tiers while the client keeps one stable model name.

Good rule of thumb:

if you want the smallest possible SDK integration, start with python-basic-poetry
if you want the smallest embeddings smoke test, start with python-ollama-embeddings-poetry
if you want a minimal Responses API tool-calling loop, start with python-responses-tools-poetry
if you want the fastest demo for a teammate, start with docker-compose-minimal
if you want app-level streaming, look at node-express-moderate or streamlit-chat-docker-compose
if you want local RAG with file upload and retrieval, go straight to streamlit-rag-redissearch-docker-compose
if you want tiered routing, go straight to python-auto-tiers-poetry

Quick paths¶

Need backend streaming?
Use the Node/Express example to see app-side SSE handling and custom LunarGate headers.

Need a browser UI?
Use the Streamlit chat example for a tiny compose-local chat interface with live responses.

Need local RAG?
Use the Streamlit RAG example for txt/md uploads, embeddings, and RedisSearch retrieval.

Need the easiest demo?
Use the minimal compose stack when you want one command and two services.

Which example to start with¶

Example	Runtime	Best for	What it teaches	Source code
`python-basic-poetry`	Python + Poetry	the smallest possible client integration	OpenAI Python SDK, `base_url`, one request, one response	GitHub
`python-responses-tools-poetry`	Python + Poetry	minimal Responses API plus local tool execution	`/v1/responses`, function-call loop, `function_call_output`, route/header verification	GitHub
`python-auto-tiers-poetry`	Python + Poetry	`lunargate/auto` and model tier selection	`model_selection`, tier headers, tool-aware routing on `chat.completions`	GitHub
`python-ollama-embeddings-poetry`	Python + Poetry	the smallest embeddings integration	OpenAI-compatible embeddings, local Ollama, `/v1/embeddings` smoke testing	GitHub
`node-express-moderate`	Node.js + Express	a backend service calling LunarGate for both JSON and streaming	SSE streaming, custom `X-LunarGate-*` headers, app API vs gateway API separation	GitHub
`docker-compose-minimal`	Docker Compose	the fastest local demo with both app and gateway	gateway + app in one compose file, smoke checks, remote-Docker-safe wrapper image	GitHub
`streamlit-chat-docker-compose`	Docker Compose	a basic chat UI beside the gateway	OpenAI-compatible chat UI, streaming responses, compose-local demo UX	GitHub
`streamlit-rag-redissearch-docker-compose`	Docker Compose	a local RAG demo with UI	file upload, embeddings, RedisSearch vector retrieval, local Ollama chat + embeddings	GitHub

Shared assumptions across examples¶

Most examples assume the gateway is on http://127.0.0.1:8080/v1.
Client-side auth is assumed to be off by default, so examples use not-needed-if-gateway-auth-is-off as the API key placeholder.
Most examples include both config-simple.yaml.example and config-observability.yaml.example, so you can switch between local-only mode and request inspection in the LunarGate Dashboard on app.lunargate.ai.

Observability-ready configs¶

Most examples also ship with a config-observability.yaml.example variant.

That variant enables:

data_sharing.enabled: true
share_prompts: true
share_responses: true
remote_control: true

To use those configs, create a gateway in the Gateways section of app.lunargate.ai, then export:

export LUNARGATE_GATEWAY_API_KEY="lgw_your_gateway_api_key"

You do not need LUNARGATE_GATEWAY_ID. The gateway identifies itself to the LunarGate Dashboard on app.lunargate.ai with LUNARGATE_GATEWAY_API_KEY, and the backend resolves the internal gateway ID automatically.

You also do not need to set LUNARGATE_BACKEND_URL in these examples unless you intentionally want to override the gateway default.