xai-ia 0.4.0

Explainable AI toolkit with pluggable explainer backends and optional IA service integration

XAI Suite

A generic, domain-agnostic Python toolkit for Explainable AI (XAI). Provides SHAP and LIME explainability methods with optional server-side narrative generation, actionable insights, and EU AI Act compliance documentation.

Part of the CyberNEMO Project

Overview

XAI Suite uses a hybrid architecture:

• xai_suite (client library): SHAP/LIME run locally with your model
• xai_suite_service (server): IA Narrative Engine + Insights + EU AI Act compliance

CUSTOMER ENVIRONMENT                          SERVER (Protected IP)
┌────────────────────────────────┐            ┌─────────────────────────────────────┐
│  Your ML Model                 │            │  XAI Suite Service                  │
│            │                   │            │                                     │
│  ┌─────────────────────────┐   │            │  ┌─────────────────────────────┐    │
│  │  xai_suite (client)     │   │            │  │  Domain Registry            │    │
│  │  - SHAP/LIME (local)    │   │  HTTP      │  │  - generic                  │    │
│  │  - IAClient             │───┼──────────▶ │  │  - cybersecurity            │    │
│  └─────────────────────────┘   │            │  │  - (extensible)             │    │
│                                │            │  └─────────────────────────────┘    │
│  Response includes:            │            │                                     │
│  - narrative                   │◀───────────│  IA Engine + Compliance Module      │
│  - insights                    │            │                                     │
│  - compliance                  │            │                                     │
└────────────────────────────────┘            └─────────────────────────────────────┘

Key Features

• Domain-Agnostic: Works with any ML application through pluggable domain contexts
• SHAP & LIME: Local explainability runs with your model
• IA is Optional: Works standalone without the server
• Actionable Insights: Domain-specific recommendations from explanations
• EU AI Act Compliance: Audit logging and article references
• Server-side LLM: Protects prompts and IP

Pluggable Domains

• generic - Default fallback for any ML application
• cybersecurity - Network security, firewall analysis, anomaly detection
• Extensible for fraud, healthcare, financial, etc.

Installation

From TestPyPI

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ xai-suite

From Source

# Install the client library
pip install -e .

# Install with server dependencies
pip install -e ".[server]"

# Install with all dependencies (including LLM backends)
pip install -e ".[all]"

Quick Start

Basic Usage (Local Only)

from xai_suite import XAIOrchestrator

# Initialize with your model
orchestrator = XAIOrchestrator(model, X_train)
orchestrator.add_explainer("shap")
orchestrator.add_explainer("lime", {"mode": "classification"})

# Generate explanations
result = orchestrator.explain(instance)
print(result["shap"]["importance_scores"])
print(result["lime"]["importance_scores"])

With IA Service (Recommended)

from xai_suite import XAIOrchestrator

orchestrator = XAIOrchestrator(model, X_train)
orchestrator.add_explainer("shap")

# Enable IA with domain context
orchestrator.enable_ia(
    endpoint="https://xai.your-server.com",
    api_key="your-api-key",
    domain="cybersecurity",  # or "generic"
    model_type="anomaly_detection"
)

result = orchestrator.explain(instance)

# Access results
print(result["shap"]["importance_scores"])  # Local SHAP values
print(result["narrative"]["text"])          # Human-readable narrative
print(result["insights"])                   # Actionable recommendations
print(result["compliance"]["applicable_articles"])  # EU AI Act references

Running the Examples

# Classification example (Iris dataset)
python examples/run_classification_example.py

# Anomaly detection example (requires data/hubble2.csv)
python examples/run_anomaly_detection_example.py

Running the IA Service

# Start the server
uvicorn xai_suite_service.main:app --reload

# Or with Docker
docker-compose up -d

Configure via environment variables:

• XAI_LLM_BACKEND: template, ollama, openai, anthropic
• XAI_API_KEYS: Comma-separated API keys
• XAI_COMPLIANCE_ENABLED: Enable EU AI Act logging

API Endpoints

Endpoint	Method	Description
/api/v1/health	GET	Health check with available domains
/api/v1/domains	GET	List available domain contexts
/api/v1/narrative	POST	Generate narrative (v1 legacy)
/api/v1/v2/explain	POST	Generate narrative + insights + compliance (v2)

V2 API Response Example

{
  "narrative": {
    "text": "The anomaly detection model flagged this traffic...",
    "method": "SHAP",
    "domain": "cybersecurity",
    "timestamp": "2026-02-04T10:30:00Z"
  },
  "insights": [
    {
      "type": "warning",
      "priority": "high",
      "title": "SYN Flood Pattern Suspected",
      "description": "High SYN count relative to ACK suggests...",
      "action": "Enable SYN cookies, implement rate limiting",
      "related_features": ["syn_count", "ack_count"]
    }
  ],
  "compliance": {
    "audit_id": "audit-2026-02-04-abc123",
    "timestamp": "2026-02-04T10:30:00Z",
    "applicable_articles": [
      {
        "article": "article_13",
        "title": "Transparency and provision of information",
        "relevance": "XAI explanations support transparency requirements"
      }
    ]
  }
}

Project Structure

xai-suite/
├── xai_suite/                    # Client library
│   ├── orchestrator.py           # Main entry point
│   ├── explainers/               # SHAP, LIME implementations
│   ├── utils/                    # Model wrapper, visualization
│   └── ia/                       # IA client (HTTP)
│
├── xai_suite_service/            # Server service
│   ├── main.py                   # FastAPI app
│   ├── api/                      # API routes (v1 + v2)
│   ├── ia_engine/
│   │   ├── domains/              # Pluggable domain contexts
│   │   ├── narrative.py          # Narrative generation
│   │   ├── insights.py           # Insight generation
│   │   └── llm_backends.py       # LLM integrations
│   └── compliance/               # EU AI Act logging
│
├── examples/                     # Example scripts
├── data/                         # Sample datasets
└── pyproject.toml

Extending the System

Adding New Domains

# xai_suite_service/ia_engine/domains/your_domain.py
from xai_suite_service.ia_engine.domains.base import DomainContext

class YourDomain(DomainContext):
    @property
    def domain_id(self) -> str:
        return "your_domain"

    @property
    def display_name(self) -> str:
        return "Your Domain"

    def get_feature_description(self, feature_name: str):
        # Return domain-specific feature descriptions
        ...

    def detect_patterns(self, feature_values: dict):
        # Detect domain-specific patterns
        ...

    def get_recommendations(self, feature_importances, patterns, prediction_value):
        # Generate domain-specific recommendations
        ...

    def get_system_prompt(self) -> str:
        # Return LLM system prompt for this domain
        ...

Adding New Explainers

1. Inherit from BaseExplainer in xai_suite/explainers/
2. Implement _initialize_explainer() and explain_local()
3. Register in XAIOrchestrator.AVAILABLE_EXPLAINERS

Requirements

Client Library:

• Python 3.11+
• scikit-learn, shap, lime, numpy, pandas, matplotlib
• httpx, pydantic (for IA integration)

Server Service:

• FastAPI, uvicorn, pydantic-settings
• Optional: ollama, openai, anthropic SDKs

License

This project is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Copyright 2026 Maggioli SPA

Author

Costas Vrioni ([e-mail])

Developed as part of the CyberNEMO research initiative.

Related Work

• SHAP (Lundberg & Lee, 2017)
• LIME (Ribeiro et al., 2016)
• EU AI Act - Regulation (EU) 2024/1689