Buckets:
AnonymousSpottedToad/candidate_bucket / codebase /python /dislovelhl_enhanced-agent-bus /explanation_service.py
| """ | |
| ACGS-2 Decision Explanation Service | |
| Constitutional Hash: 608508a9bd224290 | |
| Implements FR-12 Decision Explanation API requirements for structured | |
| factor attribution, governance vector analysis, and counterfactual reasoning. | |
| """ | |
| import time | |
| import uuid | |
| from collections.abc import Callable | |
| from typing import TYPE_CHECKING, Any, TypeAlias, cast | |
| try: | |
| from enhanced_agent_bus._compat.constants import CONSTITUTIONAL_HASH | |
| except ImportError: | |
| CONSTITUTIONAL_HASH = "standalone" | |
| from enhanced_agent_bus._compat.event_schemas.decision_explanation import ( | |
| CounterfactualHint, | |
| DecisionExplanationV1, | |
| EUAIActTransparencyInfo, | |
| ExplanationFactor, | |
| GovernanceDimension, | |
| PredictedOutcome, | |
| create_decision_explanation, | |
| ) | |
| if TYPE_CHECKING: | |
| from enhanced_agent_bus._compat.types import JSONDict | |
| else: | |
| JSONDict: TypeAlias = dict[str, Any] | |
| from enhanced_agent_bus.observability.structured_logging import get_logger | |
| logger = get_logger(__name__) | |
| # Default governance vector with neutral scores | |
| DEFAULT_GOVERNANCE_VECTOR: dict[str, float] = { | |
| "safety": 0.0, | |
| "security": 0.0, | |
| "privacy": 0.0, | |
| "fairness": 0.0, | |
| "reliability": 0.0, | |
| "transparency": 0.0, | |
| "efficiency": 0.0, | |
| } | |
| # Mapping of scoring components to governance dimensions | |
| FACTOR_TO_GOVERNANCE_MAPPING: dict[str, GovernanceDimension] = { | |
| "semantic_score": GovernanceDimension.SAFETY, | |
| "permission_score": GovernanceDimension.SECURITY, | |
| "volume_score": GovernanceDimension.RELIABILITY, | |
| "context_score": GovernanceDimension.TRANSPARENCY, | |
| "drift_score": GovernanceDimension.FAIRNESS, | |
| "priority_factor": GovernanceDimension.EFFICIENCY, | |
| "type_factor": GovernanceDimension.PRIVACY, | |
| } | |
| # Factor weights from ImpactScorer | |
| FACTOR_WEIGHTS: dict[str, float] = { | |
| "semantic_score": 0.6, | |
| "permission_score": 0.1, | |
| "volume_score": 0.05, | |
| "context_score": 0.2, | |
| "drift_score": 0.05, | |
| "priority_factor": 1.0, # Multiplier, not additive | |
| "type_factor": 1.0, # Multiplier, not additive | |
| } | |
| class CounterfactualEngine: | |
| """ | |
| Engine for generating counterfactual analysis hints. | |
| Provides "what-if" scenarios showing how decision outcomes might | |
| change with different input parameters. | |
| Constitutional Hash: 608508a9bd224290 | |
| """ | |
| def __init__(self) -> None: | |
| self.constitutional_hash = CONSTITUTIONAL_HASH | |
| def generate_counterfactuals( | |
| self, | |
| factors: list[ExplanationFactor], | |
| current_verdict: str, | |
| impact_score: float, | |
| max_hints: int = 3, | |
| ) -> list[CounterfactualHint]: | |
| """ | |
| Generate counterfactual hints based on current factors. | |
| Args: | |
| factors: List of current explanation factors. | |
| current_verdict: Current decision verdict. | |
| impact_score: Current impact score. | |
| max_hints: Maximum number of counterfactual hints to generate. | |
| Returns: | |
| List of CounterfactualHint objects. | |
| """ | |
| hints: list[CounterfactualHint] = [] | |
| for factor in factors[:max_hints]: | |
| hint = self._generate_single_counterfactual( | |
| factor=factor, | |
| current_verdict=current_verdict, | |
| impact_score=impact_score, | |
| ) | |
| if hint: | |
| hints.append(hint) | |
| return hints | |
| def _generate_single_counterfactual( | |
| self, | |
| factor: ExplanationFactor, | |
| current_verdict: str, | |
| impact_score: float, | |
| ) -> CounterfactualHint | None: | |
| """Generate a single counterfactual hint for a factor.""" | |
| original_value = factor.factor_value | |
| # Determine modified value (inverse direction) | |
| if original_value >= 0.7: | |
| # High score - show what happens if it were low | |
| modified_value = 0.3 | |
| scenario_desc = ( | |
| f"If {factor.factor_name} were lower (0.3 instead of {original_value:.2f})" | |
| ) | |
| elif original_value <= 0.3: | |
| # Low score - show what happens if it were high | |
| modified_value = 0.8 | |
| scenario_desc = ( | |
| f"If {factor.factor_name} were higher (0.8 instead of {original_value:.2f})" | |
| ) | |
| else: | |
| # Medium score - show threshold crossing | |
| modified_value = 0.9 if original_value < 0.5 else 0.2 | |
| scenario_desc = f"If {factor.factor_name} crossed threshold ({modified_value:.1f} instead of {original_value:.2f})" | |
| # Predict outcome based on score change | |
| predicted_outcome = self._predict_outcome_change( | |
| current_verdict=current_verdict, | |
| impact_score=impact_score, | |
| factor_weight=factor.factor_weight, | |
| value_delta=modified_value - original_value, | |
| ) | |
| # Calculate impact delta | |
| impact_delta = (modified_value - original_value) * factor.factor_weight * 0.1 | |
| return CounterfactualHint( | |
| scenario_id=f"cf-{factor.factor_id}", | |
| scenario_description=scenario_desc, | |
| modified_factor=factor.factor_name, | |
| original_value=original_value, | |
| modified_value=modified_value, | |
| predicted_outcome=predicted_outcome, | |
| confidence=0.75, # Base confidence for rule-based counterfactuals | |
| threshold_crossed=self._check_threshold_crossing(original_value, modified_value), | |
| impact_delta=impact_delta, | |
| ) | |
| def _predict_outcome_change( | |
| self, | |
| current_verdict: str, | |
| impact_score: float, | |
| factor_weight: float, | |
| value_delta: float, | |
| ) -> PredictedOutcome: | |
| """Predict outcome change based on factor modification.""" | |
| # Estimate new impact score | |
| score_delta = value_delta * factor_weight * 0.6 # 0.6 is semantic weight | |
| new_score = max(0.0, min(1.0, impact_score + score_delta)) | |
| # Decision thresholds | |
| if new_score >= 0.8: | |
| return PredictedOutcome.ESCALATE | |
| elif new_score >= 0.5: | |
| return PredictedOutcome.CONDITIONAL | |
| elif new_score >= 0.3: | |
| return PredictedOutcome.ALLOW | |
| else: | |
| return PredictedOutcome.ALLOW | |
| def _check_threshold_crossing(self, original: float, modified: float) -> str | None: | |
| """Check if a modification crosses any decision thresholds.""" | |
| thresholds = [ | |
| (0.8, "escalation_threshold"), | |
| (0.5, "review_threshold"), | |
| (0.3, "attention_threshold"), | |
| ] | |
| for threshold, name in thresholds: | |
| if (original < threshold <= modified) or (modified < threshold <= original): | |
| return name | |
| return None | |
| class ExplanationService: | |
| """ | |
| Service for generating structured decision explanations. | |
| Implements FR-12 requirements for: | |
| - Factor attribution with evidence | |
| - 7-dimensional governance vector | |
| - Counterfactual analysis | |
| - EU AI Act Article 13 compliance | |
| Constitutional Hash: 608508a9bd224290 | |
| """ | |
| def __init__( | |
| self, | |
| impact_scorer: Any | None = None, | |
| decision_store: Any | None = None, | |
| enable_counterfactuals: bool = True, | |
| ) -> None: | |
| """ | |
| Initialize the explanation service. | |
| Args: | |
| impact_scorer: Optional ImpactScorer instance for scoring. | |
| decision_store: Optional DecisionStore for persistence. | |
| enable_counterfactuals: Whether to generate counterfactual hints. | |
| """ | |
| self.constitutional_hash = CONSTITUTIONAL_HASH | |
| self.impact_scorer = impact_scorer | |
| self.decision_store = decision_store | |
| self.enable_counterfactuals = enable_counterfactuals | |
| self.counterfactual_engine = CounterfactualEngine() | |
| # Lazy import to avoid circular dependencies | |
| self._impact_scorer_loaded = False | |
| self._decision_store_loaded = False | |
| def _ensure_impact_scorer(self) -> None: | |
| """Lazy load impact scorer if not provided.""" | |
| if self.impact_scorer is None and not self._impact_scorer_loaded: | |
| try: | |
| from enhanced_agent_bus.deliberation_layer.impact_scorer import ( | |
| ImpactScorer, | |
| ) | |
| self.impact_scorer = ImpactScorer() | |
| self._impact_scorer_loaded = True | |
| except ImportError: | |
| logger.warning("ImpactScorer not available, using fallback scoring") | |
| self._impact_scorer_loaded = True | |
| async def _ensure_decision_store(self) -> None: | |
| """Lazy load decision store if not provided.""" | |
| if self.decision_store is None and not self._decision_store_loaded: | |
| try: | |
| from enhanced_agent_bus.decision_store import get_decision_store | |
| self.decision_store = await get_decision_store() | |
| self._decision_store_loaded = True | |
| except ImportError: | |
| logger.warning("DecisionStore not available, explanations won't be persisted") | |
| self._decision_store_loaded = True | |
| async def generate_explanation( | |
| self, | |
| message: JSONDict | object, | |
| verdict: str, | |
| context: JSONDict | None = None, | |
| decision_id: str | None = None, | |
| tenant_id: str | None = None, | |
| store_explanation: bool = True, | |
| ) -> DecisionExplanationV1: | |
| """ | |
| Generate a complete decision explanation. | |
| Args: | |
| message: The message or action being explained. | |
| verdict: Decision verdict (ALLOW, DENY, CONDITIONAL, ESCALATE). | |
| context: Additional context for scoring. | |
| decision_id: Optional decision ID (generated if not provided). | |
| tenant_id: Tenant identifier for multi-tenancy. | |
| store_explanation: Whether to store in decision store. | |
| Returns: | |
| DecisionExplanationV1 with full explanation. | |
| """ | |
| start_time = time.perf_counter() | |
| self._ensure_impact_scorer() | |
| if store_explanation: | |
| await self._ensure_decision_store() | |
| if context is None: | |
| context = {} | |
| if decision_id is None: | |
| decision_id = str(uuid.uuid4()) | |
| # Calculate impact score and factors | |
| impact_score, factor_scores = self._calculate_factor_scores(message, context) | |
| # Get governance vector | |
| governance_vector = self._get_governance_vector(message, context, factor_scores) | |
| # Create explanation factors | |
| factors = self._create_explanation_factors(factor_scores, message, context) | |
| # Calculate confidence | |
| confidence_score = self._calculate_confidence(factors, impact_score) | |
| # Get message ID if available | |
| message_id = self._extract_message_id(message) | |
| # Create base explanation | |
| explanation = create_decision_explanation( | |
| decision_id=decision_id, | |
| verdict=verdict.upper(), | |
| confidence_score=confidence_score, | |
| governance_vector=governance_vector, | |
| factors=[f.model_dump() for f in factors], | |
| message_id=message_id, | |
| tenant_id=tenant_id, | |
| ) | |
| # Set impact score | |
| explanation.impact_score = impact_score | |
| # Generate counterfactuals if enabled | |
| if self.enable_counterfactuals: | |
| counterfactuals = self.counterfactual_engine.generate_counterfactuals( | |
| factors=factors, | |
| current_verdict=verdict, | |
| impact_score=impact_score, | |
| ) | |
| explanation.counterfactual_hints = counterfactuals | |
| explanation.counterfactuals_generated = len(counterfactuals) > 0 | |
| # Set primary factors (top 3 by weight * value) | |
| sorted_factors = sorted( | |
| factors, key=lambda f: f.factor_value * f.factor_weight, reverse=True | |
| ) | |
| explanation.primary_factors = [f.factor_id for f in sorted_factors[:3]] | |
| # Add matched/violated rules from context | |
| explanation.matched_rules = context.get("matched_rules", []) | |
| explanation.violated_rules = context.get("violated_rules", []) | |
| explanation.applicable_policies = context.get("applicable_policies", []) | |
| # Generate summary | |
| explanation.summary = self._generate_summary(verdict, factors, impact_score) | |
| explanation.detailed_reasoning = self._generate_detailed_reasoning( | |
| verdict, factors, governance_vector, impact_score | |
| ) | |
| # Set EU AI Act compliance info | |
| explanation.euaiact_article13_info = self._create_euaiact_info(context) | |
| # Set processing time | |
| explanation.processing_time_ms = (time.perf_counter() - start_time) * 1000 | |
| # Store if enabled | |
| if store_explanation and self.decision_store: | |
| await cast(Any, self.decision_store).store(explanation) | |
| return explanation | |
| def _get_default_factor_scores(self) -> dict[str, float]: | |
| """ | |
| Return default factor scores used when ImpactScorer is unavailable. | |
| Returns: | |
| Dict mapping factor names to their default float scores. | |
| """ | |
| return { | |
| "semantic_score": 0.5, | |
| "permission_score": 0.5, | |
| "volume_score": 0.3, | |
| "context_score": 0.5, | |
| "drift_score": 0.2, | |
| "priority_factor": 0.5, | |
| "type_factor": 0.5, | |
| } | |
| def _calculate_single_factor( | |
| self, | |
| factor_name: str, | |
| scorer_method: str, | |
| args: tuple[object, ...], | |
| default: float, | |
| ) -> float: | |
| """ | |
| Calculate a single factor score with error handling. | |
| Attempts to call the specified ImpactScorer method with the given arguments. | |
| Falls back to the default value if the calculation fails. | |
| Args: | |
| factor_name: Name of the factor (for logging purposes). | |
| scorer_method: Name of the ImpactScorer method to call. | |
| args: Tuple of arguments to pass to the scorer method. | |
| default: Default value to return if calculation fails. | |
| Returns: | |
| The calculated score or the default value on failure. | |
| """ | |
| try: | |
| method = cast(Callable[..., float], getattr(self.impact_scorer, scorer_method)) | |
| return float(method(*args)) | |
| except (AttributeError, KeyError, TypeError) as e: | |
| logger.debug(f"{factor_name} calculation failed, using default: {e}") | |
| return default | |
| def _calculate_scorer_factors( | |
| self, | |
| msg_dict: JSONDict, | |
| context: JSONDict, | |
| ) -> dict[str, float]: | |
| """ | |
| Calculate all factor scores using the ImpactScorer. | |
| Iterates through defined factor configurations and calculates each | |
| score using the corresponding ImpactScorer method. | |
| Args: | |
| msg_dict: Message dictionary containing message attributes. | |
| context: Context dictionary with additional scoring context. | |
| Returns: | |
| Dict mapping factor names to their calculated float scores. | |
| """ | |
| from_agent = msg_dict.get("from_agent", "unknown") | |
| # Define factor configurations: (scorer_method, args, default) | |
| factor_configs: dict[str, tuple[str, tuple[object, ...], float]] = { | |
| "semantic_score": ("_calculate_semantic_score", (msg_dict,), 0.5), | |
| "permission_score": ("_calculate_permission_score", (msg_dict,), 0.5), | |
| "volume_score": ("_calculate_volume_score", (from_agent,), 0.3), | |
| "context_score": ("_calculate_context_score", (msg_dict, context), 0.5), | |
| "drift_score": ("_calculate_drift_score", (from_agent, 0.4), 0.2), | |
| "priority_factor": ("_calculate_priority_factor", (msg_dict, context), 0.5), | |
| "type_factor": ("_calculate_type_factor", (msg_dict, context), 0.5), | |
| } | |
| return { | |
| name: self._calculate_single_factor(name, method, args, default) | |
| for name, (method, args, default) in factor_configs.items() | |
| } | |
| def _calculate_overall_impact( | |
| self, | |
| message: JSONDict | object, | |
| context: JSONDict, | |
| factor_scores: dict[str, float], | |
| ) -> float: | |
| """ | |
| Calculate the overall impact score. | |
| Attempts to use the ImpactScorer's calculate_impact_score method. | |
| Falls back to a weighted sum of individual factor scores on failure. | |
| Args: | |
| message: The original message object or dictionary. | |
| context: Context dictionary with additional scoring context. | |
| factor_scores: Pre-calculated individual factor scores. | |
| Returns: | |
| The overall impact score as a float. | |
| """ | |
| try: | |
| scorer = cast(Any, self.impact_scorer) | |
| return float(scorer.calculate_impact_score(message, context)) | |
| except (AttributeError, KeyError, TypeError) as e: | |
| logger.debug(f"Impact score calculation failed, using fallback: {e}") | |
| additive_factors = [ | |
| "semantic_score", | |
| "permission_score", | |
| "volume_score", | |
| "context_score", | |
| "drift_score", | |
| ] | |
| return sum(factor_scores[k] * FACTOR_WEIGHTS.get(k, 0.1) for k in additive_factors) | |
| def _calculate_factor_scores( | |
| self, message: JSONDict | object, context: JSONDict | |
| ) -> tuple[float, dict[str, float]]: | |
| """ | |
| Calculate individual factor scores using ImpactScorer. | |
| Orchestrates the calculation of all factor scores and the overall | |
| impact score, delegating to helper methods for each component. | |
| Args: | |
| message: The message object or dictionary to score. | |
| context: Context dictionary with additional scoring context. | |
| Returns: | |
| Tuple of (impact_score, factor_scores_dict). | |
| """ | |
| if self.impact_scorer is None: | |
| return 0.5, self._get_default_factor_scores() | |
| msg_dict = ( | |
| cast(JSONDict, message) | |
| if isinstance(message, dict) | |
| else cast(JSONDict, getattr(message, "__dict__", {})) | |
| ) | |
| factor_scores = self._calculate_scorer_factors(msg_dict, context) | |
| impact_score = self._calculate_overall_impact(message, context, factor_scores) | |
| return impact_score, factor_scores | |
| def _get_governance_vector( | |
| self, | |
| message: JSONDict | object, | |
| context: JSONDict, | |
| factor_scores: dict[str, float], | |
| ) -> dict[str, float]: | |
| """Get or calculate the 7-dimensional governance vector.""" | |
| governance_vector = DEFAULT_GOVERNANCE_VECTOR.copy() | |
| # Try to get from ImpactScorer | |
| if self.impact_scorer is not None: | |
| try: | |
| scorer_vector = cast(Any, self.impact_scorer).get_governance_vector(context) | |
| if scorer_vector: | |
| governance_vector.update(scorer_vector) | |
| return governance_vector | |
| except (AttributeError, KeyError, TypeError) as e: | |
| logger.debug(f"Governance vector retrieval failed, using defaults: {e}") | |
| # Fallback: derive from factor scores | |
| for factor_name, score in factor_scores.items(): | |
| dimension = FACTOR_TO_GOVERNANCE_MAPPING.get(factor_name) | |
| if dimension: | |
| # Update governance dimension with factor score | |
| dim_key = dimension.value | |
| governance_vector[dim_key] = max(governance_vector[dim_key], score) | |
| return governance_vector | |
| def _create_explanation_factors( | |
| self, | |
| factor_scores: dict[str, float], | |
| message: JSONDict | object, | |
| context: JSONDict, | |
| ) -> list[ExplanationFactor]: | |
| """Create ExplanationFactor objects from scores.""" | |
| factors: list[ExplanationFactor] = [] | |
| factor_metadata = { | |
| "semantic_score": { | |
| "name": "Content Analysis", | |
| "explanation": "Score based on semantic analysis of message content for high-impact keywords", | |
| "source": "semantic_scorer", | |
| "method": "keyword_matching", | |
| }, | |
| "permission_score": { | |
| "name": "Permission Check", | |
| "explanation": "Score based on requested permissions and security implications", | |
| "source": "permission_checker", | |
| "method": "permission_analysis", | |
| }, | |
| "volume_score": { | |
| "name": "Request Volume", | |
| "explanation": "Score based on agent request volume and rate patterns", | |
| "source": "volume_tracker", | |
| "method": "rate_analysis", | |
| }, | |
| "context_score": { | |
| "name": "Context Analysis", | |
| "explanation": "Score based on message context and metadata quality", | |
| "source": "context_analyzer", | |
| "method": "context_evaluation", | |
| }, | |
| "drift_score": { | |
| "name": "Behavior Drift", | |
| "explanation": "Score based on deviation from established behavioral patterns", | |
| "source": "drift_detector", | |
| "method": "statistical_analysis", | |
| }, | |
| "priority_factor": { | |
| "name": "Priority Level", | |
| "explanation": "Factor based on message priority affecting urgency of processing", | |
| "source": "priority_evaluator", | |
| "method": "priority_mapping", | |
| }, | |
| "type_factor": { | |
| "name": "Message Type", | |
| "explanation": "Factor based on message type affecting processing requirements", | |
| "source": "type_classifier", | |
| "method": "type_categorization", | |
| }, | |
| } | |
| for factor_name, score in factor_scores.items(): | |
| metadata = factor_metadata.get( | |
| factor_name, | |
| { | |
| "name": factor_name.replace("_", " ").title(), | |
| "explanation": f"Calculated {factor_name} for governance decision", | |
| "source": "impact_scorer", | |
| "method": "calculation", | |
| }, | |
| ) | |
| dimension = FACTOR_TO_GOVERNANCE_MAPPING.get( | |
| factor_name, GovernanceDimension.TRANSPARENCY | |
| ) | |
| # Generate evidence based on score | |
| evidence = self._generate_factor_evidence(factor_name, score, message, context) | |
| factor = ExplanationFactor( | |
| factor_id=f"f-{factor_name}", | |
| factor_name=metadata["name"], | |
| factor_value=score, | |
| factor_weight=FACTOR_WEIGHTS.get(factor_name, 1.0), | |
| explanation=metadata["explanation"], | |
| evidence=evidence, | |
| governance_dimension=dimension, | |
| source_component=metadata["source"], | |
| calculation_method=metadata["method"], | |
| ) | |
| factors.append(factor) | |
| return factors | |
| def _generate_factor_evidence( | |
| self, | |
| factor_name: str, | |
| score: float, | |
| message: JSONDict | object, | |
| context: JSONDict, | |
| ) -> list[str]: | |
| """Generate evidence items for a factor.""" | |
| evidence: list[str] = [] | |
| if factor_name == "semantic_score": | |
| if score >= 0.9: | |
| evidence.append("High-impact keywords detected in content") | |
| elif score >= 0.5: | |
| evidence.append("Moderate semantic indicators present") | |
| else: | |
| evidence.append("No high-impact keywords detected") | |
| elif factor_name == "permission_score": | |
| if score >= 0.7: | |
| evidence.append("Elevated permissions requested") | |
| else: | |
| evidence.append("Standard permission level") | |
| elif factor_name == "priority_factor": | |
| msg_dict = message if isinstance(message, dict) else getattr(message, "__dict__", {}) | |
| priority = context.get("priority") or msg_dict.get("priority", "normal") | |
| evidence.append(f"Priority level: {priority}") | |
| elif factor_name == "volume_score": | |
| if score >= 0.7: | |
| evidence.append("High request volume from agent") | |
| else: | |
| evidence.append("Normal request volume") | |
| # Add constitutional hash as evidence | |
| evidence.append(f"Constitutional hash: {self.constitutional_hash}") | |
| return evidence | |
| def _calculate_confidence(self, factors: list[ExplanationFactor], impact_score: float) -> float: | |
| """Calculate overall confidence in the decision.""" | |
| if not factors: | |
| return 0.5 | |
| # Base confidence on factor agreement | |
| factor_values = [f.factor_value for f in factors] | |
| variance = self._calculate_variance(factor_values) | |
| # Lower variance = higher confidence | |
| base_confidence = max(0.5, 1.0 - variance) | |
| # Adjust for extreme scores (more confident at extremes) | |
| if impact_score >= 0.9 or impact_score <= 0.1: | |
| base_confidence = min(1.0, base_confidence + 0.1) | |
| return base_confidence | |
| def _calculate_variance(self, values: list[float]) -> float: | |
| """Calculate variance of a list of values.""" | |
| if not values: | |
| return 0.0 | |
| mean = sum(values) / len(values) | |
| return sum((v - mean) ** 2 for v in values) / len(values) | |
| def _extract_message_id(self, message: JSONDict | object) -> str | None: | |
| """Extract message ID from message object.""" | |
| if isinstance(message, dict): | |
| message_id = message.get("message_id") or message.get("id") | |
| return str(message_id) if isinstance(message_id, str) else None | |
| message_id = getattr(message, "message_id", None) or getattr(message, "id", None) | |
| return str(message_id) if isinstance(message_id, str) else None | |
| def _generate_summary( | |
| self, verdict: str, factors: list[ExplanationFactor], impact_score: float | |
| ) -> str: | |
| """Generate a brief human-readable summary.""" | |
| primary_factor = ( | |
| max(factors, key=lambda f: f.factor_value * f.factor_weight) if factors else None | |
| ) | |
| primary_name = primary_factor.factor_name if primary_factor else "analysis" | |
| if verdict.upper() == "ALLOW": | |
| return f"Decision: ALLOW. Impact score {impact_score:.2f} is below threshold. Primary factor: {primary_name}." | |
| elif verdict.upper() == "DENY": | |
| return f"Decision: DENY. Impact score {impact_score:.2f} exceeds threshold. Primary factor: {primary_name}." | |
| elif verdict.upper() == "CONDITIONAL": | |
| return f"Decision: CONDITIONAL. Impact score {impact_score:.2f} requires additional review. Primary factor: {primary_name}." | |
| else: | |
| return f"Decision: {verdict}. Impact score {impact_score:.2f}. Primary factor: {primary_name}." | |
| def _generate_detailed_reasoning( | |
| self, | |
| verdict: str, | |
| factors: list[ExplanationFactor], | |
| governance_vector: dict[str, float], | |
| impact_score: float, | |
| ) -> str: | |
| """Generate detailed reasoning explanation.""" | |
| lines = [ | |
| f"Constitutional Governance Analysis (Hash: {self.constitutional_hash})", | |
| "", | |
| f"Overall Impact Score: {impact_score:.3f}", | |
| f"Final Verdict: {verdict.upper()}", | |
| "", | |
| "Factor Attribution:", | |
| ] | |
| sorted_factors = sorted( | |
| factors, key=lambda f: f.factor_value * f.factor_weight, reverse=True | |
| ) | |
| for f in sorted_factors: | |
| contribution = f.factor_value * f.factor_weight | |
| lines.append( | |
| f" - {f.factor_name}: {f.factor_value:.3f} (weight: {f.factor_weight:.2f}, contribution: {contribution:.3f})" | |
| ) | |
| lines.append("") | |
| lines.append("7-Dimensional Governance Vector:") | |
| for dim, score in governance_vector.items(): | |
| lines.append(f" - {dim}: {score:.3f}") | |
| return "\n".join(lines) | |
| def _create_euaiact_info(self, context: JSONDict) -> EUAIActTransparencyInfo: | |
| """Create EU AI Act Article 13 transparency information.""" | |
| return EUAIActTransparencyInfo( | |
| article_13_compliant=True, | |
| human_oversight_level=context.get("human_oversight_level", "human-on-the-loop"), | |
| risk_category=context.get("risk_category", "limited"), | |
| transparency_measures=[ | |
| "Decision explanation API (FR-12)", | |
| "Factor attribution with evidence", | |
| "7-dimensional governance vector", | |
| "Counterfactual analysis", | |
| "Audit trail integration", | |
| ], | |
| data_governance_info={ | |
| "constitutional_hash": self.constitutional_hash, | |
| "data_retention_days": 90, | |
| "anonymization_applied": True, | |
| }, | |
| technical_documentation_ref="ACGS-2 v2.3 Specification", | |
| conformity_assessment_status="completed", | |
| intended_purpose="AI governance decision-making", | |
| limitations_and_risks=[ | |
| "Model-based scoring may have inherent biases", | |
| "Counterfactual analysis is estimative", | |
| ], | |
| human_reviewers=context.get("human_reviewers", []), | |
| ) | |
| async def get_explanation( | |
| self, decision_id: str, tenant_id: str = "default" | |
| ) -> DecisionExplanationV1 | None: | |
| """ | |
| Retrieve a stored explanation by decision ID. | |
| Args: | |
| decision_id: The decision ID to retrieve. | |
| tenant_id: Tenant identifier. | |
| Returns: | |
| DecisionExplanationV1 if found, None otherwise. | |
| """ | |
| await self._ensure_decision_store() | |
| if self.decision_store: | |
| result = await cast(Any, self.decision_store).get(decision_id, tenant_id) | |
| return cast(DecisionExplanationV1 | None, result) | |
| return None | |
| async def explain( | |
| self, | |
| *, | |
| message_id: str, | |
| factors: dict[str, Any] | None = None, | |
| include_counterfactuals: bool = False, | |
| tenant_id: str = "default", | |
| ) -> DecisionExplanationV1: | |
| """Compatibility shim for older explanation port callers.""" | |
| previous = self.enable_counterfactuals | |
| self.enable_counterfactuals = include_counterfactuals | |
| context: JSONDict = factors or {} | |
| verdict = str(context.get("verdict", "ALLOW")) | |
| try: | |
| return await self.generate_explanation( | |
| message={"message_id": message_id}, | |
| verdict=verdict, | |
| context=context, | |
| decision_id=message_id, | |
| tenant_id=tenant_id, | |
| store_explanation=False, | |
| ) | |
| finally: | |
| self.enable_counterfactuals = previous | |
| # Singleton instance | |
| _explanation_service: ExplanationService | None = None | |
| def get_explanation_service() -> ExplanationService: | |
| """Get or create the singleton ExplanationService instance.""" | |
| global _explanation_service | |
| if _explanation_service is None: | |
| _explanation_service = ExplanationService() | |
| return _explanation_service | |
| def reset_explanation_service() -> None: | |
| """Reset the singleton instance (for testing).""" | |
| global _explanation_service | |
| _explanation_service = None | |
| class ExplanationServiceAdapter: | |
| """MD-010 adapter: wraps ExplanationService to satisfy ExplanationPort Protocol. | |
| Services depend on ExplanationPort (contracts layer) rather than on the | |
| concrete ExplanationService, enabling independent testing and future | |
| implementation swaps without modifying service code. | |
| Constitutional Hash: 608508a9bd224290 | |
| """ | |
| def __init__(self, service: ExplanationService | None = None) -> None: | |
| self._service = service or get_explanation_service() | |
| async def explain_decision( | |
| self, | |
| message_id: str, | |
| *, | |
| factors: dict[str, Any] | None = None, | |
| include_counterfactuals: bool = False, | |
| tenant_id: str = "default", | |
| ) -> dict[str, Any]: | |
| """Delegate to ExplanationService.explain() and serialize result.""" | |
| result = await self._service.explain( | |
| message_id=message_id, | |
| factors=factors or {}, | |
| include_counterfactuals=include_counterfactuals, | |
| tenant_id=tenant_id, | |
| ) | |
| return result.model_dump() if hasattr(result, "model_dump") else dict(result) | |
| async def get_explanation( | |
| self, | |
| decision_id: str, | |
| tenant_id: str = "default", | |
| ) -> dict[str, Any] | None: | |
| """Retrieve a stored explanation and serialize to dict (or None).""" | |
| result = await self._service.get_explanation(decision_id, tenant_id) | |
| if result is None: | |
| return None | |
| return result.model_dump() if hasattr(result, "model_dump") else dict(result) | |
| __all__ = [ | |
| "DEFAULT_GOVERNANCE_VECTOR", | |
| "FACTOR_TO_GOVERNANCE_MAPPING", | |
| "FACTOR_WEIGHTS", | |
| "CounterfactualEngine", | |
| "ExplanationService", | |
| "ExplanationServiceAdapter", | |
| "get_explanation_service", | |
| "reset_explanation_service", | |
| ] | |
Xet Storage Details
- Size:
- 33.5 kB
- Xet hash:
- ed926b2a085d21ef448b4bf5e291d9ba9a100a57ba39beaaa478fc11a1533647
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.