> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suchi.page/llms.txt
> Use this file to discover all available pages before exploring further.

# LLM classifier

> Optional local or hosted model assistance for classification, archive research with citations, and reviewed extracted facts.

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:

```text theme={null}
Endpoint: http://host.suchi.local:11434/v1
Model:    qwen2.5:7b
```

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:

```sh theme={null}
LLM_ENDPOINT_URL=http://host.suchi.local:11434/v1
LLM_MODEL=qwen2.5:7b
LLM_CONFIDENCE_THRESHOLD=0.70
```

## Hosted providers

Hosted endpoints require `LLM_EGRESS_ACK=true` or the matching web checkbox.

| Provider      | Base URL                                                  | Model value                              |
| ------------- | --------------------------------------------------------- | ---------------------------------------- |
| OpenAI        | `https://api.openai.com/v1`                               | Provider model name                      |
| Google Gemini | `https://generativelanguage.googleapis.com/v1beta/openai` | Gemini model name                        |
| Azure OpenAI  | `https://<resource>.openai.azure.com/openai/v1`           | Deployment name                          |
| llama.cpp     | `http://127.0.0.1:8080/v1`                                | Descriptive label accepted by the server |

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](/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](/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](/config#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:

```sh theme={null}
suchi rescan --stale llm --dry-run
suchi rescan --stale llm
```

For an operator configuration change, explicitly select the desired documents
in the UI and rescan them. [Refile](/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](/archive-chat) 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](/privacy), [Automations](/automations), and
[Pipeline versions](/pipeline-versions).