decisions-reranker 0.2.0__tar.gz

decisions_reranker-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Malte Weber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

decisions_reranker-0.2.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: decisions-reranker
+Version: 0.2.0
+Summary: A simple reranker for RAG systems, built on the OpenAI Decisions API. Requires an OpenAI API key.
+Author: Malte Weber
+Author-email: Malte Weber <dev-weber@posteo.de>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: openai>=3.28.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+## decisions-reranker
+
+A simple reranker for RAG systems, built on top of the OpenAI Decisions API.
+
+OpenAI doesn't offer a dedicated reranking model, so this package uses the Decisions API to fill that gap. If your stack already runs on OpenAI, you can add reranking without bringing in another provider.
+
+### requirements
+
+This package calls the OpenAI API and requires an OpenAI API key. By default it creates an `OpenAI()` client, which reads the key from the `OPENAI_API_KEY` environment variable:
+
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+Alternatively, pass your own configured client:
+
+```python
+from openai import OpenAI
+from decisions_reranker import DecisionsReranker
+
+reranker = DecisionsReranker(client=OpenAI(api_key="sk-..."))
+```
+
+Each `filter()` or `rerank()` call makes one request to the Decisions API and is billed to your OpenAI account.
+
+### methods
+
+```python
+DecisionsReranker().filter()
+```
+
+Filters a list of documents for relevance regarding a given query. Returns only documents above a given threshold.
+
+```python
+DecisionsReranker().rerank()
+```
+
+Reorders a list of documents by relevance regarding a given query. Returns all documents in a new order.
+
+### parameters
+
+The DecisionsReranker constructor takes the following parameters. All of them are optional:
+
+```python
+    client: OpenAI | None = None,
+    model: str = "gpt-6-luna",
+    instruction: str = DEFAULT_INSTRUCTION,
+    threshold: float = 0.5
+```
+
+### Example usage
+
+```python
+from decisions_reranker import DecisionsReranker, Document
+
+reranker = DecisionsReranker(
+    instruction="Is this snippet relevant to answer the given query: {document}. Only answer with true if the snippet really contains directly relevant information for the question",
+    threshold=0.8,
+)
+
+query = "How can I reduce memory usage in a Python application?"
+
+documents = [
+    { "id": "d01", "text": "Python generators yield items lazily, so you avoid loading an entire list into memory at once."},
+    { "id": "d02", "text": "Defining __slots__ on a Python class removes the per-instance __dict__ and cuts memory overhead."},
+    { "id": "d03", "text": "The tracemalloc module shows which lines of Python code allocate the most memory."},
+    { "id": "d04", "text": "Python's GIL prevents multiple threads from executing bytecode in parallel."},
+    { "id": "d05", "text": "NumPy arrays store numbers far more compactly than Python lists of int objects."}
+]
+
+documents = [Document(id=d["id"], text=d["text"]) for d in documents]
+
+filtered =  reranker.filter(query, documents)
+
+reranked = reranker.rerank(query, documents)
+
+```

decisions_reranker-0.2.0/README.md

@@ -0,0 +1,77 @@
+## decisions-reranker
+
+A simple reranker for RAG systems, built on top of the OpenAI Decisions API.
+
+OpenAI doesn't offer a dedicated reranking model, so this package uses the Decisions API to fill that gap. If your stack already runs on OpenAI, you can add reranking without bringing in another provider.
+
+### requirements
+
+This package calls the OpenAI API and requires an OpenAI API key. By default it creates an `OpenAI()` client, which reads the key from the `OPENAI_API_KEY` environment variable:
+
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+Alternatively, pass your own configured client:
+
+```python
+from openai import OpenAI
+from decisions_reranker import DecisionsReranker
+
+reranker = DecisionsReranker(client=OpenAI(api_key="sk-..."))
+```
+
+Each `filter()` or `rerank()` call makes one request to the Decisions API and is billed to your OpenAI account.
+
+### methods
+
+```python
+DecisionsReranker().filter()
+```
+
+Filters a list of documents for relevance regarding a given query. Returns only documents above a given threshold.
+
+```python
+DecisionsReranker().rerank()
+```
+
+Reorders a list of documents by relevance regarding a given query. Returns all documents in a new order.
+
+### parameters
+
+The DecisionsReranker constructor takes the following parameters. All of them are optional:
+
+```python
+    client: OpenAI | None = None,
+    model: str = "gpt-6-luna",
+    instruction: str = DEFAULT_INSTRUCTION,
+    threshold: float = 0.5
+```
+
+### Example usage
+
+```python
+from decisions_reranker import DecisionsReranker, Document
+
+reranker = DecisionsReranker(
+    instruction="Is this snippet relevant to answer the given query: {document}. Only answer with true if the snippet really contains directly relevant information for the question",
+    threshold=0.8,
+)
+
+query = "How can I reduce memory usage in a Python application?"
+
+documents = [
+    { "id": "d01", "text": "Python generators yield items lazily, so you avoid loading an entire list into memory at once."},
+    { "id": "d02", "text": "Defining __slots__ on a Python class removes the per-instance __dict__ and cuts memory overhead."},
+    { "id": "d03", "text": "The tracemalloc module shows which lines of Python code allocate the most memory."},
+    { "id": "d04", "text": "Python's GIL prevents multiple threads from executing bytecode in parallel."},
+    { "id": "d05", "text": "NumPy arrays store numbers far more compactly than Python lists of int objects."}
+]
+
+documents = [Document(id=d["id"], text=d["text"]) for d in documents]
+
+filtered =  reranker.filter(query, documents)
+
+reranked = reranker.rerank(query, documents)
+
+```

