PolicyAware AI Gateway

Governed AI execution for LLMs, RAG, agents, and tools.

PolicyAware is an open-source Python framework that checks prompts, request context, policies, model routing, tool calls, model responses, and audit traces before AI behavior becomes business behavior.

Start with installation View repository

What It Does

  • Deny-by-default YAML policy enforcement
  • PII, PHI, secrets, and sensitive data checks
  • Risk classification and explainable decisions
  • Model routing across real providers and local models
  • MCP/tool governance and approval hooks
  • Runtime evaluation, audit traces, and replay

Installation

Local Development

Use this while working from a cloned copy of the repository:

git clone https://github.com/ktirupati/policyaware.git
cd policyaware
pip install -e ".[dev]"

Future PyPI Install

After the package is published to PyPI, users can install it with:

pip install policyaware

For optional Bedrock support:

pip install "policyaware[providers]"

Verify The Install

policyaware dev simulate
policyaware policy validate examples/policies/basic.yaml
policyaware policy explain examples/policies/basic.yaml --prompt "Email jane@example.com"
policyaware risk classify "Review patient id ABCDE diagnosis: flu" --domain healthcare --autonomy agentic
policyaware tools check examples/policies/tool-governance.yaml --agent code_assistant --connector github --action create_pr
policyaware eval run examples/evals/executable_governance_cases.yaml --policy-file examples/policies/basic.yaml

What PolicyAware Checks

Area Checked Examples Possible Outcome
User prompts / messages PII, PHI, secrets, API keys, emails, phone numbers, sensitive business text Deny, redact, classify as higher risk, or allow
Request context User role, tenant, region, task type, risk level, domain, autonomy level Apply RBAC, tenant isolation, region restrictions, or approval requirements
YAML policies basic.yaml, regulated-rag.yaml, tool-governance.yaml Produce allow, deny, conditional_allow, or require_approval decisions
Tool calls Connector name, action name, user role, arguments, approval requirements Allow read actions, deny destructive actions, require approval for writes
Model responses Sensitive data leakage, citation requirements, policy consistency Flag eval failures, record safety scores, and produce audit evidence

Working Examples

Python SDK

from policyaware import Gateway, GatewayRequest

gateway = Gateway.from_policy_file("examples/policies/basic.yaml")

response = gateway.chat(
    GatewayRequest(
        tenant="acme",
        app="support-copilot",
        user={"id": "u_123", "role": "support_agent"},
        context={
            "region": "us",
            "task_type": "support",
            "risk": "low",
            "domain": "support",
        },
        messages=[
            {"role": "user", "content": "Email jane@example.com about the claim."}
        ],
    )
)

print(response.policy.decision)
print(response.policy.risk_tier)
print(response.policy.reason_codes)
print(response.trace_id)

Policy Rule

id: basic_enterprise_policy
default: deny

rules:
  - name: block_secrets
    effect: deny
    when:
      data.contains_secrets: true

  - name: redact_pii_for_non_privileged_users
    effect: transform
    action: redact
    when:
      data.contains_pii: true
      user.role_not_in: ["privacy_admin", "compliance_officer"]

CLI Examples

policyaware policy validate examples/policies/basic.yaml
policyaware policy explain examples/policies/basic.yaml --role support_agent --prompt "Email jane@example.com"
policyaware policy explain examples/policies/basic.yaml --role developer --prompt "Use secret_api_key_abcdefghijklmnop"
policyaware audit view --traces-file .policyaware/traces.jsonl --out .policyaware/trace-viewer.html

Provider Adapters

PolicyAware supports real provider adapters while keeping the local simulated provider for development.

Cloud

Azure OpenAI, Anthropic, Amazon Bedrock, Vertex AI

Local

Ollama and vLLM

Generic

OpenAI-compatible chat completion APIs

from policyaware import Gateway, AzureOpenAIProvider, ProviderRegistry

gateway = Gateway.from_policy_file("examples/policies/basic.yaml")
gateway.provider_registry = ProviderRegistry({
    "azure-openai": AzureOpenAIProvider(
        endpoint="https://your-resource.openai.azure.com",
        api_key="YOUR_KEY",
    )
})

Audit, Observability, And Evals

Audit Storage

from policyaware.audit import SQLiteAuditLogger

gateway.audit_logger = SQLiteAuditLogger(".policyaware/audit.db")

Trace Viewer

policyaware audit view-sqlite \
  --db .policyaware/audit.db \
  --out .policyaware/trace-viewer.html

Metrics

policyaware observability prometheus
policyaware observability otel-json

More Documentation

Working Examples

Open the Markdown examples guide

Production Features

Open the production feature guide

User Guide

Download the Word user guide

GitHub Pages setup: In repository settings, set Pages source to Deploy from a branch, branch main, folder /docs.