features local ai smart replacement

Local AI Smart replacement

Active contributors: Douwe de Vries

Purpose

Local AI Smart replacement is an optional strategy for generating realistic replacement values through Ollama on localhost. It is off by default, uses the configured local model only when selected columns or quick generation use Smart replacement, validates every returned replacement, and falls back to rule-based replacement when a value is missing or unsafe.

Directory layout

Path	Role
src-tauri/src/local_ai/mod.rs	Local AI module exports, default endpoint, default model, setup URL, and HTTP client configuration
src-tauri/src/local_ai/ollama.rs	Ollama status checks, model listing, runtime availability, and ready message construction
src-tauri/src/local_ai/provider.rs	Smart replacement provider that calls Ollama /api/generate
src-tauri/src/local_ai/prompt.rs	Prompt text and JSON schema sent to Ollama
src-tauri/src/local_ai/download.rs	Model download job store, progress parsing, cancellation, and terminal state handling
src-tauri/src/commands/local_ai_commands.rs	Tauri commands for status, download, polling, cancellation, and setup URL
crates/csv-anonymizer-core/src/smart.rs	Smart replacement collection, batching, validation, map storage, and missing-value checks
frontend/src/components/LocalAiPanel.tsx	User-facing Local AI status, enable toggle, model choice, download, cancel, and setup actions
frontend/src/hooks/useLocalAi.ts	Frontend Local AI status refresh, download polling, cancellation, and readiness state

Key abstractions

Abstraction	Source	Notes
LocalAiRequest	src-tauri/src/local_ai/types.rs	Carries enabled state and requested model, normalized to gemma3:4b when blank.
LocalAiStatus	src-tauri/src/local_ai/types.rs	Reports provider, endpoint, runtime availability, installed models, readiness, and user message.
LocalAiDownloadStatus	src-tauri/src/local_ai/types.rs	Reports model download job state, progress, cancellation, and errors.
OllamaSmartReplacementProvider	src-tauri/src/local_ai/provider.rs	Implements the core SmartReplacementProvider trait.
SmartReplacementMap	crates/csv-anonymizer-core/src/smart.rs	Stores accepted replacements and rejection counters by normalized source value and column.
SmartReplacementRequest	crates/csv-anonymizer-core/src/smart.rs	Batches unique values for one selected Smart replacement column.

How it works

sequenceDiagram
    participant UI as LocalAiPanel and workflow
    participant Hook as useLocalAi
    participant Cmd as Tauri commands
    participant Ollama as Ollama localhost
    participant Core as SmartReplacementMap

    UI->>Hook: Enable, choose model, refresh, or download
    Hook->>Cmd: get_local_ai_status
    Cmd->>Ollama: /api/version and /api/tags
    Cmd-->>Hook: LocalAiStatus
    UI->>Cmd: start_local_ai_model_download
    Cmd->>Ollama: /api/pull stream
    Hook->>Cmd: poll download status
    Core->>Cmd: request replacements through provider
    Cmd->>Ollama: /api/generate with prompt and schema
    Ollama-->>Cmd: JSON response text
    Cmd-->>Core: candidate replacements
    Core->>Core: validate, store, reject, or fall back

Loading

The default provider is Ollama at http://127.0.0.1:11434, with gemma3:4b as the recommended lightweight default model. LocalAiPanel lets users enable Local AI, choose or type a model, refresh status, open the Ollama download page, download a missing model, and cancel an in-progress download.

useLocalAi requests status whenever settings change and polls download jobs every 500 ms while a model download is running. Readiness requires Local AI to be enabled, the status model to match the selected model, and the model to be installed.

Status commands call /api/version to confirm the runtime and /api/tags to list installed models. Download commands call /api/pull with streaming progress, store job state in LocalAiDownloadStore, and expose terminal states to the frontend.

Prompt, schema, and provider

provider.rs creates OllamaSmartReplacementProvider only when a selected column or quick strategy uses localAi and the request is enabled. The provider builds a prompt through prompt.rs and calls Ollama /api/generate with stream: false, temperature 0.35, and a JSON schema that requires:

{
  "replacements": [
    {
      "original": "source value",
      "replacement": "fake value"
    }
  ]
}

The prompt tells the local model to create realistic fake CSV replacement values, return only JSON matching the schema, avoid copying originals, avoid personal data, and keep the same broad data type.

Validation and fallback

The core never trusts model output directly. smart.rs collects unique non-empty values for selected Smart replacement columns, caps each column at 200 unique values, batches requests in chunks of 20, and validates candidates before storing them in SmartReplacementMap.

Validation rejects candidates when the original is unexpected, output is missing, output is empty, output equals the original, output contains source text, output contains disallowed control characters, the original is duplicated, or the output duplicates another accepted replacement. Rejection counts are stored for the privacy report.

During transformation, the strategy layer asks TransformState for a Smart replacement by column and source value. If an accepted replacement exists, it is used. If it does not exist because the provider was unavailable, the response was invalid, or the value was not covered, the strategy records a Smart fallback and continues with the rule-based pseudonymization path.

Integration points

• Desktop app hosts the Local AI settings modal and theme-level settings state.
• CSV file workflow uses preflight checks to block preview or output when selected Smart replacement columns need Local AI and it is not ready.
• Paste and quick workflows use the same provider path for pasted fields and quick generation.
• Privacy reporting displays accepted Smart replacement counts, rejection reasons, and fallback counts.

Entry points for modification

• Change user-facing Local AI controls in frontend/src/components/LocalAiPanel.tsx.
• Change frontend status or download polling in frontend/src/hooks/useLocalAi.ts.
• Change the default endpoint, default model, client timeouts, or setup URL in src-tauri/src/local_ai/mod.rs.
• Change Ollama status behavior in src-tauri/src/local_ai/ollama.rs.
• Change model download behavior in src-tauri/src/local_ai/download.rs and Tauri commands in src-tauri/src/commands/local_ai_commands.rs.
• Change generation prompt or schema in src-tauri/src/local_ai/prompt.rs.
• Change provider request parsing in src-tauri/src/local_ai/provider.rs.
• Change core validation, batching, missing-value checks, or fallback accounting in crates/csv-anonymizer-core/src/smart.rs.

Key source files

File	Why it matters
src-tauri/src/local_ai/mod.rs	Defaults and module exports for Local AI.
src-tauri/src/local_ai/ollama.rs	Runtime and model readiness checks.
src-tauri/src/local_ai/provider.rs	Ollama provider implementation for Smart replacement.
src-tauri/src/local_ai/prompt.rs	Prompt and JSON schema.
src-tauri/src/local_ai/download.rs	Model download jobs.
crates/csv-anonymizer-core/src/smart.rs	Smart replacement map, validation, batching, and fallback support.
frontend/src/components/LocalAiPanel.tsx	Local AI UI.
frontend/src/hooks/useLocalAi.ts	Local AI frontend state and polling.