Browser-Local AI for Reaktor

Documentation integration update, 7 October 2026. The browser-local docs assistant described below has been retired. Documentation questions now use Manna's native library, which exposes the source context, revisions and citations. The June experiment remains in this document as design history. Other browser-local provider and workbench proposals still need their own implementation and current provider qualification.

Browser-local AI should be a first-class Reaktor capability tier, not a replacement for Koog, MCP, server agents, or cloud models. The useful framing is simple:

• Chrome built-in AI / Gemini Nano gives Reaktor browser-managed task APIs and, where available, a prompt API without shipping model weights.
• WebLLM gives Reaktor app-managed WebGPU inference with model choice, streaming, and an OpenAI-compatible local client shape.
• Reaktor should expose both through the graph as capability-bearing provider nodes with explicit limits, permissions, feature probes, and fallbacks.

The main win is not "run the whole agent locally." The win is that every Reaktor surface can get cheap, private, low-latency assistance for summaries, explanations, translations, draft patches, and context compression while keeping authoritative mutations inside the existing WorkbenchCommand -> GraphPatch -> dryRun -> review -> commit spine.

• Scope Reaktor docs, Reaktor Web, reaktorDesktop workbench, and Reaktor-powered apps such as BestBuds
• Status Design / assessment
• Updated 2026-06-02
• Primary sources Chrome built-in AI docs and MLC WebLLM docs

1. Verdict

The right architecture is provider-neutral:

1. Reaktor probes what the browser can do.
2. It materializes those abilities as graph capabilities.
3. UI and agents call a small Reaktor AI interface, not Chrome APIs or WebLLM directly.
4. Every local-model output is typed as a suggestion, finding, explanation, or draft command.
5. Hard reasoning, long context, privileged operations, and final applies stay with Koog/server/cloud agents plus the Reaktor permission model.

2. Two provider families

2.1 Chrome built-in AI / Gemini Nano

Chrome's built-in AI APIs expose browser-managed local model functionality. The browser owns model availability, download, storage, execution, and API eligibility. Reaktor does not host the model weights and should treat every API as dynamically available.

Useful API categories:

Operational properties:

• Browser-managed model: Reaktor asks the browser for a capability; it does not bundle model weights.
• Feature-probed: code must call the API-specific availability check and support available, downloadable, downloading, and unavailable states.
• Chrome-specific: the UX must degrade cleanly in other browsers and unsupported Chrome configurations.
• Local by design: once the model is available, the prompt work is intended to run on device, but Reaktor should still redact secrets and keep audit boundaries.
• Task APIs first: for summarization, translation, language detection, and rewrite tasks, prefer task APIs over a generic local prompt.

This is the lowest-friction path for Reaktor Web docs and workbench UI because the app does not need to ship or license a model. The tradeoff is less control: Reaktor cannot assume model identity, quality, context length, or API availability.

2.2 WebLLM / MLC WebLLM

WebLLM runs LLM inference in the browser with WebGPU and an app-selected model. It gives Reaktor a local model client shape closer to server LLM integrations: model selection, streaming, web-worker execution, caching, and an OpenAI-compatible chat-completion API.

Useful properties:

Tradeoffs:

• Model downloads can be large and slow.
• WebGPU support, memory, battery, and thermal behavior vary by device.
• Reaktor owns model choice, caching UX, license review, and version drift.
• Quality is lower and less predictable than frontier cloud models.
• It is not a safe authoritative operator. It drafts; Reaktor validates.

WebLLM is the stronger fit when Reaktor needs local model control or an OpenAI-like local adapter. Chrome built-in AI is the stronger fit for narrow task APIs where the browser already handles the model.

3. Where it helps Reaktor

3.1 Retired documentation experiment

The June design used public documentation and loaded page chunks as an initial browser-local experiment. The following feature list records that experiment; the current documentation workflow is in Manna.

Useful features:

• Summarize the current doc.
• Ask questions over the currently loaded Reaktor docs bundle.
• Explain terms such as GraphSnapshot, GraphPatch, ActorNode, Capability, CloudResource, Binding, and VisitorPass.
• Produce "what changed" summaries between docs revisions.
• Rewrite a section for clarity without changing the underlying source automatically.
• Translate docs pages or selected paragraphs.
• Generate onboarding paths such as "read these five docs before editing the visual language."
• Compress a large doc section before handing it to a cloud agent.

