PolicyAware AI Gateway

PyPI: policyaware | Downloads: Pepy stats | Python: 3.10+ | License: Apache-2.0 | Docs: GitHub Pages

PolicyAware adds deny-by-default policy, PII redaction, MCP tool governance, model routing, runtime evaluation, and audit traces to LLM, RAG, and AI agent applications in minutes.

PolicyAware AI Gateway is an open-source control plane for governed AI execution across enterprise LLM, RAG, AI agent, and MCP-style tool workflows. It enforces organizational, legal, security, cost, and routing policy before requests reach models or tools, then evaluates outputs for safety, quality, compliance, and auditability.

Documentation site: https://ktirupati.github.io/policyaware/

Capability docs: docs/capabilities.md Ready-to-use YAML policies: docs/capabilities/ready-to-use-yaml.md Comparison guide: PolicyAware vs guardrails vs AI gateway vs model router Alternatives guide: PolicyAware alternatives for guardrails, AI gateways, model routers, and MCP governance Demo outputs: captured terminal output for runnable examples Changelog: release history

What It Provides

• Policy enforcement for RBAC, context, tenant, region, compliance, budgets, tokens, latency, and model constraints.
• PII, PHI, secrets, and sensitive-data detection with redaction actions.
• Multi-provider model routing with fallbacks by policy, task type, risk, cost, availability, and quality.
• Runtime evaluation for safety, policy compliance, grounding, citations, and leakage.
• Risk-tier classification with explainable reason codes.
• MCP/tool governance for connector-level and action-level permissions.
• Optional NeMo Guardrails and Guardrails AI adapter orchestration for full-stack guardrails.
• Full request/response trace, explainable decisions, replay-ready audit logs, and exportable JSONL records.
• Python SDK, CLI, YAML policies, local development mode, and integration shims.
• Fast local code scanning with a user-friendly HTML governance report for PII, PHI, secrets, direct LLM calls, provider routing, tool governance, autonomous agents, RAG grounding, data residency, cost controls, policy YAML, configuration risks, and audit gaps.

Author

Created and maintained by Krishna Kishor Tirupati.

Project links:

• PyPI: policyaware
• GitHub: ktirupati/policyaware
• Documentation: PolicyAware AI Gateway Docs

Quick Start

pip install policyaware
policyaware dev simulate
policyaware risk classify "Email jane@example.com about a patient diagnosis" --domain healthcare
policyaware scan ./mylocalfolder
policyaware scan ./mylocalfolder --json policyaware-scan-report.json --fail-on high
policyaware scan ./mylocalfolder --sarif policyaware.sarif
policyaware scan ./mylocalfolder --markdown policyaware-scan-report.md
policyaware scan ./mylocalfolder --baseline policyaware-baseline.json
policyaware scan ./mylocalfolder --config examples/policyaware-scan.yaml
policyaware scan ./mylocalfolder --diff --diff-base origin/main
policyaware scan ./mylocalfolder --format html,json,sarif,markdown
policyaware guards list examples/full-stack-guardrails/policy.yaml

Optional full-stack guardrails:

pip install "policyaware[nemo]"
pip install "policyaware[guardrails-ai]"
pip install "policyaware[full]"

For local development from this repository:

pip install -e ".[dev]"
policyaware policy test examples/policies/basic.yaml
policyaware policy validate examples/policies/basic.yaml
policyaware risk classify "Summarize this patient diagnosis" --domain healthcare
policyaware tools check examples/policies/tool-governance.yaml --agent code_assistant --connector github --action create_pr
policyaware eval run examples/evals/support_rag.yaml
policyaware scan . --out policyaware-scan-report.html
policyaware scan . --include ".py,.yaml,.json" --exclude "tests,fixtures"
policyaware scan . --write-baseline policyaware-baseline.json
policyaware scan . --config examples/policyaware-scan.yaml --format html,json,sarif,markdown

For copy-pasteable end-to-end examples, see Working Examples.

Local code scan docs: policyaware scan

Copy-Paste Examples

