zerosearch 0.1.0__tar.gz

zerosearch-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - name: Verify version matches tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          if ! ls dist/ | grep -qE -- "-${TAG}(-|\.)"; then
+            echo "::error::dist/ contents do not match tag v${TAG}"
+            ls dist/
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: dist/*
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

zerosearch-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# venv / tooling
+.venv/
+.python-version-local
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/

zerosearch-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

zerosearch-0.1.0/Makefile

@@ -0,0 +1,26 @@
+.PHONY: test setup shell coverage publish-build publish-clean release
+
+test:
+	uv run pytest
+
+setup:
+	uv sync --dev
+
+shell:
+	uv shell
+
+coverage:
+	uv run pytest --cov=zerosearch --cov-report=term-missing
+
+publish-build:
+	uv run hatch build
+
+publish-clean:
+	rm -r dist/
+
+# Release: tag the current version and push to trigger CI publish.
+release:
+	@VERSION=$$(grep -E "^__version__" zerosearch/__version__.py | sed -E "s/.*['\"]([^'\"]+)['\"].*/\1/"); \
+	echo "Releasing v$$VERSION"; \
+	git tag "v$$VERSION"; \
+	git push origin "v$$VERSION"

zerosearch-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: zerosearch
+Version: 0.1.0
+Summary: A tiny, zero-dependency BM25-lite in-memory text search index.
+Project-URL: Homepage, https://github.com/alexeygrigorev/zerosearch
+Project-URL: Repository, https://github.com/alexeygrigorev/zerosearch
+Author-email: Alexey Grigorev <alexey.s.grigoriev@gmail.com>
+License: WTFPL
+Keywords: bm25,information-retrieval,minsearch,search,tf-idf,zero-dependency
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# zerosearch
+
+A tiny, **zero-dependency** BM25-lite in-memory text search index — standard
+library only, a single small module, and good enough to power retrieval for a
+RAG pipeline. Designed to run anywhere Python runs, including constrained
+environments like Cloudflare Python Workers (Pyodide) where pulling in
+`scikit-learn`/`numpy` is not an option.
+
+It is a spiritual cousin of [`minsearch`](https://github.com/alexeygrigorev/minsearch),
+with the same `Index(text_fields, keyword_fields).fit(docs).search(query)` shape,
+but reimplemented from scratch with no third-party dependencies.
+
+## Install
+
+```bash
+pip install zerosearch
+```
+
+## Usage
+
+```python
+from zerosearch import Index
+
+docs = [
+    {"id": "1", "title": "Docker compose basics", "text": "how to start services", "course": "de"},
+    {"id": "2", "title": "Kafka consumers", "text": "consumer groups explained", "course": "de"},
+]
+
+index = Index(
+    text_fields=["title", "text"],
+    keyword_fields=["id", "course"],
+).fit(docs)
+
+results = index.search(
+    "how do I start docker compose",
+    filter_dict={"course": "de"},     # exact-match keyword filter
+    boost_dict={"title": 3.0, "text": 1.0},  # per-field boosts
+    num_results=5,
+)
+for r in results:
+    print(r["score"], r["title"])
+```
+
+Each result is a shallow copy of the original document dict with an added
+`"score"` key.
+
+## How it works
+
+* **Tokenizer** — lowercased word/number tokens; keeps `+ . # _ -` *inside* a
+  token so `c++`, `node.js`, `f-string` survive (a token must start with a
+  letter/digit). Drops 1-character tokens and a small English stop-word list
+  (both overridable).
+* **Inverted index** — built once in `fit()`. A query only scores documents that
+  actually contain a query term, so search is fast even on large corpora.
+* **Ranking** — BM25-lite: each query term contributes
+  `boost * idf * (term_frequency / sqrt(field_length))` per field. IDF and
+  document frequencies are computed over the filtered candidate set.
+
+## Customizing
+
+```python
+Index(
+    text_fields=["title", "text"],
+    stop_words={"the", "a", "an"},          # replace the default stop words
+    tokenizer=lambda s: s.lower().split(),  # or plug in your own tokenizer
+)
+```
+
+## License
+
+WTFPL.

zerosearch-0.1.0/README.md

@@ -0,0 +1,71 @@
+# zerosearch
+
+A tiny, **zero-dependency** BM25-lite in-memory text search index — standard
+library only, a single small module, and good enough to power retrieval for a
+RAG pipeline. Designed to run anywhere Python runs, including constrained
+environments like Cloudflare Python Workers (Pyodide) where pulling in
+`scikit-learn`/`numpy` is not an option.
+
+It is a spiritual cousin of [`minsearch`](https://github.com/alexeygrigorev/minsearch),
+with the same `Index(text_fields, keyword_fields).fit(docs).search(query)` shape,
+but reimplemented from scratch with no third-party dependencies.
+
+## Install
+
+```bash
+pip install zerosearch
+```
+
+## Usage
+
+```python
+from zerosearch import Index
+
+docs = [
+    {"id": "1", "title": "Docker compose basics", "text": "how to start services", "course": "de"},
+    {"id": "2", "title": "Kafka consumers", "text": "consumer groups explained", "course": "de"},
+]
+
+index = Index(
+    text_fields=["title", "text"],
+    keyword_fields=["id", "course"],
+).fit(docs)
+
+results = index.search(
+    "how do I start docker compose",
+    filter_dict={"course": "de"},     # exact-match keyword filter
+    boost_dict={"title": 3.0, "text": 1.0},  # per-field boosts
+    num_results=5,
+)
+for r in results:
+    print(r["score"], r["title"])
+```
+
+Each result is a shallow copy of the original document dict with an added
+`"score"` key.
+
+## How it works
+
+* **Tokenizer** — lowercased word/number tokens; keeps `+ . # _ -` *inside* a
+  token so `c++`, `node.js`, `f-string` survive (a token must start with a
+  letter/digit). Drops 1-character tokens and a small English stop-word list
+  (both overridable).
+* **Inverted index** — built once in `fit()`. A query only scores documents that
+  actually contain a query term, so search is fast even on large corpora.
+* **Ranking** — BM25-lite: each query term contributes
+  `boost * idf * (term_frequency / sqrt(field_length))` per field. IDF and
+  document frequencies are computed over the filtered candidate set.
+
+## Customizing
+
+```python
+Index(
+    text_fields=["title", "text"],
+    stop_words={"the", "a", "an"},          # replace the default stop words
+    tokenizer=lambda s: s.lower().split(),  # or plug in your own tokenizer
+)
+```
+
+## License
+
+WTFPL.

zerosearch-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zerosearch"
+description = "A tiny, zero-dependency BM25-lite in-memory text search index."
+readme = "README.md"
+license = {text = "WTFPL"}
+requires-python = ">=3.10"
+dynamic = ["version"]
+keywords = ["search", "bm25", "tf-idf", "information-retrieval", "minsearch", "zero-dependency"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing :: Indexing",
+    "Intended Audience :: Developers",
+]
+
+dependencies = [
+    # Intentionally empty: standard library only.
+]
+
+authors = [
+    {name = "Alexey Grigorev", email = "alexey.s.grigoriev@gmail.com"}
+]
+
+[project.urls]
+Homepage = "https://github.com/alexeygrigorev/zerosearch"
+Repository = "https://github.com/alexeygrigorev/zerosearch"
+
+[dependency-groups]
+dev = [
+    "hatch",
+    "pytest",
+    "pytest-cov",
+    "ruff",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["zerosearch"]
+
+[tool.hatch.version]
+path = "zerosearch/__version__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

zerosearch-0.1.0/tests/test_index.py

@@ -0,0 +1,101 @@
+import math
+
+import pytest
+
+from zerosearch import DEFAULT_STOP_WORDS, Index, tokenize
+
+
+DOCS = [
+    {"id": "1", "title": "Docker compose basics", "text": "how to start services with docker", "course": "de"},
+    {"id": "2", "title": "Kafka consumers", "text": "consumer groups explained in kafka", "course": "de"},
+    {"id": "3", "title": "Docker networking", "text": "containers talk over a docker network", "course": "mlops"},
+    {"id": "4", "title": "Pandas joins", "text": "merge and join dataframes", "course": "ml"},
+]
+
+
+def make_index():
+    return Index(text_fields=["title", "text"], keyword_fields=["id", "course"]).fit(DOCS)
+
+
+def test_tokenize_keeps_technical_tokens():
+    # Punctuation is kept *inside* a token (a token must start with [a-z0-9]),
+    # so a leading dot in ".env" is dropped.
+    assert tokenize("Node.js and C++ with f-strings") == ["node.js", "c++", "f-strings"]
+
+
+def test_tokenize_drops_stopwords_and_single_chars():
+    assert "the" not in tokenize("the a docker")
+    assert tokenize("a I") == []  # all stop words / single char
+
+
+def test_empty_query_returns_nothing():
+    assert make_index().search("") == []
+    assert make_index().search("   ") == []
+
+
+def test_basic_ranking_finds_relevant_doc():
+    results = make_index().search("docker compose", num_results=5)
+    assert results
+    assert results[0]["id"] == "1"
+    assert all("score" in r for r in results)
+
+
+def test_results_are_sorted_by_score_desc():
+    results = make_index().search("docker", num_results=5)
+    scores = [r["score"] for r in results]
+    assert scores == sorted(scores, reverse=True)
+
+
+def test_keyword_filter_restricts_candidates():
+    results = make_index().search("docker", filter_dict={"course": "mlops"}, num_results=5)
+    assert [r["id"] for r in results] == ["3"]
+
+
+def test_filter_with_no_matches_returns_empty():
+    assert make_index().search("docker", filter_dict={"course": "nonexistent"}) == []
+
+
+def test_boost_changes_ranking():
+    index = make_index()
+    # "kafka" appears in both title and text of doc 2; boosting title should not
+    # crash and should keep doc 2 on top.
+    results = index.search("kafka", boost_dict={"title": 5.0, "text": 1.0})
+    assert results[0]["id"] == "2"
+
+
+def test_num_results_caps_output():
+    assert len(make_index().search("docker", num_results=1)) == 1
+
+
+def test_search_does_not_mutate_source_docs():
+    index = make_index()
+    index.search("docker")
+    assert all("score" not in doc for doc in DOCS)
+
+
+def test_unknown_term_returns_empty():
+    assert make_index().search("zzzznonexistentterm") == []
+
+
+def test_custom_stopwords():
+    index = Index(text_fields=["text"], stop_words={"docker"}).fit(DOCS)
+    # "docker" is now a stop word, so a docker-only query finds nothing.
+    assert index.search("docker") == []
+
+
+def test_custom_tokenizer():
+    index = Index(text_fields=["title"], tokenizer=lambda s: s.lower().split()).fit(DOCS)
+    assert index.search("kafka")[0]["id"] == "2"
+
+
+def test_idf_is_positive_and_finite():
+    index = make_index()
+    results = index.search("docker")
+    for r in results:
+        assert math.isfinite(r["score"]) and r["score"] > 0
+
+
+def test_default_stopwords_frozen():
+    assert "the" in DEFAULT_STOP_WORDS
+    with pytest.raises(AttributeError):
+        DEFAULT_STOP_WORDS.add("x")  # frozenset has no add