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, filing category, model confidence, and language. Up to five matching administrator-authored automation questions can join that same call; each answer maps only to fixed local metadata actions. The same configured model also powers read-only questions with links back to the documents used. 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 choices. Model output cannot transfer a document or grant system access. Ask your documents also checks the user’s membership and document ACLs. The model sees each offered category as its code, area, name and description (descriptions are capped at 120 characters), and is asked for the most specific fit. Editing a category’s description therefore changes where the model files borderline documents. See Filing trees for the built-in boundaries. 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 service on the trusted network
  • Hosted model for a provider on the public internet
  • Account subscription, with Provider: OpenAI ChatGPT (Codex) for an account with Codex access
For Local or Hosted model, enter the Model service URL, model name, and optional API key. For Account subscription, connect the selected provider. Both flows configure a model, confidence threshold, and enabled state. The same screen controls local archive matching and its automatic/review thresholds. Automatically apply high-confidence suggestions is on by default; turn it off for review-first behavior. Save application mode saves that choice independently. A Hosted model still requires explicit acknowledgement that document text leaves the machine; the mode does not activate a model or grant permission by itself. 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. Save matching options saves local similar-document matching independently of the model, account connection, and inference configuration. It remains available after disconnecting an account subscription.

​
Account subscription

Choose Account subscription, select OpenAI ChatGPT (Codex) under Provider, then Connect ChatGPT. Open the device-login link and enter the displayed code; approval happens on OpenAI’s site. Device login may need to be enabled in your ChatGPT security settings. After connecting, Suchi fetches the account’s model catalog and fills a dropdown, initially selecting the first returned model when the saved selection is unavailable. Your dropdown choice saves automatically and survives a page refresh. Changing this preference does not change the active model until you test and enable it. Choose a model, acknowledge document egress, and use Test connection before enabling the model. Login alone does not enable inference. The Account subscription panel is marked Experimental. Connection state appears in one account row; the model catalog, document-egress acknowledgement, and confidence slider remain visible below it. Test connection reports one inline verdict, while disabled states explain the missing connection or acknowledgement in place. This is an instance-wide AI credential: classification and authorized archive research consume the connected account’s subscription allowance. It does not change Suchi’s local/OIDC user sign-in. Suchi uses the Codex device-login and streaming Responses endpoints, matching the subscription protocol rather than API-key chat completions. No Codex executable is required. Use Refresh models to retry a failed catalog request or refresh the options. Catalog membership does not guarantee inference entitlement. Model access and limits depend on the account; a successful connection test verifies that request. Access and refresh tokens are encrypted in SQLite using .decrypt-key, never returned to the browser, and refreshed on demand under a single lock. Pending codes expire after 15 minutes, are bound to the initiating administrator, and are lost on restart. Disconnect ChatGPT deletes Suchi’s saved credential and stops the active subscription model. Manage upstream account permissions in ChatGPT as well. Back up the data directory including its encryption key. OpenAI ChatGPT (Codex) is the first registered subscription provider, identified by openai_chatgpt. Suchi derives its fixed endpoint and authentication from the adapter; an endpoint URL does not select subscription mode. Configure account subscriptions in the browser; LLM_ENDPOINT_URL selects an endpoint model and overrides the saved subscription configuration. LLM_API_KEY is not used for subscription requests. Subscription inference sends no tools and does not store Responses remotely. It uses prompt-based JSON output followed by the same application validation as other providers. The backend does not accept the chat-completions token-limit setting; requests are bounded by Suchi’s timeout and response-size limit, and incomplete streams are rejected.

​
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 models 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 Ask your documents 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
  • up to 100 most-used correspondent names and 100 most-used tag names from the active filing system, with per-name length limits
  • the requested structured-output instructions
  • for each matching ask automation, its numeric ID, question text, and closed answer list (never its action mapping, destination IDs, or fixed values)
