# @ai4data/search

Framework-agnostic semantic search client for the **AI for Data – Data for AI** program. Combines HNSW approximate nearest-neighbour search, BM25 lexical search, and hybrid ranking — all running in a Web Worker. Published under the [@ai4data](https://www.npmjs.com/org/ai4data) npm organization.

**Browser only:** requires a browser environment (Web Workers, `fetch`, Cache API).

## Installation

```bash
npm install @ai4data/search
# or
yarn add @ai4data/search
# or
pnpm add @ai4data/search
```

## Usage

```ts
import { SearchClient } from '@ai4data/search'

const client = new SearchClient('https://example.com/data/your-collection/manifest.json')

client.on('index_ready', () => {
  client.search('climate finance', { topK: 10, mode: 'hybrid' })
})

client.on('results', ({ data, stats }) => {
  console.log(data)   // SearchResult[]
  console.log(stats)  // SearchStats | null
})

// Clean up when done
client.destroy()
```

### Custom worker path

If your bundler does not resolve the default worker URL, pass a factory:

```ts
new SearchClient(manifestUrl, {
  workerFactory: () => new Worker(
    new URL('@ai4data/search/worker', import.meta.url),
    { type: 'module' }
  )
})
```

### Rerank worker (optional)

For cross-encoder reranking of results, use the separate rank worker:

```ts
const rankWorker = new Worker(
  new URL('@ai4data/search/rank-worker', import.meta.url),
  { type: 'module' }
)
// Send { query, documents, top_k } and receive scored results
```

Vue and React adapters are planned (future: `@ai4data/search/vue`, `@ai4data/search/react`).

## Development

From the repo root (with workspaces):

```bash
npm install
npm run build --workspace=@ai4data/search
```

Or from this directory:

```bash
cd packages/ai4data/search
npm install
npm run build
```

## Documentation

- [Main project docs](https://worldbank.github.io/ai4data)
- [Repo structure](../../../docs/repo-structure.md)

## License

MIT License with World Bank IGO Rider. See [LICENSE](../../../LICENSE) in the repo root.
