View Source

<ac:layout><ac:layout-section ac:type="single"><ac:layout-cell>Reference for configuring the Local AI endpoint, master enable, tool-category bits, and pointing at alternative LLM endpoints (cloud or alternate local).<ac:link><ri:page ri:content-title="AI Integration" /></ac:link> → <ac:link><ri:page ri:content-title="Local AI" /></ac:link> → Configuration (10.1.5 draft)<hr /></ac:layout-cell></ac:layout-section><ac:layout-section ac:type="single"><ac:layout-cell><ac:structured-macro ac:name="info" ac:schema-version="1"><ac:rich-text-body>10.1.5 draft. This page documents Local AI configuration as it ships in FrameworX 10.1.5. Content may change before GA.</ac:rich-text-body></ac:structured-macro><h2>Where the configuration lives</h2>Local AI reads its full configuration from three columns on the existing <code>SolutionSettings</code> table. No new tables, no new columns — one solution has one Local AI configuration.<table><tbody><tr><th>Column</th><th>Type</th><th>Role</th><th>Default</th></tr><tr><td><code>ModelEnabled</code></td><td>Boolean</td><td>Master kill-switch for ALL Local AI features in this solution. When <code>false</code>, every <code>ChatRequest</code> action and every <code>TK.AIExecute</code> call short-circuits with <code>status="disabled"</code>.</td><td><code>false</code> — off until customer opts in</td></tr><tr><td><code>ModelSettings</code></td><td>String (JSON blob)</td><td>Five-key endpoint configuration: <code>URL</code>, <code>Name</code>, <code>Authorization</code>, <code>Headers</code>, <code>Info</code>.</td><td><code>NULL</code> — defaults apply (local Ollama + <code>qwen2.5:7b-instruct</code>)</td></tr><tr><td><code>ModelOptions</code></td><td>Int (bitmask)</td><td>Master tool-surface bit and per-category tool-enable sub-bits. Same bitmask the AI Runtime Connector reads.</td><td><code>0</code> — no tools exposed; <code>ChatRequest</code> returns <code>disabled</code> until master bit is set</td></tr></tbody></table><h2>Editing in the Designer</h2>The Local AI configuration is edited from the Local AI tile on the Data Servers page (sibling of the OPC UA, DataHub, MQTT Broker, and MCP for Runtime tiles).<ul><li>Enable Local AI checkbox — toggles <code>ModelEnabled</code>. Master kill-switch.</li><li>Status indicator — reachability probe against the configured endpoint URL. Cached for 30 seconds.</li><li>Endpoint URL — read-only display of the resolved URL.</li><li>Settings link — opens the structured 5-field editor for <code>ModelSettings</code>.</li><li>Model name — read-only display of the configured <code>Name</code> field.</li></ul><h2>The <code>ModelSettings</code> JSON</h2>Five fields, all defensive — an empty/missing/malformed <code>ModelSettings</code> column transparently resolves to defaults. Unknown extra keys are preserved across edit cycles, so future revisions stay forward-compatible.<ac:structured-macro ac:name="code" ac:schema-version="1"><ac:parameter ac:name="language">json</ac:parameter><ac:plain-text-body>BODY1</ac:plain-text-body></ac:structured-macro><table><tbody><tr><th>Key</th><th>Default</th><th>Notes</th></tr><tr><td><code>URL</code></td><td><code>http://localhost:11434/v1/chat/completions</code></td><td>Must speak OpenAI-compatible chat-completions JSON. Local Ollama, LM Studio (in OpenAI mode), vLLM, llama.cpp’s server, or any cloud endpoint that conforms.</td></tr><tr><td><code>Name</code></td><td><code>qwen2.5:7b-instruct</code></td><td>Goes into the POST body’s <code>"model"</code> field. Must match a model the configured endpoint can serve.</td></tr><tr><td><code>Authorization</code></td><td><code>None</code></td><td>Multi-line wire format. Line 1 = scheme (<code>None</code> / <code>BearerToken</code> / <code>BasicAuth</code> / <code>CustomAuth</code>); subsequent lines carry the value. Accepts <code>/secret:<Name></code> tokens for SecuritySecrets resolution. See SecuritySecrets Authentication for Local AI.</td></tr><tr><td><code>Headers</code></td><td>empty</td><td>Multi-line <code>key: value</code> per line. Same format the WebData connector uses for custom HTTP headers. Accepts <code>/secret:<Name></code> tokens.</td></tr><tr><td><code>Info</code></td><td>self-documenting block</td><td>Free-text description visible to anyone editing the configuration. Distinct from <code>SolutionSettings.Description</code>.</td></tr></tbody></table>The configuration is parsed defensively on every Local AI call — the parse cost is negligible compared with the LLM round-trip, and there is no caching layer to invalidate when the JSON changes.<h2>The <code>ModelOptions</code> bitmask</h2>An integer column carrying independent enable bits. The bitmask is shared with the AI Runtime Connector and the AI Designer connector — the same bits gate the same tool categories regardless of which transport the LLM uses to call them.<table><tbody><tr><th>Bit</th><th>Name</th><th>Effect when ON</th></tr><tr><td><code>0x02</code></td><td><code>EnableRuntimeMCP</code> (master)</td><td>Master enable for the AI tool surface. Required for the <code>ChatRequest</code> action to call any tools. When OFF, <code>ChatRequest</code> returns <code>status="disabled"</code>. <code>TK.AIExecute</code> is unaffected by this bit (atomic calls have no tools).</td></tr><tr><td><code>0x04</code></td><td><code>EnableUnsTools</code></td><td>The LLM may read tag values, browse the namespace, and search the UNS during a chat turn.</td></tr><tr><td><code>0x08</code></td><td><code>EnableAlarmTools</code></td><td>The LLM may read active alarms and query the alarm history.</td></tr><tr><td><code>0x10</code></td><td><code>EnableHistorianTools</code></td><td>The LLM may query historian time-series data.</td></tr><tr><td><code>0x20</code></td><td><code>EnableCustomTools</code></td><td>The LLM may call solution-authored MCP Tool class methods.</td></tr><tr><td><code>0x40</code></td><td><code>EnableDesignerMCP</code></td><td>Reserved for the AI Designer connector. Do not reuse for Local AI features.</td></tr><tr><td><code>0x80</code></td><td><code>EnableChatHistory</code></td><td>Per-Display-panel transcript cache participates in <code>ChatRequest</code> calls. Default ON in new 10.1.5 solutions. <code>TK.AIExecute</code> always bypasses the cache regardless of this bit.</td></tr></tbody></table>The five tool-category bits (<code>0x04</code>–<code>0x20</code>) are AND-gated against the master bit. A category bit ON without the master bit ON leaves the category effectively OFF.<h2>Master gate order</h2>Both consumer paths apply the gates in a fixed order:<ol><li><code>ModelEnabled</code> — if <code>false</code>, return <code>status="disabled"</code> immediately. No HTTP traffic. <code>latencyMs = 0</code>.</li><li><code>ModelOptions</code> bit <code>0x02</code> — <code>ChatRequest</code> only: if the master tool-surface bit is OFF, return <code>status="disabled"</code>. <code>TK.AIExecute</code> skips this gate (no tools to expose).</li><li>Per-category bits — <code>ChatRequest</code> only: AND-ed against the master bit when assembling the tool catalog the LLM sees during a chat turn.</li></ol><h2>Pointing at a different LLM endpoint</h2>Replace the <code>URL</code> and <code>Name</code> fields. Any OpenAI-compatible chat-completions endpoint works.<h3>Local Ollama (default)</h3><ac:structured-macro ac:name="code" ac:schema-version="1"><ac:parameter ac:name="language">json</ac:parameter><ac:plain-text-body>BODY2</ac:plain-text-body></ac:structured-macro><h3>Remote Ollama on a GPU server</h3><ac:structured-macro ac:name="code" ac:schema-version="1"><ac:parameter ac:name="language">json</ac:parameter><ac:plain-text-body>BODY3</ac:plain-text-body></ac:structured-macro>The remote Ollama must be started with <code>OLLAMA_HOST=0.0.0.0:11434</code> and the firewall opened on TCP 11434.<h3>OpenAI-compatible cloud endpoint with Bearer token</h3><ac:structured-macro ac:name="code" ac:schema-version="1"><ac:parameter ac:name="language">json</ac:parameter><ac:plain-text-body>BODY4</ac:plain-text-body></ac:structured-macro>The <code>/secret:CloudLLMApiKey</code> token resolves at call time from the SecuritySecrets vault — the actual API key never appears in the configuration. See SecuritySecrets Authentication for Local AI.<h3>Endpoint with extra HTTP headers</h3>Some providers require extra request headers (organization ID, project ID, region). Add them via the <code>Headers</code> field, one <code>Key: Value</code> pair per line:<ac:structured-macro ac:name="code" ac:schema-version="1"><ac:parameter ac:name="language">json</ac:parameter><ac:plain-text-body>BODY5</ac:plain-text-body></ac:structured-macro>Header values also accept <code>/secret:<Name></code> tokens.<h2>Configuration safety nets</h2>The platform applies several safety nets to prevent silent misconfiguration:<ul><li>Defensive defaults. Empty / null / malformed <code>ModelSettings</code> falls back to the recommended local Ollama defaults. A solution with a corrupted JSON blob still works against the local default.</li><li>Status probe. The Local AI tile in the Designer probes the resolved URL on a 30-second cache, surfacing a red indicator when the endpoint is unreachable. Use it before deploying.</li><li>Master kill-switch precedes everything. A solution can be staged with full configuration and shipped with <code>ModelEnabled = false</code>. No LLM traffic flows until the customer toggles it ON.</li><li>Off-server short-circuit. Secret resolution is a server-side operation. Calls reaching Local AI from a thin-client context cannot resolve secrets and fall through to a normal HTTP error reply — no silent unauthenticated POST.</li></ul><h2>What this page does NOT cover</h2><ul><li>Bringing up Local AI on a fresh machine. See <ac:link><ri:page ri:content-title="Local AI - First Install Walkthrough (10.1.5 draft)" /></ac:link>.</li><li>SecuritySecrets reference syntax and examples. See SecuritySecrets Authentication for Local AI.</li><li>Reply envelope shape and status semantics. See Local AI Reply Envelope Schema.</li><li>The <code>ChatRequest</code> Display action. See ChatRequest Action Reference.</li><li>The <code>TK.AIExecute</code> script API. See TK.AIExecute API Reference.</li></ul><hr /><h4>In this section...</h4><ac:structured-macro ac:name="pagetree" ac:schema-version="1"><ac:parameter ac:name="root"><ac:link><ri:page ri:content-title="@parent" /></ac:link></ac:parameter></ac:structured-macro></ac:layout-cell></ac:layout-section></ac:layout>