contextattr 0.1.0__tar.gz

contextattr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Surya Rayala
+
+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.

contextattr-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+# The source archive: the package (found by setuptools), README.md, LICENSE, and the tests with what they need, which
+# include the package folders' READMEs (tests/test_package.py). The wheel takes none of these (include-package-data).
+recursive-include src/contextattr README.md
+graft tests
+graft examples
+prune examples/runs
+global-exclude __pycache__ *.py[cod] *.sqlite

contextattr-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: contextattr
+Version: 0.1.0
+Summary: Context attribution: which parts of a prompt make a model give an output, for a model hosted anywhere
+Author: Surya Rayala
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Surya-Rayala/contextattr
+Project-URL: Documentation, https://github.com/Surya-Rayala/contextattr/tree/main/docs
+Project-URL: Issues, https://github.com/Surya-Rayala/contextattr/issues
+Keywords: context attribution,explainability,interpretability,LLM,feature interactions,Shapley values,SPEX
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scikit-learn>=1.9
+Provides-Extra: interactions
+Requires-Dist: shapiq[sparse]<1.9,>=1.8; extra == "interactions"
+Requires-Dist: sparse-transform<0.3,>=0.2.1; extra == "interactions"
+Requires-Dist: lightgbm>=4; extra == "interactions"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: hypothesis>=6.100; extra == "test"
+Dynamic: license-file
+
+# ContextAttr
+
+Find out which parts of a prompt make a language model give an answer.
+
+You split a prompt into parts: sentences, documents, words, or any pieces you choose. ContextAttr asks your model about many copies of the prompt with some parts removed. It then tells you how much each part, and each small group of parts working together, pushes the model towards an answer, and how far to trust that result. It works with any model, wherever it runs: you connect yours with a short wrapper.
+
+Version 0.1.0 is an early release: the interface may still change.
+
+## Install
+
+```
+pip install contextattr
+```
+
+Add `[interactions]` (`pip install "contextattr[interactions]"`) for SPEX and the other methods that find parts which matter only together. With uv: `uv add contextattr`. Needs Python 3.12 or later.
+
+## Try it
+
+This runs anywhere in seconds: `ToyModel` stands in for a real model.
+
+```python
+import contextattr as ca
+
+prompt = ca.Prompt("rio", messages=[{"role": "user", "content": [
+    ca.Unit("d1", "Rio Carnival takes place in February or March.", sep="\n"),
+    ca.Unit("d2", "Summer in Brazil runs from December to March.", sep="\n"),
+    ca.Unit("d3", "Winter in Brazil runs from June to September.", sep="\n"),
+    "Question: What is the weather like during Rio Carnival?"]}],
+    responses=[ca.Response("bad", "It is cold, because Carnival is in winter.", label="negative"),
+               ca.Response("good", "It is hot and humid: it is summer in Brazil.", label="positive")])
+
+model = ca.ToyModel.demo()        # a stand-in: put your own model's wrapper here
+e = ca.explain(prompt, model, ca.Contrast(), method="kernelshap", budget=8)
+print(e)
+```
+
+It prints:
+
+```
+rio · KernelSHAP(paired=True) · 8 masks · R² 0.991 on 128 test masks · noise 0 · 22 requests
+  d3              +0.2500  Winter in Brazil runs from June to September.
+  d1              -0.0234  Rio Carnival takes place in February or March.
+  d2              -0.2854  Summer in Brazil runs from December to March.
+```
+
+**What the example says:**
+
+| In the code | Means |
+|---|---|
+| `ca` | the package, under the short name all the docs use |
+| `ca.Prompt("rio", messages=...)` | one prompt, named `rio`, as chat messages |
+| `ca.Unit("d1", "...", sep="\n")` | a part that may be removed, named `d1`. `sep` is text that goes with it, here the line break. Everything else, like the question, always stays |
+| `ca.Response("bad", "...", label="negative")` | an answer the model could give. `negative` marks the answer you do not want, `positive` the one you do |
+| `model` | the wrapper around your model |
+| `ca.Contrast()` | what to explain: how much more likely the model finds the unwanted answers than the wanted ones |
+| `method="kernelshap"`, `budget=8` | how the scores are worked out, and how many copies of the prompt, each with some parts removed, the model is asked about |
+| `e` | the result |
+
+**How to read the output:**
+
+- The first line names the prompt and the method and says how far to trust the result. R² close to 1 means the scores describe the model well; close to 0, do not use them.
+- Then each part with its score, highest first. A positive score pushes the model towards the unwanted answer: `d3`, the sentence about winter, is what makes this model say "cold". A negative score pushes it away: `d2` protects against it. A score near zero means the part hardly matters.
+- `e.scores` gives the scores as a dictionary, and `e.to_html("report.html")` writes a page with each part shaded by its score.
+
+[Reading a result](https://github.com/Surya-Rayala/contextattr/blob/main/docs/results.md) shows the output of every method on this example and what its scores mean.
+
+## Use it with your own model
+
+ContextAttr reaches your model through a small class that you write, a *wrapper*. [Writing a wrapper](https://github.com/Surya-Rayala/contextattr/blob/main/docs/wrapper.md) is the guide, with two complete wrappers to copy from: one for an API and one for a model you run yourself.
+
+1. **Get the file to fill in.** `contextattr template my_wrapper.py` writes it. It needs one or both of:
+   - `generate`: writes replies to a prompt. Every model can do this, including the OpenAI, Gemini and Anthropic APIs.
+   - `score`: gives the log-probability of each token of a given answer. Possible when you run the model yourself, in your own code or on a vLLM or SGLang server.
+2. **Check it.** `python my_wrapper.py` runs `ca.check_model` on it and says what, if anything, is wrong.
+3. **Use it.** Put your wrapper where the example has `model`.
+
+## Choose what to explain, and how
+
+- **Parts:** mark them with `ca.Unit`, as above, or cut a text automatically: `ca.split(text, "sentence", id="s")` (or `"word"`, `"line"`, `"paragraph"`).
+- **Answer:** `ca.LogProb()` explains one answer. `ca.Contrast()` explains what moves the model from the answers you want to the ones you don't. `ca.Sampled(check)` works when your model can only generate text.
+- **Method:** `contextcite`, the default, takes a quick and cheap look, even at long prompts. `spex` finds parts that matter only together. `budget` sets how many copies of the prompt the model is asked about: more is steadier and costs more.
+- **Many prompts:** `contextattr run run.toml` explains a whole file of prompts and writes a report.
+
+## Learn more
+
+| Document | Covers |
+|---|---|
+| [docs/wrapper.md](https://github.com/Surya-Rayala/contextattr/blob/main/docs/wrapper.md) | connecting your model: what to write, two complete wrappers, the rules, and what to do when the check fails |
+| [docs/results.md](https://github.com/Surya-Rayala/contextattr/blob/main/docs/results.md) | reading a result: the output of every method on one example, what its scores mean, and how far to trust them |
+| [docs/methods.md](https://github.com/Surya-Rayala/contextattr/blob/main/docs/methods.md) | which method to use, how many masks to give it, and every setting with its default |
+| [docs/interface.md](https://github.com/Surya-Rayala/contextattr/blob/main/docs/interface.md) | the reference: prompts and the prompt file, answers and labels, what can be explained, costs, runs and the command line |
+
+## Licence
+
+ContextAttr is released under the MIT licence: see [LICENSE](https://github.com/Surya-Rayala/contextattr/blob/main/LICENSE).

contextattr-0.1.0/README.md

@@ -0,0 +1,95 @@
+# ContextAttr
+
+Find out which parts of a prompt make a language model give an answer.
+
+You split a prompt into parts: sentences, documents, words, or any pieces you choose. ContextAttr asks your model about many copies of the prompt with some parts removed. It then tells you how much each part, and each small group of parts working together, pushes the model towards an answer, and how far to trust that result. It works with any model, wherever it runs: you connect yours with a short wrapper.
+
+Version 0.1.0 is an early release: the interface may still change.
+
+## Install
+
+```
+pip install contextattr
+```
+
+Add `[interactions]` (`pip install "contextattr[interactions]"`) for SPEX and the other methods that find parts which matter only together. With uv: `uv add contextattr`. Needs Python 3.12 or later.
+
+## Try it
+
+This runs anywhere in seconds: `ToyModel` stands in for a real model.
+
+```python
+import contextattr as ca
+
+prompt = ca.Prompt("rio", messages=[{"role": "user", "content": [
+    ca.Unit("d1", "Rio Carnival takes place in February or March.", sep="\n"),
+    ca.Unit("d2", "Summer in Brazil runs from December to March.", sep="\n"),
+    ca.Unit("d3", "Winter in Brazil runs from June to September.", sep="\n"),
+    "Question: What is the weather like during Rio Carnival?"]}],
+    responses=[ca.Response("bad", "It is cold, because Carnival is in winter.", label="negative"),
+               ca.Response("good", "It is hot and humid: it is summer in Brazil.", label="positive")])
+
+model = ca.ToyModel.demo()        # a stand-in: put your own model's wrapper here
+e = ca.explain(prompt, model, ca.Contrast(), method="kernelshap", budget=8)
+print(e)
+```
+
+It prints:
+
+```
+rio · KernelSHAP(paired=True) · 8 masks · R² 0.991 on 128 test masks · noise 0 · 22 requests
+  d3              +0.2500  Winter in Brazil runs from June to September.
+  d1              -0.0234  Rio Carnival takes place in February or March.
+  d2              -0.2854  Summer in Brazil runs from December to March.
+```
+
+**What the example says:**
+
+| In the code | Means |
+|---|---|
+| `ca` | the package, under the short name all the docs use |
+| `ca.Prompt("rio", messages=...)` | one prompt, named `rio`, as chat messages |
+| `ca.Unit("d1", "...", sep="\n")` | a part that may be removed, named `d1`. `sep` is text that goes with it, here the line break. Everything else, like the question, always stays |
+| `ca.Response("bad", "...", label="negative")` | an answer the model could give. `negative` marks the answer you do not want, `positive` the one you do |
+| `model` | the wrapper around your model |
+| `ca.Contrast()` | what to explain: how much more likely the model finds the unwanted answers than the wanted ones |
+| `method="kernelshap"`, `budget=8` | how the scores are worked out, and how many copies of the prompt, each with some parts removed, the model is asked about |
+| `e` | the result |
+
+**How to read the output:**
+
+- The first line names the prompt and the method and says how far to trust the result. R² close to 1 means the scores describe the model well; close to 0, do not use them.
+- Then each part with its score, highest first. A positive score pushes the model towards the unwanted answer: `d3`, the sentence about winter, is what makes this model say "cold". A negative score pushes it away: `d2` protects against it. A score near zero means the part hardly matters.
+- `e.scores` gives the scores as a dictionary, and `e.to_html("report.html")` writes a page with each part shaded by its score.
+
+[Reading a result](https://github.com/Surya-Rayala/contextattr/blob/main/docs/results.md) shows the output of every method on this example and what its scores mean.
+
+## Use it with your own model
+
+ContextAttr reaches your model through a small class that you write, a *wrapper*. [Writing a wrapper](https://github.com/Surya-Rayala/contextattr/blob/main/docs/wrapper.md) is the guide, with two complete wrappers to copy from: one for an API and one for a model you run yourself.
+
+1. **Get the file to fill in.** `contextattr template my_wrapper.py` writes it. It needs one or both of:
+   - `generate`: writes replies to a prompt. Every model can do this, including the OpenAI, Gemini and Anthropic APIs.
+   - `score`: gives the log-probability of each token of a given answer. Possible when you run the model yourself, in your own code or on a vLLM or SGLang server.
+2. **Check it.** `python my_wrapper.py` runs `ca.check_model` on it and says what, if anything, is wrong.
+3. **Use it.** Put your wrapper where the example has `model`.
+
+## Choose what to explain, and how
+
+- **Parts:** mark them with `ca.Unit`, as above, or cut a text automatically: `ca.split(text, "sentence", id="s")` (or `"word"`, `"line"`, `"paragraph"`).
+- **Answer:** `ca.LogProb()` explains one answer. `ca.Contrast()` explains what moves the model from the answers you want to the ones you don't. `ca.Sampled(check)` works when your model can only generate text.
+- **Method:** `contextcite`, the default, takes a quick and cheap look, even at long prompts. `spex` finds parts that matter only together. `budget` sets how many copies of the prompt the model is asked about: more is steadier and costs more.
+- **Many prompts:** `contextattr run run.toml` explains a whole file of prompts and writes a report.
+
+## Learn more
+
+| Document | Covers |
+|---|---|
+| [docs/wrapper.md](https://github.com/Surya-Rayala/contextattr/blob/main/docs/wrapper.md) | connecting your model: what to write, two complete wrappers, the rules, and what to do when the check fails |
+| [docs/results.md](https://github.com/Surya-Rayala/contextattr/blob/main/docs/results.md) | reading a result: the output of every method on one example, what its scores mean, and how far to trust them |
+| [docs/methods.md](https://github.com/Surya-Rayala/contextattr/blob/main/docs/methods.md) | which method to use, how many masks to give it, and every setting with its default |
+| [docs/interface.md](https://github.com/Surya-Rayala/contextattr/blob/main/docs/interface.md) | the reference: prompts and the prompt file, answers and labels, what can be explained, costs, runs and the command line |
+
+## Licence
+
+ContextAttr is released under the MIT licence: see [LICENSE](https://github.com/Surya-Rayala/contextattr/blob/main/LICENSE).

contextattr-0.1.0/examples/README.md

@@ -0,0 +1,8 @@
+# examples/
+
+| File | Shows |
+|---|---|
+| `quickstart.py` | the Rio prompt explained through `ToyModel.demo()`: `check_model`, `explain` with `Contrast`, the removal check and an intervention; runs anywhere in seconds (`python examples/quickstart.py report.html`) |
+| `rio.toml`, `rio.jsonl` | the command line on two prompts: `python -m contextattr plan examples/rio.toml`, then `run`, then `report examples/runs/rio` |
+
+`contextattr template my_wrapper.py` writes a wrapper to fill in around your own model or service; running it runs `check_model` on it. The guide, with two complete wrappers to copy from, is [docs/wrapper.md](../docs/wrapper.md).

contextattr-0.1.0/examples/quickstart.py

@@ -0,0 +1,36 @@
+"""A first try, on any machine in seconds: the interface's Rio prompt explained through ToyModel.demo(), a stand-in
+model whose answers are known. Swap in your own wrapper to explain a real model (`contextattr template my_wrapper.py`
+writes one to fill in).
+
+    python examples/quickstart.py [report.html]
+"""
+
+import sys
+
+import contextattr as ca
+
+prompt = ca.Prompt("rio-01", messages=[
+    {"role": "system", "content": "Answer in one sentence."},
+    {"role": "user", "content": [
+        "Documents:\n",
+        ca.Unit("d1", "Rio Carnival takes place before Lent, in February or March.", sep="\n", tag="doc"),
+        ca.Unit("d2", "Summer in Brazil runs from December to March.", sep="\n", tag="doc"),
+        ca.Unit("d3", "Winter in Brazil runs from June to September.", sep="\n", tag="doc"),
+        "Question: What is the weather like during Rio Carnival?"]}],
+    responses=[ca.Response("bad-1", "It is cold, because Carnival is in winter.", label="negative"),
+               ca.Response("good-1", "It is hot and humid: it is summer in Brazil.", label="positive")])
+
+model = ca.ToyModel.demo()
+print(ca.check_model(model), "\n")
+
+# What moves the model from the good answer to the bad one? Three units have only 8 masks: exact Shapley values.
+e = ca.explain(prompt, model, ca.Contrast(), method="kernelshap", budget=8, removal=(1,))
+print(e, "\n")
+
+# The behaviour itself: how often the model says "cold", sampled afresh, with d3 and without it.
+cold = ca.checks.regex(r"\bcold\b")
+print("removing", e.top(1)[0][0], "→", ca.intervene(prompt, model, cold, [u for u, _ in e.top(1)], samples=200))
+
+if len(sys.argv) > 1:
+    e.to_html(sys.argv[1])
+    print("report:", sys.argv[1])

contextattr-0.1.0/examples/rio.jsonl

@@ -0,0 +1,2 @@
+{"id": "rio-01", "messages": [{"role": "system", "content": "Answer in one sentence."}, {"role": "user", "content": ["Documents:\n", {"unit": "d1", "text": "Rio Carnival takes place before Lent, in February or March.", "sep": "\n", "tag": "doc"}, {"unit": "d2", "text": "Summer in Brazil runs from December to March.", "sep": "\n", "tag": "doc"}, {"unit": "d3", "text": "Winter in Brazil runs from June to September.", "sep": "\n", "tag": "doc"}, "Question: What is the weather like during Rio Carnival?"]}], "reference": "Hot and humid: it is summer in Brazil.", "responses": [{"id": "bad-1", "text": "It is cold, because Carnival is in winter.", "label": "negative"}, {"id": "good-1", "text": "It is hot and humid: it is summer in Brazil.", "label": "positive"}]}
+{"id": "rio-02", "messages": [{"role": "user", "content": [{"unit": "rule", "text": "Answer in one word.", "sep": "\n", "tag": "instruction"}, {"unit": "docs", "text": "Winter in Brazil runs from June to September. Summer in Brazil runs from December to March.", "split": "sentence", "sep": "\n", "tag": "doc"}, "Is Rio warm in July?"]}], "responses": [{"id": "bad-1", "text": "Yes, it is hot in July.", "label": "negative"}, {"id": "good-1", "text": "No, it is winter then, so it is cold.", "label": "positive"}]}

contextattr-0.1.0/examples/rio.toml

@@ -0,0 +1,9 @@
+# The command line on the Rio example (examples/README.md):  python -m contextattr run examples/rio.toml
+prompts = "rio.jsonl"
+out = "runs/rio"
+[model]
+use = "contextattr:ToyModel.demo"   # your own: "my_wrappers.py:MyModel", with args = { ... }
+[run]
+method = "kernelshap"
+budget = 8
+removal = [1]

contextattr-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=77"]   # 77: the licence as an SPDX expression (PEP 639)
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "contextattr"
+version = "0.1.0"
+description = "Context attribution: which parts of a prompt make a model give an output, for a model hosted anywhere"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Surya Rayala" }]
+keywords = ["context attribution", "explainability", "interpretability", "LLM", "feature interactions",
+            "Shapley values", "SPEX"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# Tested on 3.12, 3.13 and 3.14, from a fresh install each (log, 2026-11-10); design §5 aims at 3.11, not yet tried.
+requires-python = ">=3.12"
+# Both floors are tested (log, 2026-11-10). scikit-learn 1.9 is the first whose RidgeCV fits exactly: before it, the
+# terms of a noise-free fit were off by up to 0.2 (Faith-Banzhaf's default fit, methods/interactions.py).
+dependencies = ["numpy>=1.26", "scikit-learn>=1.9"]
+
+[project.urls]
+Repository = "https://github.com/Surya-Rayala/contextattr"
+Documentation = "https://github.com/Surya-Rayala/contextattr/tree/main/docs"
+Issues = "https://github.com/Surya-Rayala/contextattr/issues"
+
+[project.scripts]
+contextattr = "contextattr.cli:main"
+
+[project.optional-dependencies]
+# The SPEX adapter reaches into shapiq's and sparse-transform's internals (methods/interactions.py), so both stay in
+# the series tested (shapiq 1.8.0, sparse-transform 0.2.1) until a newer one is checked.
+interactions = ["shapiq[sparse]>=1.8,<1.9", "sparse-transform>=0.2.1,<0.3", "lightgbm>=4"]
+test = ["pytest>=8", "hypothesis>=6.100"]
+
+[tool.setuptools]
+include-package-data = false     # the wheel holds the code only; MANIFEST.in adds the rest to the source archive
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = ["gpu: needs a GPU",
+           "shapiq: runs shapiq, slow to import; only with CA_TEST_SHAPIQ=1"]

contextattr-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

contextattr-0.1.0/src/contextattr/README.md

@@ -0,0 +1,19 @@
+# src/contextattr: the package
+
+One folder or file per role. The package reaches a model only through a wrapper its user writes ([docs/wrapper.md](../../docs/wrapper.md)) and imports no model library, which `tests/test_package.py` checks.
+
+| Role | Holds |
+|---|---|
+| [`prompt/`](prompt/README.md) | the input: prompts, units, splitting, masking, `prompts.jsonl` |
+| [`wrapper/`](wrapper/README.md) | what a user's wrapper must do, `check_model`, and `ToyModel` |
+| [`targets/`](targets/README.md) | the number read for each masked prompt: `LogProb`, `Pooled`, `Contrast`, `Choice`; `Sampled`, which needs only generate |
+| [`responses/`](responses/README.md) | checks that label a response (`regex`, `reference`, any function) and replies sampled from the model |
+| `value.py` | `Value`: masks → numbers, each distinct request asked once, in batches, cached; or a user's own function; the noise check |
+| `cache.py` | `Cache`: every answer stored once in one SQLite file (or memory), so a run resumes |
+| [`methods/`](methods/README.md) | which masks and which fit: `LeaveOneOut`, `Banzhaf`, `LIME`, `ContextCite`, `KernelSHAP`; `FaithBanzhaf`, `FaithShap`, `SPEX`, `ProxySPEX` through shapiq, and the indices of App. C |
+| `evaluate.py` | the faithfulness R² on held-out masks (SPEX eq. 7) and those masks; top-r removal (eq. 8) and Recovery@r (eq. 9); `intervene`, removing units and sampling again |
+| `result.py` | `Explanation`: the scores, R², noise and costs; `top`, `table`, `as_dict`, `from_dict`, `to_html`; Shapley, Banzhaf and Shapley-Taylor read from its surrogate |
+| `run.py` | `explain` (a prompt through a model and a target, or a function of masked prompts), `attribute` (any function of masks), and `Run` (a prompt file: `plan`, `execute` into a run directory, resumable) with `Results` (`summary` by tag) |
+| `report.py` | one self-contained HTML page: each prompt with its units shaded by score, the scores, interactions and removal |
+| `cli.py`, `__main__.py` | `contextattr plan | run | report` (also `python -m contextattr`), from a TOML file naming the wrapper by import path |
+| `__init__.py` | the public names |

contextattr-0.1.0/src/contextattr/__init__.py

@@ -0,0 +1,22 @@
+"""ContextAttr: which parts of a prompt make a model give an output (docs/interface.md, docs/methods.md)."""
+
+from .cache import Cache
+from . import responses
+from .evaluate import faithfulness, intervene
+from .methods import LIME, Banzhaf, ContextCite, KernelSHAP, LeaveOneOut
+from .prompt import Group, Message, Prompt, Response, Unit, read_prompts, split, write_prompts
+from .responses import Verdict, sample
+from .result import Explanation
+from .run import Results, Run, attribute, explain
+from .targets import Choice, Contrast, LogProb, Pooled, Sampled
+from .value import Value
+from .wrapper import ModelReport, Sampling, Scored, ToyModel, WrapperError, check_model
+
+__version__ = "0.1.0"
+
+checks = responses   # ca.checks.regex(...), ca.checks.reference(...)
+
+__all__ = ["LIME", "Banzhaf", "Cache", "Choice", "ContextCite", "Contrast", "Explanation", "Group", "KernelSHAP",
+           "LeaveOneOut", "LogProb", "Message", "ModelReport", "Pooled", "Prompt", "Response", "Results", "Run", "Sampled", "Sampling",
+           "Scored", "ToyModel", "Unit", "Value", "Verdict", "WrapperError", "attribute", "check_model", "checks",
+           "explain", "faithfulness", "intervene", "read_prompts", "responses", "sample", "split", "write_prompts"]

contextattr-0.1.0/src/contextattr/__main__.py

@@ -0,0 +1,7 @@
+"""python -m contextattr: the command line (cli.py)."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

contextattr-0.1.0/src/contextattr/cache.py

@@ -0,0 +1,64 @@
+"""The cache: every model answer stored once, under a key made from its request (docs/interface.md §7).
+
+One SQLite file per run, or memory when no path is given. A run that stops resumes from it, another method on the
+same masks reuses its answers, and nothing is asked of the model twice. The first answer stored for a key stays.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sqlite3
+from collections.abc import Iterable, Mapping
+
+_CHUNK = 500  # keys per SELECT, under SQLite's limit on query parameters
+
+
+class Cache:
+    """Answers by key. `key(request)` makes the key from a JSON-able request; answers are JSON-able values."""
+
+    def __init__(self, path: str | os.PathLike | None = None):
+        self.path = None if path is None else os.fspath(path)
+        if self.path is not None and os.path.dirname(self.path):
+            os.makedirs(os.path.dirname(self.path), exist_ok=True)
+        self._db = sqlite3.connect(":memory:" if self.path is None else self.path)
+        self._db.execute("CREATE TABLE IF NOT EXISTS answers "
+                         "(key TEXT PRIMARY KEY, kind TEXT NOT NULL, answer TEXT NOT NULL)")
+        self._db.commit()
+
+    @staticmethod
+    def key(request: Mapping) -> str:
+        """sha256 of the request as canonical JSON: the same request always gives the same key."""
+        text = json.dumps(request, sort_keys=True, ensure_ascii=False, separators=(",", ":"), allow_nan=False)
+        return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+    def get_many(self, keys: Iterable[str]) -> dict[str, object]:
+        """The stored answers among `keys`."""
+        keys = list(dict.fromkeys(keys))
+        found = {}
+        for i in range(0, len(keys), _CHUNK):
+            chunk = keys[i:i + _CHUNK]
+            rows = self._db.execute(f"SELECT key, answer FROM answers WHERE key IN ({','.join('?' * len(chunk))})",
+                                    chunk)
+            found.update((k, json.loads(a)) for k, a in rows)
+        return found
+
+    def put_many(self, kind: str, answers: Mapping[str, object]) -> None:
+        """Store answers and commit at once; a key already stored keeps its first answer."""
+        self._db.executemany("INSERT OR IGNORE INTO answers (key, kind, answer) VALUES (?, ?, ?)",
+                             [(k, kind, json.dumps(a, ensure_ascii=False, allow_nan=False))
+                              for k, a in answers.items()])
+        self._db.commit()
+
+    def __len__(self) -> int:
+        return self._db.execute("SELECT COUNT(*) FROM answers").fetchone()[0]
+
+    def close(self) -> None:
+        self._db.close()
+
+    def __enter__(self) -> Cache:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()