Metadata-Version: 2.4
Name: pramagent
Version: 0.5.20
Summary: Alpha agent trust middleware: audit trails, safety guardrails, HITL, and tool validation
Author: Sriram Rampelli
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/sriram7737/pramagent
Project-URL: Repository, https://github.com/sriram7737/pramagent
Project-URL: Issues, https://github.com/sriram7737/pramagent/issues
Project-URL: Documentation, https://github.com/sriram7737/pramagent#readme
Project-URL: Author, https://sriram7737.github.io
Keywords: ai,agents,llm,safety,audit,compliance,trust,guardrails
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema>=4.23
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.39; extra == "anthropic"
Provides-Extra: ollama
Requires-Dist: aiohttp>=3.9; extra == "ollama"
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: uvicorn>=0.29; extra == "api"
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.110; extra == "dashboard"
Requires-Dist: uvicorn>=0.29; extra == "dashboard"
Requires-Dist: jinja2>=3.1; extra == "dashboard"
Requires-Dist: python-multipart>=0.0.9; extra == "dashboard"
Requires-Dist: httpx>=0.27; extra == "dashboard"
Requires-Dist: bcrypt>=4.1; extra == "dashboard"
Provides-Extra: encrypted
Requires-Dist: cryptography>=42; extra == "encrypted"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.25; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.25; extra == "otel"
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == "redis"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9; extra == "postgres"
Provides-Extra: ethereum
Requires-Dist: web3>=7.0; extra == "ethereum"
Provides-Extra: s3
Requires-Dist: boto3>=1.34; extra == "s3"
Requires-Dist: cryptography>=42; extra == "s3"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: cryptography>=42; extra == "dev"
Requires-Dist: jinja2>=3.1; extra == "dev"
Requires-Dist: python-multipart>=0.0.9; extra == "dev"
Requires-Dist: bcrypt>=4.1; extra == "dev"
Provides-Extra: all
Requires-Dist: jsonschema>=4.23; extra == "all"
Requires-Dist: anthropic>=0.39; extra == "all"
Requires-Dist: aiohttp>=3.9; extra == "all"
Requires-Dist: fastapi>=0.110; extra == "all"
Requires-Dist: uvicorn>=0.29; extra == "all"
Requires-Dist: jinja2>=3.1; extra == "all"
Requires-Dist: python-multipart>=0.0.9; extra == "all"
Requires-Dist: httpx>=0.27; extra == "all"
Requires-Dist: bcrypt>=4.1; extra == "all"
Requires-Dist: cryptography>=42; extra == "all"
Requires-Dist: opentelemetry-api>=1.25; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.25; extra == "all"
Requires-Dist: redis>=5.0; extra == "all"
Requires-Dist: psycopg2-binary>=2.9; extra == "all"
Requires-Dist: web3>=7.0; extra == "all"
Requires-Dist: boto3>=1.34; extra == "all"
Dynamic: license-file

# Pramagent

[![PyPI version](https://img.shields.io/pypi/v/pramagent.svg)](https://pypi.org/project/pramagent/)
[![Python versions](https://img.shields.io/pypi/pyversions/pramagent.svg)](https://pypi.org/project/pramagent/)
[![License](https://img.shields.io/pypi/l/pramagent.svg)](https://github.com/sriram7737/pramagent/blob/main/LICENSE)
[![CI](https://github.com/sriram7737/pramagent/actions/workflows/tests.yml/badge.svg)](https://github.com/sriram7737/pramagent/actions/workflows/tests.yml)

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 trust stack](https://raw.githubusercontent.com/sriram7737/pramagent/main/docs/stack.png)

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](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.

## Bare Install Quickstart

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

```bash
pip install pramagent
```

```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)

asyncio.run(main())
```

![Pramagent bare-install terminal quickstart](https://raw.githubusercontent.com/sriram7737/pramagent/main/docs/quickstart-terminal.png)

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"))
```

## 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`

Run the release sanity checks:

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

Current local result: `449 passed, 1 skipped`.

## 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())
```

## 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`

## 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`.

## 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
```

## 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 |
| 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 with bypass/false-positive rates |
| 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 |

## Honest Limits

- Prompt-injection defense is not complete. The bundled static corpus and
  seeded dynamic mutation smoke tests now pass, 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.
- 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

```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
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](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)
- [Hardening guide](https://github.com/sriram7737/pramagent/blob/main/docs/HARDENING_GUIDE.md)
- [More documentation](https://github.com/sriram7737/pramagent/tree/main/docs)

## Author

- [Sriram Rampelli](https://sriram7737.github.io)

## License

Apache-2.0.
