ESRA — Enterprise Semantic Retrieval Agent

ESRA lets an AI client ask a question in plain language and get back governed evidence from your own enterprise databases — with no vector database, no embedding pipeline, and no copy of your data unless you ask for one.

It is published to AI clients as an ordinary MCP tool through the ApiMapper Runtime, so everything that already governs a tool call — authentication, access policy, audit, rate limits, tenant isolation — governs a retrieval call unchanged.

What It Does

A caller invokes esra_{name} with a prompt. ESRA then:

1. Resolves the sources the caller is allowed to search. Authorization happens first, always. An unauthorized source never appears in a prompt, a log, a diagnostic or a response.
2. Selects the relevant ones. Sources marked mandatory are always searched. Optional sources are chosen by a service LLM from business descriptions only — never schemas, never credentials.
3. Plans several searches per source. An exact phrase, a broad keyword search, synonyms, acronym expansion, a recency-weighted variant. Different sources get different strategies, because their content and terminology differ.
4. Validates every plan deterministically. The model produces structured intent, never SQL.
5. Executes concurrently as parameterized full-text queries against a read-only database principal, with per-source timeouts, row caps and circuit breakers.
6. Normalizes, merges and deduplicates the results, preserving which queries found each record.
7. Reranks semantically, then returns the Top-K evidence.

Where the exposure permits it, ESRA then composes a grounded answer from that evidence and nothing else, citing the records it used. An answer with nothing to ground it is the failure mode grounded answers exist to prevent, so no evidence means no answer rather than an invented one.

A caller that needs the text around a fragment calls the companion esra_{name}_fetch with a reference the search returned. The reference is encrypted, expiring and bound to the exposure that issued it, and every fetch is re-authorized: a reference is a pointer, never a grant. An hourly character quota bounds how much any one caller can pull, because a per-call ceiling alone would let a patient caller reconstruct a corpus one reasonable-looking request at a time.

If the service LLM is slow or unavailable, retrieval still works: every model stage has a deterministic fallback and the response is marked degraded with a warning rather than failing.

Getting a Database In Front of an AI Client

Onboarding a source starts by asking the database rather than the administrator. A guided wizard reads the catalog — relations, columns, types, primary keys and existing full-text indexes — and proposes what to search, what identifies a record, what to display as a title and what carries its business date. What it never guesses is which columns may be filtered on or must be masked: those are governance decisions, and a security control set by heuristic is worse than one left unset.

From there the path is three screens in the order the pipeline itself runs — sources feed capabilities, capabilities are published by exposures — with an overview that names whatever is blocking the next step. Once an exposure is published, Try a query runs the real pipeline as one of its own client applications and shows every stage of the run, so "why did that return nothing" is answerable before a caller ever asks it.

Retrieval Foundation: Full-Text Search

ESRA searches through the native full-text engine of the source itself: PostgreSQL tsvector / ts_rank_cd / ts_headline, SQL Server CONTAINSTABLE with native RANK, MySQL/MariaDB MATCH ... AGAINST, Elasticsearch/OpenSearch's bool-query DSL over REST, MongoDB's $text operator (or, where configured, Atlas Search's $search stage), and Oracle Text's CONTAINS/SCORE. Six engines, one contract: no term the model produced ever becomes query structure, only ever a value inside it.

This is a deliberate choice with concrete consequences:

• No data leaves the source system for indexing, on any of the six engines. There is no embedding job, no vector store to secure, and no staleness window between the record changing and the index catching up.
• Ranking is explainable. A result's score traces to term matches in named fields with configured weights — not to a distance in an opaque space.
• Record-level security is enforced by the database, in the query, as a parameterized predicate — not by filtering results in memory after the fact.

The Three-Level Configuration Model

Source        a governed searchable database: connection, search mappings, fields, limits
   ▲
Capability    retrieval behaviour: response modes, top-K, time budgets, model profile
   ▲
Exposure      the published unit: which audience, which access policy, which sources

An exposure can only narrow. It may remove a source, lower a top-K, or drop a response mode. It can never grant more than the capability, and the capability can never grant more than the source itself permits. Attempting to widen a limit is a publication error with a named reason — never a silent clamp.

This is what makes the same capability publishable twice: to one client application over sources 1–2 with one access policy, and to another over source 3 with a different one, without duplicating any configuration.

What a Caller Sees

{
  "invocationId": "0198f2c1-…",
  "status": "complete",
  "results": [
    {
      "resultId": "r01",
      "source": "Contracts Archive",
      "recordKey": "CTR-2024-8891",
      "title": "Master Services Agreement — Northwind",
      "fragments": ["… termination for convenience requires ninety days …"],
      "fields": { "status": "Active", "owner": "Legal" },
      "score": 0.91,
      "timestamp": "2024-11-02T00:00:00Z"
    }
  ],
  "warnings": []
}

Never in a response: SQL, connection details, credentials, stack traces, provider diagnostics, or any field not explicitly marked returnable. Provider and semantic sub-scores are administrator diagnostics; a caller gets one final score.

Documentation Map