GovernsAI is the AI governance layer where policy actually enforces. This service is the enforcement engine: it reads the per-org policy from the dashboard, runs PII detection (Presidio + regex), applies network-scope and tool-deny rules, and returns an allow, transform, or deny decision on every prompt, tool call, and response — without a redeploy.
Fully Open Source (MIT) — use it, modify it, host it. No restrictions.
- Policy Evaluation: Real-time evaluation of AI tool usage against configurable policies
- PII Detection & Redaction: Advanced PII detection using Microsoft Presidio with regex fallback
- API Key Authentication: Secure API key-based authentication
- Rate Limiting: Redis-based rate limiting (optional)
- Database Storage: SQLAlchemy-based storage with PostgreSQL/SQLite support
- Docker Support: Production-ready Docker containerization
-
Install dependencies:
pip install -r requirements.txt python -m spacy download en_core_web_sm
-
Run the service:
python start.py # or uvicorn app.main:app --reload --host 0.0.0.0 --port 8080 -
Test the service:
curl -X GET http://localhost:8080/api/v1/health
-
Build the image:
docker build -t governsai-precheck . -
Run the container:
docker run -p 8080:8080 governsai-precheck
GET /api/v1/healthReturns service status and version information.
POST /api/v1/precheck
X-Governs-Key: your-api-key
Content-Type: application/json
{
"tool": "web.fetch",
"scope": "net.external",
"raw_text": "Please fetch data from https://example.com for user@example.com",
"tags": ["research"],
"corr_id": "req-123"
}Response:
{
"decision": "transform",
"payload": {
"url": "https://example.com",
"email": "u***@example.com"
},
"reasons": ["pii.redacted:email"],
"policy_id": "net-redact-presidio",
"ts": 1703123456
}POST /api/v1/postcheck
X-Governs-Key: your-api-key
Content-Type: application/jsonSimilar to precheck but for post-execution validation.
The service can be configured via environment variables:
| Variable | Default | Description |
|---|---|---|
APP_BIND |
0.0.0.0:8080 |
Server bind address |
DB_URL / DATABASE_URL |
sqlite:///./local.db |
Database connection URL |
USE_PRESIDIO |
true |
Enable Presidio PII detection |
PRESIDIO_MODEL |
en_core_web_sm |
spaCy model for Presidio |
PRESIDIO_LANGUAGES |
en |
Analyzer languages, comma-separated. See Detection languages |
PRESIDIO_LANGUAGE_MODE |
hint |
hint: caller's language, else the first configured; union: every configured language |
WEBHOOK_URL |
None |
Webhook URL for dashboard events |
WEBHOOK_SECRET |
dev-webhook-secret-change-in-production |
Outbound webhook HMAC key |
PII_TOKEN_SALT |
dev-pii-token-salt-change-in-production |
PII tokenization salt |
KEY_HMAC_SECRET |
dev-key-hmac-secret-change-in-production |
API-key hashing secret |
PRECHECK_DLQ |
/tmp/precheck.dlq.jsonl |
Dead letter queue file path |
POLICY_STORE_FAIL_MODE |
redact |
Policy store unreachable and no cached org policy: redact PII under a built-in policy, or deny. The request's policy_config is never used instead |
The service uses Microsoft Presidio for advanced PII detection with the following capabilities:
- Email addresses: Detected and masked
- Phone numbers: International format detection and masking
- Credit cards: Luhn algorithm validation and masking
- API keys: Custom patterns for various API key formats
- JWT tokens: Detection and redaction
- SSN: US Social Security Number detection
- IP addresses: IPv4/IPv6 detection
If Presidio fails to initialize, the service falls back to regex-based detection for basic PII types (email, phone, credit card).
The image ships spaCy models for English, Spanish, French, German and Chinese, but only English is loaded by default. With English only, text in other languages is analysed by the English model: it misses noticeably more PII and redacts words in clean text. If any traffic is not in English, enable the other models:
PRESIDIO_LANGUAGES=en,es,fr,de,zhCallers pick the language per request with tool_config.metadata.language
(hint mode). Each model is held in memory, so size the instance for the
languages you enable (resident memory of one worker, approximate):
PRESIDIO_LANGUAGES |
Memory |
|---|---|
en |
~170 MB |
en,es |
~230 MB |
en,es,fr,de |
~580 MB |
en,es,fr,de,zh |
~1 GB |
English-only fits a 512 MB instance; all five languages need about 2 GB. English stays the default so small instances do not run out of memory at boot, but it is never silent. At startup the service logs the loaded languages and warns when:
PRESIDIO_LANGUAGESwas left at its English-only default (set it explicitly, even toen, to record the choice and clear the warning);- a configured language's model is not installed (that language is skipped);
- Presidio failed to load and detection is regex-only.
A request that hints a language that is not loaded is logged once per
language. Outside the image, make install-multilingual downloads the
non-English models.
The service emits fire-and-forget webhook events for all precheck and postcheck decisions to enable dashboard integration and audit logging.
{
"userId": "user123",
"tool": "web.fetch",
"scope": "net.external",
"decision": "transform",
"policyId": "net-redact-presidio",
"reasons": ["pii.redacted:email"],
"payloadHash": "sha256_hash_of_payload",
"latencyMs": 45,
"timestamp": 1703123456,
"correlationId": "req-123",
"tags": ["research"],
"direction": "precheck"
}- Set
WEBHOOK_URLenvironment variable to enable webhook emission - Failed webhook deliveries are written to DLQ file (configurable via
PRECHECK_DLQ) - Webhook includes retry logic with exponential backoff (0.5s, 1s, 2s)
Use the provided webhook test URL for development:
export WEBHOOK_URL="https://webhook-test.com/1508b1ea2414ed242d2b8abf6ea66616"The following tools are automatically denied:
python.execbash.execcode.execshell.exec
Tools with network scope or web/http prefixes trigger PII redaction:
web.*http.*fetch.*request.*net.*scope
# Install development dependencies
pip install -r requirements-dev.txt
# Download spaCy model
python -m spacy download en_core_web_smpytest tests/Seed or reactivate a test API key in your local database, then run the k6 script:
python scripts/seed_test_api_key.py --key GAI_local_load_test_key --user-id load-test-user --org-id load-test-org
PRECHECK_API_KEY=GAI_local_load_test_key make load-testThe load test targets POST /api/v1/precheck at 100 req/s for 30s and spreads
requests across synthetic user_id values so the aggregate traffic does not trip
the service's per-user rate limiter.
black app/ tests/
isort app/ tests/mypy app/- Bind to
0.0.0.0:8080 - Use PostgreSQL database
- Use Redis for rate limiting
- Set
PUBLIC_BASEfor external access
- Bind to
127.0.0.1:7071 - Use SQLite database
- Optional Redis
- Local development setup
MIT License - Fully open source, no restrictions.
- ✅ Use in production - Deploy for your organization
- ✅ Host as a service - Offer "Precheck-as-a-Service" to customers
- ✅ Modify freely - Customize for your needs
- ✅ Bundle with products - Integrate into your software
- ✅ No attribution required - Use without mentioning GovernsAI (though we'd appreciate it!)
We want Precheck to become the standard for AI governance. Making it fully open source (not just source-available) means:
- No legal friction for enterprise adoption
- Can be integrated into any project (open or proprietary)
- Community can build on and extend it
- You can run it anywhere, anytime, for any purpose
See LICENSE file for full legal text.
Precheck is the core of the GovernsAI ecosystem:
- Precheck Service (this package) - MIT (fully open source)
- TypeScript SDK - MIT
- Browser Extension - MIT
- Platform Console - ELv2 (source-available for self-hosting)
Learn more: GovernsAI Licensing