Add CrossEncoder integration

1_LogitScore/config.json

@@ -0,0 +1,4 @@
+{
+    "true_token_id": 9405,
+    "false_token_id": 2083
+}

README.md

@@ -58,6 +58,22 @@ If the document is not relevant, the model outputs `no` and stops. No contributi
 
 ## Quickstart
 
+Two ways to call the model. Both produce the **same** relevance score `s(q, d) = σ(ℓ_yes − ℓ_no)`. Use **A** when you also want `<contribution>` / `<evidence>`. Use **B** when you only need a score and want a drop-in replacement for any other CrossEncoder reranker.
+
+We use one shared example throughout so you can compare the outputs side by side:
+
+```python
+QUERY = "What is the boiling point of water at sea level?"
+DOCUMENTS = [
+    "Water boils at 100 C (212 F) at standard atmospheric pressure (1 atm), "
+    "which corresponds to sea-level conditions.",
+    "Mount Everest is the highest mountain on Earth, with a peak elevation "
+    "of 8,848 meters above sea level.",
+]
+```
+
+### A. Transformers (full output: score + contribution + evidence)
+
 ```python
 import torch
 from transformers import AutoModelForCausalLM, AutoTokenizer
@@ -80,7 +96,7 @@ INSTRUCTION = (
     "- Concise: drop query-irrelevant background.\n"
     "- Verbatim (no translation): proper nouns, terms, abbreviations, "
     "numbers, dates, code, URLs.\n"
-    "- Output language: multilingual doc -> query's language; else doc's language."
+    "- Output language: multilingual doc → query's language; else doc's language."
     "</evidence>"
 )
 
@@ -138,27 +154,62 @@ def rerank(query: str, doc: str, max_new_tokens: int = 512):
     return {"score": score, "text": text}
 
 
-example = rerank(
-    query="What is the boiling point of water at sea level?",
-    doc=(
-        "Water boils at 100 C (212 F) at standard atmospheric pressure (1 atm), "
-        "which corresponds to sea-level conditions."
-    ),
-)
-print(example)
+for doc in DOCUMENTS:
+    print(rerank(QUERY, doc))
 ```
 
-Expected shape of the output:
+Expected output (one dict per document):
 
 ```text
-{
-  "score": 0.98,
-  "text": "yes\n<contribution>...</contribution>\n<evidence>...</evidence>"
-}
+{"score": 0.98, "text": "yes\n<contribution>...</contribution>\n<evidence>...</evidence>"}
+{"score": 0.01, "text": "no"}
 ```
 
 For irrelevant pairs the score is close to 0 and `text` is just `"no"`.
 
+### B. Sentence Transformers CrossEncoder (score only)
+
+If you only need the score and want a drop-in CrossEncoder, the same model works directly with `sentence-transformers >= 5.4.0`. **Note:** in this mode `<contribution>` and `<evidence>` are not produced — only the calibrated relevance score.
+
+The system prompt and instruction are baked into the model's `chat_template.jinja` and are **not configurable** — the model was trained with one fixed prompt and only that prompt produces calibrated scores. You only pass `(query, document)`; the rest is hardcoded.
+
+```python
+import torch
+from sentence_transformers import CrossEncoder
+
+MODEL_PATH = "infgrad/Prism-Qwen3.5-Reranker-4B"  # or any sibling repo above
+
+ce = CrossEncoder(MODEL_PATH, model_kwargs={"torch_dtype": torch.bfloat16})
+
+# 1) Score (q, d) pairs. The default activation is Sigmoid, so scores are in (0, 1)
+# and equal to s(q, d) = sigmoid(logit_yes - logit_no) — identical to path A above.
+pairs = [(QUERY, doc) for doc in DOCUMENTS]
+scores = ce.predict(pairs)
+print(scores)
+# array([0.98, 0.01], dtype=float32)
+
+# 2) Rank documents directly.
+ranked = ce.rank(QUERY, DOCUMENTS, return_documents=True)
+for r in ranked:
+    print(f"{r['score']:.3f}\t{r['corpus_id']}\t{r['text'][:80]}")
+```
+
+To get raw logit differences instead of [0, 1] probabilities, pass `activation_fn=torch.nn.Identity()` to `ce.predict(...)`.
+
+#### A note on numerical parity with path A
+
+In **fp32**, paths A and B produce the same score to within ~1e-6 (verified across all five checkpoints).
+
+In **bf16** with the default batched call (`batch_size > 1`), CE scores can drift from path A by **~1–3%** for individual pairs. The cause is bf16 SDPA: when CrossEncoder pads shorter sequences to the longest in the batch, the bf16 attention numerics differ by a few ULPs vs running each pair alone, and the difference accumulates across layers before the final sigmoid. **Ranking order is unaffected.** If you need bit-for-bit parity with path A:
+
+```python
+# Option 1: keep bf16, disable batching
+ce.predict(pairs, batch_size=1)
+
+# Option 2: use fp32 (slower, larger memory)
+ce = CrossEncoder(MODEL_PATH, model_kwargs={"torch_dtype": torch.float32})
+```
+
 
 ## Notes on usage
 