For Ask your documents, Suchi instead sends the question, newest complete conversation pairs within four messages/12 KB, and at most six documents that the user may read. Each document includes a title, sensitivity, selected text, and—only with archive_intelligence—bounded accepted detail values and quotes. Only documents linked from the prior answer are checked and reused. Confidential and Restricted text requires explicit consent for that conversation. It does not send original PDF or image bytes, unrelated archive content, ownership, ACLs, folder layouts, 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, automation-answer IDs/choices, and archive-research citations are bounded before persistence or rendering. A non-unknown automation answer must include a normalized exact quote present in the text sent to the model and the current document. Duplicate IDs, unknown IDs, unavailable destinations, invented choices, and stale question definitions produce no mapped action. Invalid provider output fails or is ignored according to its bounded field without exposing raw output or document text in logs or API errors. Before proposing correspondent or tag changes, Suchi reloads the current catalog and reuses an existing ID for exact names/slugs and for one unambiguous narrow match (a plural variant or a company name extended by at most two words). Ambiguous matches remain new proposals rather than choosing an arbitrary entry. The confidence threshold ranges from 0.50 to 0.95 in 0.05 steps and defaults to 0.70. With automatic mode on, eligible model metadata at or above the threshold can apply without review. With it off, valid inferred changes go to Approvals even at confidence 1.0. Below-threshold changes remain review suggestions. Scores are model-reported signals, not calibrated probabilities of correctness. An unset correspondent and Inbox-only filing remain eligibility checks. A model may suggest or apply a title only while that title is automatically owned. Renaming a document or accepting a title suggestion makes its title human-owned and shows it as Title pinned; Unpin releases it without changing the current text. Human edits, clears and language locks take precedence over in-flight inference; automatic language changes do not create a human language lock. Automation answers use their own model-reported confidence against the same threshold and application mode. Answer actions are mapped before ordinary classifier metadata in the final transaction; configured automation order wins for single-value destinations, while tags combine. All question answers from a request are discarded if the ordered matching question/action definitions changed during the call. The ordinary classifier result remains independently eligible. No question-specific request, retry, or answer-history row is created. Local archive matching shares the same mode, with a default automatic threshold of 0.90 and minimum review-suggestion score of 0.50. Explicit user-authored rules remain independent. Existing custom thresholds are preserved. An older review-only configuration with a 0.90 review floor and no saved automatic threshold uses 0.95 for automatic application, keeping its review floor valid. Date extraction shares the request but requires exact target-document evidence and evaluates each date’s own score against the model/date threshold, independently of overall classification confidence. See Document dates. Similar-document titles used as naming context are selected under the document owner’s access, not an administrator’s archive-wide bypass. Their identities, source snapshots and visibility are rechecked before results are stored and again when a metadata suggestion is applied. 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. An authorized human metadata PATCH or bulk metadata/tag edit resolves a classifier-owned needs-review assignment in the same write transaction. Manual, imported, rule-owned and legacy review tags remain; explicitly adding needs-review takes human ownership before cleanup rather than removing it. Trash, restore and rescan alone do not count as review.

​
Test and live reload

Test connection sends fixed synthetic text without live automation questions 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 or confidence threshold applies immediately. No Suchi restart is required. A provider-configuration change during a model call invalidates that result; the current application mode is checked again inside the writer before automatic changes. Saving settings never accepts pending suggestions. 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. Maintainers separately raise the tagged LLM recommendation when existing successful results should receive 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.

​
Ask your documents and suggested details

Administrators have archive_chat and archive_intelligence implicitly and may grant either capability to members. Ask your documents performs bounded FTS5 matching, checks access to follow-up document IDs again, and validates the structured answer and numbered-document contract. It has no model tools or write actions. The document-number check verifies format and range, not whether every claim is correct. A View is saved or Approvals/Calendar is opened only after a separate user action. The same classification call may suggest typed details. Dates are the first registered type, stored in the generic document_intelligence ledger. Only accepted dates reach Calendar, rich-query filters, or later answers: acceptance may be automatic under the current mode and threshold, or explicitly reviewed. Automatic acceptance records no human reviewer and does not enable ICS export. See Ask your documents for the complete document-matching, prompt, answer-link, saved-View, suggested-detail review, date-format, Calendar, API, privacy, rate-limit, and maintainer contracts.

​
Current scope

The product provides fixed document classification, transient read-only document questions, Views made from exact document sets, suggested details tied to document text, 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 Model service URL and model. Hosted models also need permission to send document text and usually an API key.
  • 401 or 403: verify the provider key, Azure deployment, or service 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.