xains 0.0.1__tar.gz

xains-0.0.1/.gitignore

@@ -0,0 +1,47 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual envs
+.venv/
+venv/
+env/
+.env
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Type checkers
+.mypy_cache/
+.pyright/
+.pytype/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.local

xains-0.0.1/CHANGELOG.md

@@ -0,0 +1,220 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+While `0.y.z`, minor versions may contain breaking changes.
+
+## [Unreleased]
+
+### Changed (BREAKING)
+
+- `ExplanationConfig.mode` is now a required field with no default.
+  Construction without `mode=` raises `ValidationError`. Previously
+  defaulted to `"auto"`.
+- Mode vocabulary is now `"feature_importance"`, `"counterfactual"`,
+  `"feature_importance_counterfactual"`. The previous values `"auto"` and
+  `"contrastive"` are removed. `"contrastive"` is renamed and redefined
+  as `"feature_importance_counterfactual"` (a narrative weaving both factual
+  contributions and counterfactual(s)).
+- `Explainer._resolve_mode` renamed to `_validate_mode` — the method no
+  longer infers mode from the request shape; it validates the explicit
+  mode and returns it.
+- ADR 0012: explanation-mode vocabulary finalized (supersedes the mode
+  portion of ADR 0003).
+- Removed `include_confidence` and `include_caveats` fields from
+  `ExplanationConfig`. They had no consumer in the library and never
+  affected behavior. Setting them now raises `ValidationError`.
+  ADR 0013.
+- Scoring API renamed for lexical consistency (the word "score" reads
+  like a prediction/confidence score, which is not what these functions
+  produce):
+  `score_extraction` → `grade_extraction`,
+  `score_narrativity` → `grade_narrativity`,
+  `ExtractionScores` → `ExtractionGrades`,
+  `NarrativityScores` → `NarrativityGrades`.
+  The source module `xainarratives.metrics.scorer` is renamed to
+  `xainarratives.metrics.grader`; top-level re-exports
+  (`xainarratives.ExtractionGrades`, etc.) keep the same import path
+  modulo the new name. ADR 0014.
+- `OpenAICompatibleEchoProvider` API key is now optional and keyword-only.
+  It resolves from `api_key=` if passed, else from the environment variable
+  named by `api_key_env_var` (default `OPENAI_API_KEY`), raising
+  `ValueError` if neither is set. The constructor is now keyword-only past
+  `base_url`. ADR 0015.
+- Mode vocabulary renamed for semantic accuracy (the prior `"factual"`
+  collided with the counterfactual-explanation literature's meaning —
+  "factual" is the input datapoint, not an explanation style; the mode
+  actually means "explain via feature-importance contributions"):
+  `"factual"` → `"feature_importance"`,
+  `"factual_counterfactual"` → `"feature_importance_counterfactual"`.
+  `"counterfactual"` unchanged. `FactualTabularPromptTemplate` →
+  `FeatureImportanceTabularPromptTemplate`; module path
+  `xainarratives.prompts.factual_tabular` →
+  `xainarratives.prompts.feature_importance_tabular`. The CF-literature
+  use of "factual" in `Explainer._warn_if_counterfactual_does_not_flip`
+  (`factual_class` local var + warning prose) is deliberately preserved
+  as the now-unambiguous "input datapoint" sense. ADR 0016 (supersedes
+  the mode naming in ADR 0012).
+- `Explainer` now takes `generator=` (a `NarrativeGenerator`:
+  `LLMNarrativeGenerator` or a future templated generator) instead of
+  `prompt_template=` / `llm=`. `judge_llm` is required when
+  `extract_narrative=True` — the silent `self.llm` fallback is removed;
+  `explain()` raises `ValueError` otherwise.
+  `ExplanationResult.{prompt, model_name, raw_llm_response}` widened
+  to `str | None` (templated generators produce no LLM metadata).
+  ADR 0018.
+- Renamed the package from `xainarratives` to `xain`.
+  `from xainarratives import ...` becomes `from xain import ...`;
+  `pip install "xainarratives[extra]"` becomes
+  `pip install "xain[extra]"`. ADR 0021.
+- Renamed the package from `xain` to `xains` (the PyPI name `xain` was unavailable). `from xain import ...` becomes `from xains import ...`; the distribution is `xains`. ADR 0022.
+
+### Added
+
+- `xainarratives.metrics` subpackage: `sign_faithfulness`,
+  `value_faithfulness`, `rank_correlation`, `coverage`,
+  `hallucination_count`, `readability`. All pure functions; degenerate
+  inputs return `None` rather than raising.
+- `ExtractionScores` model + `score_extraction(extraction, request,
+  schema, narrative_text, k=10, perplexity_provider=None)` integration
+  function.
+- `PerplexityProvider` Protocol (`@runtime_checkable`) with two
+  concretes: `DisabledProvider` (always returns `None`; default) and
+  `APIPerplexityProvider` (wraps a caller-supplied callable).
+- `FeatureClaim.narrative_name` (required) and
+  `FeatureClaim.resolved_to: str | None` fields, capturing the LLM's
+  resolution from narrative mention to schema feature name.
+- `NarrativeExtraction.hallucinations: list[FeatureClaim]` channel for
+  unresolved narrative mentions.
+- Three new pydantic validators on `NarrativeExtraction`: rank
+  permutation over features and hallucinations together; key /
+  `resolved_to` consistency for resolved features; `resolved_to is None`
+  for every hallucination.
+- `textstat` as an optional dependency
+  (`pip install "xainarratives[textstat]"`) for the readability metric.
+- ADR 0007: resolution at extraction time.
+- Seven paper narrativity metrics from Cedro & Martens 2026
+  (arXiv:2604.18311): `csr`, `dcpr`, `ccpr`, `cecpr`, `fdr`, `ttcpr`,
+  `vcpr`. All pure `(text, provider) -> float | None`; degrade to
+  `None` on degenerate inputs.
+- `NarrativityScores` model + `score_narrativity(text, provider)`
+  orchestrator. Captures the 7 derived metrics plus 9 auxiliary
+  primitives (`ppl_ordered`, `ppl_shuffled`, `decay_constant`,
+  `dist2`, `ttr`, `vr`, `cr`, `cer`, `n_sentences`) for paper
+  replication.
+- `xainarratives.metrics._internal/` private subpackage:
+  `tokenize` (NLTK sentence/POS, regex word tokenizer), `curve_fit`
+  (scipy exponential decay fitter), `lexicons` (vendored JSON loaders
+  + greedy phrase counter), `perplexity_utils` (cumulative perplexity
+  over sentence prefixes).
+- Vendored lexicons under
+  `src/xainarratives/metrics/_internal/data/`: 142-entry connectives
+  (Das et al. 2018, ACL W18-5042) and 19-entry cause-effect markers
+  (paper Appendix A). Loaders assert expected counts at load time.
+- `narrativity` optional dependency
+  (`pip install "xainarratives[narrativity]"`) bundling
+  `nltk>=3.9,<4` and `scipy>=1.13,<2`.
+- ADR 0008: narrativity metrics — paper-faithful composition over
+  Protocol changes.
+- `HuggingFacePerplexityProvider` — local autoregressive perplexity via
+  `transformers` + `torch`. Eager-loads model + tokenizer in `__init__`,
+  auto-detects CUDA, truncates oversize inputs with one `UserWarning` per
+  provider instance. Default `model_name="gpt2"` (~500 MB cached
+  download on first use); paper replication wants
+  `meta-llama/Llama-3.1-8B`.
+- `OpenAICompatibleEchoProvider` — hits any OpenAI-compatible
+  `/v1/completions` endpoint with `echo=True, logprobs=1, max_tokens=1`
+  (Together.ai, vLLM, TGI's OpenAI shim, OpenAI's legacy completions).
+  Dual-shape response parser handles both `choices[0].logprobs` and
+  `prompt[0].logprobs`. Catches `openai.OpenAIError` and returns `None`
+  per Protocol contract.
+- `perplexity-hf` optional dependency
+  (`pip install "xainarratives[perplexity-hf]"`) bundling
+  `transformers>=4.40,<5` and `torch>=2.0,<3`.
+- `perplexity-api` optional dependency
+  (`pip install "xainarratives[perplexity-api]"`) bundling
+  `openai>=1.30,<2`.
+- ADR 0009: perplexity providers — two concretes, no shared base.
+- Executable quickstart notebook at `notebooks/01_quickstart.ipynb`:
+  end-to-end pipeline on a 30-row OpenML German Credit slice (load,
+  one-hot encode, RF + SHAP, build request, generate + extract, score
+  extraction + narrativity). Outputs committed for GitHub rendering.
+- Vendored `notebooks/data/german_credit_sample.csv` and its
+  deterministic regenerator `scripts/generate_german_credit_sample.py`
+  (seed 42; runs once before the notebook ever executes).
+- `notebook` optional dependency
+  (`pip install "xainarratives[notebook]"`) bundling `jupyter`, `shap`,
+  `scikit-learn`, `pandas`.
+- ADR 0010: ship a quickstart Jupyter notebook.
+- Configurable narrative-generation rules: `ExplanationConfig.narrative_rules`
+  (a string field, default `DEFAULT_NARRATIVE_RULES`) is injected into the
+  system prompt by `FeatureImportanceTabularPromptTemplate`. The default is the
+  four-rule operational definition of an XAI Narrative from Cedro & Martens
+  2026; users override it by passing a custom value. Applies to all
+  narrative-generating templates by convention.
+- ADR 0011: configurable narrative-generation rules.
+- `FeatureImportanceTabularPromptTemplate` now accepts `system_template`,
+  `user_template`, and `extra_placeholders` (all keyword-only, defaulted)
+  for editable prompts with `{placeholder}` substitution.
+  `DEFAULT_SYSTEM_TEMPLATE` and `DEFAULT_USER_TEMPLATE` are exported from
+  `xainarratives.prompts`. The quickstart notebook prints the rendered
+  prompt before sending. ADR 0017.
+- `TemplatedNarrativeGenerator` - LLM-free feature-importance
+  narratives. Verbalizes ranked contributions as prose with no LLM
+  call; method-agnostic by default (`method="SHAP"` reproduces
+  Cedro 2026's templated-baseline wording); editable lead/clause
+  templates; raw values from `request.features`; tabular-only. Slots
+  into `Explainer(generator=)` and flows through the same extraction
+  + grading path as LLM narratives (LLM-free generation, LLM-graded).
+  The shared `substitute()` helper now has its second user. ADR 0019.
+- OpenAI and OpenRouter narrative-generation providers:
+  `OpenAIProvider` (reads `OPENAI_API_KEY`) and `OpenRouterProvider`
+  (reads `OPENROUTER_API_KEY`, optional `HTTP-Referer`/`X-Title`
+  headers), both thin presets over a new public
+  `OpenAICompatibleProvider` base usable directly for any
+  OpenAI-compatible endpoint (Together, Groq, vLLM, ...). Eager key
+  resolution, lazy SDK import. New `openai` pip extra. All providers
+  now top-level importable: `from xainarratives import
+  AnthropicProvider, OpenAIProvider, OpenRouterProvider,
+  OpenAICompatibleProvider, ...`. ADR 0020.
+
+### Changed
+
+- `_EXTRACTION_PROMPT_VERSION` bumped from `"1"` to `"2"`. The wire
+  format adds `narrative_name` per feature claim and a separate
+  `hallucinations` array.
+- `NarrativeExtraction.features` is now keyed by **schema feature
+  name** rather than the narrative's name for the feature. Resolution
+  happens at extraction time, not at scoring time.
+- `extract_narrative_claims` now rejects `features` keys not in the
+  schema's resolution vocabulary as a parse failure (advisory
+  `GuardrailResult`, no exception).
+- `grade_extraction` swallows `ImportError` from `readability` so a
+  missing `textstat` install degrades to `readability=None` rather than
+  cascading to the whole scorer. `readability()` itself keeps the
+  strict `ImportError` contract for direct callers.
+- ADR 0006 status updated to "superseded in part by 0007".
+
+### Removed
+
+- Support for prompt-version `"1"` extractions. Hard cutover; pre-1.0
+  project, no external users, no compatibility shim.
+- `APIPerplexityProvider` (abstract callable-wrapper placeholder). Zero
+  callers in the codebase, failed the CLAUDE.md "abstractions need ≥2
+  implementations" rule. Replaced by `HuggingFacePerplexityProvider` and
+  `OpenAICompatibleEchoProvider`.
+
+## [0.0.1] - 2026-04-23
+
+### Added
+
+- Initial skeleton: pydantic schema / types / config for all four modalities
+  (tabular, text, image, graph).
+- `LLMProvider` Protocol + `MockLLMProvider`.
+- `PromptTemplate` ABC + `EchoPromptTemplate`.
+- `Explainer` orchestrator with sync `explain()`.
+- ADRs 0001–0004 recording scope, API style, data-model, and counterfactual-payload
+  decisions.

