> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.docs.gooclaim.com/llms.txt.
> For full documentation content, see https://api.docs.gooclaim.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.docs.gooclaim.com/_mcp/server.

# Advanced Search

Gooclaim's Knowledge Layer search is built for the messy reality of insurance
content: long policy PDFs with overlapping clauses, partner-specific
overrides, multi-language source material, and constantly-evolving rate
tables. This page explains the search capabilities you can tune per source.

## Search modes

Embedding-based similarity. Best for natural-language questions where
keywords don't match exactly — "what does the policy say about pre-existing
conditions?" finds clauses worded differently.

BM25 lexical match. Best for IDs, codes, and exact phrases — policy
numbers, ICD-10 codes, specific clause references.

Default. Runs both in parallel and re-ranks. Recommended for most
workflow queries — gets the precision of keyword and the recall of
semantic.

## AI query expansion

For ambiguous claimant questions ("kab milega paisa?" / "when will I get paid?"),
the search engine expands the raw query into multiple semantic variants before
hitting the index. This improves recall without manual synonym dictionaries.

Expansion is **on by default** but can be disabled per query if you need
deterministic results (e.g. an audit-traceable lookup).

```json
POST /v1/knowledge/search
{
  "query": "kab milega paisa",
  "expand": true,
  "mode": "hybrid",
  "top_k": 5
}
```

Response includes both the expanded variants used and the matched documents,
so audits show the full reasoning trail.

## Metadata filtering

Every document indexed carries metadata — source, tenant, document type,
language, tags applied at ingest. Filter results to scope queries:

```json
POST /v1/knowledge/search
{
  "query": "maternity benefit waiting period",
  "filters": {
    "document_type": ["policy", "endorsement"],
    "language": ["en", "hi_en"],
    "tags": ["plan_b"]
  }
}
```

Use this to:

* Restrict to **policy documents only** (exclude internal SOPs from claimant-facing answers)
* Match the claimant's **preferred language**
* Apply **partner-specific overrides** when the same question has different answers per plan

## AI-generated answers

By default, search returns ranked passages with citations. If you want a
synthesised answer paragraph (e.g. for a rich-content channel like a web
chat widget), enable `generate_answer`:

```json
POST /v1/knowledge/search
{
  "query": "what is the network hospital limit?",
  "generate_answer": true,
  "answer_template_id": "policy_lookup_v2"
}
```

The generated answer always:

1. Cites the source passages it drew from
2. Passes through the Policy Gate before return
3. Uses an **approved template** as the formatting scaffold — never raw LLM output

In pilot (v1.0), generated answers are available for internal Console
preview and the public API. End-user messaging surfaces always use the
template-based response builder, not free-text generation.

## Ranking and re-rank

Hybrid mode runs three stages:

1. **Recall** — pull top-50 from semantic + top-50 from keyword (de-duplicated)
2. **Re-rank** — cross-encoder model scores each candidate against the query
3. **Trim** — return the top-K to the caller

You can tune `recall_size` (default 100) and disable re-rank for latency-
sensitive paths. Re-rank typically adds 50-150ms but lifts precision by
15-25% on the messy queries that benefit most from it.

## Best practices

A 1000-document index with high signal-to-noise produces better answers
than a 50,000-document index full of stale memos. Curate ruthlessly.

Tag documents with plan codes, partner IDs, and document types when you
set up the source connector. Query-time filters then become trivial and
indexes stay fast.

The Audit Ledger captures every Knowledge Layer query plus the documents
that scored highest. Review weekly to spot drift — questions that used to
answer correctly but now don't usually mean a source has gone stale.

Don't ask the Knowledge Layer "where's my claim?" — that's a Truth Layer
job (live CMS query). Knowledge is for the **why**, Truth is for the
**what**. The Workflow Engine routes correctly when both are configured.

## Next steps

Connect your first source if you haven't yet.

Full schema for the search endpoints.