Metadata-Version: 2.4
Name: llmatch-bm25
Version: 2025.12.21101341
Summary: The new package transforms a user’s plain‑text search phrase into a structured, BM25‑ranked list of PostgreSQL search results. It takes the query text as input, forwards it to an LLM that rewrites the
Author-email: llmatch-bm25 <hi@eugene.plus>
License: MIT
Project-URL: Homepage, https://github.com/chigwell/llmatch-bm25
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: langchain-llm7>=0.0.0
Requires-Dist: llmatch-messages>=0.0.0
Requires-Dist: langchain-core>=0.3.0

# llmatch-bm25
[![PyPI version](https://badge.fury.io/py/llmatch-bm25.svg)](https://badge.fury.io/py/llmatch-bm25)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://static.pepy.tech/badge/llmatch-bm25)](https://pepy.tech/project/llmatch-bm25)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-blue)](https://www.linkedin.com/in/eugene-evstafev-716669181/)


A Python package that transforms a user's plain-text search phrase into a structured, BM25-ranked list of PostgreSQL search results.

## Features

- Transforms user input into BM25-friendly format using an LLM
- Runs the query against the database
- Returns a JSON array of hits with title, snippet, and BM25 relevance score
- Ensures LLM output matches expected JSON pattern with retries and diagnostics
- Quick and reliable way to embed BM25-based relevance into database-query workflows

## Installation

```bash
pip install llmatch_bm25
```

## Usage

### Basic Usage

```python
from llmatch_bm25 import llmatch_bm25

response = llmatch_bm25(user_input="your search query here")
```

### Using a Custom LLM

You can use any LLM compatible with LangChain's `BaseChatModel` interface. Here are examples with different LLMs:

#### Using OpenAI

```python
from langchain_openai import ChatOpenAI
from llmatch_bm25 import llmatch_bm25

llm = ChatOpenAI()
response = llmatch_bm25(user_input="your search query here", llm=llm)
```

#### Using Anthropic

```python
from langchain_anthropic import ChatAnthropic
from llmatch_bm25 import llmatch_bm25

llm = ChatAnthropic()
response = llmatch_bm25(user_input="your search query here", llm=llm)
```

#### Using Google

```python
from langchain_google_genai import ChatGoogleGenerativeAI
from llmatch_bm25 import llmatch_bm25

llm = ChatGoogleGenerativeAI()
response = llmatch_bm25(user_input="your search query here", llm=llm)
```

### Using LLM7 API Key

By default, the package uses the `ChatLLM7` from `langchain_llm7`. You can pass your own API key via an environment variable or directly in the function call.

#### Using Environment Variable

```python
import os
from llmatch_bm25 import llmatch_bm25

os.environ["LLM7_API_KEY"] = "your_api_key_here"
response = llmatch_bm25(user_input="your search query here")
```

#### Directly Passing API Key

```python
from llmatch_bm25 import llmatch_bm25

response = llmatch_bm25(user_input="your search query here", api_key="your_api_key_here")
```

## Parameters

- `user_input` (str): The user input text to process.
- `llm` (Optional[BaseChatModel]): The LangChain LLM instance to use. If not provided, the default `ChatLLM7` will be used.
- `api_key` (Optional[str]): The API key for LLM7. If not provided, the package will use the default `ChatLLM7` without an API key.

## Rate Limits

The default rate limits for LLM7 free tier are sufficient for most use cases of this package. If you want higher rate limits, you can pass your own API key via the environment variable `LLM7_API_KEY` or directly in the function call.

## Getting an API Key

You can get a free API key by registering at [LLM7](https://token.llm7.io/).

## Issues

If you encounter any issues, please report them on the [GitHub issues page](https://github.com/chigwell/llmatch-bm25/issues).

## Author

- **Eugene Evstafev**
- **Email**: hi@eugene.plus
- **GitHub**: [chigwell](https://github.com/chigwell)
