GovernAI Python SDK

Dependency-light, local-first Python SDK for AI governance, auditability, and policy enforcement.

What is GovernAI?

GovernAI is a Python SDK that adds governance, auditability, and policy enforcement to AI-powered applications. It tracks every AI operation — recording hashes, risk scores, policy decisions, and timing — without storing raw prompts or responses by default.

GovernAI runs fully in-process with zero external dependencies. No cloud account, no API key, and no infrastructure are needed to get started.

What GovernAI is NOT

• Not a firewall or a content filter that can fully block all malicious prompts.
• Not a replacement for responsible AI practices or human review.
• Not an AI provider — it wraps your existing AI calls.
• Not dependent on any cloud platform, AI vendor, or observability service.

Requirements

• Python 3.10 or later
• No external package dependencies (standard library only)

Packages

Installation

Install from source (editable):

pip install -e .

Or install individual packages once published:

pip install governai

Quick Start

Minimal — track an AI call

import asyncio
from governai.abstractions.models import GovernAIContext
from governai.core.options import GovernAIOptions
from governai.core.runtime import GovernAIRuntime
from governai.core.exporters import ConsoleExporter

async def main() -> None:
    options = GovernAIOptions(
        application_name="MyApp",
        environment_name="development",
    )
    runtime = GovernAIRuntime(options=options, exporter=ConsoleExporter())

    context = GovernAIContext(
        application_name="MyApp",
        environment_name="development",
        operation_name="SummariseDocument",
        prompt="Summarise this document.",
    )

    response = await runtime.track_async(
        context,
        lambda: my_ai_provider_call_async("Summarise this document."),
    )
    print(response)

asyncio.run(main())

WSGI Integration

from governai.wsgi import GovernAIConfig, GovernAIMiddleware

config = GovernAIConfig(
    application_name="Enterprise.Api",
    environment_name="production",
)

app = GovernAIMiddleware(wsgi_app=your_wsgi_app, config=config)

Run with Python's built-in server:

from wsgiref.simple_server import make_server

with make_server("0.0.0.0", 8000, app) as server:
    server.serve_forever()

With Security — PII Redaction and Local Policy

from governai.core.runtime import GovernAIRuntime
from governai.core.options import GovernAIOptions
from governai.core.exporters import ConsoleExporter
from governai.security.policy import DefaultLocalPolicyEvaluator
from governai.security.redaction import BasicPiiRedactor
from governai.wsgi import GovernAIConfig, GovernAIMiddleware

redactor = BasicPiiRedactor()
prompt = redactor.redact("My email is user@example.com")

options = GovernAIOptions(application_name="SecureApp", environment_name="production")
runtime = GovernAIRuntime(
    options=options,
    exporter=ConsoleExporter(),
    policy_evaluator=DefaultLocalPolicyEvaluator(),
)
config = GovernAIConfig(application_name="SecureApp", runtime=runtime)
app = GovernAIMiddleware(wsgi_app=your_wsgi_app, config=config)

Security and Privacy Defaults

GovernAI never reads the HTTP request body. It never logs Authorization, Cookie, or other sensitive headers.

Warning: The heuristic PII redactor and prompt injection scanner do not guarantee complete protection. They reduce accidental exposure but are not a substitute for a dedicated DLP or content-safety system.

Correlation IDs

GovernAIMiddleware automatically generates a X-Correlation-Id for every request. If the inbound request already carries this header, the existing value is reused. The correlation ID is:

• Added to the WSGI environ as governai.correlation_id.
• Appended to every response as a X-Correlation-Id header.
• Included in every governance event exported by the runtime.

Samples

Extending GovernAI

Implement any of the protocols in governai.abstractions to plug in custom behaviour:

Persisting events to a database or custom destination

Every governance event is delivered to whichever GovernAIExporter you configure. To persist events to a database, a message queue, a remote API, or any other store, implement the GovernAIExporter protocol — it requires only one async method:

import asyncio
from governai.abstractions.models import GovernAIEvent

class MyDatabaseExporter:
    """Persist GovernAI events to a database of your choice."""

    async def export_async(self, event: GovernAIEvent) -> None:
        # Replace the body below with any storage backend:
        # psycopg2 (PostgreSQL), pyodbc (SQL Server), pymongo (MongoDB),
        # boto3 (DynamoDB), aiohttp (REST API), etc.
        await asyncio.to_thread(self._write, event)

    def _write(self, event: GovernAIEvent) -> None:
        # example: write one row to a relational database
        # con.execute(
        #     "INSERT INTO ai_events (event_id, operation, decision, risk, duration_ms)"
        #     " VALUES (?, ?, ?, ?, ?)",
        #     (event.event_id, event.operation_name,
        #      event.policy_decision.value if event.policy_decision else None,
        #      event.risk_level.value if event.risk_level else None,
        #      event.duration_ms),
        # )
        pass

Wire it in at startup:

from governai.core.runtime import GovernAIRuntime
from governai.core.options import GovernAIOptions

runtime = GovernAIRuntime(
    options=GovernAIOptions(application_name="MyApp"),
    exporter=MyDatabaseExporter(),
)

Combine multiple exporters to write to several destinations at once — for example, buffer events in memory for a live UI feed while also persisting them to a database:

from governai.core.exporters import CompositeExporter, InMemoryExporter

mem = InMemoryExporter(capacity=200)   # used by /events UI endpoint
db  = MyDatabaseExporter()

runtime = GovernAIRuntime(
    options=GovernAIOptions(application_name="MyApp"),
    exporter=CompositeExporter([mem, db]),
)

CompositeExporter fans out every event to all exporters. If one fails, the others continue; set fail_on_error=True only if a failed export should be treated as fatal.

Key fields available on every GovernAIEvent:

Architecture

GovernAI is designed as a local-first MVP with a clear extension path:

[Your App]
    │
    ▼
GovernAIMiddleware (WSGI)
    │
    ▼
GovernAIRuntime ──► GovernAIPolicyEvaluator (local or remote)
    │
    ▼
GovernAIExporter ──► Console / InMemory / File / (future: Collector)

Future phases will add:

• GovernAI Collector — aggregated event collection service
• Remote Policy Server — centralised policy evaluation
• OpenTelemetry — trace and metric export
• Dashboard — governance observability UI

See docs/architecture.md and docs/roadmap.md for details.

Contributing

1. Clone the repository.
2. Create and activate a virtual environment:

   python -m venv .venv
   .venv\Scripts\activate   # Windows
   source .venv/bin/activate # macOS/Linux
   

3. Install in editable mode:

   pip install -e .
   

4. Run tests:

   python -m unittest discover tests -v
   

See CONTRIBUTING.md for full guidelines.

License

MIT