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
- Connect LLM providers (model routing) and integrations in the dashboard.
- Define policies in the dashboard. Each check returns
allow,denyorflag. - Send traffic through the gateway with this SDK. Your code holds one Paved key and no provider keys.
- 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 thestream:passthroughscope.
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:inputoroutpute.reasons: a list of stringse.request_id: the audit log IDe.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 isdeny.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 onalloworflagand raises ondeny.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
alloworflagcounts asdeny.
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()raisesProxyErrorwhen the call fails before it reaches the upstream, for example a resource that is set up wrong. A policy denial still raisesPolicyDeniedError.
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. Useproject=to pick the project.PavedCallbackHandleris gone. UseChatPaved.agent.llm(),agent.http_request()andagent.send_email()are gone. They returned mock values.- Telemetry and
agent.complete()are gone. The gateway audit log is the record. - LiteLLM
image_generationand the*_with_streamingmethods are gone. Passstream=True. - The CLI keeps
login,logout,listand addscheck. The deploy and runtime commands are gone.
Links
- Dashboard: app.hipaved.com
- Docs: docs.hipaved.com
- Website: hipaved.com
- PyPI: pypi.org/project/pvd
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.