AI Admin Console
The AI stack ships with an admin console. Use it to see how busy the GPUs are, whether the LLM has slowed down, and whether document indexing ran correctly — from a browser, without logging in to the server.
This document gives one section per screen. Each section has a screenshot, and the numbers in the image (① ② ③) match the numbers in the table below it. The numbers follow the screen from top to bottom. If this is your first time, take a lap through Take a tour, then look up the section for the screen you need.
Field operators and system administrators. The console is mostly read-only, so it is nearly impossible to break something with a stray click. Screens that change values are flagged with a warning in their section.
Access and login
The address is one of three. Check with your administrator which one applies.
| Form | Address | Notes |
|---|---|---|
| By IP on the internal network (HTTP) | http://<AI_SERVER_IP>:5959 | PI_ADMIN_WEB_PORT, default 5959 |
| By IP on the internal network (HTTPS) | https://<AI_SERVER_IP>:5960 | PI_ADMIN_WEB_TLS_PORT, default 5960. The proxy (plantpulse-proxy) terminates TLS and forwards to the console |
| Installation with a domain name | https://admin.<COMPANY_DOMAIN> | Goes through port 443 on the proxy |
HTTP and HTTPS are both open. Arriving over HTTP does not redirect you to HTTPS.
Through 2026.09 the console lived on 9080. As of 2026.10, port 9080 is no longer used — change your bookmarks and firewall rules to 5959 · 5960. The full port list is in the service port map.
On the login screen (/login/), enter your username and password. The default username is admin, and the password is set by the administrator at install time. After logging in you return to the screen you originally tried to open.
The console does not keep per-user accounts. You sign in with a single account shared by the operations team. Keep the password inside the team. Account settings are described in Accounts and sessions.
After 8 hours you must log in again. The address of the screen you were viewing is remembered, so you return to that spot after logging in.
The console comes in two languages: English · 한국어. Switch with the language button on the login screen, or with the Language button at the bottom of the left rail after logging in. Appending ?lang=ko to the address also opens it in Korean. This document puts the Korean screen names in bold with the English names in parentheses.
Screen map
The vertical strip on the left (the rail) selects a service, and the sidebar to its right shows that service's screens. Home and GPU have no sidebar. At the bottom of the rail are Operations Manual ↗ · Language · Log out.
GPU and LLM sit above the services on purpose. Whatever is slow or dead usually starts in the infrastructure underneath, so scanning from top to bottom finds the problem faster. MCP Gateway comes right after LLM — you see the model and the gateway its tools pass through side by side.
| Rail (English UI) | Screens in the sidebar |
|---|---|
| 홈 (Home) | — |
| GPU | — |
| LLM | Dashboard · Chat test · Model registration · API keys · API endpoints · Upstream status · Logs · Settings |
| MCP 게이트웨이 (MCP Gateway) | Overview, Gateway group (Servers · Tools · Permissions · Client API Keys), Tool Search group (Search Test Bench · Search Settings), Monitoring group (Calls & Metrics) + common menu (2026.10 re-release (2026-10-20)) |
| RAG API | Dashboard, Index group (Documents · Videos · Sync history · Drawing register), API group (Query test) + common menu |
| 시계열 인사이트 (Timeseries Insight) | Dashboard, analysis group (Assets · Production · OEE · RAM · EMS · Alarms · System), AI autonomy · Profiling · Feature store + common menu |
| 문서 파싱 (Document Parsing) | Document check, Drawings group (Drawing read test) + common menu |
| 비전 (Vision) | Vision check + common menu |
| 디지털 스레드 (Digital Thread) | Integration map · Graph mirror + common menu |
| 자동화 샌드박스 (Automation Sandbox) | Overview, Execution group (Run History · Run limits) + common menu (no MCP server info) |
The common menu is identical across all six of RAG API · Timeseries Insight · Document Parsing · Vision · Digital Thread · MCP Gateway (Automation Sandbox has the same except MCP server info) — MCP server info · API endpoints (MCP group), Logs · API keys (Operations group), and Settings at the end of the list. Learn it once and it is the same in all six. The Common menu section at the end of this document covers them all at once.
Things field personnel look at — job readiness, equipment timelines, revision badges on drawings — live in the copilot (Field › Digital Thread /thread, the timeline on the equipment screen, drawing cards in chat) → Copilot screen map. The Digital Thread rail in this console keeps only the operator screens for wiring up connectors and watching the mirror. Operators look not at the verdict but at «what feeds the verdict» → Readiness sources.
Operations Manual in the rail goes out to an external site (docs.kopens.io). It will not open at a field site with no internet. A copy of the manual is installed on the server — ask your administrator.
Narrow screens — the menu collapses into a drawer
When the window is narrower than 1024px, the rail and sidebar disappear from the left edge and a bar appears across the top.
| No. | Location | What it does |
|---|---|---|
| ① | ☰ at the left of the top bar | Open menu — the rail and sidebar open as a drawer |
| ② | Top bar | Logo and product name |
| ③ | Drawer (right-hand scene) | The same menu as the rail · sidebar on a wide screen. When open it covers ① · ② in the top bar |
| ④ | Dim overlay outside the drawer | Tap to close the drawer |
The drawer closes on any of: Esc, tapping outside, tapping a menu item, navigating to another screen, or widening the window past 1024px.
Take a tour
If this is your first time, take a lap in this order. You only look — nothing changes.
- Home — if Down in the System Status row is 0, you can relax for now.
- GPU — check that XID errors is 0.
- LLM → Dashboard — check that P95 per model is close to normal.
- RAG API → Documents — just confirm that indexed documents exist.
- Logs in the same sidebar — recent log lines, newest first. No need to SSH in and run
docker logs.
See overall status on Home → go into the service that looks wrong → read its logs. That one line covers most of what you do in the console.
Home — /
An at-a-glance view of the health of the whole AI stack, and the starting point for entering each service screen. Status refreshes automatically every 20 seconds.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Product name and subtitle — a header you can customize per installation |
| ② | System Status | Counts every monitored service as Total · Healthy · Warning · Down. The dot in the header is the overall verdict, with the last refresh time and a refresh button beside it. Expanding Details shows per-service status and response times |
| ③ | Service cards | One card per service. Grouped as Service APIs · Model serving · Storage · gateway · tracing, so that during an incident you can work down from «the caller → the server → storage and observability» |
Read a card like this:
- The status dot on the right appears only on monitored services.
- Cards with an arrow can be opened. RAG API · Timeseries Insight · Vision · Document Understanding · Digital Thread open screens inside the console; LLM proxy · Graph DB open that tool's own UI in a new window.
- Cards without an arrow are status-only. They are internal services the browser cannot reach directly.
- The second line of a card describes what that service does in two lines or less. For example, RAG API is "Indexes and searches asset documents (PDF · Office), drawings (DXF · PDF), video, and audio," and the time series inference model server is "TSPulse anomaly detection · TTM forecasting model server."
Common tasks
- Expand Details. Once expanded, it stays expanded the next time you come in.
- Hover over the status indicator of a service in Warning (yellow). The tooltip also shows the raw status the service itself reported — for example, the service is alive but its database connection is down.
- Go into that service and read its Logs.
While no status has arrived yet the dot is gray (not measured). Gray means "not known yet," not "healthy."
GPU — /gpu/
Shows utilization, temperature, and errors for GPU devices. Values are re-collected every 5 seconds.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and last collection time — check here that values are not frozen |
| ② | Summary row | Devices · Unified memory · Host CPU · XID errors — in one line, how full the machine is right now and whether any hardware errors occurred |
| ③ | Devices table | One row per GPU. Compare SM (utilization) · memory bandwidth · temperature · memory temperature · power · SM clock · encode / decode · XID down the column to find the GPU that stands out |
| ④ | Trend | A 60-minute chart — tells a momentary spike from a sustained high |
XID is an error raised by the NVIDIA hardware or driver. A non-zero value puts a red marker on that row. If you let it pass quietly, the next symptom is usually a server crash. Copy the value verbatim and report it to your system administrator.
LLM dashboard — /llm/
Shows response speed and throughput of the model serving engines. Values are collected every 5 seconds.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and last collection time |
| ② | Summary row | Models · Running · Queue · Worst P95 — in one line, whether the engine is backing up. The warning threshold is shown next to worst P95 |
| ③ | Models table | One row per model. Use status · running · queue · throughput · P50 · P95 · P99 · 1-min interruptions · KV cache · 30-min TPS to find which model is slow. A dash (—) means no samples yet |
| ④ | Trend | A 60-minute chart (1-minute buckets) for one model — find when it slowed down |
When someone says "answers have been slow lately," look at the P95 column (the 5th slowest out of 100). If it is well above normal, their impression is correct.
Chat test — /llm/playground/
Sends a single prompt through the model gateway (LiteLLM). It is the same path the applications use, so it tells "the model is alive but only the app is broken" apart.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and the number of models reported by the gateway |
| ② | Prompt card | Pick a model with the model buttons, fill in System prompt (optional) · Max tokens · the prompt, and press Send (Ctrl+Enter). Below you get the answer, elapsed time, and input/output tokens |
Whatever you enter, the server caps it at 2048 tokens. The answer arrives all at once (streaming is intentionally disabled). The model «thinks» before answering, so with a small budget it may run out before any answer text appears — the screen tells you when that happens. The same GPU also serves the copilot, so long answers take time.
Model registration — /llm/models/
Registers external model endpoints with the gateway. Internal or commercial, anything OpenAI-compatible works.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and refresh |
| ② | Summary row | Serving · Config file · Registered here — counts the models the gateway routes to, by source. Only the ones «registered here» can be edited from this screen |
| ③ | 모델 추가 (Add a model) | Registers a new endpoint — fill in Model name · Provider path · Endpoint · Provider API key · API version · Type, run Test connection, then Register |
| ④ | Serving models | The models currently being served — only rows whose Source is «this console» can be deleted |
Common tasks
- Enter the model name (the name callers will pass as
model), the provider path (LiteLLM format, e.g.openai/gpt-4o), and the endpoint. If the endpoint needs a key, enter the provider API key. API version is used only with Azure OpenAI. - Pick the right type (chat · completion · embedding · rerank). Pick it wrong and a perfectly good endpoint will look broken.
- Confirm a response with Test connection, then Register.
- Default models whose source is the config file (
litellm-config.yaml) cannot be edited here — that file is the source of truth. - Deleting one makes everything calling that name start failing immediately.
- Registration, testing, and deletion are recorded in the audit log (provider keys are not recorded; only fingerprints are).
Provider API keys entered here are stored encrypted with PI_LITELLM_SALT_KEY. Change the salt and the registered models stay visible in the list while calls fail silently → Changing passwords and API keys
LLM API keys — /llm/api-keys/
Issues, rotates, and deletes virtual keys to hand out to applications. It shares a name with API keys in the common menu but does something different — that one measures «whether our key works», this one mints «keys to give to others».
| Location | What it does |
|---|---|
| Summary row | Keys · Spend · Blocked — how much the issued keys have been used and whether any are blocked |
| 키 발급 (Issue a key) | Set Name · Max budget (USD) · Expires in (e.g. 30d, 24h, 1mo) and press Issue. Leave blank for no limit |
| Issued keys table | Per key: hash · models · spend / budget · status · expiry, with Rotate · Delete at the end of the row |
Neither the console nor the gateway stores the plaintext. If you did not copy it right after issuing, you must rotate it. Rotating or deleting stops the current value from working immediately. Issue, rotate, and delete are recorded in the audit log (the key value is not).
LLM also has API endpoints (/llm/api-endpoints/). It lists the gateway's full API surface and looks the same as the one in the common menu.
Upstream status — /llm/operations/
Probes whether the models behind the gateway actually answer. One check is one real call.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and Run check — only when pressed does it actually call every model once |
| ② | Summary row | Healthy · Unhealthy counts — see at a glance whether any model is not answering |
| ③ | Endpoints table | Status and Details per model — the gateway's values are shown unmodified, so you can read the failure reason as-is |
LLM logs — /llm/logs/
One line per request that passed through the gateway. Different from Logs in the common menu (service log files).
| Location | What it does |
|---|---|
| Top of screen | Start · End → Apply — choose the window to view |
| Table | Time · model · type · tokens · latency · cost · request id — find which request was slow or expensive |
Prompt and answer bodies are not here — they are in the Phoenix traces.
LLM settings — /llm/config/
Shows how the console reaches the LLM stack and what the gateway reports. Read-only.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and refresh |
| ② | 게이트웨이 (Gateway) | The gateway address and key the console uses. Only a fingerprint is shown; the plaintext is fetched only when you press the eye icon, and that request is recorded in the audit log with the username |
| ③ | 지표 수집 대상 (Metric poll targets) | The engines the LLM dashboard scrapes directly — if the dashboard is empty, check here whether a target is missing |
| ④ | 게이트웨이가 아는 모델 (Models the gateway knows) | The model list exactly as reported by the gateway — the console keeps no list of its own |
The gateway master key is held by the console server and never sent to the browser. Hand applications a virtual key issued on the LLM API keys screen — you can attach a budget, an expiry, and revoke it separately.
RAG dashboard — /rag/
Shows the indexing status of the service (RAG API) that lets the chatbot answer from internal documents.
| No. | Location | What it does |
|---|---|---|
| ① | 색인 운영 (Indexing Operations) | Screen name, last refresh time, refresh |
| ② | Summary row | Total documents · Indexed · Pending · Failed — counts how many documents in the platform ledger made it through indexing |
| ③ | Scheduler | Next run · Last run and a summary of that run — check that synchronization is running on time |
Below that come the backend reachability table (whether LightRAG · PostgreSQL · graph DB · vector DB · platform are reachable) and index status by asset. If Failed is non-zero or anything is Unreachable, read that service's Logs.
Documents — /rag/documents/
Shows indexed documents and lets you upload or re-index documents. When someone reports "the chatbot can't find a document," start here.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Upload (opens the upload dialog) · Refresh · Sync now (immediately re-fetches platform documents) · Reindex all |
| ② | Summary row | Documents · Indexed · Pending · Failed — whether any document has not finished indexing or has failed |
| ③ | Document table | Asset · Document · Status · Indexed at · Actions. Row actions: view details, re-index, download original, test search with this document, exclude from / re-include in the corpus, delete (uploaded documents only) |
Common task — when the chatbot cannot find a document
- Check whether the document is in the table — if not, it was never indexed.
- If it is, use Test search with this document at the end of the row, or the Query test screen, with wording similar to what the user asked.
- Check in Sync history that the last sync did not end in failure.
While indexing is running, status refreshes automatically every second, so you do not need to refresh.
If drawing indexing (DRAWING_INGEST_ENABLED) is on, drawing rows also show the drawing number · revision · part number and a revision badge (Latest · Superseded (latest …) · Change in progress · Unverified) under the document name. To view drawings grouped by revision, open the drawing register.
- PDF drawings whose drawing number could not be read from the title block still appear as drawing rows — with "Drawing · could not read drawing number from title block" under the name. The marking keeps them from looking like ordinary documents.
- Exclude from search on a drawing row depends on how the drawing arrived.
- Drawings from the platform ledger (source
PLATFORM) have the Exclude from / re-include in corpus button enabled, like ordinary documents. The ledger is the source of truth so they cannot be deleted; use this to take them out of search. - Drawings uploaded directly in the console have the button disabled (grayed out). Hovering shows "Manually uploaded drawings cannot be excluded from search — delete or re-index the drawing instead (platform ledger drawings can be excluded)."
- Re-index and download original work for any drawing; delete works only for ones uploaded directly.
- Drawings from the platform ledger (source
That sentence is generated by the LLM on the spot, so it differs every time. Do not judge by a specific phrase — judge by whether the indexed count is 0.
Delete is available only for directly uploaded documents (marked Manual). A deleted document can no longer be used as evidence by the chatbot, and putting it back requires uploading the original file again. If you do not have the original file at hand, do not delete it. For documents that came from the platform, use Exclude from corpus instead of deleting.
Reindex all re-indexes «every» platform document. Documents are re-collected incrementally so there is no indexing gap, and directly uploaded documents are unaffected. Still, it takes time — press it only when you need to.
Upload dialog — shared by Documents · Drawing register · Videos
All three screens open the same dialog. Only the initial values and accepted formats differ by where you open it from.
| Opened from | Button | Dialog |
|---|---|---|
| Documents | Upload | Accepts every format below. PDFs default to document |
| Drawing register | Upload drawing | Titled "Upload drawing"; PDFs default to drawing |
| Videos | Upload video | Titled "Upload video/audio"; accepts video · audio · subtitles only. Dropping a document or drawing is blocked with "Only video, audio, and subtitles are accepted here" |
| No. | Location | What it does |
|---|---|---|
| ① | Asset | Search by asset ID or name and pick one. If you pick none it goes to the shared bucket (_manual) and is not tied to an asset |
| ② | Drop zone · Accepted formats | Drop multiple files at once or pick them with Choose files. The strip below shows the currently accepted formats and the maximum size per format — disabled formats show Off |
| ③ | File list | Per file, the type (table below) and state (Ready · Blocked · Uploading · Done · Failed). PDF rows have a document / drawing toggle, and All PDFs switches them all at once |
| ④ | Blocked rows | The reason it was blocked before sending is written on that row (below) |
| ⑤ | Upload N files | Sends files one at a time, in order — because RAG indexing writes only one at a time |
| Extension | Type |
|---|---|
pdf · docx · pptx · xlsx · md · txt | Document (PDF: choose document / drawing) |
dxf | Drawing |
mp4 · mov · mkv · webm | Video |
m4a · mp3 · wav | Audio |
srt · vtt | Subtitles |
Choosing drawing for a PDF indexes it as a drawing (document_kind=drawing is sent with it). On installations where drawing indexing (DRAWING_INGEST_ENABLED) is off, "Drawing indexing is off … PDFs will be indexed as ordinary documents" appears and PDFs become ordinary documents.
Blocked before sending
| Case | Reason shown on the row |
|---|---|
.dwg | "DWG is not accepted — export to DXF or PDF and upload that." |
| Video or audio while media ingestion is off | "Video/audio ingestion is off — set PI_MEDIA_ENABLED=true in the install env …" |
| Subtitles while subtitle ingestion is off | "Subtitle ingestion is off (MEDIA_TEXT_TRACKS)." |
| DXF while drawing indexing is off | "Drawing indexing is off (DRAWING_INGEST_ENABLED), so DXF cannot be indexed." |
| Over the size limit | "Too large — … exceeds the limit of ….". The limits are SYNC_MAX_FILE_MB for documents and drawings (bundled value 50 MB), MEDIA_MAX_FILE_MB for video and audio (default 2048 MB), and 5 MB for subtitles |
| Empty file | "The file is empty." |
- The enabled features and limits are not decided by the dialog; they come from the RAG API configuration. If the configuration cannot be read, "Could not read rag-api configuration — the server decides formats and sizes." appears and only
.dwgand unknown extensions are blocked. - Files uploaded here are marked Manual (directly uploaded) and are never removed by synchronization.
- Uploading a drawing shows the drawing number · revision · dimensions · BOM row count in the result line; video and audio end with "Queued for transcription and indexing" — transcription starts in the processing window.
- If the same name is already indexed the other way (drawing / ordinary document), the server rejects it — delete it first or rename the file.
Videos — /rag/videos/
Shows repair, training, and equipment-operation video and audio file by file — whether it was transcribed, whether scene thumbnails were produced, whether it made it into the search index. When a video is not showing up as evidence in chat, start here. How videos are used in chat is described in Video search.
The screen shows only a "Video/audio ingestion is off" box, with no table. PI_MEDIA_ENABLED=true in the install env file is the switch — turn it on and recreate the stack, and RAG API will accept video ingestion and the transcription (ASR) server will come up. Until then RAG API has no media routes and video uploads are rejected → Configuration
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and description |
| ② | Summary row | Files · Indexed · Pending/processing · Failed (failed · skipped) · Empty transcript · Missing from search (number of segments indexed but absent from the search index) |
| ③ | Toolbar | Search file/asset (part of a file name · asset ID · asset name) · Problems only (failed · skipped · empty transcript · has segments missing from search) · Refresh · Upload video (opens the upload dialog restricted to video · audio · subtitles) |
| ④ | Right of the toolbar | Processing window — when transcription and indexing start (below) |
| ⑤ | Table | File · Asset · Duration · Status · Transcript (characters · segments) · Scenes (scene thumbnails) · Uploaded at · Actions |
| ⑥ | Expanded row | Expanding a row reveals a player, the transcript with timestamp chips (tap a chip to play from that moment), the subtitle file paired with the video, and processing info (language · indexed segments · ASR model · updated at, etc.) |
| ⑦ | Row actions | Only the buttons that fit the state — in the image, the indexed row has Re-transcribe (↻) and Delete (directly uploaded only); failed and skipped rows have Retry (below) |
Processing window. Video transcription occupies the GPU for a long time, so it only starts within a configured window. A row shows one of three:
- "Processing window … — processing now"
- "Processing window … — pending files start at …"
- "No processing window restriction"
The window is set with MEDIA_PROCESSING_WINDOW. If left blank it is 20:00-06:00 (based on the install time zone PP_TZ), and always means it can start at any time. The window applies only to the «start» of processing — work that has started runs to completion even after the window closes → Configuration
Status
| Status | Meaning |
|---|---|
| Pending | Waiting for the processing window |
| Fetching · Transcribing · Indexing | In progress |
| Indexed | Used in search |
| No audio · No speech | There is no audio track, or no speech was found — if the video does contain speech, use Re-transcribe |
| Skipped · Failed | Could not be processed — expand to read the reason and press Retry |
| Deleting | Deletion is in progress |
Actions
| Action | Rows where it appears | What it does |
|---|---|---|
| Retry | Failed · Skipped | Re-queues it. Starts in the next processing window |
| Re-transcribe | Indexed · No speech · No audio | Transcribes again from scratch. The current transcript is discarded, and new segments replace the old ones once indexed |
| Delete | Directly uploaded (manual) only | Deletes segments, transcript, and the archived original. Videos from the platform ledger cannot be deleted here |
- If any row is processing, the screen reloads every 5 seconds. If only Pending rows remain it does not reload (waiting for the window can take hours).
- Do not let a non-zero Empty transcript slide. If a video with speech has an empty transcript, chat cannot use it as evidence — follow the guidance in the expanded row, check the ASR model, then Re-transcribe (or Retry).
- As of 2026.10 re-release 4, transcription no longer discards the first sentence that follows silence or noise, and it pulls the timestamp of a retained sentence forward to the actual speech. Videos transcribed before that are not redone automatically, so for videos with a missing first sentence or misaligned source timestamps, use Re-transcribe — they will be transcribed again during the processing window (
20:00-06:00if left blank). - Times (uploaded at · next start) are shown in the install time zone (
PP_TZ). Them:sson transcript chips is the position within the video.
Sync history — /rag/sync-history/
The history of synchronization runs that fetch asset documents from the platform. It survives restarts.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name, number of recorded runs, refresh |
| ② | Table | Per run: Started · Trigger · Assets · Ledger · Indexed · Disappeared · Cards · Duration · Result — see what came in and what dropped out when, and whether any run failed |
If Result on the top row is Error, read the RAG API Logs around that time.
Drawing register — /rag/drawings/
Shows the drawings indexed in RAG (DXF · vector PDF) grouped by drawing number, one row per revision. If a revision has several files (DXF and PDF, platform ledger and direct upload), they collapse into one row. Open it to settle "is the drawing posted in the field the latest revision?" and "was the title block read correctly?"
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and description |
| ② | Summary row | Drawings · Revisions · Superseded · Unread — how many are superseded and how many failed to read |
| ③ | Filter row | Search box (drawing number or part number — also matches part of a document name, case-insensitive) · Superseded only · Read failures only · Refresh · Upload drawing (the upload dialog with PDFs defaulting to «drawing») |
| ④ | Table | Drawing no. · Revision · Part no. · Revision status · Files · Read · Uploaded at. Within one drawing number, newer revisions are on top. The arrow at the left of a row expands a page preview (with page navigation) and the title block readings |
| ⑤ | Files column | Format chips for this revision — a solid chip marks the primary file (the one the chat card and preview open) |
| ⑥ | Right side of the expanded row | N files in this revision — format · ledger/manual upload · asset · file name, with "(primary — opens this file)" on the primary. The primary is chosen as usable file → DXF original → platform ledger, in that order |
| ⑦ | Compare column | When a drawing number has two or more revisions, the newer row gets a Compare with rev ○ button — comparing against the revision directly below |
| Field | Values | Meaning |
|---|---|---|
| Revision status | Latest · Superseded (latest ○) · Change in progress · Unverified | The answer obtained by querying PLM for the released revision and engineering changes by part number. Unverified does not mean «latest», it means «unknown» — there is no PLM connector, or it did not answer → Digital Thread |
| Read | Title block read · No title block · Failed (with reason) · Processing | Speaks only to whether the drawing number was read from the title block and whether indexing failed. PDF drawings whose drawing number could not be read still appear in the register and are counted as Unread with No title block |
| Uploaded at | — | Shown in the install time zone (PP_TZ) |
Pressing Compare opens, below that row, a summary · confidence · Could not compare items · a change table (added · removed · changed for title block · dimensions · BOM · notes), and the changed regions overlaid on the newer revision's image. Press again to close.
A banner reads "Drawing indexing is off in rag-api (DRAWING_INGEST_ENABLED)" at the top of the screen, and page preview · revision status · revision comparison are unavailable. The shipping default is off. How to turn it on is in Configuration.
The Read field in the register speaks only to the title block and indexing failures. Upload the same file to the drawing read test — it uses the same reader RAG uses when indexing drawings.
Query test — /rag/query/
Runs a search against the indexed documents yourself. It honors the same contract as the query API consumers use, so it reproduces exactly what the chatbot receives as evidence.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and description |
| ② | Query box | Enter a question, pick a search mode (hybrid · local · global · naive · mix, default hybrid), and press Run query (Ctrl+Enter). Below you get the answer, elapsed time, and sources |
If the document you expect does not appear under Sources, change the mode and try again.
Timeseries Insight dashboard — /insight/
Shows the status of the engine that finds anomalies in equipment data and forecasts what is coming (Timeseries Insight). It has the most menus of any service.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name |
| ② | Status alert | Whether the service and all its dependencies respond — healthy / unhealthy / server connection error |
| ③ | Summary row | Anomaly detection · Forecasting · MCP tools · Scheduler — the number of analyses, tools, and scheduled jobs this engine offers |
| ④ | Pipeline table | Last run time for each feature store pipeline — check that the inputs to the analyses are being produced on time |
Below that come a description of the analysis domains and system info (AI models · uptime · scheduler · forecasting models).
Anomaly detection — /insight/anomaly/asset/ and others
Scores recent data for the target as anomalous and ranks which tags or metrics deviated most from normal. The six screens below share this layout (alarm frequency anomaly is covered under Alarm analysis below).
| Sidebar | Path | Target |
|---|---|---|
| Assets › Anomaly detection | /insight/anomaly/asset/ | Sensor tags of one piece of equipment |
| Production › Anomaly detection | /insight/anomaly/order/ | Recent work orders (the axis is order sequence, not time) |
| OEE › Anomaly detection | /insight/anomaly/oee/ | Availability · performance · quality, viewed as deltas of cumulative OEE |
| RAM › Anomaly detection | /insight/anomaly/ram/ | Reliability · availability · maintainability (MTBF/MTTR) |
| EMS › Anomaly detection | /insight/anomaly/ems/ | Consumption, viewed as deltas of cumulative energy (power · fuel) |
| System › Anomaly detection | /insight/anomaly/system/ | CPU · memory · disk of the collection host |
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and the model used |
| ② | Parameters | Set the asset and the window to analyze (data interval · row limit · threshold · lookback range · recent window · top K) and press Run detection. The results — a summary row, time series + anomaly score, anomaly ranking, response data, and a guidance card — open below |
Common tasks
- Pick an asset ID and press Run detection.
- Take the top tag in the anomaly ranking and look at its actual values in time series + anomaly score at the moment the score spiked.
- Open the Forecast screen for the same asset to see where it is headed.
The score is renormalized to 0–1 «within» the requested window, so even a quiet window produces points near 1. Change the window and the same point gets a different score. Read Easy to misread on the guidance card below the results as well.
In earlier releases these three groups were not in the sidebar and could only be opened by URL. They now appear as groups under Assets · Production.
Forecasting — /insight/forecast/asset/ and others
Forecasts the next window for the target and draws the confidence interval as a band. The six screens below share this layout (alarm failure forecast is covered under Alarm analysis below).
| Sidebar | Path | Target |
|---|---|---|
| Assets › Forecast | /insight/forecast/asset/ | Sensor tags of one piece of equipment |
| Production › Quality forecast | /insight/forecast/order/ | Quality · OEE · energy for the next few orders |
| OEE › Forecast | /insight/forecast/oee/ | Where OEE is trending |
| RAM › Forecast | /insight/forecast/ram/ | Reliability · availability · maintainability (MTBF/MTTR) |
| EMS › Forecast | /insight/forecast/ems/ | Energy consumption |
| System › Forecast | /insight/forecast/system/ | CPU · memory · disk of the collection host |
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and the model used |
| ② | Parameters | Set the asset and the horizon (data interval · row limit · context length · forecast length · lookback range · confidence interval) and press Run forecast. The results — a summary row (duration · model · confidence interval · context), forecast result, response data, and a guidance card — open below |
The Model in the summary row must be TTM for it to be a real forecast. NAIVE means TTM failed and a fallback was returned. The forecast length goes up to 96 points; anything larger is rejected rather than truncated.
Health index — /insight/asset/health/
Reports one piece of equipment as a single 0–100 number, together with the deductions that brought the score down.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name — notes that the score combines sensors · OEE · RAM · EMS · alarms |
| ② | Parameters and guidance card | Set Asset ID · Data interval and press Check health index. The score · scores by domain · response data open below. The guidance card (Details / Collapse) explains how to read the score and which screen to go to next |
Press again within 60 seconds and the previous result is shown instead of a fresh calculation. A domain with no data is not counted as healthy — it is excluded from the score, and if observation is insufficient the grade is withheld as "-".
Setup · planned stops · calendar holidays · outside-shift time are not deducted. Domains with short history are withheld from judgment rather than scored 0 (held_domains in the response data), and the grade issued then is provisional (grade_provisional) → Timeseries Insight tools — reading the health index
Alarm analysis — /insight/alarm/…
The five screens in the Alarms sidebar group. All share the same layout: set the asset and range in Parameters at the top, press the run button, and results, response data, and a guidance card open below. The image shows frequency anomaly.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and description |
| ② | Parameters | Set the asset · priority · aggregation window · row limit · threshold · top K and press Run detection. Before you run it, the results area shows only a prompt |
| Sidebar | Path | Run button | What it shows |
|---|---|---|---|
| Frequency anomaly | /insight/alarm/anomaly/ | Run detection | Which time windows the alarms clustered in |
| Failure forecast | /insight/alarm/forecast/ | Run forecast | How many alarms to expect per window going forward |
| Duration analysis | /insight/alarm/duration/ | Analyze duration | Whether the same alarm is staying active longer over time (degradation detection) |
| Sensor correlation | /insight/alarm/correlation/ | Run correlation | Which sensor tags the alarms hang off |
| Statistics | /insight/alarm/stats/ | Query statistics | Alarm counts · priority distribution · top alarm configurations and tags |
It «counts» alarms per tag and per time window. These are tags that frequently appeared together, not tags proven to move together. In Statistics, no alarms in the period is not an error — it returns 0 and an empty list.
AI findings — /insight/findings/
Shows what the AI noticed in the field (order shortfalls · data gaps · AI changes · process anomalies · sensor failures). Open items come first. It lives in the AI autonomy sidebar group.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and refresh |
| ② | Summary row | Open · Critical · High severity · Acknowledged — how many need a human right now |
| ③ | Status filter | Narrow the list to Not closed · Open · Acknowledged · Closed. Beside it you can also narrow by type and asset |
| ④ | Table | Per finding: type · asset · severity · description · last observed · status, with Acknowledge · Close at the end of the row — leaving a record that someone is on it and that it is handled |
Common tasks
- Read the description of an open finding and press Acknowledge to mark that you are on it.
- When the work is done, press Close and confirm once more in the dialog.
Acknowledge and close are recorded under the logged-in administrator's name and also land in the console audit log (insight.write).
Autonomous improvement — /insight/autonomy/
Shows what the AI changed on its own and why, and lets you stop or roll it back.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and refresh |
| ② | 지금 모드 (Current mode) | The current mode (Auto · Propose only · Off), who set it and when, and the last nightly run. Mode switch buttons and the emergency-stop Off are here |
| ③ | Target table | Per improvement target: version in use · in trial · pending candidate · status, with Roll back · Resume (when stopped) · Approve replacement (for candidates ready in propose-only mode) at the end of the row |
Below that, the Change log records when · where · what happened · who, one line each.
- Filter by period (7 · 30 · 90 days, default 7) and by decision. 50 entries at a time, with Show more to continue.
- Skipped rows are hidden by default. Turn them on with Show skipped. The text above the rows reports the total in the window, how many are shown, and how many are hidden.
| Mode | What it does |
|---|---|
| Auto | The AI checks, trials, and replaces baselines on its own, and rolls back on its own if results get worse |
| Propose only | Checks and trials a new version, then waits for approval before switching |
| Off | Checks, replaces, and rolls back nothing. What is in use stays in use |
Mode switch · off · approve replacement · roll back · resume take effect immediately after a confirmation dialog, and a changed mode survives restarts. Every action is recorded under the logged-in administrator's name in the Change log and the console audit log (insight.write). In an emergency, Off is the stop button.
Scorer comparison (shadow) — /insight/shadow/
Runs the model-free scorer over an asset's recent data to show what it would have caught had it been enabled.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and description |
| ② | Inputs | Enter Asset ID · Recent minutes and press Run scoring. A summary of alert windows · alert minutes · no verdict · sensor faults opens, along with tables of the baselines used and per-window results |
Nothing is saved and no notifications are sent. The anomaly verdicts in production are unaffected.
Asset profiling — /insight/profile/asset/
Understands an asset's tags automatically from real data — what each tag measures, its normal range, and the confidence in that.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name, with asset selection and Reload profile on the right |
| ② | Body | Before an asset is selected, only a prompt. Once selected, a summary row and the Tag understanding · Relationship graph tabs open |
The Tag understanding tab shows each tag's type · normal range · alarm limits · confidence, and Run relationship analysis on the Relationship graph tab computes tags that move together and lead → lag relationships (this can take tens of seconds).
Pipeline status — /insight/feature/status/
Shows whether the processed data the analyses above consume (the feature store) is currently being produced correctly. If analysis results are empty or stale, this is usually the cause.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name, refresh, Run all — runs every pipeline right now |
| ② | Scheduler jobs | Per job, the trigger and next run — check the schedule is alive |
| ③ | Pipelines | Per pipeline, the last run and trigger, with a run button on each row — find one that has not run in a while and run just that one |
Below, the Backfill status card shows backfills in progress and the last error.
The other three screens in the Feature store group:
| Sidebar | Path | What it does |
|---|---|---|
| 실행 이력 (Run History) | /insight/feature/history/ | Past pipeline runs — run time · duration · processed · status · notes |
| 피처 데이터 (Feature Data) | /insight/feature/data/ | Asset feature lookup (Asset ID · Period · Row count → Query features), plus text search and similar assets (vector search) |
| 백필 (Backfill) | /insight/feature/backfill/ | Pick a start date · end date · pipeline and press Start backfill — refills missing periods. You cannot start a new backfill while one is running |
It recomputes past periods, so a wide range takes a long time and raises server load. Run it when production is quiet, narrowed to the period you need. If it is your first time, discuss it with your administrator.
Document parsing check — /parser/
Upload one document to see exactly how the document parsing service reads it (the text RAG would have indexed). Use this screen before trusting RAG indexing results. The sidebar entry is Document check.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and the service this screen calls |
| ② | Input | Pick a parsing profile (default · fast · ocr · scan) and drop in a document (PDF · DOCX · PPTX · XLSX · image) or press Choose file. default matches the RAG indexing configuration; picking another shows «differs from default» |
| ③ | Below ② | Guidance card — what the selected profile does (for default, "How did RAG read this document?"). Collapse with Collapse |
Results appear in the Parsed markdown card beside it, with duration · confidence · characters · lines in the summary row above. If the result is empty and the document is a scan, try again with the scan profile.
Each profile gets its own guidance card (③) below ②, telling you what that profile does, when to use it, and what to watch out for.
| Profile | Card title | Key point |
|---|---|---|
default | "How did RAG read this document?" | Same parsing options as RAG indexing. The text here is the text RAG would have indexed, and anything missing here is also unknown to RAG |
fast | "What does this document look like read fast with OCR off?" | OCR is off, so text in scans and images does not appear. This differs from what RAG saw |
ocr | "What comes out if you extract only the text?" | Table structure is not recognized, so tables flatten into prose. The OCR operation in the vision console uses this profile |
scan | "How does this document read if the text layer is discarded and everything is OCR'd?" | Discards even a perfectly good text layer and reads via OCR. For digitally created PDFs, default is more accurate |
- Limits the card also mentions — uploads through the console are capped at 100 MB (over that returns 413). The console cap applies before the service's own cap (
MAX_DOCUMENT_BYTES, default 200 MiB). The screen polls progress every 2 seconds and stops waiting after about 5 minutes — that does not cancel the parse. - Documents uploaded here are shown and discarded. They are not indexed into RAG.
- Even if
scanis clearly better, the profile on this screen does not change the RAG configuration. To get the same result in RAG you must change the document parsing OCR setting (DOCLING_*). - Drawings (DXF · PDF) belong on the drawing read test, not this screen.
Drawing read test — /parser/drawings/
Upload one drawing file to see what the document understanding service reads and where from that drawing. It lives in the Drawings sidebar group. It uses the same reader RAG uses when indexing drawings, so use it to settle "the chatbot states the wrong dimension from a drawing."
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and description |
| ② | Drawing | Drop a file or click to choose, then press Read drawing. The accepted formats and size limit are decided by the service; the text below the drop zone states them |
| ③ | Summary row | Format · pages · dimensions · BOM rows · title block (found · not found) · warnings |
| ④ | Page image | Draws colored boxes on the page image where things were read. The type buttons (Title block · Dimensions · BOM · Notes) toggle the boxes |
| ⑤ | Reading tables | Title block · dimensions (tolerances) · BOM · notes · zones in tables. Click a table row to highlight its box |
| ⑥ | Two-revision comparison test | Upload two files of the same drawing — the old revision and the new revision — and press Compare to see title block · dimension · BOM · note changes and the changed regions |
The "upper/lower limit" column in the dimensions table. For each dimension, it also records where the allowed range came from.
| What the cell shows | Meaning |
|---|---|
| «lower ~ upper» values + (formula) | An estimate produced by the ISO fit formula from the fit symbol on the drawing (e.g. H7) — it may differ from the standard tables by micrometers |
| «lower ~ upper» values + (drawing) | The ± value written on the drawing, as-is |
| Not calculated | Not calculated — hover to see why |
| General tolerance … | The general tolerance grade the drawing specifies for untoleranced dimensions (no figures are derived) |
If any «formula» value is present, the note "«formula» values are ISO fit estimates — … confirm accept/reject decisions against your own copy of the standard." appears below the table.
GD&T frame check card. Checks whether the GD&T frames on the drawing conform to the rules. The header shows the drawing's general tolerance specification and the datum letters, and each row gives the severity (error · warning · info) · the target letter · the finding · the basis (standard number · concept name). Clicking a row tied to a dimension highlights that dimension in the image. If no frame violates a rule: "No frames violate the rules."
Guidance cards. Below the drop zone, "What was read from this drawing?"; below the comparison test, "What changed between the two revisions?" Both tell you what · when · how to read. The key points:
- RAG's drawing indexing uses these same readings. A dimension missing here is also unknown to RAG.
- Drawings uploaded here are shown and discarded. They are not indexed into RAG — indexed drawings are in the drawing register.
- Scanned PDFs with no text layer yield no text for that page. This reader does not perform OCR.
- If a comparison shows no changes at all, either the two revisions are identical or the comparison failed — tell them apart with the Could not compare list and the confidence value.
Title block not found · No text layer (scanned page) · Zone grid defaulted (no border ticks) tell you «how it was read». Scanned PDFs have no text layer, so dimensions cannot be read.
Files outside the accepted formats are rejected by the service with a reason. For DWG, export to DXF or PDF from your CAD tool and upload that.
Vision check — /vision/
Upload one image to confirm what the vision service actually sees.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and the service this screen calls |
| ② | Request | Pick an operation (Inspection · Gauge reading · Text extraction · Classification · Free question · Object detection), upload an image, and press Run |
| ③ | Guidance card | What the selected operation does and how to read the result (Details / Collapse) |
Running it produces a samples · agreed · disagreed summary row and Image · Result cards. For object detection, boxes are drawn on the image.
The vision service asks the model several times and returns a result only when enough answers agree (usually 2 of 3; 4 of 5 for gauge reading). When answers diverge it returns Cannot determine rather than inventing a value. Pressing again gives the same answer, so retake the photo. Free question does not go through this agreement check, so do not use it for readings or verdicts.
Integration map — /thread/
Shows how the digital thread is wired to external systems, on one map. For connector registration, field binding, and synchronization procedures, see Digital Thread.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | View buttons (Map · List · Readiness sources), Add connector (four registration steps in a side panel), refresh |
| ② | Summary row | Connectors · Enabled · Conformance failures · Tools — how many integrations are alive |
| ③ | Map | A filter row (family · status) and the map. External system → connector → tool → binding → plant graph, left to right. Green = enabled, red = conformance failure, gray = disabled. Clicking a node opens its configuration, conformance results, and recent action calls in a side panel, and the map highlights only that node's chain |
Working the map:
- It opens at 1× scale, centered. Connectors are laid out with family order ERP → MES → PLM → SCM → scheduling first, then the remaining families alphabetically.
- Drag to pan, wheel to scroll vertically, Ctrl+wheel to zoom. The buttons at the top right are zoom in · zoom out · fit all.
- The filter row above the map narrows connectors by family · status (map only). Clear filters restores it.
- The minimap is hidden by default. Turn it on with Show minimap in the control buttons.
- If there are too many connectors to read the map, switch to List for a table — Name · Family · System · Endpoint · Status · Level · Tools · Credentials · Conformance.
- The family list in Add connector initially shows
erp·mes·plm·scm·sched·qm.
Sync now in a connector's side panel immediately loads that connector's bindings into the mirror and closes links that disappeared at the source (it does not delete them; it records an end time — the link history is built from that). When it finishes, "Synchronized N objects · N links" appears. If the list the connector returned was truncated, a yellow line also appears: "This sync did not close disappeared links — collection was truncated (…). They will be closed by a sync that reads to the end." — closing links from a truncated list would close healthy links too. Enabled connectors are also synchronized on a schedule by the service → Digital Thread — connector synchronization
Connector registration, modification, deletion, discovery, testing, synchronization, and field binding are recorded in the console audit log (thread.write) under the logged-in administrator's name. Action tools (🔒) are never called from the console — the copilot relays them through approved proposal cards.
Readiness sources — the third view of the integration map
Shows, from the operator's side, what the copilot's supervisor job readiness (Go/No-Go per operation) bases its verdict on. The verdict itself (which operation is blocked) is not here; it is on the copilot screen. What you see here is «which connector feeds each item, whether that data is fresh, and what happens to the verdict if it is missing». The view button appears only when the digital thread service is a release that provides this feature.
| No. | Location | What it does |
|---|---|---|
| ① | Header row | The last verdict time and state (Judged · Stale source — verdict halted · No MES — not judged), and Re-measure now |
| ② | Item · Wiring | For each of eight items: Wired (green) · Partially wired (amber) · None (gray) |
| ③ | Source (family · tool → connector) | For each input: required · either-or · optional, which tool of which family reads it, and the name of the connector providing that tool. If the data is older than the limit, an amber Stale badge is attached. Clicking a connector name returns to the map and opens that connector's side panel |
| ④ | If missing | What the verdict becomes without the source — verdict «unknown», or, with no MES work order, no verdict is made at all. Each input carries a line saying what you lose (e.g. "material shortages are unknown — materials become unknown"). Inputs that actually could not be read in the most recent verdict are marked «could not read in the latest verdict» |
The eight items and the families that feed them (the source of truth is a single declaration in the digital thread service; the verdict and this screen read the same declaration):
| Item | Source read |
|---|---|
| (foundation) | MES work order — without it, no item is judged |
| Preceding operation | MES work order |
| Materials | SCM shortages (or the equivalent tool from MES if absent) |
| Tooling · calibration | Tool management (per-job tool list — required, tool register — optional) |
| Personnel · qualifications | MES operation qualification requirements + ERP personnel (or MES personnel if absent) |
| Permits · isolation | Safety (EHS) work permit (required) · isolation (optional) |
| Quality holds | Quality (QM) nonconformance (or MES nonconformance if absent) |
| Equipment maintenance | At least one of maintenance (CMMS) PM windows · maintenance work orders |
| Drawing revision | PLM engineering change (required) · PLM BOM (optional) · workstation drawings (digital thread mirror — drawings indexed by RAG) |
- Freshness is measured against the last verdict. With no verdict on record, "No verdict recorded yet" appears — Re-measure now runs a verdict once (read-only) and re-measures.
- The freshness limit differs by family → Digital Thread — when data goes stale
- A connector's side panel on the map also has a Readiness items row showing which items that connector feeds.
The verdict is not wrong — the sources are not wired. Find the items marked None (gray) here and attach a connector from that family. «Unknown» is not GO — items with a missing source are never counted as passing.
Graph mirror — /thread/mirror/
Shows the status of periodically copying (projecting) the platform ledger and learned edges into the plant graph. Read-only. For details see Digital Thread.
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and refresh |
| ② | Summary row | Projection · Last success · Dt objects · Projected links — whether projection is succeeding on time |
| ③ | Last run | Finish time · run number · consecutive failures · per-stage results — find which stage failed |
| ④ | What is in the mirror | Source and count per item — what is mirrored and how much |
MCP Gateway — /mcp-gateway/
The gateway that every MCP tool the AI calls passes through. It gathers the tools of the platform integration MCP, this installation's AI services (Timeseries Insight · RAG · Document Understanding · Vision · Digital Thread · Engineering Calculation), and the external MCP servers the operator has attached, and serves them at a single address (plantpulse-mcp-gateway-api:7160/mcp/).
The copilot looks only at this one address, and turning tools on and off is also done here (2026.10 re-release (2026-10-20) — before that it was the Tool Servers (MCP) screen in the Copilot Admin Console).
| Screen | Address | What it does |
|---|---|---|
| Overview | /mcp-gateway/ | Gateway status (database · embedding · platform MCP · MCP servers), server summary, calls · errors · latency p95 · searches over the last 24 hours |
| Servers | /mcp-gateway/servers/ | The servers behind the gateway — kind (Platform · Built-in · External) · prefix · status · number of enabled tools · authentication · circuit · last discovery. Rediscover · Enable/Disable, and for external servers Register server · Edit · Authentication · Delete |
| Tools | /mcp-gateway/tools/ | Every discovered tool — exposed name · server · description · search terms and their source · status · search index. The place to turn each tool on and off; you can also override the description (4000 characters) and the search terms → Tool search terms |
| Permissions | /mcp-gateway/permissions/ | Which caller (the copilot · each issued key) sees which server's tools |
| Client API Keys | /mcp-gateway/client-keys/ | Issue · scope · revoke keys (ppgw_…) for external MCP clients (other agents · desktop apps) |
| Search Test Bench | /mcp-gateway/search/ | Enter one question and see the tools the gateway would give the model — score · lexical rank · embedding rank · reason for selection |
| Search Settings | /mcp-gateway/search-settings/ | Tool search on/off · budget (number of tools given per turn) · family guarantee · dependency expansion |
| Calls & Metrics | /mcp-gateway/calls/ | Call counts by server · error, and for each call the time · caller · server · tool · result (Succeeded · Tool failed · Transport failed) · duration · result size → Call log |
Tool on/off — the initial value is set by policy
When a tool is first discovered, it comes in enabled or disabled according to the gateway policy. After that, the value you change on the Tools screen stays, and neither a restart nor an upgrade overwrites it.
| Server | Initially |
|---|---|
| Platform integration MCP | All on |
| Timeseries Insight | 34 on · 4 off · 1 write tool that cannot be enabled |
| Digital Thread | 9 on |
| Engineering Calculation | 4 on |
| RAG · Document Understanding · Vision | On (all 2 · 2 · 5) — if you turn off document search rag_search, chat cannot find documents |
| External servers | Off |
The per-tool list is in the MCP tool map.
- Some tools cannot be enabled — tools suspected of writing (they declare
readOnlyHint=false, or their name · description indicates a write) and connector tools (mes_·erp_…) served by a server other than Digital Thread. Platform tools are not blocked by the gateway; if they write, the copilot's approval gate gets a person's approval. - If two servers expose the same name, the one registered first wins and the later one is not exposed, marked «conflict». Change the later server's prefix.
- An overridden description changes both the description the model reads and the search index. Clear it to go back to the server's original description.
Attaching an external MCP server
- Servers › Register server — name · Streamable HTTP address · tool prefix (lowercase · digits, ending in
_, required) · call time limit (1–600 seconds, default 120). The server is created disabled and allowed to no one. - If authentication is needed, enter the header name and value under Authentication. The value is sealed and never shown again (only «Set»).
- Enable → Rediscover. External tools come in disabled. 🔴 An external tool's description and arguments go into the model prompt as-is, so read them on the Tools screen and enable each tool. If the definition of an enabled external tool changes, the gateway disables that tool and flags it for review.
- Under Permissions, allow that server or tool for the copilot (or an issued key).
- External tools are passed to the copilot as write tools — the copilot does not call them without a person's approval.
- If the address resolves to a loopback · link-local · cloud metadata address, it will not attach. Internal networks (10/8 · 172.16/12 · 192.168/16) are fine.
- Platform · Built-in servers are determined by the installation, so they can only be disabled; they cannot be edited or deleted.
- 🔴 External system connectors such as MES · ERP · PLM are attached not here but on the Integration map.
Permissions and client API keys
- Built-in servers are allowed for the copilot with all tools from the start. «All tools» includes tools discovered later.
- New external servers and new keys are created with nothing allowed. If «not a single tool shows up», check Permissions first.
- A key's plaintext is shown only once, when it is issued. The list keeps only the first 12 characters. Revocation takes effect immediately.
- A key is given a scope (equipment · site · project · customer PO · supplier) and a grade. A key without a scope can call only external server tools, and built-in tools read narrowed to that scope · grade. Platform tools can be called only by keys whose scope is the whole installation (the platform does not filter by scope).
- These keys are used only for
/mcp/. This is a different screen from API keys in the common menu. - The address external MCP clients connect to is
https://<호스트>/mcp/gateway/→ API Integration Guide
Tool search — on by default, budget 20
Instead of loading every enabled tool for every question, the gateway picks only the ones that fit the question and gives them to the copilot. The initial values are on · budget 20 · family guarantee on · dependency expansion on.
search_domains, which finds IDs by name, and document search rag_search are always loaded regardless of the budget (when allowed for that account).
- If you turn it off in Search Settings, the copilot receives all allowed tools — with 70-some tools, the model often fails to pick. The bar for turning it on is recall@20 of 0.95 or higher in offline evaluation; if you try to turn it on below the bar, the screen warns you (it does not block you).
- The values an operator changes and saves win — upgrading does not reset them to defaults.
- 🔴 Search depends on the embedding service. If embedding is down, search returns
503 search_unavailableand there is no fallback path — check «Embedding» on the Overview. - The Search Test Bench produces rankings even when search is off. Use it to see «why this tool was not called for this question».
Tool search terms — the words that link Korean questions to tools
Tool descriptions are in English, so a Korean question such as «알람 확인 처리» (handle alarm acknowledgement) is linked to a tool through its search terms. Search terms are used only in keyword search (BM25); they are not embedded and are not shown to the model. On the Tools screen, below the description column, each tool shows the search terms it currently uses and their source.
| Source | Meaning |
|---|---|
| This install | An operator of this installation overrode them — wins over the three below |
| Server declared | The MCP server declared them along with the tool (Timeseries Insight · Digital Thread · Engineering Calculation · RAG · Document Understanding · Vision) |
| Gateway default | The value the gateway attaches for a server that does not declare its own (the platform integration MCP) |
| No search terms | Indexed by name and description only |
- Search terms are shown in full, never truncated. Read the search terms an external server declares, too, before turning its tools on.
- The Search terms button edits the Korean (ko) search terms, one per line (or comma-separated). Search terms in other languages are kept as they are and shown in the same dialog.
- 🔴 The limits per tool are 4 languages, and 8 terms · 64 characters across all languages together. Beyond that, the save button is locked.
- If you change nothing, the save button is locked — this prevents a copy of the server's value from freezing into an override and later hiding a value the server changes.
- Saving it empty means the tool has «no Korean search terms». Remove override, in the «This install overrides the search terms.» strip at the top of the dialog, goes back to the server declaration · gateway default. They are two different buttons.
- Search terms a server sent in the wrong shape or over the limits, and a stored override discarded for exceeding the limits, show their reason on a warning line (a discarded value is treated as absent and the next source applies). A discarded override is also cleared with Remove override.
- The search box at the top of the screen filters by name · description · search terms together. If the search terms of an enabled external tool change, the gateway treats it as a changed definition and turns that tool off.
When this happens
| Symptom | What to check |
|---|---|
| Server status is «Down» | The circuit on Servers (after 3 consecutive failures it is not called for 120 seconds) and the discovery error |
| External server shows «Warning», authentication «Not set» | An authentication header is defined but has no value — enter it again under Authentication |
Call ends in upstream_auth | That server returned 401/403 — check the authentication value |
Call ends in result_too_large | The result exceeded 1 MiB |
| No tools visible with an issued key | A new key has no permissions — Permissions |
| A question asked in Korean does not load the right tool | Enter that question in the Search Test Bench to see the ranking, and look at that tool's search terms and source on the Tools screen → Tool search terms |
| Call is «Tool failed» but the server is fine | The backend answered but the result is a failure — look at the tool result (arguments · source data), not the server → Call log |
Calls with an issued key end in forbidden_scope | That key has no scope, or it is a platform tool and the scope is not the whole installation — Client API Keys |
Call log — tool failures and transport failures
Calls & Metrics has three results. The error count includes tool failures and is split beside it as «tool N · transport N». The per-server table also has a Tool failed column.
| Result | Meaning |
|---|---|
| Succeeded | The tool answered and the result is a success too |
| Tool failed | The backend server answered but the result is a failure — isError, a non-empty error, {"ok": false}, error_code with status: "error" (the same rule the copilot uses to treat a result as a failure) |
| Transport failed | The call never reached the backend, or the gateway blocked it — the Error code is the reason |
The Result filter is All · Succeeded · Failed (any) · Tool failed. If «the server is fine but the answers are strange», filter by Tool failed.
The call log does not keep arguments · results · authentication values. «Who asked what», per person, is in the copilot's audit log → Copilot administration
Automation Sandbox — /sandbox/
The screens of the service that runs the Python code of automation steps (processing earlier steps' tool results with numpy · pandas · scipy and producing JSON · tables · figures · text). On the rail it is Automation Sandbox, separate from MCP Gateway. The console only reads — runs are made by the copilot's approved automation plans, and writes from the console to the sandbox are blocked.
The sandbox container itself runs on gVisor (runsc), and for each run it starts an isolated process inside it with new namespaces (user · net · pid · mount). It does not start a new gVisor per run. Inside a run there is no network, so it cannot call tools or REST, and the root file system is read-only.
| Screen | Address | What it does |
|---|---|---|
| Overview | /sandbox/ | Isolation (gVisor version · platform · architecture · network, last self-test), Running · Queued, Executed · Errors · Turned away per period, run counts by result code |
| Run History | /sandbox/runs/ | For each run: received time · result · error code · code SHA-256 · size · queue wait · elapsed. Expand it for input · output sizes · limits · context. Kept 30 days by default |
| Run limits | /sandbox/limits/ | Per-run limits (time · memory, code · inputs · outputs · tables · figures · /tmp · processes), concurrency · queue limits, importable packages and their versions. These are the values the sandbox actually enforces |
There are three results: Succeeded · Error · Turned away. Turned away is a request that was not run; its elapsed time in Run History is «—».
| Code | Result | Meaning |
|---|---|---|
ok | Succeeded | Finished and returned outputs |
syntax | Error | The code did not compile — nothing ran |
forbidden | Error | Tried something the calculation step may not do (network · processes · native code · files outside /tmp) |
timeout | Error | Exceeded the wall-clock or CPU limit |
memory | Error | Exceeded the memory limit |
output_too_large | Error | Output · table · figure · /tmp exceeded its cap |
runtime | Error | Any other exception, or the outputs could not become JSON |
queue_full | Turned away | The queue was full |
queue_timeout | Turned away | Waited too long for a free slot |
sandbox_unavailable | Turned away | The isolation could not be set up — the code was not run |
- 🔴 The code text is not here. The sandbox keeps no code · inputs · outputs, only their sizes and the code SHA-256. The text is in the copilot's approved plan with the same hash.
- If
sandbox_unavailablepiles up or the overview shows «The isolation self-test failed», isolation setup is failing. Check the runtime version and last self-test under Overview › Isolation, and the sandbox's Logs. - If «Run records are not being stored» appears, the run record store (PostgreSQL) cannot be written. Runs continue, but runs during that time are missing from the records and counts.
- The common menu is API endpoints · Logs · API keys · Settings. The sandbox has no MCP server, so there is no MCP server info.
Common menu
Five screens that are identical across the six services RAG API · Timeseries Insight · Document Parsing · Vision · Digital Thread · MCP Gateway. The <service> slot in the address is rag · insight · parser · vision · thread · mcp-gateway. The images are from RAG API.
Automation Sandbox (sandbox) has the same four, minus MCP server info.
MCP server info — /(service)/mcp-info/
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | This service's MCP address and a summary (tool · resource · prompt counts) — filled in live by querying the service directly |
| ② | Tool table | The tools the AI copilot can call — Tool · Description · Parameters. Clicking a row expands each parameter's type · required · default |
Below come the Resources · Prompts tables.
An MCP server with no tools at all should be read not as «no tools» but as a failure to read the list.
API endpoints — /(service)/api-endpoints/
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Endpoint count and description — built from the service's OpenAPI schema |
| ② | Table | Method · Path · Description · Domain — integration developers find the API to call |
MCP endpoints (POST /mcp) are not in the OpenAPI schema — see MCP server info.
Logs — /(service)/logs/
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Auto 5s (reloads every 5 seconds while on) · refresh |
| ② | Header row | The log file being read · size · record count — whether the file is empty or has corrupted lines |
| ③ | Log tail | The tail of the log file, newest on top — Time · Level · Event · Fields |
You can narrow by line count · level · search term (Enter) at the top of the screen. No need to SSH in and run docker logs.
API keys — /(service)/api-keys/
Measures whether inbound API key authentication is actually enabled on this service. It is not a screen for viewing key «values».
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Screen name and Run check — only when pressed does it call twice, once without a key and once with one |
| ② | Summary row | Console key (whether the console holds a key, and its fingerprint) · Authentication (check result) · Shared across services (whether several services use the same key) |
| ③ | Round trip | Response codes without a key · with a key, plus the verdict and its meaning — a closed service answers 401 then 200 |
| ④ | Wiring | Per service: console env var · service env var · key · upstream — under which name the key goes where. Pressing the eye icon beside a fingerprint reveals the plaintext, and that action is recorded in the audit log with the username |
| ⑤ | Note below the table | The key callers must send in X-API-Key, and which env var holds it in the console and in the service |
| Verdict | Meaning |
|---|---|
| Enforced | Rejects keyless calls and accepts the console's key — correct |
| Open | Responds without a key — anyone who can reach the route can access it |
| Not enforced | The console holds a key, but the service responds without one |
| Key mismatch | The service is closed but rejects the key the console holds |
| No console key | The service is closed but the console has no key |
| Unreachable | The service did not answer — this is not a «pass» |
The five services refuse to start if the inbound key (PI_INBOUND_API_KEY) is empty. The only exception is deliberately disabling authentication by setting PI_INBOUND_AUTH_DISABLED=true in the install env, in which case the service comes up with no key — and the container reports healthy, so there is no signal. That is why you press Run check to measure it — so that merely opening the screen does not pile up 401s on the service. If it responds without a key (Open), a warning box appears above the table. The check deliberately sends one keyless request, so alerts watching for 401s may fire → API integration guide — inbound keys
Settings — /(service)/config/
| No. | Location | What it does |
|---|---|---|
| ① | Top of screen | Key count and refresh |
| ② | Component table | Per component the service uses: status · endpoint — find which dependency is down |
| ③ | Settings table | The runtime settings currently in effect, key · value — sensitive values such as passwords and tokens are masked |
It only displays values; it cannot change them. To actually change them, see Changing passwords and API keys and Service operations.
When this happens, do this
| Symptom | Look here first | Then |
|---|---|---|
| The chatbot cannot find a document | RAG API → Documents | Search directly with Query test → Sync history |
| Chatbot answers are slow | P95 on the LLM dashboard | GPU utilization and temperature |
| A model does not answer | LLM → Upstream status | LLM → Chat test, once by hand |
| Analysis results are empty | Timeseries Insight → Pipeline status | The failures in Run history |
| Checking the backend is not open without authentication | That service → API keys → Run check | Changing passwords and API keys |
… rejected the console's inbound API key (401) - check <환경변수> on screen | The service's key differs from the one the console holds (error reason upstream_auth, 502) | That service → the Wiring table under API keys → align the env var named in the message and restart the console |
An LLM screen (API keys · logs · model registration, etc.) returns 502 with reason llm_upstream | The gateway (LiteLLM) or its DB returned a 5xx. This is not a console fault — upstream_status is the gateway's status code | docker compose logs plantpulse-litellm → Troubleshooting |
| "Connector registry unavailable: 503 … config_error …" on the integration map | The digital thread's registry store (DT_PG_*) or encryption key (DT_SECRET_KEY) is empty | Ask your administrator to configure it. The graph mirror runs independently of this |
| "Drawing indexing is off" in the drawing register | DRAWING_INGEST_ENABLED is off in rag-api (the shipping default) | Turn it on per Configuration and restart rag-api |
| "Video/audio ingestion is off" on the Videos screen · video upload blocked | PI_MEDIA_ENABLED is not enabled in the install env (off by default) | Turn it on per Configuration and recreate the stack |
| An uploaded video sits in Pending for a long time | It is outside the processing window — the processing window line on the Videos screen states the next start time | To change the window, MEDIA_PROCESSING_WINDOW → Configuration |
| Chat does not use a video as evidence | RAG API → Videos → Empty transcript · Missing from search | Expand the row and Re-transcribe as instructed |
| Every Revision status in the drawing register is Unverified | There is no PLM connector to query for revisions, or it does not answer | Digital Thread → Integration map to check the PLM connector is enabled → Digital Thread |
| Supervisor readiness is full of «unknown» | The source connectors for those items are not attached, or the data is stale | Digital Thread → Integration map → Readiness sources |
| A yellow light on Home | Expand Details and read the tooltip | That service → Logs |
| A red light on Home | That service → Logs | The restart procedure in Service operations |
| The screen is blank with an error banner | That service may not be up yet | Check status on Home |
If a service rejects the console's key, the console does not treat that as an expired session — it shows a single error line (502, upstream_auth). Logging in again will not fix it, so check the env var named in the message.
When the console cannot fetch data it shows an error banner rather than faking an empty table. If you see an error banner, there is no missing data — the connection failed.
Accounts and sessions
The console account is defined by environment variables, not a database (/etc/kopens/plantpulse-ai.env).
| Environment variable | Meaning | Default |
|---|---|---|
PI_ADMIN_USER | Login username | admin |
PI_ADMIN_PASSWORD | Login password | None — must be set |
PI_ADMIN_SESSION_SECRET | Session signing key | Generated by the installer |
ADMIN_SESSION_MAX_AGE | Session lifetime (minutes) | 480 (8 hours) |
Inside the container they appear under the names ADMIN_AUTH_USERNAME · ADMIN_AUTH_PASSWORD · ADMIN_SESSION_SECRET, but compose simply copies the values above in, so edit the PI_* side.
Leaving PI_ADMIN_PASSWORD empty makes the console refuse to start. This is intended behavior, meant to prevent an unauthenticated admin portal from sitting quietly open.
If PI_ADMIN_SESSION_SECRET changes, every existing login is invalidated. Leave the value the installer generated as-is and logins survive restarts.
bin/passwd.shThe console account is not in the list of keys managed by bin/passwd.sh (see the table in Changing passwords and API keys). To change it you must edit the env file directly and restart the service. Ask your administrator.
Related documents
- Service port map — the console address and where each service listens
- Service operations — start, stop, and restart procedures
- Changing passwords and API keys — key rotation
- Logging and monitoring — reading logs directly on the server
- Digital Thread — concepts behind the integration map, graph mirror, and readiness sources, plus connector registration
- Configuration — the drawing indexing and video/audio ingestion switches (
DRAWING_INGEST_ENABLED·PI_MEDIA_ENABLED) and the processing window (MEDIA_PROCESSING_WINDOW) - Video search — how indexed videos are used in chat
- Copilot administration — where action tool approvals happen
- MCP tool map — each server's tools and which ones are on at first