Create README.md

README.md

@@ -0,0 +1,127 @@
+---
+language: en
+library_name: bm25s
+tags:
+- bm25
+- bm25s
+- retrieval
+- search
+- lexical
+---
+
+# BM25S Index
+
+This is a BM25S index created with the [`bm25s` library](https://github.com/xhluca/bm25s) (version `{version}`), an ultra-fast implementation of BM25. It can be used for lexical retrieval tasks.
+
+BM25S Related Links:
+
+* 🏠[Homepage](https://bm25s.github.io)
+* 💻[GitHub Repository](https://github.com/xhluca/bm25s)
+* 🤗[Blog Post](https://huggingface.co/blog/xhluca/bm25s)
+* 📝[Technical Report](https://arxiv.org/abs/2407.03618)
+
+
+## Installation
+
+You can install the `bm25s` library with `pip`:
+
+```bash
+pip install "bm25s==0.2.0"
+
+# For huggingface hub usage
+pip install huggingface_hub
+```
+
+## Loading a `bm25s` index
+
+You can use this index for information retrieval tasks. Here is an example:
+
+```python
+import bm25s
+from bm25s.hf import BM25HF
+
+# Load the index
+retriever = BM25HF.load_from_hub("{username}/{repo_name}}")
+
+# You can retrieve now
+query = "a cat is a feline"
+results = retriever.retrieve(bm25s.tokenize(query), k=3)
+```
+
+## Saving a `bm25s` index
+
+You can save a `bm25s` index to the Hugging Face Hub. Here is an example:
+
+```python
+import bm25s
+from bm25s.hf import BM25HF
+
+corpus = [
+    "a cat is a feline and likes to purr",
+    "a dog is the human's best friend and loves to play",
+    "a bird is a beautiful animal that can fly",
+    "a fish is a creature that lives in water and swims",
+]
+
+retriever = BM25HF(corpus=corpus)
+retriever.index(bm25s.tokenize(corpus))
+
+token = None  # You can get a token from the Hugging Face website
+retriever.save_to_hub("{username}/{repo_name}", token=token)
+```
+
+## Advanced usage
+
+You can leverage more advanced features of the BM25S library during `load_from_hub`:
+
+```python
+# Load corpus and index in memory-map (mmap=True) to reduce memory
+retriever = BM25HF.load_from_hub("{username}/{repo_name}", load_corpus=True, mmap=True)
+
+# Load a different branch/revision
+retriever = BM25HF.load_from_hub("{username}/{repo_name}", revision="main")
+
+# Change directory where the local files should be downloaded
+retriever = BM25HF.load_from_hub("{username}/{repo_name}", local_dir="/path/to/dir")
+
+# Load private repositories with a token:
+retriever = BM25HF.load_from_hub("{username}/{repo_name}", token=token)
+```
+
+## Stats
+
+This dataset was created using the following data:
+
+| Statistic | Value |
+| --- | --- |
+| Number of documents | {num_docs} |
+| Number of tokens | {num_tokens} |
+| Average tokens per document | {avg_tokens_per_doc} |
+
+## Parameters
+
+The index was created with the following parameters:
+
+| Parameter | Value |
+| --- | --- |
+| k1 | `{k1}` |
+| b | `{b}` |
+| delta | `{delta}` |
+| method | `{method}` |
+| idf method | `{idf_method}` |
+
+## Citation
+
+To cite `bm25s`, please use the following bibtex:
+
+```
+@misc{lu_2024_bm25s,
+      title={BM25S: Orders of magnitude faster lexical search via eager sparse scoring}, 
+      author={Xing Han Lù},
+      year={2024},
+      eprint={2407.03618},
+      archivePrefix={arXiv},
+      primaryClass={cs.IR},
+      url={https://arxiv.org/abs/2407.03618}, 
+}
+```