verity-audit 1.3.1
Verity - AI Governance Through Enforcement (API + CLI)
Requires Python: <3.14,>=3.11
Keywords: ai, governance, fairness, audit, compliance, ml, machine-learning

# Verity - AI Governance Through Enforcement

Complete AI model audit system with CI/CD integration, evidence storage, and regulator-ready exports.

## Quick Start

### Install Dependencies

```bash
# Install root dependencies (concurrently)
npm install

# Install website and dashboard dependencies
npm run install:all
```

### Run Everything

```bash
# Run website, dashboard, and API together
npm run dev:all
```

This will start:
- **Website**: http://localhost:3000
- **Dashboard**: http://localhost:3001
- **API**: http://localhost:8000

### Run Individual Services

```bash
# Just the website
npm run dev:website

# Just the dashboard
npm run dev:dashboard

# Just the API
npm run dev:api
```

## Project Structure

```
ai-audit-ci/
├── audit/              # CLI audit tool
│   ├── cli.py         # Main CLI interface
│   ├── metrics.py      # Fairness metrics
│   ├── evidence.py    # Report generation
│   └── export.py      # PDF/JSON exports
├── api/                # FastAPI backend
│   ├── main.py        # API server
│   ├── database.py    # Database models
│   ├── routes/        # API routes
│   └── manage.py      # Management CLI
├── website/            # Marketing website (React)
│   └── src/
│       ├── pages/     # Website pages
│       └── components/
└── dashboard/          # Dashboard app (React)
    └── src/
        ├── pages/     # Dashboard pages
        └── components/
```

## Features

### Core Audit Tool
- ✅ Fairness metrics (demographic parity, equal opportunity, disparate impact)
- ✅ SHA-256 hashing for all artifacts
- ✅ Immutable audit reports
- ✅ GitHub Actions integration
- ✅ Regulator-ready PDF/JSON exports

### API & Evidence Store
- ✅ User authentication
- ✅ Organization & project management
- ✅ API key management
- ✅ Append-only audit storage
- ✅ Commit context tracking
- ✅ Policy versioning

### Dashboard
- ✅ Project overview with statistics
- ✅ Audit timeline visualization
- ✅ Trend charts
- ✅ Policy management
- ✅ Regulator portal (Enterprise)

### Website
- ✅ Dark, professional design
- ✅ Responsive layout
- ✅ Animated interactions
- ✅ Enterprise messaging

## Development

### Prerequisites
- Python 3.11+
- Node.js 18+
- npm or yarn

### Setup

1. **Install Python dependencies:**
```bash
cd ai-audit-ci
pip install -r requirements.txt
```

2. **Install Node dependencies:**
```bash
npm run install:all
```

3. **Initialize database:**
```bash
cd api
python -m api.main
```

4. **Run all services:**
```bash
npm run dev:all
```

## Usage

### Run an Audit

```bash
cd ai-audit-ci
python -m audit.cli run --config examples/tabular/config.yml
```

### Upload Audit Evidence

Set environment variables:
```bash
export VERITY_API_KEY=your_api_key
export VERITY_API_URL=https://verityai-production.up.railway.app
```

Then run with upload:
```bash
python -m audit.cli run --config config.yml --upload
```

### GitHub Actions

Add to `.github/workflows/audit.yml`:
```yaml
name: AI Governance Audit (Verity)
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: |
          pip install verity-audit
          verity run --config verity.yml --upload
        env:
          VERITY_API_KEY: ${{ secrets.VERITY_API_KEY }}
          DATASET_URL: ${{ secrets.DATASET_URL }}  # For datasets not in repo
          GITHUB_SHA: ${{ github.sha }}
          GITHUB_REF_NAME: ${{ github.ref_name }}
          GITHUB_REPOSITORY: ${{ github.repository }}
```

**Note:** For datasets stored outside the repository (S3, GCS, etc.), see [CI/CD Dataset Patterns](docs/CI_DATASET_PATTERNS.md) for configuration options.

## API Endpoints

- `POST /v1/audits` - Upload audit evidence
- `GET /v1/audits/{audit_id}` - Retrieve audit
- `POST /auth/signup` - Create account
- `POST /auth/login` - Sign in
- `GET /dashboard/orgs/{org_id}/projects` - List projects
- `GET /dashboard/projects/{project_id}/audits` - Get audit history
- `GET /dashboard/projects/{project_id}/trends` - Get trend data

See `api/README.md` for full API documentation.

## License

Proprietary - All rights reserved