Metadata-Version: 2.4
Name: precept-ai-sdk
Version: 0.1.0
Summary: Pre-embedding data governance layer for AI systems
Home-page: https://github.com/precept-ai/precept-sdk
Author: Ayodele David
Author-email: davidayo2603@gmail.com
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 :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: spacy>=3.7.0
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Precept SDK

**The pre-embedding data governance layer for AI systems.**

Precept sits between your raw data and AI memory â€” enforcing security, privacy, and compliance rules before anything gets embedded into a vector database.

## Installation

```bash
pip install -e .
python -m spacy download en_core_web_sm
```

## Quick Start

```python
from precept import PreceptGuard

# Initialize with a policy
guard = PreceptGuard(policy='gdpr')

# Sanitize text before embedding
result = guard.sanitize('John Doe email is john@test.com phone 08012345678')

print(result.clean_text)
# Output: 'PERSON_1 email is EMAIL_1 phone PHONE_1'

print(result.detections)
# List of Detection objects showing what was found and replaced

print(result.compliance_status)
# {'gdpr': True}

print(result.tokens_consumed)
# Word count of the processed text

print(result.audit_id)
# UUID for this sanitization event
```

## Policies

Precept ships with pre-built compliance policy presets:

| Policy | What It Redacts | Bias Mode | Quality |
|--------|----------------|-----------|---------|
| `pii` | Names, emails, phones, SSNs, credit cards, IPs | Off | Off |
| `gdpr` | All PII + dates + proprietary terms | Flag | On |
| `hipaa` | All 18 PHI categories (names, dates, SSNs, emails, phones, etc.) | Remove | On |
| `ndpr` | GDPR-equivalent + Nigerian ID patterns (NIN, BVN) | Flag | On |

### Using a single policy

```python
guard = PreceptGuard(policy='hipaa')
result = guard.sanitize(clinical_note)
```

### Using multiple policies

```python
guard = PreceptGuard(policies=['gdpr', 'hipaa'])
result = guard.sanitize(document)
# result.compliance_status -> {'gdpr': True, 'hipaa': True}
```

### Custom proprietary terms

```python
guard = PreceptGuard(
    policy='gdpr',
    custom_terms=['Project Apollo', 'Operation X', 'AcmeCorp']
)
result = guard.sanitize('The Project Apollo launch is scheduled for Q3.')
# 'Project Apollo' replaced with 'PROPRIETARY_1'
```

### Multi-tenant access control

```python
guard = PreceptGuard(policy='gdpr', tenant_id='customer_123')
result = guard.sanitize(document)
# result.clean_text ends with [PRECEPT_TENANT: <hash>]
# result.tenant_tag contains the 16-char SHA256 hash
```

### Bias detection

GDPR and NDPR policies flag biased sentences; HIPAA removes them:

```python
guard = PreceptGuard(policy='hipaa')
result = guard.sanitize('The patient recovered well. A nurse used a slur.')
# Sentence with slur is removed in HIPAA mode (bias_mode='remove')
print(result.bias_flags)  # List of flagged sentences
```

### Data quality checks

Quality checks run automatically with GDPR, HIPAA, and NDPR policies:

```python
guard = PreceptGuard(policy='gdpr')
result = guard.sanitize('')
print(result.is_safe)           # False â€” empty text
print(result.quality_report)    # QualityReport with details
```

## API Key (Optional in Phase 1)

If you have a Precept API key, pass it to enable usage tracking:

```python
guard = PreceptGuard(api_key='prct_live_xxxx', policy='gdpr')
```

Without an API key, the SDK works fully offline â€” all detection and redaction happens locally.

## Running Tests

```bash
pip install -e ".[dev]"
python -m spacy download en_core_web_sm
pytest tests/ -v
```

## Project Structure

```
precept-sdk/
  precept/
    __init__.py          # Public API â€” exports PreceptGuard
    guard.py             # Core PreceptGuard class
    models.py            # Pydantic data models
    client.py            # HTTP client for API calls
    detectors/
      pii.py             # PII detection (spaCy + regex)
      proprietary.py     # Proprietary term detection
      bias.py            # Bias and toxicity detection
      quality.py         # Data quality checks
      access.py          # Multi-tenant access control
      data/
        bias_terms.txt   # Curated bias term wordlist
    policies/
      base.py            # Base policy class
      gdpr.py            # GDPR policy preset
      hipaa.py           # HIPAA policy preset
      ndpr.py            # NDPR policy preset
  tests/
    test_guard.py        # Guard integration tests
    test_pii.py          # PII detector unit tests
    test_all_modules.py  # Bias, quality, access, full pipeline tests
  setup.py
  README.md
```

## Dependencies

- `spacy>=3.7.0` + `en_core_web_sm` model
- `pydantic>=2.0`
- `httpx>=0.24`

## Phase 1 â€” What's Built

- PII detection and redaction (names, emails, phones, SSNs, credit cards, IPs, dates)
- Proprietary term detection with custom term lists
- GDPR, HIPAA, and NDPR compliance policy presets
- Semantic placeholder replacements (PERSON_1, EMAIL_1, etc.)
- Local audit ID generation
- Stub API client (fully connected in Phase 2)

## Phase 4 â€” What's New

- **Bias detection**: Curated wordlist matching for discriminatory terms with flag/remove modes
- **Data quality checks**: Empty text, too-short, encoding errors, duplicate detection (session-scoped)
- **Multi-tenant access control**: SHA256 tenant tagging, isolation verification
- **Extended SanitizeResult**: `is_safe`, `quality_report`, `bias_flags`, `tenant_tag` fields
- **Updated policy presets**: GDPR/NDPR flag bias, HIPAA removes bias, all run quality checks
- **Full pipeline**: Quality â†’ PII â†’ Proprietary â†’ Bias â†’ Access control in one `sanitize()` call
