Skip to main content
Suchi ships deterministic automations and local archive matching. The optional LLM classifier adds one fixed post-extraction model call for title, correspondent, tags, Johnny.Decimal category, confidence, and language. The same configured transport also powers read-only, source-grounded archive questions for authorized users. Provider/model/OCR and classification controls are instance-wide. Each document’s offered categories, local neighbors, metadata creation, rules and approval suggestions stay inside its filing system; equal labels in another system are not candidates. Model output cannot transfer a document or grant system access. Archive research additionally checks the requesting user’s membership and ACLs. It uses the OpenAI-compatible chat-completions API and supports local servers such as Ollama or llama.cpp and compatible hosted providers. The plugin is compiled into Suchi and can be enabled or reconfigured from the web interface.

​
Configure in the web app

Open Settings > Archive configuration > Classification during or after setup and choose:
  • Local model for Ollama or another endpoint on the trusted network
  • Hosted endpoint for a provider on the public internet
Configure endpoint, model, optional API key, confidence threshold, and enabled state. The same screen controls local archive matching and its review and auto-apply thresholds. Hosted mode also requires an explicit egress acknowledgement. API keys are sealed before entering SQLite. Leaving the key field blank keeps the stored value; Clear the stored API key removes the web-managed value. A key pinned in the config file or environment remains active until the operator changes that source and restarts Suchi.

​
Local Ollama

The shipped Compose network maps host.suchi.local to the host, so the default works when Ollama listens on port 11434:
When Suchi runs directly on the same host, use http://127.0.0.1:11434/v1. A local endpoint needs no key or egress acknowledgement. Equivalent environment fallback:

​
Hosted providers

Hosted endpoints require LLM_EGRESS_ACK=true or the matching web checkbox. Gemini must use its OpenAI-compatible endpoint. Azure uses the deployment name as the model. Set LLM_API_KEY or mount a key file through LLM_API_KEY_FILE for unattended startup. Classification and Archive research request OpenAI-compatible response_format: {"type":"json_object"} output before applying their own schema validation. A provider or gateway that rejects this field is not compatible with the configured model path. Claude requires an OpenAI-compatible gateway; Suchi does not call Anthropic’s native Messages API. Kimi, Qwen, Ollama, and similar providers work when their OpenAI-compatible endpoint accepts JSON-object response mode.

​
Egress boundary

For hosted model assistance, Suchi sends:
  • extracted text from the current document
  • bounded filing context and a small set of similar-document titles
  • the requested structured-output instructions
For Archive research, it instead sends the question, newest complete history pairs within four messages/12 KB, and at most six sources selected from documents the caller may read. Each source contains a title, sensitivity, snippet, and—only with archive_intelligence—bounded accepted fact value and evidence. Only cited context is reauthorized. Sensitive snippets require explicit per-conversation consent. It does not send original PDF or image bytes, unrelated archive content, ownership, ACLs, storage paths, or backup information. Loopback, private-network, link-local, .local, and .localhost hosts are treated as local. Every other host requires acknowledgement and appears in the redacted egress inventory and boundary logs.

​
Validation and confidence

Suchi accepts only validated JSON contracts. Text lengths, tag count, language shape, confidence ranges, JD code, extracted date count and calendar values, evidence quotes, and archive-research citations are bounded before persistence or rendering. Invalid provider output fails without exposing raw output or document text in logs or API errors. The confidence threshold ranges from 0.50 to 0.95 in 0.05 steps and defaults to 0.70. At or above the threshold:
  • a validated suggested title replaces the current title;
  • an unset correspondent can be filled;
  • tags are added; an earlier classifier-owned needs-review tag is removed when the new result no longer requests it;
  • the JD category changes only while the document remains in the inbox.
Date extraction uses the same score but has its own automatic-versus-reviewed contract. See Document dates. Below the threshold, source fields stay unchanged, Suchi adds the needs-review tag, and a changed title is offered as an approval assigned to the document owner. Automatic review-tag cleanup depends on a successful classification at or above the threshold, not on whether the document has a descriptive title. Failed requests, low-confidence results, and results that still include needs-review retain the marker. Other tags are never removed by classification. Suchi tracks ownership only when the classifier creates a new review-tag assignment. Existing assignments retain their ownership; adding the same tag manually, accepting a tag suggestion, or assigning it through a rule makes it independent of the classifier. Renaming its name or slug also preserves existing assignments. Tags from imports and older versions have no classifier ownership and are not automatically cleared. They can be removed explicitly after review.

​
Test and live reload

Test connection sends fixed synthetic text and validates the response with the production parser. It returns latency and sanitized synthetic fields only. It does not save settings, send archive content, or reveal raw provider output. Saving local archive settings or the model’s enabled state, endpoint, model, key, timeout, acknowledgement, confidence, or automatic Calendar-date option applies immediately. No Suchi restart is required. Date-setting effects are documented under Document dates. Other setting changes affect new ingests and explicit rescans; they never start an automatic archive-wide model backfill. Select older documents in Documents and use Rescan when they need processing again. Config-file and environment values take precedence over stored web settings on a field-by-field basis, following the documented configuration precedence. Unpinned fields still reload live. Prefer one management path per deployment so partial overrides remain easy to reason about.

​
Pipeline versions and rescans

Each classification records pipeline_version_llm. A code, output-schema, or prompt revision can bump that version and create a stale-results proposal. Changing endpoint, model, key, timeout, or threshold does not mark the archive stale. Version 0 means classification never completed. Valid low-confidence results receive the current version plus needs-review; they are completed results, not failed or unprocessed documents. Automatic upgrade proposals exclude version-zero documents, while an explicit selected or CLI rescan may include them. For version-driven command-line rescans:
For an operator configuration change, explicitly select the desired documents in the UI and rescan them. Refile reruns deterministic filing but does not call the LLM.

​
Archive research and extracted facts

Administrators have archive_chat and archive_intelligence implicitly and may grant either capability to members. Archive research performs bounded FTS5 retrieval, reauthorizes follow-up source IDs, and validates a structured answer/citation contract. It has no model tools or write actions. Its citation check verifies format and source numbers, not whether each claim is correct. A View is saved or Approvals/Calendar is opened only after a separate user action. The same classification call may propose typed facts for review. Dates are the first registered type. They are stored in the generic document_intelligence ledger and never reach Calendar, rich-query filters, or later answers until a person approves them. See Archive research for the complete retrieval, prompt, grounding, source-view, extracted-fact review, date-format, Calendar, API, privacy, rate-limit, and maintainer contracts.

​
Current scope

The product provides fixed document classification, transient read-only archive research, Views made from retrieved documents, confidence-gated facts with optional review, and document-date Calendar/query workflows. It does not provide arbitrary model tools, custom code in the ingest pipeline, persistent chat, timed calendar events, or implicit rule learning from approvals.

​
Troubleshooting

  • Disabled: configure both endpoint and model. Hosted endpoints also need egress acknowledgement and usually a key.
  • 401 or 403: verify the provider key, Azure deployment, or endpoint base URL.
  • 404: verify the model name against the provider’s current model list and confirm that the endpoint is its OpenAI-compatible base URL.
  • Invalid result: use an instruction-tuned model that reliably returns one JSON object. Suchi intentionally rejects explanatory prose.
  • Low confidence: use a stronger model, improve deterministic automations, or keep the conservative threshold and review suggestions in Approvals.
  • No classification: inspect Classification and Approvals for a dead post-classify job.
See Privacy, Automations, and Pipeline versions.