Skip to main content

Paved

The Python SDK for the Paved platform — the governed gateway your agents call through.

Paved is an operating layer for an organization's real work: agents run the routine middleware of a function and escalate the genuine judgment calls to humans, whose resolutions are captured as reusable knowledge. This SDK is the on-ramp to that platform — it routes your LLM calls, tool executions, and API requests through Paved's policy engine, so you get security, credential injection, and audit trails without changing your agent code. Governance is the entry point; the platform's escalation → resolution loop and autonomy ladder build on top of it (see the platform docs).

Paved sits between your AI agents and the APIs they call. Every request flows through the policy engine, checked allow / deny / flag before it reaches a provider.

Dashboard: app.hipaved.com | Docs: docs.hipaved.com | Website: hipaved.com


How It Works

Your agent --> Paved gateway --> policy check (Guard API -> OPA) --> LLM provider or integration API
                    |
                    +--> provider keys and credentials injected, output checked, audit log
  1. Connect LLM providers (model routing) and integrations in the dashboard.
  2. Define policies in the dashboard. Each check returns allow, deny or flag.
  3. Send traffic through the gateway with this SDK. Your code holds one Paved key and no provider keys.
  4. Read audit logs, cost and policy results in the dashboard.

A denied call is blocked and raises PolicyDeniedError. A flagged call proceeds and is logged for review.

Gateway-first. Every surface in this SDK sends traffic to the gateway. No surface calls a provider directly, and no surface accepts a provider key. The policy check happens on the server, where the client cannot skip it.

Surface Use it for Endpoint
pvd.openai.OpenAI / AsyncOpenAI OpenAI-shaped model calls /v1/gateway/chat/completions, /embeddings, ...
pvd.anthropic.Anthropic / AsyncAnthropic Anthropic-shaped model calls /v1/gateway/v1/messages
pvd.litellm.LiteLLM LiteLLM code /v1/gateway/chat/completions, /embeddings
pvd.langchain.ChatPaved LangChain and LangGraph /v1/gateway/chat/completions
Agent.proxy() Integration API calls with stored credentials /v1/gateway/proxy
Agent.agent() A tool loop that the gateway runs /v1/gateway/agent
Agent.check(), @tool, @guard_tool Your own tools and actions /v1/policies/check

Install

pip install pvd                # core: Agent, tool, guard_tool, CLI
pip install "pvd[openai]"      # also: anthropic, litellm, langchain, all

Python 3.10 or newer. The core package needs click and requests.

API keys start with pvd_live_. Create one in the dashboard.


Configuration

Variable Meaning Default
PAVED_API_KEY Your pvd_live_... key none (required)
PAVED_URL Platform API base https://app.hipaved.com/v1
PAVED_PROJECT Project slug or ID, sent as X-Paved-Project none

Every surface reads the same three variables. Arguments override them: paved_api_key=, paved_url=, project= (on Agent: api_key=, base_url=, project=).

PAVED_URL may end in /v1 or not; the SDK adds it. PAVED_API_URL still works as an older name. Use the app host (app.hipaved.com), not api.hipaved.com. The api. host serves the Guard API only.

For local development, set PAVED_URL=http://localhost:8090.

Stream policy

The model clients take stream_policy= (sent as X-Paved-Stream-Policy):

  • progressive (default on the server): chunks flow; the gateway checks the output as it grows.
  • buffered: the gateway checks the full output before it sends the first chunk.
  • passthrough: no output check on streams. The key needs the stream:passthrough scope.

Model calls

OpenAI

from pvd.openai import OpenAI, PolicyDeniedError   # also AsyncOpenAI

client = OpenAI(project="payments")   # PAVED_API_KEY from the environment
try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Summarize our Q3 results"}],
    )
except PolicyDeniedError as e:
    print(e.phase, e.reasons, e.request_id)

This is the real openai.OpenAI with its base URL set to the gateway. Every method works as before. The gateway routes by model name, so model="claude-sonnet-4-5" also works if model routing has it.

Passing api_key= raises TypeError. Provider keys live in model routing on the platform.

Anthropic

from pvd.anthropic import Anthropic   # also AsyncAnthropic

client = Anthropic(stream_policy="buffered")
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Analyze this contract"}],
)

The Paved key is sent as x-api-key. Passing api_key= or auth_token= raises TypeError.

LiteLLM

from pvd.litellm import LiteLLM

llm = LiteLLM(project="payments")
llm.completion(model="gpt-4o", messages=[{"role": "user", "content": "Hello"}])
llm.embedding(model="text-embedding-3-small", input="Hello world")

Methods: completion, acompletion, embedding, aembedding. Each call goes to the gateway as openai/<model>. Passing api_key, api_base or base_url raises TypeError.

LangChain and LangGraph

from pvd.langchain import ChatPaved

llm = ChatPaved(model="gpt-4o-mini", project="payments")
llm.invoke("Hello")

ChatPaved returns a langchain_openai.ChatOpenAI that points at the gateway. Tools, streaming and LangGraph work as they do with ChatOpenAI.

Denials

A policy denial from the gateway raises PolicyDeniedError. The OpenAI and Anthropic clients raise a class that is both pvd.PolicyDeniedError and the provider's PermissionDeniedError, so existing except blocks still work. The error carries:

  • e.phase: input or output
  • e.reasons: a list of strings
  • e.request_id: the audit log ID
  • e.decision: the full response body

A 403 that is not a policy denial (for example, a missing project) stays the provider's normal error.

Known gap: a denial in the middle of a stream arrives as an error chunk. It is not yet mapped to PolicyDeniedError.

curl

curl -X POST https://app.hipaved.com/v1/gateway/chat/completions \
  -H "Authorization: Bearer pvd_live_..." \
  -H "X-Paved-Project: payments" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

Integration calls: Agent.proxy()

from pvd import Agent

agent = Agent(agent_id="my-agent", project="payments")

repos = agent.proxy("github", "GET", "/user/repos")
agent.proxy("github", "POST", "/repos/acme/app/issues", body={"title": "Bug: login broken"})
accounts = agent.proxy(
    "salesforce", "GET", "/services/data/v59.0/query",
    query={"q": "SELECT Id, Name FROM Account LIMIT 10"},
)
agent.proxy("stripe", "GET", "/v1/charges", on_behalf_of={"role": "support", "department": "cs"})

Signature: proxy(resource, method, path, body=None, query=None, headers=None, on_behalf_of=None, timeout=30.0). resource is an integration slug or a resource UUID. Paved checks resource-access policy, adds the stored credentials and forwards the request. Credentials stay on the platform.

The call returns the platform response:

{
    "status_code": 200,
    "body": [...],        # upstream response
    "headers": {...},
    "decision": "allow",
    "reasons": [],
    "request_id": "...",
    "latency_ms": 142,
}
  • PolicyDeniedError: the decision is deny.
  • ProxyError: a transport error, a non-JSON reply, or a reply with no decision (for example, HTTP 401).

Gateway agent runs: Agent.agent()

The gateway turns each integration's actions into LLM tools and runs the tool loop. It checks policy on every tool call and returns the final answer with a trace.

result = agent.agent(
    messages=[{"role": "user", "content": "Get me my top 5 Salesforce accounts"}],
    integrations=["salesforce"],
    model="gpt-4o",
)

print(result.content)
print(result.finish_reason)    # "stop", "max_rounds" or "policy_denied"
print(result.tool_executions)  # one trace per tool call
print(result.denied_tools)     # the traces that policy denied

Parameters: messages, integrations, model="gpt-4o", max_rounds=10 (1 to 50), temperature, max_tokens, on_behalf_of, system, timeout=120.0.

A denied input raises PolicyDeniedError. A denied tool call does not raise; the run continues and the trace shows the denial. Other failures raise AgentError.

on_behalf_of passes end-user identity to OPA, so policies can apply per-user rules. The standard fields are user_id, role, department and clearance. Other fields reach OPA unchanged.

AgentResult

result.content          result.finish_reason    result.rounds_used
result.tool_executions  result.usage            result.latency_ms
result.request_id       result.model
result.prompt_tokens    result.completion_tokens    result.total_tokens
result.successful_tools   # no deny, no error
result.denied_tools       # denied by policy
result.to_dict()          # raw response

