Upload Concept Memory base model

README.md

@@ -34,6 +34,15 @@ The three supported judgment types are:
   lowest to highest.
 - **Noul (Yes/No):** return a binary judgment for the instruction.
 
+The idea behind **Concept Memory** is to make a judgment through reusable,
+human-readable concepts. For example, when routing a support request, concepts
+such as “payment issue” or “integration failure” can connect details in the
+input to a possible outcome. The base checkpoint makes the typed judgment and
+can rank which concepts are relevant; a Concept Bank adds explicit links from
+those concepts to outcomes. This makes the reasoning path inspectable and lets
+you adapt the bank to your domain. A relevance score is a relative ranking, not
+a calibrated measure of evidence.
+
 The example below demonstrates Choice. The same `Question` interface supports
 the other judgment types by setting `type` to `"score"` or `"noul"` and
 providing the corresponding criteria where applicable.
@@ -109,6 +118,73 @@ print("Prediction:", predicted.id, "-", predicted.description)
 print("Probabilities:", result.probabilities.tolist())
 ```
 
+## Use a Concept Bank
+
+This example builds a small bank of domain concepts. Each concept describes a
+pattern and names the outcome it supports or contradicts. The model first
+ranks relevant concepts, then the helper blends their linked votes with the
+raw Choice probabilities only when the top bank outcome agrees with the raw
+model prediction. The helper is included in the repository's minimal runtime
+package.
+
+```python
+from concept_memory.concept_bank import apply_concept_votes
+
+concepts = [
+    {
+        "id": "payment_issue",
+        "name": "Payment issue",
+        "description": "A charge, invoice, refund, or subscription problem.",
+        "supports": ["billing"],
+    },
+    {
+        "id": "integration_failure",
+        "name": "Integration failure",
+        "description": "An API, SDK, or third-party integration is failing.",
+        "supports": ["technical"],
+    },
+    {
+        "id": "purchase_intent",
+        "name": "Purchase intent",
+        "description": "The customer is evaluating plans or pricing before buying.",
+        "supports": ["sales"],
+    },
+]
+
+concept_question = Question(
+    id="concepts",
+    type="choice",
+    instructions=f"Which concepts are most relevant to this input and question: {question.instructions}",
+    criteria=[
+        {"id": item["id"], "description": f"{item['name']}: {item['description']}"}
+        for item in concepts
+    ],
+)
+
+with torch.inference_mode():
+    raw_result, concept_result = model.predict(
+        "Stripe integration keeps failing after several attempts.",
+        [question, concept_question],
+    )
+
+outcomes = [
+    {"id": item.id, "description": item.description}
+    for item in question.normalized_criteria()
+]
+signals = [
+    {"description": concept["name"], "probability": float(probability)}
+    for concept, probability in zip(concepts, concept_result.probabilities.tolist())
+]
+adjusted_probabilities, contributions = apply_concept_votes(
+    raw_result.probabilities.tolist(), signals, concepts, outcomes
+)
+
+winner = max(range(len(adjusted_probabilities)), key=adjusted_probabilities.__getitem__)
+print("Concept-assisted prediction:", outcomes[winner]["description"])
+print("Adjusted probabilities:", adjusted_probabilities)
+print("Concept contributions:", contributions)
+```
+
 The Hub checkpoint is a PyTorch artifact for this project's Python package; it
 is not directly compatible with `transformers.AutoModel.from_pretrained`.
 

concept_memory/concept_bank.py

@@ -0,0 +1,82 @@
+"""Concept Bank vote blending shared by the playground and benchmark."""
+
+from __future__ import annotations
+
+from typing import Any
+
+CONCEPT_BANK_POLICY_VERSION = "agreement-gate-v2"
+
+
+def _resolve_outcome(value: Any, outcomes: list[dict[str, str]]) -> int | None:
+    target = str(value).strip().casefold()
+    for index, outcome in enumerate(outcomes):
+        if target in {outcome["id"].casefold(), outcome["description"].casefold()}:
+            return index
+    aliases = {"true": "yes", "false": "no", "1": "yes", "0": "no"}
+    target = aliases.get(target, target)
+    for index, outcome in enumerate(outcomes):
+        if target in {outcome["id"].casefold(), outcome["description"].casefold()}:
+            return index
+    return None
+
+
+def apply_concept_votes(
+    raw_probabilities: list[float],
+    signals: list[dict[str, Any]],
+    concepts: list[dict[str, Any]],
+    outcomes: list[dict[str, str]],
+) -> tuple[list[float], list[dict[str, Any]]]:
+    """Use linked bank votes only when they agree with the raw decision.
+
+    Relevance is a relative ranking, not a calibrated measure of evidence. Until
+    bank reliability is measured, a conflicting vote must not override the model.
+    """
+    votes = [0.0] * len(outcomes)
+    contributions = []
+    for signal, concept in zip(signals, concepts):
+        relevance = float(signal["probability"])
+        supports = concept.get("supports", []) or []
+        contradicts = concept.get("contradicts", []) or []
+        if isinstance(supports, str):
+            supports = [supports]
+        if isinstance(contradicts, str):
+            contradicts = [contradicts]
+        supported = sorted(
+            {i for value in supports if (i := _resolve_outcome(value, outcomes)) is not None}
+        )
+        opposed = sorted(
+            {i for value in contradicts if (i := _resolve_outcome(value, outcomes)) is not None}
+        )
+        concept_votes = [0.0] * len(outcomes)
+        if supported:
+            for i in supported:
+                concept_votes[i] += relevance / len(supported)
+        if opposed:
+            alternatives = [i for i in range(len(outcomes)) if i not in opposed]
+            if alternatives:
+                for i in alternatives:
+                    concept_votes[i] += relevance / len(alternatives)
+        for i, amount in enumerate(concept_votes):
+            votes[i] += amount
+        contributions.append(
+            {
+                "description": signal["description"],
+                "probability": relevance,
+                "votes": [
+                    {"description": outcomes[i]["description"], "weight": amount}
+                    for i, amount in enumerate(concept_votes)
+                    if amount > 0
+                ],
+            }
+        )
+    total = sum(votes)
+    if total <= 0:
+        return raw_probabilities, []
+    bank_probabilities = [value / total for value in votes]
+    raw_winner = max(range(len(raw_probabilities)), key=raw_probabilities.__getitem__)
+    bank_winner = max(range(len(bank_probabilities)), key=bank_probabilities.__getitem__)
+    if bank_winner != raw_winner:
+        return raw_probabilities, contributions
+    adjusted = [0.2 * raw + 0.8 * bank for raw, bank in zip(raw_probabilities, bank_probabilities)]
+    adjusted_total = sum(adjusted)
+    return [value / adjusted_total for value in adjusted], contributions