Local AI Architecture Reference (10.1.5 draft)

Architectural reference for the Local AI capability in FrameworX 10.1.5: the two-path execution model, code organization, master-gate semantics, transcript cache mechanics, tool dispatch loop, and integration points with the rest of the platform.

Technical Reference → Platform Architecture Reference → Local AI Architecture Reference (10.1.5 draft)

Audience and scope

This page is for system integrators, custom-driver authors, OEM partners, and engineers who need to reason about how Local AI is composed inside the FrameworX runtime: which assembly hosts what, which thread runs which work, where gates apply, and which contracts must be honoured when extending or wrapping Local AI.

End users configuring Local AI from the Designer or wiring a chat panel from a Display do not need this page. See Local AI and the user-facing reference children there.

Capability summary

Local AI exposes one platform capability — calling an OpenAI-compatible LLM from inside a FrameworX solution — through two architecturally independent consumer paths:

Both paths POST to the same OpenAI-compatible endpoint, configured once per solution on three columns of SolutionSettings. Both paths return the same reply envelope (see Local AI Reply Envelope Schema (10.1.5 draft)).

Two-path model — what is shared and what is divergent

The two paths are deliberately independent code paths sharing a small set of explicit anchors. Code duplication is welcomed where the alternative would be a shared helper that couples them.

Shared by architecture (legitimate coupling)

• The endpoint configuration — both paths read SolutionSettings.ModelSettings JSON via the same defensive accessors on the Local AI service singleton.
• The master kill-switch — both paths check SolutionSettings.ModelEnabled at entry and short-circuit identically when off.
• The SecuritySecrets resolver — both paths invoke Security.CheckAndResolveSecretCommConfiguration on resolved auth strings; this is a Kernel-side platform service, not a path-specific helper.
• The reply envelope schema — both paths produce the same five-field JSON shape (text, status, toolTrace, latencyMs, warnings).
• The auth multi-line decoder — both paths call the platform's pre-existing ReportWebData.DecodeAuthorizationHeader static, which is the single source of truth for the None / BearerToken / BasicAuth / CustomAuth wire format.

Divergent by design

Code organization

Assembly home and the namespace-contribution rule

Local AI is implemented in its own peer assembly, T.LocalAI.dll, sibling to T.Modules.dll and T.Toolkit.dll. It is NOT inside T.Modules.dll.

The placement is governed by a platform rule: code lives in T.Modules.dll if and only if it contributes to the runtime Object Model — Tag namespaces, eObjType registration, ListObj / RunObj entries, user-visible runtime addressability. Local AI has zero Object Model contribution: TK.AIExecute (a Toolkit static) and the Display ChatRequest action both consume the Object Model — they read tags, dispatch runtime_* tools — but neither contributes a Tag namespace or a runtime root. Therefore Local AI is a peer infrastructure assembly, not a runtime Module.

This explains why there is no AI namespace in the runtime Object Model in 10.1.5 — Local AI is reachable only as TK.AIExecute(...) from script and as the ChatRequest Display action. A future @Solution.AI.* binding surface is post-10.1.5 work.

Build position and dependencies

The build position is between Kernel/ProjectServer and Toolkit. The Toolkit consumer (TK_AI.cs) takes a compile-time project reference to T.LocalAI.dll — there is no reflection-by-name on this binding.

Bind sites

Two callers reach the Local AI service entry methods. Both are compile-time-checked under the prescribed code organization, so signature changes surface as build errors rather than runtime nulls.

Type visibility

The Local AI service singleton, the cached-path orchestrator, and the atomic-path class are all internal sealed. The single public static surface is the defaults class, which exposes the recommended endpoint constants (URL, model name, etc.) for the Designer-side configuration dialog to seed its 5-field editor.

Process and thread model

Where Local AI runs

Local AI HTTP traffic is server-side only. Both paths execute their LLM POST inside the TServer process; clients never directly contact the LLM endpoint.