xains-0.0.1/LICENSE

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

xains-0.0.1/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: xains
+Version: 0.0.1
+Summary: Natural-language verbalization of ML model predictions from pre-computed attributions.
+Project-URL: Repository, https://github.com/ADMAntwerp/xains
+Project-URL: Issues, https://github.com/ADMAntwerp/xains/issues
+Author-email: Mateusz Cedro <mateusz.cedro@uantwerpen.be>, David Martens <david.martens@uantwerpen.be>
+License: MIT
+License-File: LICENSE
+Keywords: explainability,llm,nlg,shap,xai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.6
+Provides-Extra: anthropic
+Requires-Dist: anthropic<1.0,>=0.96; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: anthropic<1.0,>=0.96; extra == 'dev'
+Requires-Dist: jupyter<2,>=1.1; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: nltk<4,>=3.9; extra == 'dev'
+Requires-Dist: openai<2,>=1.30; extra == 'dev'
+Requires-Dist: pandas<3,>=2.2; extra == 'dev'
+Requires-Dist: pre-commit>=3.6; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest-recording<0.14,>=0.13; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Requires-Dist: scikit-learn<2,>=1.5; extra == 'dev'
+Requires-Dist: scipy<2,>=1.13; extra == 'dev'
+Requires-Dist: shap<1,>=0.46; extra == 'dev'
+Requires-Dist: textstat<1,>=0.7; extra == 'dev'
+Requires-Dist: torch<3,>=2.0; extra == 'dev'
+Requires-Dist: transformers<5,>=4.40; extra == 'dev'
+Requires-Dist: vcrpy<9,>=8.1; extra == 'dev'
+Provides-Extra: narrativity
+Requires-Dist: nltk<4,>=3.9; extra == 'narrativity'
+Requires-Dist: scipy<2,>=1.13; extra == 'narrativity'
+Provides-Extra: notebook
+Requires-Dist: jupyter<2,>=1.1; extra == 'notebook'
+Requires-Dist: pandas<3,>=2.2; extra == 'notebook'
+Requires-Dist: scikit-learn<2,>=1.5; extra == 'notebook'
+Requires-Dist: shap<1,>=0.46; extra == 'notebook'
+Provides-Extra: openai
+Requires-Dist: openai<2,>=1.30; extra == 'openai'
+Provides-Extra: perplexity-api
+Requires-Dist: openai<2,>=1.30; extra == 'perplexity-api'
+Provides-Extra: perplexity-hf
+Requires-Dist: torch<3,>=2.0; extra == 'perplexity-hf'
+Requires-Dist: transformers<5,>=4.40; extra == 'perplexity-hf'
+Provides-Extra: textstat
+Requires-Dist: textstat<1,>=0.7; extra == 'textstat'
+Description-Content-Type: text/markdown
+
+# xains
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org)
+
+<!-- TODO (add as each service comes online for ADMAntwerp/xains):
+[![PyPI version](https://img.shields.io/pypi/v/xains.svg)](https://pypi.org/project/xains/)
+[![Tests](https://github.com/ADMAntwerp/xains/actions/workflows/ci.yml/badge.svg)](https://github.com/ADMAntwerp/xains/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/ADMAntwerp/xains/branch/master/graph/badge.svg)](https://codecov.io/gh/ADMAntwerp/xains)
+[![Read the Docs](https://readthedocs.org/projects/xains/badge/?version=latest)](https://xains.readthedocs.io/en/latest/)
+-->
+
+xains generates explainable AI (XAI) narratives - hence the name. It turns technical XAI outputs such as SHAP attributions and counterfactuals into clear natural-language explanations that make model decisions understandable to a broad audience.
+
+> **Scope.** This library generates natural-language XAI narratives from technical outputs like SHAP attributions or counterfactual explanations, making the explanations more transparent and understandable.
+
+## Install
+
+```bash
+git clone https://github.com/ADMAntwerp/xains.git
+cd xains
+pip install -e .
+```
+
+## Minimal example
+
+```python
+import xains
+import xains.prompts
+
+schema = xains.DatasetSchema(
+    modality=xains.Modality.TABULAR,
+    name="credit_risk",
+    description="Predicts 24-month default on personal loans.",
+    target=xains.TargetSchema(
+        name="default",
+        description="Whether the applicant defaulted.",
+        classes={0: "Repaid", 1: "Defaulted"},
+    ),
+    features=[
+        xains.FeatureSchema(name="age", dtype="numeric", unit="years",
+                           description="Applicant age at application."),
+        xains.FeatureSchema(name="salary", dtype="numeric", unit="EUR",
+                           description="Annual gross salary."),
+        xains.FeatureSchema(name="debt_to_income", dtype="numeric",
+                           description="Debt-to-income ratio."),
+    ],
+)
+
+request = xains.TabularExplanationRequest(
+    features={"age": 29, "salary": 52000, "debt_to_income": 0.41},
+    prediction=xains.Prediction(predicted_class=1, probabilities={0: 0.2, 1: 0.8}),
+    contributions=[
+        xains.TabularContribution(name="debt_to_income", value=0.41, importance=0.37),
+        xains.TabularContribution(name="salary", value=52000, importance=-0.21),
+        xains.TabularContribution(name="age", value=29, importance=-0.12),
+    ],
+)
+
+llm = xains.AnthropicProvider(model="claude-haiku-4-5", max_tokens=512)
+explainer = xains.Explainer(
+    schema=schema,
+    generator=xains.LLMNarrativeGenerator(
+        prompt_template=xains.prompts.FeatureImportanceTabularPromptTemplate(),
+        llm=llm,
+    ),
+    config=xains.ExplanationConfig(
+        mode="feature_importance", audience="end_user",
+        max_length_words=40, extract_narrative=True,
+    ),
+    judge_llm=llm,  # required when extract_narrative=True
+)
+
+result = explainer.explain(request)
+print(result.text)
+```
+
+Output is illustrative; LLM responses vary run-to-run:
+
+```text
+Your profile indicates elevated default risk. A debt-to-income ratio of 0.41
+substantially increases this concern, signaling that your debt obligations
+consume a meaningful portion of earnings. Although your salary of EUR 52,000
+and relatively young age of 29 provide some protective factors that work
+against default, they ultimately prove insufficient to offset the debt burden
+weighing on your financial stability.
+```
+
+### Scoring the narrative
+
+A narrative is only useful if it is faithful to the attributions and reads well. xains scores both. `grade_extraction` checks the claims the narrative makes against the input attributions - sign, value, and rank fidelity, coverage, hallucination count, and readability (perplexity is added when a perplexity provider is supplied):
+
+```python
+grades = xains.grade_extraction(
+    extraction=result.narrative_extraction,
+    request=request,
+    schema=schema,
+    narrative_text=result.text,
+    k=5,
+)
+print(grades)
+```
+
+```text
+sign_faithfulness=1.0 value_faithfulness=1.0 rank_correlation=1.0 coverage=1.0
+hallucination_count=0 readability=30.09 perplexity=None prompt_version='2'
+```
+
+`grade_narrativity` scores how well the text reads as a narrative, using the metrics from Cedro & Martens 2026. It needs a perplexity provider (any OpenAI-compatible endpoint that returns logprobs):
+
+```python
+from xains.metrics import OpenAICompatibleEchoProvider
+
+ppl = OpenAICompatibleEchoProvider(
+    base_url="https://api.together.xyz/v1",
+    model="meta-llama/Meta-Llama-3-8B-Instruct-Lite",
+    api_key_env_var="TOGETHER_API_KEY",
+)
+narrativity = xains.grade_narrativity(result.text, ppl)
+print(narrativity.fdr, narrativity.csr)
+```
+
+```text
+0.29 0.11
+```
+
+The two values are Fluency-Diversity Rate (FDR) and Continuous Structure Rate (CSR), both higher-is-better - two of the seven Cedro & Martens 2026 narrativity metrics; the notebook computes all seven plus auxiliary primitives.
+
+### End-to-end notebook
+
+For the full pipeline (load German Credit, train a RandomForest, compute SHAP, generate the narrative, extract structured claims, and score on faithfulness and narrativity), see the tutorial in [`notebooks/01_quickstart.ipynb`](notebooks/01_quickstart.ipynb).
+
+See `docs/design.md` for the full design and `docs/decisions/` for recorded architecture decisions.
+
+## Choosing a model
+
+Any `LLMProvider` drops into `xains.LLMNarrativeGenerator(llm=...)` - pick the provider for the model you want:
+
+```python
+import xains
+
+# Anthropic (reads ANTHROPIC_API_KEY)
+llm = xains.AnthropicProvider(model="claude-haiku-4-5", max_tokens=512)
+
+# OpenAI (reads OPENAI_API_KEY)
+llm = xains.OpenAIProvider(model="gpt-4o-mini", max_tokens=512)
+
+# OpenRouter - Llama, and many others (reads OPENROUTER_API_KEY)
+llm = xains.OpenRouterProvider(model="meta-llama/llama-3.3-70b-instruct", max_tokens=512)
+
+# Any OpenAI-compatible endpoint (Together, Groq, vLLM, ...) - set base_url + the env var to read
+llm = xains.OpenAICompatibleProvider(
+    base_url="https://api.together.xyz/v1",
+    api_key_env_var="TOGETHER_API_KEY",
+    model="meta-llama/Llama-3.3-70B-Instruct-Turbo",
+    max_tokens=512,
+)
+```
+
+Each reads its API key from the named env var (or pass `api_key=` explicitly); drop any of them into `xains.LLMNarrativeGenerator(llm=...)` exactly as the Minimal example does.
+
+## License
+
+MIT - see [`LICENSE`](LICENSE).

xains-0.0.1/README.md

@@ -0,0 +1,164 @@
+# xains
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org)
+
+<!-- TODO (add as each service comes online for ADMAntwerp/xains):
+[![PyPI version](https://img.shields.io/pypi/v/xains.svg)](https://pypi.org/project/xains/)
+[![Tests](https://github.com/ADMAntwerp/xains/actions/workflows/ci.yml/badge.svg)](https://github.com/ADMAntwerp/xains/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/ADMAntwerp/xains/branch/master/graph/badge.svg)](https://codecov.io/gh/ADMAntwerp/xains)
+[![Read the Docs](https://readthedocs.org/projects/xains/badge/?version=latest)](https://xains.readthedocs.io/en/latest/)
+-->
+
+xains generates explainable AI (XAI) narratives - hence the name. It turns technical XAI outputs such as SHAP attributions and counterfactuals into clear natural-language explanations that make model decisions understandable to a broad audience.
+
+> **Scope.** This library generates natural-language XAI narratives from technical outputs like SHAP attributions or counterfactual explanations, making the explanations more transparent and understandable.
+
+## Install
+
+```bash
+git clone https://github.com/ADMAntwerp/xains.git
+cd xains
+pip install -e .
+```
+
+## Minimal example
+
+```python
+import xains
+import xains.prompts
+
+schema = xains.DatasetSchema(
+    modality=xains.Modality.TABULAR,
+    name="credit_risk",
+    description="Predicts 24-month default on personal loans.",
+    target=xains.TargetSchema(
+        name="default",
+        description="Whether the applicant defaulted.",
+        classes={0: "Repaid", 1: "Defaulted"},
+    ),
+    features=[
+        xains.FeatureSchema(name="age", dtype="numeric", unit="years",
+                           description="Applicant age at application."),
+        xains.FeatureSchema(name="salary", dtype="numeric", unit="EUR",
+                           description="Annual gross salary."),
+        xains.FeatureSchema(name="debt_to_income", dtype="numeric",
+                           description="Debt-to-income ratio."),
+    ],
+)
+
+request = xains.TabularExplanationRequest(
+    features={"age": 29, "salary": 52000, "debt_to_income": 0.41},
+    prediction=xains.Prediction(predicted_class=1, probabilities={0: 0.2, 1: 0.8}),
+    contributions=[
+        xains.TabularContribution(name="debt_to_income", value=0.41, importance=0.37),
+        xains.TabularContribution(name="salary", value=52000, importance=-0.21),
+        xains.TabularContribution(name="age", value=29, importance=-0.12),
+    ],
+)
+
+llm = xains.AnthropicProvider(model="claude-haiku-4-5", max_tokens=512)
+explainer = xains.Explainer(
+    schema=schema,
+    generator=xains.LLMNarrativeGenerator(
+        prompt_template=xains.prompts.FeatureImportanceTabularPromptTemplate(),
+        llm=llm,
+    ),
+    config=xains.ExplanationConfig(
+        mode="feature_importance", audience="end_user",
+        max_length_words=40, extract_narrative=True,
+    ),
+    judge_llm=llm,  # required when extract_narrative=True
+)
+
+result = explainer.explain(request)
+print(result.text)
+```
+
+Output is illustrative; LLM responses vary run-to-run:
+
+```text
+Your profile indicates elevated default risk. A debt-to-income ratio of 0.41
+substantially increases this concern, signaling that your debt obligations
+consume a meaningful portion of earnings. Although your salary of EUR 52,000
+and relatively young age of 29 provide some protective factors that work
+against default, they ultimately prove insufficient to offset the debt burden
+weighing on your financial stability.
+```
+
+### Scoring the narrative
+
+A narrative is only useful if it is faithful to the attributions and reads well. xains scores both. `grade_extraction` checks the claims the narrative makes against the input attributions - sign, value, and rank fidelity, coverage, hallucination count, and readability (perplexity is added when a perplexity provider is supplied):
+
+```python
+grades = xains.grade_extraction(
+    extraction=result.narrative_extraction,
+    request=request,
+    schema=schema,
+    narrative_text=result.text,
+    k=5,
+)
+print(grades)
+```
+
+```text
+sign_faithfulness=1.0 value_faithfulness=1.0 rank_correlation=1.0 coverage=1.0
+hallucination_count=0 readability=30.09 perplexity=None prompt_version='2'
+```
+
+`grade_narrativity` scores how well the text reads as a narrative, using the metrics from Cedro & Martens 2026. It needs a perplexity provider (any OpenAI-compatible endpoint that returns logprobs):
+
+```python
+from xains.metrics import OpenAICompatibleEchoProvider
+
+ppl = OpenAICompatibleEchoProvider(
+    base_url="https://api.together.xyz/v1",
+    model="meta-llama/Meta-Llama-3-8B-Instruct-Lite",
+    api_key_env_var="TOGETHER_API_KEY",
+)
+narrativity = xains.grade_narrativity(result.text, ppl)
+print(narrativity.fdr, narrativity.csr)
+```
+
+```text
+0.29 0.11
+```
+
+The two values are Fluency-Diversity Rate (FDR) and Continuous Structure Rate (CSR), both higher-is-better - two of the seven Cedro & Martens 2026 narrativity metrics; the notebook computes all seven plus auxiliary primitives.
+
+### End-to-end notebook
+
+For the full pipeline (load German Credit, train a RandomForest, compute SHAP, generate the narrative, extract structured claims, and score on faithfulness and narrativity), see the tutorial in [`notebooks/01_quickstart.ipynb`](notebooks/01_quickstart.ipynb).
+
+See `docs/design.md` for the full design and `docs/decisions/` for recorded architecture decisions.
+
+## Choosing a model
+
+Any `LLMProvider` drops into `xains.LLMNarrativeGenerator(llm=...)` - pick the provider for the model you want:
+
+```python
+import xains
+
+# Anthropic (reads ANTHROPIC_API_KEY)
+llm = xains.AnthropicProvider(model="claude-haiku-4-5", max_tokens=512)
+
+# OpenAI (reads OPENAI_API_KEY)
+llm = xains.OpenAIProvider(model="gpt-4o-mini", max_tokens=512)
+
+# OpenRouter - Llama, and many others (reads OPENROUTER_API_KEY)
+llm = xains.OpenRouterProvider(model="meta-llama/llama-3.3-70b-instruct", max_tokens=512)
+
+# Any OpenAI-compatible endpoint (Together, Groq, vLLM, ...) - set base_url + the env var to read
+llm = xains.OpenAICompatibleProvider(
+    base_url="https://api.together.xyz/v1",
+    api_key_env_var="TOGETHER_API_KEY",
+    model="meta-llama/Llama-3.3-70B-Instruct-Turbo",
+    max_tokens=512,
+)
+```
+
+Each reads its API key from the named env var (or pass `api_key=` explicitly); drop any of them into `xains.LLMNarrativeGenerator(llm=...)` exactly as the Minimal example does.
+
+## License
+
+MIT - see [`LICENSE`](LICENSE).