pramagent 0.7.3

Alpha agent trust middleware: audit trails, safety guardrails, HITL, and tool validation

Pramagent

Trust middleware for LLM agents: deterministic tool policy, HITL approvals, and tamper-evident audit traces. Alpha - read the implementation status before customer-facing pilots.

Pramagent wraps OpenAI, Anthropic, Gemini, Ollama, local, and OpenAI-compatible providers with guardrails that run outside the model. The most differentiated layer is ToolGuard: deterministic tool validation with JSON Schema, tenant/action allow-lists, side-effect taxonomy, dangerous-chain detection, output scanning, and HITL escalation. The current package also ships curated safety rule corpora, persistent HITL queues, thin adapters for popular agent frameworks, and compliance evidence generation.

Alpha Maturity Notice

Pramagent is published as Alpha software. It has live smoke-test evidence for Sepolia anchoring, S3 cold archive, local load testing, real OpenAI/Ollama provider calls, and bundled red-team runs, but it has not passed an external penetration test, SOC 2 audit, HIPAA assessment, or regulated-production certification.

Do not treat Pramagent as bank-grade or healthcare-grade security infrastructure. Do not claim prompt-injection immunity, production compliance, or third-party-validated safety from the bundled benchmarks alone. Read Implementation status, Live test results, and Hardening guide before using it in a customer-facing pilot. The June 11 active security prompt results are tracked in Security test results.

Bare Install Quickstart

This works with the base package only. No Docker, API server, or provider key is required.

pip install pramagent

import asyncio
from pramagent import Pramagent

async def main():
    resp = await Pramagent().run("Summarize this request", tenant_id="demo", session_id="s1")
    print(resp.output)
    print(resp.trace.this_hash)

asyncio.run(main())

That creates a tamper-evident trace using the deterministic mock provider.

Swap to a real OpenAI model by setting OPENAI_API_KEY:

from pramagent import Pramagent
from pramagent.providers import OpenAIProvider

armor = Pramagent(provider=OpenAIProvider(model="gpt-4o-mini"))

API And Dashboard Install

pip install "pramagent[api,dashboard,redis,postgres]"

From source:

git clone [e-mail]:sriram7737/pramagent.git
cd Pramagent
pip install -e ".[dev,api,redis,postgres,dashboard]"

CLI And Docker Quickstart

pramagent init
pramagent validate

Run the local stack:

cp .env.example .env
docker compose up -d

Open:

• API docs: http://localhost:8080/docs
• Dashboard: http://localhost:8501

Run the release sanity checks:

python -m pytest -q --tb=no
pramagent redteam --json --attacks 100
pramagent redteam --json --dynamic --attacks 200 --seed 999

Current local result: 558 passed, 1 skipped.

ToolGuard Example

import asyncio

from pramagent import Pramagent, Verdict
from pramagent.layers import ToolGuardLayer, ToolPolicy
from pramagent.layers.tool_guard import SideEffect

guard = ToolGuardLayer(policies=[
    ToolPolicy(
        name="send_payment",
        side_effect=SideEffect.PAYMENT,
        action=Verdict.ESCALATE,
        allowed_tenants={"finance_team"},
        schema={
            "type": "object",
            "required": ["amount_usd", "destination"],
            "properties": {
                "amount_usd": {"type": "number", "minimum": 0.01, "maximum": 5000},
                "destination": {"type": "string", "pattern": r"acct-\d{6,}"},
            },
            "additionalProperties": False,
        },
    )
])

armor = Pramagent(tool_guard=guard)

async def main():
    decision = armor.validate_tool(
        "send_payment",
        {"amount_usd": 250.00, "destination": "acct-123456"},
        tenant_id="finance_team",
        session_id="demo",
    )
    print(decision.verdict)  # ESCALATE

    too_large = armor.validate_tool(
        "send_payment",
        {"amount_usd": 9000.00, "destination": "acct-123456"},
        tenant_id="finance_team",
        session_id="demo",
    )
    print(too_large.verdict, too_large.reason)  # BLOCK: schema violation

    wrong_tenant = armor.validate_tool(
        "send_payment",
        {"amount_usd": 250.00, "destination": "acct-123456"},
        tenant_id="marketing_team",
        session_id="demo",
    )
    print(wrong_tenant.verdict, wrong_tenant.reason)  # BLOCK: tenant mismatch

    response = await armor.run(
        "Summarize this payment request",
        tenant_id="finance_team",
        session_id="demo",
        action="send_payment",
    )
    print(response.hitl)
    print(response.trace.this_hash)

