Upload Concept Memory base model

README.md

@@ -34,159 +34,69 @@ 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.
+## Concept Memory and the Concept Bank
+
+Jev- or Laya-style typed decision systems return a structured judgment, such as
+a Choice label and its probabilities. Concept Memory can make that same kind of
+prediction and optionally add a **Concept Bank**: a separate, editable set of
+human-readable concepts with links to outcomes. For example, “integration
+failure” may support “Technical,” while “payment issue” may support “Billing.”
+This externalizes some domain knowledge from the model's learned weights so it
+can be inspected, reused, and adapted to different tasks or domains.
+
+With a bank, inference has two paths: the base model predicts an outcome, and a
+second Choice question ranks which bank concepts are relevant to the input.
+The bank maps those relevant concepts to outcome votes. In the current helper,
+the bank adjusts the probabilities only when its leading outcome agrees with
+the base model's leading outcome; the adjusted distribution is a blend of 20%
+raw model probabilities and 80% normalized bank votes. The bank therefore
+provides constrained decision support rather than an independent rule engine.
+
+Concept rankings and declared concept-to-outcome links make part of the
+decision process inspectable. They are not proof of the model's internal
+causal reasoning: relevance is a relative ranking, not calibrated evidence,
+and a ranked concept is not necessarily what caused the raw prediction.
+
+## What this does and does not establish
+
+The Concept Bank offers a way to change or extend domain mappings without
+retraining the encoder, but new concepts still need evaluation on representative
+examples. This is an architectural capability, not evidence that Concept
+Memory is more accurate than Jev, Laya, or another model. Accuracy, calibration,
+robustness, and latency need head-to-head evaluation on the same data and
+conditions before making comparative performance claims.
+
+The current implementation ranks concepts with a second Choice question and
+uses an agreement gate. It does not independently detect each concept or let a
+bank vote overturn a raw prediction. Concept hierarchies, dependencies,
+contradictions, interventions, and provenance tracking are possible research
+directions, not capabilities of this checkpoint.
 
 ## Files
 
 - `model.pt`: PyTorch state dictionary and training metadata.
 - `config.json`: encoder, task, and training run metadata.
-- `concept_memory/`: the minimal model runtime modules needed for inference.
-- `example.py`: a runnable end to end Choice prediction example.
 
-## Run a prediction
+The Python inference implementation is not distributed in this model
+repository. The checkpoint is a PyTorch artifact and is not directly
+compatible with `transformers.AutoModel.from_pretrained`. For interactive
+inference, use the [Concept Memory playground](https://dewmal--concept-memory-playground-playground.modal.run/).
 
-Use Python 3.11 or newer. Install the runtime dependencies:
+## Example Concept Bank entry
 
-```bash
-pip install torch transformers huggingface_hub
-```
-
-Run the standalone example with:
-
-```bash
-python example.py
-```
-
-Download this model repository. It contains only the small `concept_memory`
-runtime package needed to load the checkpoint, rather than the full training
-project. Then construct a question with the criteria you want the model to
-judge and inspect its prediction and probabilities:
-
-```python
-import torch
-import sys
-from pathlib import Path
-from huggingface_hub import snapshot_download
-
-repo_id = "Syigen/rgcm"
-repo_path = snapshot_download(repo_id)
-sys.path.insert(0, repo_path)
-
-from concept_memory import ConceptMemoryModel
-from concept_memory.types import Question
-
-checkpoint = Path(repo_path) / "model.pt"
-payload = torch.load(checkpoint, map_location="cpu", weights_only=False)
-model = ConceptMemoryModel.from_pretrained(
-    payload["encoder"],
-    decision_size=payload["decision_size"],
-    max_length=payload["max_length"],
-)
-model.load_state_dict(payload["model_state_dict"])
-model.eval()
-
-question = Question(
-    id="intent",
-    type="choice",
-    instructions="Which team should handle this customer request?",
-    criteria=[
-        {"id": "billing", "description": "Payment or subscription issues"},
-        {"id": "technical", "description": "Bugs or integration problems"},
-        {"id": "sales", "description": "Pricing or account questions"},
-    ],
-)
-
-with torch.inference_mode():
-    result = model.predict(
-        "Stripe integration keeps failing after several attempts.", [question]
-    )[0]
-
-criteria = question.normalized_criteria()
-predicted = criteria[result.prediction.item()]
-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)
+```json
+{
+  "id": "integration_failure",
+  "name": "Integration failure",
+  "description": "An API, SDK, or third-party integration is failing.",
+  "supports": ["technical"],
+  "contradicts": ["sales"]
+}
 ```
 
-The Hub checkpoint is a PyTorch artifact for this project's Python package; it
-is not directly compatible with `transformers.AutoModel.from_pretrained`.
+Concept entries describe reusable patterns and link them to outcome IDs or
+labels. Add entries to the playground's Concept Bank field to inspect which
+concepts rank as relevant and how their links contribute to a prediction.
 
 ## Training metadata