Explainability API¶

Geodesia G-1 provides two explainability interfaces: the inline explain flag on the evaluate endpoint (for LLM-internal attribution), and the causal explainability endpoint on the gateway (for black-box attribution). This page documents both.

Inline Explain (Evaluate Endpoint)¶

When you call POST /glad/evaluate with explain: true, attribution scores are computed alongside the regular detection scores and returned in the xai field of the response.

Parameters¶

Credit Tiers¶

The credit_tiers array specifies which attribution methods to run. Methods can be combined:

Example — run MuPAX and gradient together:

{
  "model_path": "/app/pretrained_glad",
  "prompt": "When was the Eiffel Tower built?",
  "explain": true,
  "credit_tiers": ["mupax", "gradient"]
}

explain_mode: "causal"¶

In causal mode, the system additionally computes a token→token causal matrix: for the answer token with the highest attribution score, it identifies which prompt tokens are causally responsible for its generation.

This answers: "Not just what words were important — but specifically which prompt words caused the model to write the most suspicious part of the answer."

XAI Response Structure¶

"xai": {
  "mupax_halluc": {
    "detection_type": "hallucination",
    "top_tokens": [
      {
        "token": "Paris",
        "position": 7,
        "importance": 0.48,
        "retention_frequency": 0.71,
        "conditional_goodness": 0.88
      }
    ],
    "threshold_W": 0.14,
    "threshold_percentile_used": 0.2,
    "n_accepted": 412,
    "n_total": 500,
    "attribution_heatmap": [0.02, 0.01, 0.48, 0.12, ...],
    "score_function": "combined_logreg"
  },
  "mupax_safety": {
    "detection_type": "safety",
    ...
  },
  "mupax_halluc_causal": {
    "detection_type": "hallucination_causal",
    "target_token": "1889",
    "target_position": 14,
    "prompt_tokens": [...],
    "answer_tokens": [...],
    "causal_edges": [
      {
        "source_position": 4,
        "source_token": "built",
        "target_position": 14,
        "target_token": "1889",
        "raw_importance": 0.61,
        "normalized_importance": 0.83,
        "absolute_importance": 0.83
      }
    ]
  }
}

Per-Token Attribution Fields¶

Causal Edge Fields¶

Causal XAI via Gateway¶

For the companion gateway deployment (where Geodesia runs against an external LLM without access to model internals), black-box attribution is available at:

See Causal XAI for full documentation.

PSS: Positional Semantic Stability¶

Positional Semantic Stability (PSS, Tier 1.5) is a training-free attribution method that asks: "If I change the prompt in this position, does the key claim in the answer change?"

Unlike gradient-based methods, PSS does not need access to model gradients. It works by generating N alternative answers with small prompt variations and measuring stability.

PSS Configuration Parameters¶

When to use PSS¶

• You are explaining hallucination in long-form answers where gradient methods are noisy
• You need attribution that works without any model weights (fully black-box)
• You are building a human review workflow and need the explanation to be relatable ("this claim changed when we removed that specific context sentence")