Salesforce-Intelligence

<p align="center">
  <img src="assets/hero.svg" alt="sf-intelligence — Salesforce Org Intelligence for AI agents: a read-only, offline MCP server and CLI" width="100%">
</p>

<p align="center">
  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT%20%2B%20Commons%20Clause-blue.svg" alt="License: MIT + Commons Clause"></a>
  <a href="https://www.npmjs.com/package/sf-intelligence"><img src="https://img.shields.io/npm/v/sf-intelligence.svg?color=cb3837&label=npm" alt="npm version"></a>
  <a href="https://github.com/PranavNagrecha/Salesforce-Intelligence/actions/workflows/ci.yml"><img src="https://github.com/PranavNagrecha/Salesforce-Intelligence/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <img src="https://img.shields.io/badge/node-%E2%89%A520-339933.svg" alt="Node.js >= 20">
  <img src="https://img.shields.io/badge/status-read--only%20%26%20offline-2ea44f.svg" alt="Read-only and offline-first">
</p>

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

```jsonc
// 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](./docs/routing.md) for the full
host contract.

## Honesty guarantees

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

- **Grounded or refused.** Every answer path ends in real tool output against
  the vault (or the consented live org); when no tool covers the ask, the
  router returns an honest gap — never a lookalike tool, never general
  Salesforce knowledge dressed up as org fact.
- **Premise checks.** A question naming a component the resolver cannot find
  still routes (the tools fail closed on the unknown id), but confidence is
  downgraded and a `PREMISE CHECK` disclosure warns that no such component
  exists in the vault — and a funnel-advisory route is never granted on a
  failed premise.
- **Disclosure-first.** Coverage caveats, staleness warnings, live-consent
  notices, refusa