Explainability & Decision Transparency

The Explainability Layer ensures that every decision Layerr makes can be understood, audited, and trusted. It produces structured rationales for why a specific model was chosen, why a fallback occurred, and how the strategy influenced the outcome.

Why Explainability Matters

• Trust: Users need to know why their request went to Claude instead of GPT-4o
• Debugging: Developers can trace routing failures back to root causes
• Optimization: Workspace admins can understand how strategy changes affect routing
• Compliance: Enterprises need audit trails for AI governance

Explainable Decisions

Decision Type	Explanation Format	Key Function
Routing Explanation	Why this provider/model was chosen	buildRoutingExplanation()
Scoring Breakdown	Per-dimension scores with weights	buildScoringExplanation()
Adaptive Selection	How historical learning influenced the choice	buildAdaptiveSelectionExplanation()
Fallback Ordering	Why the fallback chain is ordered this way	buildFallbackOrderingExplanation()
Policy Explanation	How workspace restrictions shaped the decision	buildPolicyExplanation()
Capability Mapping	Which capabilities were matched or missing	buildCapabilityExplanation()
Provider Intelligence	Historical performance summary for the chosen provider	buildProviderIntelligenceExplanation()

Explanation Structure

Every explanation follows a structured template (explainability/templates.ts):

interface Explanation {
  summary: string;           // One-sentence summary
  intentMatch: string;       // How intent classification influenced routing
  strategyApplied: string;   // Which strategy was used and why
  scores: ScoreBreakdown;    // Per-dimension scores
  providerRationale: string; // Why this provider was selected
  fallbackRationale: string; // Why fallback chain is ordered this way
  warnings: Warning[];       // Hard and soft warnings
  alternatives: Alternative[]; // What other options were considered
}

Score-to-Label Mapping

Scores are translated into human-readable labels (explainability/templates.ts):

Score Range	Label	Colour
90-100	Excellent	Green
75-89	Good	Teal
60-74	Acceptable	Yellow
40-59	Below Average	Orange
0-39	Poor	Red

Functions: scoreToLabel() and scoreToColor() (also in src/components/orchestration/ScoreBadge.tsx)

Warning Levels

• Hard Warnings: Non-negotiable issues (provider blocked by policy, model doesn’t support required feature)
• Soft Warnings: Recommendations (cheaper option available, higher-quality model possible)

Frontend Components

Component	File	Purpose
RoutingExplanationTimeline	src/features/replay/RoutingExplanationTimeline.tsx	Visual timeline of routing decisions
DecisionBreakdownPanel	src/features/replay/DecisionBreakdownPanel.tsx	Detailed score breakdown per dimension
ScoreBadge	src/components/orchestration/ScoreBadge.tsx	Reusable score indicator with colour coding

File Reference

File	What It Does
explainability/explainer.ts	Main explanation builder. Orchestrates all explanation types
explainability/templates.ts	Templates and label mappings for human-readable output
explainability/types.ts	TypeScript types for explanations, score breakdowns, and warnings

Integration

1. Execution Engine → provides execution trace for post-hoc explanations
2. Scoring Layer → provides per-dimension scores
3. Strategy Engine → provides strategy rationale
4. Workspace Profiles → provides policy constraints
5. Replay → stores explanations alongside traces
6. Frontend → renders explanations in the UI