asyncio.run(main())

Built-In Rule Corpora

Pramagent now includes deterministic, importable rule bundles. They are plain Python Rule objects, so a reviewer can inspect exactly what is enforced.

from pramagent import Pramagent
from pramagent.layers import SafetyLayer
from pramagent.rules import ALL_RULES, JAILBREAK_PATTERNS, OWASP_LLM_TOP10

armor = Pramagent(
    safety=SafetyLayer(rules=[*JAILBREAK_PATTERNS, *OWASP_LLM_TOP10])
)

strict_armor = Pramagent(safety=SafetyLayer(rules=ALL_RULES))

Included corpora:

• JAILBREAK_PATTERNS
• OWASP_LLM_TOP10
• INJECTION_CORPUS
• FICTIONAL_WRAPPER
• PHI_PATTERNS
• FINANCIAL_PII

Persistent HITL Queue

For approval flows that must survive process restarts, use the persistent queue backends:

from pramagent.layers import HITLLayer
from pramagent.queue import SQLiteHITLQueue

hitl = HITLLayer(
    require_approval_for=["send_email", "wire_transfer"],
    store=SQLiteHITLQueue("hitl.db"),
    timeout_s=None,  # wait until another process approves or denies
)

InMemoryHITLQueue, SQLiteHITLQueue, and PostgresHITLQueue are available under pramagent.queue.

Framework Adapters

Pramagent is meant to sit under existing agent frameworks, not replace them.

from pramagent.adapters import PramagentNode, PramagentHook, PramagentGuard

# LangGraph
guard_node = PramagentNode(armor=armor)

# AutoGen
PramagentHook(armor=armor).attach(agent)

# CrewAI
safe_tool = PramagentGuard(armor=armor).wrap_tool(send_email)

Generic helpers are also available:

from pramagent.adapters import protect, protect_tool

Compliance Evidence

ComplianceReporter.generate() can produce point-in-time evidence packages from Pramagent traces and mappings:

from pramagent.compliance import ComplianceReporter

ComplianceReporter(store=store, audit=audit).generate(
    framework="SOC2",
    period_start="2026-01-01",
    period_end="2026-06-30",
    tenant_id="demo",
    output="evidence.json",
)

Supported mapping targets include SOC2, HIPAA, GDPR, NIST AI RMF, EU AI Act, and PCI DSS. This is engineering evidence, not a certification.

When To Use Pramagent

• You are wrapping LLM calls or agent workflows and need audit trails, policy checks, HITL approvals, PII scrubbing, and provider fallback in one place.
• You want deterministic tool policy outside the model, especially for actions like payments, data export, account changes, or admin operations.
• You are building an internal tool or pilot where honest safety evidence matters more than marketing claims.
• You need tamper-evident traces with optional Sepolia anchoring and encrypted S3 cold archive support.
• You already use LangGraph, AutoGen, CrewAI, or a custom loop and want a thin trust layer around prompts, tool calls, and approvals.

When Not To Use Pramagent Yet

• You need certified bank-grade, healthcare-grade, or SOC2-audited production infrastructure today.
• You need proven jailbreak resistance against a serious red team; the bundled benchmark is only a deterministic smoke test, not third-party assurance.
• You need mature enterprise dashboard auth such as SSO/OIDC/RBAC. Optional generated dashboard keys and SQL users exist, but this is not an enterprise IAM plane yet.
• You need production-grade scale evidence, chaos engineering, or SLA-backed capacity numbers beyond the published local Docker Compose load run.
• You need billing-grade Stripe/Chargebee metering rather than the local usage ledger and event hooks.

What Works Today

