# Semantic Retrieval Adapter

`semantic-retrieval-adapter` is an optional OpenClerk building block. It is not
loaded by OpenClerk core and does not change `openclerk retrieval search`.

## Command

```bash
semantic-retrieval-adapter search < request.json
```

Request:

```json
{
  "query": "semantic recall citation quality",
  "path_prefix": "docs/architecture/",
  "tag": "semantic-retrieval",
  "limit": 10,
  "provider": "ollama"
}
```

The adapter reads OpenClerk documents through the embedded read-only runner
client, applies path-prefix, tag, or metadata filters before chunking, builds
citation-preserving chunks, embeds them with Ollama or Gemini, stores a
rebuildable cache under the user cache directory, and returns the shared
`openclerk_semantic_retrieval.v1` JSON contract with hybrid RRF ranking and
citations.

Filter rules match core search validation: `tag` must be non-empty when
provided, `metadata_key` and `metadata_value` must be provided together, and
`tag` cannot be combined with metadata filters.

## Boundaries

- Ollama keeps corpus/query text local when the local service and model are
  available. `ollama_url` must resolve to a loopback HTTP(S) host.
- Gemini is explicit provider-backed mode only and reads
  `runtime_config:GEMINI_API_KEY`; the key is never printed or written back.
  `gemini_api_base` is accepted only for the canonical
  `https://generativelanguage.googleapis.com/v1beta` endpoint. Custom Gemini
  endpoints and provider mimics are not supported by the production adapter.
- The cache is outside the committed repository and can be deleted/rebuilt.
- Results are retrieval evidence only. Canonical markdown citations and
  approved OpenClerk runner writes remain authority.
- The module performs no durable OpenClerk writes, schema migrations, provider
  config secret writes, hidden provider fallback, or default search ranking
  changes.