@@ -170,4 +221,4 @@ For irrelevant pairs the score is close to 0 and `text` is just `"no"`.
 
 ## Contact
 
-Dun Zhang — `dunnzhang0@gmail.com` (independent researcher).
+Dun Zhang — `dunnzhang0@gmail.com` (independent researcher).

chat_template.jinja

@@ -1,154 +1,22 @@
-{%- set image_count = namespace(value=0) %}
-{%- set video_count = namespace(value=0) %}
-{%- macro render_content(content, do_vision_count, is_system_content=false) %}
-    {%- if content is string %}
-        {{- content }}
-    {%- elif content is iterable and content is not mapping %}
-        {%- for item in content %}
-            {%- if 'image' in item or 'image_url' in item or item.type == 'image' %}
-                {%- if is_system_content %}
-                    {{- raise_exception('System message cannot contain images.') }}
-                {%- endif %}
-                {%- if do_vision_count %}
-                    {%- set image_count.value = image_count.value + 1 %}
-                {%- endif %}
-                {%- if add_vision_id %}
-                    {{- 'Picture ' ~ image_count.value ~ ': ' }}
-                {%- endif %}
-                {{- '<|vision_start|><|image_pad|><|vision_end|>' }}
-            {%- elif 'video' in item or item.type == 'video' %}
-                {%- if is_system_content %}
-                    {{- raise_exception('System message cannot contain videos.') }}
-                {%- endif %}
-                {%- if do_vision_count %}
-                    {%- set video_count.value = video_count.value + 1 %}
-                {%- endif %}
-                {%- if add_vision_id %}
-                    {{- 'Video ' ~ video_count.value ~ ': ' }}
-                {%- endif %}
-                {{- '<|vision_start|><|video_pad|><|vision_end|>' }}
-            {%- elif 'text' in item %}
-                {{- item.text }}
-            {%- else %}
-                {{- raise_exception('Unexpected item type in content.') }}
-            {%- endif %}
-        {%- endfor %}
-    {%- elif content is none or content is undefined %}
-        {{- '' }}
-    {%- else %}
-        {{- raise_exception('Unexpected content type.') }}
-    {%- endif %}
-{%- endmacro %}
-{%- if not messages %}
-    {{- raise_exception('No messages provided.') }}
-{%- endif %}
-{%- if tools and tools is iterable and tools is not mapping %}
-    {{- '<|im_start|>system\n' }}
-    {{- "# Tools\n\nYou have access to the following functions:\n\n<tools>" }}
-    {%- for tool in tools %}
-        {{- "\n" }}
-        {{- tool | tojson }}
-    {%- endfor %}
-    {{- "\n</tools>" }}
-    {{- '\n\nIf you choose to call a function ONLY reply in the following format with NO suffix:\n\n<tool_call>\n<function=example_function_name>\n<parameter=example_parameter_1>\nvalue_1\n</parameter>\n<parameter=example_parameter_2>\nThis is the value for the second parameter\nthat can span\nmultiple lines\n</parameter>\n</function>\n</tool_call>\n\n<IMPORTANT>\nReminder:\n- Function calls MUST follow the specified format: an inner <function=...></function> block must be nested within <tool_call></tool_call> XML tags\n- Required parameters MUST be specified\n- You may provide optional reasoning for your function call in natural language BEFORE the function call, but NOT after\n- If there is no function call available, answer the question like normal with your current knowledge and do not tell the user about function calls\n</IMPORTANT>' }}
-    {%- if messages[0].role == 'system' %}
-        {%- set content = render_content(messages[0].content, false, true)|trim %}
-        {%- if content %}
-            {{- '\n\n' + content }}
-        {%- endif %}
-    {%- endif %}
-    {{- '<|im_end|>\n' }}
-{%- else %}
-    {%- if messages[0].role == 'system' %}
-        {%- set content = render_content(messages[0].content, false, true)|trim %}
-        {{- '<|im_start|>system\n' + content + '<|im_end|>\n' }}
-    {%- endif %}
-{%- endif %}
-{%- set ns = namespace(multi_step_tool=true, last_query_index=messages|length - 1) %}
-{%- for message in messages[::-1] %}
-    {%- set index = (messages|length - 1) - loop.index0 %}
-    {%- if ns.multi_step_tool and message.role == "user" %}
-        {%- set content = render_content(message.content, false)|trim %}
-        {%- if not(content.startswith('<tool_response>') and content.endswith('</tool_response>')) %}
-            {%- set ns.multi_step_tool = false %}
-            {%- set ns.last_query_index = index %}
-        {%- endif %}
-    {%- endif %}
-{%- endfor %}
-{%- if ns.multi_step_tool %}
-    {{- raise_exception('No user query found in messages.') }}
-{%- endif %}
-{%- for message in messages %}
-    {%- set content = render_content(message.content, true)|trim %}
-    {%- if message.role == "system" %}
-        {%- if not loop.first %}
-            {{- raise_exception('System message must be at the beginning.') }}
-        {%- endif %}
-    {%- elif message.role == "user" %}
-        {{- '<|im_start|>' + message.role + '\n' + content + '<|im_end|>' + '\n' }}
-    {%- elif message.role == "assistant" %}
-        {%- set reasoning_content = '' %}
-        {%- if message.reasoning_content is string %}
-            {%- set reasoning_content = message.reasoning_content %}
-        {%- else %}
-            {%- if '</think>' in content %}
-                {%- set reasoning_content = content.split('</think>')[0].rstrip('\n').split('<think>')[-1].lstrip('\n') %}
-                {%- set content = content.split('</think>')[-1].lstrip('\n') %}
-            {%- endif %}
-        {%- endif %}
-        {%- set reasoning_content = reasoning_content|trim %}
-        {%- if loop.index0 > ns.last_query_index %}
-            {{- '<|im_start|>' + message.role + '\n<think>\n' + reasoning_content + '\n</think>\n\n' + content }}
-        {%- else %}
-            {{- '<|im_start|>' + message.role + '\n' + content }}
-        {%- endif %}
-        {%- if message.tool_calls and message.tool_calls is iterable and message.tool_calls is not mapping %}
-            {%- for tool_call in message.tool_calls %}
-                {%- if tool_call.function is defined %}
-                    {%- set tool_call = tool_call.function %}
-                {%- endif %}
-                {%- if loop.first %}
-                    {%- if content|trim %}
-                        {{- '\n\n<tool_call>\n<function=' + tool_call.name + '>\n' }}
-                    {%- else %}
-                        {{- '<tool_call>\n<function=' + tool_call.name + '>\n' }}
-                    {%- endif %}
-                {%- else %}
-                    {{- '\n<tool_call>\n<function=' + tool_call.name + '>\n' }}
-                {%- endif %}
-                {%- if tool_call.arguments is defined %}
-                    {%- for args_name, args_value in tool_call.arguments|items %}
-                        {{- '<parameter=' + args_name + '>\n' }}
-                        {%- set args_value = args_value | tojson | safe if args_value is mapping or (args_value is sequence and args_value is not string) else args_value | string %}
-                        {{- args_value }}
-                        {{- '\n</parameter>\n' }}
-                    {%- endfor %}
-                {%- endif %}
-                {{- '</function>\n</tool_call>' }}
-            {%- endfor %}
-        {%- endif %}
-        {{- '<|im_end|>\n' }}
-    {%- elif message.role == "tool" %}
-        {%- if loop.previtem and loop.previtem.role != "tool" %}
-            {{- '<|im_start|>user' }}
-        {%- endif %}
-        {{- '\n<tool_response>\n' }}
-        {{- content }}
-        {{- '\n</tool_response>' }}
-        {%- if not loop.last and loop.nextitem.role != "tool" %}
-            {{- '<|im_end|>\n' }}
-        {%- elif loop.last %}
-            {{- '<|im_end|>\n' }}
-        {%- endif %}
-    {%- else %}
-        {{- raise_exception('Unexpected message role.') }}
-    {%- endif %}
-{%- endfor %}
-{%- if add_generation_prompt %}
-    {{- '<|im_start|>assistant\n' }}
-    {%- if enable_thinking is defined and enable_thinking is false %}
-        {{- '<think>\n\n</think>\n\n' }}
-    {%- else %}
-        {{- '<think>\n' }}
-    {%- endif %}
-{%- endif %}
+{%- set query_text = messages | selectattr("role", "eq", "query") | map(attribute="content") | first -%}
+{%- set document_text = messages | selectattr("role", "eq", "document") | map(attribute="content") | first -%}
+<|im_start|>system
+Judge whether the Document meets the requirements based on the Query and the Instruct provided. <|im_end|>
+<|im_start|>user
+<Instruct>: Judge if the document is relevant to the query. Reply "yes" or "no".
+On "yes", also emit:
+<contribution>One sentence covering every core point the document contributes to the query, without elaboration.</contribution>
+<evidence>Self-contained rewrite of the query-relevant content. Rules:
+- Faithful: rephrase only; add or infer nothing.
+- Self-contained: evidence alone must fully answer the query.
+- Concise: drop query-irrelevant background.
+- Verbatim (no translation): proper nouns, terms, abbreviations, numbers, dates, code, URLs.
+- Output language: multilingual doc → query's language; else doc's language.</evidence>
+<Query>: {{ query_text }}
+<Document>: {{ document_text }}<|im_end|>
+<|im_start|>assistant
+<think>
+
+</think>
+
+

config_sentence_transformers.json

@@ -0,0 +1,7 @@
+{
+  "__version__": {
+    "sentence_transformers": "5.4.1"
+  },
+  "activation_fn": "torch.nn.modules.activation.Sigmoid",
+  "model_type": "CrossEncoder"
+}

modules.json

@@ -0,0 +1,14 @@
+[
+  {
+    "idx": 0,
+    "name": "0",
+    "path": "",
+    "type": "sentence_transformers.base.modules.transformer.Transformer"
+  },
+  {
+    "idx": 1,
+    "name": "1",
+    "path": "1_LogitScore",
+    "type": "sentence_transformers.cross_encoder.modules.logit_score.LogitScore"
+  }
+]

sentence_bert_config.json

@@ -0,0 +1,15 @@
+{
+    "transformer_task": "text-generation",
+    "modality_config": {
+        "text": {
+            "method": "forward",
+            "method_output_name": "logits"
+        },
+        "message": {
+            "method": "forward",
+            "method_output_name": "logits",
+            "format": "flat"
+        }
+    },
+    "module_output_name": "causal_logits"
+}