Capability	Status	Notes
Provider adapters	Implemented	Mock, OpenAI, Anthropic, Gemini, Ollama, OpenAI-compatible/local
Rule corpora	MVP	129 deterministic rules across jailbreaks, OWASP LLM risks, injection, fictional-wrapper bypasses, PHI, and financial PII
ToolGuard	Strong MVP	Draft 2020-12 JSON Schema, allow-lists, side-effect taxonomy, output scanning, Redis-backed chain state
HITL	Beta	Slack callbacks, persistent SQLite/Postgres queues, quorum/escalation primitives, ServiceNow/PagerDuty/email/webhook notifiers
Audit trail	Strong MVP	SHA-256 hash chain; optional real Sepolia anchoring
PII redaction	Strong MVP	Context-aware patterns for common regulated data; bounded email scrubbing avoids long-input regex DoS
Auth/rate limits/quotas	Beta	JWT/API keys, token buckets, per-tenant quotas
Framework adapters	MVP	LangGraph node, AutoGen hook, CrewAI guard, generic protect/protect_tool helpers
Dashboard	Prototype	Shared-key fallback, optional SQL users with generated keys, tenant scoping, traces, approvals, metrics, usage page, CSRF
Redis/Postgres backends	Beta	Wired and tested locally; needs scale/load testing
OpenTelemetry	Partial	Per-layer spans exist; dashboards and alerting need hardening
Red-team benchmark	MVP	Static and dynamic mutation modes; includes base64, translation-wrapper, and authority-framing regressions
Billing hooks	MVP	In-memory hash-chain usage ledger plus fail-open webhook; no Stripe/Chargebee provider yet
S3 cold archive	MVP	Gzip + encrypted trace archive wrapper; metadata sink hook
Compliance evidence	MVP	ComplianceReporter.generate() for JSON/text/PDF-style evidence packages

Integration Safety Contract

Pramagent should not replace human workflows that already work. Treat it as a policy and evidence layer around risky agent actions, not as a mandate to put AI into every decision path.

Before integrating a new feature or agent workflow, require three gates:

1. Isolation contract: declare which trust layers the feature touches. HITL features need a negative test proving the action cannot proceed without an authenticated approval. Isolation features need tenant/session boundary tests.
2. Regression baseline: run the full suite plus the new feature tests. Zero regressions are allowed for previously passing safety, trace, auth, and store behavior.
3. Consequence traceability: every approved or triggered action must leave a trace that explains why it was allowed, who/what approved it, what policy applied, and which downstream side effect was attempted.

The reusable reviewer prompt for this is in Security audit prompt.

Honest Limits

• Prompt-injection defense is not complete. The bundled static corpus and seeded dynamic mutation smoke tests now include base64, translation-wrapper, and authority-framing regressions, but the embedding classifier is optional and the project still needs larger third-party red-team sets.
• ToolGuard is a hard policy gate outside the model, but it is not a sandbox.
• ToolGuard chain detection and per-session call limits are per-process unless a shared Redis backend is configured (PRAMAGENT_TOOL_GUARD_REDIS_URL or PRAMAGENT_REDIS_URL). When running multiple uvicorn workers, a dangerous tool chain whose steps land on different workers is only detected with a shared Redis backend; the Redis path uses an atomic Lua append so concurrent same-session calls never lose history.
• Slack is the main decision-collecting HITL adapter today. ServiceNow, PagerDuty, email, and generic webhooks are useful notification/escalation adapters. Persistent SQLite/Postgres approval queues exist, but broader enterprise approval workflows are still in development.
• Dashboard auth has tenant-scoped shared-key fallback plus optional SQL-backed users with generated dashboard keys and key regeneration. It is still not SSO/OIDC/RBAC-grade.
• Ethereum anchoring is Sepolia/testnet-oriented; no mainnet runbook, verifier contract, HSM/KMS key-management story, or enterprise anchoring operating model is included yet.
• The usage ledger is local audit evidence for pilots, not an invoice-grade billing system.
• Redis/Postgres support exists, but the stack has not been chaos-tested or load-tested for high-stakes deployments.
• No external penetration test or formal compliance certification has been run.
• QuantumLayer is future research only. It is not implemented, advertised as a feature, or exposed as a production API.

Optional Anchoring And Archive

pip install "pramagent[ethereum,s3]"

Ethereum/Sepolia anchoring submits the audit head as transaction calldata and stores the tx hash plus block number on the trace when configured. S3 cold archive wraps a primary store and archives pruned/erased traces as encrypted gzip JSON while keeping metadata available for compliance reporting.

Demo Flow

pramagent init
docker compose up -d
python -m pytest -q --tb=no
pramagent redteam --json --dynamic --attacks 200 --seed 999

Then use the dashboard to inspect traces, pending HITL approvals, audit status, metrics, and per-tenant usage.

Docs

• Implementation status
• Live test results
• Hardening guide
• Security test results
• More documentation

Author

• Sriram Rampelli

License

Apache-2.0.