Knowledge Engine

What This Engine Does

Knowledge Engine is the single, shared implementation of Stage 1 ("Embedding Engine") in TotalApp's two-stage hybrid AI pattern. Any screen that needs to rank a list of candidate records by semantic similarity to a query text — before handing a shortlist to a deeper AI analysis — goes through this one module. It embeds text via the user's local Ollama instance, ranks candidates by cosine similarity, applies an optional score threshold and top-K limit, caches computed embeddings for the session, and falls back to a keyword match when the embedding engine is unavailable.

The Two-Stage Hybrid Pattern This Engine Completes

Knowledge Engine is always Stage 1. Stage 2 is a separate, domain-specific engine (e.g. Patent Agent, or the Customs Trade Compliance audit) that reasons over the shortlist Stage 1 produced:

The Core Function — rankDocsByEmbedding()

Every domain wrapper calls one generic function:

It returns { matches: EmbeddingRankedMatch<T>[]; degraded: boolean }. degraded: true means the embedding path failed and matches came from the keyword fallback instead — the function never throws.

Internal Mechanics

Embedding calls

Reads ollamaEmbeddingModel and ollamaBaseUrl from useUIStore.getState() (the user's Settings → Agentic selection). Both the query text and every candidate's content are embedded via ollamaEngine.embed(). Text longer than MAX_EMBED_CHARS (3000 characters) is truncated — local embedding models have a limited token context window, and Ollama rejects an oversized batch with a 500 rather than truncating server-side.

Cosine similarity

Uses the shared cosineSimilarity(a, b) primitive from knowledgeSearchService.ts — the same function My Knowledge / Attach Knowledge uses for its own ranking. Returns 0 for degenerate input (empty vector, length mismatch) rather than throwing or returning NaN.

In-memory embedding cache

A session-lifetime Map<string, number[]>, keyed by the embedded text itself (`${text.length}:${text}`) — not by a caller-supplied id. Two practical consequences: a changed record automatically invalidates its own cache entry (no separate updatedAt/version field needed), and the cache is safely shared across every domain (patent, customs, fintech) without any risk of cross-domain id collisions producing a wrong result — the key is derived from content, not from an id namespace. The cache is never persisted (page reload clears it) since embeddings are cheap to recompute and tied to whichever Ollama model happens to be configured at the time.

Threshold + top-K ordering

Matches are sorted by score, then the minScore threshold is applied, then the result is truncated to topK. This order matters: applying the threshold before truncation guarantees a weak match can never occupy a slot that should have gone to a stronger one that happened to be ranked just outside the naive top-K window.

Keyword fallback

Engaged whenever the embedding path can't produce a result: no embedding model configured, the embed call fails or returns an empty vector, or (when a threshold is set) every candidate falls below it. The query text is tokenized on whitespace/punctuation (tokens under 3 characters are dropped), and candidates are scored by the fraction of query tokens their content contains. This guarantees Stage 2 always receives at least a rough context, even with Ollama completely unavailable, rather than an empty list.

Domain Wrappers — Who Uses It

No screen calls Knowledge Engine directly. Each domain has a thin wrapper service that supplies its own candidate type and a content-formatting helper:

A new domain follows the same pattern: define a candidate type, write one format<Domain>ForEmbedding() helper that turns a record into a content string (reused for both the embedding candidate and the Stage 2 prompt's context block, so the two never drift apart), and call rankDocsByEmbedding() with sensible minScore/topK defaults.

End-User Documentation

This page is the technical/developer reference. For the plain-language explanation of this feature aimed at end users (what it does, where it appears, why the AI ranking runs locally) see Finding Similar Records under the Semantic Search section.

Known Limitations

• No real external corpus. Candidate pools are either static in-app data (Patent & R&D's COMPETITOR_CANDIDATES) or the tenant's own operational records (Customs's sanction rule ledger) — never a live external database (a real patent office API, a real sanctions-list API). Wiring a real external source is a separate, larger integration.
• 6 of 9 Patent & R&D screens migrated to the centralized options parameter; 3 didn't need to (they apply no threshold/limit at all, or compare a single candidate). The remaining migration surface is fintechEmbeddingService.ts's 12 functions, none of which are wired into any screen's UI yet — connecting them is a separate, larger UI task per screen, not a Knowledge Engine change.
• Always dependent on the user having Ollama running locally with an embedding model selected in Settings → Agentic; when it isn't, every caller degrades to the keyword fallback rather than failing outright.

Frequently Asked Questions