Metadata-Version: 2.4
Name: pavri
Version: 0.1.0
Summary: Pavri AI Agent Security SDK
Project-URL: Homepage, https://pavri.ai
Project-URL: Documentation, https://docs.pavri.ai
Project-URL: Repository, https://github.com/pavri/pavri
Project-URL: Bug Tracker, https://github.com/pavri/pavri/issues
License: Apache-2.0
Keywords: agent,ai,governance,llm,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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.12
Requires-Dist: cryptography<44,>=42
Requires-Dist: grpcio<2,>=1.60
Requires-Dist: protobuf<7,>=6.31
Requires-Dist: pyahocorasick<3,>=2.0
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pyjwt[cryptography]<3,>=2.8
Requires-Dist: xxhash<4,>=3.4
Provides-Extra: all
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.27; extra == 'all'
Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == 'all'
Requires-Dist: prometheus-client<1,>=0.20; extra == 'all'
Requires-Dist: spacy<4,>=3.7; extra == 'all'
Provides-Extra: dev
Requires-Dist: bandit>=1.7; extra == 'dev'
Requires-Dist: hypothesis<7,>=6.100; extra == 'dev'
Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == 'dev'
Requires-Dist: pytest-benchmark<5,>=4; extra == 'dev'
Requires-Dist: pytest-cov<7,>=6; extra == 'dev'
Requires-Dist: pytest<9,>=8; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Provides-Extra: metrics
Requires-Dist: prometheus-client<1,>=0.20; extra == 'metrics'
Provides-Extra: ml
Requires-Dist: onnxruntime>=1.17; extra == 'ml'
Requires-Dist: optimum>=1.17; extra == 'ml'
Requires-Dist: torch>=2.2; extra == 'ml'
Requires-Dist: transformers>=4.40; extra == 'ml'
Provides-Extra: ner
Requires-Dist: spacy<4,>=3.7; extra == 'ner'
Provides-Extra: otel
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.27; extra == 'otel'
Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == 'otel'
Provides-Extra: otel-http
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.27; extra == 'otel-http'
Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == 'otel-http'
Provides-Extra: perf
Requires-Dist: pytest-benchmark<5,>=4; extra == 'perf'
Description-Content-Type: text/markdown

# Pavri Python SDK

The Pavri Python SDK instruments AI agents with one line of code, giving your security team
real-time visibility, runtime governance, and threat detection across your agent fleet.

## Installation

```bash
pip install pavri
```

Requires Python 3.12+.

## Quickstart

### 1. Instrument your agent

```python
from pavri import PavriConfig, secure

# Any Python agent — LangGraph, CrewAI, OpenAI Agents, Claude SDK, Google ADK, AutoGen, or generic
from my_app import MyAgent

agent = secure(
    MyAgent(),
    PavriConfig(
        agent_name="customer-support-agent",
        plugin="generic",        # or: langgraph, crewai, openai_agents, claude, google_adk, autogen
        api_key="fbx_sk_...",   # from your Pavri dashboard → Admin → API Keys
        endpoint="https://gateway.pavri.ai:443",
    ),
)
```

That is the entire instrumentation step. The agent now reports to Pavri on every
session, tool call, and policy decision.

### 2. Verify it works

```python
from pavri.core import get_runtime

runtime = get_runtime(agent)
print(runtime.status())
# RuntimeStatus(agent_id='...', registered=True, policy_loaded=True, ...)
```

### 3. Open the dashboard

Sign in to your Pavri dashboard. Your agent will appear in **Agents** within seconds
of running a session.

---

## Framework examples

### LangGraph

```python
from pavri import PavriConfig, secure
from langgraph.prebuilt import create_react_agent

# Build your graph first, then wrap with secure()
graph = create_react_agent(model, tools)
secured = secure(graph, PavriConfig(agent_name="langgraph-agent", plugin="langgraph"))
```

### CrewAI

```python
from pavri import PavriConfig, secure
from crewai import Crew

crew = Crew(agents=[...], tasks=[...])
secured = secure(crew, PavriConfig(agent_name="my-crew", plugin="crewai"))
```

### OpenAI Agents SDK

```python
from pavri import PavriConfig, secure
from agents import Agent

agent = Agent(name="assistant", instructions="...", tools=[...])
secured = secure(agent, PavriConfig(agent_name="openai-agent", plugin="openai_agents"))
```

### Anthropic Claude SDK

```python
from pavri import PavriConfig, secure

class ClaudeAgent:
    name = "claude-agent"

secured = secure(ClaudeAgent(), PavriConfig(agent_name="claude-agent", plugin="claude"))
```

### Google ADK

```python
from pavri import PavriConfig, secure
from google.adk.agents import LlmAgent

agent = LlmAgent(name="adk-agent", model="gemini-1.5-pro", tools=[...])
secured = secure(agent, PavriConfig(agent_name="adk-agent", plugin="google_adk"))
```

### AutoGen

```python
from pavri import PavriConfig, secure
from autogen import AssistantAgent

agent = AssistantAgent(name="assistant", llm_config={...})
secured = secure(agent, PavriConfig(agent_name="autogen-agent", plugin="autogen"))
```

---

## Runtime governance

