PolicyAware: Open-Source AI Gateway And Agent Control Plane
Add deny-by-default policy, PII redaction, MCP tool governance, model routing, runtime evaluation, local code scanning, and audit traces to Python AI applications before workflows reach production.
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
- Optional NeMo Guardrails and Guardrails AI orchestration
- Runtime evaluation, audit traces, and replay
- Local code scanning with HTML, JSON, SARIF, and Markdown reports
- LangChain and LlamaIndex callback governance
Installation
Install From PyPI
Use this lightweight base install for application development and normal usage:
pip install policyawareInstall optional integrations only when you need them:
pip install "policyaware[privacy]" # Presidio + spaCy
pip install "policyaware[guardrails]" # NeMo Guardrails + Guardrails AI
pip install "policyaware[providers]" # Provider extras
pip install "policyaware[all]" # All optional integrationsLocal Development
Use this while contributing from a cloned copy of the repository:
git clone https://github.com/ktirupati/policyaware.git
cd policyaware
pip install -e ".[dev]"Verify The Install
policyaware init
policyaware policy validate policyaware.yaml
policyaware dev simulate
policyaware risk classify "Review patient id ABCDE diagnosis: flu" --domain healthcare --autonomy agenticTry Repository Examples
From a cloned repository, you can run the bundled policy, tool, and evaluation examples:
policyaware policy validate examples/policies/basic.yaml
policyaware policy explain examples/policies/basic.yaml --prompt "Email jane@example.com"
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.yamlCopy-Paste Examples
- FastAPI LLM policy middleware
- LangChain policy guardrails
- MCP tool permission gateway
- PII redaction policy
- Regulated RAG assistant
- Provider routing by risk
- Audit trace viewer
- Approval workflow hooks
Search-Friendly Guides
- PolicyAware use-case guide index
- PolicyAware branding and standard icon
- Codex, Antigravity, Claude, Cursor, and Windsurf integration packs
- AI firewall for LLM agents
- MCP tool permission gateway
- Policy-as-code for LLMs
- Centralized YAML policy distribution with S3, GCS, ADLS, and HTTP
- PII redaction before LLM calls
- LLM token budget and cost controls
- LLM audit logging and OpenTelemetry
- FastAPI LLM policy middleware guide
- LangChain policy guardrails guide
- MCP tool permission gateway guide
- PII redaction for LLM apps guide
- Local code scan and HTML report guide
- NeMo Guardrails and Guardrails AI integrations
- LangChain and LlamaIndex callback integrations
- LangGraph agent node governance
- Haystack RAG and agent governance integration
- Microsoft AGT-style evidence export
- Smart integration recommender
- CLI usability commands
- Compliance-oriented policy packs
- Policy composition and hierarchical overrides
- HTTP sidecar gateway for non-Python services
- Dynamic policy distribution for many agents
- Stateful session governance for cumulative leakage
- Enterprise hardening primitives
- Policy rollout and trace correlation
- Grafana, Prometheus, and OpenTelemetry templates
- Official PolicyAware GitHub Action for CI/CD
- Policy contract checks for YAML/tool drift
- Security boundaries and sidecar enforcement
- GitHub Actions scan template
- Advanced PolicyAware policy CI/CD template
- Captured terminal output for runnable examples
- SEO and distribution checklist
Choosing The Right Category
If you are comparing guardrails, AI gateways, and model routers, read the PolicyAware comparison guide. If you are searching for Guardrails AI alternatives, LiteLLM alternatives, model router alternatives, or MCP governance tools, read the PolicyAware alternatives guide.
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 about
policyaware feedback
policyaware init
policyaware policy validate policyaware.yaml
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 scan . --out policyaware-scan-report.html
policyaware scan . --config examples/policyaware-scan.yaml --format html,json,sarif,markdown
policyaware scan . --diff --diff-base origin/main --fail-on high
policyaware audit view --traces-file .policyaware/traces.jsonl --out .policyaware/trace-viewer.htmlStarter Policy Initialization
Create a NIST-aligned deny-by-default starter policy with baseline privacy, tool governance, token budget, and agent-loop controls:
policyaware init
policyaware policy validate policyaware.yamlThe generated template includes PII/PHI/secrets handling, risky MCP/tool command blocking, approval requirements for side-effecting actions, token caps, and high-iteration agent approval rules.
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.htmlMetrics
policyaware observability prometheus
policyaware observability otel-jsonMore Documentation
Working Examples
Production Features
User Guide
Enterprise Readiness
Review enterprise governance controls and evidence artifacts
Security Model
Understand deny-by-default enforcement, tool governance, output evaluation, and scan boundaries
Examples Matrix
Microsoft AGT-Style Interop
Export PolicyAware decisions as agent-governance evidence JSON
Integration Strategy
Understand official, compatible, and optional integration language
Integration Recommender
Recommend the best integration from project signals and user needs
Dynamic Policy Distribution
Refresh central policy changes without redeploying every agent
Stateful Session Governance
Detect cumulative leakage and repeated tool activity across a session
Enterprise Hardening
Use SQLite state, emergency revokes, checksum pinning, and signed traces
Observability Templates
Connect traces and metrics to dashboards and compliance systems
Policy Contract Checks
Prevent drift between YAML policies and Python tool signatures
Security Boundaries
Choose embedded SDK mode or authenticated sidecar enforcement
Deploy from a branch, branch main, folder /docs.
Articles
PolicyAware vs Guardrails vs AI Gateways vs Model Routers
Build a Policy-Aware AI Gateway in Python
Stop Shipping AI Features Without Guardrails
Feedback And Testimonials
PolicyAware improves through real-world user feedback from AI platform, security, compliance, and engineering teams. Share what you built, which feature you used, what risk or governance gap it helped identify, and what should improve next.
Please do not share secrets, private prompts, PHI, PII, customer data, or confidential internal details.