pic-standard 0.6.1

PIC Standard: Provenance & Intent Contracts for agentic side-effect governance

PIC Standard: Provenance & Intent Contracts

Make your AI agents safe, auditable & production-ready. No rogue actions, no blind trust.

PIC is a lightweight, local-first protocol that forces AI agents to prove every important action before it happens. Agents must declare intent, risk, provenance, and evidence; PIC verifies everything and fails closed if anything is wrong.

No more hallucinations turning into wire transfers. No more prompt injections triggering data exports.

Example: An LLM agent decides to send a $500 payment based on a user message. PIC requires the agent to prove: where did this instruction come from? Is the source trusted? Is there evidence the invoice is real? If any answer is missing or wrong, the action is blocked before it reaches the payment API.

---

Table of Contents

• Why PIC?
• Quickstart
• The PIC Contract
• How It Works
• Evidence Verification
• Keyring (Trusted Signers)
• Integrations
• RFC & Prior Art
• Roadmap
• Contributing

---

Why PIC?

Guardrails constrain what the model says. PIC constrains what the agent is allowed to do based on verifiable provenance + evidence.

• Stops prompt injections & blind tool calls at the action boundary
• Works 100% locally: zero cloud, zero data leaves your machine
• Plugs into your stack in minutes: LangGraph, MCP, OpenClaw, Cordum
• Open-source (Apache 2.0):audit it, fork it, own it

---

Quickstart

pip install pic-standard

# Verify an example proposal
pic-cli verify examples/financial_irreversible.json
# Schema valid
# Verifier passed

Optional extras:

pip install "pic-standard[langgraph]"  # LangGraph PICToolNode
pip install "pic-standard[mcp]"        # MCP tool guarding
pip install "pic-standard[crypto]"     # Ed25519 signature evidence

From source (contributors):

git clone https://github.com/madeinplutofabio/pic-standard.git
cd pic-standard && pip install -e ".[langgraph,mcp,crypto]"
pytest -q

---

The PIC Contract

Agents emit an Action Proposal (PIC/1.0) before every tool call:

Field	Purpose
intent	What the agent is trying to do
impact	Risk class: money, privacy, irreversible, compute, ...
provenance	Which inputs influenced the decision (with trust levels)
claims + evidence	What the agent asserts and the evidence backing it
action	The actual tool call (tool binding)

Rule: For high-impact proposals, at least one claim must reference evidence from trusted provenance. Fail-closed.

---

How It Works

graph TD
    A[Untrusted Input] --> B{AI Agent / Planner}
    C[Trusted Data/DB] --> B
    B --> D[Action Proposal JSON]
    D --> E[PIC Verifier]
    E --> F{Valid Contract?}
    F -- Yes --> G[Tool Executor]
    F -- No --> H[Blocked / Alert Log]

---

Evidence Verification

PIC supports deterministic evidence verification that upgrades provenance trust in-memory.

Type	Description
hash	SHA-256 verification of file artifacts (file://...)
sig	Ed25519 signature verification via trusted keyring

# Verify hash evidence
pic-cli verify examples/financial_hash_ok.json --verify-evidence

# Verify signature evidence
pic-cli verify examples/financial_sig_ok.json --verify-evidence

Full guide: docs/evidence.md

---

Keyring (Trusted Signers)

Signature evidence requires a keyring of trusted public keys with expiry and revocation support.

pic-cli keys                        # Inspect current keyring
pic-cli keys --write-example        # Generate starter keyring

Full guide: docs/keyring.md

---

Integrations

LangGraph

Guard any tool node with PICToolNode:

pip install "pic-standard[langgraph]"
python examples/langgraph_pic_toolnode_demo.py

• Validates schema + verifier + tool binding per tool call
• Returns ToolMessage outputs

---

MCP (Model Context Protocol)

Enterprise tool guarding with production defaults:

pip install "pic-standard[mcp]"
python -u examples/mcp_pic_client_demo.py

• Fail-closed, request tracing, DoS limits, evidence sandboxing
• Debug gating (PIC_DEBUG=1)

---

OpenClaw

TypeScript plugin for OpenClaw AI agents (hook API):

# Start the PIC bridge
pic-cli serve --port 7580

# Install the plugin
cd integrations/openclaw && npm install && npm run build
openclaw plugins install .

• pic-gate — verifies proposals before tool execution
• pic-init — injects PIC awareness at session start
• pic-audit — structured audit logging

Full guide: docs/openclaw-integration.md

---

Cordum

Go Pack providing PIC verification as a Cordum workflow gate step:

• job.pic-standard.verify worker topic with fail-closed design
• Three-way routing: proceed / fail / require_approval
• Pack manifest with schemas, overlays, and simulation tests

Full guide: docs/cordum-integration.md

---

HTTP Bridge (any language)

For non-Python integrations, PIC exposes an HTTP bridge:

pic-cli serve --port 3100
# POST /verify with {tool_name, tool_args}
# GET /health

---

RFC & Prior Art

RFC-0001: PIC/1.0 — Provenance & Intent Contracts for AI Agent Action Safety

Formal specification covering scope, threat model, security properties, conformance levels, and prior art differentiation. Published as a defensive publication with a SHA-256 fingerprint manifest: docs/RFC-0001.SHA256.

Verify locally: sha256sum -c docs/RFC-0001.SHA256

---

Roadmap

• Phase 1: Standardize Impact Classes (money, privacy, irreversible, ...)
• Phase 2: Reference Python verifier + CLI
• Phase 3: Anchor integrations (LangGraph + MCP)
• Phase 4: Evidence verification (hash + Ed25519 signatures)
• Phase 5: OpenClaw + Cordum integrations
• Phase 6: TypeScript SDK + audit dashboard + case studies

---

Contributing

We welcome contributions! See CONTRIBUTING.md for how to propose changes or report issues.

We're actively seeking:

• Security researchers to stress-test causal logic
• Framework authors to build native integrations
• Enterprise architects to define domain Impact Classes

If you find PIC useful, please consider giving us a star on GitHub: it helps attract more security experts and framework authors into the community.

Issues & ideas: GitHub Issues

Maintained by @fmsalvadori   MadeInPluto