Metadata-Version: 2.4
Name: veritas-ml
Version: 0.1.7
Summary: AI Bias Detection and Ethics Compliance Agent
Author: AI Ethics Team
License: MIT
Project-URL: Homepage, https://github.com/anomalyco/veritas
Project-URL: Repository, https://github.com/anomalyco/veritas
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aif360>=0.6.1
Requires-Dist: langgraph>=0.3.0
Requires-Dist: langchain-openai>=0.3.0
Requires-Dist: langchain-ollama>=0.2.0
Requires-Dist: langchain-groq>=0.2.0
Requires-Dist: langsmith>=0.1.0
Requires-Dist: langchain-huggingface>=0.1.0
Requires-Dist: langchain-chroma>=0.2.0
Requires-Dist: langchain-community>=0.3.0
Requires-Dist: langchain-text-splitters>=0.3.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: chromadb>=0.5.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyarrow>=22.0.0
Provides-Extra: tensorflow
Requires-Dist: tensorflow<2.20.0,>=2.19.0; extra == "tensorflow"
Dynamic: license-file

# Veritas - AI Bias Detection and Ethics Compliance

A Python package for detecting bias in ML models and checking compliance with AI ethics laws using RAG-powered recommendations.

[![PyPI](https://img.shields.io/pypi/v/veritas-ml)](https://pypi.org/project/veritas-ml/)
[![Python](https://img.shields.io/pypi/pyversions/veritas-ml)](https://pypi.org/project/veritas-ml/)

## Features

- **Automatic bias detection** using IBM AIF360 toolkit
- **AI ethics compliance checking** via LangGraph ReAct agent
- **RAG-powered law lookup** from bundled AI ethics knowledge base
- **sklearn-compatible wrappers** for drop-in integration
- **Auto-initialization** - knowledge base ingests automatically on first import

## Installation

```bash
# From PyPI
pip install veritas-ml

# From source
pip install -e .

# Set API key for LLM provider
export OPENROUTER_API_KEY="your-key-here"
# OR
export GROQ_API_KEY="your-key-here"
```

## Quick Start

### Pattern 1: Drop-in sklearn Replacement

```python
from veritas import VeritasClassifier
from sklearn.linear_model import LogisticRegression

# Wrap any sklearn classifier
clf = VeritasClassifier(
    base_estimator=LogisticRegression(),
    protected_attribute="gender",
    run_audit=True,
    generate_report=True
)

# Fit with sensitive features
clf.fit(X_train, y_train, sensitive_features=sensitive_train)

# Get reports
print(clf.get_bias_report())         # AIF360 metrics
print(clf.get_compliance_report())   # Mitigation recommendations
```

### Pattern 2: Manual Audit After Training

```python
from veritas import BiasDetector, ComplianceChecker

# Train your model normally
model.fit(X_train, y_train)

# Audit separately
detector = BiasDetector(
    protected_attribute="sex",
    privileged_classes=["Male"]
)
bias_report = detector.audit(model, X_test, y_test, sensitive_test)

# Check compliance
checker = ComplianceChecker()
compliance_report = checker.check(bias_report)
```

### Pattern 3: Full End-to-End Audit

```python
from veritas import ComplianceChecker

checker = ComplianceChecker()
result = checker.full_audit(
    X_train=X_train, y_train=y_train,
    X_test=X_test, y_test=y_test,
    sensitive_train=sensitive_train,
    sensitive_test=sensitive_test,
    protected_attribute="sex"
)

print(result["compliance_report"])
```

## Publishing to PyPI

This section documents how to release new versions of `veritas-ml` to the Python Package Index.

### Prerequisites

1. **PyPI Account**: Create an account at https://pypi.org/
2. **API Token**: Generate at https://pypi.org/manage/account/#api-tokens
3. **Token Access**: Ensure token has scope for `veritas-ml` project

### Set Up Your Token

Add to `veritas/.env`:
```bash
PYPI_API_TOKEN=pypi-AgEIcHlwaS5vcmcC...
```

Or set environment variable:
```bash
export PYPI_API_TOKEN="your-token-here"
```

### Using the Upload Script (Recommended)

```bash
# Navigate to veritas directory
cd veritas

# Option 1: Test first, then live (recommended)
python scripts/upload_pypi.py --test

# Option 2: Direct live upload
python scripts/upload_pypi.py

# Option 3: Build only (for verification)
python scripts/upload_pypi.py --build
```

### Manual Upload (Alternative)

```bash
# Install build tools
pip install build twine

# Clean previous builds
rm -rf dist/ build/ src/*egg-info/

# Build
python -m build

# Upload to TestPyPI first (recommended)
twine upload --repository testppi dist/*
# Verify: https://test.pypi.org/project/veritas-ml/
# Install: pip install --index-url https://test.pypi.org/simple veritas-ml

# Upload to live PyPI
twine upload --repository pypi dist/*
```

### Version Bumping

Before uploading, increment version in `pyproject.toml`:

```toml
[project]
version = "0.1.1"  # Increment as needed
```

### Troubleshooting

| Error | Solution |
|-------|---------|
| `name too similar` | Change package name in `pyproject.toml` |
| `403 Forbidden` | Check API token permissions |
| `[mutex.cc : 452]` | TensorFlow and PyArrow are included by default (see Dependencies) |

## Dependencies

### LLM Providers

Veritas loads settings in this order:
1. Explicit constructor overrides (e.g. `ComplianceChecker(llm_provider="groq")`)
2. Environment variables (auto-loaded from `veritas/.env`)
3. `defaults.json` (`veritas/defaults.json` or repository-root `defaults.json`)
4. `~/.veritas/config.json`

Environment variables:

```bash
# OpenRouter
export LLM_PROVIDER=openrouter
export OPENROUTER_API_KEY=your-key

# Ollama (local)
export LLM_PROVIDER=ollama
export OLLAMA_BASE_URL=http://localhost:11434

# Groq
export LLM_PROVIDER=groq
export GROQ_API_KEY=your-key
```

Or set `defaults.json`:

```json
{
  "provider": "ollama",
  "llm": "qwen3.5:4b"
}
```

You can still use `~/.veritas/config.json`:

```json
{
  "provider": "openrouter",
  "llm": "openai/gpt-4o-mini"
}
```

### Knowledge Base

The AI ethics knowledge base auto-initializes on first import at `~/.veritas/vector_store/`.

## API Reference

### `VeritasClassifier`

sklearn-compatible wrapper with built-in bias auditing.

**Parameters:**
- `base_estimator`: sklearn estimator (default: LogisticRegression)
- `protected_attribute`: Name of protected attribute
- `privileged_classes`: Privileged class values
- `run_audit`: Run bias audit on fit()
- `generate_report`: Generate compliance report

**Methods:**
- `fit(X, y, sensitive_features=None)` - Train and audit
- `predict(X)` - Predict labels
- `get_bias_report()` - Get AIF360 metrics
- `get_compliance_report()` - Get mitigation recommendations
- `has_bias()` - Check if bias detected

### `BiasDetector`

Low-level bias detection with AIF360.

**Methods:**
- `audit(model, X_test, y_test, sensitive_features)` - Run audit

### `ComplianceChecker`

High-level compliance checking with LLM agent.

**Methods:**
- `check(bias_report)` - Analyze bias report
- `full_audit(...)` - End-to-end training + audit + compliance

## Dependencies

- aif360 >= 0.6.1
- langgraph >= 0.3.0
- langchain-* providers
- chromadb >= 0.5.0
- scikit-learn >= 1.3.0

## License

MIT