decisions_reranker-0.2.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "decisions-reranker"
+version = "0.2.0"
+description = "A simple reranker for RAG systems, built on the OpenAI Decisions API. Requires an OpenAI API key."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["openai>=3.28.0"]
+
+[[project.authors]]
+name = "Malte Weber"
+email = "dev-weber@posteo.de"
+
+[build-system]
+requires = ["uv_build>=0.12.15,<0.13.0"]
+build-backend = "uv_build"

decisions_reranker-0.2.0/pyproject.toml.orig

@@ -0,0 +1,18 @@
+[project]
+name = "decisions-reranker"
+version = "0.2.0"
+description = "A simple reranker for RAG systems, built on the OpenAI Decisions API. Requires an OpenAI API key."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Malte Weber", email = "dev-weber@posteo.de" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "openai>=3.28.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.15,<0.13.0"]
+build-backend = "uv_build"

decisions_reranker-0.2.0/src/decisions_reranker/__init__.py

@@ -0,0 +1,3 @@
+from decisions_reranker.reranker import DecisionsReranker, Document, ScoredDocument
+
+__all__ = ["DecisionsReranker", "Document", "ScoredDocument"]

decisions_reranker-0.2.0/src/decisions_reranker/reranker.py

@@ -0,0 +1,92 @@
+from dataclasses import dataclass
+
+from openai import OpenAI
+from openai.types.decision import AnswerAnswerResourcePredicate
+from openai.types.decision_create_params import QuestionQuestionParamPredicate
+
+DEFAULT_INSTRUCTION = "Is this snippet relevant to answer the given query: {document}"
+
+
+@dataclass
+class Document:
+    id: str
+    text: str
+
+@dataclass
+class ScoredDocument:
+    id: str
+    text: str
+    score: float
+
+
+def _validate_instruction(instruction: str) -> str:
+    if "{document}" not in instruction:
+        raise ValueError("instruction must contain the placeholder '{document}'")
+    try:
+        instruction.format(document="")
+    except (KeyError, IndexError) as error:
+        raise ValueError(f"instruction contains an unknown placeholder: {error}") from error
+    return instruction
+
+
+class DecisionsReranker:
+    def __init__(
+        self,
+        client: OpenAI | None = None,
+        model: str = "gpt-6-luna",
+        instruction: str = DEFAULT_INSTRUCTION,
+        threshold: float = 0.5
+    ) -> None:
+        self._client = client or OpenAI()
+        self._model = model
+        self._instruction = _validate_instruction(instruction)
+        self._threshold = threshold
+
+    def filter(
+        self,
+        query: str,
+        documents: list[Document],
+        threshold: float | None = None,
+        instruction: str | None = None,
+    ) -> list[ScoredDocument]:
+        cutoff = self._threshold if threshold is None else threshold
+        filtered = [
+            ScoredDocument(document.id, document.text, score)
+            for document, score in self._score(query, documents, instruction)
+            if score > cutoff
+        ]
+        filtered_sorted = sorted(filtered, key=lambda d: d.score, reverse=True)
+        return filtered_sorted
+
+    def rerank(
+        self,
+        query: str,
+        documents: list[Document],
+        instruction: str | None = None,
+    ) -> list[ScoredDocument]:
+        scored = sorted(self._score(query, documents, instruction), key=lambda item: item[1], reverse=True)
+        return [ScoredDocument(document.id, document.text, score) for document, score in scored]
+
+    def _score(
+        self,
+        query: str,
+        documents: list[Document],
+        instruction: str | None,
+    ) -> list[tuple[Document, float]]:
+        template = self._instruction if instruction is None else _validate_instruction(instruction)
+        decision = self._client.decisions.create(
+            model=self._model,
+            input=query,
+            questions=[
+                QuestionQuestionParamPredicate(
+                    type="predicate",
+                    name=document.id,
+                    instructions=template.format(document=document.text),
+                )
+                for document in documents
+            ],
+        )
+        return [
+            (document, answer.probability if isinstance(answer, AnswerAnswerResourcePredicate) else 0.0)
+            for document, answer in zip(documents, decision.answers, strict=True)
+        ]