Formula Syntax Assistant & Cloud AI

The opt-in assistant maps a natural-language calculation request to a locally verifiable Kalc formula. Kalc's native parser and evaluator remain the source of truth; valid native expressions continue to evaluate locally without Cloud AI.

Pipeline

1. The macOS app scans only the active line for typed currency, percentage, unit, duration, date, scalar, and workspace-variable spans. Workspace variable values are not included in the request.
2. CategoryClassifier asks a typed JEV Choice question over enabled categories. FunctionSelector asks a second Choice question over functions in the selected category. Both include an explicit other option and validate returned confidence and probability distributions.
3. ArgumentMapper assigns unique extracted spans to required function parameters. A single feasible mapping is deterministic; competing mappings use batched typed Score questions.
4. FormulaBuilder constructs syntax from local entity values. FormulaPreviewGate parses and evaluates deterministic formulas locally. Plugin and other non-deterministic calls are syntax-checked and deferred until the user inserts them.
5. Low-confidence or ambiguous function choices are shown as separately selectable formulas with individual confidence. Confidence is color-coded (green at 85%+, orange at 65-84%, red below 65%). Other low-confidence stages abstain. No suggestion is inserted without an explicit user action.

Gateway and Privacy

JEV requests use the existing CloudRoutingClient and Kalc Cloud POST /api/ai schema-v3 gateway. The app sends the typed JEV question batch with the active input line and standard Kalc device headers. The gateway owns provider authentication, validation, rate limits, quota/history accounting, and upstream access. No provider API key, direct-provider endpoint, or bearer credential is stored or sent by the app.

Cloud AI is opt-in. Only the active line and locally extracted value spans needed for the decision are sent. The surrounding document, tab names, previous results, and workspace variable values are excluded. Gateway request bodies are not stored in history or telemetry. Local preview validation confirms executable syntax and runtime behavior, not that the inferred intent is semantically correct.

Data Retention And Quota

Kalc's gateway stores usage metadata only: request ID, device-scoped quota counters, model, input/output token counts, charge, decision mode, status, and timestamps. It does not store the active line, extracted entity values, JEV state, question text, formulas, or provider response content in D1 history or application telemetry. A stable device ID is retained to scope quota and history; it is not a document identifier.

Each request performs a quota preflight and is charged only after a valid provider response. When the allowance is exhausted, the gateway returns 402 AI_CREDIT_EXHAUSTED; the app updates the allowance shown in Settings and keeps local calculation available.

Cloudflare's current Workers AI data usage policy states that Cloudflare does not use Workers AI customer content to train AI models or improve Cloudflare or third-party services without explicit consent. Customer content may be stored when a customer explicitly uses a Cloudflare storage service with Workers AI. Kalc does not write these inference requests to R2, KV, Durable Objects, or Vectorize. Provider policies can change, so the linked policy is the authoritative source for Cloudflare's handling of inference content.

Preferences and Use

AI features are disabled by default at build time. Standard builds and the GitHub release pipeline hide Settings > AI and the assistant command, ignore saved AI opt-ins, and do not invoke AI. The implementation remains in the repository.

For local development, opt in when building or running the macOS package:

KALC_ENABLE_AI=1 DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift run --package-path apps/macos KalcApp

Use the same KALC_ENABLE_AI=1 environment variable with swift build, swift test, or the packaging scripts. Unset, 0, or any value other than 1/true disables the feature. This is baked into the binary; changing the environment at launch cannot enable a disabled build. AI preferences still default to off in an enabled build.

In an AI-enabled build, open Settings > AI to enable suggestions or the assistant, choose the minimum confidence, and select enabled categories. The standard cloud suggestion mode and typed JEV assistant are separate settings. When Cloud AI is unavailable, rate-limited, invalid, or out of credits, the calculator remains usable locally and displays a status message.

The editor can invoke the assistant for unresolved lines when enabled, or on an explicit assistant request. Review the formula and preview before accepting it. Dismiss alternatives without modifying the line.

Plugin Metadata

Plugin functions are eligible only when their manifest declares AI metadata with a label, category, a parameter description for every declared argument, and unique parameter names. Metadata must describe a real function contract; the local preview gate defers execution of plugin calls until acceptance.

No accuracy or latency level is implied by this feature description. Model decisions and local syntax verification do not establish semantic correctness; measure representative outcomes before making quality claims.

Safe Preview Gate for Plugin Functions

When a proposed formula invokes a JavaScript plugin function, the preview gate validates its syntax without executing plugin code in the background. The picker marks that preview as deferred. The function runs only after the user explicitly accepts the formula and the editor evaluates it normally.

Formula Examples

Request	Formula	Local result
15% of 200	15% * 200	30
monthly payment on $500k at 5% for 30 years	pmt(500000, 5%, 30)	Locally evaluated payment
75 mph in km/h	75 mph in km/h	Locally evaluated conversion