# sher-search

Local, auditable semantic search over a pinned, approved subset of Mirza Ghalib's Urdu corpus.

## Safety and provenance boundary

- The server returns existing source records only. It does not generate, rewrite, or complete verse.
- The initial corpus is restricted to Mirza Ghalib.
- The build refuses source manifests that are incomplete, unapproved, checksum-mismatched, or Rekhta-derived without an explicit permission reference.
- The default `local-hash-v1` backend is deterministic and offline, but is a lexical baseline rather than a claim of neural Urdu quality. An optional FastEmbed model can be configured after review.

## Quick start

```bash
uv sync --extra dev
uv run sher-search version
uv run sher-search audit-corpus --source-dir .cache/corpora/ghalib
uv run sher-search build-corpus --source-dir .cache/corpora/ghalib
uv run sher-search build-index
uv run sher-search search "subtle betrayal" --limit 5
uv run sher-search serve
```

`build-index` uses the default corpus, model, and output paths shown in the quick start. `search`, `find`, `similar`, and `audit` accept `--config config/index.toml`.

## MCP tools

- `search_sher(query, poet?, limit?)`
- `find_sher(situation, tone?, limit?)`
- `similar_sher(sher, limit?)`
- `find_reply_sher(message, intent?, tone?, limit?)`

Every successful result includes the exact stored Urdu couplet, stable ID, source URL, source locator, license evidence, verification state, and score components. `find_reply_sher` explicitly labels its result as retrieval, not a historically authored reply.

## Reproducibility

Generated indexes and downloaded source checkouts live under `.cache/` by default. The source commit, license evidence path and SHA-256, and source file SHA-256 are recorded in `corpus/SOURCES.json` and the build manifest. See `docs/corpus-and-legal.md` and `docs/reproducibility.md` for the release gate.

## MCP client example

```json
{
  "mcpServers": {
    "sher-search": {
      "command": "uv",
      "args": ["run", "--directory", "/Volumes/Internal Drive/Vibe Coding/Sher-o-Shayari", "sher-search", "serve"],
      "env": {
        "SHER_SEARCH_INDEX": "/Volumes/Internal Drive/Vibe Coding/Sher-o-Shayari/.cache/index",
        "SHER_SEARCH_MODEL": "/Volumes/Internal Drive/Vibe Coding/Sher-o-Shayari/config/model.json"
      }
    }
  }
}
```

The project is currently an implementation baseline. Run the complete quality gate before publishing or redistributing generated corpus data.