Your own tools: check, @tool, @guard_tool

Use these for actions that do not go through the gateway, such as a function in your own code.

from pvd import Agent, PolicyDeniedError, guard_tool, tool

agent = Agent(agent_id="my-agent", policies=["default"])

try:
    agent.check("email", {"to": ["ceo@company.com"], "subject": "Q3 Report"})
    send_email(...)
except PolicyDeniedError as e:
    print(f"Blocked: {e.reasons}")


@tool(policies=["pii_strict"])          # the first argument is the Agent
def lookup_customer(agent, customer_id): ...

@guard_tool(name="refund", agent=agent)  # or bind the Agent once
def refund(order_id, amount): ...
  • check(action, payload, policies=None) returns the decision on allow or flag and raises on deny.
  • policies= on a check or a decorator replaces the agent's default policies for that call.
  • The tool payload is {"tool_name", "args", "kwargs"}. The Agent itself is never in it. Values that are not JSON become strings.
  • A denied tool does not run.
  • If the platform cannot be reached, the check fails closed: the decision is deny.
  • Any decision other than allow or flag counts as deny.

Governance summary

Every check, proxy call and agent tool execution is recorded once on the Agent.

summary = agent.get_governance_summary()
summary["total_checks"], summary["allowed_actions"], summary["denied_actions"], summary["flagged_actions"]
summary["violations"]         # the denied records
summary["overall_decision"]   # "deny" if any deny, else "flag" if any flag, else "allow"

agent.get_policy_decisions() returns the raw list. The record lives in memory only. The SDK sends nothing in the background and nothing at exit; the audit trail lives on the platform.


CLI

pvd check                  # does PAVED_API_KEY reach the gateway?
pvd login                  # email + password, for `pvd list`
pvd list --limit 20        # agents in your projects
pvd logout
pvd --version

--platform <url> overrides the platform URL for one command. The CLI reads PAVED_URL (then PAVED_PLATFORM_URL) and stores its login in ~/.paved/config.json.


Changes in 0.3.1

  • agent.proxy() raises ProxyError when the call fails before it reaches the upstream, for example a resource that is set up wrong. A policy denial still raises PolicyDeniedError.

Upgrading from 0.2

0.3.0 is a breaking release. Every surface now sends traffic through the gateway.

  • The OpenAI, Anthropic and LiteLLM wrappers no longer accept a provider key. The SDK-check mode is gone.
  • agent_id= is gone from the model clients. Use project= to pick the project.
  • PavedCallbackHandler is gone. Use ChatPaved.
  • agent.llm(), agent.http_request() and agent.send_email() are gone. They returned mock values.
  • Telemetry and agent.complete() are gone. The gateway audit log is the record.
  • LiteLLM image_generation and the *_with_streaming methods are gone. Pass stream=True.
  • The CLI keeps login, logout, list and adds check. The deploy and runtime commands are gone.

Metadata

Release files for pvd 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pvd 0.3.1
File Size Uploaded Provenance Actions
pvd-0.3.1.tar.gz 30.5 kB Without provenance Details for pvd-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pvd 0.3.1
File Interpreter ABI Platform Actions
pvd-0.3.1-py3-none-any.whl Python 3 none any Details for pvd-0.3.1-py3-none-any.whl

Total release size: 57.7 kB

Release files / pvd-0.3.1.tar.gz

Download URL pvd-0.3.1.tar.gz
Size 30.5 kB
Tags Source
SHA-256 checksum
How to use checksums
3e9918e107320b20df432f65ebdde4cead024775a1108345f2ed9d8c9a6d48f1
BLAKE2b-256 checksum
How to use checksums
915f7d0e5e335beea853e5c792ce2085fc596f0acd99630f4369c3e0b042c0b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / pvd-0.3.1-py3-none-any.whl

Download URL pvd-0.3.1-py3-none-any.whl
Size 27.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
70e0b76d77e2af9f887d378e5d3a47d7229ebb47de6110d624bd6ff6bb83aaea
BLAKE2b-256 checksum
How to use checksums
822222972f67cb92608f5b09b056858107344e548bcaecbd9813fa825920e006
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for pvd 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page