# 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 PyPI

```bash
pip install xai-ia
```

### From Source

```bash
# 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)

```python
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)

```python
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

```bash
# 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

```bash
# 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

```json
{
  "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

```python
# 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.10+
- 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](LICENSE) for the full license text.

Copyright 2026 Maggioli SPA

## Author

Costas Vrioni (costas.vrioni@maggioli.gr)

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