Policies are defined in your dashboard or via YAML (policy-as-code) and enforced at runtime.
No SDK changes required when policies change — they sync automatically.

Built-in policy types:

| Policy type | Description |
|-------------|-------------|
| `tool_acl` | Allow or deny specific tools by name or pattern |
| `domain_acl` | Allow or deny network domains the agent may access |
| `cost_budget` | Cap total AI inference cost per session or per day |
| `rate_limit` | Limit calls per minute at agent or session scope |
| `data_classification` | Block PII, credentials, or sensitive data in tool outputs |

### Policy-as-code DSL

```yaml
# my-policy.yaml
name: production-safety
rules:
  - type: tool_acl
    mode: allowlist
    patterns: ["search_*", "summarize"]
  - type: cost_budget
    max_usd_per_session: 0.50
  - type: data_classification
    block: [pii, credentials]
```

```bash
# Validate in CI
pavri-policy validate my-policy.yaml

# Compile to binary format for deployment
pavri-policy compile my-policy.yaml --output policy.bin
```

---

## Threat detection

Detection runs in a T0 → T1 → T2 → T3 cascade, escalating only when needed:

| Tier | Method | Latency | Requires |
|------|--------|---------|---------|
| T0 | Pattern matching + Aho-Corasick | < 1ms | Nothing |
| T1 | ONNX SLM classifier (CPU) | ~10ms | CPU only |
| T2 | Backend ML model | ~50ms | Backend connection |
| T3 | LLM judge | ~500ms | LLM API key |

Free tier uses T0 + T1 only — no GPU, no external API calls required.

### Advanced security features

Beyond the detection cascade, Pavri includes 14 advanced agent protection features:

| Feature | Description | Config |
|---------|-------------|--------|
| Prompt drift detection | Semantic diff when system prompts change | `ProtectionProfile.prompt_drift_detection` |
| Canary data injection | Trackable fake credentials to prove exfiltration | `ProtectionProfile.canary_data_injection` |
| Capability escalation | Detect undeclared tools and mid-session tool drift | `ProtectionProfile.capability_escalation_detection` |
| Memory poisoning detection | Scan write-path tool calls for injection | `ProtectionProfile.memory_write_judge` |
| Generated code scanning | SQL/XSS/shell injection in agent output | `ProtectionProfile.scan_generated_code` |
| Cross-agent influence | Detect inter-agent manipulation in multi-agent systems | `ProtectionProfile.cross_agent_detection` |
| Semantic policies | Natural-language constraints enforced via LLM judge | `semantic_policy` rule type in DSL |
| Faithfulness checking | Verify agent responses match tool outputs | `ProtectionProfile.faithfulness_checking` |
| Consistency checking | Detect inconsistent answers to similar queries | `ProtectionProfile.consistency_checking` |
| Tool call graph analysis | Behavioral fingerprinting via transition matrices | `PavriConfig.sequence_baseline_enabled` |
| Shadow execution | Dual-agent verification for high-stakes operations | `PavriConfig.shadow_execution` |

All features are opt-in via `ProtectionProfile` or `PavriConfig` fields. See the
[Advanced Security Feature Roadmap](../../docs/16-ADVANCED-SECURITY-FEATURE-ROADMAP.md)
for full details.

---

## CLI tools

Two CLI tools are installed with the SDK:

### `pavri-preflight`

Run before deploying to verify your environment is correctly configured:

```bash
pavri-preflight --api-key fbx_sk_... --endpoint https://gateway.pavri.ai:443
# Checking connectivity... OK
# Checking API key... OK (tenant: acme-corp)
# Checking policy sync... OK (3 policies loaded)
# Preflight passed.
```

### `pavri-policy`

Validate and compile policy YAML files:

```bash
pavri-policy validate policy.yaml
pavri-policy compile policy.yaml --output policy.bin
pavri-policy list  # List all policies for your tenant
```

---

## Free tier mode

Set `PAVRI_TIER=free` to run in free tier mode. This caps detection to T0 and T1 only —
no GPU inference, no external LLM API calls required.

```python
import os
os.environ["PAVRI_TIER"] = "free"

from pavri import PavriConfig, secure
# T2 and T3 detection will not run
```

---

## Optional dependencies

```bash
# OpenTelemetry export (gRPC)
pip install "pavri[otel]"

# OpenTelemetry export (HTTP)
pip install "pavri[otel-http]"

# Prometheus metrics
pip install "pavri[metrics]"

# All optional dependencies
pip install "pavri[all]"
```

---

## Development install

```bash
git clone https://github.com/pavri/pavri.git
cd pavri
pip install -e "sdk/python[dev,metrics,otel]"
pytest sdk/python/tests/ -q
```

See [CONTRIBUTING.md](../../CONTRIBUTING.md) for full dev setup and test commands.

---

## Documentation

- [Full quickstart](https://docs.pavri.ai/quickstart)
- [Framework integration guides](https://docs.pavri.ai/frameworks)
- [Policy configuration](https://docs.pavri.ai/security/policies)
- [Threat detection tuning](https://docs.pavri.ai/security/threat-detection)
- [API reference](https://docs.pavri.ai/reference/api)

## License

Apache 2.0 — see [LICENSE](../../LICENSE).