This can run entirely as suggestions in the browser. The model does not need repository write access.

3.2 Reaktor graph and workbench

Browser-local AI is useful beside the visual graph because it can interpret a selected local snapshot quickly without waiting for a server agent.

Useful features:

• Explain the selected node, pins, edges, providers, consumers, facets, and findings.
• Summarize a subgraph or diff between two graph snapshots.
• Suggest compatible nodes for an unwired port based on ContractId, facets, and local examples.
• Convert a compiler finding into a plain-language remediation checklist.
• Summarize execution traces, logs, Maestro failures, Dagger runs, Gradle failures, and deploy output.
• Draft a GraphPatchProposal from a typed intent, then hand it to the real Reaktor validator.
• Compress selected graph context before escalation to Koog, Codex, Claude, or a server model.

The key rule: browser-local AI may propose GraphPatchProposal, not apply GraphPatch.

3.3 Reaktor visual language

For the Blueprint-style visual language, local AI can improve authoring speed without owning semantics.

Useful features:

• Generate concise node display names from source-owned node metadata.
• Explain a typed hole: "this input expects MessageRepository and no provider exists in this subgraph."
• Suggest small graph edits from existing patterns.
• Summarize a visual program's execution path.
• Label edge groups and nested graph boundaries.
• Convert a selected Blueprint-style graph into prose documentation.
• Compare two visual graph versions and explain behavioral intent.

This composes with Reaktor Visual Language: the canvas remains a projection of graph facts and reversible commands.

3.4 BestBuds and Reaktor apps

For product apps, browser-local AI is useful for low-risk user-facing assistance when the app can tolerate device variability.

Candidate BestBuds features:

• Translate or rewrite a draft message before sending.
• Summarize long chats locally.
• Detect message language before routing translation.
• Draft event descriptions, campaign copy, and profile text.
• Pre-classify obvious spam or unsafe text before server moderation.
• Generate accessibility alt text for user-selected media if a local multimodal API is available.
• Summarize local support/debug logs before the user submits a report.

Do not use browser-local AI as the final authority for safety, moderation, entitlement, ranking, billing, or abuse enforcement. It can pre-filter and explain; the product still needs governed server-side policy.

3.5 Local context compression before cloud agents

One of the strongest Reaktor uses is as a privacy and cost reducer before remote agent calls:

selected graph/docs/logs
  -> local sanitizer
  -> browser-local summarizer/compressor
  -> redaction validator
  -> cloud/Koog/MCP agent with smaller context

This gives Reaktor a principled path to send less data to remote models while keeping the final high-stakes reasoning in stronger governed agents.

4. Graph representation

Browser-local AI should appear in the Reaktor Engine graph as provider and capability nodes. These nodes describe what the current browser/session can do; they are not source-of-truth business objects.

4.1 Provider nodes

These are closer to Capability and Provider nodes than durable domain actors. A DurableObject can reuse actor semantics because it is an addressable stateful runtime object. A local browser model session is not the same thing; it is a transient execution capability with dynamic availability.

4.2 Capability nodes and ports

Suggested facets:

4.3 Kotlin-first declaration shape

Reaktor should still define the stable contract in Kotlin. Browser APIs and WebLLM are adapters behind that contract.

interface LocalAiProvider {
    val providerId: ProviderId
    val capabilities: Set<LocalAiCapability>
    suspend fun availability(task: LocalAiTask): LocalAiAvailability
    suspend fun summarize(request: SummarizeRequest): SummaryResult
    suspend fun translate(request: TranslateRequest): TranslationResult
    suspend fun promptStructured(request: StructuredPromptRequest): StructuredPromptResult
}

data class LocalAiCapability(
    val task: LocalAiTask,
    val facets: Set<CapabilityFacet>,
    val limits: LocalAiLimits,
    val provenance: ProviderProvenance,
)

On the web target, ChromeBuiltInAiProvider and WebLlmProvider implement this contract. In reaktorDesktop, the same interface can be backed by Koog, Ollama, WebLLM-in-browser panes, or remote providers. The graph sees the contract; each host supplies the adapter.

