pygenguard 0.1.0

Runtime security and governance framework for GenAI systems

PyGenGuard

Runtime security and governance framework for GenAI systems.

PyGenGuard enforces trust, intent, cost, and compliance policies before and after model execution. It sits between your application and the LLM, acting as a deterministic security layer.

---

What problem does this solve?

GenAI systems face unique security challenges:

• Prompt injection: Users bypassing system instructions
• Privilege escalation: "Ignore previous instructions" attacks
• Session hijacking: Attackers taking over authenticated sessions
• Denial-of-wallet: Token flooding to drain API budgets
• Compliance violations: PII leakage, unaudited decisions

PyGenGuard blocks these threats with deterministic, offline-capable checks.

---

Where does it sit in my system?

┌─────────────────────────────────────────────────────────────────┐
│                         Your Application                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        PyGenGuard.inspect()                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│  │ Identity │→│  Intent  │→│ Context  │→│Economics │→│Comply  │ │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
              ┌─────────┐         ┌─────────┐
              │  ALLOW  │         │  BLOCK  │
              │   ↓     │         │   ↓     │
              │  LLM    │         │ Safe    │
              │  API    │         │ Response│
              └─────────┘         └─────────┘

---

Installation

pip install pygenguard

Requirements: Python 3.9+
Dependencies: None (pure Python stdlib)

---

Quickstart (5 minutes)

from pygenguard import Guard, Session

# 1. Create a guard with your preferred mode
guard = Guard(mode="balanced")  # Options: strict, balanced, permissive

# 2. Create a session from your request context
session = Session.create(
    user_id="user_123",
    ip_address="192.168.1.1",
    user_agent="Mozilla/5.0..."
)

# 3. Inspect every prompt before sending to LLM
decision = guard.inspect(
    prompt=user_input,
    session=session
)

# 4. Act on the decision
if decision.allowed:
    response = call_llm(user_input)
else:
    response = decision.safe_response
    # decision.rationale contains the reason

With FastAPI

from fastapi import FastAPI, Request
from pygenguard import Guard, Session

app = FastAPI()
guard = Guard(mode="strict")

@app.post("/chat")
async def chat(request: Request, body: ChatRequest):
    session = Session.from_request(request, user_id=body.user_id)
    
    decision = guard.inspect(body.prompt, session)
    
    if not decision.allowed:
        return {"response": decision.safe_response, "blocked": True}
    
    # Safe to call LLM
    return {"response": await call_llm(body.prompt)}

---

Security Planes

PyGenGuard evaluates every request through 5 security planes (in order):

Plane	Purpose	Blocks On
Identity	Session fingerprint + trust scoring	Fingerprint drift, low trust score
Intent	Cognitive threat detection	Privilege escalation, coercion, authority spoofing
Context	Multi-turn attack detection	Split payloads, instruction poisoning
Economics	Token burn-rate limiting	Denial-of-wallet patterns
Compliance	PII detection + audit logging	Never blocks, only annotates

---

Configuration

All configuration is code-based (no YAML files):

guard = Guard(
    mode="strict",                              # Preset mode
    trust_thresholds={"full": 80, "degraded": 50},  # Custom identity thresholds
    intent_sensitivity=0.3,                     # Lower = stricter
    max_burn_rate=500.0,                        # Tokens/sec limit
    audit_enabled=True                          # JSON audit logging
)

Mode Presets

Mode	Trust Thresholds	Intent Sensitivity	Burn Rate
strict	full: 80, degraded: 50	0.3	500
balanced	full: 70, degraded: 40	0.5	1000
permissive	full: 50, degraded: 20	0.7	2000

---

The Decision Object

Every inspect() call returns an immutable Decision:

decision = guard.inspect(prompt, session)

decision.allowed          # bool: Can we proceed?
decision.action           # "ALLOW" | "BLOCK" | "DEGRADE" | "CHALLENGE"
decision.rationale        # Human-readable reason
decision.safe_response    # Pre-built response for blocked requests
decision.trace_id         # UUID for audit trail
decision.plane_results    # Per-plane breakdown
decision.to_dict()        # JSON-serializable for logging

---

What PyGenGuard Does NOT Do

• ❌ No ML model inference — All checks are rule-based and deterministic
• ❌ No network calls — Works fully offline
• ❌ No content generation — Only inspection and blocking
• ❌ No output filtering — v0.1 is input-only (output guards in v0.3)
• ❌ No multimodal — Text-only in v0.1 (image/audio in v0.3)

---

Audit Logging

Every decision is logged as structured JSON:

{
  "event": "security_decision",
  "trace_id": "abc-123",
  "timestamp": "2026-01-06T09:30:00Z",
  "allowed": false,
  "action": "BLOCK",
  "rationale": "Intent analysis failed: Privilege escalation detected",
  "plane_results": {
    "identity": {"passed": true, "risk_score": 0.0},
    "intent": {"passed": false, "risk_score": 0.75}
  },
  "regulatory": {
    "eu_ai_act": "Article 13 compliant",
    "nist_ai_rmf": "GV-3 logged"
  }
}

---

License

Apache 2.0 — Enterprise-safe, permissive, no patent traps.

---

Contributing

See CONTRIBUTING.md for guidelines.

---

Roadmap

• v0.1.0 (Current): Core security planes, text-only
• v0.2.0: Plugin system, async support, Redis adapters
• v0.3.0: Multimodal guards (image, audio)