AI Assistant

AI Assistant

The AI assistant is an in-app chat that answers questions about your warehouse in plain language. It is backed by the assistant service (Java, port 8096) which runs an Anthropic Claude Messages API tool-use agentic loop: the model is given a fixed set of read-only tools, calls them as it needs, the service runs each call and feeds the result back, and the loop continues until the model produces a final answer. The model is instructed to answer only from tool results, so it never makes up facts about your warehouse.

The feature is off by default. It requires an operator-supplied Anthropic API key, which is an external, billed dependency, and stays disabled until an admin sets a key and turns it on.

What it can do

Ask it about your orders, transports, stock, and handling units, for example:

• "How many outbound orders are open today?"
• "What's the available stock for SKU DEMO-0042?"
• "Trace handling unit DEMO-HU-007 through the system."
• "Which lines are blocked on short stock right now?"
• "Give me the inbound situation."

It answers by calling the WCS's own read APIs under your permissions (see the guarantees below), so it can only see and report what you yourself are allowed to see.

How to enable it

1. Sign in as an admin and open Settings → AI Assistant.
2. Paste an Anthropic API key (the field is write-only — it is never shown back to you).
3. Pick a model: Haiku 4.5 (claude-haiku-4-5, the default — fast and economical) or Opus 4.8 (claude-opus-4-8 — more capable).
4. Enable the feature.

Once enabled, a lime-green circular chat bubble (bottom-right of every screen) appears for users across the app. Click it to open the chat panel. The widget keeps conversation history and scopes every question to the active warehouse from the top-bar switcher. It is shown only while GET /api/assistant/status reports enabled: true.

To replace the key later, type a new one and save. To keep the existing key while changing only the model or the enabled flag, leave the key field blank — an empty apiKey is treated as "keep the current key". To turn the feature off, disable it in the same tab.

The tool surface (read-only, identity-forwarded)

The assistant has no free-form access to the system. It can only call a fixed set of read-only tools, each of which is an HTTP call to an existing WCS endpoint:

Tool	Reads from	Returns
search_orders	order-management	matching orders
get_stock_by_sku	inventory	per-SKU available / allocated / unavailable
get_inventory_dashboard	inventory	inventory situation aggregate
get_hu_trace	flow-orchestrator	a handling unit's transport timeline
get_transport_tasks	flow-orchestrator	device / transport tasks
get_stock_blocking	allocation	lines blocked on short stock
get_dashboard	order-management	inbound / outbound situation aggregate

None of these tools write or change any state, so the assistant cannot modify orders, stock, transports, or configuration.

Guarantees

• Read-only. The tool surface is read endpoints only — the assistant cannot change anything.
• Your permissions apply. Every tool call forwards the caller's identity headers (X-Auth-User / X-Auth-Roles / X-Auth-Warehouses), so the same gateway and per-service RBAC and warehouse-scope checks apply to the assistant as to you. It can never surface data you could not fetch yourself, and it is scoped to your active warehouse.
• Answers only from tool results. The model is instructed to answer from what the tools return, not from general knowledge about your operation.
• The key never leaves the server / write-only. The Anthropic API key, the chosen model, and the enabled flag are stored in master-data's system_configuration (AI_ASSISTANT_API_KEY / AI_ASSISTANT_MODEL / AI_ASSISTANT_ENABLED). On the public API the key is write-only: GET /api/master-data/ai-assistant returns {enabled, configured, model} and never the key, and the admin PUT accepts a new key but never echoes it. The assistant service reads the actual key from a network-only internal endpoint GET /internal/ai-assistant that is never routed through the gateway (it has no /api/ prefix), mirroring iam's /internal/screen-access. The key never reaches the browser.

API

• POST /api/assistant/chat {warehouseId, messages[]} → {reply} — runs the tool-use loop and returns the assistant's reply. RBAC: authenticated users with INVENTORY_VIEW.
• GET /api/assistant/status → {enabled, configured, model} — used by the UI to decide whether to show the chat widget.

Master-data config endpoints:

• GET /api/master-data/ai-assistant → {enabled, configured, model} (never the key).
• PUT /api/master-data/ai-assistant (ADMIN) — set enabled / model / apiKey (omit apiKey to keep the existing key).
• GET /internal/ai-assistant — network-only, never gateway-exposed; serves the actual key to the assistant service.

See Services for the service summary and Security for the identity-forwarding model.