Why no runtime "view-client" gate

The cached path is reachable only through the Kernel-side TCP service handler — by construction, that handler runs in the TServer process. A misrouted client-side caller cannot land in ExecuteChatAsync.

The atomic path is reachable from a Toolkit static, so technically a Display CodeBehind script (which runs at the client) could call TK.AIExecute. The platform does not block this with a runtime gate, because three platform-level safety nets already defend against degraded execution at the client:

1. Secret resolution short-circuits off-server. Security.CheckAndResolveSecretCommConfiguration returns the unresolved literal /secret:<Name> token when not running server-side. The LLM endpoint then receives the literal token as the credential and rejects with 401.
2. SolutionSettings reads route through ObjServer.DB. Some client-side configurations have a stripped-config DB; reads fall back to defaults targeting localhost:11434 — unreachable from a remote browser.
3. Master kill-switch precedes everything. When ModelEnabled is off, the call short-circuits with status="disabled" before any HTTP work.

Together these mean a misrouted call from a thin client never silently succeeds with leaked credentials — it returns a normal HTTP-error envelope or the master-gate disabled envelope. No runtime view-client predicate is required.

Master gates — application order

Both paths apply gates in a fixed sequence at entry to the service method. The order is non-negotiable.

The asymmetry on gate 2 is intentional. ModelOptions exists to gate the LLM's tool surface; the atomic path exposes no tools, so the bit is meaningless to it. Gating the atomic path on 0x02 would prevent customers from using TK.AIExecute for pure-language tasks (translation, summary, rephrase) while reserving tool-equipped chat for selected operator panels — a legitimate posture.

Cached-path mechanics

Per-Display-panel transcript cache

The cached orchestrator maintains a per-solution ConcurrentDictionary<string, ChatSession> keyed by ClientInfo.Guid — the platform's per-TCP-connection identifier (the same key shape ModuleHistorian and ServiceSyncObjects use for their own per-connection bookkeeping).

Tool dispatch loop

When the master tool bit is on and at least one category sub-bit is on, each chat turn assembles a tool catalog and may enter a tool-dispatch loop:

1. POST messages + tools to the LLM endpoint.
2. Inspect the assistant message. If it contains tool_calls, dispatch each tool in-process against the live ObjectServer (no HTTP loopback to RuntimeMCP — sub-millisecond direct dispatch).
3. Append tool-result messages to the running message list. Loop back to step 1.
4. Terminal exit when the assistant message is plain content (no tool_calls).

The loop is bounded by two limits:

• Per-turn dispatch cap — total tool calls per turn. The default ships conservative; the platform target is 10. When the cap trips, the next iteration POSTs WITHOUT new tool results so the LLM gets one final chance to compose a terminal reply, and returns status="truncated" if it does not.
• Wall-clock budget — 60 seconds covering the entire loop (LLM POSTs + in-process tool dispatches combined).

Hook chain

OnBeforeChat and OnAfterChatReply are event Func<string, Task<string>> on the per-ObjectServer Local AI service singleton. Multicast; throwing handlers caught and logged into the reply's warnings[] with handler identity; chain proceeds with the un-mutated input. Hook failures do NOT flip the envelope's status away from ok — that's reserved for chain-aborting failures (LLM HTTP error, malformed query, etc.).

See Local AI Developer Reference (10.1.5 draft) for the reflection-attach pattern and worked hook examples.

Atomic-path mechanics

The atomic path is deliberately simple. After the master ModelEnabled gate:

1. Parse query JSON (plain text wrap or structured form with system / user / context / metadata fields).
2. Read fresh ModelSettings via the same defensive accessors as the cached path.
3. Resolve /secret:<Name> tokens via the platform's secret resolver.
4. Resolve {Tag.X} expressions in URL via the platform's expression resolver.
5. Decode auth multi-line via ReportWebData.DecodeAuthorizationHeader.
6. Build a single OpenAI-compatible messages[] array — no transcript prefix, no prior turns.
7. POST with empty tools[], 60-second wall-clock CancellationTokenSource, no loop.
8. Read choices[0].message.content. Build the SPEC envelope (toolTrace=[] always for atomic).

