pramagent
Pramagent Guard policy enforcement for Gemini CLI tool calls.
Open source Open in the app JSON README (API)
About
Pramagent Guard policy enforcement for Gemini CLI tool calls.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- sriram7737
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.4
- Stars
- 2
- Last push
- 2026-09-14T04:13:19Z
- Repository state
- ativo
- Language
- Python
- License
- Apache-2.0
- Added
- 2026-09-14 09:05:40
- Updated
- 2026-09-14 09:05:40
- Origin id
sriram7737/pramagent
README
# Pramagent
[](https://pypi.org/project/pramagent/)
[](https://pepy.tech/projects/pramagent)
[](https://pypi.org/project/pramagent/)
[](https://github.com/sriram7737/pramagent/blob/main/LICENSE)
[](https://github.com/sriram7737/pramagent/actions/workflows/tests.yml)
[](https://github.com/google-gemini/cookbook/blob/main/examples/Pramagent_trust_layer_for_gemini.ipynb)
[](https://github.com/langchain-ai/docs/pull/4806)
Trust middleware for LLM agents: deterministic tool policy, HITL approvals,
and tamper-evident audit traces. **Alpha** - read the
[implementation status](https://github.com/sriram7737/pramagent/blob/main/docs/IMPLEMENTATION_STATUS.md)
before customer-facing pilots.
Pramagent is listed in the
[Google Gemini Cookbook examples index](https://github.com/google-gemini/cookbook/blob/main/examples/README.md)
and included as the
[Pramagent trust layer for Gemini agents notebook](https://github.com/google-gemini/cookbook/blob/main/examples/Pramagent_trust_layer_for_gemini.ipynb).
The contribution was merged in
[google-gemini/cookbook#1269](https://github.com/google-gemini/cookbook/pull/1269)
on July 29, 2026.
Pramagent is also listed in the
[LangChain docs integrations index](https://github.com/langchain-ai/docs/blob/main/src/oss/python/integrations/providers/all_providers.mdx)
as an external `ToolGuardLayer` integration for LangGraph tool calls. The
contribution was merged in
[langchain-ai/docs#4806](https://github.com/langchain-ai/docs/pull/4806)
on August 11, 2026.
The wedge is narrow by design: Pramagent does not prevent your model from being
wrong; it prevents your model from doing damage when it is wrong.
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, compliance evidence generation, and trace-local
self-assessed control indicators mapped to DeepMind/AWS-style vocabulary. It also includes an
optional agent-memory integrity contract, structured decision-rationale schema,
and a human-labeled overreach corpus for measuring valid-goal overreach.
## What it's ready for (and what it isn't)
Pramagent is an honest alpha. The core trust pipeline is real and tested; the
gaps are around it. Use this to decide whether it fits your use case.
**Ready for today:**
- Developer evaluation and integration against the SDK and FastAPI sidecar
- Single-tenant or trusted-network pilots **with a persistent store configured**
(`PRAMAGENT_POSTGRES_DSN` or `PRAMAGENT_DB`) — the API refuses to boot on
volatile memory unless you explicitly opt in
- Design-partner deployments where you control the network boundary
- Generating compliance *evidence* (control mappings, not certifications)
**Not ready for yet — do not claim:**
- Production banking / healthcare or other regulated environments
- Multi-tenant SaaS at scale (no published HA/soak evidence, no backup/DR runbook,
no SLA)
- Prompt-injection *immunity*, *certified* GDPR/SOC 2/HIPAA compliance, or
third-party-validated safety — none of these have been externally assessed
**What backs this:** 720 passing integration-first tests across Python
3.10–3.13, CI security scanning (Bandit, Semgrep, authenticated OWASP ZAP), and
three prior engineering audits whose release-blocking findings are remediated
and verified in the current source. Those audit reports are kept in the repo
**with remediation banners** so you can read both the original findings and
their fixes — see
[Full audit](https://github.com/sriram7737/pramagent/blob/main/docs/audits/pramagent_full_audit.md)
and [Enterprise review](https://github.com/sriram7737/pramagent/blob/main/docs/audits/pramagent_enterprise_audit.md).
## 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](https://github.com/sriram7737/pramagent/blob/main/docs/IMPLEMENTATION_STATUS.md),
[Live test results](https://github.com/sriram7737/pramagent/blob/main/docs/LIVE_TEST_RESULTS.md), and
[Hardening guide](https://github.com/sriram7737/pramagent/blob/main/docs/HARDENING_GUIDE.md)
before using it in a customer-facing pilot.
The June 11 active security prompt results are tracked in
[Security test results](https://github.com/sriram7737/pramagent/blob/main/docs/audits/pramagent_security_test_results.md).
The self-assessed DeepMind/AWS agent-security mapping is tracked in
[Conformance map](https://github.com/sriram7737/pramagent/blob/main/docs/CONFORMANCE.md).
Deferred controls and the reasoning behind them are tracked in
[Design decisions](https://github.com/sriram7737/pramagent/blob/main/docs/DESIGN_DECISIONS.md).
The YC/product-readiness gap list and commercial hardening roadmap are tracked
in [Enterprise readiness roadmap](https://github.com/sriram7737/pramagent/blob/main/docs/ENTERPRISE_READINESS_ROADMAP.md).
**Start here:** [Getting Started With Pramagent](https://github.com/sriram7737/pramagent/blob/main/docs/GETTING_STARTED.md)
walks from install to provider setup, agent wrapping, ToolGuard, HITL, trace
storage, dashboard/API, and real workflow demos.
**Try the public demo:** run the API and open `/demo`. The front-door scenario
is financial tool-calling safety: a payment-like action is held for HITL before
any provider call and sealed into a verifiable trace. No provider key is needed
for that zero-config path. Visitors can optionally enter an NVIDIA NIM
`nvapi-*` key, OpenAI `sk-*` key, or Gemini API Studio key for live model
answers; keys are used for that request only and never persisted.
One-command local demo:
```bash
pip install "pramagent[api]"
pramagent demo
# open http://127.0.0.1:8080/demo
```
## Bare Install Quickstart
This works with the base package only. No Docker, API server, or provider key is
required.
```bash
pip install pramagent
```
### Google Gemini Cookbook Recipe
The merged recipe appears in the
[Google Gemini Cookbook examples index](https://github.com/google-gemini/cookbook/blob/main/examples/README.md)
as "Pramagent trust layer for Gemini agents" and links to the direct
[notebook in `examples/`](https://github.com/google-gemini/cookbook/blob/main/examples/Pramagent_trust_layer_for_gemini.ipynb).
It is pinned to `pramagent==0.8.5` for reproducibility. That notebook should
keep using the stable `0.8.5` baseline even as newer Pramagent releases ship
additional hardening and coding-agent hook support. For the latest package in
new projects, install or upgrade normally:
```bash
pip install -U pramagent
```
Only update the Cookbook pin for a security fix, a breakage fix, or a
substantial recipe revision.
### LangChain Docs Integration
The merged LangChain docs entry appears in the
[LangChain integrations index](https://github.com/langchain-ai/docs/blob/main/src/oss/python/integrations/providers/all_providers.mdx)
as "Pramagent" and in the generated tools/downloads table as
[`ToolGuardLayer`](https://github.com/sriram7737/pramagent). The contribution
was merged in
[langchain-ai/docs#4806](https://github.com/langchain-ai/docs/pull/4806)
on August 11, 2026.
For LangGraph users, start with the repo-hosted
[Pramagent with LangGraph guide](https://github.com/sriram7737/pramagent/blob/main/docs/integrations/langgraph.md),
which shows deterministic `ToolGuardLayer` checks before LangGraph tool
execution.
```python
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)
print(resp.trace.detection_tier, resp.trace.response_tier) # trace-local indicators
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`:
```python
from pramagent import Pramagent
from pramagent.providers import OpenAIProvider
armor = Pramagent(provider=OpenAIProvider(model="gpt-4o-mini"))
```
Run against NVIDIA NIM with an `nvapi-*` key:
```python
from pramagent import Pramagent
from pramagent.providers import NvidiaProvider
armor = Pramagent(provider=NvidiaProvider(model="meta/llama-3.3-70b-instruct"))
```
## Frequently Asked Questions
**How do I add safety guardrails to an LLM agent?**
Install Pramagent and wrap your agent call with the trust stack. Pramagent
enforces deterministic policy outside the model, so the LLM cannot override the
tool policy, HITL gate, or audit chain by changing its own text output.
**How do I audit AI agent decisions in production?**
Every Pramagent call produces a hash-chained `TraceEvent` with layer decisions,
verdicts, provider metadata, PII redactions, HITL status, and `this_hash` /
`prev_hash`. New traces also include `aws_scope`, `detection_tier`,
`response_tier`, `attack_techniques`, and `conformance_metrics` so the same
evidence can be read through DeepMind/AWS-style agent-security vocabulary. These
fields are trace-local self-assessment metadata, not system-level conformance
or certification claims. The local chain can be verified and optionally anchored
externally.
**How do I declare AWS agent autonomy scope?**
Pass `agent_scope="scope_1"`, `"scope_2"`, or `"scope_3"` to `Pramagent`, or
set `PRAMAGENT_AGENT_SCOPE` for the API sidecar. Scope 1 blocks non-read side
effects. Scope 2 requires human approval for non-read tools even if a policy
was accidentally configured as `ALLOW`. Scope 3 records bounded-autonomy intent
and relies on your configured ToolGuard/HITL/rate-limit policies.
**How do I prevent prompt injection in a Python LLM agent?**
`IsolationLayer` is a content-boundary layer: it scans inputs before the model
sees them, enforces size caps, and scopes optional memory by tenant/session. It
does not sandbox processes, networks, credentials, tools, or files. It covers known
instruction overrides, chat-template wrapper attacks, authority framing,
base64/hex/unicode-escape encoded payloads, and targeted multilingual override
phrases. v0.8.0 adds structured classifier verdicts, held-out PINT/TensorTrust
style fixtures, provenance-aware stricter scanning for tool output and
retrieved content, and optional `pramagent[ml]` embedding/DeBERTa layers. This
is defense-in-depth, not proof of prompt-injection immunity.
**How do I stop unsafe model output from reaching users?**
`OutputJudgeLayer` runs an LLM-as-judge on every output before it returns — the
"is the OUTPUT safe?" check that regex cannot give. It catches semantic failures
deterministic rules miss (working malware, bypass walkthroughs, confirmed
destructive actions, leaked internals). On by default in the public demo, opt-in
for `/v1/run` (`PRAMAGENT_OUTPUT_JUDGE=1`). It is fail-closed, but it is itself a
model — strong defense-in-depth, not a guarantee.
**How do I stop unsafe tool calls from an AI agent?**
Use `ToolGuardLayer` with `ToolPolicy`. Pramagent validates JSON Schema,
tenant/action allow-lists, side-effect class, call frequency, argument
injection, and dangerous chains before any side effect can execute.
**Can I trial policies without breaking production workflows?**
Yes. Construct `Pramagent(enforcement_mode="observe")` or set
`PRAMAGENT_ENFORCEMENT_MODE=observe` for the API sidecar. Observe mode records
`trace.would_block=True`, `trace.would_block_reason`, and a `*.observe`
LayerEvent, but lets Safety/ToolGuard/Scope policy decisions continue so teams
can tune policies. Consent, size caps, and injection isolation still fail
closed.
**Can security teams review policies without editing Python?**
Yes. `pramagent.policies.load_tool_guard("policies.json")` loads ToolPolicy
definitions from JSON, and YAML is supported with `pip install pyyaml` or
`pramagent[policy]`. `pramagent backtest policies.json --cases cases.jsonl`
runs proposed policy changes against explicit tool-call cases and exits
nonzero on expected-verdict mismatches.
**How do I add human approval to AI agent actions?**
Use `HITLLayer` or a ToolGuard policy with `Verdict.ESCALATE`. Silence is never
consent: if approval does not arrive, the action remains unexecuted.
**Does Pramagent work with OpenAI, Anthropic, Gemini, Ollama, and local models?**
Yes. Pramagent ships provider adapters for OpenAI, Anthropic, Gemini, Ollama,
NVIDIA NIM, and OpenAI-compatible local endpoints, plus a deterministic mock
provider for tests.
**Is Pramagent compliant with SOC 2, HIPAA, or the EU AI Act?**
No. Pramagent includes compliance evidence mapping and tamper-evident logging
features that can support an assessment, but it has not passed SOC 2, HIPAA, EU
AI Act conformity assessment, or an external penetration test.
## API And Dashboard Install
```bash
pip install "pramagent[api,dashboard,redis,postgres]"
```
From source:
```bash
git clone git@github.com:sriram7737/pramagent.git
cd Pramagent
pip install -e ".[dev,api,redis,postgres,dashboard]"
```
## CLI And Docker Quickstart
```bash
pramagent init
pramagent validate
```
Run the local stack:
```bash
cp .env.example .env
docker compose up -d
```
Open:
- API docs: `http://localhost:8080/docs`
- Dashboard: `http://localhost:8501`
## Public Live Demo
The API serves a single-page product demo at `/demo`. It is enabled by default
so a new evaluator reaches the trust-stack proof immediately; set
`PRAMAGENT_DEMO_ENABLED=false` for API-only deployments.
```bash
pip install "pramagent[api]"
pramagent demo
```
`pramagent demo` sets demo-safe local defaults in that process:
`PRAMAGENT_DEMO_ENABLED=true`, `PRAMAGENT_ALLOW_MEMORY_STORE=1`, and
`PRAMAGENT_PROVIDER=mock`.
The first scenario needs no provider key: it routes a financial transfer
request through deterministic policy, pauses it at HITL, and returns the trace
plus `this_hash` / `prev_hash`. This is the five-minute wedge: financial
side-effect safety before the model is trusted.
The same page includes a read-only quantum evidence band backed by completed
physical IBM Quantum job `dajho5hhvn6c73cueht0`. It shows the backend, physical
layout, observed shots and counts, correlation, QPU usage, layout-policy proxy,
and execution-evidence hash. The public endpoint never receives IBM
credentials or submits paid hardware work. The displayed run is real hardware
evidence, while its original local audit capture is explicitly labeled as an
unkeyed test chain; new local runs use a separate versioned quantum signing
ring.
Visitors can optionally bring a provider key on each run: `nvapi-*` for NVIDIA
NIM models, `sk-*` / `sk-proj-*` for OpenAI `gpt-4o-mini`, or an AI Studio
Gemini key for `gemini-2.5-flash`. Pramagent uses that key only for the current
provider call; it is not written to traces, logs, stores, usage records, or the
hash-chain payload. Each demo run uses an isolated in-memory trace store and
returns the output, trust-layer events, redactions, HITL state, latency,
self-assessed trace-control fields, `this_hash`, `prev_hash`, and local chain
verification.
The demo also includes optional product signals. If a visitor checks the
anonymous usage box, Pramagent records only a process-salted hashed visitor ID,
provider kind, verdict, HITL state, and trace-control indicators. It never records
prompts, outputs, provider keys, IP addresses, or plaintext email. The
managed-pilot form stores salted contact hashes plus a short use-case label
with obvious email/phone values redacted, so demand can show up as data without
turning the demo into a tracking surface.
Set `PRAMAGENT_DEMO_ADMIN_KEY` to enable the protected operator view at
`/demo/admin/signals`. The browser page asks for that key and then calls
`/demo/admin/signals.json` with an `Authorization: Bearer ...` header; the key
is never placed in a URL. By default these signals are process-local memory.
Set `PRAMAGENT_DEMO_SIGNALS_POSTGRES_DSN` to persist them to Postgres, and set
`PRAMAGENT_DEMO_SIGNAL_SALT` when you want hashed visitor/contact identifiers
to remain stable across restarts. The persisted schema still stores only
hashed/scrubbed fields, not prompts, outputs, provider keys, IPs, or plaintext
contacts.
The public throttle is keyed by client IP plus a short in-memory SHA-256 hash
of the visitor's provider key. The no-key deterministic path is throttled by
IP. If a visitor switches to a different key, they get a fresh demo bucket
without Pramagent storing the plaintext key.
A `DEGRADED` demo result means the upstream model call failed and Pramagent
returned its safe default with a trace. NVIDIA HTTP 403 usually means the
NVIDIA organization lacks hosted Public API Endpoints access; changing models
usually will not fix that entitlement issue.
Dashboard evidence from the authenticated June 21 smoke run is captured in
[Demo evidence](https://github.com/sriram7737/pramagent/blob/main/docs/DEMO_EVIDENCE_2026-06-21.md).
It includes screenshots for safe output, PII scrubbing, prompt-injection
blocking, destructive database-operation blocking, HITL-held financial action,
trace hashes, and the dashboard metric fix that reports engine latency
separately from human approval wait time. The evidence set also includes the
current console redesign preview: single-brand navigation, dense trace detail
with raw/scrubbed payloads, terminal `EXPIRED` approval states, and a
favicon-size proof for the Pramagent mark. The packaged dashboard serves the
new Pramagent SVG mark from `/static` across authenticated and pre-auth key
flows.
Run the release sanity checks:
```bash
python -m pytest -q --tb=no
python -m pramagent.cli redteam --json --attacks 100
python -m pramagent.cli redteam --json --dynamic --attacks 200 --seed 999
```
Current local result: `684 passed, 2 skipped`. The latest targeted prompt
suite also passed with `0` failures across emergency override, output override,
margin/liquidation, IBAN/SWIFT, ambiguous escalation, PHI, false-positive,
base64, hex, unicode-escape, multilingual override-token, and
chat-template-wrapper cases.
## ToolGuard Example
```python
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())
```
## Policy-As-Code And Backtesting
Security teams can review ToolGuard definitions as JSON/YAML files instead of
hardcoding them in application code.
`policies.json`:
```json
{
"policies": [
{
"name": "send_payment",
"side_effect": "payment",
"action": "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": "acct-\\d{6,}"}
},
"additionalProperties": false
}
}
]
}
```
```python
from pramagent import Pramagent
from pramagent.policies import load_tool_guard
armor = Pramagent(tool_guard=load_tool_guard("policies.json"))
```
Backtest before merging a policy PR:
```bash
pramagent backtest policies.json --cases cases.jsonl
```
`cases.jsonl` uses one JSON object per historical/proposed tool call:
```json
{"case_id":"pay-001","tool_name":"send_payment","arguments":{"amount_usd":250,"destination":"acct-123456"},"tenant_id":"finance_team","expected":"escalate"}
```
This v0 backtest contract is explicit case replay. Stored-trace replay over the
last 30 days is on the roadmap once deployments have a stable tool-call export
shape.
## Drop-In Tool Decorator
For custom Python agents, wrap existing tools without rewriting the execution
loop:
```python
from pramagent.adapters import guarded_tool
@guarded_tool(armor, policy="send_payment")
def send_payment(amount_usd: float, destination: str):
...
```
`BLOCK` and `ESCALATE` both stop the function before the side effect runs.
Use the persistent HITL queue/dashboard path to approve and then re-run the
side effect intentionally; the decorator never treats escalation as consent.
## 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.
```python
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`
## Escalation Policy
`Verdict.ESCALATE` means "suspicious, but not certain enough to block." What
the pipeline does with it is configurable per stage — `pre` (the input pass,
before the model runs) and `post` (the output pass, after) — with one of
`"log"` (record and continue), `"hitl"` (route to the human-in-the-loop gate,
idle-on-silence), or `"block"` (hard stop). The default is `"log"` so adding an
ESCALATE rule never silently starts gating traffic; the ESCALATE verdict is
always recorded in the trace either way.
```python
# Healthcare / finance — maximum caution
Pramagent(safety=SafetyLayer(rules=[...]),
escalate_policy={"pre": "hitl", "post": "block"})
# Developer tool — minimal interruption (default)
Pramagent(safety=SafetyLayer(rules=[...]),
escalate_policy="log")
# Internal enterprise — gate suspicious input, log suspicious output
Pramagent(safety=SafetyLayer(rules=[...]),
escalate_policy={"pre": "hitl", "post": "log"})
```
A string applies to both stages; a dict sets them independently. Invalid values
raise at construction, not at request time.
## Persistent HITL Queue
For approval flows that must survive process restarts, use the persistent
queue backends:
```python
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`.
Persistent requests carry an expiry and a SHA-256 binding over the tenant,
action, and canonical context. Queue backends enforce expiry at decision time,
accept only the first decision, and reject duplicate request IDs, so a stale or
replayed approval cannot authorize a different action.
## Framework Adapters
Pramagent is meant to sit under existing agent frameworks, not replace them.
```python
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:
```python
from pramagent.adapters import protect, protect_tool
```
## Integration Listings
Pramagent is listed in external ecosystem docs as a trust layer for agent tool
calls:
- [Google Gemini Cookbook recipe](https://github.com/google-gemini/cookbook/blob/main/examples/Pramagent_trust_layer_for_gemini.ipynb) - Gemini agent trust-layer notebook merged in `google-gemini/cookbook#1269`.
- [LangChain/LangGraph integration guide](https://github.com/sriram7737/pramagent/blob/main/docs/integrations/langgraph.md) - deterministic `ToolGuardLayer` checks before LangGraph tool execution.
- [LangChain docs integration listing](https://github.com/langchain-ai/docs/pull/4806) - merged external listing for `ToolGuardLayer` and `pramagent`.
## Coding-Agent Hooks
For deployments where the agent must not be able to rewrite its own hook,
install the runtime and host configuration under an OS-owned permission
boundary. The Windows and Linux installers, threat boundary, and verification
steps are documented in
[Hook Deployment Boundary](docs/HOOK_DEPLOYMENT_BOUNDARY.md). In-process path
checks alone do not protect files writable by the same OS identity.
Pramagent also ships a publishable hook plugin for coding agents:
- Claude Code `PreToolUse`
- Codex plugin hooks
- Grok Build / xAI plugin hooks
- any host that can emit Claude-style pre-tool-call JSON on stdin
The plugin lives in `plugins/pramagent-guard/`, with publishing notes in
[`docs/AGENT_HOOK_PUBLISHING.md`](docs/AGENT_HOOK_PUBLISHING.md). It is not an
MCP server/client/proxy; it is a host-agent lifecycle hook that evaluates
proposed tool calls before execution.
Hook registrations use a broad matcher and deny unregistered tools. The shared
control-plane check runs before policy toggles and protects host settings, hook
launchers, plugin policy files, the guard package, and audit stores from
tool-mediated edits. A bootstrap wrapper converts import, syntax, timeout, and
invalid-output failures into explicit denials. These checks protect the agent
tool path; production deployments still need OS permissions or a separate
service account so the guarded process cannot rewrite its own installation.
From the source checkout that provides the hook/plugin files, run
`pramagent hooks-doctor --repo-root .` to verify host wiring, approved runtime
hashes, and control-plane integrity. The PyPI wheel provides the shared policy
engine and doctor command; host hook bundles are installed from this repository
or its plugin marketplace. `--strict` also fails when hook files remain writable
by the current OS account. The admin console records field-level changes and can
restore an audited snapshot by appending a rollback event; history is never
rewritten.
## Compliance Evidence
`ComplianceReporter.generate()` can produce point-in-time evidence packages
from Pramagent traces and mappings:
```python
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](https://github.com/sriram7737/pramagent/blob/main/docs/SECURITY_AUDIT_PROMPT.md).
## 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. v0.8.0 adds structured verdicts,
provenance-aware stricter scanning, held-out PINT/TensorTrust-style fixtures,
and optional `pramagent[ml]` embedding/DeBERTa layers, but the project still
needs larger third-party red-team sets and external assessment.
- 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.
- Portable Evidence Envelope V2 now includes integer-only RFC 8785
canonicalization, Merkle proofs, and strict hybrid Ed25519 plus ML-DSA-65
checkpoint signatures. Its optional Sigstore adapter obtains live RFC 3161
timestamps and Rekor inclusion receipts using TUF-authenticated trust
material, with a durable local retry outbox. Managed signing keys, archive
timestamp renewal, QRNG mixing, and a complete QuantumLayer remain roadmap
work. The IBM Runtime path submits a guarded
Bell-pair hardware attestation with explicit consent, bounded shots, provider
job evidence, and hash-chained audit records. It is not a quantum-advantage
claim or a production VLM by itself.
## Optional Anchoring And Archive
```bash
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
```bash
pramagent init
docker compose up -d
python -m pytest -q --tb=no
python -m pramagent.cli redteam --json --dynamic --attacks 200 --seed 999
```
Then use the dashboard to inspect traces, pending HITL approvals, audit status,
metrics, and per-tenant usage.
## Current Integration Notes
The merged Gemini Cookbook notebook remains pinned for reproducibility, and the
LangChain docs listing points back to this repository. Newer integration work
should stay additive here: keep the public `Pramagent`, `ToolGuardLayer`,
`ToolPolicy`, `SideEffect`, `Verdict`, and `validate_tool()` surface stable,
then document newer controls in this repo.
Recent additions include the local hook control plane, per-tenant hook
permissions, HMAC-chained hook-admin audit records, and installable guarded
PennyLane QNode and hybrid-router APIs under `pramagent.quantum`. Existing hook-control files created
before state binding must be reviewed and bound once from the admin console;
until then, hook enforcement stays on. Users coming from the cookbook or
LangChain listing can upgrade Pramagent from PyPI and follow the docs in this
repository without changing either upstream link.
The optional IBM hardware path is installed with
`pip install "pramagent[quantum-ibm]"`. Run `pramagent quantum-status` before
using `pramagent quantum-run`; real submissions require explicit hardware and
unpriced-QPU-time acknowledgements. See the quantum guide for the exact trust
boundary and current limitations.
Quantum budgets can use an opt-in SQLite ledger on one host or a PostgreSQL
ledger across workers and hosts. Both atomically reserve shots and estimated
cost before execution and reconcile measured use afterward. IBM attestations
also emit a sealed, time-bounded calibration canary. Applications can require a
fresh canary for the same provider and backend, then bind it to the completed
workload evidence in the audit chain. IBM and PennyLane paths emit the same
sealed `QuantumExecutionEvidence` shape. Unknown IBM QPU-time cost remains
`None`, not `$0`.
Portable evidence signing is installed separately with
`pip install "pramagent[evidence-v2]"`. It writes additive V2 envelopes while
leaving issued V1 hashes unchanged, requires both Ed25519 and ML-DSA-65 under a
versioned policy, and reports `record_assurance`, `checkpoint_assurance`, and
the effective `assurance_level` on every verification. See the
[Evidence Envelope V2 specification](docs/EVIDENCE_ENVELOPE_V2.md); the
`evidence-v2-verify` CLI accepts trusted public keys from a separate registry.
Install `pramagent[evidence-anchors]` to timestamp a signed checkpoint with the
Sigstore production RFC 3161 service and publish its digest to Rekor. Anchoring
runs after checkpoint creation. SQLite is the local default; multi-worker
deployments use the PostgreSQL outbox with transactional `SKIP LOCKED` claims
and lease fencing:
```bash
pramagent evidence-v2-anchor \
--envelope evidence.json \
--output evidence.anchored.json \
--outbox .pramagent/evidence_anchor_outbox.sqlite3
# Multi-worker deployment; the DSN may instead come from
# PRAMAGENT_ANCHOR_POSTGRES_DSN.
pramagent evidence-v2-anchor \
--envelope evidence.json \
--output evidence.anchored.json \
--outbox-postgres-dsn "$PRAMAGENT_ANCHOR_POSTGRES_DSN"
pramagent evidence-v2-verify \
--envelope evidence.anchored.json \
--keys verification-keys.json \
--anchor-trust sigstore-production \
--require-assurance tsa_anchored
```
The verifier checks the RFC 3161 message imprint, nonce, TSA chain, Rekor
artifact signature, Merkle inclusion proof, and signed log checkpoint. The
production and cache-only trust modes obtain roots from Sigstore's TUF trust
configuration. This establishes externally witnessed time and publication; it
does not make the underlying event truthful or turn two services in the same
operator ecosystem into two independent organizations. The anchor captures
and verifies OCSP/CRL responses when the TSA certificate advertises them; a
signed certificate without either endpoint receives an explicit
`no_endpoint_advertised` record. Pramagent also supports the RFC 4998
single-object/SHA-256 timestamp-renewal profile:
```bash
pramagent evidence-archive-create \
--envelope evidence.anchored.json \
--output evidence.archive.json
pramagent evidence-archive-renew \
--bundle evidence.archive.json \
--output evidence.archive.renewed.json
pramagent evidence-archive-verify \
--bundle evidence.archive.renewed.json
```
The archive bundle retains each TSA response, certificate chain, and available
revocation artifact. Hash-tree renewal, immutable archive storage, automated
renewal scheduling, and a seven-year operational validation drill remain
release requirements; timestamp-renewal support alone is not a seven-year
guarantee. The
PostgreSQL outbox provides at-least-once delivery: a crash after a witness
accepts a request can repeat that external request, while lease fencing keeps
stale workers from overwriting the authoritative stored receipt.
## Verified IBM Hardware Results
On September 13, 2026, the updated Pramagent CLI submitted two guarded
Bell-pair attestations to the physical IBM Quantum backend `ibm_fez`. Both used
atomic shot reservation, explicit hardware consent, sealed execution evidence,
and the persistent HMAC audit chain. IBM Runtime and the local audit database
were independently read again after each completion.
| Field | Optimization 1 | Optimization 3 |
| --- | --- | --- |
| IBM Runtime job | `dajg0i1hvn6c73cuckbg` | `dajg4l1hvn6c73cucon0` |
| Physical qubits | `[0, 1]` | `[146, 147]` |
| Requested / observed shots | `128 / 128` | `128 / 128` |
| Counts (`00`, `01`, `10`, `11`) | `68, 2, 3, 55` | `74, 1, 1, 52` |
| Same-bit correlation | `0.9609375` | `0.984375` |
| Wilson 95% interval | `[0.9118, 0.9832]` | `[0.9448, 0.9957]` |
| Two-sided Fisher exact comparison | reference | `p = 0.4466`; not significant at `0.05` |
| Logical / ISA depth | `3 / 8` | `3 / 7` |
| ISA operations | `12` | `11` |
| SWAP operations | `0` | `0` |
| IBM QPU charge time | `2 s` (billing granularity, not a differentiator) | `2 s` |
| Audit chain | valid | valid |
The PostgreSQL budget and calibration-binding path was subsequently validated
with another physical `ibm_fez` job, `dajgtnphvn6c73cudlf0`: 128/128 observed
shots, counts `00=48, 01=8, 10=4, 11=68`, same-bit correlation `0.90625`, and
2 seconds of provider-reported QPU usage. The budget reservation reconciled
from 128 estimated to 128 actual shots. Its sealed canary was bound to the
earlier same-backend hardware job `dajgs2b9k43c73ah7730` at an age of
183.639432 seconds, and the destination audit chain remained valid. The clean
validation database used an unkeyed SHA-256 test chain because no audit signing
key was visible to that process; deployments should configure the versioned
signing-key ring. See the
[control-plane validation record](docs/quantum-results/ibm_fez_dajgtnphvn6c73cudlf0.json).
The calibration-aware layout guard was then enabled and validated on physical
hardware. Job `dajho5hhvn6c73cueht0` used level 3, automatically selected
`[147,146]`, and passed a complete layout error proxy of `0.011177` against the
`0.05` ceiling before submission. It observed 249 same-bit outcomes in 256
shots, for correlation `0.972656` and Wilson 95% interval
`[0.9446, 0.9867]`. This was higher than the degraded `[0,1]` run at the raw
shot-count level (two-sided Fisher exact `p=0.0102`) and statistically
indistinguishable from the earlier `0.984375` optimized result (`p=0.7236`).
The runs differ in calibration time and shot count, so this validates the
selection and enforcement workflow rather than isolating a causal fidelity
effect. Record: [calibration-aware hardware validation](docs/quantum-results/ibm_fez_dajho5hhvn6c73cueht0.json).
This verifies a one-layer ISA reduction from optimization level 3, not the
suggested SWAP-removal explanation. Physical qubits `[0, 1]` were already
directly connected and the first ISA circuit contained no SWAP. For the current
Qiskit Runtime API, layout belongs on `generate_preset_pass_manager`; `SamplerV2`
does not expose `options.transpilation.initial_layout`. Calibration-aware auto
layout selected `[146, 147]` for the optimized run.
Because the two hardware runs changed optimization level and qubit pair
together, the depth attribution was re-tested offline over the full grid -
optimization level `1` and `3` crossed with layouts `[0, 1]`, `[146, 147]`, and
auto, across 10 transpiler seeds each. Transpilation consumes no QPU time.
| Optimization level | Layout `[0, 1]` | Layout `[146, 147]` | Auto layout |
| --- | --- | --- | --- |
| `1` | depth `8`, size `12` | depth `8`, size `12` | depth `8`, size `12` |
| `3` | depth `7`, size `11` | depth `7`, size `11` | depth `7`, size `11` |
Depth and size were identical across all 10 seeds in every cell. For this Bell
circuit, backend snapshot, and tested layouts, ISA depth and size varied only
with optimization level. This settles the observed depth attribution only. The
hardware correlation comparison remains confounded by layout and is not
statistically significant (two-sided Fisher exact `p = 0.4466`). Record:
[transpiler depth attribution](docs/quantum-results/transpiler_depth_attribution.json).
Machine-readable records are available for the
[optimization-1 run](docs/quantum-results/ibm_fez_dajg0i1hvn6c73cuckbg.json),
[optimization-3 run](docs/quantum-results/ibm_fez_dajg4l1hvn6c73cucon0.json),
and [earlier provider-only run](docs/quantum-results/ibm_fez_daj5doomhr3c73e8i5a0.json).
They contain no API key or instance CRN. The three records are not
schema-identical and should not be parsed interchangeably: the provider-only run
predates the guarded path and carries no `audit`, `pramagent_execution`, or
`same_bit_correlation_wilson_95` fields, and only the optimization-3 record
carries `isa_circuit` in place of `circuit`. The optimized sample had higher
observed correlation, but the confidence intervals overlap and the runs used
different calibrated qubit pairs. The result does not establish a causal
fidelity improvement, a complete entanglement witness, quantum advantage, or
hybrid-VLM improvement.
## Docs
- [Getting started](https://github.com/sriram7737/pramagent/blob/main/docs/GETTING_STARTED.md)
- [LangGraph integration](https://github.com/sriram7737/pramagent/blob/main/docs/integrations/langgraph.md)
- [Implementation status](https://github.com/sriram7737/pramagent/blob/main/docs/IMPLEMENTATION_STATUS.md)
- [Quantum integration](https://github.com/sriram7737/pramagent/blob/main/docs/QUANTUM.md)
- [Conformance map](https://github.com/sriram7737/pramagent/blob/main/docs/CONFORMANCE.md)
- [Design decisions](https://github.com/sriram7737/pramagent/blob/main/docs/DESIGN_DECISIONS.md)
- [Overreach corpus](https://github.com/sriram7737/pramagent/tree/main/corpus/overreach)
- [Live test results](https://github.com/sriram7737/pramagent/blob/main/docs/LIVE_TEST_RESULTS.md)
- [Hardening guide](https://github.com/sriram7737/pramagent/blob/main/docs/HARDENING_GUIDE.md)
- [Incident-response runbook](https://github.com/sriram7737/pramagent/blob/main/docs/INCIDENT_RESPONSE_RUNBOOK.md) - key/credential compromise, audit-chain tamper response, and the security CLI: `pramagent auth-revoke` (revoke a leaked API key), `pramagent audit-verify-watch` (automated tamper detection), `pramagent audit-export` (export a tenant's trace rows)
- [Google Dev Library submission draft](https://github.com/sriram7737/pramagent/blob/main/docs/GOOGLE_DEV_LIBRARY_SUBMISSION.md)
- [Cookbook submission plan](https://github.com/sriram7737/pramagent/blob/main/docs/COOKBOOK_SUBMISSIONS.md)
- [Security test results](https://github.com/sriram7737/pramagent/blob/main/docs/audits/pramagent_security_test_results.md)
- [More documentation](https://github.com/sriram7737/pramagent/tree/main/docs)
## Author
- [Sriram Rampelli](https://sriram7737.github.io)
## License
Apache-2.0.