5. Provider selection policy

Reaktor should choose the cheapest safe provider that satisfies the task:

1. Prefer Chrome task APIs for narrow tasks when available: summarization, translation, language detection, writing, and rewriting.
2. Use Chrome Prompt API for short local freeform or structured work when available and policy allows it.
3. Use WebLLM when WebGPU is available, the user accepts model download/cache, and Reaktor needs model choice, OpenAI-compatible local calls, streaming, or stronger structured-output control.
4. Use Koog on JVM or a server/cloud model for long context, tool-heavy reasoning, code edits, cross-repository planning, infrastructure operations, or any privileged mutation.
5. If none are available, degrade to normal UI: no broken panels, no required local AI dependency.

Provider choice should be visible in the graph inspector:

LocalAiProvider
  provider = chrome.builtInAi.summarizer
  availability = available
  facets = [LocalOnly, TaskApi, DraftOnly, NoSecretInput]
  limits = { inputTokens: dynamic, outputTokens: dynamic }
  policy = docs-assist.readonly

6. Security and permission model

Browser-local AI must be treated as an untrusted assistant with local execution privileges, not as a privileged operator.

Hard rules:

• It never receives graph:apply, deploy:*, infra:mutate, auth:admin, billing:*, secrets:read, or raw store-management scopes.
• It can emit Explanation, Finding, Summary, RewriteDraft, GraphPatchProposal, and WorkbenchCommandProposal.
• A proposal must go through schema validation, graph validation, dry-run, policy checks, and human or Critic review before apply.
• Prompts must separate trusted instructions from untrusted docs, page content, logs, graph metadata, and user text.
• Reaktor must redact secrets even for local models. "Local" reduces exposure; it does not remove data-classification obligations.
• Model availability and model identity are not authorization facts.
• Every AI-produced operation should be auditable with provider, availability state, prompt class, output schema, validation result, and user action.

Suggested operation spine:

LocalAiProvider
  -> DraftGraphPatchProposal
  -> SchemaValidator
  -> GraphPatchDryRun
  -> PolicyGate
  -> Critic/HumanReview
  -> WorkbenchCommandQueue
  -> Commit/Apply

7. Evaluation and telemetry

Browser-local AI quality will vary by browser, model, hardware, and API version. Reaktor needs evals from day one.

Track:

• Availability by browser, OS, device class, and task.
• Model download success, failure, size, cache state, and time-to-ready.
• Latency, cancellation, memory pressure, battery impact, and UI jank.
• Structured-output validity rate.
• Dry-run pass/fail rate for GraphPatchProposal.
• Human accept/edit/reject rate.
• Escalation rate to Koog/cloud agents.
• Privacy lint failures and redaction counts.
• User-visible fallback rate.

The telemetry should feed Reaktor Analytics and Telemetry and graph-linked findings in the workbench.

8. Limitations

Browser-local AI is useful, but it is not magic infrastructure.

• Availability is dynamic. API support, model readiness, policy eligibility, browser version, and device constraints can change.
• Chrome built-in AI is not portable. Other browsers need fallback behavior.
• WebLLM has real weight. Model downloads, GPU memory, cache size, and load time affect UX.
• Mobile support is uncertain. Treat mobile browser-local AI as opportunistic, not a required path.
• Context windows are limited. Local models are best for scoped graph selections and document chunks.
• Quality varies. It should not be the final authority for security, moderation, infra, or code mutation.
• Licensing matters. WebLLM model choices need explicit license and redistribution review.
• Privacy is not automatic. Local execution helps, but prompt logs, debug traces, caches, and copied content still need governance.

9. Implementation plan

P0 - historical docs assistant

This implementation was removed in October. The following records its June behavior, not the current docs site's behavior.