No hooks. No transcript. No tool dispatch. No retry. Every step lives in the atomic class; nothing calls into the cached orchestrator.

Configuration topology

Three columns on SolutionSettings

Local AI uses three pre-existing scaffolding columns. No schema migration; no per-solution row creation; no AI-specific table.

Defensive accessors

Every Local AI call re-parses ModelSettings JSON on every read. There is no caching layer with invalidation. The parse cost is negligible compared to the LLM round-trip; the alternative (cached parsed values + invalidation on column change) introduces a stale-cache bug surface that buys nothing measurable. Reads of NULL / empty / malformed JSON / missing keys / empty values transparently fall back to the defaults class.

Forward-compatibility on unknown keys

The Designer's 5-field editor preserves unknown JSON keys via a capture/replay mechanism, so future SPEC extensions to ModelSettings (e.g., a Provider dialect enum) survive an open/OK round-trip in the editor without being stripped.

SecuritySecrets integration

Local AI uses the same SecuritySecrets pattern that protocol drivers, the WebData connector, the UNS tag-provider service, and the Devices module use for credentials. There is no AI-specific secret mechanism.

For the customer-facing walk-through and worked examples, see SecuritySecrets Authentication for Local AI (10.1.5 draft).

Reply envelope contract

The reply envelope is a strict five-field shape, identical for both paths and identical across success / error / disabled / truncated outcomes:

{
  "text":      "<answer text or '' on non-ok status>",
  "status":    "ok | error | disabled | truncated",
  "toolTrace": [ ... ],
  "latencyMs": 1247,
  "warnings":  [ ... ]
}

Architectural guarantees:

• Always parseable. Every envelope is well-formed JSON. JObject.Parse(reply) never throws on a Local AI reply.
• Field stability. All five fields present on every envelope, every code path. Adding new top-level fields is non-breaking.
• latencyMs always present — including on errors. Pre-condition errors (gates) report 0; post-condition errors report actual elapsed time.
• Never throws. Network failures, parser failures, gate-off conditions, internal exceptions — all become envelopes with status="error" or status="disabled" and a populated warnings[].

Full schema and worked examples: Local AI Reply Envelope Schema (10.1.5 draft).

Integration points with other platform services

What Local AI deliberately does NOT add

Versioning and forward-compatibility expectations

• Reply envelope schema is LOCKED. Adding new top-level fields in future versions is non-breaking; existing five fields stay present and stay typed as documented.
• Configuration topology is LOCKED. The three-column shape will not change. Future configuration extensions land as new keys inside the ModelSettings JSON or as new bits in ModelOptions.
• Two-path independence is LOCKED. Future features ship in one path or the other (or both, with separate implementations). The two paths will not be merged behind a shared helper.
• Code organization may evolve. The T.LocalAI.dll assembly home is stable for 10.1.5; later releases may split or rename internal types. The compile-time entry surface (ExecuteChatAsync, ExecuteAtomicAsync) is signature-stable.

See also

• Local AI — the customer-facing capability page (overview + quick start).
• Local AI Configuration (10.1.5 draft) — endpoint, master enable, and bitmask configuration.
• ChatRequest Action Reference (10.1.5 draft) — the operator-chat surface.
• TK.AIExecute API Reference (10.1.5 draft) — the atomic script surface.
• Local AI Reply Envelope Schema (10.1.5 draft) — the uniform reply envelope.
• SecuritySecrets Authentication for Local AI (10.1.5 draft) — credential management.
• Local AI Developer Reference (10.1.5 draft) — hook attachment, custom tools, advanced patterns.

In this section...