• FastAPI LLM policy middleware: protect a FastAPI /chat endpoint with policy checks before model execution.
• LangChain policy guardrails: wrap a chain-style LLM call with deny-by-default policy, PII redaction, and secret blocking.
• MCP tool permission gateway: govern connector-level and action-level tool permissions for agent workflows.
• PII redaction policy: inspect and redact sensitive text before model execution.
• Regulated RAG assistant: require citations and stricter controls for healthcare-style RAG.
• Provider routing by risk: route public-safe requests to low-cost models and high-risk requests to approved models.
• Audit trace viewer: write audit traces and generate a local HTML trace viewer.
• Approval workflow hooks: send high-risk requests to approval instead of calling a model.
• Local code scan: scan local AI app code and generate an HTML governance report.
• Full-stack guardrails: orchestrate NeMo Guardrails, Guardrails AI, or custom validators as input/output guards.

Captured terminal output for the runnable examples is available in docs/demo-outputs.md.

Articles

• PolicyAware vs Guardrails vs AI Gateways vs Model Routers
• Build a Policy-Aware AI Gateway in Python
• Stop Shipping AI Features Without Guardrails

from policyaware import Gateway, GatewayRequest

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

response = gateway.chat(
    GatewayRequest(
        tenant="acme",
        app="claims-assistant",
        user={"id": "u_123", "role": "claims_adjuster"},
        context={"region": "us", "task_type": "summarization", "risk": "low"},
        messages=[{"role": "user", "content": "Summarize claim ACME-42."}],
    )
)

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

Architecture

Application / Agent / RAG App
        |
        v
PolicyAware SDK / Middleware
        |
        v
Identity + Context Resolver
        |
        v
Policy Decision Engine -> Data Protection Engine -> Model Router -> Provider/Tool
        |
        v
Runtime Evaluation -> Audit Trace -> Response

Repository Layout

src/policyaware/
  audit.py              Request traces and audit export records
  cli.py                policyaware CLI
  data_protection.py    PII/PHI/secret detection and redaction
  evals.py              Offline and runtime evaluation primitives
  gateway.py            Main SDK facade
  models.py             Core typed contracts
  policy.py             Deny-by-default policy engine
  providers.py          Provider abstraction and local simulated provider
  routing.py            Policy-aware model routing
  integrations/         FastAPI, Flask, LangChain, LlamaIndex shims
examples/
  policies/
  evals/
tests/

Policy Example

id: basic_enterprise_policy
default: deny

rules:
  - name: allow_low_risk_support
    effect: allow
    when:
      user.role_in: ["support_agent", "claims_adjuster"]
      request.risk_in: ["low", "medium"]
      data.contains_secrets: false

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

  - name: require_approval_for_high_risk
    effect: require_approval
    when:
      request.risk: "high"

Development Status

This is a production-grade starter framework: the core extension points and executable behavior are present, while provider integrations, enterprise identity adapters, dashboard UI, and long-term storage can be expanded by contributors.

v0.2 MVP Capabilities

• Deterministic risk classification: low, medium, high, critical.
• Explainable policy decisions with reason codes and remediation.
• Replayable audit trace snapshots.
• Audit bundle generation.
• Tool governance policies for MCP-style connectors and actions.
• Governance-aware eval report schema.
• Provider adapters for OpenAI-compatible APIs, Azure OpenAI, Anthropic, Bedrock, Vertex AI, Ollama, and vLLM.
• Optional ML signal integrations for Presidio PII detection, ProtectAI prompt-injection detection, and custom Transformers domain/risk classifiers.
• Optional NeMo Guardrails and Guardrails AI adapters for full-stack guardrail orchestration.
• Fast local code scanner and HTML recommendation report.
• SQLite audit storage and static trace viewer.
• Prometheus text and OpenTelemetry-shaped JSON exporters.
• File and webhook approval hooks.
• Executable golden dataset policy checks.

Third-Party ML Models

Optional ML integrations may download third-party models at runtime. PolicyAware does not bundle model weights. Review and accept the license or access terms for any model you configure, especially gated Hugging Face models.

Recommended GitHub Topics

For discovery, use repository topics such as llm, ai-gateway, llm-governance, guardrails, rag, mcp, ai-agents, pii-redaction, model-routing, audit, python, and open-source.

License

Apache-2.0