• Shipped 2026-06-02. The Docusaurus docs site mounts a browser-local DocsAssistant through the Docusaurus root theme hook. It probes Chrome LanguageModel, Summarizer, Translator, LanguageDetector, and Rewriter, reads only the rendered article plus the generated local search index, and keeps prompts/results in memory only.
• Updated 2026-06-02. WebLLM is now a real on-demand provider path rather than a future-only status chip. If Chrome task APIs are unavailable but WebGPU is present, the assistant can lazy-load @mlc-ai/web-llm and Llama-3.2-1B-Instruct-q4f16_1-MLC after a user action. Nothing downloads on page load.
• The runtime order is Chrome task API first, Chrome Prompt API second, WebLLM third, deterministic local page/index matching last.
• The assistant supports summarize, explain, translate, and rewrite draft, with model/provider availability shown in the inspector surface.
• Prompts are not persisted by default. WebLLM model artifacts may be cached by the browser/runtime so repeat use does not pay the full first-run load cost.

P1 - provider abstraction

• Add Kotlin-first LocalAiProvider contracts.
• If this provider work resumes, implement reusable Reaktor web providers; the retired Docusaurus adapters are no longer a maintained integration.
• Normalize availability, limits, streaming, cancellation, and errors.
• Materialize provider/capability nodes in Reaktor Engine graph snapshots.

P2 - graph explanation

• Feed selected node/subgraph/finding context to local providers.
• Generate GraphExplanation and remediation summaries.
• Add telemetry for accept/reject and escalation.

P3 - draft graph patches

• Add strict schemas for GraphPatchProposal.
• Run every proposal through schema validation and graph dry-run.
• Display the resulting diff as a command proposal only.
• Require human/Critic approval before any queue apply.

P4 - local context compressor

• Compress selected docs/graph/log bundles before remote agent calls.
• Run redaction after compression.
• Attach provenance so the cloud agent can see what was omitted.

P5 - app-facing local AI

• Expose opt-in app capabilities for BestBuds: translate draft, summarize chat, rewrite profile/event copy, language detect.
• Keep policy decisions on server-side governed systems.
• Add per-feature capability gates so unsupported devices do not see broken flows.

10. Open questions

• Should Reaktor Web ship WebLLM support by default, or keep it behind an experimental flag until download/cache UX is excellent?
• Which local models meet Reaktor's license, size, latency, and structured-output requirements?
• Should browser-local AI prompts be fully ephemeral, or can users opt into local IndexedDB history?
• How should Reaktor display model download/storage cost without turning the workbench into a settings maze?
• What is the minimum eval suite before allowing GraphPatchProposal generation?
• For future browser-local providers, which parts of the revisioned documentation corpus can be cached within their context and storage limits?

11. See also

• The Reaktor Control Plane - Observe/Call/Change, permission-gated tools, and mutation spine.
• Koog in reaktorDesktop - JVM-side agent runtime for privileged workbench operations.
• Reaktor Visual Language - Blueprint-style visual graph authoring.
• Reaktor Unified System Graph - whole-product graph, infra/resource nodes, and control-plane importers.
• Reaktor Capability - provider/capability/facet vocabulary.
• Reaktor Analytics and Telemetry - signal model for availability, quality, and usage telemetry.

12. External references

• Chrome built-in AI overview
• Chrome built-in AI get started
• Chrome built-in AI APIs
• Chrome Prompt API
• Chrome Summarizer API
• Chrome Translator API
• Chrome Language Detector API
• MLC WebLLM documentation
• MLC WebLLM GitHub repository

13. Doc lineage

Authored 2026-06-02 after evaluating Chrome built-in AI/Gemini Nano and WebLLM for Reaktor docs, graph tooling, and workbench use. The document intentionally keeps browser-local models in a draft-only capability tier and routes authoritative operations through existing Reaktor graph validation, permission, telemetry, and review mechanisms.

Related docs

• Control Plane - Use when exposing Reaktor safely to humans and agents.
• Koog Workbench - Use before wiring real agent behavior into reaktorDesktop.
• UI & Design System - Use before touching reaktor-ui tokens/components/theming, designing the tactile runtime (interaction/physics/field/skins/host-tree/reconciler), or planning adaptive layouts and AI/server-driven UI.
• Perf and Observability - Use before optimizing or adding instrumentation.
• Security Plan - Use before enabling deploy actions, remote agents, or privileged commands.
• Visual Language - Use when designing the node-based authoring/orchestration language and its editor, compiler, and agentic surface.