docs: document Bayesian-FPDE lambda posterior selection

api-reference.mdx

@@ -1,6 +1,6 @@
 ---
 title: "API reference"
-description: "Public FPDE classes, functions, parameters, and result objects"
+description: "Reference for FPDE public classes, engine methods, prototype helpers, perturbation curves, result objects, and common error messages."
 ---
 
 Import the public package as `fpde`.
@@ -13,7 +13,7 @@ This page documents the public API exported by `fpde` and `fpde.core`.
 
 ## `FPDEEngine`
 
-Use `FPDEEngine` for repeated explanations, batch explanations, Hyb-FPDE, grid search, and validation-based lambda selection.
+Use `FPDEEngine` for repeated explanations, batch explanations, Hyb-FPDE, grid search, validation-based lambda selection, and Bayesian-FPDE lambda posterior selection.
 
 ### `FPDEEngine.fit`
 
@@ -127,6 +127,71 @@ engine.select_lambda(
 Selects `lambda_hyb` by held-out deletion and insertion validation.
 Returns a `HybFPDEValidationSelectionResult`.
 
+### `engine.select_bayesian_lambda`
+
+```python
+engine.select_bayesian_lambda(
+    X_val,
+    *,
+    lambda_hyb_grid=...,
+    fractions=(0.0, 0.05, 0.1, 0.2, 0.3, 0.5, 0.7, 1.0),
+    normalize="l1",
+    anchor_strategy="mean",
+    eps=1e-12,
+    max_working_bytes=268435456,
+    alpha=1.0,
+    beta=1.0,
+    temperature=1.0,
+    credible_mass=0.95,
+    model=None,
+)
+```
+
+Builds a Bayesian posterior over unique `lambda_hyb` candidates using the same held-out deletion and insertion validation score as `select_lambda`.
+
+| Parameter | Description |
+| --- | --- |
+| `alpha` | Positive alpha parameter for the Beta prior on `lambda_hyb`. |
+| `beta` | Positive beta parameter for the Beta prior on `lambda_hyb`. |
+| `temperature` | Positive likelihood temperature. Smaller values make the posterior sharper. |
+| `credible_mass` | Credible interval mass in `(0, 1)`. |
+
+Returns a `BayesianFPDELambdaSelectionResult`.
+
+### `engine.explain_one_bayesian`
+
+```python
+engine.explain_one_bayesian(x, selection, *, model=None)
+```
+
+Explains one sample using `selection.posterior_mean_lambda`, where `selection` is a `BayesianFPDELambdaSelectionResult`.
+Returns `(attributions, details)`.
+
+The `details` dictionary includes the usual fixed-lambda fields plus `lambda_source`, `posterior_mean_lambda`, `map_lambda`, `credible_interval`, `posterior_entropy`, and `effective_candidates`.
+
+### `engine.explain_batch_bayesian`
+
+```python
+engine.explain_batch_bayesian(
+    X,
+    selection,
+    *,
+    include_details=True,
+    model=None,
+)
+```
+
+Explains many samples with the Bayesian posterior-mean `lambda_hyb`.
+Returns `(attribution_matrix, details)`.
+
+### `engine.explain_matrix_bayesian`
+
+```python
+engine.explain_matrix_bayesian(X, selection, *, model=None)
+```
+
+Returns only the Bayesian-FPDE attribution matrix for a batch.
+
 ## Prototype helpers
 
 ### `class_mean_prototypes`
@@ -276,6 +341,7 @@ Features are ranked by signed positive attribution in descending order.
 | `FPDEContext` | Prototypes, prototype labels, mean anchor, zero anchor, baseline, and feature count. |
 | `HybFPDEGridSearchResult` | `best_config`, `best_score`, `rows`, `objective`, `n_candidates`, and `n_eval_samples`. |
 | `HybFPDEValidationSelectionResult` | `best_lambda`, `best_config`, `rows`, and `n_eval_samples`. |
+| `BayesianFPDELambdaSelectionResult` | `posterior_mean_lambda`, `map_lambda`, `credible_interval`, `posterior_rows`, `prior_alpha`, `prior_beta`, `temperature`, `normalize`, `anchor_strategy`, `eps`, and `n_eval_samples`. Call `sorted_rows()` to inspect candidates from highest to lowest posterior probability. |
 
 ## Common errors
 

examples.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Examples"
-description: "Common FPDE usage patterns for single samples, batches, and lambda selection"
+description: "FPDE usage examples for single-sample explanations, batch explanations, lambda selection, Bayesian-FPDE posteriors, and grid search."
 ---
 
 Use `FPDEEngine` for most workflows.
@@ -61,6 +61,39 @@ attributions, details = engine.explain_batch(X_test, lambda_hyb=best_lambda)
 
 Save `selection.rows` with your experiment results so you can inspect the score for each candidate later.
 
+## Build a Bayesian-FPDE posterior over `lambda_hyb`
+
+Use `select_bayesian_lambda` when you want a posterior over the Hyb-FPDE mixture weight instead of a single selected value.
+The posterior is built on the same held-out deletion and insertion score as `select_lambda`, with a `Beta(alpha, beta)` prior and a likelihood temperature.
+
+```python
+selection = engine.select_bayesian_lambda(
+    X_val,
+    lambda_hyb_grid=(0.0, 0.25, 0.5, 0.75, 1.0),
+    alpha=1.0,
+    beta=1.0,
+    temperature=1.0,
+    credible_mass=0.95,
+)
+
+print(selection.posterior_mean_lambda)
+print(selection.map_lambda)
+print(selection.credible_interval)
+```
+
+Then explain samples with the posterior-mean `lambda_hyb`:
+
+```python
+attributions, details = engine.explain_one_bayesian(X_test[0], selection)
+
+print(details["posterior_mean_lambda"])
+print(details["credible_interval"])
+print(details["posterior_entropy"])
+```
+
+Use `explain_batch_bayesian` or `explain_matrix_bayesian` for many samples.
+Inspect `selection.sorted_rows()` to see candidates from highest to lowest posterior mass.
+
 ## Run grid search
 
 Use `grid_search` to compare Diff-FPDE, Cos-FPDE, and Hyb-FPDE candidate settings.

index.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Introduction"
-description: "Explain classification results with prototype-contrast feature attribution"
+description: "FPDE is a Python package that explains classifier predictions with prototype-contrast feature attribution for tabular feature vectors."
 ---
 
 Feature Prototype Direction Explainer (FPDE) is a Python package for prototype-contrast feature attribution.
@@ -16,6 +16,7 @@ Use FPDE when you need a lightweight, post-hoc explanation method for tabular-st
 - Explain batches while reusing fitted prototype state.
 - Search Diff, Cos, and Hyb-FPDE candidate settings.
 - Select `lambda_hyb` with held-out deletion and insertion validation.
+- Build a Bayesian-FPDE posterior over `lambda_hyb` candidates and explain with the posterior mean.
 - Compute deletion and insertion perturbation curves for an attribution vector.
 
 ## How FPDE explains a prediction

method-overview.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Method overview"
-description: "Understand prototypes, target-rival contrasts, and FPDE variants"
+description: "Learn how FPDE builds class prototypes, picks target and rival contrasts, and decomposes them with Diff-FPDE, Cos-FPDE, and Hyb-FPDE."
 ---
 
 FPDE is a post-hoc feature attribution method for classification.
@@ -107,6 +107,35 @@ phi_hyb_j = lambda_hyb * phi_diff_j + (1 - lambda_hyb) * phi_cos_j
 By default, Hyb-FPDE uses L1-normalized component attribution vectors before mixing.
 Set `normalize="none"` when you want to mix the raw component scales.
 
+## Bayesian-FPDE
+
+Bayesian-FPDE replaces a single selected `lambda_hyb` with a posterior distribution over the lambda grid.
+Use it when you want to express uncertainty about the Hyb-FPDE mixture weight, or when you want a Bayesian model-averaged attribution instead of a point-selected one.
+
+`FPDEEngine.select_bayesian_lambda` evaluates the same held-out deletion and insertion validation score as `select_lambda`, then converts the finite lambda grid into a posterior.
+The default prior is `Beta(1, 1)`, which is uniform over the candidates.
+
+For each candidate, the unnormalized log-posterior is:
+
+```text
+log_likelihood = n_eval_samples * validation_score / temperature
+log_prior      = (alpha - 1) * log(lambda_hyb)
+               + (beta - 1) * log(1 - lambda_hyb)
+```
+
+Tune `alpha` and `beta` to encode prior preferences over `lambda_hyb`.
+Smaller `temperature` values make the posterior sharper around high-scoring candidates; larger values flatten it toward the prior.
+
+The normalized posterior weights produce:
+
+- `posterior_mean_lambda`: the Bayesian model-averaged mixture weight.
+- `map_lambda`: the highest-posterior lambda candidate.
+- `credible_interval`: an equal-tail credible interval on the grid for the chosen `credible_mass`.
+- `posterior_rows`: candidate rows with validation metrics and posterior mass.
+
+`engine.explain_one_bayesian`, `engine.explain_batch_bayesian`, and `engine.explain_matrix_bayesian` use `posterior_mean_lambda`.
+Because Hyb-FPDE is linear in `lambda_hyb`, this is equivalent to the expected attribution vector under the lambda posterior.
+
 ## Interpreting results
 
 An FPDE explanation contains: