Metadata-Version: 2.4
Name: mais
Version: 3.0.2
Summary: A Python library and Jupyter plugin that detects risky ML model and dataset loads.
Author-email: Daniel Bardenstein <daniel@manifestcyber.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: anchore-syft>=1.18.1
Requires-Dist: ipython>=7.0.0
Requires-Dist: pydantic>=2.11.7
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: requests>=2.31.0

# MAIS - ML Model Audit & Inspection System

A Python library that watches for potentially risky model or dataset loads. MAIS analyzes code in real-time to detect when you're trying to load models that might require special permissions or licensing. It works as a Jupyter notebook plugin **and** as a plain Python library — instantiate `MAIS()` in a regular script and it automatically hooks into your imports the same way it hooks into notebook cells.

## Detection

MAIS uses provider-based detection: specialized AST and regex detectors per ML/AI provider, combining structural analysis with pattern matching for broad coverage.

| Provider        | Coverage                                              |
| --------------- | ----------------------------------------------------- |
| **HuggingFace** | Transformers, Hub model loads, `datasets` integration |
| **OpenAI**      | Full API client and model usage                       |
| **PyTorch**     | `torch.load` and extended model-loading patterns      |
| **Anthropic**   | Claude API integrations                               |
| **LangChain**   | LangChain components, chains, and framework usage     |
| **LlamaIndex**  | LlamaIndex document processing                        |

## Architecture Overview

MAIS uses a flexible, strategy-based architecture with multiple specialized components:

![MAIS Architecture](docs/images/architecture.svg)

### Additional Architecture Views

| View                | Purpose                             | Link                                                       |
| ------------------- | ----------------------------------- | ---------------------------------------------------------- |
| **📊 Dependencies** | Component relationships & data flow | [MAIS_DEPENDENCY.svg](docs/images/MAIS_DEPENDENCY.svg)     |
| **⚡ Process Flow** | End-to-end analysis workflow        | [MAIS_PROCESS.svg](docs/images/MAIS_PROCESS.svg)           |
| **🏗️ DDD Layers**   | Domain-driven design structure      | [MAIS_ARCHITECTURE.svg](docs/images/MAIS_ARCHITECTURE.svg) |

### Core Components

#### 📥 **Input Layer**

Processes various types of source code inputs:

- **Source Code**: Direct Python code analysis
- **Notebooks**: Jupyter notebook cell analysis
- **Requirements**: Dependency file scanning
- **Python Files**: Static file analysis

#### 🔍 **Provider-Specific Detectors**

Specialized detectors for different ML/AI providers and frameworks:

- **OpenAI**: Detects GPT, DALL-E, and OpenAI API usage
- **HuggingFace**: Identifies Transformers, Datasets, and Hub model loads
- **Anthropic**: Catches Claude API integrations
- **LangChain**: Finds LangChain components and chains
- **LlamaIndex**: Detects LlamaIndex document processing

#### ⚙️ **Detection Strategies**

Pluggable analysis approaches that detectors can use:

- **AST Strategy**: Advanced parsing with variable resolution for complex code analysis
- **Regex Strategy**: Fast pattern matching for simple detection scenarios
- **LLM-based Strategy**: Future AI-powered code understanding

#### 📊 **Intermediate Output**

Analysis results from provider detectors:

- **Model Findings**: Detected model usage with metadata
- **Risk Assessment**: Security and compliance evaluation
- **Inventory Mapping**: Model-to-provider relationship mapping

#### 📋 **JSON Schema Standardization**

Converts findings into structured format:

- **AI Detection JSON Schema**: Standardized detection results format
- **Provider Attribution**: Links findings to specific ML providers
- **Risk Categorization**: Security and compliance classifications

#### 📦 **SBOM Generation**

Creates comprehensive software bills of materials:

- **manifest-cli Integration**: Uses external SBOM generation tools
- **SBOM Builder**: Internal component for SBOM creation
- **Dependency Analysis**: Maps AI/ML dependencies

#### 📤 **Output Formats**

Multiple standard formats for integration:

- **CycloneDX JSON**: Industry-standard SBOM format
- **SPDX JSON**: Open-source license compliance format

## Installation

```bash
# Using pip
pip install mais
```

```python
# Import and initialize the MAIS plugin
from mais import MAIS

m = MAIS(api_token="<manifest-api-token>")

# Now run your notebook as normal
# MAIS will monitor for potentially risky model loads
```

## Using MAIS in a Plain Python Script

MAIS isn't limited to Jupyter — you can use it directly from any Python script, CI job, or service. Instantiating `MAIS()` outside of a notebook automatically installs script-mode hooks that mirror the per-cell behavior you get in Jupyter:

- **One-shot scan of your entry script** (`__main__`) at construction time.
- **Per-module import hook** (`sys.meta_path` finder) that analyzes the source of each first-party module you import *before* it executes. Stdlib and `site-packages` modules are skipped automatically — only your user code is scanned.

```python
from mais import MAIS

# Instantiating MAIS in a regular script automatically:
#   1. Reads and analyzes the running script's source.
#   2. Installs an import hook so every user module you import next
#      gets analyzed before it runs (just like a Jupyter cell).
m = MAIS(api_token="<manifest-api-token>", verbosity="DEBUG")

from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("moonshotai/Kimi-K2-Instruct")

from datasets import load_dataset
dataset = load_dataset("ProlificAI/social-reasoning-rlhf")

# Methods like register_model() and create_sbom() work without any
# extra plumbing — MAIS uses the cached script source automatically.
m.register_model("my_custom_model", "1.0", "Acme", "USA")
m.create_sbom(path=".", publish=False)

# Need to detach the import hook (e.g. in tests)?
m.uninstall()
```

Expected output (truncated):

```text
MAIS [DEBUG]: Jupyter plugin initialized
MAIS [DEBUG]: Found dataset loading call: load_dataset('ProlificAI/social-reasoning-rlhf')
MAIS [DEBUG]: Datasets found: [{'title': 'ProlificAI/social-reasoning-rlhf', ...}]
MAIS [DEBUG]: Custom model registration → POST https://api.manifestcyber.com/v1/model-analysis/custom
MAIS [DEBUG]: Model '<id>' registered successfully
✅ SBOM Created — sbom.json written at .
```

### Google Colab Usage

Perfect for environments where you can't set environment variables:

```python
from google.colab import userdata
api_token = userdata.get('MANIFEST_API_KEY')

from mais import MAIS
m = MAIS(api_token=api_token)
```

## SBOM Generation

```python
# Generate an SBOM for your project or notebook environment.
m.create_sbom(path=".", publish=False)
```

## SBOM Publishing

```python
m.create_sbom(path=".", publish=True)
```

## Environment Variables

MAIS supports configuration through environment variables:

### Core Configuration

- `MANIFEST_API_TOKEN` - API token for MOSAIC/Manifest integration
- `MAIS_MOSAIC_API_URL` - Override default API URL
- `MAIS_DEFAULT_VERBOSITY` - Set default logging level
- `MAIS_API_TIMEOUT` - API request timeout in seconds

All configuration values can be overridden with `MAIS_` prefix.

