sf-intelligence

A grounded, fail-closed backend for AI assistants working in one Salesforce org. Your AI host (Claude, or any MCP client) asks it questions in plain language; it answers from the org's real metadata — never a guess — and labels every claim with how much to lean on it.

sf-intelligence is an offline, read-only, MCP-first knowledge base for a single Salesforce org. You run one retrieve (sf project retrieve); it builds a local Markdown vault and a DuckDB dependency graph. From then on every answer is served locally by default — offline-first, no network egress for vault answers. An opt-in live read-only plane (sfi.live_*) can answer record counts and samples when enabled. Private by design. MIT + Commons Clause.

It is not a standalone chatbot — it has no chat surface. It is the evidence layer an AI host consumes: a router that advises (ranked tool candidates plus explicit disclosures), a host LLM that decides (picks and runs the tools), and an engine that grounds every answer in the vault and fails closed — refusing, disclosing a gap, or asking a clarifying question — when it cannot.

Ask it like a person

You don't need to know the exact API name of anything. The front door is a typo-tolerant resolver that turns messy phrasing into the right component — and when it isn't sure, it asks you a clarifying question instead of guessing:

You: where's the emale field?

It: I found several matches for "email" — which did you mean? · Email__c on Account · Email__c on Contact · Alternate_Email__c on Lead

You: what about the paymnet object?

It: Payment__c — one confident match.

You: is there a "warranty fee" field?

It: Nothing matched that confidently. Your vault was last refreshed on 2026-05-20 — want to pull fresh metadata from the org (/sfi-refresh) in case it's new, or rephrase?

That is the headline behavior for resolution and routing: they never silently commit to a guess. Resolution is always heuristic and labeled as such. When several components are plausible it hands you a clarifying question; when nothing matches it offers to refresh from the org or stop. A high match score is string similarity, not proof. Source grep tools (sfi.search_apex_source, sfi.search_flow_metadata) walk the vaulted source/ tree from your last refresh — run /sfi-refresh before trusting an empty grep result.

Advisory routing — the funnel advises, the host decides

Under the hood a semantic router (sfi.route_question) reads each question and returns a meaning-ranked shortlist (toolCandidates) of the sfi.* tools that can answer it — so your AI host picks and runs them without you ever typing a tool name. It runs fully offline (a small TF-IDF model over the tool catalog — no network, no embeddings service) and it advises rather than dictates: the candidates are the primary output; the deterministic route that rides along is a non-authoritative hint. The host LLM decides which tools to run, in what order.

Confidence semantics are explicit. When no deterministic intent matches but the semantic funnel's top candidate scores above a fixed floor, the router returns a funnel-advisory route — the top funnel tools, confidence low by construction, reason flagged FUNNEL-DERIVED — an advisory pick for the host to verify (resolve the named component, then ground), never a command. Each candidate row also carries cosine, its raw semantic score, so a host can tell real semantic support from a regex-rule assertion.

The router also tags each question with the plane that answers it — the offline vault (metadata, dependencies, permissions), the live org (counts, samples, limits, inactive users — read-only, opt-in), or a hybrid of both (e.g. "is this field actually populated?"). Every answer is stamped with its provenance (offline_snapshot, live_org, or hybrid) and freshness. Clarifying questions are a last resort: a qualifier already in the question ("the X object", an object word next to a same-named field, a literal API name) auto-resolves instead of blocking, and offered options are hygienic — fuzzy lookalike junk never appears as a choice. But when two genuinely competing components remain, or the best-fitting tools diverge on something consequential (one destructive-simulation, one read-only), the router stops and asks which you meant instead of letting the host silently commit. When nothing fits, it says so rather than guessing (and can log the gap locally — opt-in via logGap: true). (A deterministic, no-LLM routing mode is available via SFI_ROUTER_MODE=offline for CI / air-gapped hosts.)

An experimental, opt-in RRF hybrid embeddings layer is available for early adopters (SFI_EMBEDDINGS=1 + npm i @huggingface/transformers). It fuses the TF-IDF candidates with a locally cached neural model (~23 MB) via Reciprocal Rank Fusion. The model is not bundled with the npm package and isn't fetched automatically — it requires the separate peer-dependency install above, and the download-on-first-use path is still being hardened, so treat it as a manual opt-in step, not something that happens for you. Off by default either way — the lexical path is byte-identical when unset, and if the model isn't installed or cached the funnel silently falls back to lexical-only. The honesty/refusal decision and the deterministic route.tools plan are not affected. See docs/configuration.md for details.

Refusal behavior — fail closed, offer the read

Some questions should never route to an executable tool, no matter how well they score. Score-independent refusal gates run on the raw question before any intent matching, and a refusal is non-executable by shape (tools: [] plus a structured route.refusal disclosure):

• Write imperatives ("delete the X field for me", "go ahead and merge these profiles") → refused-write, with a read-only alternative offered instead (safe_to_delete_field, what_if_merge_profiles, get_impact, … by verb family) — the product has no write path; the refusal names the simulation that answers the underlying question safely.
• Prompt injection / record-value exfiltration ("ignore your previous instructions…", "dump all SSN values") → refused-injection, with candidates and guidance suppressed entirely.
• Runtime telemetry no tool models → honest-gap-runtime, naming the nearest real reads. Non-Salesforce asks → out-of-scope.

Legitimate reads are explicit excluders — "am I allowed to edit…", "who can delete…", "is it safe to…" are permission questions and route normally. On a 2,000-question real-org evaluation, the gates cut genuine over-confident routes from 69 to 11 with zero answerable questions falsely refused.

Conversation context — follow-ups without server-side memory

The product stores no conversation state. Instead, the host may pass an optional context.previous on each route_question call describing what the prior turn was about, and terse follow-ups ("does it fire on delete too?", "what about on Contact?", "the second one") resolve against it — pronoun substitution is an exact-id lookup (never fuzzy), an inherited tool is an advisory continuation capped at medium confidence, and a clarification pick re-dispatches through the normal clarification contract (out-of-range ordinals re-ask, stale ids are rejected). A self-contained question ignores context entirely, and refusal gates run before any context logic — context never bypasses them. Host-side, after routing "who can edit the SSN field?" and running the tools:

// next turn: "can Support Agents specifically edit it?"
{
  "question": "can Support Agents specifically edit it?",
  "context": {
    "previous": {
      "question": "who can edit the SSN field?",
      "tool": "sfi.field_access_audit",
      "componentId": "CustomField:Contact.SSN__c"
    }
  }
}

When (and only when) context changes the route, the response discloses it in route.contextApplied. See docs/routing.md for the full host contract.

Honesty guarantees

The design rule across the surface is fail closed, disclose first: