OpenAI-compatible, but more.

01 Entry point.

The app factory lives in service/api.py. The lifespan handler at module load does five things in order:

1. Wire MCP_SERVER_URL so memory operations are routed via MCP tools (loggable, traceable) rather than direct DB access.
2. Seed and merge model definitions from ModelDefinitionStore — DB always wins over the YAML.
3. Warm the sentence-transformer embedding model on a background thread. The first inference takes ~6 s; warming it off-thread keeps the first chat after a restart fast.
4. Start the BackgroundService worker, the JobScheduler (if LLM_BAWT_SCHEDULER_ENABLED), and the OpenClaw Redis subscriber if configured.
5. Mount every router from service/routes/__init__.py:
   health, ha_weather, nextcloud, models, openclaw_ws, botchat, chat, tasks, turn_logs, jobs, history, memory, prompts, settings, profiles, llm, media

02 The chat-completions surface.

The OpenAI-compatible endpoint is small. routes/chat.py is 214 lines and defines three POSTs:

The request schema (ChatCompletionRequest in service/schemas.py) accepts the standard OpenAI fields and adds:

03 Streaming the response.

Non-streaming requests return a normal ChatCompletionResponse. Streaming requests return SSE: a StreamingResponse wrapping BackgroundService.chat_completion_stream, which is implemented across service/chat_streaming.py and service/chat_stream_worker.py.

Three things happen in parallel during a streaming turn:

1. The pipeline runs in a worker thread. It's CPU- and IO-bound (memory search, tool calls, eventual LLM call); offloading keeps the event loop responsive.
2. Token deltas flow into an asyncio.Queue. The streaming generator awaits the queue and formats each chunk as a standard OpenAI {"choices":[{"delta":{"content":"..."}}]} SSE event.
3. Tool events fan out through a separate channel. Each tool invocation emits a tool_call event before execution and a tool_result event after; the streaming generator interleaves these with the content deltas so frontends can render tool progress in real time.

04 The 18 route modules.

Each file under service/routes/ registers one APIRouter. routes/__init__.py imports them and exposes all_routers for the app factory.

05 Models and bots are CRUDable at runtime.

Two of the heaviest routers (settings.py and models.py) implement live editing of the things that bots.yaml and the model definition YAMLs seed. The DB always wins:

• Bot profiles: PUT /v1/bots/{slug}/profile for full replace, PATCH for partial. System prompt, default model, tool flags, agent-backend config, runtime settings — every field that bots.yaml seeds is editable here. A POST /v1/admin/reload-bots forces a re-read after manual DB edits.
• Model definitions: PUT /v1/models/definitions/{alias} sets a model alias's type, model_id, base_url, context window, max tokens, and adapter. A POST /v1/models/definitions/seed re-seeds from YAML.
• Prompt templates: Every system-prompt fragment used by extraction, summarization, consolidation, and animation classification is a versioned PromptTemplate editable via routes/prompts.py. Each PUT creates a new version; GET /v1/prompts/{key}/versions lists them; POST .../reset rolls back to the default.

06 Turn logs are first-class.

Every chat turn writes a row to turn_logs capturing the request, the assembled message list (system prompt + history + retrieved memories + tool results), the final response, the model used, timing, status, and the full set of tool calls with their arguments and results. The streaming pipeline flushes partial response text periodically so a client reconnecting mid-stream can show progress.

routes/turn_logs.py exposes GET /v1/turn-logs (filterable list) and GET /v1/turn-logs/{turn_id} (full reconstruction). The BawtHub UI's debug pane uses these to replay any turn — to see exactly what the LLM saw — which is invaluable when a bot misbehaves.

07 The OpenClaw lifespan integration.

When OPENCLAW_WS_ENABLED and REDIS_URL are set, the lifespan handler constructs a RedisSubscriber from the openclaw-bridge package and starts two background tasks:

• Stale consumer-group cleanup. Every 5 minutes, destroys idle ui:* Redis consumer groups so reconnecting browsers don't accumulate orphans.
• Tool-event persistence. Subscribes to the bridge's tool_start / tool_end events on Redis streams and writes each one to tool_call_records for later inspection via GET /v1/tool-calls.

A bot-id-to-session-key mapping is built at startup by walking every bot with agent_backend: openclaw and harvesting the session_key from its agent_backend_config. This is logged at startup so you can see exactly which sessions the service is listening for.

08 Running it.

The service is started by llm-service (entry point at service/server.py:main). Flags:

09 Key files.