Metadata-Version: 2.4
Name: moss-edge-classifier
Version: 0.1.0
Summary: MOSS Edge Classifier - On-device policy evaluation and audit logging
Author-email: MOSS Computing <engineering@mosscomputing.com>
License: Proprietary
Keywords: ai,governance,compliance,edge-computing,post-quantum
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pynacl>=1.5.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# MOSS Edge Classifier

On-device policy evaluation and audit logging for AI agent governance.

## Overview

The Edge Classifier enables **offline-first AI governance** by:
- Downloading signed policy bundles from MOSS
- Evaluating policies locally on user devices
- Classifying data (PII detection, keyword matching)
- Buffering audit events and syncing to MOSS
- Operating offline with a configurable grace period
- Verifying ML-DSA-44 post-quantum signatures

## Installation

```bash
pip install moss-edge-classifier
```

## Quick Start

```python
from moss_edge_classifier import EdgeClassifier

# Initialize with your customer API key
classifier = EdgeClassifier(
    api_key="cust_key_xyz...",
    base_url="https://api.mosscomputing.com",
    offline_grace_period_hours=24,
)

# Download and verify policy bundle
await classifier.refresh_bundle()

# Evaluate an action
decision = await classifier.evaluate(
    agent_id="agent_123",
    action_type="chat",
    input_text="What is the user's SSN?",
    output_text="I cannot share SSN information.",
    context={"user_id": "user_456"},
)

print(decision.allowed)  # True/False
print(decision.policies_evaluated)  # ['pol_pii_block', 'pol_chat_allow']
print(decision.classifications)  # {'input': ['pii_detected'], 'output': []}
```

## Features

### Policy Evaluation
- Downloads cryptographically-signed policy bundles
- Evaluates rules locally (no network latency)
- Handles complex policy conditions (capabilities, data classifications)

### Data Classification
- **PII Detection**: SSN, credit cards, email, phone numbers (regex-based)
- **Keyword Matching**: Custom sensitive terms per organization
- Extensible classification framework

### Offline Mode
- Continues working when MOSS API is unreachable
- Configurable grace period (default: 24 hours)
- Automatic bundle refresh on reconnection

### Audit Logging
- Buffers audit events locally
- Syncs to MOSS in batches (max 100 per request)
- Idempotent sync (duplicate detection via envelope_id)
- Local ML-DSA-44 signatures on audit entries

### Post-Quantum Security
- Verifies bundle signatures using ML-DSA-44
- Downloads MOSS public keys from /v1/keys/signing
- Rejects tampered or unsigned bundles

## API Reference

### EdgeClassifier

```python
class EdgeClassifier:
    def __init__(
        self,
        api_key: str,
        base_url: str = "https://api.mosscomputing.com",
        offline_grace_period_hours: int = 24,
        max_audit_buffer: int = 1000,
    ):
        """Initialize Edge Classifier.

        Args:
            api_key: Customer API key (starts with cust_key_)
            base_url: MOSS API base URL
            offline_grace_period_hours: Hours to operate offline
            max_audit_buffer: Max audit events before forced sync
        """
```

#### Methods

**`refresh_bundle()`**
Downloads the latest policy bundle from MOSS and verifies the signature.

```python
await classifier.refresh_bundle()
```

**`evaluate()`**
Evaluates an action against loaded policies.

```python
decision = await classifier.evaluate(
    agent_id="agent_123",
    action_type="chat",
    input_text="...",
    output_text="...",
    context={},
)
```

Returns `EvaluationDecision` with:
- `allowed: bool` - Whether action is permitted
- `decision: str` - "allow", "block", or "require_approval"
- `policies_evaluated: list[str]` - Policy IDs checked
- `classifications: dict` - Input/output classifications
- `bundle_version: int` - Policy bundle version used

**`sync_audit()`**
Syncs buffered audit events to MOSS.

```python
result = await classifier.sync_audit()
# Returns: {"synced": ["env_001", ...], "failed": [], "chainPosition": 42}
```

**`get_revocations()`**
Fetches emergency revocation list from MOSS.

```python
revocations = await classifier.get_revocations()
# Returns: {"revocations": [...], "revocationListId": "rvk_xyz"}
```

## Architecture

```
┌─────────────────────────────────────────────┐
│ AI Agent Application                         │
│  ┌────────────────────────────────────────┐ │
│  │ EdgeClassifier                          │ │
│  │  • Policy Bundle (cached locally)       │ │
│  │  • Signing Keys (cached)                │ │
│  │  • Audit Buffer (SQLite)                │ │
│  │  • Classification Rules                 │ │
│  └────────────────────────────────────────┘ │
│           ▲                      │           │
│           │ Download bundle      │ Sync audit│
│           │ (signed)             │ (batched) │
└───────────┼──────────────────────┼───────────┘
            │                      │
            │    HTTPS (TLS 1.3)   │
            │                      ▼
┌───────────┴──────────────────────────────────┐
│ MOSS API (https://api.mosscomputing.com)     │
│  • GET /v1/customer/policy-bundles/latest    │
│  • GET /v1/keys/signing                      │
│  • POST /v1/customer/audit/sync              │
│  • GET /v1/customer/policy-revocations       │
└──────────────────────────────────────────────┘
```

## Security Model

1. **Bundle Integrity**: All policy bundles are signed with ML-DSA-44
2. **Key Rotation**: Automatic key refresh from MOSS signing key endpoint
3. **Tamper Detection**: Rejects bundles with invalid signatures
4. **Offline Safety**: Grace period prevents indefinite offline operation
5. **Audit Integrity**: Local signatures on audit entries before sync

## Configuration

Environment variables:
```bash
MOSS_API_KEY=cust_key_...
MOSS_BASE_URL=https://api.mosscomputing.com
MOSS_OFFLINE_GRACE_HOURS=24
MOSS_MAX_AUDIT_BUFFER=1000
MOSS_CACHE_DIR=~/.moss/cache
```

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Type checking
mypy moss_edge_classifier/

# Linting
ruff check moss_edge_classifier/
```

## License

Proprietary - MOSS Computing, Inc.

## Support

- Documentation: https://docs.mosscomputing.com
- Email: support@mosscomputing.com
- GitHub Issues: https://github.com/mosscomputing/moss-edge-classifier/issues
